@brett_lamy/docstream 0.3.1 → 0.3.3

package/README.md

@@ -12,6 +12,8 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 - 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.
+- Attribute-aware direct video embeds for muted, looping inline clips in long-form posts.
+- Optional `VizEmbed` integration for mounting deterministic `@brett_lamy/viz-engine` scenes in a document.
 
 ## Installation
 
@@ -39,6 +41,13 @@ 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:
+
+```tsx
+import { GitbookStreamdown } from "@brett_lamy/docstream/streamdown"
+```
+
 ```tsx
 import { GitbookStreamdown } from "@brett_lamy/docstream"
 import "@brett_lamy/docstream/styles.css"
@@ -139,6 +148,40 @@ Call the API.
 
 When a spec cannot be resolved, the renderer displays a fallback asking for an OpenAPI spec URL.
 
+### Inline video clips
+
+Direct media embeds can opt into browser-safe inline playback. `muted` is
+important when `autoplay` is enabled:
+
+```md
+{% embed url="/generated/example/clips/offsets.mp4"
+  title="A reader resumes from its bookmark"
+  autoplay="true" loop="true" muted="true" controls="false" %}
+```
+
+The attributes round-trip through `parseMarkdown` and `serializeMarkdown` and
+are rendered as a native `<video playsInline>` element.
+
+### VizEngine scenes
+
+Install the optional peer dependency when a document needs a live, seekable
+scene rather than a rendered clip:
+
+```sh
+npm install @brett_lamy/docstream @brett_lamy/viz-engine
+```
+
+```tsx
+import { VizEmbed } from "@brett_lamy/docstream/viz"
+import "@brett_lamy/docstream/styles.css"
+
+<VizEmbed scene={scene} title="The same event, replayed into two projections" />
+```
+
+`VizEmbed` keeps the scene's timeline deterministic and delegates the clock to
+VizEngine, so a reader can pause or scrub the same explanation used to produce
+the short clip.
+
 ## Assets and OpenAPI Specs
 
 Relative image and OpenAPI spec paths can be resolved against an asset base:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "main": "./src/index.ts",
@@ -21,6 +21,10 @@
       "types": "./src/gitbook/index.ts",
       "import": "./src/gitbook/index.ts"
     },
+    "./streamdown": {
+      "types": "./src/streamdown.tsx",
+      "import": "./src/streamdown.tsx"
+    },
     "./assets": {
       "types": "./src/assets.ts",
       "import": "./src/assets.ts"
@@ -37,6 +41,10 @@
       "types": "./src/video/index.ts",
       "import": "./src/video/index.ts"
     },
+    "./viz": {
+      "types": "./src/viz/index.ts",
+      "import": "./src/viz/index.ts"
+    },
     "./playground": {
       "types": "./src/playground/index.ts",
       "import": "./src/playground/index.ts"
@@ -50,14 +58,21 @@
     "mermaid": "^11.15.0",
     "rrweb": "2.0.0-alpha.20",
     "streamdown": "^2.5.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@brett_lamy/viz-engine": "^0.2.0"
   },
   "peerDependencies": {
-    "react": ">=18",
-    "@agent-wasm/core": ">=0.4.0"
+    "@agent-wasm/core": ">=0.4.0",
+    "@brett_lamy/viz-engine": ">=0.2.0",
+    "react": ">=18"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/BLamy/docstream.git"
+  },
+  "devDependencies": {
+    "@agent-wasm/core": "^0.4.0",
+    "@types/react": "^18.3.3",
+    "typescript": "^5.5.4"
   }
 }

package/src/docs/DocsRenderer.tsx

@@ -16,7 +16,14 @@ import { VideoEmbed } from "../video"
 import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
-import { ReactCodePreview } from "../playground"
+
+export interface LivePreviewProps {
+  files: Record<string, string>
+  entry: string
+  title: string
+}
+
+export type LivePreviewRenderer = (props: LivePreviewProps) => ReactNode
 
 function InlineText({ nodes }: { nodes: Inline[] }) {
   return (
@@ -72,7 +79,7 @@ function isDirectVideo(url: string): boolean {
   return /\.(?:mp4|webm|ogg)(?:[?#]|$)/i.test(url)
 }
 
-function Tabs({ block }: { block: Extract<Block, { type: "tabs" }> }) {
+function Tabs({ block, liveRenderer }: { block: Extract<Block, { type: "tabs" }>; liveRenderer?: LivePreviewRenderer }) {
   const [active, setActive] = useState(0)
   return (
     <div className="docs-tabs">
@@ -88,13 +95,13 @@ function Tabs({ block }: { block: Extract<Block, { type: "tabs" }> }) {
         ))}
       </div>
       <div className="docs-tabs-body">
-        <Blocks blocks={block.tabs[active]?.children ?? []} />
+        <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} />
       </div>
     </div>
   )
 }
 
-function BlockView({ block }: { block: Block }) {
+function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LivePreviewRenderer }) {
   switch (block.type) {
     case "paragraph":
       return (
@@ -112,15 +119,13 @@ function BlockView({ block }: { block: Block }) {
     }
     case "code":
       if (block.language === "mermaid") return <Mermaid code={block.code} />
-      if (block.live && isReactLanguage(block.language)) {
+      if (block.live && isReactLanguage(block.language) && liveRenderer) {
         const entry = block.entry ?? "/src/main.jsx"
-        return (
-          <ReactCodePreview
-            files={{ [entry]: block.code }}
-            entry={entry}
-            title={block.title ?? "Live React preview"}
-          />
-        )
+        return liveRenderer({
+          files: { [entry]: block.code },
+          entry,
+          title: block.title ?? "Live React preview",
+        })
       }
       return (
         <div className="docs-code">
@@ -145,19 +150,19 @@ function BlockView({ block }: { block: Block }) {
         <div className={`docs-hint docs-hint-${block.style}`}>
           <Icon className="docs-hint-icon" />
           <div>
-            <Blocks blocks={block.children} />
+            <Blocks blocks={block.children} liveRenderer={liveRenderer} />
           </div>
         </div>
       )
     }
     case "tabs":
-      return <Tabs block={block} />
+      return <Tabs block={block} liveRenderer={liveRenderer} />
     case "expandable":
       return (
         <details className="docs-expandable">
           <summary>{block.summary}</summary>
           <div className="docs-expandable-body">
-            <Blocks blocks={block.children} />
+            <Blocks blocks={block.children} liveRenderer={liveRenderer} />
           </div>
         </details>
       )
@@ -172,7 +177,7 @@ function BlockView({ block }: { block: Block }) {
               </div>
               <div className="docs-step-main">
                 {s.title && <div className="docs-step-title">{s.title}</div>}
-                <Blocks blocks={s.children} />
+                <Blocks blocks={s.children} liveRenderer={liveRenderer} />
               </div>
             </div>
           ))}
@@ -187,7 +192,12 @@ function BlockView({ block }: { block: Block }) {
         <VideoEmbed
           src={src ?? block.url}
           className="docs-embed"
-          title={block.url}
+          title={block.title ?? block.url}
+          {...(block.autoplay === undefined ? {} : { autoplay: block.autoplay })}
+          {...(block.loop === undefined ? {} : { loop: block.loop })}
+          {...(block.muted === undefined ? {} : { muted: block.muted })}
+          {...(block.controls === undefined ? {} : { controls: block.controls })}
+          {...(block.poster === undefined ? {} : { poster: resolveAsset(block.poster) })}
         />
       ) : (
         <a className="docs-content-ref" href={block.url} target="_blank" rel="noreferrer">
@@ -210,7 +220,7 @@ function BlockView({ block }: { block: Block }) {
         <div className="docs-columns">
           {block.columns.map((c, i) => (
             <div key={i} className="docs-column">
-              <Blocks blocks={c.children} />
+              <Blocks blocks={c.children} liveRenderer={liveRenderer} />
             </div>
           ))}
         </div>
@@ -229,7 +239,7 @@ function BlockView({ block }: { block: Block }) {
           {block.items.map((item, i) => (
             <li key={i}>
               {block.task && <input type="checkbox" checked={!!item.checked} readOnly />}
-              <Blocks blocks={item.children} inline />
+              <Blocks blocks={item.children} inline liveRenderer={liveRenderer} />
             </li>
           ))}
         </Tag>
@@ -238,7 +248,7 @@ function BlockView({ block }: { block: Block }) {
     case "blockquote":
       return (
         <blockquote>
-          <Blocks blocks={block.children} />
+          <Blocks blocks={block.children} liveRenderer={liveRenderer} />
         </blockquote>
       )
     case "divider":
@@ -293,7 +303,7 @@ function BlockView({ block }: { block: Block }) {
             <div key={i} className="docs-update">
               <div className="docs-update-date">{u.date}</div>
               <div className="docs-update-body">
-                <Blocks blocks={u.children} />
+                <Blocks blocks={u.children} liveRenderer={liveRenderer} />
               </div>
             </div>
           ))}
@@ -314,11 +324,11 @@ function isReactLanguage(language: string | null): boolean {
   return language === "jsx" || language === "tsx" || language === "react"
 }
 
-function Blocks({ blocks, inline }: { blocks: Block[]; inline?: boolean }) {
+function Blocks({ blocks, inline, liveRenderer }: { blocks: Block[]; inline?: boolean; liveRenderer?: LivePreviewRenderer }) {
   return (
     <div className={inline ? "docs-blocks-inline" : undefined} style={inline ? { display: "inline" } : undefined}>
       {blocks.map((b, i) => (
-        <BlockView key={i} block={b} />
+        <BlockView key={i} block={b} liveRenderer={liveRenderer} />
       ))}
     </div>
   )
@@ -326,14 +336,14 @@ function Blocks({ blocks, inline }: { blocks: Block[]; inline?: boolean }) {
 
 // Renders a markdown string inline — used for embedded markdown like
 // OpenAPI descriptions, which can themselves contain GitBook blocks.
-export function MarkdownContent({ markdown }: { markdown: string }) {
-  return <Blocks blocks={parseMarkdown(markdown).children} />
+export function MarkdownContent({ markdown, liveRenderer }: { markdown: string; liveRenderer?: LivePreviewRenderer }) {
+  return <Blocks blocks={parseMarkdown(markdown).children} liveRenderer={liveRenderer} />
 }
 
-export function DocsRenderer({ doc }: { doc: DocumentNode }) {
+export function DocsRenderer({ doc, liveRenderer }: { doc: DocumentNode; liveRenderer?: LivePreviewRenderer }) {
   return (
     <article className="docs-article">
-      <Blocks blocks={doc.children} />
+      <Blocks blocks={doc.children} liveRenderer={liveRenderer} />
     </article>
   )
 }

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module "*.css" {
+  const href: string
+  export default href
+}

package/src/gitbook/ast.ts

@@ -85,6 +85,12 @@ export interface StepperNode {
 export interface EmbedNode {
   type: "embed"
   url: string
+  title?: string
+  autoplay?: boolean
+  loop?: boolean
+  muted?: boolean
+  controls?: boolean
+  poster?: string
 }
 
 export interface ContentRefNode {

package/src/gitbook/parse.ts

@@ -66,6 +66,11 @@ function parseAttrs(raw: string | undefined): Record<string, string> {
   return attrs
 }
 
+function booleanAttr(attrs: Record<string, string>, key: string): boolean | undefined {
+  if (!(key in attrs)) return undefined
+  return attrs[key] !== "false"
+}
+
 interface TemplateTag {
   name: string
   attrs: Record<string, string>
@@ -197,7 +202,24 @@ export function parseBlocks(lines: string[]): Block[] {
       }
 
       if (tag.name === "embed") {
-        blocks.push({ type: "embed", url: tag.attrs.url ?? "" })
+        blocks.push({
+          type: "embed",
+          url: tag.attrs.url ?? "",
+          ...(tag.attrs.title ? { title: tag.attrs.title } : {}),
+          ...(tag.attrs.poster ? { poster: tag.attrs.poster } : {}),
+          ...(booleanAttr(tag.attrs, "autoplay") === undefined
+            ? {}
+            : { autoplay: booleanAttr(tag.attrs, "autoplay") }),
+          ...(booleanAttr(tag.attrs, "loop") === undefined
+            ? {}
+            : { loop: booleanAttr(tag.attrs, "loop") }),
+          ...(booleanAttr(tag.attrs, "muted") === undefined
+            ? {}
+            : { muted: booleanAttr(tag.attrs, "muted") }),
+          ...(booleanAttr(tag.attrs, "controls") === undefined
+            ? {}
+            : { controls: booleanAttr(tag.attrs, "controls") }),
+        })
         i++
         // tolerate optional {% endembed %}
         if (i < lines.length && templateTag(lines[i])?.name === "endembed") i++

package/src/gitbook/serialize.ts

@@ -60,8 +60,18 @@ function serializeBlock(b: Block): string {
         })
         .join("\n\n")}\n{% endstepper %}`
 
