@brett_lamy/docstream 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,295 @@
+# @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`.
+- Optional live React/JSX/TSX previews powered by the almost-node runtime.
+- A complete virtual-filesystem helper for multi-file React demos.
+- GitBook block support for hints, tabs, expandables, steppers, embeds, content refs, columns, figures, tables, math, dividers, updates, and OpenAPI operations.
+- Embed blocks render YouTube/direct video URLs through the built-in `VideoEmbed` and public Loop QA task, journey, exploration, or test-run URLs through `ReplayPreview`.
+- 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} />
+}
+```
+
+## Run React and JSX demos
+
+Install `@agent-wasm/core` in the host app and serve its service worker through
+the Vite plugin:
+
+```ts
+import { almostnodePlugin } from "@agent-wasm/core/vite"
+
+export default defineConfig({
+  plugins: [almostnodePlugin()],
+})
+```
+
+`ReactDemo` creates the complete file tree in almost-node, starts its Vite
+server, and renders the resulting app in a preview iframe. The file map can
+contain any number of files:
+
+```tsx
+import { ReactDemo } from "@brett_lamy/docstream"
+
+const files = {
+  "/src/main.jsx": `
+    import React from "react"
+    import { createRoot } from "react-dom/client"
+    import App from "./App.jsx"
+    createRoot(document.getElementById("root")).render(<App />)
+  `,
+  "/src/App.jsx": `
+    import Card from "./Card.jsx"
+    export default function App() { return <Card title="Hello" /> }
+  `,
+  "/src/Card.jsx": `
+    export default function Card({ title }) { return <button>{title}</button> }
+  `,
+}
+
+<ReactDemo files={files} entry="/src/main.jsx" />
+```
+
+For lower-level integrations, `createAlmostNodeFilesystem(files)` creates a
+`VirtualFS`, while `createAlmostNodeWorkspace(files)` creates a container and
+populates its complete filesystem so callers can run shell commands, npm, or
+Vite themselves.
+
+Single-file live code blocks opt in explicitly so ordinary documentation
+snippets remain inert:
+
+````md
+{% code language="jsx" live="true" entry="/src/main.jsx" %}
+```jsx
+import { createRoot } from "react-dom/client"
+createRoot(document.getElementById("root")).render(<h1>Hello</h1>)
+```
+{% endcode %}
+````
+
+## 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} />
+}
+```
+
+## Video and Replay QA embeds
+
+`embed` blocks accept direct `.mp4`, `.webm`, and `.ogg` assets, YouTube URLs,
+and public Loop QA project URLs. Loop QA project URLs are converted to the
+chrome-free `/p/...` route automatically:
+
+```md
+{% embed url="https://loop-qa.replay.io/projects/project-id/journeys/journey-id" /%}
+```
+
+The replay component is also available directly when a document needs a
+custom source or native rrweb events:
+
+```tsx
+import { ReplayPreview } from "@brett_lamy/docstream"
+
+<ReplayPreview source="https://loop-qa.replay.io/projects/project-id/tasks/task-id" />
+```
+
+## 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.
+- `ReplayPreview` / `ReplayEmbed`: Embeds public Loop QA pages or plays CORS-enabled rrweb event data.
+- `VideoEmbed`: Renders direct video assets or hosted video players.
+- `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.0",
   "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,17 @@
     "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"
+  },
+  "peerDependenciesMeta": {
+    "@agent-wasm/core": {
+      "optional": true
+    }
   }
 }

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"