@brett_lamy/docstream 1.2.4 → 1.3.0

package/README.md

@@ -13,7 +13,7 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
   Markdown vs HTML images, blank lines between blocks, list markers, fences, table layout and tag lines as written).
   Layout-only fields (`gap`, `raw`, `opening`, …) are recorded only where the source differs from the default
   output, and are ignored once they no longer fit an edited node.
-- Syntax-highlighted code blocks through `lowlight`.
+- Syntax-highlighted code blocks through `gpu-lexer`; Mermaid diagrams and KaTeX math load on first use.
 - GitBook block support for hints, tabs, expandables, steppers, embeds, content refs, columns, figures, tables, math, dividers, updates, and OpenAPI operations.
 - CSS exported as a stable package entrypoint so host apps can theme with CSS variables or shadcn-style design tokens.
 - Attribute-aware direct video embeds for muted, looping inline clips in long-form posts.
@@ -23,10 +23,31 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 ## Installation
 
 ```sh
-npm install @brett_lamy/docstream react
+pnpm add @brett_lamy/docstream
+# or: npm install @brett_lamy/docstream
 ```
 
-React is a peer dependency and must be provided by your app.
+React and React DOM are peer dependencies and must be provided by your app.
+Nothing in docstream's dependency tree runs an install script, so
+`pnpm add` succeeds with no build-script prompts (no `ERR_PNPM_IGNORED_BUILDS`).
+Heavy renderers are loaded only when a page needs them: Mermaid for
+` ```mermaid ` fences, KaTeX for math blocks, rrweb for replay event lists.
+
+Two features are opt-in, each behind its own entry and an **optional** peer
+dependency that the rest of the package never references:
+
+| Entry | Install to use it | What it adds |
+| --- | --- | --- |
+| `@brett_lamy/docstream/playground` | `@agent-wasm/core` (almost-node, an in-browser Node runtime) | Live React code fences and runnable inline `{% demo %}` files |
+| `@brett_lamy/docstream/viz` | `@brett_lamy/viz-engine` | `VizEmbed` |
+
+```sh
+pnpm add @agent-wasm/core   # only if you import @brett_lamy/docstream/playground
+```
+
+Without the playground, live code fences render as highlighted code (or through
+a `liveRenderer` you pass), and inline-file demos open on their Code view with a
+short "needs the playground runtime" note.
 
 ## Basic Setup
 
@@ -50,11 +71,12 @@ If your TypeScript app checks CSS side-effect imports, include Vite's standard e
 
 Use `GitbookStreamdown` when markdown may arrive incrementally from an AI stream. The component accepts either `markdown` or string children.
 
-Markdown-only applications can import the renderer from the `streamdown`
-subpath. This keeps optional playground integrations out of the host bundle:
+The package root's `GitbookStreamdown` is the same component as the
+`@brett_lamy/docstream/streamdown` entry. For live code fences and runnable
+inline demos, import the playground variant instead (requires `@agent-wasm/core`):
 
 ```tsx
-import { GitbookStreamdown } from "@brett_lamy/docstream/streamdown"
+import { GitbookStreamdown } from "@brett_lamy/docstream/playground" // = PlaygroundStreamdown
 ```
 
 ```tsx
@@ -367,13 +389,15 @@ what it did before 1.2: a demo, then a code block. While streaming, a block whos
 | inline files | no runtime (e.g. the `/streamdown` entry) | a one-line note; the viewer opens on Code | the inline files |
 | `src` only | no resolver | a placeholder chip | — |
 
