@brett_lamy/docstream 0.3.0 → 0.3.2

package/README.md

@@ -10,11 +10,10 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 - 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.
+- 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
 
@@ -70,62 +69,6 @@ export function Preview() {
 }
 ```
 
-## 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:
@@ -138,25 +81,6 @@ export function Preview({ markdown }: { markdown: string }) {
 }
 ```
 
-## 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.
@@ -217,6 +141,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:
@@ -236,8 +194,6 @@ You can also resolve paths yourself with `resolveAsset`.
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "main": "./src/index.ts",
@@ -37,6 +37,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,15 +54,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"
   },
-  "peerDependenciesMeta": {
-    "@agent-wasm/core": {
-      "optional": true
-    }
+  "devDependencies": {
+    "@agent-wasm/core": "^0.4.0",
+    "@types/react": "^18.3.3",
+    "typescript": "^5.5.4"
   }
 }

package/src/docs/DocsRenderer.tsx

@@ -187,7 +187,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">

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

@@ -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/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"