@brett_lamy/docstream 1.3.0 → 1.5.0

package/src/demo/clipboard.ts

@@ -0,0 +1,228 @@
+/* Copy / paste of docstream content that contains `{% demo %}` blocks.
+
+   A copy writes one clipboard item with three representations (react-aria `DragItem` shape,
+   so `useClipboard` / `useDrag` can write it; `writeDocstreamClipboard` writes it to a raw
+   `DataTransfer`):
+
+   - `text/plain` and `text/markdown`: renderable docstream Markdown — every demo carries its
+     files inline (`{% demo … %}` + titled fences + `{% enddemo %}`), resolver files included,
+     so pasting it anywhere (a docs page, an LLM, another editor) still renders;
+   - `application/x-docstream+json` (`DOCSTREAM_CLIPBOARD_TYPE`): a `DocstreamClipboardPayload`
+     — the exact Markdown (src-only demos stay src-only), plus every demo's files and meta by
+     `src`, so a docstream editor can restore the structure and register the files in its
+     `DemoVFS`. */
+import type { DemoNode, DocumentNode } from "../gitbook/ast"
+import { parseMarkdown } from "../gitbook/parse"
+import { serializeMarkdown } from "../gitbook/serialize"
+import { inlineDemoNode, toInlineFiles } from "./markdown"
+import { cssToSurface } from "./surface"
+import type { DemoFile, DemoMeta } from "./types"
+
+export const DOCSTREAM_CLIPBOARD_TYPE = "application/x-docstream+json"
+
+export interface DocstreamClipboardPayload {
+  /** Always `"docstream"`. */
+  kind: "docstream"
+  version: 1
+  /** The copied content as docstream Markdown, structure exactly as it was. */
+  markdown: string
+  /** Every demo's files by `src` (inline files, or the resolver's for src-only demos). */
+  files: Record<string, DemoFile[]>
+  /** `meta.json`-style defaults by `src` (the resolver's meta, else the tag's attributes). */
+  meta: Record<string, DemoMeta>
+}
+
+/** A demo's files (and meta) as the copying side knows them. */
+export interface DemoSourceSnapshot {
+  files: DemoFile[]
+  meta?: DemoMeta
+}
+
+export interface DocstreamClipboard {
+  payload: DocstreamClipboardPayload
+  /** The renderable Markdown (demos inlined) written as `text/plain` / `text/markdown`. */
+  text: string
+}
+
+/** A react-aria `DragItem`: one representation per MIME type. */
+export type DocstreamClipboardItem = Record<string, string>
+
+/** Every `{% demo %}` node in a document (inside tabs, hints, lists …), in document order. */
+export function collectDemoNodes(doc: DocumentNode): DemoNode[] {
+  const out: DemoNode[] = []
+  const walk = (value: unknown) => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item)
+      return
+    }
+    if (!value || typeof value !== "object") return
+    const node = value as { type?: unknown }
+    if (node.type === "demo") {
+      out.push(value as DemoNode)
+      return
+    }
+    for (const child of Object.values(value)) if (child && typeof child === "object") walk(child)
+  }
+  walk(doc.children)
+  return out
+}
+
+/** A copy of `doc` with every demo node replaced by `map(node)`. */
+export function mapDemoNodes(doc: DocumentNode, map: (node: DemoNode) => DemoNode): DocumentNode {
+  const walk = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(walk)
+    if (!value || typeof value !== "object") return value
+    if ((value as { type?: unknown }).type === "demo") return map(value as DemoNode)
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) out[k] = v && typeof v === "object" ? walk(v) : v
+    return out
+  }
+  return walk(doc) as DocumentNode
+}
+
+/** A demo tag's attributes as `meta.json`-style defaults. */
+export function demoNodeMeta(node: DemoNode): DemoMeta {
+  const meta: DemoMeta = {}
+  if (node.title) meta.title = node.title
+  if (node.description) meta.description = node.description
+  if (node.height) meta.height = /^\d+(?:\.\d+)?$/.test(node.height) ? Number(node.height) : node.height
+  if (node.layout) meta.layout = node.layout
+  if (node.variants?.length) meta.variants = node.variants.map((v) => ({ ...v }))
+  if (node.entry) meta.entry = node.entry
+  if (node.status) meta.status = node.status
+  if (node.bleed !== undefined) meta.bleed = node.bleed
+  if (node.className) meta.className = node.className
+  if (node.surface) meta.surface = cssToSurface(node.surface)
+  if (node.variantsWidth) meta.variantsWidth = node.variantsWidth
+  return meta
+}
+
+export interface CreateDocstreamClipboardOptions {
+  /**
+   * Files (and meta) for demos that don't carry theirs inline — the host resolver's, read
+   * synchronously (see `peekDemoSource`), or a `DemoVFS`'s. Demos it can't answer for stay
+   * src-only in both representations.
+   */
+  lookup?: (node: DemoNode) => DemoSourceSnapshot | undefined
+  /** Markdown serializer. Defaults to docstream's `serializeMarkdown`. */
+  serialize?: (doc: DocumentNode) => string
+}
+
+/** The clipboard representations of a document (or a selection of one). */
+export function createDocstreamClipboard(doc: DocumentNode, options: CreateDocstreamClipboardOptions = {}): DocstreamClipboard {
+  const serialize = options.serialize ?? serializeMarkdown
+  const files: Record<string, DemoFile[]> = {}
+  const meta: Record<string, DemoMeta> = {}
+  const inlined = mapDemoNodes(doc, (node) => {
+    if (node.files?.length) {
+      if (node.src) {
+        files[node.src] = toInlineFiles(node.files)
+        const tagMeta = demoNodeMeta(node)
+        if (Object.keys(tagMeta).length) meta[node.src] = tagMeta
+      }
+      return node
+    }
+    const found = node.src ? options.lookup?.(node) : undefined
+    if (!found?.files.length) return node
+    files[node.src] = toInlineFiles(found.files)
+    const merged = { ...found.meta, ...demoNodeMeta(node) }
+    if (Object.keys(merged).length) meta[node.src] = merged
+    return inlineDemoNode(node, found.files, found.meta)
+  })
+  return {
+    payload: { kind: "docstream", version: 1, markdown: serialize(doc), files, meta },
+    text: serialize(inlined),
+  }
+}
+
+/** Parse the Markdown of a copied docstream selection (or a single demo). */
+export function createDocstreamClipboardFromMarkdown(markdown: string, options: CreateDocstreamClipboardOptions = {}): DocstreamClipboard {
+  const clip = createDocstreamClipboard(parseMarkdown(markdown), options)
+  // Keep the author's bytes for the exact representation.
+  return { ...clip, payload: { ...clip.payload, markdown } }
+}
+
+/** The clipboard as react-aria `DragItem`s (for `useClipboard`'s `getItems` / `useDrag`). */
+export function docstreamClipboardItems(clip: DocstreamClipboard): DocstreamClipboardItem[] {
+  return [
+    {
+      "text/plain": clip.text,
+      "text/markdown": clip.text,
+      [DOCSTREAM_CLIPBOARD_TYPE]: JSON.stringify(clip.payload),
+    },
+  ]
+}
+
+/** Writes the representations straight onto a `DataTransfer` (a copy / cut / dragstart event's). */
+export function writeDocstreamClipboard(data: Pick<DataTransfer, "setData">, clip: DocstreamClipboard): void {
+  for (const [type, value] of Object.entries(docstreamClipboardItems(clip)[0])) data.setData(type, value)
+}
+
+/** Validates a `DOCSTREAM_CLIPBOARD_TYPE` string. */
+export function parseDocstreamClipboard(json: string | null | undefined): DocstreamClipboardPayload | null {
+  if (!json) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(json)
+  } catch {
+    return null
+  }
+  if (!raw || typeof raw !== "object") return null
+  const value = raw as Partial<DocstreamClipboardPayload>
+  if (value.kind !== "docstream" || typeof value.markdown !== "string") return null
+  const files: Record<string, DemoFile[]> = {}
+  for (const [src, list] of Object.entries(value.files && typeof value.files === "object" ? value.files : {})) {
+    if (!Array.isArray(list)) continue
+    const clean = list
+      .filter((f): f is DemoFile => !!f && typeof f === "object" && typeof f.path === "string" && typeof f.content === "string")
+      .map((f) => ({ path: f.path, content: f.content, ...(typeof f.language === "string" && f.language ? { language: f.language } : {}) }))
+    if (clean.length) files[src] = clean
+  }
+  const meta: Record<string, DemoMeta> = {}
+  for (const [src, m] of Object.entries(value.meta && typeof value.meta === "object" ? value.meta : {})) {
+    if (m && typeof m === "object") meta[src] = m as DemoMeta
+  }
+  return { kind: "docstream", version: 1, markdown: value.markdown, files, meta }
+}
+
+function hasType(types: ArrayLike<string> | null | undefined, type: string) {
+  return !!types && Array.prototype.indexOf.call(types, type) >= 0
+}
+
+/** True when a `DataTransfer` carries a docstream payload. */
+export function hasDocstreamClipboard(data: Pick<DataTransfer, "types"> | null | undefined): boolean {
+  return hasType(data?.types, DOCSTREAM_CLIPBOARD_TYPE)
+}
+
+/** The docstream payload on a paste / drop `DataTransfer`, if any. */
+export function readDocstreamClipboard(data: Pick<DataTransfer, "getData" | "types"> | null | undefined): DocstreamClipboardPayload | null {
+  if (!data || !hasDocstreamClipboard(data)) return null
+  return parseDocstreamClipboard(data.getData(DOCSTREAM_CLIPBOARD_TYPE))
+}
+
+/** Minimal react-aria `DropItem` shape (text items). */
+export interface DocstreamDropItem {
+  kind: string
+  types?: Set<string>
+  getText?: (type: string) => Promise<string>
+}
+
+/** The docstream payload among react-aria `DropItem`s (`useClipboard`'s `onPaste`, `useDrop`). */
+export async function readDocstreamClipboardItems(items: readonly DocstreamDropItem[]): Promise<DocstreamClipboardPayload | null> {
+  for (const item of items) {
+    if (item.kind === "text" && item.types?.has(DOCSTREAM_CLIPBOARD_TYPE) && item.getText) {
+      const payload = parseDocstreamClipboard(await item.getText(DOCSTREAM_CLIPBOARD_TYPE))
+      if (payload) return payload
+    }
+  }
+  return null
+}
+
+/**
+ * A payload for Markdown that arrived without one (only `text/plain` / `text/markdown`):
+ * inline-file demos give their files by `src`.
+ */
+export function docstreamPayloadFromMarkdown(markdown: string): DocstreamClipboardPayload {
+  const { payload } = createDocstreamClipboardFromMarkdown(markdown)
+  return payload
+}

