@brett_lamy/docstream 0.3.5 → 0.3.7

package/README.md

@@ -14,6 +14,7 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 - 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.
+- Vite source mounts for rendering and editing real component or Storybook files without copying implementations into Markdown.
 
 ## Installation
 
@@ -182,6 +183,59 @@ import "@brett_lamy/docstream/styles.css"
 VizEngine, so a reader can pause or scrub the same explanation used to produce
 the short clip.
 
+### File-backed components and stories
+
+Markdown is the composition layer. Keep component and Storybook implementations
+in normal source files, then mount their directory in Vite:
+
+```ts
+// vite.config.ts
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+import { docstreamSources } from "@brett_lamy/docstream/vite"
+
+export default defineConfig({
+  plugins: [
+    react(),
+    docstreamSources({
+      mounts: [{ name: "ui", root: "src/components" }],
+    }),
+  ],
+})
+```
+
+Reference a named component export or a CSF story from Markdown:
+
+```md
+{% source-ref mount="ui" path="Button.tsx" export="Button" kind="component" title="Button" %}
+
+{% source-ref mount="ui" path="Button.stories.tsx" export="Primary" kind="story" title="Primary button" %}
+```
+
+Render references using the Vite client. The AST keeps `mount`, `path`,
+`exportName`, and `kind`, so provenance survives parse/edit/serialize cycles:
+
+```tsx
+import { MarkdownContent, SourcePreview, createViteSourceClient } from "@brett_lamy/docstream"
+
+const client = createViteSourceClient()
+
+export function Guide({ markdown }: { markdown: string }) {
+  return (
+    <MarkdownContent
+      markdown={markdown}
+      sourceRenderer={(reference) => <SourcePreview reference={reference} client={client} />}
+    />
+  )
+}
+```
+
+`client.read(reference)` returns the current file plus provenance.
+`client.write(reference, content)` writes back to the mounted real file. The
+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.
+
 ## Assets and OpenAPI Specs
 
 Relative image and OpenAPI spec paths can be resolved against an asset base:
@@ -202,6 +256,8 @@ You can also resolve paths yourself with `resolveAsset`.
 - `DocsRenderer`: Renders a parsed `DocumentNode`.
 - `MarkdownContent`: Parses and renders a markdown string.
 - `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.
 
 ### Parser and Serializer
 

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "type": "module",
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "files": [
     "src",
+    "!src/**/*.test.ts",
     "README.md"
   ],
   "sideEffects": [
@@ -49,6 +54,14 @@
       "types": "./src/playground/index.ts",
       "import": "./src/playground/index.ts"
     },
+    "./source": {
+      "types": "./src/source/index.ts",
+      "import": "./src/source/index.ts"
+    },
+    "./vite": {
+      "types": "./src/vite/index.ts",
+      "import": "./src/vite/index.ts"
+    },
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
@@ -64,7 +77,13 @@
   "peerDependencies": {
     "@agent-wasm/core": ">=0.4.0",
     "@brett_lamy/viz-engine": ">=0.2.0",
-    "react": ">=18"
+    "react": ">=18",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
@@ -72,7 +91,10 @@
   },
   "devDependencies": {
     "@agent-wasm/core": "^0.4.0",
+    "@types/node": "^24.0.0",
     "@types/react": "^18.3.3",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vite": "^7.0.0",
+    "vitest": "^3.2.4"
   }
 }

package/src/docs/DocsRenderer.tsx

@@ -8,7 +8,7 @@ import {
   XCircle,
 } from "lucide-react"
 
-import type { Block, DocumentNode, Inline } from "../gitbook/ast"
+import type { Block, DocumentNode, Inline, SourceRefNode } from "../gitbook/ast"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
 import { ReplayPreview, isReplayQaUrl } from "../replay"
@@ -25,6 +25,8 @@ export interface LivePreviewProps {
 
 export type LivePreviewRenderer = (props: LivePreviewProps) => ReactNode
 
+export type SourceReferenceRenderer = (reference: SourceRefNode) => ReactNode
+
 function InlineText({ nodes }: { nodes: Inline[] }) {
   return (
     <>
@@ -79,7 +81,12 @@ function isDirectVideo(url: string): boolean {
   return /\.(?:mp4|webm|ogg)(?:[?#]|$)/i.test(url)
 }
 
-function Tabs({ block, liveRenderer }: { block: Extract<Block, { type: "tabs" }>; liveRenderer?: LivePreviewRenderer }) {
+interface Renderers {
+  liveRenderer?: LivePreviewRenderer
+  sourceRenderer?: SourceReferenceRenderer
+}
+
+function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, { type: "tabs" }> } & Renderers) {
   const [active, setActive] = useState(0)
   return (
     <div className="docs-tabs">
@@ -95,13 +102,13 @@ function Tabs({ block, liveRenderer }: { block: Extract<Block, { type: "tabs" }>
         ))}
       </div>
       <div className="docs-tabs-body">
-        <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} />
+        <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       </div>
     </div>
   )
 }
 
-function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LivePreviewRenderer }) {
+function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & Renderers) {
   switch (block.type) {
     case "paragraph":
       return (
@@ -150,19 +157,19 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
         <div className={`docs-hint docs-hint-${block.style}`}>
           <Icon className="docs-hint-icon" />
           <div>
-            <Blocks blocks={block.children} liveRenderer={liveRenderer} />
+            <Blocks blocks={block.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
           </div>
         </div>
       )
     }
     case "tabs":
-      return <Tabs block={block} liveRenderer={liveRenderer} />
+      return <Tabs block={block} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
     case "expandable":
       return (
         <details className="docs-expandable">
           <summary>{block.summary}</summary>
           <div className="docs-expandable-body">
-            <Blocks blocks={block.children} liveRenderer={liveRenderer} />
+            <Blocks blocks={block.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
           </div>
         </details>
       )
@@ -177,7 +184,7 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
               </div>
               <div className="docs-step-main">
                 {s.title && <div className="docs-step-title">{s.title}</div>}
-                <Blocks blocks={s.children} liveRenderer={liveRenderer} />
+                <Blocks blocks={s.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
               </div>
             </div>
           ))}
@@ -215,12 +222,22 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
           <ChevronRight className="size-4 ml-auto" />
         </a>
       )
+    case "source-ref":
+      return sourceRenderer ? (
+        sourceRenderer(block)
+      ) : (
+        <div className="docs-source-ref" data-docstream-source-ref="">
+          <File className="size-4" />
+          <span>{block.title ?? `${block.path}#${block.exportName}`}</span>
+          <code>{block.mount}:{block.path}</code>
+        </div>
+      )
     case "columns":
       return (
         <div className="docs-columns">
           {block.columns.map((c, i) => (
             <div key={i} className="docs-column">
-              <Blocks blocks={c.children} liveRenderer={liveRenderer} />
+              <Blocks blocks={c.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
             </div>
           ))}
         </div>
@@ -239,7 +256,7 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
           {block.items.map((item, i) => (
             <li key={i}>
               {block.task && <input type="checkbox" checked={!!item.checked} readOnly />}
-              <Blocks blocks={item.children} inline liveRenderer={liveRenderer} />
+              <Blocks blocks={item.children} inline liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
             </li>
           ))}
         </Tag>
@@ -248,7 +265,7 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
     case "blockquote":
       return (
         <blockquote>
-          <Blocks blocks={block.children} liveRenderer={liveRenderer} />
+          <Blocks blocks={block.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
         </blockquote>
       )
     case "divider":
@@ -303,7 +320,7 @@ function BlockView({ block, liveRenderer }: { block: Block; liveRenderer?: LiveP
             <div key={i} className="docs-update">
               <div className="docs-update-date">{u.date}</div>
               <div className="docs-update-body">
-                <Blocks blocks={u.children} liveRenderer={liveRenderer} />
+                <Blocks blocks={u.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
               </div>
             </div>
           ))}
@@ -324,11 +341,11 @@ function isReactLanguage(language: string | null): boolean {
   return language === "jsx" || language === "tsx" || language === "react"
 }
 
-function Blocks({ blocks, inline, liveRenderer }: { blocks: Block[]; inline?: boolean; liveRenderer?: LivePreviewRenderer }) {
+function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Block[]; inline?: boolean } & Renderers) {
   return (
     <div className={inline ? "docs-blocks-inline" : undefined} style={inline ? { display: "inline" } : undefined}>
       {blocks.map((b, i) => (
-        <BlockView key={i} block={b} liveRenderer={liveRenderer} />
+        <BlockView key={i} block={b} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       ))}
     </div>
   )
@@ -339,19 +356,20 @@ function Blocks({ blocks, inline, liveRenderer }: { blocks: Block[]; inline?: bo
 export function MarkdownContent({
   markdown,
   liveRenderer,
+  sourceRenderer,
   className,
-}: { markdown: string; liveRenderer?: LivePreviewRenderer; className?: string }) {
+}: { markdown: string; className?: string } & Renderers) {
   return (
     <div data-docstream="" className={className}>
-      <Blocks blocks={parseMarkdown(markdown).children} liveRenderer={liveRenderer} />
+      <Blocks blocks={parseMarkdown(markdown).children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
     </div>
   )
 }
 
-export function DocsRenderer({ doc, liveRenderer }: { doc: DocumentNode; liveRenderer?: LivePreviewRenderer }) {
+export function DocsRenderer({ doc, liveRenderer, sourceRenderer }: { doc: DocumentNode } & Renderers) {
   return (
     <article className="docs-article">
-      <Blocks blocks={doc.children} liveRenderer={liveRenderer} />
+      <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
     </article>
   )
 }

package/src/gitbook/ast.ts

@@ -99,6 +99,24 @@ export interface ContentRefNode {
   children: Inline[]
 }
 
+export type SourceReferenceKind = "component" | "story"
+
+/**
+ * A reference to an export in a real source file. The source file remains the
+ * authority; Markdown only stores the composition and presentation metadata.
+ */
+export interface SourceRefNode {
+  type: "source-ref"
+  /** Name of the directory mounted by the Docstream Vite plugin. */
+  mount: string
+  /** POSIX-style path relative to the mounted source directory. */
+  path: string
+  /** Named export to render. Defaults to `default`. */
+  exportName: string
+  kind: SourceReferenceKind
+  title?: string
+}
+
 export interface ColumnNode {
   type: "column"
   children: Block[]
@@ -182,6 +200,7 @@ export type Block =
   | StepperNode
   | EmbedNode
   | ContentRefNode
+  | SourceRefNode
   | ColumnsNode
   | FigureNode
   | ListNode

package/src/gitbook/parse.ts

@@ -234,6 +234,21 @@ export function parseBlocks(lines: string[]): Block[] {
         continue
       }
 
+      if (tag.name === "source-ref" || tag.name === "component" || tag.name === "story") {
+        const kind = tag.name === "story" || tag.attrs.kind === "story" ? "story" : "component"
+        blocks.push({
+          type: "source-ref",
+          mount: tag.attrs.mount ?? "source",
+          path: tag.attrs.path ?? tag.attrs.src ?? "",
+          exportName: tag.attrs.export ?? (kind === "story" ? "Primary" : "default"),
+          kind,
+          ...(tag.attrs.title ? { title: tag.attrs.title } : {}),
+        })
+        i++
+        if (i < lines.length && templateTag(lines[i])?.name === `end${tag.name}`) i++
+        continue
+      }
+
       if (tag.name === "updates") {
         const { body, next } = collectUntil(lines, i + 1, "updates")
         blocks.push({

package/src/gitbook/serialize.ts

@@ -76,6 +76,17 @@ function serializeBlock(b: Block): string {
     case "content-ref":
       return `{% content-ref url="${b.url}" %}\n${serializeInline(b.children)}\n{% endcontent-ref %}`
 
+    case "source-ref": {
+      const attrs = [
+        ` mount="${b.mount}"`,
+        ` path="${b.path}"`,
+        ` export="${b.exportName}"`,
+        ` kind="${b.kind}"`,
+        b.title ? ` title="${b.title}"` : "",
+      ].join("")
+      return `{% source-ref${attrs} %}`
+    }
+
     case "columns":
       return `{% columns %}\n${b.columns
         .map((c) => `{% column %}\n${serializeBlocks(c.children)}\n{% endcolumn %}`)

package/src/index.ts

@@ -1,6 +1,7 @@
 export { PlaygroundStreamdown as GitbookStreamdown } from "./playground/PlaygroundStreamdown"
 export type { PlaygroundStreamdownProps as GitbookStreamdownProps } from "./playground/PlaygroundStreamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
+export type { LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { ReplayEmbed, ReplayPreview } from "./replay"
 export type {
   ReplayEventsSource,
@@ -33,6 +34,14 @@ export type {
   ReactDemoProps,
 } from "./playground"
 export { resolveAsset, setAssetBase } from "./assets"
+export { createViteSourceClient, SourcePreview } from "./source"
+export type {
+  SourceFileSnapshot,
+  SourceModule,
+  SourcePreviewProps,
+  SourceProvenance,
+  SourceReferenceClient,
+} from "./source"
 export { parseMarkdown, parseBlocks } from "./gitbook/parse"
 export { serializeBlocks, serializeMarkdown } from "./gitbook/serialize"
 export { parseInline, plainText, refDefinitions, serializeInline } from "./gitbook/inline"

package/src/playground/ReactCodePreview.tsx

@@ -4,6 +4,7 @@ import {
   createReactDemoFiles,
   type AlmostNodeFiles,
   type AlmostNodeWorkspace,
+  type AlmostNodeWorkspaceOptions,
 } from "./filesystem"
 
 export interface ReactDemoProps {
@@ -21,6 +22,8 @@ export interface ReactDemoProps {
   autoStart?: boolean
   /** iframe sandbox value. The same-origin permission lets the almost-node service worker route the preview. */
   sandbox?: string
+  /** Extra options spread into `createAlmostNodeWorkspace` (e.g. `basePath` for static hosting). */
+  workspaceOptions?: Partial<AlmostNodeWorkspaceOptions>
   className?: string
   onReady?: (url: string) => void
   onError?: (error: Error) => void
@@ -49,6 +52,7 @@ export function ReactDemo({
   title = "Live React preview",
   autoStart = true,
   sandbox = "allow-scripts allow-same-origin allow-forms allow-modals",
+  workspaceOptions,
   className,
   onReady,
   onError,
@@ -77,9 +81,11 @@ export function ReactDemo({
       try {
         const projectFiles = createReactDemoFiles(files, { entry })
         workspace = await createAlmostNodeWorkspace(projectFiles, {
-          env: DETACHED_SERVER_ENV,
-          onServerReady: (_port, serverUrl) => {
+          ...workspaceOptions,
+          env: { ...DETACHED_SERVER_ENV, ...workspaceOptions?.env },
+          onServerReady: (serverPort, serverUrl) => {
             readyUrl = serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`
+            workspaceOptions?.onServerReady?.(serverPort, serverUrl)
           },
         })
 
@@ -114,7 +120,7 @@ export function ReactDemo({
       cancelled = true
       workspace?.dispose()
     }
-  }, [entry, files, onError, onReady, port, run])
+  }, [entry, files, onError, onReady, port, run, workspaceOptions])
 
   const wrapperClass = className ? `docs-react-demo ${className}` : "docs-react-demo"
   const running = state === "starting"

package/src/source/SourcePreview.tsx

@@ -0,0 +1,69 @@
+import { createElement, useEffect, useState, type ComponentType, type ReactNode } from "react"
+import type { SourceRefNode } from "../gitbook/ast"
+import type { SourceModule, SourceReferenceClient, StoryLike, StoryMetaLike } from "./types"
+
+export interface SourcePreviewProps {
+  reference: SourceRefNode
+  client: SourceReferenceClient
+  className?: string
+  fallback?: ReactNode
+  onError?: (error: Error) => void
+}
+
+function componentFrom(module: SourceModule, reference: SourceRefNode): { component: ComponentType<Record<string, unknown>>; props: Record<string, unknown> } {
+  if (reference.kind === "component") {
+    const candidate = reference.exportName === "default" ? module.default : module[reference.exportName]
+    if (typeof candidate !== "function") throw new Error(`${reference.path} does not export component ${reference.exportName}`)
+    return { component: candidate as ComponentType<Record<string, unknown>>, props: {} }
+  }
+
+  const meta = (module.default ?? {}) as StoryMetaLike
+  const story = module[reference.exportName] as StoryLike | undefined
+  if (!story) throw new Error(`${reference.path} does not export story ${reference.exportName}`)
+  const component = story.render ?? meta.render ?? meta.component
+  if (typeof component !== "function") throw new Error(`${reference.path}#${reference.exportName} has no renderable component`)
+  return {
+    component: component as ComponentType<Record<string, unknown>>,
+    props: { ...(meta.args ?? {}), ...(story.args ?? {}) },
+  }
+}
+
+/** Render a component or CSF story directly from a Vite-mounted source file. */
+export function SourcePreview({ reference, client, className, fallback = "Loading source…", onError }: SourcePreviewProps) {
+  const [renderable, setRenderable] = useState<ReturnType<typeof componentFrom> | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setRenderable(null)
+    setError(null)
+    void client.importModule(reference).then(
+      (module) => {
+        if (!cancelled) setRenderable(componentFrom(module, reference))
+      },
+      (cause: unknown) => {
+        const next = cause instanceof Error ? cause : new Error(String(cause))
+        if (!cancelled) {
+          setError(next)
+          onError?.(next)
+        }
+      },
+    )
+    return () => {
+      cancelled = true
+    }
+  }, [client, onError, reference])
+
+  const wrapper = className ? `docs-source-preview ${className}` : "docs-source-preview"
+  return (
+    <section className={wrapper} data-docstream-source-preview="" data-source-path={reference.path}>
+      <header className="docs-source-preview-header">
+        <span>{reference.title ?? `${reference.path}#${reference.exportName}`}</span>
+        <code>{reference.mount}:{reference.path}</code>
+      </header>
+      <div className="docs-source-preview-body">
+        {error ? <pre className="docs-source-preview-error">{error.message}</pre> : renderable ? createElement(renderable.component, renderable.props) : fallback}
+      </div>
+    </section>
+  )
+}

package/src/source/client.ts

@@ -0,0 +1,40 @@
+import type { SourceRefNode } from "../gitbook/ast"
+import type { SourceFileSnapshot, SourceReferenceClient, SourceModule } from "./types"
+
+function params(reference: SourceRefNode): URLSearchParams {
+  return new URLSearchParams({
+    mount: reference.mount,
+    path: reference.path,
+    export: reference.exportName,
+    kind: reference.kind,
+  })
+}
+
+async function json<T>(response: Response): Promise<T> {
+  if (!response.ok) throw new Error((await response.text()) || `Docstream source request failed (${response.status})`)
+  return response.json() as Promise<T>
+}
+
+/** Create a browser client for the endpoints installed by `docstreamSources()`. */
+export function createViteSourceClient(apiBase = "/@docstream"): SourceReferenceClient {
+  const base = apiBase.replace(/\/$/, "")
+  return {
+    async read(reference) {
+      return json<SourceFileSnapshot>(await fetch(`${base}/source?${params(reference)}`))
+    },
+    async write(reference, content) {
+      return json<SourceFileSnapshot>(
+        await fetch(`${base}/source?${params(reference)}`, {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ content }),
+        }),
+      )
+    },
+    async importModule(reference) {
+      const url = `${base}/module?${params(reference)}&t=${Date.now()}`
+      const loaded = await import(/* @vite-ignore */ url) as { default?: SourceModule }
+      return loaded.default ?? (loaded as SourceModule)
+    },
+  }
+}

package/src/source/index.ts

@@ -0,0 +1,11 @@
+export { createViteSourceClient } from "./client"
+export { SourcePreview } from "./SourcePreview"
+export type { SourcePreviewProps } from "./SourcePreview"
+export type {
+  SourceFileSnapshot,
+  SourceModule,
+  SourceProvenance,
+  SourceReferenceClient,
+  StoryLike,
+  StoryMetaLike,
+} from "./types"

package/src/source/types.ts

@@ -0,0 +1,38 @@
+import type { ComponentType } from "react"
+import type { SourceRefNode } from "../gitbook/ast"
+
+export interface SourceProvenance {
+  mount: string
+  path: string
+  exportName: string
+  kind: SourceRefNode["kind"]
+  absolutePath?: string
+  mtimeMs?: number
+}
+
+export interface SourceFileSnapshot {
+  content: string
+  provenance: SourceProvenance
+}
+
+export interface SourceModule {
+  default?: unknown
+  [exportName: string]: unknown
+}
+
+export interface SourceReferenceClient {
+  read(reference: SourceRefNode): Promise<SourceFileSnapshot>
+  write(reference: SourceRefNode, content: string): Promise<SourceFileSnapshot>
+  importModule(reference: SourceRefNode): Promise<SourceModule>
+}
+
+export interface StoryLike {
+  args?: Record<string, unknown>
+  render?: ComponentType<Record<string, unknown>> | ((args: Record<string, unknown>) => unknown)
+}
+
+export interface StoryMetaLike {
+  args?: Record<string, unknown>
+  component?: ComponentType<Record<string, unknown>>
+  render?: ComponentType<Record<string, unknown>> | ((args: Record<string, unknown>) => unknown)
+}

package/src/styles.css

@@ -32,6 +32,42 @@
   --gb-danger-bg: rgba(239, 68, 68, 0.1);
 }
 