-The package root's `GitbookStreamdown` (`PlaygroundStreamdown`) runs inline demos
-in almost-node by default. Elsewhere pass `demoRuntime`:
+`PlaygroundStreamdown` (also exported as `GitbookStreamdown` from
+`@brett_lamy/docstream/playground`) runs inline demos in almost-node by default.
+Elsewhere pass `demoRuntime` (and `liveRenderer` for live code fences):
 
 ```tsx
 import { createAlmostNodeDemoRuntime } from "@brett_lamy/docstream/playground"
 
 const demoRuntime = createAlmostNodeDemoRuntime({ workspaceOptions: { basePath: "/docs" } })
+// live code fences: import { almostNodeLiveRenderer } from "@brett_lamy/docstream/playground"
 
 <MarkdownContent markdown={page} demoResolver={demoResolver} demoRuntime={demoRuntime}
   demoDependencies={{ "@brett_lamy/ui": "^1.2.0" }} />
@@ -546,7 +570,8 @@ You can also resolve paths yourself with `resolveAsset`.
 - `resolveDemosToMarkdown(markdown, resolver, { format })`: Gives each `{% demo %}` its real files inline — renderable docstream by default, `format: "plain"` for LLM prompts (pure, async).
 - `inlineDemoMarkdown(node, files, meta)`: One demo as a pasteable block-form `{% demo %}`.
 - `preloadDemos(resolver, srcs)`: Settle resolver demos before the first render (SSR, static export).
-- `createAlmostNodeDemoRuntime(options)` / `InlineDemoPreview` / `createInlineDemoProject(files, { entry, dependencies })` (`/playground`): Run inline demo files in almost-node.
+- `createAlmostNodeDemoRuntime(options)` / `InlineDemoPreview` (`/playground`): Run inline demo files in almost-node. `createInlineDemoProject(files, { entry, dependencies })` (root and `/playground`) builds the runnable project as plain data.
+- `PlaygroundStreamdown`, `almostNodeLiveRenderer`, `ReactDemo` / `ReactCodePreview`, `createAlmostNodeWorkspace`, `useAlmostNodeServer` (`/playground` only): the almost-node playground.
 - `DocPageActions`: The "Copy page ▾" menu.
 
 ### Parser and Serializer
@@ -623,6 +648,23 @@ This release ships TypeScript and TSX source through ESM exports:
 
 It is validated with Vite and modern TypeScript `moduleResolution: "Bundler"`. Plain Node.js, CommonJS, or tooling that does not transpile TypeScript in dependencies may need a future precompiled JS build.
 
+## Migrating to 1.3
+
+1.3 moves everything that touches almost-node (`@agent-wasm/core`) out of the
+package root, so installing docstream no longer drags a WASM Node runtime and
+native compressors into every app. `@agent-wasm/core` is now an optional peer.
+
+| 1.2 (root import) | 1.3 |
+| --- | --- |
+| `GitbookStreamdown` (ran live code + inline demos in almost-node) | Root `GitbookStreamdown` renders them as code unless you pass `liveRenderer` / `demoRuntime`. For the old behaviour: `import { GitbookStreamdown } from "@brett_lamy/docstream/playground"` and install `@agent-wasm/core`. |
+| `ReactCodePreview`, `ReactDemo`, `InlineDemoPreview`, `almostNodeDemoRuntime`, `createAlmostNodeDemoRuntime`, `createAlmostNodeFilesystem`, `createAlmostNodeWorkspace` and their option/prop types | `@brett_lamy/docstream/playground` |
+| `VizEmbed`, `VizEmbedProps` | `@brett_lamy/docstream/viz`, and install `@brett_lamy/viz-engine` (now an optional peer, no longer a dependency) |
+| `Streamdown`, `StreamdownProps` (re-export of `streamdown`) | Removed: install `streamdown` and import it directly |
+
+`createInlineDemoProject`, `createReactDemoFiles` and the `AlmostNodeFile*` data
+types stay on the root (they are plain data helpers). Math blocks now show their
+TeX source for a moment while KaTeX loads.
+
 ## Related Package
 
 Use `@brett_lamy/docstream-editor` when you need the editable TipTap experience for the same document model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"
@@ -78,23 +78,28 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/viz-engine": ">=0.2.0",
     "framer-motion": "^13.1.1",
     "gpu-lexer": "^0.0.2",
     "katex": "^0.18.5",
     "lucide-react": "^1.17.0",
     "mermaid": "^11.15.0",
     "rrweb": "2.0.0-alpha.20",
-    "streamdown": "^2.5.0",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "@agent-wasm/core": ">=0.4.0",
     "@brett_lamy/viz-engine": ">=0.2.0",
     "react": ">=18",
+    "react-dom": ">=18",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {
+    "@agent-wasm/core": {
+      "optional": true
+    },
+    "@brett_lamy/viz-engine": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     }
@@ -105,6 +110,7 @@
   },
   "devDependencies": {
     "@agent-wasm/core": "^0.4.0",
+    "@brett_lamy/viz-engine": "^0.2.1",
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.3",
     "typescript": "^5.5.4",

package/src/demo/types.ts

@@ -85,8 +85,8 @@ export interface InlineDemoRuntimeProps {
 /**
  * Renders the Preview of a `{% demo %}` block that carries its files inline and has
  * no resolver behind it. `@brett_lamy/docstream/playground` provides an almost-node
- * implementation (`createAlmostNodeDemoRuntime`), which `PlaygroundStreamdown` (the
- * package root's `GitbookStreamdown`) wires in by default.
+ * implementation (`createAlmostNodeDemoRuntime`), which that entry's `PlaygroundStreamdown`
+ * wires in by default. The package root never loads a runtime on its own.
  */
 export type InlineDemoRuntime = (props: InlineDemoRuntimeProps) => ReactNode
 

package/src/docs/DocsRenderer.tsx

@@ -1,6 +1,5 @@
-import { useContext, useId, useMemo, useState, type ReactNode } from "react"
+import { useContext, useEffect, useId, useMemo, useState, type ReactNode } from "react"
 import { motion, useReducedMotion } from "framer-motion"
-import "katex/dist/katex.min.css"
 import {
   AlertTriangle,
   CheckCircle2,
@@ -24,16 +23,41 @@ import { CopyButton } from "./copy"
 import { PillTabs, rovingKeyDown } from "./controls"
 import { DocPageActions, type DocPageActionsOptions } from "./PageActions"
 import { useSyncedTab } from "./tabs-sync"
-import { ReplayPreview, isReplayQaUrl } from "../replay"
+import { ReplayPreview } from "../replay/ReplayPreview"
+import { isReplayQaUrl } from "../replay/url"
 import { VideoEmbed } from "../video"
 import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
 import { CitationSources, InlineReference } from "./reference"
-import { renderMathToHtml } from "./math"
 
+type MathRenderer = (formula: string) => string
+let mathRenderer: MathRenderer | null = null
+let mathLoad: Promise<MathRenderer> | null = null
+function loadMathRenderer(): Promise<MathRenderer> {
+  mathLoad ??= import("./math").then((m) => (mathRenderer = m.renderMathToHtml))
+  return mathLoad
+}
+
+// KaTeX loads on first use; until then the TeX source shows in place.
 function MathBlock({ formula }: { formula: string }) {
-  return <div className="docs-math" dangerouslySetInnerHTML={{ __html: renderMathToHtml(formula) }} />
+  const [render, setRender] = useState<MathRenderer | null>(() => mathRenderer)
+  useEffect(() => {
+    if (render) return
+    let live = true
+    loadMathRenderer().then((fn) => live && setRender(() => fn), () => {})
+    return () => {
+      live = false
+    }
+  }, [render])
+  if (!render) {
+    return (
+      <div className="docs-math" data-pending="">
+        <code>{formula}</code>
+      </div>
+    )
+  }
+  return <div className="docs-math" dangerouslySetInnerHTML={{ __html: render(formula) }} />
 }
 
 export interface LivePreviewProps {
@@ -561,8 +585,8 @@ export interface DocRenderOptions {
   demoResolver?: DemoResolver
   /**
    * Runs the Preview of `{% demo %}` blocks that carry their files inline and have no
-   * resolver behind them. `PlaygroundStreamdown` (the package root's `GitbookStreamdown`)
-   * supplies an almost-node runtime by default; see `createAlmostNodeDemoRuntime`.
+   * resolver behind them. Nothing is supplied by default: pass `createAlmostNodeDemoRuntime()`
+   * from `@brett_lamy/docstream/playground` (or use its `PlaygroundStreamdown`) to run them.
    * Without one, such demos show their code with a short note.
    */
   demoRuntime?: InlineDemoRuntime

package/src/docs/math.ts

@@ -1,4 +1,7 @@
+/* KaTeX lives behind this module, which DocsRenderer loads with a dynamic import the
+   first time a page has a math block — pages without math never download KaTeX. */
 import katex from "katex"
+import "katex/dist/katex.min.css"
 
 export function renderMathToHtml(formula: string): string {
   return katex.renderToString(formula, {

package/src/index.ts

@@ -1,5 +1,7 @@
-export { PlaygroundStreamdown as GitbookStreamdown } from "./playground/PlaygroundStreamdown"
-export type { PlaygroundStreamdownProps as GitbookStreamdownProps } from "./playground/PlaygroundStreamdown"
+// The root entry never references `@agent-wasm/core` (almost-node). Live code fences and
+// inline-file demos run only when the host passes a runtime — see `@brett_lamy/docstream/playground`.
+export { GitbookStreamdown } from "./streamdown"
+export type { GitbookStreamdownProps } from "./streamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
 export type { DocRenderOptions, LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { DocPageActions } from "./docs/PageActions"
@@ -47,45 +49,27 @@ export type {
 } from "./demo"
 export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference"
 export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
-export { ReplayEmbed, ReplayPreview } from "./replay"
+export { ReplayEmbed, ReplayPreview } from "./replay/ReplayPreview"
 export type {
   ReplayEventsSource,
   ReplayEventsUrlSource,
   ReplayPageSource,
   ReplayPreviewProps,
   ReplaySource,
-} from "./replay"
-export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay"
+} from "./replay/ReplayPreview"
+export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay/url"
 export { VideoEmbed } from "./video"
 export type { VideoEmbedProps } from "./video"
-export { VizEmbed } from "./viz"
-export type { VizEmbedProps } from "./viz"
 export { OpenApiOperation } from "./openapi/OpenApiOperation"
-export {
-  InlineDemoPreview,
-  ReactCodePreview,
-  ReactDemo,
-  almostNodeDemoRuntime,
-  createAlmostNodeDemoRuntime,
-  createInlineDemoProject,
-  createReactDemoFiles,
-  createAlmostNodeFilesystem,
-  createAlmostNodeWorkspace,
-} from "./playground"
+export { createInlineDemoProject, createReactDemoFiles } from "./playground/project"
 export type {
   AlmostNodeFile,
   AlmostNodeFileContent,
   AlmostNodeFiles,
-  AlmostNodeFilesystemOptions,
-  AlmostNodeWorkspace,
-  AlmostNodeWorkspaceOptions,
-  AlmostNodeDemoRuntimeOptions,
-  InlineDemoPreviewProps,
   InlineDemoProject,
   InlineDemoProjectOptions,
-  ReactCodePreviewProps,
-  ReactDemoProps,
-} from "./playground"
+  ReactDemoFilesOptions,
+} from "./playground/project"
 export { resolveAsset, setAssetBase } from "./assets"
 export { createBundledSourceClient, createViteSourceClient, SourcePreview } from "./source"
 export type {
@@ -108,8 +92,6 @@ export {
   serializeInline,
   serializeReference,
 } from "./gitbook/inline"
-export { Streamdown } from "streamdown"
-export type { StreamdownProps } from "streamdown"
 export type * from "./gitbook/ast"
 export { PACKAGE_MANAGERS, packageManagerCommands } from "./gitbook/package-managers"
 export { flattenBlocks, flattenForPlainMarkdown } from "./gitbook/flatten"

package/src/playground/PlaygroundStreamdown.tsx

@@ -1,73 +1,40 @@
-import { useContext, useMemo } from "react"
+import { useContext } from "react"
 
-import { DocsRenderer, type DocRenderOptions, type LivePreviewRenderer, type SourceReferenceRenderer } from "../docs/DocsRenderer"
-import { parseMarkdown, trimPartialInlineToken } from "../gitbook/parse"
+import type { LivePreviewRenderer } from "../docs/DocsRenderer"
 import { DocstreamDemoRuntimeContext } from "../demo/context"
+import { GitbookStreamdown, type GitbookStreamdownProps } from "../streamdown"
 import { almostNodeDemoRuntime } from "./InlineDemoPreview"
 import { ReactCodePreview } from "./ReactCodePreview"
 
-export interface PlaygroundStreamdownProps extends DocRenderOptions {
-  children?: string
-  sourceRenderer?: SourceReferenceRenderer
-  className?: string
-  isAnimating?: boolean
-  isStreaming?: boolean
-  markdown?: string
-}
+export type PlaygroundStreamdownProps = GitbookStreamdownProps
 
 /**
- * The full renderer variant. It keeps the optional almost-node playground
- * behind an explicit import boundary; markdown-only consumers should use the
- * `@brett_lamy/docstream/streamdown` entry instead. Live code fences and
- * `{% demo %}` blocks with inline files (and no resolver) run in almost-node.
+ * A `LivePreviewRenderer` that runs `live` React/JSX/TSX code fences in almost-node.
+ * Pass it as `liveRenderer` to the root `GitbookStreamdown` / `DocsRenderer` (or the editor).
  */
-export function PlaygroundStreamdown({
-  children,
-  className,
-  isAnimating,
-  isStreaming = false,
-  markdown,
-  sourceRenderer,
-  demoResolver,
-  demoRuntime,
-  demoDependencies,
-  pageActions,
-}: PlaygroundStreamdownProps) {
-  const content = markdown ?? children ?? ""
-  // Inline-file demos run in almost-node unless the host (or an outer renderer) chose a runtime.
-  const inheritedRuntime = useContext(DocstreamDemoRuntimeContext).runtime
-  const runtime = demoRuntime ?? inheritedRuntime ?? almostNodeDemoRuntime
-  const doc = useMemo(
-    () => parseMarkdown(isStreaming ? trimPartialInlineToken(content) : content),
-    [content, isStreaming]
-  )
-  const liveRenderer: LivePreviewRenderer = ({ files, entry, title, collapsedCodeLines, expandedCodeLines }) => (
-    <ReactCodePreview
-      files={files}
-      entry={entry}
-      title={title}
-      collapsedCodeLines={collapsedCodeLines}
-      expandedCodeLines={expandedCodeLines}
-    />
-  )
+export const almostNodeLiveRenderer: LivePreviewRenderer = ({ files, entry, title, collapsedCodeLines, expandedCodeLines }) => (
+  <ReactCodePreview
+    files={files}
+    entry={entry}
+    title={title}
+    collapsedCodeLines={collapsedCodeLines}
+    expandedCodeLines={expandedCodeLines}
+  />
+)
 
+/**
+ * `GitbookStreamdown` with the almost-node playground wired in: live code fences and
+ * `{% demo %}` blocks with inline files (and no resolver) run in almost-node
+ * (`@agent-wasm/core`, an optional peer dependency — install it to use this entry).
+ * Explicit `liveRenderer` / `demoRuntime` props (or an outer runtime context) still win.
+ */
+export function PlaygroundStreamdown({ liveRenderer, demoRuntime, ...props }: PlaygroundStreamdownProps) {
+  const inheritedRuntime = useContext(DocstreamDemoRuntimeContext).runtime
   return (
-    <div
-      aria-busy={isAnimating ?? isStreaming}
-      className={className}
-      data-docstream=""
-      data-streaming={isStreaming ? "" : undefined}
-    >
-      <DocsRenderer
-        doc={doc}
-        markdown={content}
-        liveRenderer={liveRenderer}
-        sourceRenderer={sourceRenderer}
-        demoResolver={demoResolver}
-        demoRuntime={runtime}
-        demoDependencies={demoDependencies}
-        pageActions={isStreaming ? false : pageActions}
-      />
-    </div>
+    <GitbookStreamdown
+      {...props}
+      liveRenderer={liveRenderer ?? almostNodeLiveRenderer}
+      demoRuntime={demoRuntime ?? inheritedRuntime ?? almostNodeDemoRuntime}
+    />
   )
 }

package/src/playground/filesystem.ts

@@ -1,20 +1,13 @@
 import type { ContainerInstance, ContainerOptions, VirtualFS } from "@agent-wasm/core"
+import {
+  normalizeAlmostNodeFiles,
+  normalizeAlmostNodePath,
+  type AlmostNodeFileContent,
+  type AlmostNodeFiles,
+  type AlmostNodeFilesystemOptions,
+} from "./project"
 
-export type AlmostNodeFileContent = string | Uint8Array
-
-export interface AlmostNodeFile {
-  path: string
-  content: AlmostNodeFileContent
-}
-
-export type AlmostNodeFiles =
-  | Readonly<Record<string, AlmostNodeFileContent>>
-  | readonly AlmostNodeFile[]
-
-export interface AlmostNodeFilesystemOptions {
-  /** Prefix for relative file paths. Defaults to the virtual root. */
-  root?: string
-}
+export * from "./project"
 
 export interface AlmostNodeWorkspaceOptions extends Omit<ContainerOptions, "cwd"> {
   /** Project root used as the container cwd and Vite root. */
@@ -44,49 +37,6 @@ async function loadAlmostNode(): Promise<AlmostNodeModule> {
   }
 }
 
-export function normalizeAlmostNodePath(path: string, root = "/"): string {
-  const normalizedRoot = normalizeRoot(root)
-  const source = path.replaceAll("\\", "/")
-  const absolute = source.startsWith("/") ? source : `${normalizedRoot}/${source}`
-  const result = normalizeAbsolutePath(absolute)
-
-  if (normalizedRoot !== "/" && result !== normalizedRoot && !result.startsWith(`${normalizedRoot}/`)) {
-    throw new Error(`File path escapes the almost-node root: ${path}`)
-  }
-  return result
-}
-
-function normalizeAbsolutePath(path: string): string {
-  const parts: string[] = []
-
-  for (const part of path.split("/")) {
-    if (!part || part === ".") continue
-    if (part === "..") {
-      if (parts.length > 0) parts.pop()
-      continue
-    }
-    if (part.includes("\0")) throw new Error("almost-node file paths cannot contain null bytes")
-    parts.push(part)
-  }
-
-  const result = `/${parts.join("/")}`
-  return result === "" ? "/" : result
-}
-
-export function normalizeAlmostNodeFiles(files: AlmostNodeFiles): AlmostNodeFile[] {
-  if (Array.isArray(files)) return files.map((file) => ({ ...file }))
-  return Object.entries(files).map(([path, content]) => ({ path, content }))
-}
-
-export function toAlmostNodeFileMap(files: AlmostNodeFiles): Record<string, AlmostNodeFileContent> {
-  return Object.fromEntries(normalizeAlmostNodeFiles(files).map(({ path, content }) => [path, content]))
-}
-
-function normalizeRoot(root: string): string {
-  const normalized = normalizeAbsolutePath(root.replaceAll("\\", "/"))
-  return normalized === "/" ? normalized : normalized.replace(/\/$/, "")
-}
-
 function parentDirectory(path: string): string {
   const index = path.lastIndexOf("/")
   return index <= 0 ? "/" : path.slice(0, index)
@@ -110,7 +60,7 @@ export async function createAlmostNodeFilesystem(
   options: AlmostNodeFilesystemOptions = {},
 ): Promise<VirtualFS> {
   const { VirtualFS } = await loadAlmostNode()
-  const root = normalizeRoot(options.root ?? "/")
+  const root = normalizeAlmostNodePath(options.root ?? "/")
   const vfs = new VirtualFS()
   writeFilesToVfs(vfs, files, root)
   return vfs
@@ -125,7 +75,7 @@ export async function createAlmostNodeWorkspace(
   options: AlmostNodeWorkspaceOptions = {},
 ): Promise<AlmostNodeWorkspace> {
   const { root: requestedRoot, ...containerOptions } = options
-  const root = normalizeRoot(requestedRoot ?? "/")
+  const root = normalizeAlmostNodePath(requestedRoot ?? "/")
   const { createContainer } = await loadAlmostNode()
   const container = createContainer({ ...containerOptions, cwd: root })
 
@@ -152,133 +102,3 @@ export async function createAlmostNodeWorkspace(
   }
 }
 
-export interface ReactDemoFilesOptions {
-  entry?: string
-  /** Extra npm dependencies for the generated package.json (ignored when the files bring one). */
-  dependencies?: Record<string, string>
-}
-
-/**
- * Add the tiny Vite/React shell needed by a file map that only contains source
- * files. Existing package.json and index.html files are always respected.
- */
-export function createReactDemoFiles(
-  files: AlmostNodeFiles,
-  options: ReactDemoFilesOptions = {},
-): Record<string, AlmostNodeFileContent> {
-  const map = toAlmostNodeFileMap(files)
-  const entry = normalizeAlmostNodePath(options.entry ?? "/src/main.jsx")
-  const has = (candidate: string) => Object.keys(map).some((path) => normalizeAlmostNodePath(path) === candidate)
-
-  if (!has("/package.json")) {
-    map["/package.json"] = JSON.stringify(
-      {
-        name: "docstream-react-demo",
-        private: true,
-        type: "module",
-        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0", ...options.dependencies },
-      },
-      null,
-      2,
-    )
-  }
-
-  if (!has("/index.html")) {
-    const entryUrl = `.${entry}`
-    map["/index.html"] = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Docstream React demo</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="${entryUrl}"></script>
-  </body>
-</html>
-`
-  }
-
-  return map
-}
-
-export interface InlineDemoProjectOptions {
-  /** Entry file among `files` (relative path). Defaults to the first file. */
-  entry?: string
-  /** Extra npm dependencies (merged over a `package.json` among the files, if any). */
-  dependencies?: Record<string, string>
-}
-
-export interface InlineDemoProject {
-  /** Complete almost-node project: the demo under `/src/demo/`, a wrapper entry, package.json, index.html. */
-  files: Record<string, AlmostNodeFileContent>
-  /** The Vite entry to hand to `createReactDemoFiles` / `ReactDemo`. */
-  entry: string
-  /** Whether the entry is wrapped (so `?variant=` reaches the component as its `variant` prop). */
-  wrapped: boolean
-}
-
-/** Folder the inline demo's files are written to inside the almost-node project. */
-export const INLINE_DEMO_DIR = "/src/demo"
-const WRAPPER_ENTRY = "/src/__docstream_demo_entry.js"
-
-function selfMounting(source: string): boolean {
-  return /\bcreateRoot\s*\(|\bReactDOM\.render\s*\(|\bhydrateRoot\s*\(/.test(source)
-}
-
-/**
- * Turn a `{% demo %}` block's inline files into a runnable almost-node project.
- *
- * The files go under `/src/demo/` (relative imports between them keep working). A tiny
- * wrapper entry imports the entry file, takes its default export (or the first exported
- * function), and renders it with `variant` read from the page's `?variant=` query — so
- * switching variants just reloads the iframe, no new Vite server. An entry that mounts
- * itself (`createRoot(…)`) is used directly instead, and receives no `variant`.
- *
- * A `package.json` among the files contributes its `dependencies`; `options.dependencies`
- * are merged over them. Bare imports resolve through almost-node (installed packages, else
- * esm.sh at the major version declared here), with `react`/`react-dom` provided.
- */
-export function createInlineDemoProject(
-  files: readonly { path: string; content: string }[],
-  options: InlineDemoProjectOptions = {},
-): InlineDemoProject {
-  const map: Record<string, AlmostNodeFileContent> = {}
-  let packageDeps: Record<string, string> = {}
-  for (const file of files) {
-    const relative = file.path.replace(/^\.?\/+/, "")
-    if (relative === "package.json") {
-      try {
-        const pkg = JSON.parse(file.content) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
-        packageDeps = { ...pkg.devDependencies, ...pkg.dependencies }
-      } catch {
-        // Not JSON: keep it as a plain file.
-      }
-    }
-    map[normalizeAlmostNodePath(relative, INLINE_DEMO_DIR)] = file.content
-  }
-  const entryFile = files.find((f) => f.path === options.entry) ?? files[0]
-  if (!entryFile) throw new Error("An inline demo needs at least one file")
-  const entryPath = normalizeAlmostNodePath(entryFile.path.replace(/^\.?\/+/, ""), INLINE_DEMO_DIR)
-  const dependencies = { ...packageDeps, ...options.dependencies }
-  const wrapped = !selfMounting(entryFile.content)
-  if (wrapped) {
-    const specifier = `.${entryPath.slice("/src".length)}`
-    map[WRAPPER_ENTRY] = `import { createElement } from "react"
-import { createRoot } from "react-dom/client"
-import * as demo from ${JSON.stringify(specifier)}
-
-const Component = demo.default ?? Object.values(demo).find((value) => typeof value === "function")
-const variant = new URLSearchParams(location.search).get("variant")
-const props = variant === null ? {} : { variant }
-createRoot(document.getElementById("root")).render(
-  Component
-    ? createElement(Component, props)
-    : createElement("pre", null, ${JSON.stringify(`${entryFile.path} has no default export to render.`)}),
-)
-`
-  }
-  const entry = wrapped ? WRAPPER_ENTRY : entryPath
-  return { files: createReactDemoFiles(map, { entry, dependencies }), entry, wrapped }
-}

package/src/playground/index.ts

@@ -1,3 +1,7 @@
+/* `@brett_lamy/docstream/playground` — the only entry that touches almost-node
+   (`@agent-wasm/core`, an optional peer dependency). Install it to use anything here. */
+export { PlaygroundStreamdown, PlaygroundStreamdown as GitbookStreamdown, almostNodeLiveRenderer } from "./PlaygroundStreamdown"
+export type { PlaygroundStreamdownProps, PlaygroundStreamdownProps as GitbookStreamdownProps } from "./PlaygroundStreamdown"
 export { ReactCodePreview, ReactDemo, useAlmostNodeServer } from "./ReactCodePreview"
 export type { AlmostNodeServerOptions, AlmostNodeServerState, PreviewState, ReactCodePreviewProps, ReactDemoProps } from "./ReactCodePreview"
 export { InlineDemoPreview, almostNodeDemoRuntime, createAlmostNodeDemoRuntime } from "./InlineDemoPreview"

package/src/playground/project.ts

@@ -0,0 +1,194 @@
+/* Pure, runtime-free helpers for describing an almost-node project as a file map.
+   Nothing here imports `@agent-wasm/core`, so these are safe to use from the package
+   root; the runtime itself lives in ./filesystem (the `/playground` entry). */
+
+export type AlmostNodeFileContent = string | Uint8Array
+
+export interface AlmostNodeFile {
+  path: string
+  content: AlmostNodeFileContent
+}
+
+export type AlmostNodeFiles =
+  | Readonly<Record<string, AlmostNodeFileContent>>
+  | readonly AlmostNodeFile[]
+
+export interface AlmostNodeFilesystemOptions {
+  /** Prefix for relative file paths. Defaults to the virtual root. */
+  root?: string
+}
+
+export function normalizeAlmostNodePath(path: string, root = "/"): string {
+  const normalizedRoot = normalizeRoot(root)
+  const source = path.replaceAll("\\", "/")
+  const absolute = source.startsWith("/") ? source : `${normalizedRoot}/${source}`
+  const result = normalizeAbsolutePath(absolute)
+
+  if (normalizedRoot !== "/" && result !== normalizedRoot && !result.startsWith(`${normalizedRoot}/`)) {
+    throw new Error(`File path escapes the almost-node root: ${path}`)
+  }
+  return result
+}
+
+function normalizeAbsolutePath(path: string): string {
+  const parts: string[] = []
+
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") {
+      if (parts.length > 0) parts.pop()
+      continue
+    }
+    if (part.includes("\0")) throw new Error("almost-node file paths cannot contain null bytes")
+    parts.push(part)
+  }
+
+  const result = `/${parts.join("/")}`
+  return result === "" ? "/" : result
+}
+
+export function normalizeAlmostNodeFiles(files: AlmostNodeFiles): AlmostNodeFile[] {
+  if (Array.isArray(files)) return files.map((file) => ({ ...file }))
+  return Object.entries(files).map(([path, content]) => ({ path, content }))
+}
+
+export function toAlmostNodeFileMap(files: AlmostNodeFiles): Record<string, AlmostNodeFileContent> {
+  return Object.fromEntries(normalizeAlmostNodeFiles(files).map(({ path, content }) => [path, content]))
+}
+
+function normalizeRoot(root: string): string {
+  const normalized = normalizeAbsolutePath(root.replaceAll("\\", "/"))
+  return normalized === "/" ? normalized : normalized.replace(/\/$/, "")
+}
+
+
+export interface ReactDemoFilesOptions {
+  entry?: string
+  /** Extra npm dependencies for the generated package.json (ignored when the files bring one). */
+  dependencies?: Record<string, string>
+}
+
+/**
+ * Add the tiny Vite/React shell needed by a file map that only contains source
+ * files. Existing package.json and index.html files are always respected.
+ */
+export function createReactDemoFiles(
+  files: AlmostNodeFiles,
+  options: ReactDemoFilesOptions = {},
+): Record<string, AlmostNodeFileContent> {
+  const map = toAlmostNodeFileMap(files)
+  const entry = normalizeAlmostNodePath(options.entry ?? "/src/main.jsx")
+  const has = (candidate: string) => Object.keys(map).some((path) => normalizeAlmostNodePath(path) === candidate)
+
+  if (!has("/package.json")) {
+    map["/package.json"] = JSON.stringify(
+      {
+        name: "docstream-react-demo",
+        private: true,
+        type: "module",
+        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0", ...options.dependencies },
+      },
+      null,
+      2,
+    )
+  }
+
+  if (!has("/index.html")) {
+    const entryUrl = `.${entry}`
+    map["/index.html"] = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Docstream React demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="${entryUrl}"></script>
+  </body>
+</html>
+`
+  }
+
+  return map
+}
+
+export interface InlineDemoProjectOptions {
+  /** Entry file among `files` (relative path). Defaults to the first file. */
+  entry?: string
+  /** Extra npm dependencies (merged over a `package.json` among the files, if any). */
+  dependencies?: Record<string, string>
+}
+
+export interface InlineDemoProject {
+  /** Complete almost-node project: the demo under `/src/demo/`, a wrapper entry, package.json, index.html. */
+  files: Record<string, AlmostNodeFileContent>
+  /** The Vite entry to hand to `createReactDemoFiles` / `ReactDemo`. */
+  entry: string
+  /** Whether the entry is wrapped (so `?variant=` reaches the component as its `variant` prop). */
+  wrapped: boolean
+}
+
+/** Folder the inline demo's files are written to inside the almost-node project. */
+export const INLINE_DEMO_DIR = "/src/demo"
+const WRAPPER_ENTRY = "/src/__docstream_demo_entry.js"
+
+function selfMounting(source: string): boolean {
+  return /\bcreateRoot\s*\(|\bReactDOM\.render\s*\(|\bhydrateRoot\s*\(/.test(source)
+}
+
+/**
+ * Turn a `{% demo %}` block's inline files into a runnable almost-node project.
+ *
+ * The files go under `/src/demo/` (relative imports between them keep working). A tiny
+ * wrapper entry imports the entry file, takes its default export (or the first exported
+ * function), and renders it with `variant` read from the page's `?variant=` query — so
+ * switching variants just reloads the iframe, no new Vite server. An entry that mounts
+ * itself (`createRoot(…)`) is used directly instead, and receives no `variant`.
+ *
+ * A `package.json` among the files contributes its `dependencies`; `options.dependencies`
+ * are merged over them. Bare imports resolve through almost-node (installed packages, else
+ * esm.sh at the major version declared here), with `react`/`react-dom` provided.
+ */
+export function createInlineDemoProject(
+  files: readonly { path: string; content: string }[],
+  options: InlineDemoProjectOptions = {},
+): InlineDemoProject {
+  const map: Record<string, AlmostNodeFileContent> = {}
+  let packageDeps: Record<string, string> = {}
+  for (const file of files) {
+    const relative = file.path.replace(/^\.?\/+/, "")
+    if (relative === "package.json") {
+      try {
+        const pkg = JSON.parse(file.content) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        packageDeps = { ...pkg.devDependencies, ...pkg.dependencies }
+      } catch {
+        // Not JSON: keep it as a plain file.
+      }
+    }
+    map[normalizeAlmostNodePath(relative, INLINE_DEMO_DIR)] = file.content
+  }
+  const entryFile = files.find((f) => f.path === options.entry) ?? files[0]
+  if (!entryFile) throw new Error("An inline demo needs at least one file")
+  const entryPath = normalizeAlmostNodePath(entryFile.path.replace(/^\.?\/+/, ""), INLINE_DEMO_DIR)
+  const dependencies = { ...packageDeps, ...options.dependencies }
+  const wrapped = !selfMounting(entryFile.content)
+  if (wrapped) {
+    const specifier = `.${entryPath.slice("/src".length)}`
+    map[WRAPPER_ENTRY] = `import { createElement } from "react"
+import { createRoot } from "react-dom/client"
+import * as demo from ${JSON.stringify(specifier)}
+
+const Component = demo.default ?? Object.values(demo).find((value) => typeof value === "function")
+const variant = new URLSearchParams(location.search).get("variant")
+const props = variant === null ? {} : { variant }
+createRoot(document.getElementById("root")).render(
+  Component
+    ? createElement(Component, props)
+    : createElement("pre", null, ${JSON.stringify(`${entryFile.path} has no default export to render.`)}),
+)
+`
+  }
+  const entry = wrapped ? WRAPPER_ENTRY : entryPath
+  return { files: createReactDemoFiles(map, { entry, dependencies }), entry, wrapped }
+}

package/src/replay/NativeReplay.tsx

@@ -0,0 +1,236 @@
+/* The rrweb player. Loaded on demand by ReplayPreview, so pages that only embed Loop QA
+   iframes (the markdown `{% embed %}` case) never download rrweb or its stylesheet. */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { EventType, Replayer } from 'rrweb';
+import type { eventWithTime } from 'rrweb';
+import { sanitizeReplayEvent } from './sanitize';
+import 'rrweb/dist/style.css';
+
+const DEFAULT_SPEEDS = [0.5, 1, 2, 4, 8];
+const SKIP_IDLE_THRESHOLD_MS = 5_000;
+
+export default function NativeReplay({
+  events,
+  autoplay = false,
+  loop = false,
+  speeds = DEFAULT_SPEEDS,
+}: {
+  events: eventWithTime[];
+  autoplay?: boolean;
+  loop?: boolean;
+  speeds?: number[];
+}) {
+  const stageRef = useRef<HTMLDivElement>(null);
+  const playerRef = useRef<HTMLDivElement>(null);
+  const replayerRef = useRef<Replayer | null>(null);
+  const fedCountRef = useRef(0);
+  const [playing, setPlaying] = useState(false);
+  const [speed, setSpeed] = useState(1);
+  const [dims, setDims] = useState<{ w: number; h: number } | null>(null);
+  const [scale, setScale] = useState(1);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [totalTime, setTotalTime] = useState(0);
+  const [scrubbing, setScrubbing] = useState<number | null>(null);
+  const speedRef = useRef(speed);
+  const loopRef = useRef(loop);
+  const autoplayRef = useRef(autoplay);
+
+  const prepared = useMemo(
+    () => events.map((event) => sanitizeReplayEvent(event)).sort((a, b) => a.timestamp - b.timestamp),
+    [events],
+  );
+  const hasSnapshot = prepared.some((event) => event.type === EventType.FullSnapshot);
+
+  useEffect(() => {
+    if (replayerRef.current && prepared.length < fedCountRef.current) {
+      try {
+        replayerRef.current.destroy();
+      } catch {
+        // Ignore stale player teardown.
+      }
+      replayerRef.current = null;
+      fedCountRef.current = 0;
+    }
+    if (!hasSnapshot || !playerRef.current) return;
+
+    if (!replayerRef.current) {
+      const replayer = new Replayer(prepared, {
+        root: playerRef.current,
+        liveMode: false,
+        speed: speedRef.current,
+        skipInactive: true,
+        inactivePeriodThreshold: SKIP_IDLE_THRESHOLD_MS,
+        mouseTail: false,
+        showWarning: false,
+      });
+      replayer.on('resize', (payload) => {
+        const size = payload as { width?: number; height?: number };
+        if (size.width && size.height) setDims({ w: size.width, h: size.height });
+      });
+      replayer.on('finish', () => {
+        if (loopRef.current) {
+          replayer.play(0);
+          setPlaying(true);
+        } else {
+          setPlaying(false);
+        }
+      });
+      replayer.pause(0);
+      replayerRef.current = replayer;
+      fedCountRef.current = prepared.length;
+      if (autoplayRef.current) {
+        replayer.play(0);
+        setPlaying(true);
+      }
+    } else if (prepared.length > fedCountRef.current) {
+      for (let i = fedCountRef.current; i < prepared.length; i++) {
+        replayerRef.current.addEvent(prepared[i]!);
+      }
+      fedCountRef.current = prepared.length;
+    }
+  }, [hasSnapshot, prepared]);
+
+  useEffect(
+    () => () => {
+      try {
+        replayerRef.current?.destroy();
+      } catch {
+        // Ignore unmount teardown errors from rrweb.
+      }
+      replayerRef.current = null;
+      fedCountRef.current = 0;
+    },
+    [],
+  );
+
+  useEffect(() => {
+    speedRef.current = speed;
+    replayerRef.current?.setConfig({ speed });
+  }, [speed]);
+
+  useEffect(() => {
+    loopRef.current = loop;
+  }, [loop]);
+
+  useEffect(() => {
+    autoplayRef.current = autoplay;
+  }, [autoplay]);
+
+  const recalcScale = useCallback(() => {
+    if (!dims || !stageRef.current || dims.w <= 0) return;
+    setScale(Math.min(1, stageRef.current.clientWidth / dims.w));
+  }, [dims]);
+
+  useEffect(() => {
+    recalcScale();
+    window.addEventListener('resize', recalcScale);
+    return () => window.removeEventListener('resize', recalcScale);
+  }, [recalcScale]);
+
+  useEffect(() => {
+    if (!hasSnapshot) return;
+    const interval = window.setInterval(() => {
+      const replayer = replayerRef.current;
+      if (!replayer) return;
+      try {
+        const total = replayer.getMetaData().totalTime;
+        const current = Math.max(0, Math.min(replayer.getCurrentTime(), total));
+        setTotalTime(total);
+        if (scrubbing === null) setCurrentTime(current);
+      } catch {
+        // rrweb can briefly be unready while a full snapshot is applied.
+      }
+    }, 200);
+    return () => window.clearInterval(interval);
+  }, [hasSnapshot, scrubbing]);
+
+  const seek = useCallback(
+    (value: number) => {
+      const replayer = replayerRef.current;
+      if (!replayer) return;
+      const next = Math.max(0, Math.min(value, totalTime));
+      if (playing) replayer.play(next);
+      else replayer.pause(next);
+      setCurrentTime(next);
+    },
+    [playing, totalTime],
+  );
+
+  const toggle = () => {
+    const replayer = replayerRef.current;
+    if (!replayer) return;
+    if (playing) {
+      replayer.pause();
+      setPlaying(false);
+      return;
+    }
+    let offset = currentTime;
+    try {
+      if (offset >= replayer.getMetaData().totalTime - 1) offset = 0;
+    } catch {
+      offset = 0;
+    }
+    replayer.play(offset);
+    setPlaying(true);
+  };
+
+  const restart = () => {
+    replayerRef.current?.play(0);
+    setCurrentTime(0);
+    setPlaying(true);
+  };
+
+  if (!hasSnapshot) {
+    return (
+      <div className="replay-preview__empty">
+        {events.length ? `Captured ${events.length} events, but no full DOM snapshot is available.` : 'Replay data is not available yet.'}
+      </div>
+    );
+  }
+
+  return (
+    <div className="replay-preview__native">
+      <div
+        ref={stageRef}
+        className="replay-preview__stage"
+        style={dims ? { height: Math.max(1, Math.round(dims.h * scale)) } : undefined}
+      >
+        <div
+          className="replay-preview__scaler"
+          style={{ transform: `scale(${scale})`, transformOrigin: 'top left' }}
+        >
+          <div ref={playerRef} className="replay-preview__player" aria-hidden="true" />
+        </div>
+      </div>
+      <div className="replay-preview__controls">
+        <button type="button" onClick={toggle} aria-label={playing ? 'Pause replay' : 'Play replay'}>
+          {playing ? 'Pause' : 'Play'}
+        </button>
+        <button type="button" onClick={restart} aria-label="Restart replay">
+          Restart
+        </button>
+        <input
+          type="range"
+          min={0}
+          max={Math.max(totalTime, 1)}
+          step={1}
+          value={scrubbing ?? currentTime}
+          onChange={(event) => setScrubbing(Number(event.target.value))}
+          onPointerUp={(event) => {
+            seek(Number((event.currentTarget as HTMLInputElement).value));
+            setScrubbing(null);
+          }}
+          aria-label="Replay position"
+        />
+        <select value={speed} onChange={(event) => setSpeed(Number(event.target.value))} aria-label="Replay speed">
+          {speeds.map((option) => (
+            <option key={option} value={option}>
+              {option}×
+            </option>
+          ))}
+        </select>
+      </div>
+    </div>
+  );
+}
+

package/src/replay/ReplayPreview.tsx

@@ -1,9 +1,6 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { EventType, Replayer } from 'rrweb';
+import { Suspense, lazy, useEffect, useState } from 'react';
 import type { eventWithTime } from 'rrweb';
 import { normalizeReplayEmbedUrl } from './url';
-import { sanitizeReplayEvent } from './sanitize';
-import 'rrweb/dist/style.css';
 import './styles.css';
 
 export interface ReplayPageSource {
@@ -45,7 +42,6 @@ export interface ReplayPreviewProps {
 }
 
 const DEFAULT_SPEEDS = [0.5, 1, 2, 4, 8];
-const SKIP_IDLE_THRESHOLD_MS = 5_000;
 
 function sourcePage(source: ReplaySource): ReplayPageSource | null {
   if (typeof source === 'string') return { kind: 'url', url: source };
@@ -86,228 +82,14 @@ function ReplayFrame({ source, title }: { source: ReplayPageSource; title?: stri
   );
 }
 
-function NativeReplay({
-  events,
-  autoplay = false,
-  loop = false,
-  speeds = DEFAULT_SPEEDS,
-}: {
-  events: eventWithTime[];
-  autoplay?: boolean;
-  loop?: boolean;
-  speeds?: number[];
-}) {
-  const stageRef = useRef<HTMLDivElement>(null);
-  const playerRef = useRef<HTMLDivElement>(null);
-  const replayerRef = useRef<Replayer | null>(null);
-  const fedCountRef = useRef(0);
-  const [playing, setPlaying] = useState(false);
-  const [speed, setSpeed] = useState(1);
-  const [dims, setDims] = useState<{ w: number; h: number } | null>(null);
-  const [scale, setScale] = useState(1);
-  const [currentTime, setCurrentTime] = useState(0);
-  const [totalTime, setTotalTime] = useState(0);
-  const [scrubbing, setScrubbing] = useState<number | null>(null);
-  const speedRef = useRef(speed);
-  const loopRef = useRef(loop);
-  const autoplayRef = useRef(autoplay);
-
-  const prepared = useMemo(
-    () => events.map((event) => sanitizeReplayEvent(event)).sort((a, b) => a.timestamp - b.timestamp),
-    [events],
-  );
-  const hasSnapshot = prepared.some((event) => event.type === EventType.FullSnapshot);
-
-  useEffect(() => {
-    if (replayerRef.current && prepared.length < fedCountRef.current) {
-      try {
-        replayerRef.current.destroy();
-      } catch {
-        // Ignore stale player teardown.
-      }
-      replayerRef.current = null;
-      fedCountRef.current = 0;
-    }
-    if (!hasSnapshot || !playerRef.current) return;
-
-    if (!replayerRef.current) {
-      const replayer = new Replayer(prepared, {
-        root: playerRef.current,
-        liveMode: false,
-        speed: speedRef.current,
-        skipInactive: true,
-        inactivePeriodThreshold: SKIP_IDLE_THRESHOLD_MS,
-        mouseTail: false,
-        showWarning: false,
-      });
-      replayer.on('resize', (payload) => {
-        const size = payload as { width?: number; height?: number };
-        if (size.width && size.height) setDims({ w: size.width, h: size.height });
-      });
-      replayer.on('finish', () => {
-        if (loopRef.current) {
-          replayer.play(0);
-          setPlaying(true);
-        } else {
-          setPlaying(false);
-        }
-      });
-      replayer.pause(0);
-      replayerRef.current = replayer;
-      fedCountRef.current = prepared.length;
-      if (autoplayRef.current) {
-        replayer.play(0);
-        setPlaying(true);
-      }
-    } else if (prepared.length > fedCountRef.current) {
-      for (let i = fedCountRef.current; i < prepared.length; i++) {
-        replayerRef.current.addEvent(prepared[i]!);
-      }
-      fedCountRef.current = prepared.length;
-    }
-  }, [hasSnapshot, prepared]);
-
-  useEffect(
-    () => () => {
-      try {
-        replayerRef.current?.destroy();
-      } catch {
-        // Ignore unmount teardown errors from rrweb.
-      }
-      replayerRef.current = null;
-      fedCountRef.current = 0;
-    },
-    [],
-  );
-
-  useEffect(() => {
-    speedRef.current = speed;
-    replayerRef.current?.setConfig({ speed });
-  }, [speed]);
-
-  useEffect(() => {
-    loopRef.current = loop;
-  }, [loop]);
-
-  useEffect(() => {
-    autoplayRef.current = autoplay;
-  }, [autoplay]);
-
-  const recalcScale = useCallback(() => {
-    if (!dims || !stageRef.current || dims.w <= 0) return;
-    setScale(Math.min(1, stageRef.current.clientWidth / dims.w));
-  }, [dims]);
-
-  useEffect(() => {
-    recalcScale();
-    window.addEventListener('resize', recalcScale);
-    return () => window.removeEventListener('resize', recalcScale);
-  }, [recalcScale]);
-
-  useEffect(() => {
-    if (!hasSnapshot) return;
-    const interval = window.setInterval(() => {
-      const replayer = replayerRef.current;
-      if (!replayer) return;
-      try {
-        const total = replayer.getMetaData().totalTime;
-        const current = Math.max(0, Math.min(replayer.getCurrentTime(), total));
-        setTotalTime(total);
-        if (scrubbing === null) setCurrentTime(current);
-      } catch {
-        // rrweb can briefly be unready while a full snapshot is applied.
-      }
-    }, 200);
-    return () => window.clearInterval(interval);
-  }, [hasSnapshot, scrubbing]);
-
-  const seek = useCallback(
-    (value: number) => {
-      const replayer = replayerRef.current;
-      if (!replayer) return;
-      const next = Math.max(0, Math.min(value, totalTime));
-      if (playing) replayer.play(next);
-      else replayer.pause(next);
-      setCurrentTime(next);
-    },
-    [playing, totalTime],
-  );
-
-  const toggle = () => {
-    const replayer = replayerRef.current;
-    if (!replayer) return;
-    if (playing) {
-      replayer.pause();
-      setPlaying(false);
-      return;
-    }
-    let offset = currentTime;
-    try {
-      if (offset >= replayer.getMetaData().totalTime - 1) offset = 0;
-    } catch {
-      offset = 0;
-    }
-    replayer.play(offset);
-    setPlaying(true);
-  };
-
-  const restart = () => {
-    replayerRef.current?.play(0);
-    setCurrentTime(0);
-    setPlaying(true);
-  };
-
-  if (!hasSnapshot) {
-    return (
-      <div className="replay-preview__empty">
-        {events.length ? `Captured ${events.length} events, but no full DOM snapshot is available.` : 'Replay data is not available yet.'}
-      </div>
-    );
-  }
+// rrweb (and its stylesheet) load on first use of an event-based source.
+const LazyNativeReplay = lazy(() => import('./NativeReplay'));
 
+function NativeReplay(props: { events: eventWithTime[]; autoplay?: boolean; loop?: boolean; speeds?: number[] }) {
   return (
-    <div className="replay-preview__native">
-      <div
-        ref={stageRef}
-        className="replay-preview__stage"
-        style={dims ? { height: Math.max(1, Math.round(dims.h * scale)) } : undefined}
-      >
-        <div
-          className="replay-preview__scaler"
-          style={{ transform: `scale(${scale})`, transformOrigin: 'top left' }}
-        >
-          <div ref={playerRef} className="replay-preview__player" aria-hidden="true" />
-        </div>
-      </div>
-      <div className="replay-preview__controls">
-        <button type="button" onClick={toggle} aria-label={playing ? 'Pause replay' : 'Play replay'}>
-          {playing ? 'Pause' : 'Play'}
-        </button>
-        <button type="button" onClick={restart} aria-label="Restart replay">
-          Restart
-        </button>
-        <input
-          type="range"
-          min={0}
-          max={Math.max(totalTime, 1)}
-          step={1}
-          value={scrubbing ?? currentTime}
-          onChange={(event) => setScrubbing(Number(event.target.value))}
-          onPointerUp={(event) => {
-            seek(Number((event.currentTarget as HTMLInputElement).value));
-            setScrubbing(null);
-          }}
-          aria-label="Replay position"
-        />
-        <select value={speed} onChange={(event) => setSpeed(Number(event.target.value))} aria-label="Replay speed">
-          {speeds.map((option) => (
-            <option key={option} value={option}>
-              {option}×
-            </option>
-          ))}
-        </select>
-      </div>
-    </div>
+    <Suspense fallback={<div className="replay-preview__empty">Loading replay…</div>}>
+      <LazyNativeReplay {...props} />
+    </Suspense>
   );
 }
 

package/src/styles.css

@@ -1,4 +1,3 @@
-@import "streamdown/styles.css";
 
 [data-docstream],
 .docs-article {