@copse/streaming-markdown

Markdown that renders as it arrives. Two emitters for the same content stream — a pure string→HTML function for at-rest rendering, and an incremental DOM renderer that reveals partial markdown as tokens arrive without flashing raw syntax. CommonMark + GFM, built for LLM/agent chat UIs, but host-independent.

▶ Live demo — watch both emitters stream the same content side by side.

npm install @copse/streaming-markdown

Quick start

At rest — renderMarkdown is the safe, default entry point: its output has already passed through the sink sanitizer, so it drops straight into innerHTML (or setSanitizedHtml, which is also Trusted Types-safe):

import { renderMarkdown, setSanitizedHtml } from '@copse/streaming-markdown'

setSanitizedHtml(el, renderMarkdown('# Hi\n\n**bold** and ~~strike~~'))
// el.innerHTML = renderMarkdown('…') is also safe — the output is sanitized.

Because sanitizing builds a DOM, renderMarkdown needs a sanitizer backend (the browser's native Sanitizer API by default, or a registered one such as …/sanitizers/dompurify); with neither available it throws rather than return unsafe HTML.

Working with strings end-to-end (SSR, snapshots, non-DOM pipelines) with no backend? Use renderMarkdownUnsafe — the zero-dependency, DOM-free path. It returns untrusted HTML, so pass it through sanitizeRenderedMarkdown before it reaches any innerHTML sink you manage yourself.

Streaming — feed the growing string on each token. The string emitter is the simplest; the DOM emitter patches incrementally instead of replacing innerHTML:

import { StreamingMarkdownRenderer } from '@copse/streaming-markdown'

const renderer = new StreamingMarkdownRenderer(el)
for await (const chunk of stream) {
  accumulated += chunk
  renderer.update(accumulated) // incremental DOM patch, pending blocks styled while they form
}
renderer.finish() // end of stream: release held text, close an unclosed fence, render at rest

Mid-stream the renderer holds back what the next character could still change (a trailing ~~run, the last table row or list item). finish() tells it nothing more is coming: .stream-complete then matches renderMarkdown of the same text with its last line ended (identical to renderMarkdown(text) except in three shapes it parses provisionally without the newline; see finish()). A later update() resumes streaming. With the string emitter, render the end-of-stream frame the same way: renderMarkdown(accumulated), with a final \n appended if it lacks one.

Highlights

• Streaming-safe. Pending block states show partial structure (tables, lists, code, diagrams, math) without flashing raw syntax; a re-render upgrades in place.
• CommonMark + GFM — tables, task lists, strikethrough, autolinks, footnotes ([^1]), GitHub alerts (> [!NOTE]), indented and fenced code. Tracked against the spec's conformance suite.
• First-class math. ```math fences, $$…$$ and \[…\] display blocks (the OpenAI delimiter style), and $…$ / \(…\) inline math with currency guards ($20 and $30 stays prose) — rendered lazily via KaTeX, streamed without delimiter flash. The prose delimiters are opt-in per render via { mathSyntax: true }; until then output stays byte-identical to a math-free build (the ```math fence renders regardless). See Math in docs/EXTENDING.md.
• Sanitize at the sink. Rendered HTML is treated as untrusted and links are scheme-validated; the sink sanitizer is the security gate. Raw HTML is passed through by default (htmlPolicy: 'passthrough') and the sink sanitizer is the sole arbiter — allowlisted tags render as elements, everything else (including <script>) is stripped/unwrapped; pass htmlPolicy: 'escape' in the render config to literalize raw HTML instead, e.g. if you write the renderer string to a sink without sanitizing. An opt-in link/image origin allowlist (linkImagePolicy) layers on top — restrict which origins links/images may point at, rewrite/neutralize the rest, and strip base64 data: images — off by default, byte-identical until you set it. See Link/image origin policy in docs/EXTENDING.md. The full security model, threat model, and hardening knobs are in docs/SECURITY.md.
• Zero runtime dependencies. The core carries no required dependency. HTML character references decode against a built-in set (the 252 classic HTML4 named references plus all numeric references) that covers essentially everything real markdown emits; the full ~2,100-entry HTML5 table (~23 KB gzip) is opt-in via browserEntityDecoder (zero bundle cost in the DOM) or the @copse/streaming-markdown/entities/full entry — see Entity decoding in docs/EXTENDING.md. highlight.js (or Shiki — both ship as backends), DOMPurify, mermaid, and KaTeX are optional and lazy — never in your bundle unless you opt in. See docs/LAZY-LOADING.md.
• Pluggable everything — sanitizer, syntax highlighter, mermaid & math & custom fenced blocks, custom inline syntax (citations, highlights), and <a> routing are all injectable. Emoji shortcodes (:smile: → 😄) ship as an optional inline pass behind @copse/streaming-markdown/inline/emoji — a GitHub/gemoji-aligned map, zero bytes in your bundle unless imported.
• Optional reveal smoothing. An opt-in helper (@copse/streaming-markdown/smoothing) steadies chunky token arrival into a smooth character-cadence reveal by throttling the input fed to renderer.update() — at a fixed rate, or adaptively following the stream's own rate — and never stops a frame on half-arrived markdown syntax. Off by default and zero bytes unless imported; honours prefers-reduced-motion, and at stream end either drains briefly (finish) or releases at once (flush). See Input smoothing in docs/LAZY-LOADING.md.

Extending

The sanitizer, syntax highlighter, diagram/fenced-block renderers, custom inline syntax, link routing, and raw-image handling are all plug points — register a backend once and it stays out of your bundle until you do. The full guide, with code for each, is in docs/EXTENDING.md:

import { renderMarkdown } from '@copse/streaming-markdown'
import { dompurifyBackend } from '@copse/streaming-markdown/sanitizers/dompurify'

