@brett_lamy/docstream 0.1.0 → 0.3.1

package/README.md

@@ -0,0 +1,215 @@
+# @brett_lamy/docstream
+
+GitBook-aware markdown rendering for React applications and AI streaming surfaces.
+
+`@brett_lamy/docstream` combines a small GitBook-flavored markdown parser with React renderers that can display docs blocks while a response is still streaming. It is designed for read-only documentation previews, AI answer panes, and apps that need GitBook-specific syntax without embedding a full editor.
+
+## Features
+
+- 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`.
+- 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.
+
+## Installation
+
+```sh
+npm install @brett_lamy/docstream react
+```
+
+React is a peer dependency and must be provided by your app.
+
+## Basic Setup
+
+Import the package CSS once near your app entrypoint:
+
+```ts
+import "@brett_lamy/docstream/styles.css"
+```
+
+If your TypeScript app checks CSS side-effect imports, include Vite's standard environment declaration or an equivalent CSS module declaration:
+
+```ts
+/// <reference types="vite/client" />
+```
+
+## Render Streaming Markdown
+
+Use `GitbookStreamdown` when markdown may arrive incrementally from an AI stream. The component accepts either `markdown` or string children.
+
+```tsx
+import { GitbookStreamdown } from "@brett_lamy/docstream"
+import "@brett_lamy/docstream/styles.css"
+
+export function Answer({ text, isStreaming }: { text: string; isStreaming: boolean }) {
+  return (
+    <GitbookStreamdown markdown={text} isStreaming={isStreaming} />
+  )
+}
+```
+
+`isStreaming` adds `aria-busy` and a `data-streaming` attribute to the wrapper. `isAnimating` is also accepted for compatibility with stream UI state.
+
+## Render Parsed Documents
+
+Use `parseMarkdown` and `DocsRenderer` when you want to parse once, inspect the AST, or serialize it later.
+
+```tsx
+import { DocsRenderer, parseMarkdown, serializeMarkdown } from "@brett_lamy/docstream"
+
+const doc = parseMarkdown(markdown)
+const roundTripped = serializeMarkdown(doc)
+
+export function Preview() {
+  return <DocsRenderer doc={doc} />
+}
+```
+
+## Markdown Helper Component
+
+`MarkdownContent` parses and renders a markdown string in one step:
+
+```tsx
+import { MarkdownContent } from "@brett_lamy/docstream"
+
+export function Preview({ markdown }: { markdown: string }) {
+  return <MarkdownContent markdown={markdown} />
+}
+```
+
+## GitBook Syntax
+
+The parser supports normal Markdown plus GitBook-style block tags.
+
+### Hints
+
+```md
+{% hint style="info" %}
+Helpful context for the reader.
+{% endhint %}
+```
+
+Supported styles are `info`, `success`, `warning`, and `danger`.
+
+### Tabs
+
+````md
+{% tabs %}
+{% tab title="TypeScript" %}
+```ts
+export const ok = true
+```
+{% endtab %}
+{% tab title="JSON" %}
+```json
+{ "ok": true }
+```
+{% endtab %}
+{% endtabs %}
+````
+
+### Expandables
+
+```md
+{% expandable title="More details" %}
+Hidden content goes here.
+{% endexpandable %}
+```
+
+### Steppers
+
+```md
+{% stepper %}
+{% step %}
+Create a token.
+{% endstep %}
+{% step %}
+Call the API.
+{% endstep %}
+{% endstepper %}
+```
+
+### OpenAPI Operations
+
+```md
+{% openapi-operation spec="petstore.yaml" path="/store/orders" method="get" /%}
+```
+
+When a spec cannot be resolved, the renderer displays a fallback asking for an OpenAPI spec URL.
+
+## Assets and OpenAPI Specs
+
+Relative image and OpenAPI spec paths can be resolved against an asset base:
+
+```ts
+import { setAssetBase } from "@brett_lamy/docstream"
+
+setAssetBase("/docs/assets/")
+```
+
+You can also resolve paths yourself with `resolveAsset`.
+
+## API Reference
+
+### Components
+
+- `GitbookStreamdown`: Parses and renders markdown for read-only stream output.
+- `DocsRenderer`: Renders a parsed `DocumentNode`.
+- `MarkdownContent`: Parses and renders a markdown string.
+- `OpenApiOperation`: Renders a parsed OpenAPI operation block.
+
+### Parser and Serializer
+
+- `parseMarkdown(markdown)`: Converts a full markdown document into a `DocumentNode`.
+- `parseBlocks(markdown)`: Parses markdown into block nodes.
+- `serializeMarkdown(doc)`: Converts a `DocumentNode` back to markdown.
+- `serializeBlocks(blocks)`: Serializes block nodes.
+- `parseInline(markdown)`: Parses inline markdown nodes.
+- `serializeInline(nodes)`: Serializes inline nodes.
+- `plainText(nodes)`: Extracts plain text from inline nodes.
+- `refDefinitions(markdown)`: Reads reference-style link definitions.
+
+### Types
+
+All AST types are exported from the package root, including `DocumentNode`, `Block`, `Inline`, and `HintStyle`.
+
+## Styling and Theming
+
+The package CSS is intentionally token-driven. It uses normal CSS variables and class names so host apps can align the renderer with a shadcn-style theme.
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --border: 214.3 31.8% 91.4%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --primary: 221.2 83.2% 53.3%;
+}
+```
+
+Import the CSS once, then set tokens globally in your app. Components also expose stable classes such as `docs-code`, `docs-tabs`, `docs-hint`, `docs-table`, and `docs-openapi`.
+
+## Bundler Notes
+
+This release ships TypeScript and TSX source through ESM exports:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./styles.css": "./src/styles.css"
+  }
+}
+```
+
+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.
+
+## Related Package
+
+Use `@brett_lamy/docstream-editor` when you need the editable TipTap experience for the same document model.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
-    "src"
+    "src",
+    "README.md"
   ],
   "sideEffects": [
     "**/*.css"
@@ -16,6 +17,30 @@
       "types": "./src/index.ts",
       "import": "./src/index.ts"
     },
+    "./gitbook": {
+      "types": "./src/gitbook/index.ts",
+      "import": "./src/gitbook/index.ts"
+    },
+    "./assets": {
+      "types": "./src/assets.ts",
+      "import": "./src/assets.ts"
+    },
+    "./openapi": {
+      "types": "./src/openapi/OpenApiOperation.tsx",
+      "import": "./src/openapi/OpenApiOperation.tsx"
+    },
+    "./replay": {
+      "types": "./src/replay/index.ts",
+      "import": "./src/replay/index.ts"
+    },
+    "./video": {
+      "types": "./src/video/index.ts",
+      "import": "./src/video/index.ts"
+    },
+    "./playground": {
+      "types": "./src/playground/index.ts",
+      "import": "./src/playground/index.ts"
+    },
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
@@ -23,10 +48,16 @@
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0",
     "mermaid": "^11.15.0",
+    "rrweb": "2.0.0-alpha.20",
     "streamdown": "^2.5.0",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "@agent-wasm/core": ">=0.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BLamy/docstream.git"
   }
 }

package/src/docs/DocsRenderer.tsx

@@ -11,9 +11,12 @@ import {
 import type { Block, DocumentNode, Inline } from "../gitbook/ast"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
+import { ReplayPreview, isReplayQaUrl } from "../replay"
+import { VideoEmbed } from "../video"
 import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
+import { ReactCodePreview } from "../playground"
 
 function InlineText({ nodes }: { nodes: Inline[] }) {
   return (
@@ -65,6 +68,10 @@ function embedSrc(url: string): string | null {
   return yt ? `https://www.youtube.com/embed/${yt[1]}` : null
 }
 