+.docs-source-ref,
+.docs-source-preview-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.docs-source-ref,
+.docs-source-preview {
+  border: 1px solid var(--gb-border);
+  border-radius: var(--gb-radius);
+  overflow: hidden;
+}
+
+.docs-source-ref,
+.docs-source-preview-header {
+  padding: 0.65rem 0.8rem;
+  background: var(--gb-muted);
+}
+
+.docs-source-ref code,
+.docs-source-preview-header code {
+  margin-left: auto;
+  color: var(--gb-muted-foreground);
+  font-size: 0.75rem;
+}
+
+.docs-source-preview-body {
+  padding: 1rem;
+}
+
+.docs-source-preview-error {
+  color: var(--gb-danger-foreground, #b42318);
+  white-space: pre-wrap;
+}
+
 .docs-article {
   max-width: 760px;
   margin: 0 auto;

package/src/vite/index.ts

@@ -0,0 +1,165 @@
+import { promises as fs } from "node:fs"
+import path from "node:path"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import type { Plugin, ViteDevServer } from "vite"
+
+export interface DocstreamSourceMount {
+  /** Stable name used by Markdown source references. */
+  name: string
+  /** Real source directory. Relative paths are resolved from the Vite root. */
+  root: string
+  /** Allow PUT requests to edit files in this mount. Defaults to true. */
+  writable?: boolean
+}
+
+export interface DocstreamSourcesOptions {
+  mounts: readonly DocstreamSourceMount[]
+  /** HTTP endpoint prefix. Defaults to `/@docstream`. */
+  apiBase?: string
+}
+
+interface ResolvedMount {
+  name: string
+  root: string
+  writable: boolean
+}
+
+const VIRTUAL_ID = "virtual:docstream-sources"
+const RESOLVED_VIRTUAL_ID = "\0virtual:docstream-sources"
+
+function send(response: ServerResponse, status: number, body: string, type = "application/json; charset=utf-8") {
+  response.statusCode = status
+  response.setHeader("content-type", type)
+  response.setHeader("cache-control", "no-store")
+  response.end(body)
+}
+
+function requestUrl(request: IncomingMessage): URL {
+  return new URL(request.url ?? "/", "http://docstream.local")
+}
+
+async function requestBody(request: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+  return Buffer.concat(chunks).toString("utf8")
+}
+
+function normalizeRelativePath(value: string): string {
+  const source = value.replaceAll("\\", "/").replace(/^\.\//, "")
+  if (!source || source.startsWith("/") || source.split("/").some((part) => part === ".." || part === "")) {
+    throw new Error(`Invalid mounted source path: ${value}`)
+  }
+  return source
+}
+
+function sourcePath(mount: ResolvedMount, requestedPath: string): { relativePath: string; absolutePath: string } {
+  const relativePath = normalizeRelativePath(requestedPath)
+  const absolutePath = path.resolve(mount.root, relativePath)
+  const prefix = mount.root.endsWith(path.sep) ? mount.root : `${mount.root}${path.sep}`
+  if (!absolutePath.startsWith(prefix)) throw new Error(`Source path escapes mount ${mount.name}: ${requestedPath}`)
+  return { relativePath, absolutePath }
+}
+
+function provenance(url: URL, mount: ResolvedMount, relativePath: string, absolutePath: string, mtimeMs: number) {
+  return {
+    mount: mount.name,
+    path: relativePath,
+    exportName: url.searchParams.get("export") || "default",
+    kind: url.searchParams.get("kind") === "story" ? "story" : "component",
+    absolutePath,
+    mtimeMs,
+  }
+}
+
+function findMount(url: URL, mounts: readonly ResolvedMount[]): ResolvedMount {
+  const name = url.searchParams.get("mount") ?? ""
+  const mount = mounts.find((candidate) => candidate.name === name)
+  if (!mount) throw new Error(`Unknown Docstream source mount: ${name}`)
+  return mount
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function installMiddleware(server: ViteDevServer, apiBase: string, viteBase: string, mounts: readonly ResolvedMount[]) {
+  server.middlewares.use(async (request, response, next) => {
+    const url = requestUrl(request)
+    if (url.pathname !== `${apiBase}/source` && url.pathname !== `${apiBase}/module`) return next()
+
+    try {
+      const mount = findMount(url, mounts)
+      const requestedPath = url.searchParams.get("path") ?? ""
+      const { relativePath, absolutePath } = sourcePath(mount, requestedPath)
+
+      if (url.pathname === `${apiBase}/module`) {
+        if (request.method !== "GET") return send(response, 405, "Method not allowed", "text/plain; charset=utf-8")
+        await fs.access(absolutePath)
+        const sourceUrl = `${viteBase.replace(/\/$/, "")}/@fs/${absolutePath.replaceAll(path.sep, "/")}?docstream=${Date.now()}`
+        const module = `import * as source from ${JSON.stringify(sourceUrl)};\nexport default source;\n`
+        return send(response, 200, module, "text/javascript; charset=utf-8")
+      }
+
+      if (request.method === "GET") {
+        const [content, stat] = await Promise.all([fs.readFile(absolutePath, "utf8"), fs.stat(absolutePath)])
+        return send(response, 200, JSON.stringify({ content, provenance: provenance(url, mount, relativePath, absolutePath, stat.mtimeMs) }))
+      }
+
+      if (request.method === "PUT") {
+        if (!mount.writable) return send(response, 403, `Source mount ${mount.name} is read-only`, "text/plain; charset=utf-8")
+        await fs.access(absolutePath)
+        const parsed = JSON.parse(await requestBody(request)) as { content?: unknown }
+        if (typeof parsed.content !== "string") return send(response, 400, "Expected a JSON string field named content", "text/plain; charset=utf-8")
+        await fs.writeFile(absolutePath, parsed.content, "utf8")
+        const stat = await fs.stat(absolutePath)
+        server.watcher.add(absolutePath)
+        server.ws.send({ type: "full-reload", path: "*" })
+        return send(response, 200, JSON.stringify({ content: parsed.content, provenance: provenance(url, mount, relativePath, absolutePath, stat.mtimeMs) }))
+      }
+
+      return send(response, 405, "Method not allowed", "text/plain; charset=utf-8")
+    } catch (error) {
+      const status = error && typeof error === "object" && "code" in error && (error as { code?: string }).code === "ENOENT" ? 404 : 400
+      return send(response, status, errorMessage(error), "text/plain; charset=utf-8")
+    }
+  })
+}
+
+/**
+ * Mount real source directories behind safe Vite dev-server endpoints.
+ * Markdown references import live modules from these files, and editor writes
+ * go back to disk so Vite's normal watcher/HMR pipeline remains authoritative.
+ */
+export function docstreamSources(options: DocstreamSourcesOptions): Plugin {
+  const apiBase = `/${(options.apiBase ?? "/@docstream").replace(/^\/+|\/+$/g, "")}`
+  let mounts: ResolvedMount[] = []
+  let viteBase = "/"
+
+  return {
+    name: "docstream-sources",
+    enforce: "pre",
+    configResolved(config) {
+      viteBase = config.base || "/"
+      const names = new Set<string>()
+      mounts = options.mounts.map((mount) => {
+        if (!mount.name || names.has(mount.name)) throw new Error(`Docstream source mount names must be unique: ${mount.name}`)
+        names.add(mount.name)
+        return {
+          name: mount.name,
+          root: path.resolve(config.root, mount.root),
+          writable: mount.writable !== false,
+        }
+      })
+    },
+    configureServer(server) {
+      installMiddleware(server, apiBase, viteBase, mounts)
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_VIRTUAL_ID
+    },
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_ID) return
+      return `export const apiBase = ${JSON.stringify(apiBase)};\nexport const mounts = ${JSON.stringify(options.mounts.map(({ name, writable = true }) => ({ name, writable })))};\n`
+    },
+  }
+}