package/src/demo/context.ts

@@ -27,3 +27,10 @@ export function useDemoRuntime(override?: DemoRuntimeOptions): DemoRuntimeOption
       : undefined,
   }
 }
+
+/**
+ * Demo files held in memory by `src` (a `DemoVFS`), e.g. demos pasted from another page or
+ * editor. `DemoViewer` falls back to them when a block has no inline files; the host
+ * resolver still wins when it knows `src`. Provided by renderers' / editors' `demoVFS`.
+ */
+export const DocstreamDemoVFSContext = createContext<import("./vfs").DemoVFS | undefined>(undefined)

package/src/demo/copy-demo.tsx

@@ -0,0 +1,102 @@
+/* "Copy demo": writes the docstream clipboard (Markdown with the demo's files inline, plus the
+   `application/x-docstream+json` payload) through react-aria's `useClipboard`, so pasting into
+   a docstream editor recreates the demo with its files. A button click has no copy event of
+   its own, so the button focuses itself and runs the browser's copy command; react-aria's
+   listener then fills the event's DataTransfer. Where that is unavailable, the Markdown is
+   copied as plain text (editors still parse its inline-file demos). */
+import { useEffect, useRef, useState, type DOMAttributes, type MutableRefObject } from "react"
+import { useClipboard } from "react-aria"
+import { CopyIcon, copyText } from "../docs/copy"
+import { docstreamClipboardItems, type DocstreamClipboard } from "./clipboard"
+
+export interface DocstreamCopy<T extends HTMLElement> {
+  ref: MutableRefObject<T | null>
+  /** react-aria `useClipboard`'s focus handlers: Cmd/Ctrl+C on the focused element copies too. */
+  props: DOMAttributes<T>
+  /** Copies; resolves false when there was nothing to copy. */
+  copy: () => Promise<boolean>
+}
+
+/**
+ * Copies a `DocstreamClipboard` (all three representations) from a click. Spread `props` on
+ * the triggering element (a focusable one, e.g. a `<button>`) and give it `ref`.
+ */
+export function useDocstreamCopy<T extends HTMLElement = HTMLButtonElement>(produce: () => DocstreamClipboard | null): DocstreamCopy<T> {
+  const ref = useRef<T | null>(null)
+  const latest = useRef(produce)
+  latest.current = produce
+  const wrote = useRef(false)
+  const { clipboardProps } = useClipboard({
+    getItems: () => {
+      const clip = latest.current()
+      return clip ? docstreamClipboardItems(clip) : []
+    },
+    onCopy: () => {
+      wrote.current = true
+    },
+  })
+
+  const copy = async (): Promise<boolean> => {
+    const clip = latest.current()
+    if (!clip) return false
+    const el = ref.current
+    wrote.current = false
+    if (el && typeof document !== "undefined" && typeof document.execCommand === "function") {
+      // The copy event targets the selection when there is one; clear it so it targets
+      // this (focused) element and nothing else — an editor around us — claims the event.
+      const selection = typeof window !== "undefined" ? window.getSelection() : null
+      const ranges: Range[] = []
+      if (selection) for (let i = 0; i < selection.rangeCount; i++) ranges.push(selection.getRangeAt(i))
+      try {
+        if (document.activeElement !== el) el.focus({ preventScroll: true })
+        selection?.removeAllRanges()
+        document.execCommand("copy")
+      } catch {
+        // fall through to the plain-text copy
+      } finally {
+        if (selection && ranges.length && !selection.rangeCount) for (const range of ranges) selection.addRange(range)
+      }
+    }
+    if (!wrote.current) await copyText(clip.text)
+    return true
+  }
+
+  return { ref, props: clipboardProps as DOMAttributes<T>, copy }
+}
+
+export interface CopyDemoButtonProps {
+  /** The clipboard to write, computed on click. `null` disables the copy. */
+  clipboard: () => DocstreamClipboard | null
+  label?: string
+  className?: string
+}
+
+/** Icon button: copies the demo (Markdown + files + docstream payload) and swaps to a tick. */
+export function CopyDemoButton({ clipboard, label = "Copy demo", className }: CopyDemoButtonProps) {
+  const { ref, props, copy } = useDocstreamCopy(clipboard)
+  const [copied, setCopied] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  useEffect(() => () => clearTimeout(timer.current), [])
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      className={className ? `docs-copy ${className}` : "docs-copy"}
+      onClick={() => {
+        void copy().then((ok) => {
+          if (!ok) return
+          setCopied(true)
+          clearTimeout(timer.current)
+          timer.current = setTimeout(() => setCopied(false), 1600)
+        })
+      }}
+      aria-label={copied ? "Copied" : label}
+      title={copied ? "Copied" : `${label} (Markdown with its files — paste into a docstream editor)`}
+      data-copied={copied || undefined}
+      data-docstream-copy-demo=""
+    >
+      <CopyIcon copied={copied} />
+    </button>
+  )
+}

