@humanspeak/svelte-markdown 1.2.0 → 1.3.0

package/README.md

@@ -683,11 +683,19 @@ Images automatically lazy load using native `loading="lazy"` and IntersectionObs
 
 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.
 
+The preferred API is now imperative: bind the component instance and call `writeChunk()` as chunks arrive. This avoids prop reactivity edge cases like identical consecutive string chunks being coalesced.
+
 ```svelte
 <script lang="ts">
     import SvelteMarkdown from '@humanspeak/svelte-markdown'
+    import type { StreamingChunk } from '@humanspeak/svelte-markdown'
 
-    let source = $state('')
+    let markdown:
+        | {
+              writeChunk: (chunk: StreamingChunk) => void
+              resetStream: (nextSource?: string) => void
+          }
+        | undefined
 
     async function streamResponse() {
         const response = await fetch('/api/chat', { method: 'POST', body: '...' })
@@ -697,11 +705,62 @@ For real-time rendering of AI responses from ChatGPT, Claude, Gemini, and other
         while (true) {
             const { done, value } = await reader.read()
             if (done) break
-            source += decoder.decode(value, { stream: true })
+            markdown?.writeChunk(decoder.decode(value, { stream: true }))
         }
     }
 </script>
 
+<SvelteMarkdown bind:this={markdown} source="" streaming={true} />
+```
+
+For websocket-style offset patches, pass an object chunk instead:
+
+```ts
+markdown?.writeChunk({ value: 'world', offset: 6 })
+```
+
+Object chunks overwrite the internal buffer at `offset`. This is overwrite semantics, not insert semantics: the chunk replaces characters starting at that index and preserves any trailing content after the overwritten span.
+
+If `offset` skips ahead, missing positions are padded with spaces. There is no delete or truncate behavior in offset mode.
+
+Typical websocket-style usage can arrive out of order:
+
+```ts
+markdown?.writeChunk({ value: ' world', offset: 5 })
+markdown?.writeChunk({ value: 'Hello', offset: 0 })
+```
+
+The internal buffer converges as later patches fill earlier gaps.
+
+You can reset the internal streaming buffer at any time:
+
+```ts
+markdown?.resetStream('')
+markdown?.resetStream('# Seeded response')
+```
+
+The first successful write after a reset locks the stream into one input mode:
+
+- `string` chunks: append mode
+- `{ value, offset }` chunks: offset mode
+
+Switching modes before `resetStream()` or a `source` prop reset logs a warning and drops the chunk. Offset chunks must use a non-negative safe integer `offset`.
+
+Changing the `source` prop also resets the imperative buffer, seeds a new baseline value, and unlocks the input mode.
+
+Appending directly to `source` is still supported:
+
+```svelte
+<script lang="ts">
+    import SvelteMarkdown from '@humanspeak/svelte-markdown'
+
+    let source = $state('')
+
+    function onChunk(chunk: string) {
+        source += chunk
+    }
+</script>
+
 <SvelteMarkdown {source} streaming={true} />
 ```
 

package/dist/SvelteMarkdown.svelte

@@ -50,7 +50,11 @@
      */
 
     import Parser from './Parser.svelte'
