@brett_lamy/docstream 0.3.2 → 0.3.4

package/README.md

@@ -41,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"

package/package.json

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

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>
           ))}
@@ -215,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>
@@ -234,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>
@@ -243,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":
@@ -298,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>
           ))}
@@ -319,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>
   )
@@ -331,14 +336,22 @@ 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,
+  className,
+}: { markdown: string; liveRenderer?: LivePreviewRenderer; className?: string }) {
+  return (
+    <div data-docstream="" className={className}>
+      <Blocks blocks={parseMarkdown(markdown).children} liveRenderer={liveRenderer} />
+    </div>
+  )
 }
 
-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/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 {

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

@@ -2,19 +2,19 @@
 
 [data-docstream],
 .docs-article {
-  --gb-panel: var(--card);
-  --gb-panel-foreground: var(--card-foreground);
-  --gb-muted: var(--muted);
-  --gb-muted-foreground: var(--muted-foreground);
-  --gb-border: var(--border);
-  --gb-accent: var(--accent);
-  --gb-accent-foreground: var(--accent-foreground);
-  --gb-primary: var(--primary);
-  --gb-primary-foreground: var(--primary-foreground);
+  --gb-panel: var(--card, #ffffff);
+  --gb-panel-foreground: var(--card-foreground, #18181b);
+  --gb-muted: var(--muted, #f4f4f5);
+  --gb-muted-foreground: var(--muted-foreground, #71717a);
+  --gb-border: var(--border, #e4e4e7);
+  --gb-accent: var(--accent, #f4f4f5);
+  --gb-accent-foreground: var(--accent-foreground, #18181b);
+  --gb-primary: var(--primary, #4f46e5);
+  --gb-primary-foreground: var(--primary-foreground, #fafafa);
   /* Plain rgba/hex values (no color-mix()/oklch()) so the theme renders
      correctly in older Chromium forks; hosts can override any token. */
   --gb-code-bg: rgba(128, 128, 128, 0.13);
-  --gb-code-fg: var(--foreground);
+  --gb-code-fg: var(--foreground, #18181b);
 
   /* Semantic hint palette — solid color plus precomputed tints. Matches the
      editor palette in @brett_lamy/docstream-editor/styles.css. */
@@ -55,7 +55,7 @@
   font-weight: 650;
   margin-top: 1.4em;
   padding-bottom: 0.2em;
-  border-bottom: 1px solid var(--border);
+  border-bottom: 1px solid var(--border, #e4e4e7);
 }
 
 .docs-article h3 {
@@ -216,8 +216,8 @@
 }
 
 .docs-tabs-header .docs-tab-active {
-  background: var(--background);
-  color: var(--foreground);
+  background: var(--background, #ffffff);
+  color: var(--foreground, #18181b);
   font-weight: 500;
 }
 
@@ -298,7 +298,7 @@
   border-radius: 12px;
   font-weight: 500;
   text-decoration: none !important;
-  color: var(--foreground) !important;
+  color: var(--foreground, #18181b) !important;
 }
 
 .docs-content-ref:hover {
@@ -463,7 +463,7 @@
   padding: 16px;
   border: 1px solid var(--gb-border);
   border-radius: 12px;
-  background: var(--background);
+  background: var(--background, #ffffff);
 }
 
 .docs-mermaid svg {
@@ -560,7 +560,7 @@
 }
 
 .oas-desc {
-  color: var(--foreground);
+  color: var(--foreground, #18181b);
   margin-bottom: 8px;
 }