@humanspeak/svelte-markdown 1.0.5 → 1.1.0

package/README.md

@@ -27,6 +27,7 @@ A powerful, customizable markdown renderer for Svelte with TypeScript support. B
 - 🧪 Comprehensive test coverage (vitest and playwright)
 - 🧩 First-class marked extensions support via `extensions` prop (e.g., KaTeX math, alerts)
 - ⚡ Intelligent token caching (50-200x faster re-renders)
+- 📡 LLM streaming mode with incremental rendering (~1.6ms avg per update)
 - 🖼️ Smart image lazy loading with fade-in animation
 
 ## Installation
@@ -678,6 +679,46 @@ Images automatically lazy load using native `loading="lazy"` and IntersectionObs
 <SvelteMarkdown source={markdown} {renderers} />
 ```
 
+### LLM Streaming
+
+For real-time rendering of AI responses from ChatGPT, Claude, Gemini, and other LLMs, enable the `streaming` prop. This uses a smart diff algorithm that re-parses the full source for correctness but only updates changed DOM nodes, keeping render times constant regardless of document size.
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+
+    let source = $state('')
+
+    async function streamResponse() {
+        const response = await fetch('/api/chat', { method: 'POST', body: '...' })
+        const reader = response.body.getReader()
+        const decoder = new TextDecoder()
+
+        while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            source += decoder.decode(value, { stream: true })
+        }
+    }
+</script>
+
+<SvelteMarkdown {source} streaming={true} />
+```
+
+**Performance** (measured at 100 characters/sec, character mode):
+
+| Metric         | Standard Mode | Streaming Mode |
+| -------------- | :-----------: | :------------: |
+| Average render |    ~3.6ms     |     ~1.6ms     |
+| Peak render    |     ~21ms     |     ~10ms      |
+| Dropped frames |       0       |       0        |
+
+When `streaming` is `false` (default), existing behavior is unchanged. The `streaming` prop skips cache lookups (always a miss during streaming) and uses in-place token array mutation so Svelte only re-renders components for tokens that actually changed.
+
+**Note:** `streaming` is automatically disabled when async extensions (e.g., `markedMermaid`) are used. A console warning is logged in this case.
+
+See the [full streaming documentation](https://markdown.svelte.page/docs/advanced/llm-streaming) and [interactive demo](https://markdown.svelte.page/examples/llm-streaming).
+
 ## Available Renderers
 
 - `text` - Text within other elements
@@ -764,6 +805,7 @@ The component emits a `parsed` event when tokens are calculated:
 | Prop       | Type                    | Description                                      |
 | ---------- | ----------------------- | ------------------------------------------------ |
 | source     | `string \| Token[]`     | Markdown content or pre-parsed tokens            |
+| streaming  | `boolean`               | Enable incremental rendering for LLM streaming   |
 | renderers  | `Partial<Renderers>`    | Custom component overrides                       |
 | options    | `SvelteMarkdownOptions` | Marked parser configuration                      |
 | isInline   | `boolean`               | Toggle inline parsing mode                       |

package/dist/SvelteMarkdown.svelte

@@ -51,6 +51,7 @@
 
     import Parser from './Parser.svelte'
     import { type SvelteMarkdownProps } from './types.js'
+    import { IncrementalParser } from './utils/incremental-parser.js'
     import {
         defaultOptions,
         defaultRenderers,
@@ -67,6 +68,7 @@
 
     const {
         source = [],
+        streaming = false,
         renderers = {},
         options = {},
         isInline = false,
@@ -93,9 +95,59 @@
     // Detect if any extension requires async processing
     const hasAsyncExtension = $derived(extensions.some((ext) => ext.async === true))
 
-    // Synchronous token derivation (default fast path)
+    // Streaming mode: full re-parse + smart in-place diff
+    let incrementalParser: IncrementalParser | undefined
+    let lastOptionsKey = ''
+    let streamTokens = $state<Token[]>([])
+
+    $effect(() => {
+        if (!streaming || hasAsyncExtension) {
+            if (incrementalParser) {
+                incrementalParser = undefined
+                lastOptionsKey = ''
+            }
+            if (streaming && hasAsyncExtension) {
+                console.warn(
+                    '[svelte-markdown] streaming prop is ignored when async extensions are used. ' +
+                        'Remove async extensions or set streaming={false} to silence this warning.'
+                )
+            }
+            return
+        }
+
+        // Read combinedOptions unconditionally so Svelte tracks it as a dependency
+        const currentOptions = combinedOptions
+        const optionsKey = JSON.stringify(currentOptions)
+
+        if (Array.isArray(source)) {
+            streamTokens = source as Token[]
+            return
+        }
+
+        if (source === '') {
+            if (incrementalParser) incrementalParser.reset()
+            streamTokens.length = 0
+            return
+        }
+
+        // Recreate parser only when options actually change
+        if (!incrementalParser || lastOptionsKey !== optionsKey) {
+            incrementalParser = new IncrementalParser(currentOptions)
+            lastOptionsKey = optionsKey
+        }
+        const { tokens: newTokens, divergeAt } = incrementalParser.update(source as string)
+
+        // In-place update: only touch changed/appended indices
+        for (let i = divergeAt; i < newTokens.length; i++) {
+            streamTokens[i] = newTokens[i]
+        }
+        streamTokens.length = newTokens.length
+    })
+
+    // Synchronous token derivation (default fast path — non-streaming)
     const syncTokens = $derived.by(() => {
         if (hasAsyncExtension) return undefined
+        if (streaming) return undefined
 
         // Pre-parsed tokens - skip caching and parsing
         if (Array.isArray(source)) {
@@ -107,7 +159,7 @@
             return []
         }
 
-        // Parse with caching (handles cache lookup, parsing, and storage)
+        // Standard mode - full parse with caching
         return parseAndCacheTokens(source as string, combinedOptions, isInline)
     }) satisfies Token[] | TokensList | undefined
 
@@ -149,8 +201,8 @@
             })
     })
 