+function isDirectVideo(url: string): boolean {
+  return /\.(?:mp4|webm|ogg)(?:[?#]|$)/i.test(url)
+}
+
 function Tabs({ block }: { block: Extract<Block, { type: "tabs" }> }) {
   const [active, setActive] = useState(0)
   return (
@@ -105,6 +112,16 @@ function BlockView({ block }: { block: Block }) {
     }
     case "code":
       if (block.language === "mermaid") return <Mermaid code={block.code} />
+      if (block.live && isReactLanguage(block.language)) {
+        const entry = block.entry ?? "/src/main.jsx"
+        return (
+          <ReactCodePreview
+            files={{ [entry]: block.code }}
+            entry={entry}
+            title={block.title ?? "Live React preview"}
+          />
+        )
+      }
       return (
         <div className="docs-code">
           {(block.title || block.language) && (
@@ -162,9 +179,16 @@ function BlockView({ block }: { block: Block }) {
         </div>
       )
     case "embed": {
+      if (isReplayQaUrl(block.url)) {
+        return <ReplayPreview source={block.url} title="Replay preview" />
+      }
       const src = embedSrc(block.url)
-      return src ? (
-        <iframe className="docs-embed" src={src} title={block.url} allowFullScreen />
+      return src || isDirectVideo(block.url) ? (
+        <VideoEmbed
+          src={src ?? block.url}
+          className="docs-embed"
+          title={block.url}
+        />
       ) : (
         <a className="docs-content-ref" href={block.url} target="_blank" rel="noreferrer">
           <File className="size-4" /> {block.url}
@@ -286,6 +310,10 @@ function BlockView({ block }: { block: Block }) {
   }
 }
 
+function isReactLanguage(language: string | null): boolean {
+  return language === "jsx" || language === "tsx" || language === "react"
+}
+
 function Blocks({ blocks, inline }: { blocks: Block[]; inline?: boolean }) {
   return (
     <div className={inline ? "docs-blocks-inline" : undefined} style={inline ? { display: "inline" } : undefined}>

package/src/gitbook/ast.ts

@@ -42,6 +42,10 @@ export interface CodeBlockNode {
   title: string | null
   lineNumbers: boolean
   code: string
+  /** Run a React/JSX/TSX entry file in the optional almost-node preview. */
+  live?: boolean
+  /** Project-relative entry file used by a live preview. */
+  entry?: string | null
 }
 
 export interface HintNode {

package/src/gitbook/index.ts

@@ -0,0 +1,6 @@
+// Pure GitBook markdown engine (no React, no mermaid/streamdown). Safe to import
+// in non-DOM environments such as a server-side AI agent or a Cloudflare Worker.
+export type * from "./ast"
+export { parseMarkdown, parseBlocks } from "./parse"
+export { serializeBlocks, serializeMarkdown } from "./serialize"
+export { parseInline, plainText, refDefinitions, serializeInline } from "./inline"

package/src/gitbook/parse.ts

@@ -25,6 +25,36 @@ function htmlToInlineMd(html: string): string {
     .trim()
 }
 
+// Split a GFM pipe-table row into cell strings. Splits only on unescaped pipes
+// that are outside inline-code spans, and unescapes "\|" back to a literal "|".
+function splitTableRow(row: string): string[] {
+  const trimmed = row.trim().replace(/^\|/, "").replace(/\|$/, "")
+  const cells: string[] = []
+  let cur = ""
+  let inCode = false
+  for (let k = 0; k < trimmed.length; k++) {
+    const ch = trimmed[k]
+    if (ch === "\\" && trimmed[k + 1] === "|") {
+      cur += "|"
+      k++
+      continue
+    }
+    if (ch === "`") {
+      inCode = !inCode
+      cur += ch
+      continue
+    }
+    if (ch === "|" && !inCode) {
+      cells.push(cur)
+      cur = ""
+      continue
+    }
+    cur += ch
+  }
+  cells.push(cur)
+  return cells
+}
+
 const TEMPLATE_RE = /^\s*\{%\s*(\S+?)(\s+[^%]*?)?\s*%\}\s*$/
 
 function parseAttrs(raw: string | undefined): Record<string, string> {
@@ -158,6 +188,8 @@ export function parseBlocks(lines: string[]): Block[] {
         if (code && code.type === "code") {
           code.title = tag.attrs.title ?? null
           code.lineNumbers = tag.attrs.lineNumbers === "true"
+          code.live = tag.attrs.live === "true"
+          code.entry = tag.attrs.entry ?? null
           blocks.push(code)
         }
         i = next
@@ -414,11 +446,7 @@ export function parseBlocks(lines: string[]): Block[] {
     if (trimmed.startsWith("|") && lines[i + 1]?.trim().match(/^\|[\s:|-]+\|$/)) {
       flushParagraph()
       const parseRow = (row: string): Inline[][] =>
-        row
-          .trim()
-          .replace(/^\||\|$/g, "")
-          .split("|")
-          .map((cell) => parseInline(cell.trim()))
+        splitTableRow(row).map((cell) => parseInline(cell.trim()))
       const header = parseRow(lines[i])
       i += 2
       const rows: Inline[][][] = []

package/src/gitbook/serialize.ts

@@ -29,10 +29,12 @@ function serializeBlock(b: Block): string {
     case "code": {
       const fence = "```" + (b.language ?? "")
       const body = `${fence}\n${b.code}\n\`\`\``
-      if (b.title || b.lineNumbers) {
+      if (b.title || b.lineNumbers || b.live || b.entry) {
         const attrs = [
           b.title ? ` title="${b.title}"` : "",
           b.lineNumbers ? ` lineNumbers="true"` : "",
+          b.live ? ` live="true"` : "",
+          b.entry ? ` entry="${b.entry}"` : "",
         ].join("")
         return `{% code${attrs} %}\n${body}\n{% endcode %}`
       }
@@ -96,7 +98,9 @@ function serializeBlock(b: Block): string {
           .join("")}</tbody>`
         return `<table data-view="${b.view}">${head}${body}</table>`
       }
-      const row = (cells: Inline[][]) => `| ${cells.map((c) => serializeInline(c)).join(" | ")} |`
+      // Escape pipes inside cell text so they don't break the GFM row.
+      const cell = (c: Inline[]) => serializeInline(c).replace(/\|/g, "\\|")
+      const row = (cells: Inline[][]) => `| ${cells.map(cell).join(" | ")} |`
       const sep = `| ${b.header.map(() => "---").join(" | ")} |`
       return [row(b.header), sep, ...b.rows.map(row)].join("\n")
     }

package/src/index.ts

@@ -1,7 +1,35 @@
 export { GitbookStreamdown } from "./streamdown"
 export type { GitbookStreamdownProps } from "./streamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
+export { ReplayEmbed, ReplayPreview } from "./replay"
+export type {
+  ReplayEventsSource,
+  ReplayEventsUrlSource,
+  ReplayPageSource,
+  ReplayPreviewProps,
+  ReplaySource,
+} from "./replay"
+export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay"
+export { VideoEmbed } from "./video"
+export type { VideoEmbedProps } from "./video"
 export { OpenApiOperation } from "./openapi/OpenApiOperation"
+export {
+  ReactCodePreview,
+  ReactDemo,
+  createReactDemoFiles,
+  createAlmostNodeFilesystem,
+  createAlmostNodeWorkspace,
+} from "./playground"
+export type {
+  AlmostNodeFile,
+  AlmostNodeFileContent,
+  AlmostNodeFiles,
+  AlmostNodeFilesystemOptions,
+  AlmostNodeWorkspace,
+  AlmostNodeWorkspaceOptions,
+  ReactCodePreviewProps,
+  ReactDemoProps,
+} from "./playground"
 export { resolveAsset, setAssetBase } from "./assets"
 export { parseMarkdown, parseBlocks } from "./gitbook/parse"
 export { serializeBlocks, serializeMarkdown } from "./gitbook/serialize"

package/src/playground/ReactCodePreview.tsx

@@ -0,0 +1,161 @@
+import { useEffect, useState, type CSSProperties } from "react"
+import {
+  createAlmostNodeWorkspace,
+  createReactDemoFiles,
+  type AlmostNodeFiles,
+  type AlmostNodeWorkspace,
+} from "./filesystem"
+
+export interface ReactDemoProps {
+  /** Complete project file map. Relative paths are rooted at `/`. */
+  files: AlmostNodeFiles
+  /** Vite entry file. Defaults to `/src/main.jsx`. */
+  entry?: string
+  /** Preferred virtual port. almost-node picks the next free port if needed. */
+  port?: number
+  /** Height of the embedded preview. */
+  height?: number | string
+  /** Label shown above the preview. */
+  title?: string
+  /** Start the runtime on mount (default true). */
+  autoStart?: boolean
+  /** iframe sandbox value. The same-origin permission lets the almost-node service worker route the preview. */
+  sandbox?: string
+  className?: string
+  onReady?: (url: string) => void
+  onError?: (error: Error) => void
+}
+
+export type ReactCodePreviewProps = ReactDemoProps
+
+type PreviewState = "idle" | "starting" | "ready" | "error"
+
+const DETACHED_SERVER_ENV = { ALMOSTNODE_DETACH_DEV_SERVERS: "1" }
+
+function errorFromUnknown(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+function frameHeight(height: number | string): CSSProperties {
+  return { height: typeof height === "number" ? `${height}px` : height }
+}
+
+/** Render a multi-file React/JSX/TSX project through almost-node's Vite server. */
+export function ReactDemo({
+  files,
+  entry = "/src/main.jsx",
+  port = 4173,
+  height = 360,
+  title = "Live React preview",
+  autoStart = true,
+  sandbox = "allow-scripts allow-same-origin allow-forms allow-modals",
+  className,
+  onReady,
+  onError,
+}: ReactDemoProps) {
+  const [run, setRun] = useState(autoStart ? 1 : 0)
+  const [state, setState] = useState<PreviewState>(autoStart ? "starting" : "idle")
+  const [url, setUrl] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!run) {
+      setState("idle")
+      setUrl(null)
+      setError(null)
+      return
+    }
+
+    let cancelled = false
+    let workspace: AlmostNodeWorkspace | null = null
+    let readyUrl: string | null = null
+    setState("starting")
+    setUrl(null)
+    setError(null)
+
+    const start = async () => {
+      try {
+        const projectFiles = createReactDemoFiles(files, { entry })
+        workspace = await createAlmostNodeWorkspace(projectFiles, {
+          env: DETACHED_SERVER_ENV,
+          onServerReady: (_port, serverUrl) => {
+            readyUrl = serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`
+          },
+        })
+
+        const result = await workspace.container.run(`vite --port ${port}`, {
+          env: DETACHED_SERVER_ENV,
+        })
+        if (result.exitCode !== 0) {
+          throw new Error(result.stderr || result.stdout || "almost-node could not start Vite")
+        }
+
+        const serverUrl = readyUrl ?? `${workspace.container.serverBridge.getServerUrl(port)}/`
+        if (cancelled) {
+          workspace.dispose()
+          return
+        }
+        setUrl(serverUrl)
+        setState("ready")
+        onReady?.(serverUrl)
+      } catch (cause) {
+        const nextError = errorFromUnknown(cause)
+        if (!cancelled) {
+          setState("error")
+          setError(nextError.message)
+          onError?.(nextError)
+        }
+        workspace?.dispose()
+      }
+    }
+
+    void start()
+    return () => {
+      cancelled = true
+      workspace?.dispose()
+    }
+  }, [entry, files, onError, onReady, port, run])
+
+  const wrapperClass = className ? `docs-react-demo ${className}` : "docs-react-demo"
+  const running = state === "starting"
+
+  return (
+    <section className={wrapperClass} data-docstream-react-demo="">
+      <header className="docs-react-demo-header">
+        <span>{title}</span>
+        <span className={`docs-react-demo-status docs-react-demo-status-${state}`}>
+          {state === "ready" ? "ready" : state === "starting" ? "starting" : state}
+        </span>
+        {!autoStart || state === "error" ? (
+          <button
+            type="button"
+            className="docs-react-demo-run"
+            disabled={running}
+            onClick={() => setRun((value) => value + 1)}
+          >
+            {state === "error" ? "Retry" : "Run demo"}
+          </button>
+        ) : null}
+      </header>
+      {error ? (
+        <pre className="docs-react-demo-error">{error}</pre>
+      ) : url ? (
+        <iframe
+          title={title}
+          className="docs-react-demo-frame"
+          src={url}
+          sandbox={sandbox}
+          style={frameHeight(height)}
+        />
+      ) : (
+        <div className="docs-react-demo-placeholder" style={frameHeight(height)}>
+          {running ? "Starting almost-node…" : "Run the demo to open its virtual filesystem."}
+        </div>
+      )}
+    </section>
+  )
+}
+
+export function ReactCodePreview(props: ReactCodePreviewProps) {
+  return <ReactDemo {...props} />
+}