Markstream Solid

Read the Solid guide for setup and the Solid component/API reference for exact contracts. The repository source contains workspace commands and validation records. Check the selected package's actual version and publication status before installing it.

Setup

1. Detect solid-js / @solidjs/start in the host. TSX alone does not imply React. Require Solid 1.9 and the Solid compiler; SolidStart owns its compiler setup.
2. While the package is a workspace preview, build and pack the parser, core and Solid packages together. For npm releases, use the package's declared dependency versions; never substitute an older published core/parser for the workspace build.
3. Add only required peers: katex, mermaid, stream-diffs, @terrastruct/d2 or @antv/infographic. Math also requires katex/dist/katex.min.css.
4. Load resets before exactly one markstream-solid/index.css, index.px.css or index.tailwind.css. Use .markstream-solid around standalone basic nodes.
5. Keep props reactive: read props.content in JSX/accessors. Avoid destructuring reactive props or treating signals as Vue refs.

Streaming and restoration

import MarkdownRender from 'markstream-solid'
import 'markstream-solid/index.css'

export function Message(props: { content: string, done: boolean }) {
  return <MarkdownRender mode="chat" content={props.content} final={props.done} />
}

• Append decoded Markdown to accumulated content. Set final at completion and back to false before resuming. Replacement/empty content starts a new source session.
• Use mode="chat" for conversations and mode="docs" for documents. smoothStreaming controls pacing; fade controls animation. Solid and Vue 3 share the bounded text fade implementation.
• useSmoothMarkdownStream returns accessors (visible(), source(), final(), done(), snapshot()). Use one pacing owner per response.
• Use non-empty nodes for shared/preparsed ASTs; an empty array falls back to content.
• For full immediate DOM restoration, disable pacing, batching, viewport priority, deferral and live windows explicitly. Use the default window/timeline for large interactive histories.
• Use MarkstreamVirtualTimeline for mixed message windows. Markdown items use its built-in renderer; renderItem supplies the non-Markdown fallback. Use useMarkstreamVirtualAdapter when an existing outer virtualizer owns rows.

Workers and SSR

• Configure Vite worker: { format: 'es' }.
• Import markstream-solid/workers/katexRenderer.worker?worker and markstream-solid/workers/mermaidParser.worker?worker, then call setKaTeXWorker / setMermaidWorker once in the browser entry or onMount.
• Use file workers for Mermaid: its diagram chunks need a resolvable module base. Do not copy the old inline-worker example.
• KaTeX worker renders block/inline math and includes mhchem. Mermaid worker handles parsing/prefix discovery; SVG rendering still runs on the main thread, matching Vue 3.
• CDN helpers are a separate path; supply dependency URLs and CSP/CORS permissions as documented. Host-owned highlighter pools use setStreamDiffsWorkerPool.
• Keep browser-only constructors behind the client boundary. SSR and hydration must start with identical content/final values. Prefer MarkstreamProvider for request-scoped translations/components.

Components and callbacks

• Use ComponentProps<typeof Component> from solid-js or the exported interfaces for exact TSX props.
• Use local customComponents, a MarkstreamProvider, or scoped setCustomComponents(id, mapping) for overrides. Mark block-level overrides with withMarkstreamComponentDisplay.
• Use callbacks instead of Vue emits, JSX/render functions instead of slots, and a callback ref for renderer/timeline handles.
• ReferenceNode forwards click/enter/leave with (event, id, messageId, threadId).
• MathBlockNode.cacheScope namespaces the renderer-owned pending-height cache with indexKey; it is not a global KaTeX macro/HTML-cache namespace.
• Mermaid stability/poll options control stable source-to-preview switching and bounded preview retries. Preserve cleanup and stale-result cancellation.
• Read the per-component/API tables before configuring previews, diagrams, virtual state or advanced worker clients.

Verification

Run the host's build and typecheck. In this repository use pnpm test:solid, pnpm test:smoke:solid, pnpm test:smoke:solid-workers, pnpm test:e2e:solid-playground and pnpm play:solid:seo. Verify worker consumption through packed subpaths, streaming/final/full restore, user scroll detachment, and SSR/hydration where applicable.