-    // Unified tokens: prefer sync path, fall back to async
-    const tokens = $derived(hasAsyncExtension ? asyncTokens : syncTokens)
+    // Unified tokens: streaming > sync > async
+    const tokens = $derived(streaming ? streamTokens : hasAsyncExtension ? asyncTokens : syncTokens)
 
     $effect(() => {
         if (!tokens) return

package/dist/index.d.ts

@@ -58,6 +58,7 @@ export { htmlRendererKeysInternal as htmlRendererKeys, rendererKeysInternal as r
  * - `tokenCache`  — shared singleton `TokenCache` instance
  */
 export { MemoryCache } from './utils/cache.js';
+export { IncrementalParser, type IncrementalUpdateResult } from './utils/incremental-parser.js';
 export { TokenCache, tokenCache } from './utils/token-cache.js';
 /** Re-exported `MarkedExtension` type for the `extensions` prop. */
 export type { MarkedExtension } from 'marked';

package/dist/index.js

@@ -57,4 +57,5 @@ export { htmlRendererKeysInternal as htmlRendererKeys, rendererKeysInternal as r
  * - `tokenCache`  — shared singleton `TokenCache` instance
  */
 export { MemoryCache } from './utils/cache.js';
+export { IncrementalParser } from './utils/incremental-parser.js';
 export { TokenCache, tokenCache } from './utils/token-cache.js';

package/dist/types.d.ts

@@ -190,6 +190,20 @@ export type SvelteMarkdownProps<T extends Renderers = Renderers> = {
      * @defaultValue `false`
      */
     isInline?: boolean;
+    /**
+     * Enables optimized rendering for LLM streaming scenarios.
+     *
+     * When `true`, the component performs a full re-parse on each source
+     * update but diffs the resulting tokens against the previous parse.
+     * Only changed or appended tokens trigger DOM updates, keeping render
+     * cost proportional to the change rather than the full document size.
+     *
+     * Use this when appending tokens to `source` in a streaming fashion
+     * (e.g., ChatGPT/Claude SSE responses).
+     *
+     * @defaultValue `false`
+     */
+    streaming?: boolean;
     /**
      * Callback invoked after the source has been parsed into tokens.
      *

package/dist/utils/incremental-parser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Incremental Markdown Parser for Streaming
+ *
+ * Optimizes streaming scenarios (LLM token-by-token updates) by performing
+ * a full re-parse but diffing the result against the previous token array.
+ * Only changed/appended tokens are returned as updates, allowing Svelte to
+ * skip re-rendering unchanged components.
+ *
+ * @module incremental-parser
+ */
+import type { SvelteMarkdownOptions } from '../types.js';
+import type { Token } from './markdown-parser.js';
+/**
+ * Result of an incremental parse update.
+ */
+export interface IncrementalUpdateResult {
+    /** The full new token array */
+    tokens: Token[];
+    /** Index of the first token that differs from the previous parse */
+    divergeAt: number;
+}
+/**
+ * Streaming-optimized parser that performs full re-parses but diffs results
+ * against the previous token array to minimize DOM updates.
+ *
+ * For append-only streaming (typical LLM use case), most tokens are identical
+ * between updates. By comparing `raw` strings, we identify which tokens changed
+ * so Svelte can skip re-rendering unchanged components.
+ *
+ * @example
+ * ```typescript
+ * const parser = new IncrementalParser({ gfm: true })
+ *
+ * // First update — all tokens are "new"
+ * const r1 = parser.update('# Hello')
+ * // r1.divergeAt === 0
+ *
+ * // Second update — heading unchanged, paragraph appended
+ * const r2 = parser.update('# Hello\n\nWorld')
+ * // r2.divergeAt === 1 (heading at index 0 unchanged)
+ * ```
+ */
+export declare class IncrementalParser {
+    /** Previous parse result for diffing */
+    private prevTokens;
+    /** Parser options passed to the Marked lexer */
+    private options;
+    /**
+     * Creates a new incremental parser instance.
+     *
+     * @param options - Svelte markdown parser options forwarded to Marked's Lexer
+     */
+    constructor(options: SvelteMarkdownOptions);
+    /**
+     * Parses the full source and diffs against the previous result.
+     *
+     * @param source - The full accumulated markdown source string
+     * @returns The new tokens and the index where they diverge from the previous parse
+     */
+    update: (source: string) => IncrementalUpdateResult;
+    /**
+     * Resets the parser state. Call this when starting a new stream.
+     */
+    reset: () => void;
+}

package/dist/utils/incremental-parser.js

@@ -0,0 +1,75 @@
+/**
+ * Incremental Markdown Parser for Streaming
+ *
+ * Optimizes streaming scenarios (LLM token-by-token updates) by performing
+ * a full re-parse but diffing the result against the previous token array.
+ * Only changed/appended tokens are returned as updates, allowing Svelte to
+ * skip re-rendering unchanged components.
+ *
+ * @module incremental-parser
+ */
+import { lexAndClean } from './parse-and-cache.js';
+/**
+ * Streaming-optimized parser that performs full re-parses but diffs results
+ * against the previous token array to minimize DOM updates.
+ *
+ * For append-only streaming (typical LLM use case), most tokens are identical
+ * between updates. By comparing `raw` strings, we identify which tokens changed
+ * so Svelte can skip re-rendering unchanged components.
+ *
+ * @example
+ * ```typescript
+ * const parser = new IncrementalParser({ gfm: true })
+ *
+ * // First update — all tokens are "new"
+ * const r1 = parser.update('# Hello')
+ * // r1.divergeAt === 0
+ *
+ * // Second update — heading unchanged, paragraph appended
+ * const r2 = parser.update('# Hello\n\nWorld')
+ * // r2.divergeAt === 1 (heading at index 0 unchanged)
+ * ```
+ */
+export class IncrementalParser {
+    /** Previous parse result for diffing */
+    prevTokens = [];
+    /** Parser options passed to the Marked lexer */
+    options;
+    /**
+     * Creates a new incremental parser instance.
+     *
+     * @param options - Svelte markdown parser options forwarded to Marked's Lexer
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Parses the full source and diffs against the previous result.
+     *
+     * @param source - The full accumulated markdown source string
+     * @returns The new tokens and the index where they diverge from the previous parse
+     */
+    update = (source) => {
+        const newTokens = lexAndClean(source, this.options, false);
+        // Apply walkTokens if configured
+        if (typeof this.options.walkTokens === 'function') {
+            newTokens.forEach(this.options.walkTokens);
+        }
+        // Find first divergence point by comparing raw strings
+        let divergeAt = 0;
+        const minLen = Math.min(this.prevTokens.length, newTokens.length);
+        while (divergeAt < minLen) {
+            if (this.prevTokens[divergeAt].raw !== newTokens[divergeAt].raw)
+                break;
+            divergeAt++;
+        }
+        this.prevTokens = newTokens;
+        return { tokens: newTokens, divergeAt };
+    };
+    /**
+     * Resets the parser state. Call this when starting a new stream.
+     */
+    reset = () => {
+        this.prevTokens = [];
+    };
+}

package/dist/utils/parse-and-cache.d.ts

@@ -8,6 +8,24 @@
  */
 import type { SvelteMarkdownOptions } from '../types.js';
 import type { Token, TokensList } from './markdown-parser.js';
+/**
+ * Lexes markdown source and cleans the resulting tokens. Shared by sync and async paths.
+ *
+ * @param source - Raw markdown string to lex
+ * @param options - Parser options forwarded to the Marked lexer
+ * @param isInline - When true, uses inline tokenization (no block elements)
+ * @returns Cleaned token array with HTML tokens properly nested
+ *
+ * @example
+ * ```typescript
+ * import { lexAndClean } from './parse-and-cache.js'
+ *
+ * const tokens = lexAndClean('# Hello **world**', { gfm: true }, false)
+ * ```
+ *
+ * @internal
+ */
+export declare const lexAndClean: (source: string, options: SvelteMarkdownOptions, isInline: boolean) => Token[];
 /**
  * Parses markdown source with caching (synchronous path).
  * Checks cache first, parses on miss, stores result, and returns tokens.

package/dist/utils/parse-and-cache.js

@@ -17,9 +17,16 @@ import { Lexer, Marked } from 'marked';
  * @param isInline - When true, uses inline tokenization (no block elements)
  * @returns Cleaned token array with HTML tokens properly nested
  *
+ * @example
+ * ```typescript
+ * import { lexAndClean } from './parse-and-cache.js'
+ *
+ * const tokens = lexAndClean('# Hello **world**', { gfm: true }, false)
+ * ```
+ *
  * @internal
  */
-const lexAndClean = (source, options, isInline) => {
+export const lexAndClean = (source, options, isInline) => {
     const lexer = new Lexer(options);
     const parsedTokens = isInline ? lexer.inlineTokens(source) : lexer.lex(source);
     return shrinkHtmlTokens(parsedTokens);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-markdown",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes",
   "keywords": [
     "svelte",
@@ -69,8 +69,8 @@
   "dependencies": {
     "@humanspeak/memory-cache": "^1.0.6",
     "github-slugger": "^2.0.0",
-    "htmlparser2": "^10.1.0",
-    "marked": "^17.0.4"
+    "htmlparser2": "^12.0.0",
+    "marked": "^17.0.5"
   },
   "devDependencies": {
     "@eslint/compat": "^2.0.3",
@@ -86,32 +86,32 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/katex": "^0.16.8",
     "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^10.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^4.1.1",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.15.2",
+    "eslint-plugin-svelte": "^3.16.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
-    "jsdom": "^29.0.0",
-    "katex": "^0.16.38",
+    "jsdom": "^29.0.1",
+    "katex": "^0.16.41",
     "marked-katex-extension": "^5.1.7",
     "mermaid": "^11.13.0",
-    "mprocs": "^0.8.3",
+    "mprocs": "^0.9.2",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.18",
-    "svelte": "^5.53.13",
+    "svelte": "^5.55.0",
     "svelte-check": "^4.4.5",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1",
-    "vite": "^8.0.0",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.2",
+    "vitest": "^4.1.1"
   },
   "peerDependencies": {
     "mermaid": ">=10.0.0",