@brett_lamy/docstream 0.3.1 → 0.3.2

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
 
@@ -139,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.3.1",
+  "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,14 +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"
+  },
+  "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"