@brett_lamy/docstream 1.2.3 → 1.3.0

package/README.md

@@ -8,8 +8,12 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 
 - React renderer for GitBook-style markdown blocks.
 - Streaming-friendly `GitbookStreamdown` component inspired by `vercel/streamdown`.
-- Parser and serializer for round-tripping supported GitBook syntax.
-- Syntax-highlighted code blocks through `lowlight`.
+- Parser and serializer for round-tripping supported GitBook syntax — byte-for-byte: `serializeMarkdown(parseMarkdown(md)) === md`
+  for Markdown and GitBook pages (the author's emphasis markers, escapes, link forms and reference definitions,
+  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 `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.
@@ -19,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
 
@@ -46,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
@@ -363,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" }} />
@@ -542,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
@@ -619,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.3",
+  "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/markdown.ts

@@ -177,7 +177,7 @@ function inlineDemoKeepingTag(tagLine: string, node: DemoNode, files: DemoFile[]
   const next = inlineDemoNode(node, files, meta)
   const out = serializeBlocks([next])
   const bare = (n: DemoNode): DemoNode => {
-    const { files: _files, open: _open, ...rest } = n
+    const { files: _files, open: _open, raw: _raw, ...rest } = n
     return rest
   }
   if (serializeBlocks([bare(next)]) !== serializeBlocks([bare(node)])) return out

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 {
@@ -52,8 +76,12 @@ function InlineText({ nodes }: { nodes: Inline[] }) {
   return (
     <>
       {nodes.map((n, i) => {
-        if (n.type === "reference") return <InlineReference key={i} node={n} />
-        if (n.type === "image") {
+        const emphasized = !!(n.bold || n.italic || n.strike)
+        let el: ReactNode
+        if (n.type === "reference") {
+          if (!emphasized && !n.link) return <InlineReference key={i} node={n} />
+          el = <InlineReference node={n} />
+        } else if (n.type === "image") {
           const img = (
             <img
               src={resolveAsset(n.src)}
@@ -62,16 +90,20 @@ function InlineText({ nodes }: { nodes: Inline[] }) {
               style={{ width: n.width, height: n.height }}
             />
           )
-          return n.link ? (
+          const linked = n.link ? (
             <a key={i} href={n.link} target="_blank" rel="noreferrer" className="docs-inline-img-link">
               {img}
             </a>
-          ) : (
-            <span key={i}>{img}</span>
-          )
-        }
-        let el: ReactNode = n.text
-        if (n.code) el = <code>{el}</code>
+          ) : null
+          if (!emphasized) return linked ?? <span key={i}>{img}</span>
+          // The image's link is its own anchor; emphasis wraps it.
+          el = linked ?? img
+          if (n.bold) el = <strong>{el}</strong>
+          if (n.italic) el = <em>{el}</em>
+          if (n.strike) el = <s>{el}</s>
+          return <span key={i}>{el}</span>
+        } else el = n.text
+        if (n.type === "text" && n.code) el = <code>{el}</code>
         if (n.bold) el = <strong>{el}</strong>
         if (n.italic) el = <em>{el}</em>
         if (n.strike) el = <s>{el}</s>
@@ -523,6 +555,10 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
           method={block.method || "get"}
         />
       )
+    // Reference definitions and verbatim-kept tags carry no content of their own.
+    case "definition":
+    case "raw":
+      return null
   }
 }
 
@@ -549,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, {