@brett_lamy/docstream 0.5.4 → 0.5.6

package/README.md

@@ -236,6 +236,21 @@ plugin validates the mount boundary, only edits existing files, and notifies
 Vite after a save so the preview reloads through Vite's normal module pipeline.
 Set `writable: false` on a mount when a documentation site should only render.
 
+The Vite endpoints exist only during development. For a deployed static site,
+bundle the referenced modules and use the read-only production client:
+
+```tsx
+import { createBundledSourceClient } from "@brett_lamy/docstream"
+import * as ButtonModule from "./components/Button"
+
+const client = createBundledSourceClient({
+  "ui:Button.tsx": ButtonModule,
+})
+```
+
+Entries may also be lazy import functions. Keys can be `mount:path` (recommended)
+or just `path` when names cannot collide.
+
 ## Assets and OpenAPI Specs
 
 Relative image and OpenAPI spec paths can be resolved against an asset base:
@@ -258,6 +273,7 @@ You can also resolve paths yourself with `resolveAsset`.
 - `OpenApiOperation`: Renders a parsed OpenAPI operation block.
 - `SourcePreview`: Imports and renders a mounted component or CSF story export.
 - `createViteSourceClient`: Reads, writes, and imports files exposed by the Vite plugin.
+- `createBundledSourceClient`: Imports bundled source modules in read-only production builds.
 
 ### Parser and Serializer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
   "scripts": {
@@ -72,6 +72,7 @@
     "@brett_lamy/viz-engine": ">=0.2.0",
     "framer-motion": "^13.1.1",
     "hast-util-to-html": "^9.0.5",
+    "katex": "^0.18.5",
     "lowlight": "^3.3.0",
     "lucide-react": "^1.17.0",
     "mermaid": "^11.15.0",

package/src/docs/DocsRenderer.tsx

@@ -1,5 +1,6 @@
 import { useState, type ReactNode } from "react"
 import { LayoutGroup, motion } from "framer-motion"
+import "katex/dist/katex.min.css"
 import {
   AlertTriangle,
   CheckCircle2,
@@ -18,11 +19,18 @@ import { OpenApiOperation } from "../openapi/OpenApiOperation"
 import { Mermaid } from "./Mermaid"
 import { HighlightedCode } from "./HighlightedCode"
 import { CitationSources, InlineReference } from "./reference"
+import { renderMathToHtml } from "./math"
+
+function MathBlock({ formula }: { formula: string }) {
+  return <div className="docs-math" dangerouslySetInnerHTML={{ __html: renderMathToHtml(formula) }} />
+}
 
 export interface LivePreviewProps {
   files: Record<string, string>
   entry: string
   title: string
+  collapsedCodeLines?: number
+  expandedCodeLines?: number
 }
 
 export type LivePreviewRenderer = (props: LivePreviewProps) => ReactNode
@@ -140,13 +148,23 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
       )
     }
     case "code":
-      if (block.language === "mermaid") return <Mermaid code={block.code} />
+      if (block.language === "mermaid") {
+        return (
+          <Mermaid
+            code={block.code}
+            collapsedCodeLines={block.collapsedCodeLines}
+            expandedCodeLines={block.expandedCodeLines}
+          />
+        )
+      }
       if (block.live && isReactLanguage(block.language) && liveRenderer) {
         const entry = block.entry ?? "/src/main.jsx"
         return liveRenderer({
           files: { [entry]: block.code },
           entry,
           title: block.title ?? "Live React preview",
+          collapsedCodeLines: block.collapsedCodeLines,
+          expandedCodeLines: block.expandedCodeLines,
         })
       }
       return (
@@ -327,7 +345,7 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
         </table>
       )
     case "math":