-    import { type SvelteMarkdownProps } from './types.js'
+    import {
+        type StreamingChunk,
+        type StreamingOffsetChunk,
+        type SvelteMarkdownProps
+    } from './types.js'
     import { IncrementalParser } from './utils/incremental-parser.js'
     import {
         defaultOptions,
@@ -65,6 +69,13 @@
 
     // trunk-ignore(eslint/@typescript-eslint/no-explicit-any)
     type AnySnippet = (..._args: any[]) => any
+    type StreamFlushHandle =
+        | { kind: 'raf'; id: number }
+        | { kind: 'timeout'; id: ReturnType<typeof setTimeout> }
+        | null
+
+    const STREAM_BATCH_FALLBACK_MS = 16
+    const STREAM_BATCH_MAX_CHARS = 256
 
     const {
         source = [],
@@ -99,51 +110,270 @@
     let incrementalParser: IncrementalParser | undefined
     let lastOptionsSrc: typeof options | undefined
     let lastExtensionsSrc: typeof extensions | undefined
+    let lastSourceProp: typeof source | undefined
+    let streamSourceBuffer = ''
+    let pendingStreamAppendBuffer = ''
+    let streamFlushHandle: StreamFlushHandle = null
+    let streamInputMode: 'append' | 'offset' | null = null
     let streamTokens = $state<Token[]>([])
 
+    const warnStreaming = (message: string) => {
+        console.warn(`[svelte-markdown] ${message}`)
+    }
+
+    const clearStreamingParser = () => {
+        incrementalParser = undefined
+        lastOptionsSrc = undefined
+        lastExtensionsSrc = undefined
+    }
+
+    const cancelScheduledAppendFlush = () => {
+        if (!streamFlushHandle) return
+
+        if (streamFlushHandle.kind === 'raf' && typeof cancelAnimationFrame === 'function') {
+            cancelAnimationFrame(streamFlushHandle.id)
+        } else if (streamFlushHandle.kind === 'timeout') {
+            clearTimeout(streamFlushHandle.id)
+        }
+
+        streamFlushHandle = null
+    }
+
+    const hasStreamingParserConfigChanged = () =>
+        !incrementalParser || lastOptionsSrc !== options || lastExtensionsSrc !== extensions
+
+    const applyStreamingSource = (nextSource: string, forceNewParser = false) => {
+        if (forceNewParser || hasStreamingParserConfigChanged()) {
+            incrementalParser = new IncrementalParser(combinedOptions)
+            lastOptionsSrc = options
+            lastExtensionsSrc = extensions
+        }
+
+        const parser = incrementalParser
+        if (!parser) return
+
+        const { tokens: newTokens, divergeAt } = parser.update(nextSource)
+
+        for (let i = divergeAt; i < newTokens.length; i++) {
+            streamTokens[i] = newTokens[i]
+        }
+        streamTokens.length = newTokens.length
+    }
+
+    const commitPendingAppendBuffer = () => {
+        if (pendingStreamAppendBuffer === '') return false
+
+        streamSourceBuffer += pendingStreamAppendBuffer
+        pendingStreamAppendBuffer = ''
+
+        return true
+    }
+
+    const flushPendingAppendChunks = (forceNewParser = false) => {
+        cancelScheduledAppendFlush()
+
+        if (!commitPendingAppendBuffer()) return
+
+        applyStreamingSource(streamSourceBuffer, forceNewParser)
+    }
+
+    const scheduleAppendFlush = () => {
+        if (streamFlushHandle || pendingStreamAppendBuffer === '') return
+
+        if (typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function') {
+            const id = window.requestAnimationFrame(() => {
+                streamFlushHandle = null
+                flushPendingAppendChunks()
+            })
+            streamFlushHandle = { kind: 'raf', id }
+            return
+        }
+
+        const id = setTimeout(() => {
+            streamFlushHandle = null
+            flushPendingAppendChunks()
+        }, STREAM_BATCH_FALLBACK_MS)
+        streamFlushHandle = { kind: 'timeout', id }
+    }
+
+    const teardownStreamingBuffers = () => {
+        cancelScheduledAppendFlush()
+        pendingStreamAppendBuffer = ''
+        streamInputMode = null
+        streamSourceBuffer = ''
+    }
+
+    const resetStreamingState = (nextSource = '') => {
+        teardownStreamingBuffers()
+        streamSourceBuffer = nextSource
+
+        if (nextSource === '') {
+            clearStreamingParser()
+            streamTokens.length = 0
+            return
+        }
+
+        applyStreamingSource(nextSource, true)
+    }
+
+    const syncStreamingSourceFromProp = (nextSource: typeof source) => {
+        lastSourceProp = nextSource
+
+        if (Array.isArray(nextSource)) {
+            teardownStreamingBuffers()
+            clearStreamingParser()
+            streamTokens = [...(nextSource as Token[])]
+            return
+        }
+
+        resetStreamingState(nextSource as string)
+    }
+
+    const canUseImperativeStreaming = (methodName: 'writeChunk' | 'resetStream'): boolean => {
+        if (!streaming) {
+            warnStreaming(`${methodName}() is only available when streaming={true}; call dropped.`)
+            return false
+        }
+
+        if (hasAsyncExtension) {
+            warnStreaming(
+                `${methodName}() is unavailable when async extensions are used; call dropped.`
+            )
+            return false
+        }
+
+        if (Array.isArray(source)) {
+            warnStreaming(
+                `${methodName}() requires a string-backed source; token array sources are not supported.`
+            )
+            return false
+        }
+
+        return true
+    }
+
+    const applyAppendChunk = (value: string) => {
+        pendingStreamAppendBuffer += value
+
+        if (pendingStreamAppendBuffer.length >= STREAM_BATCH_MAX_CHARS) {
+            flushPendingAppendChunks()
+            return
+        }
+
+        scheduleAppendFlush()
+    }
+
+    const applyOffsetChunk = ({ value, offset }: StreamingOffsetChunk) => {
+        const padded =
+            offset > streamSourceBuffer.length
+                ? streamSourceBuffer + ' '.repeat(offset - streamSourceBuffer.length)
+                : streamSourceBuffer
+        const prefix = padded.slice(0, offset)
+        const suffix = padded.slice(offset + value.length)
+
+        streamSourceBuffer = prefix + value + suffix
+        applyStreamingSource(streamSourceBuffer)
+    }
+
+    const isStreamingOffsetChunk = (chunk: StreamingChunk): chunk is StreamingOffsetChunk =>
+        typeof chunk === 'object' && chunk !== null && 'offset' in chunk
+
+    export function writeChunk(chunk: StreamingChunk): void {
+        if (!canUseImperativeStreaming('writeChunk')) return
+
+        if (typeof chunk === 'string') {
+            if (streamInputMode === 'offset') {
+                warnStreaming(
+                    'offset mode active, string chunk dropped. Call resetStream() before switching streaming input modes.'
+                )
+                return
+            }
+
+            if (streamInputMode === null) {
+                streamInputMode = 'append'
+            }
+
+            applyAppendChunk(chunk)
+            return
+        }
+
+        if (!isStreamingOffsetChunk(chunk) || typeof chunk.value !== 'string') {
+            warnStreaming(
+                'Invalid chunk object passed to writeChunk(); expected { value: string, offset: number }.'
+            )
+            return
+        }
+
+        if (!Number.isSafeInteger(chunk.offset) || chunk.offset < 0) {
+            warnStreaming(
+                'Invalid offset chunk passed to writeChunk(); offset must be a non-negative safe integer.'
+            )
+            return
+        }
+
+        if (streamInputMode === 'append') {
+            warnStreaming(
+                'append mode active, offset chunk dropped. Call resetStream() before switching streaming input modes.'
+            )
+            return
+        }
+
+        if (streamInputMode === null) {
+            streamInputMode = 'offset'
+        }
+
+        applyOffsetChunk(chunk)
+    }
+
+    export function resetStream(nextSource = ''): void {
+        if (!canUseImperativeStreaming('resetStream')) return
+
+        resetStreamingState(nextSource)
+    }
+
+    $effect(() => {
+        return () => {
+            cancelScheduledAppendFlush()
+        }
+    })
+
     $effect(() => {
         if (!streaming || hasAsyncExtension) {
-            if (incrementalParser) {
-                incrementalParser = undefined
-                lastOptionsSrc = undefined
-                lastExtensionsSrc = undefined
-            }
+            teardownStreamingBuffers()
+            if (incrementalParser) clearStreamingParser()
+            lastSourceProp = source
             if (streaming && hasAsyncExtension) {
-                console.warn(
-                    '[svelte-markdown] streaming prop is ignored when async extensions are used. ' +
+                warnStreaming(
+                    'streaming prop is ignored when async extensions are used. ' +
                         'Remove async extensions or set streaming={false} to silence this warning.'
                 )
             }
             return
         }
 
-        // Read combinedOptions so Svelte tracks it as a dependency
-        const currentOptions = combinedOptions
-
-        if (Array.isArray(source)) {
-            streamTokens = source as Token[]
+        if (lastSourceProp !== source) {
+            syncStreamingSourceFromProp(source)
             return
         }
 
-        if (source === '') {
-            if (incrementalParser) incrementalParser.reset()
-            streamTokens.length = 0
+        if (Array.isArray(source)) {
             return
         }
 
-        // Recreate parser when user-facing options or extensions change
-        if (!incrementalParser || lastOptionsSrc !== options || lastExtensionsSrc !== extensions) {
-            incrementalParser = new IncrementalParser(currentOptions)
-            lastOptionsSrc = options
-            lastExtensionsSrc = extensions
-        }
-        const { tokens: newTokens, divergeAt } = incrementalParser.update(source as string)
+        if (hasStreamingParserConfigChanged()) {
+            if (pendingStreamAppendBuffer !== '') {
+                flushPendingAppendChunks(true)
+                return
+            }
 
-        // In-place update: only touch changed/appended indices
-        for (let i = divergeAt; i < newTokens.length; i++) {
-            streamTokens[i] = newTokens[i]
+            if (streamSourceBuffer === '') {
+                clearStreamingParser()
+                streamTokens.length = 0
+                return
+            }
+
+            applyStreamingSource(streamSourceBuffer, true)
         }
-        streamTokens.length = newTokens.length
     })
 
     // Synchronous token derivation (default fast path — non-streaming)
@@ -204,7 +434,13 @@
     })
 
     // Unified tokens: streaming > sync > async
-    const tokens = $derived(streaming ? streamTokens : hasAsyncExtension ? asyncTokens : syncTokens)
+    const tokens = $derived(
+        streaming && !hasAsyncExtension
+            ? streamTokens
+            : hasAsyncExtension
+              ? asyncTokens
+              : syncTokens
+    )
 
     $effect(() => {
         if (!tokens) return

package/dist/SvelteMarkdown.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type SvelteMarkdownProps } from './types.js';
+import { type StreamingChunk, type SvelteMarkdownProps } from './types.js';
 type $$ComponentProps = SvelteMarkdownProps & {
     [key: string]: unknown;
 };
@@ -24,6 +24,9 @@ type $$ComponentProps = SvelteMarkdownProps & {
  * @property {boolean} [isInline=false] - Whether to parse the content as inline markdown
  * @property {function} [parsed] - Callback function called with the parsed tokens
  */
-declare const SvelteMarkdown: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const SvelteMarkdown: import("svelte").Component<$$ComponentProps, {
+    writeChunk: (chunk: StreamingChunk) => void;
+    resetStream: (nextSource?: string) => void;
+}, "">;
 type SvelteMarkdown = ReturnType<typeof SvelteMarkdown>;
 export default SvelteMarkdown;

package/dist/index.d.ts

@@ -17,7 +17,7 @@
  */
 import { type HtmlRenderers } from './renderers/html/index.js';
 import SvelteMarkdown from './SvelteMarkdown.svelte';
-import type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, SnippetOverrides, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps } from './types.js';
+import type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, SnippetOverrides, StreamingChunk, StreamingOffsetChunk, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps } from './types.js';
 import { defaultRenderers, type RendererComponent, type Renderers, type Token, type TokensList } from './utils/markdown-parser.js';
 /** The primary markdown rendering component. */
 export default SvelteMarkdown;
@@ -63,4 +63,4 @@ export { TokenCache, tokenCache } from './utils/token-cache.js';
 /** Re-exported `MarkedExtension` type for the `extensions` prop. */
 export type { MarkedExtension } from 'marked';
 /** Re-exported types for consumer convenience. */
-export type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlRenderers, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, RendererComponent, Renderers, SnippetOverrides, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps, Token, TokensList };
+export type { BlockquoteSnippetProps, BrSnippetProps, CodeSnippetProps, CodespanSnippetProps, DelSnippetProps, EmSnippetProps, EscapeSnippetProps, HeadingSnippetProps, HrSnippetProps, HtmlRenderers, HtmlSnippetOverrides, HtmlSnippetProps, ImageSnippetProps, LinkSnippetProps, ListItemSnippetProps, ListSnippetProps, ParagraphSnippetProps, RawTextSnippetProps, RendererComponent, Renderers, SnippetOverrides, StreamingChunk, StreamingOffsetChunk, StrongSnippetProps, SvelteMarkdownOptions, SvelteMarkdownProps, TableBodySnippetProps, TableCellSnippetProps, TableHeadSnippetProps, TableRowSnippetProps, TableSnippetProps, TextSnippetProps, Token, TokensList };

package/dist/types.d.ts

@@ -139,6 +139,11 @@ export interface HtmlSnippetProps {
 export type HtmlSnippetOverrides = {
     [K in HtmlKey as `html_${K}`]?: Snippet<[HtmlSnippetProps]>;
 };
+export interface StreamingOffsetChunk {
+    value: string;
+    offset: number;
+}
+export type StreamingChunk = string | StreamingOffsetChunk;
 export type SvelteMarkdownProps<T extends Renderers = Renderers> = {
     /**
      * Markdown content to render.

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

@@ -43,14 +43,23 @@ export interface IncrementalUpdateResult {
 export declare class IncrementalParser {
     /** Previous parse result for diffing */
     private prevTokens;
+    /** Previous full source string for append-only tail reparsing */
+    private prevSource;
     /** Parser options passed to the Marked lexer */
     private options;
+    /** Whether caller-supplied parser hooks make tail-window reparsing unsafe */
+    private tailWindowDisabled;
     /**
      * Creates a new incremental parser instance.
      *
      * @param options - Svelte markdown parser options forwarded to Marked's Lexer
      */
     constructor(options: SvelteMarkdownOptions);
+    private getTailWindowBoundary;
+    private isStableAtSourceEnd;
+    private hasAppendSensitiveReferenceSyntax;
+    private canUseTailWindow;
+    private parseSource;
     /**
      * Parses the full source and diffs against the previous result.
      *
@@ -58,8 +67,4 @@ export declare class IncrementalParser {
      * @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

@@ -9,6 +9,10 @@
  * @module incremental-parser
  */
 import { lexAndClean } from './parse-and-cache.js';
+const CLOSED_FENCE_RE = /^ {0,3}(`{3,}|~{3,}).*\n[\s\S]*\n {0,3}\1[ \t]*\n*$/;
+const LINK_REFERENCE_RE = /\[[^\]\n]+\]\[[^\]\n]*\]/;
+const SHORTCUT_REFERENCE_RE = /\[[^\]\n]+\](?![[(])/; // Excludes inline links/images and full refs
+const REFERENCE_DEFINITION_RE = /^\s{0,3}\[[^\]\n]+\]:/m;
 /**
  * Streaming-optimized parser that performs full re-parses but diffs results
  * against the previous token array to minimize DOM updates.
@@ -33,8 +37,12 @@ import { lexAndClean } from './parse-and-cache.js';
 export class IncrementalParser {
     /** Previous parse result for diffing */
     prevTokens = [];
+    /** Previous full source string for append-only tail reparsing */
+    prevSource = '';
     /** Parser options passed to the Marked lexer */
     options;
+    /** Whether caller-supplied parser hooks make tail-window reparsing unsafe */
+    tailWindowDisabled;
     /**
      * Creates a new incremental parser instance.
      *
@@ -42,7 +50,77 @@ export class IncrementalParser {
      */
     constructor(options) {
         this.options = options;
+        const exts = options.extensions;
+        const hasExtensionTokenizers = (exts?.block != null && exts.block.length > 0) ||
+            (exts?.inline != null && exts.inline.length > 0);
+        this.tailWindowDisabled =
+            typeof options.walkTokens === 'function' ||
+                options.tokenizer != null ||
+                hasExtensionTokenizers;
     }
+    getTailWindowBoundary = () => {
+        if (this.prevTokens.length === 0) {
+            return { prefixCount: 0, reparseOffset: 0 };
+        }
+        let offset = 0;
+        for (let i = 0; i < this.prevTokens.length - 1; i++) {
+            offset += this.prevTokens[i].raw.length;
+        }
+        const lastToken = this.prevTokens[this.prevTokens.length - 1];
+        if (this.isStableAtSourceEnd(lastToken)) {
+            return {
+                prefixCount: this.prevTokens.length,
+                reparseOffset: this.prevSource.length
+            };
+        }
+        return {
+            prefixCount: this.prevTokens.length - 1,
+            reparseOffset: offset
+        };
+    };
+    isStableAtSourceEnd = (token) => {
+        if (token.type === 'space')
+            return false;
+        if (token.raw.endsWith('\n\n'))
+            return true;
+        switch (token.type) {
+            case 'heading':
+            case 'hr':
+                return token.raw.endsWith('\n');
+            case 'code':
+                return CLOSED_FENCE_RE.test(token.raw);
+            default:
+                return false;
+        }
+    };
+    hasAppendSensitiveReferenceSyntax = (source) => {
+        if (!source.includes('[') || !source.includes(']'))
+            return false;
+        return (LINK_REFERENCE_RE.test(source) ||
+            SHORTCUT_REFERENCE_RE.test(source) ||
+            REFERENCE_DEFINITION_RE.test(source));
+    };
+    canUseTailWindow = (source, boundary) => {
+        if (this.tailWindowDisabled)
+            return false;
+        if (this.prevSource === '' || this.prevTokens.length === 0)
+            return false;
+        if (!source.startsWith(this.prevSource))
+            return false;
+        if (boundary.reparseOffset <= 0)
+            return false;
+        const stablePrefix = this.prevSource.slice(0, boundary.reparseOffset);
+        if (this.hasAppendSensitiveReferenceSyntax(stablePrefix))
+            return false;
+        return true;
+    };
+    parseSource = (source, boundary) => {
+        if (!this.canUseTailWindow(source, boundary)) {
+            return lexAndClean(source, this.options, false);
+        }
+        const tailTokens = lexAndClean(source.slice(boundary.reparseOffset), this.options, false);
+        return [...this.prevTokens.slice(0, boundary.prefixCount), ...tailTokens];
+    };
     /**
      * Parses the full source and diffs against the previous result.
      *
@@ -50,26 +128,28 @@ export class IncrementalParser {
      * @returns The new tokens and the index where they diverge from the previous parse
      */
     update = (source) => {
-        const newTokens = lexAndClean(source, this.options, false);
+        const boundary = this.getTailWindowBoundary();
+        const newTokens = this.parseSource(source, boundary);
         // Apply walkTokens if configured
         if (typeof this.options.walkTokens === 'function') {
             newTokens.forEach(this.options.walkTokens);
         }
+        // Reference definitions can change inline children without changing raw,
+        // so force a full rerender when reference syntax is present
+        const referenceSensitive = this.hasAppendSensitiveReferenceSyntax(this.prevSource) ||
+            this.hasAppendSensitiveReferenceSyntax(source);
         // 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++;
+        if (!referenceSensitive) {
+            const minLen = Math.min(this.prevTokens.length, newTokens.length);
+            while (divergeAt < minLen) {
+                if (this.prevTokens[divergeAt].raw !== newTokens[divergeAt].raw)
+                    break;
+                divergeAt++;
+            }
         }
+        this.prevSource = source;
         this.prevTokens = newTokens;
         return { tokens: newTokens, divergeAt };
     };
-    /**
-     * Resets the parser state. Call this when starting a new stream.
-     */
-    reset = () => {
-        this.prevTokens = [];
-    };
 }

package/dist/utils/stream-benchmark.d.ts

@@ -0,0 +1,26 @@
+import type { SvelteMarkdownOptions } from '../types.js';
+import type { Token } from './markdown-parser.js';
+export interface StreamBenchmarkResult {
+    totalChars: number;
+    chunkCount: number;
+    totalParseMs: number;
+    peakParseMs: number;
+    p95ParseMs: number;
+    finalTokens: Token[];
+    parseDurationsMs: number[];
+}
+/**
+ * Benchmarks incremental parsing performance by simulating streaming chunk appends.
+ *
+ * @param chunks - Array of string chunks to append sequentially
+ * @param options - SvelteMarkdown parser options forwarded to IncrementalParser
+ * @returns Benchmark results including per-chunk timing, peak, and p95 parse durations
+ *
+ * @example
+ * ```ts
+ * const chunks = ['# Hello ', 'world, ', 'this is a test.']
+ * const result = benchmarkAppendStream(chunks, { gfm: true })
+ * console.log(result.p95ParseMs, result.peakParseMs)
+ * ```
+ */
+export declare const benchmarkAppendStream: (chunks: string[], options: SvelteMarkdownOptions) => StreamBenchmarkResult;

package/dist/utils/stream-benchmark.js

@@ -0,0 +1,53 @@
+import { IncrementalParser } from './incremental-parser.js';
+/**
+ * Calculates the p-th percentile of a numeric array.
+ *
+ * @param values - Array of numeric values
+ * @param p - Percentile to calculate (0-1, e.g., 0.95 for 95th percentile)
+ * @returns The value at the specified percentile, or 0 if array is empty
+ */
+const percentile = (values, p) => {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+    return sorted[index];
+};
+/**
+ * Benchmarks incremental parsing performance by simulating streaming chunk appends.
+ *
+ * @param chunks - Array of string chunks to append sequentially
+ * @param options - SvelteMarkdown parser options forwarded to IncrementalParser
+ * @returns Benchmark results including per-chunk timing, peak, and p95 parse durations
+ *
+ * @example
+ * ```ts
+ * const chunks = ['# Hello ', 'world, ', 'this is a test.']
+ * const result = benchmarkAppendStream(chunks, { gfm: true })
+ * console.log(result.p95ParseMs, result.peakParseMs)
+ * ```
+ */
+export const benchmarkAppendStream = (chunks, options) => {
+    const parser = new IncrementalParser(options);
+    const parseDurationsMs = [];
+    let source = '';
+    let finalTokens = [];
+    for (const chunk of chunks) {
+        source += chunk;
+        const start = performance.now();
+        const result = parser.update(source);
+        const elapsed = performance.now() - start;
+        parseDurationsMs.push(elapsed);
+        finalTokens = result.tokens;
+    }
+    const totalParseMs = parseDurationsMs.reduce((sum, duration) => sum + duration, 0);
+    return {
+        totalChars: source.length,
+        chunkCount: chunks.length,
+        totalParseMs,
+        peakParseMs: parseDurationsMs.length > 0 ? Math.max(...parseDurationsMs) : 0,
+        p95ParseMs: percentile(parseDurationsMs, 0.95),
+        finalTokens,
+        parseDurationsMs
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-markdown",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes",
   "keywords": [
     "svelte",
@@ -75,7 +75,7 @@
   "devDependencies": {
     "@eslint/compat": "^2.0.3",
     "@eslint/js": "^10.0.1",
-    "@playwright/cli": "^0.1.1",
+    "@playwright/cli": "^0.1.2",
     "@playwright/test": "^1.58.2",
     "@sveltejs/adapter-auto": "^7.0.1",
     "@sveltejs/kit": "^2.55.0",
@@ -86,9 +86,9 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/katex": "^0.16.8",
     "@types/node": "^25.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.57.2",
-    "@typescript-eslint/parser": "^8.57.2",
-    "@vitest/coverage-v8": "^4.1.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
+    "@vitest/coverage-v8": "^4.1.2",
     "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -97,7 +97,7 @@
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "jsdom": "^29.0.1",
-    "katex": "^0.16.41",
+    "katex": "^0.16.44",
     "marked-katex-extension": "^5.1.7",
     "mermaid": "^11.13.0",
     "mprocs": "^0.9.2",
@@ -106,12 +106,12 @@
     "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.18",
-    "svelte": "^5.55.0",
-    "svelte-check": "^4.4.5",
+    "svelte": "^5.55.1",
+    "svelte-check": "^4.4.6",
     "typescript": "^6.0.2",
-    "typescript-eslint": "^8.57.2",
-    "vite": "^8.0.2",
-    "vitest": "^4.1.1"
+    "typescript-eslint": "^8.58.0",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
     "mermaid": ">=10.0.0",