@brett_lamy/docstream 0.5.3 → 0.5.5

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.3",
+  "version": "0.5.5",
   "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,6 +19,11 @@ 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>
@@ -327,7 +333,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/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/parse.ts

@@ -431,7 +431,6 @@ export function parseBlocks(lines: string[]): Block[] {
     const fence = trimmed.match(/^(`{3,}|~{3,})([^\s`]*)?(?:\s+(.*?))?\s*$/)
     if (fence) {
       flushParagraph()
-      const marker = fence[1][0]
       const attrs = parseAttrs(fence[3])
       const code: string[] = []
       i++

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

@@ -489,10 +489,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 {