-      return <pre className="docs-math">{block.formula}</pre>
+      return <MathBlock formula={block.formula} />
     case "updates":
       return (
         <div className="docs-updates">

package/src/docs/Mermaid.tsx

@@ -1,11 +1,26 @@
-import { useEffect, useRef, useState } from "react"
+import { useEffect, useId, useRef, useState, type CSSProperties } from "react"
+import { HighlightedCode } from "./HighlightedCode"
 
 let seq = 0
 
-export function Mermaid({ code }: { code: string }) {
+export interface MermaidProps {
+  code: string
+  collapsedCodeLines?: number
+  expandedCodeLines?: number
+}
+
+function positiveLineCount(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+}
+
+export function Mermaid({ code, collapsedCodeLines = 3, expandedCodeLines = 30 }: MermaidProps) {
   const [svg, setSvg] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
+  const [codeExpanded, setCodeExpanded] = useState(false)
   const idRef = useRef(`mermaid-${++seq}`)
+  const codePanelId = useId()
+  const collapsedLines = positiveLineCount(collapsedCodeLines, 3)
+  const expandedLines = Math.max(collapsedLines, positiveLineCount(expandedCodeLines, 30))
 
   useEffect(() => {
     let cancelled = false
@@ -23,15 +38,35 @@ export function Mermaid({ code }: { code: string }) {
     }
   }, [code])
 
-  if (error) {
-    return (
-      <pre className="docs-mermaid-error">
-        mermaid error: {error}
-        {"\n"}
-        {code}
-      </pre>
-    )
-  }
-  if (!svg) return <div className="docs-mermaid">Rendering diagram…</div>
-  return <div className="docs-mermaid" dangerouslySetInnerHTML={{ __html: svg }} />
+  return (
+    <section className="docs-mermaid-preview" data-docstream-mermaid="">
+      {error ? (
+        <pre className="docs-mermaid-error">mermaid error: {error}</pre>
+      ) : svg ? (
+        <div className="docs-mermaid" dangerouslySetInnerHTML={{ __html: svg }} />
+      ) : (
+        <div className="docs-mermaid">Rendering diagram…</div>
+      )}
+      <div className="docs-react-demo-code docs-mermaid-code">
+        <pre
+          id={codePanelId}
+          className={codeExpanded ? "docs-react-demo-code-body docs-react-demo-code-body-expanded" : "docs-react-demo-code-body"}
+          style={{
+            "--docs-react-demo-code-lines": codeExpanded ? expandedLines : collapsedLines,
+          } as CSSProperties}
+        >
+          <HighlightedCode code={code} language="mermaid" lineNumbers />
+        </pre>
+        <button
+          type="button"
+          className="docs-react-demo-code-toggle"
+          aria-controls={codePanelId}
+          aria-expanded={codeExpanded}
+          onClick={() => setCodeExpanded((value) => !value)}
+        >
+          {codeExpanded ? "Hide Code" : "View Code"}
+        </button>
+      </div>
+    </section>
+  )
 }

package/src/docs/math.ts

@@ -0,0 +1,9 @@
+import katex from "katex"
+
+export function renderMathToHtml(formula: string): string {
+  return katex.renderToString(formula, {
+    displayMode: true,
+    throwOnError: false,
+    output: "htmlAndMathml",
+  })
+}

package/src/gitbook/ast.ts

@@ -68,6 +68,10 @@ export interface CodeBlockNode {
   live?: boolean
   /** Project-relative entry file used by a live preview. */
   entry?: string | null
+  /** Source lines visible before an expandable code preview is opened. */
+  collapsedCodeLines?: number
+  /** Maximum source lines visible before expanded code scrolls. */
+  expandedCodeLines?: number
 }
 
 export interface HintNode {

package/src/gitbook/parse.ts

@@ -71,6 +71,12 @@ function booleanAttr(attrs: Record<string, string>, key: string): boolean | unde
   return attrs[key] !== "false"
 }
 
+function positiveNumberAttr(attrs: Record<string, string>, key: string): number | undefined {
+  if (!(key in attrs)) return undefined
+  const value = Number(attrs[key])
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined
+}
+
 interface TemplateTag {
   name: string
   attrs: Record<string, string>
@@ -447,6 +453,12 @@ export function parseBlocks(lines: string[]): Block[] {
         code: code.join("\n"),
         ...(booleanAttr(attrs, "live") === undefined ? {} : { live: booleanAttr(attrs, "live") }),
         ...(attrs.entry ? { entry: attrs.entry } : {}),
+        ...(positiveNumberAttr(attrs, "collapsedCodeLines") === undefined
+          ? {}
+          : { collapsedCodeLines: positiveNumberAttr(attrs, "collapsedCodeLines") }),
+        ...(positiveNumberAttr(attrs, "expandedCodeLines") === undefined
+          ? {}
+          : { expandedCodeLines: positiveNumberAttr(attrs, "expandedCodeLines") }),
       })
       continue
     }

package/src/gitbook/serialize.ts

@@ -39,6 +39,8 @@ function serializeBlock(b: Block): string {
         !b.lineNumbers ? `lineNumbers="false"` : "",
         b.live ? `live="true"` : "",
         b.entry ? `entry="${b.entry}"` : "",
+        b.collapsedCodeLines ? `collapsedCodeLines="${b.collapsedCodeLines}"` : "",
+        b.expandedCodeLines ? `expandedCodeLines="${b.expandedCodeLines}"` : "",
       ].filter(Boolean)
       const info = [b.language ?? "", ...attrs].filter(Boolean).join(" ")
       return `\`\`\`${info}\n${b.code}\n\`\`\``

package/src/index.ts

@@ -36,8 +36,9 @@ export type {
   ReactDemoProps,
 } from "./playground"
 export { resolveAsset, setAssetBase } from "./assets"
-export { createViteSourceClient, SourcePreview } from "./source"
+export { createBundledSourceClient, createViteSourceClient, SourcePreview } from "./source"
 export type {
+  BundledSourceModule,
   SourceFileSnapshot,
   SourceModule,
   SourcePreviewProps,

package/src/playground/PlaygroundStreamdown.tsx

@@ -29,8 +29,14 @@ export function PlaygroundStreamdown({
     () => parseMarkdown(isStreaming ? trimPartialInlineToken(content) : content),
     [content, isStreaming]
   )
-  const liveRenderer: LivePreviewRenderer = ({ files, entry, title }) => (
-    <ReactCodePreview files={files} entry={entry} title={title} />
+  const liveRenderer: LivePreviewRenderer = ({ files, entry, title, collapsedCodeLines, expandedCodeLines }) => (
+    <ReactCodePreview
+      files={files}
+      entry={entry}
+      title={title}
+      collapsedCodeLines={collapsedCodeLines}
+      expandedCodeLines={expandedCodeLines}
+    />
   )
 
   return (

package/src/source/client.ts

@@ -1,6 +1,8 @@
 import type { SourceRefNode } from "../gitbook/ast"
 import type { SourceFileSnapshot, SourceReferenceClient, SourceModule } from "./types"
 
+export type BundledSourceModule = SourceModule | (() => SourceModule | Promise<SourceModule>)
+
 function params(reference: SourceRefNode): URLSearchParams {
   return new URLSearchParams({
     mount: reference.mount,
@@ -38,3 +40,20 @@ export function createViteSourceClient(apiBase = "/@docstream"): SourceReference
     },
   }
 }
+
+/** Create a read-only source client for modules included in a production bundle. */
+export function createBundledSourceClient(modules: Record<string, BundledSourceModule>): SourceReferenceClient {
+  return {
+    async read() {
+      throw new Error("Source text is unavailable in a bundled source client.")
+    },
+    async write() {
+      throw new Error("Bundled source previews are read-only.")
+    },
+    async importModule(reference) {
+      const entry = modules[`${reference.mount}:${reference.path}`] ?? modules[reference.path]
+      if (!entry) throw new Error(`No bundled source module found for ${reference.mount}:${reference.path}`)
+      return typeof entry === "function" ? entry() : entry
+    },
+  }
+}

package/src/source/index.ts

@@ -1,4 +1,5 @@
-export { createViteSourceClient } from "./client"
+export { createBundledSourceClient, createViteSourceClient } from "./client"
+export type { BundledSourceModule } from "./client"
 export { SourcePreview } from "./SourcePreview"
 export type { SourcePreviewProps } from "./SourcePreview"
 export type {

package/src/styles.css

@@ -123,15 +123,29 @@
   padding-left: 1.5em;
 }
 
-.docs-article .docs-tasklist {
+.docs-tasklist {
   list-style: none;
   padding-left: 0.2em;
 }
 
-.docs-article .docs-tasklist li {
+.docs-tasklist li {
   display: flex;
   gap: 8px;
-  align-items: baseline;
+  align-items: flex-start;
+}
+
+.docs-tasklist li > input {
+  flex: 0 0 auto;
+  margin-top: 0.45em;
+}
+
+.docs-tasklist .docs-blocks-inline {
+  flex: 1;
+  min-width: 0;
+}
+
+.docs-tasklist .docs-blocks-inline > p:first-child {
+  margin: 0;
 }
 
 .docs-article blockquote {
@@ -489,10 +503,12 @@
   border-radius: 12px;
   padding: 14px 16px;
   background: var(--gb-muted);
-  font-family: ui-monospace, Menlo, monospace;
-  font-size: 13.5px;
   text-align: center;
-  white-space: pre-wrap;
+  overflow-x: auto;
+}
+
+.docs-math .katex-display {
+  margin: 0;
 }
 
 .docs-updates {
@@ -547,12 +563,16 @@
   margin-top: 4px;
 }
 
+.docs-mermaid-preview {
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  overflow: hidden;
+}
+
 .docs-mermaid {
   display: flex;
   justify-content: center;
   padding: 16px;
-  border: 1px solid var(--gb-border);
-  border-radius: 12px;
   background: var(--background, #ffffff);
 }
 
@@ -561,14 +581,17 @@
 }
 
 .docs-mermaid-error {
+  margin: 0;
   font-size: 12px;
   color: var(--gb-danger);
-  border: 1px solid var(--gb-border);
-  border-radius: 8px;
   padding: 10px;
   white-space: pre-wrap;
 }
 
+.docs-mermaid-code {
+  border-top: 1px solid var(--gb-border);
+}
+
 .docs-inline-img {
   display: inline-block;
   vertical-align: middle;