package/src/demo/index.ts

@@ -1,5 +1,32 @@
-export { DocstreamDemoContext, DocstreamDemoRuntimeContext, useDemoResolver, useDemoRuntime } from "./context"
-export { DemoBlock, DemoFullscreen, DemoViewer, preloadDemos } from "./DemoViewer"
+export { DocstreamDemoContext, DocstreamDemoRuntimeContext, DocstreamDemoVFSContext, useDemoResolver, useDemoRuntime } from "./context"
+export { DemoBlock, DemoFullscreen, DemoViewer, peekDemoSource, prefetchDemoSources, preloadDemos } from "./DemoViewer"
+export {
+  DOCSTREAM_CLIPBOARD_TYPE,
+  collectDemoNodes,
+  createDocstreamClipboard,
+  createDocstreamClipboardFromMarkdown,
+  demoNodeMeta,
+  docstreamClipboardItems,
+  docstreamPayloadFromMarkdown,
+  hasDocstreamClipboard,
+  mapDemoNodes,
+  parseDocstreamClipboard,
+  readDocstreamClipboard,
+  readDocstreamClipboardItems,
+  writeDocstreamClipboard,
+} from "./clipboard"
+export type {
+  CreateDocstreamClipboardOptions,
+  DemoSourceSnapshot,
+  DocstreamClipboard,
+  DocstreamClipboardItem,
+  DocstreamClipboardPayload,
+  DocstreamDropItem,
+} from "./clipboard"
+export { CopyDemoButton, useDocstreamCopy } from "./copy-demo"
+export type { CopyDemoButtonProps, DocstreamCopy } from "./copy-demo"
+export { createDemoVFS, useDemoVFS, useDemoVFSContext, useDemoVFSEntry, useDemoVFSFiles } from "./vfs"
+export type { DemoVFS, DemoVFSChange, DemoVFSEntry, DemoVFSResolverOptions } from "./vfs"
 export type { DemoFullscreenProps, DemoViewerProps } from "./DemoViewer"
 export {
   createGlobDemoResolver,

package/src/demo/vfs.ts

@@ -0,0 +1,197 @@
+/* The demo virtual file system: demo files held in memory by `src`, for demos no host
+   resolver knows — typically ones pasted from another docstream page or editor.
+
+   - `DemoViewer` reads it from context (`DocstreamDemoVFSContext`, or a renderer's `demoVFS`):
+     a block with no inline files whose `src` is in the VFS shows the VFS files exactly like
+     inline files (the host resolver still wins when it knows `src`; the Preview runs through
+     the `demoRuntime`, else the Code view opens with the "needs runtime" note).
+   - `vfs.resolver({ resolver, runtime })` is the same thing as a `DemoResolver`, layered over
+     a host resolver: `files` / `meta` from the host when it knows `src`, else from the VFS;
+     `load` from the host, else a component that runs the VFS files through the runtime.
+   - One VFS may be shared by several editors / renderers; `subscribe` reports changes so a
+     host can persist pasted files. */
+import { useContext, useRef, useSyncExternalStore } from "react"
+import { DocstreamDemoVFSContext } from "./context"
+import type { DemoComponentProps, DemoFile, DemoMeta, DemoResolver, InlineDemoRuntime } from "./types"
+
+export interface DemoVFSEntry {
+  /** Entry first (or `meta.entry`), paths relative to the demo folder. */
+  files: DemoFile[]
+  /** `meta.json`-style defaults, usually the `{% demo %}` tag's attributes. */
+  meta?: DemoMeta
+}
+
+export interface DemoVFSChange {
+  src: string
+  /** The new entry; `undefined` when `src` was removed. */
+  entry: DemoVFSEntry | undefined
+}
+
+export interface DemoVFSResolverOptions {
+  /** The host resolver, consulted first. */
+  resolver?: DemoResolver
+  /** Runs VFS files for `load(src)`. Without one, `load` rejects for VFS-only demos. */
+  runtime?: InlineDemoRuntime
+  /** Extra npm dependencies handed to the runtime. */
+  dependencies?: Record<string, string>
+}
+
+export interface DemoVFS {
+  get(src: string): DemoVFSEntry | undefined
+  has(src: string): boolean
+  /** Every `src` held, in insertion order. */
+  list(): string[]
+  /** Adds or replaces `src`. A no-op (and no change event) when nothing differs. */
+  set(src: string, files: DemoFile[], meta?: DemoMeta): void
+  delete(src: string): boolean
+  clear(): void
+  /** Everything held, as `{ [src]: entry }`. The object is stable until the next change. */
+  snapshot(): Readonly<Record<string, DemoVFSEntry>>
+  /** Files only, as `{ [src]: files }` (what a host usually persists). Stable until the next change. */
+  files(): Readonly<Record<string, DemoFile[]>>
+  subscribe(listener: (change: DemoVFSChange) => void): () => void
+  /** This VFS as a `DemoResolver` layered over a host resolver. */
+  resolver(options?: DemoVFSResolverOptions): DemoResolver
+}
+
+const RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead."
+
+function cleanFiles(files: DemoFile[]): DemoFile[] {
+  return files
+    .filter((f) => f && typeof f.path === "string" && typeof f.content === "string")
+    .map((f) => ({ path: f.path, content: f.content, ...(f.language ? { language: f.language } : {}) }))
+}
+
+function entryFirst(files: DemoFile[], entry: string | undefined): DemoFile[] {
+  const index = entry ? files.findIndex((f) => f.path === entry) : -1
+  return index > 0 ? [files[index], ...files.slice(0, index), ...files.slice(index + 1)] : files
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+/** A new, empty (or pre-filled) demo VFS. */
+export function createDemoVFS(initial?: Record<string, DemoFile[] | DemoVFSEntry>): DemoVFS {
+  const entries = new Map<string, DemoVFSEntry>()
+  const listeners = new Set<(change: DemoVFSChange) => void>()
+  let snap: Record<string, DemoVFSEntry> | null = null
+  let fileSnap: Record<string, DemoFile[]> | null = null
+
+  const put = (src: string, files: DemoFile[], meta?: DemoMeta) => {
+    const entry: DemoVFSEntry = { files: cleanFiles(files), ...(meta && Object.keys(meta).length ? { meta } : {}) }
+    const prev = entries.get(src)
+    if (prev && same(prev, entry)) return undefined
+    entries.set(src, entry)
+    return entry
+  }
+  const emit = (change: DemoVFSChange) => {
+    snap = null
+    fileSnap = null
+    for (const listener of Array.from(listeners)) listener(change)
+  }
+
+  for (const [src, value] of Object.entries(initial ?? {})) {
+    if (Array.isArray(value)) put(src, value)
+    else if (value) put(src, value.files, value.meta)
+  }
+
+  const vfs: DemoVFS = {
+    get: (src) => entries.get(src),
+    has: (src) => entries.has(src),
+    list: () => Array.from(entries.keys()),
+    set(src, files, meta) {
+      const entry = put(src, files, meta)
+      if (entry) emit({ src, entry })
+    },
+    delete(src) {
+      if (!entries.delete(src)) return false
+      emit({ src, entry: undefined })
+      return true
+    },
+    clear() {
+      for (const src of Array.from(entries.keys())) vfs.delete(src)
+    },
+    snapshot() {
+      if (!snap) snap = Object.fromEntries(entries)
+      return snap
+    },
+    files() {
+      if (!fileSnap) fileSnap = Object.fromEntries(Array.from(entries, ([src, e]) => [src, e.files]))
+      return fileSnap
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    resolver: (options) => layeredResolver(vfs, options ?? {}),
+  }
+  return vfs
+}
+
+function layeredResolver(vfs: DemoVFS, { resolver: host, runtime, dependencies }: DemoVFSResolverOptions): DemoResolver {
+  // Whether the host should be asked first: it lists `src`, or it can't list at all.
+  const hostFirst = (src: string) => !!host && (!host.list || host.list().includes(src) || !vfs.has(src))
+  const fromVfs = (src: string) => {
+    const entry = vfs.get(src)
+    if (!entry) throw new Error(`Unknown demo: ${src}`)
+    return entry
+  }
+  async function pick<T>(src: string, viaHost: (host: DemoResolver) => Promise<T>, viaVfs: (entry: DemoVFSEntry) => T): Promise<T> {
+    if (hostFirst(src)) {
+      try {
+        return await viaHost(host!)
+      } catch (error) {
+        if (!vfs.has(src)) throw error
+      }
+    }
+    return viaVfs(fromVfs(src))
+  }
+  const layered: DemoResolver = {
+    list: () => Array.from(new Set([...(host?.list?.() ?? []), ...vfs.list()])),
+    meta: (src) => pick(src, (h) => h.meta(src), (e) => e.meta),
+    files: (src) => pick(src, (h) => h.files(src), (e) => entryFirst(e.files, e.meta?.entry)),
+    load: (src) =>
+      pick(src, (h) => h.load(src), (e) => {
+        if (!runtime) throw new Error(RUNTIME_NOTE)
+        const files = entryFirst(e.files, e.meta?.entry)
+        const title = e.meta?.title ?? (src.split("/").pop() || "Demo")
+        const VfsDemo = ({ variant }: DemoComponentProps) =>
+          runtime({ src, title, files, entry: files[0]?.path ?? "index.tsx", ...(variant ? { variant } : {}), ...(dependencies ? { dependencies } : {}) })
+        VfsDemo.displayName = `VfsDemo(${src})`
+        return VfsDemo as never
+      }),
+  }
+  if (host?.href) layered.href = (src, options) => (hostFirst(src) ? host.href!(src, options) : undefined)
+  return layered
+}
+
+/**
+ * A demo VFS owned by the calling component (created once). Pass it as `demoVFS` to several
+ * editors / renderers to share pasted demo files between them.
+ */
+export function useDemoVFS(initial?: Record<string, DemoFile[] | DemoVFSEntry>): DemoVFS {
+  const ref = useRef<DemoVFS | null>(null)
+  if (!ref.current) ref.current = createDemoVFS(initial)
+  return ref.current
+}
+
+/** The VFS in context (a renderer's or editor's `demoVFS`), unless `override` is given. */
+export function useDemoVFSContext(override?: DemoVFS): DemoVFS | undefined {
+  const inherited = useContext(DocstreamDemoVFSContext)
+  return override ?? inherited
+}
+
+const EMPTY: Readonly<Record<string, DemoFile[]>> = Object.freeze({})
+const noop = () => () => {}
+
+/** `{ [src]: files }` of a VFS, re-rendering on change. */
+export function useDemoVFSFiles(vfs: DemoVFS | undefined): Readonly<Record<string, DemoFile[]>> {
+  return useSyncExternalStore(vfs ? vfs.subscribe : noop, () => (vfs ? vfs.files() : EMPTY), () => (vfs ? vfs.files() : EMPTY))
+}
+
+/** One VFS entry, re-rendering when it changes. */
+export function useDemoVFSEntry(vfs: DemoVFS | undefined, src: string): DemoVFSEntry | undefined {
+  const snapshot = useSyncExternalStore(vfs ? vfs.subscribe : noop, () => vfs?.snapshot(), () => vfs?.snapshot())
+  return src ? snapshot?.[src] : undefined
+}

package/src/docs/DocsRenderer.tsx

@@ -16,7 +16,8 @@ import { slugify } from "../gitbook/outline"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
 import { serializeMarkdown } from "../gitbook/serialize"
-import { DocstreamDemoContext, DocstreamDemoRuntimeContext } from "../demo/context"
+import { DocstreamDemoContext, DocstreamDemoRuntimeContext, DocstreamDemoVFSContext } from "../demo/context"
+import type { DemoVFS } from "../demo/vfs"
 import { DemoBlock } from "../demo/DemoViewer"
 import type { DemoResolver, InlineDemoRuntime } from "../demo/types"
 import { CopyButton } from "./copy"
@@ -592,6 +593,11 @@ export interface DocRenderOptions {
   demoRuntime?: InlineDemoRuntime
   /** Extra npm dependencies inline demos may import (`{ "@brett_lamy/ui": "^1.2.0" }`). */
   demoDependencies?: Record<string, string>
+  /**
+   * Demo files held in memory by `src` (`createDemoVFS` / `useDemoVFS`), e.g. demos pasted
+   * into an editor. Blocks without inline files use them when no resolver knows `src`.
+   */
+  demoVFS?: DemoVFS
   /**
    * Render "Copy page ▾" (Copy / View as Markdown, Open in ChatGPT / Claude) above the content.
    * `true` uses the defaults; an object passes options to `DocPageActions`.
@@ -599,8 +605,9 @@ export interface DocRenderOptions {
   pageActions?: boolean | DocPageActionsOptions
 }
 
-function withDemoContext({ demoResolver, demoRuntime, demoDependencies }: DocRenderOptions, children: ReactNode) {
+function withDemoContext({ demoResolver, demoRuntime, demoDependencies, demoVFS }: DocRenderOptions, children: ReactNode) {
   let out = children
+  if (demoVFS) out = <DocstreamDemoVFSContext.Provider value={demoVFS}>{out}</DocstreamDemoVFSContext.Provider>
   if (demoRuntime || demoDependencies) {
     out = <DemoRuntimeProvider runtime={demoRuntime} dependencies={demoDependencies}>{out}</DemoRuntimeProvider>
   }
@@ -640,12 +647,13 @@ export function MarkdownContent({
   demoResolver,
   demoRuntime,
   demoDependencies,
+  demoVFS,
   pageActions,
   className,
 }: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
   const doc = useMemo(() => parseMarkdown(markdown), [markdown])
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS },
     <div data-docstream="" className={className}>
       <PageActionsBar markdown={markdown} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
@@ -661,11 +669,12 @@ export function DocsRenderer({
   demoResolver,
   demoRuntime,
   demoDependencies,
+  demoVFS,
   pageActions,
   markdown,
 }: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS },
     <article className="docs-article">
       <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />

package/src/docs/Mermaid.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useRef, useState, type CSSProperties } from "react"
+import { useEffect, useId, useState, type CSSProperties } from "react"
 import { HighlightedCode } from "./HighlightedCode"
 
 let seq = 0
@@ -17,7 +17,6 @@ export function Mermaid({ code, collapsedCodeLines = 3, expandedCodeLines = 30 }
   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))
@@ -27,7 +26,10 @@ export function Mermaid({ code, collapsedCodeLines = 3, expandedCodeLines = 30 }
     import("mermaid")
       .then(async ({ default: mermaid }) => {
         mermaid.initialize({ startOnLoad: false, securityLevel: "strict" })
-        const { svg } = await mermaid.render(idRef.current, code)
+        // A fresh id per render: mermaid.render removes any element with the id it is given,
+        // so reusing one (StrictMode's double effect, a code change) deleted the diagram an
+        // earlier render had already mounted.
+        const { svg } = await mermaid.render(`mermaid-${++seq}`, code)
         if (!cancelled) setSvg(svg)
       })
       .catch((e) => {