// Pass the backend in the per-render config — e.g. for Node/jsdom/SSR.
renderMarkdown(md, { sanitizerBackend: dompurifyBackend })

Pages that enforce Trusted Types (require-trusted-types-for 'script') are supported out of the box with any backend — see Trusted Types in docs/EXTENDING.md for the CSP policy names and the trustedTypesPolicy config field.

Chinese / Japanese / Korean output has an opt-in entry too: spread cjkFriendlyConfig from @copse/streaming-markdown/cjk into the render config to make emphasis and bare autolinks behave around full-width punctuation (**「強調」**, https://example.com。), and the optional styles/cjk.css carries the line-break / spacing CSS the host owns — see CJK / East-Asian text. Both are off by default; Latin output is byte-identical.

React

First-party React bindings ship as the @copse/streaming-markdown/react subpath. React is an optional peer dependency, so it stays out of your bundle until you import that subpath. Two components mirror the core's two rendering paths — no useEffect/useRef boilerplate and no dangerouslySetInnerHTML in your code, because each component owns its node and routes every DOM write through the sanitizer internally:

import { Markdown, StreamingMarkdown } from '@copse/streaming-markdown/react'

// At rest — a complete document. SSR-safe; every DOM write is sanitized.
<Markdown markdown={content} />

// Streaming — feed the growing text; the incremental DOM renderer patches only
// the settled tail per token, not a re-render of the whole document (the thing
// that makes naive react-markdown-in-a-loop janky).
<StreamingMarkdown markdown={accumulatedText} />

Both take a per-instance config prop (html/scheme policy, linkDecorator, fenceHandlers, math/CJK toggles, …), an as prop to pick the container element, and forward standard container attributes (className, etc.). The full guide — SSR and hydration, the onUpdate hook for math/diagram backends, and a react-markdown migration — is in docs/REACT.md.

Styling

The renderer emits documented class hooks but ships no styles by default. Optional stylesheets are provided (styles/core.css, structural only; styles/default.css, a batteries-included theme; styles/cjk.css, opt-in East-Asian line-break / spacing); each scopes every rule under a .streaming-markdown class:

import '@copse/streaming-markdown/styles/default.css'
el.classList.add('streaming-markdown')

Retheme via --sm-* custom properties. Full details — class contract, the CSS variables, and native-nesting note — are in docs/EXTENDING.md.

Documentation

• docs/REACT.md — using it from React: at-rest and incremental-streaming components, SSR, and migrating from react-markdown.
• docs/EXTENDING.md — every plug point (sanitizer, highlighter, custom fenced blocks, link routing, images, scheme allowlist) and styling.
• docs/RECIPES.md — UI recipes: how to add copy buttons (and similar widgets) to code blocks without fighting the streaming morph.
• docs/LAZY-LOADING.md — why the heavy deps are optional and lazy, and how the code-split loading works.
• docs/ARCHITECTURE.md — design invariants, the two-emitter streaming architecture, and the regression/conformance suite.
• docs/BENCHMARKS.md — cross-library streaming benchmarks (vs Streamdown, react-markdown, smd, Incremark): methodology, caveats, and the latest published results.
• docs/SECURITY.md — the sanitize-at-the-sink security model, a threat model, trust boundaries, and hardening knobs.
• docs/GITHUB-PARITY.md — the by-design divergences from github.com rendering, validated against GitHub's actual comment HTML, and which gaps close via configuration.

Stability & versioning

The package follows semver. The contract covers:

• The main entry's exports (src/index.ts) — every symbol is stable; the pre-1.0 @experimental tier (ambient-config introspection getters and low-level renderer internals) was removed from the entry at 1.0.
• The subpath entries (/sanitizers/*, /highlighters/*, /math/katex, /diagrams, /diagrams/mermaid, /inline/emoji, /cjk, /entities/full, /smoothing, /react, /host/workspace) and the CSS entry points.
• Default output stability. The CommonMark/GFM conformance baselines and the "byte-identical until you opt in" property (math syntax, link/image policy, entity tables) are part of the contract — changes to default output are breaking changes.

Streaming pending-state markup (stream-pending-* classes and transient structure) is a rendering behaviour, not a wire format: its invariants (no raw syntax flash; convergence with the at-rest render) are stable, its exact transient DOM is not.

Development

Pull requests can receive advisory Copse reviews, running entirely in this repository's GitHub Actions alongside normal CI.

npm install
npm run typecheck   # tsc (strict, exactOptionalPropertyTypes)
npm test            # node:test via tsx — unit + CommonMark & GFM conformance
npm run build       # emit dist/ (ESM JS + .d.ts)
npm run test:e2e    # Trusted Types enforcement e2e in real Chromium (skips without a browser)
npm run bench:browser  # sink-path throughput in real Chromium, incl. a TT-enforced page

Diagram rendering

Pele is the default diagram backend, available through diagrams (also diagrams/pele). It renders Mermaid syntax and loads only on the first hydration. Pass an SVG sanitizer through transformSvg; the demo uses DOMPurify. Mermaid.js remains available through the explicit diagrams/mermaid adapter. The core emits inert diagram source until a host configures a backend.

Isolated Mermaid rendering

For an opaque execution frame with hash-pinned CSP, use the optional diagrams/mermaid/isolated adapter. It runs Mermaid entirely outside the parent document. Serve the prebuilt frame document (diagrams/mermaid/frame.html) or build your own; theme, label font and the frame's accessible name are per-render options. Hosts retain navigation/native API enforcement. The existing in-document adapter is unchanged. For zoom, pan, reset and full screen on a rendered diagram, the optional diagrams/mermaid/viewer adds plain-DOM controls (styles/diagram-viewer.css styles them).