-    case "embed":
-      return `{% embed url="${b.url}" %}`
+    case "embed": {
+      const attrs = [
+        ` url="${b.url}"`,
+        b.title ? ` title="${b.title}"` : "",
+        b.poster ? ` poster="${b.poster}"` : "",
+        b.autoplay === undefined ? "" : ` autoplay="${b.autoplay}"`,
+        b.loop === undefined ? "" : ` loop="${b.loop}"`,
+        b.muted === undefined ? "" : ` muted="${b.muted}"`,
+        b.controls === undefined ? "" : ` controls="${b.controls}"`,
+      ].join("")
+      return `{% embed${attrs} %}`
+    }
 
     case "content-ref":
       return `{% content-ref url="${b.url}" %}\n${serializeInline(b.children)}\n{% endcontent-ref %}`

package/src/index.ts

@@ -1,5 +1,5 @@
-export { GitbookStreamdown } from "./streamdown"
-export type { GitbookStreamdownProps } from "./streamdown"
+export { PlaygroundStreamdown as GitbookStreamdown } from "./playground/PlaygroundStreamdown"
+export type { PlaygroundStreamdownProps as GitbookStreamdownProps } from "./playground/PlaygroundStreamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
 export { ReplayEmbed, ReplayPreview } from "./replay"
 export type {
@@ -12,6 +12,8 @@ export type {
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay"
 export { VideoEmbed } from "./video"
 export type { VideoEmbedProps } from "./video"
+export { VizEmbed } from "./viz"
+export type { VizEmbedProps } from "./viz"
 export { OpenApiOperation } from "./openapi/OpenApiOperation"
 export {
   ReactCodePreview,

package/src/playground/PlaygroundStreamdown.tsx

@@ -0,0 +1,43 @@
+import { useMemo } from "react"
+
+import { DocsRenderer, type LivePreviewRenderer } from "../docs/DocsRenderer"
+import { parseMarkdown } from "../gitbook/parse"
+import { ReactCodePreview } from "./ReactCodePreview"
+
+export interface PlaygroundStreamdownProps {
+  children?: string
+  className?: string
+  isAnimating?: boolean
+  isStreaming?: boolean
+  markdown?: string
+}
+
+/**
+ * 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.
+ */
+export function PlaygroundStreamdown({
+  children,
+  className,
+  isAnimating,
+  isStreaming = false,
+  markdown,
+}: PlaygroundStreamdownProps) {
+  const content = markdown ?? children ?? ""
+  const doc = useMemo(() => parseMarkdown(content), [content])
+  const liveRenderer: LivePreviewRenderer = ({ files, entry, title }) => (
+    <ReactCodePreview files={files} entry={entry} title={title} />
+  )
+
+  return (
+    <div
+      aria-busy={isAnimating ?? isStreaming}
+      className={className}
+      data-docstream=""
+      data-streaming={isStreaming ? "" : undefined}
+    >
+      <DocsRenderer doc={doc} liveRenderer={liveRenderer} />
+    </div>
+  )
+}

package/src/styles.css

@@ -122,6 +122,22 @@
   margin-top: 8px;
 }
 
+.docstream-viz {
+  margin: 1.5rem 0;
+}
+
+.docstream-viz__player {
+  overflow: hidden;
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  background: var(--gb-muted);
+}
+
+.docstream-viz figcaption {
+  margin-top: 8px;
+  color: var(--gb-muted-foreground);
+}
+
 .docs-hint {
   display: flex;
   gap: 12px;

package/src/viz/VizEmbed.tsx

@@ -0,0 +1,42 @@
+import type { PlayerAudio, VideoScene } from "@brett_lamy/viz-engine"
+import { VizPlayer } from "@brett_lamy/viz-engine"
+
+export interface VizEmbedProps {
+  scene: VideoScene
+  audio?: PlayerAudio
+  title?: string
+  className?: string
+  autoplay?: boolean
+  loop?: boolean
+  showCaptions?: boolean
+}
+
+/**
+ * Mount a deterministic VizEngine scene inside a Docstream document. This is
+ * intentionally a component API rather than a markdown escape hatch: callers
+ * choose the scene and its evidence, while Docstream supplies document chrome
+ * and accessible figure semantics.
+ */
+export function VizEmbed({
+  scene,
+  audio,
+  title,
+  className,
+  autoplay = true,
+  loop = true,
+  showCaptions = false,
+}: VizEmbedProps) {
+  return (
+    <figure className={`docstream-viz ${className ?? ""}`.trim()}>
+      <VizPlayer
+        scene={scene}
+        {...(audio === undefined ? {} : { audio })}
+        autoplay={autoplay}
+        loop={loop}
+        showCaptions={showCaptions}
+        className="docstream-viz__player"
+      />
+      {title && <figcaption>{title}</figcaption>}
+    </figure>
+  )
+}

package/src/viz/index.ts

@@ -0,0 +1,4 @@
+import "@brett_lamy/viz-engine/styles.css"
+
+export { VizEmbed } from "./VizEmbed"
+export type { VizEmbedProps } from "./VizEmbed"