@brett_lamy/docstream 1.1.0 → 1.2.0

package/src/demo/markdown.ts

@@ -1,14 +1,33 @@
-import type { DemoNode } from "../gitbook/ast"
-import { parseMarkdown } from "../gitbook/parse"
+import type { DemoInlineFile, DemoNode } from "../gitbook/ast"
+import { flattenForPlainMarkdown } from "../gitbook/flatten"
+import { demoBody, fenceTracker, parseBlocks, parseMarkdown } from "../gitbook/parse"
+import { fenceFor, serializeBlocks, serializeMarkdown } from "../gitbook/serialize"
 import type { DemoFile, DemoMeta, DemoResolver } from "./types"
 import { languageForPath } from "./glob"
 
+export { fenceFor }
+
+/**
+ * - `"inline"` (default): every `{% demo src=… %}` keeps its tag and gains its files as
+ *   inline fences (`{% demo … %}` + titled fences + `{% enddemo %}`), so the Markdown is
+ *   still a docstream page: it renders back identically where the resolver exists and
+ *   self-contained everywhere else.
+ * - `"plain"`: for LLM prompts and plain Markdown tools — each demo becomes a bold
+ *   "Example — Title" line, its description, a variants note and one titled fence per
+ *   file (the pre-1.2 output); `{% command %}` boxes become npm ```` ```sh ```` fences and
+ *   titled tab sets become a heading plus one bold-labelled part per tab
+ *   (`flattenForPlainMarkdown`). Not renderable as docstream any more.
+ */
+export type DemoMarkdownFormat = "inline" | "plain"
+
 export interface ResolveDemosOptions {
-  /** Title shown on each file fence. Defaults to `<src>/<path>`. */
+  /** Output shape. Defaults to `"inline"` (renderable docstream Markdown). */
+  format?: DemoMarkdownFormat
+  /** `"plain"` only: title shown on each file fence. Defaults to `<src>/<path>`. */
   filePath?: (src: string, file: DemoFile) => string
   /**
-   * Markdown rendered for one demo. The default is a bold "Example — Title" line,
-   * the description, a variants note, then one titled fence per file (entry first).
+   * Markdown rendered for one demo, replacing the whole `{% demo %}` block whatever the
+   * `format`. Called only for demos with files (resolved, or inline).
    */
   render?: (demo: ResolvedDemo) => string
 }
@@ -20,19 +39,13 @@ export interface ResolvedDemo {
   title: string
 }
 
-const TAG_RE = /^\s*\{%\s*demo(\s[^%]*?)?\s*\/?%\}\s*$/
-const END_RE = /^\s*\{%\s*enddemo\s*%\}\s*$/
-
-/** A fence longer than any backtick run in the content, so nested fences survive. */
-export function fenceFor(content: string): string {
-  const longest = Math.max(2, ...[...content.matchAll(/`+/g)].map((m) => m[0].length))
-  return "`".repeat(longest + 1)
-}
+const TAG_RE = /^(\s*)\{%\s*demo(\s[^%]*?)?\s*\/?%\}\s*$/
 
 function titleFor(src: string, node: DemoNode, meta: DemoMeta | undefined) {
-  return node.title ?? meta?.title ?? src.split("/").pop() ?? src
+  return node.title ?? meta?.title ?? (src.split("/").pop() || src || "Demo")
 }
 
+/** The pre-1.2 "plain" rendering of one demo: prose plus titled fences. */
 export function defaultDemoMarkdown(demo: ResolvedDemo, filePath?: ResolveDemosOptions["filePath"]): string {
   const { node, meta, files, title } = demo
   const description = node.description ?? meta?.description
@@ -46,57 +59,141 @@ export function defaultDemoMarkdown(demo: ResolvedDemo, filePath?: ResolveDemosO
   for (const file of files) {
     const fence = fenceFor(file.content)
     const language = file.language ?? languageForPath(file.path) ?? ""
-    const title = filePath ? filePath(node.src, file) : `${node.src}/${file.path}`
+    const title = filePath ? filePath(node.src, file) : node.src ? `${node.src}/${file.path}` : file.path
     const body = file.content.replace(/\n+$/, "")
     parts.push(`${fence}${language} title="${title}"\n${body}\n${fence}`)
   }
   return parts.join("\n\n")
 }
 
+/** Resolver / viewer files as inline demo files: trailing newlines dropped, language filled in. */
+export function toInlineFiles(files: DemoFile[]): DemoInlineFile[] {
+  return files.map((file) => {
+    const language = file.language ?? languageForPath(file.path)
+    return { path: file.path, content: file.content.replace(/\n+$/, ""), ...(language ? { language } : {}) }
+  })
+}
+
 /**
- * Replace every `{% demo %}` tag with the demo's real source files as titled
- * fences, so the Markdown is self-contained (Copy page, `.md` exports, llms.txt).
- * Everything else is returned byte-for-byte; tags inside code fences are left alone.
- * Without a resolver, or for demos the resolver cannot find, tags are replaced by
- * a short note rather than left as syntax other tools would not understand.
+ * A demo as a self-contained block-form `{% demo %}`: the node's attributes, with the
+ * folder's `meta.json` defaults folded in (so the block renders the same without the
+ * resolver), and `files` as inline fences.
+ */
+export function inlineDemoNode(node: DemoNode, files: DemoFile[], meta?: DemoMeta): DemoNode {
+  const inline = toInlineFiles(files)
+  const height = node.height ?? (meta?.height === undefined || meta.height === "" ? undefined : String(meta.height))
+  const title = node.title ?? meta?.title
+  const description = node.description ?? meta?.description
+  const layout = node.layout ?? meta?.layout
+  const variants = node.variants?.length ? node.variants : meta?.variants?.length ? meta.variants : undefined
+  const entry = node.entry ?? (meta?.entry && inline[0]?.path !== meta.entry ? meta.entry : undefined)
+  return {
+    type: "demo",
+    src: node.src,
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(height ? { height } : {}),
+    ...(layout ? { layout } : {}),
+    ...(variants ? { variants } : {}),
+    ...(node.viewport ? { viewport: node.viewport } : {}),
+    ...(entry ? { entry } : {}),
+    ...(inline.length ? { files: inline } : {}),
+  }
+}
+
+/** `inlineDemoNode` serialized: `{% demo … %}` + titled fences + `{% enddemo %}`. */
+export function inlineDemoMarkdown(node: DemoNode, files: DemoFile[], meta?: DemoMeta): string {
+  return serializeBlocks([inlineDemoNode(node, files, meta)])
+}
+
+/**
+ * Make every `{% demo %}` in a page carry its real source files (Copy page, `.md`
+ * exports, llms.txt). By default the result is still docstream Markdown — see
+ * `DemoMarkdownFormat`. Everything outside demo blocks is returned byte-for-byte, and
+ * tags inside code fences are left alone.
+ *
+ * `"inline"`: blocks that already carry inline files, and demos the resolver cannot
+ * resolve (or no resolver), are left exactly as written — they are valid docstream.
+ * `"plain"`: unresolvable demos become a short note rather than tag syntax other tools
+ * would not understand.
  */
 export async function resolveDemosToMarkdown(
   markdown: string,
   resolver: DemoResolver | undefined,
   options: ResolveDemosOptions = {},
 ): Promise<string> {
+  // Plain output also flattens docstream-only presentation blocks (command boxes, titled tabs).
+  if (options.format === "plain" && /\{%\s*(?:command\b|tabs\s[^%]*\btitle=)/.test(markdown)) {
+    markdown = serializeMarkdown(flattenForPlainMarkdown(parseMarkdown(markdown)))
+  }
   const lines = markdown.split("\n")
-  const jobs: { index: number; drop: number; promise: Promise<string> }[] = []
-  let fence: string | null = null
+  const jobs: { index: number; end: number; indent: string; promise: Promise<string | null> }[] = []
+  const fences = fenceTracker()
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]
-    const opener = line.match(/^\s*(`{3,}|~{3,})/)
-    if (opener) {
-      if (!fence) fence = opener[1]
-      else if (line.trim().startsWith(fence[0].repeat(fence.length)) && line.trim().replace(/[`~]/g, "") === "") fence = null
-      continue
-    }
-    if (fence || !TAG_RE.test(line)) continue
-    const node = parseMarkdown(line.trim()).children[0]
+    if (fences.step(line)) continue
+    const tag = line.match(TAG_RE)
+    if (!tag) continue
+    const indent = tag[1]
+    const body = demoBody(lines, i + 1, /\/\s*%\}\s*$/.test(line))
+    const end = body ? body.next : i + 1
+    const block = lines.slice(i, end).map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l))
+    const node = parseBlocks(block)[0]
     if (node?.type !== "demo") continue
-    const drop = END_RE.test(lines[i + 1] ?? "") ? 1 : 0
-    jobs.push({ index: i, drop, promise: renderDemo(node, resolver, options) })
+    jobs.push({ index: i, end, indent, promise: renderDemo(node, block[0], resolver, options) })
+    i = end - 1
   }
   if (!jobs.length) return markdown
   const rendered = await Promise.all(jobs.map((job) => job.promise))
   for (let j = jobs.length - 1; j >= 0; j--) {
-    lines.splice(jobs[j].index, 1 + jobs[j].drop, rendered[j])
+    const out = rendered[j]
+    if (out === null) continue
+    const { index, end, indent } = jobs[j]
+    const text = indent ? out.split("\n").map((l) => (l ? indent + l : l)).join("\n") : out
+    lines.splice(index, end - index, text)
   }
   return lines.join("\n")
 }
 
-async function renderDemo(node: DemoNode, resolver: DemoResolver | undefined, options: ResolveDemosOptions): Promise<string> {
-  if (!resolver || !node.src) return `> Live demo \`${node.src || "?"}\` (interactive on the docs site).`
-  try {
-    const [meta, files] = await Promise.all([resolver.meta(node.src), resolver.files(node.src)])
-    const demo: ResolvedDemo = { node, meta, files, title: titleFor(node.src, node, meta) }
-    return options.render ? options.render(demo) : defaultDemoMarkdown(demo, options.filePath)
-  } catch (error) {
-    return `> Live demo \`${node.src}\` could not be resolved: ${error instanceof Error ? error.message : String(error)}`
+/**
+ * `inlineDemoMarkdown`, but keeping the author's tag line byte-for-byte when folding in
+ * `meta.json` added no attributes (only the files are new).
+ */
+function inlineDemoKeepingTag(tagLine: string, node: DemoNode, files: DemoFile[], meta: DemoMeta | undefined): string {
+  const next = inlineDemoNode(node, files, meta)
+  const out = serializeBlocks([next])
+  const bare = (n: DemoNode): DemoNode => {
+    const { files: _files, open: _open, ...rest } = n
+    return rest
+  }
+  if (serializeBlocks([bare(next)]) !== serializeBlocks([bare(node)])) return out
+  const tag = tagLine.trim().replace(/\s*\/\s*%\}$/, " %}")
+  return tag + out.slice(out.indexOf("\n"))
+}
+
+/** The replacement for one demo block, or null to keep it byte-for-byte. */
+async function renderDemo(node: DemoNode, tagLine: string, resolver: DemoResolver | undefined, options: ResolveDemosOptions): Promise<string | null> {
+  const plain = options.format === "plain"
+  const inlineFiles: DemoFile[] | undefined = node.files?.length ? node.files : undefined
+  let meta: DemoMeta | undefined
+  let files: DemoFile[] | undefined
+  let failure: string | undefined
+  if (resolver && node.src && !(inlineFiles && !plain && !options.render)) {
+    try {
+      ;[meta, files] = await Promise.all([resolver.meta(node.src), resolver.files(node.src)])
+    } catch (error) {
+      failure = error instanceof Error ? error.message : String(error)
+    }
+  }
+  // Resolver files are the authority; inline files stand in when it cannot help.
+  const chosen = files?.length ? files : inlineFiles
+  if (!chosen) {
+    if (!plain) return null
+    if (failure !== undefined) return `> Live demo \`${node.src}\` could not be resolved: ${failure}`
+    if (!resolver || !node.src) return `> Live demo \`${node.src || "?"}\` (interactive on the docs site).`
   }
+  const demo: ResolvedDemo = { node, meta, files: chosen ?? [], title: titleFor(node.src, node, meta) }
+  if (options.render) return options.render(demo)
+  if (plain) return defaultDemoMarkdown(demo, options.filePath)
+  return chosen === inlineFiles ? null : inlineDemoKeepingTag(tagLine, node, chosen!, meta)
 }

package/src/demo/types.ts

@@ -1,4 +1,4 @@
-import type { ComponentType } from "react"
+import type { ComponentType, ReactNode } from "react"
 import type { DemoLayout, DemoVariantOption } from "../gitbook/ast"
 
 export type DemoVariant = DemoVariantOption
@@ -7,7 +7,11 @@ export type DemoVariant = DemoVariantOption
 export interface DemoMeta {
   title?: string
   description?: string
-  /** Preview height: pixels, or any CSS length (`"60vh"`, `"auto"`). */
+  /**
+   * Preview height: pixels, or any CSS length (`"60vh"`, `"auto"`). Single-file previews
+   * treat it as a **minimum** (the card grows with its content); the multi-file viewer's
+   * resizable stage and inline-demo iframes use it as the height.
+   */
   height?: number | string
   variants?: DemoVariant[]
   /** Entry file, relative to the demo folder. Defaults to `index.tsx`. */
@@ -15,6 +19,17 @@ export interface DemoMeta {
   layout?: DemoLayout
   /** Drop the padded preview surface for demos that bring their own full-bleed frame. */
   bleed?: boolean
+  /** Extra class on the preview canvas (the surface the component renders on). */
+  className?: string
+  /**
+   * Inline style for the preview canvas: CSS custom properties or plain properties,
+   * e.g. `{ "background": "var(--brand-50)", "--demo-gap": "12px" }`.
+   */
+  surface?: Record<string, string | number>
+  /** A short status shown in the demo header, e.g. `"Live"` or `"Needs network"`. */
+  status?: string
+  /** Width of the variant switch (px number or CSS length); its options share it equally. */
+  variantsWidth?: number | string
 }
 
 export interface DemoFile {
@@ -51,3 +66,32 @@ export interface DemoResolver {
    */
   href?(src: string, options?: { variant?: string }): string | undefined
 }
+
+/** What an inline-demo runtime gets: the block's own files, ready to run. */
+export interface InlineDemoRuntimeProps {
+  /** The block's `src` (may be empty); useful as a cache key or label. */
+  src: string
+  title: string
+  /** The inline files, entry first, paths relative to the demo folder. */
+  files: DemoFile[]
+  /** Path of the entry file (its default export is the component). */
+  entry: string
+  /** The selected variant, passed to the component as its `variant` prop. */
+  variant?: string
+  /** Extra npm dependencies (`{ "@brett_lamy/ui": "^1.2.0" }`) the files may import. */
+  dependencies?: Record<string, string>
+}
+
+/**
+ * Renders the Preview of a `{% demo %}` block that carries its files inline and has
+ * no resolver behind it. `@brett_lamy/docstream/playground` provides an almost-node
+ * implementation (`createAlmostNodeDemoRuntime`), which `PlaygroundStreamdown` (the
+ * package root's `GitbookStreamdown`) wires in by default.
+ */
+export type InlineDemoRuntime = (props: InlineDemoRuntimeProps) => ReactNode
+
+export interface DemoRuntimeOptions {
+  runtime?: InlineDemoRuntime
+  /** Extra npm dependencies handed to the runtime for every inline demo. */
+  dependencies?: Record<string, string>
+}

package/src/docs/DocsRenderer.tsx

@@ -1,4 +1,4 @@
-import { useId, useMemo, useState, type ReactNode } from "react"
+import { useContext, useId, useMemo, useState, type ReactNode } from "react"
 import { motion, useReducedMotion } from "framer-motion"
 import "katex/dist/katex.min.css"
 import {
@@ -11,15 +11,17 @@ import {
   XCircle,
 } from "lucide-react"
 
-import type { Block, CodeBlockNode, DocumentNode, Inline, SourceRefNode } from "../gitbook/ast"
+import type { Block, CodeBlockNode, CommandNode, DocumentNode, Inline, PackageManager, SourceRefNode } from "../gitbook/ast"
+import { PACKAGE_MANAGERS, packageManagerCommands } from "../gitbook/package-managers"
+import { slugify } from "../gitbook/outline"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
 import { serializeMarkdown } from "../gitbook/serialize"
-import { DocstreamDemoContext } from "../demo/context"
+import { DocstreamDemoContext, DocstreamDemoRuntimeContext } from "../demo/context"
 import { DemoBlock } from "../demo/DemoViewer"
-import type { DemoResolver } from "../demo/types"
+import type { DemoResolver, InlineDemoRuntime } from "../demo/types"
 import { CopyButton } from "./copy"
-import { rovingKeyDown } from "./controls"
+import { PillTabs, rovingKeyDown } from "./controls"
 import { DocPageActions, type DocPageActionsOptions } from "./PageActions"
 import { useSyncedTab } from "./tabs-sync"
 import { ReplayPreview, isReplayQaUrl } from "../replay"
@@ -120,28 +122,24 @@ function codeOnlyTabs(block: Extract<Block, { type: "tabs" }>): CodeBlockNode[]
   return codes
 }
 
-function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, { type: "tabs" }> } & Renderers) {
-  const [local, setLocal] = useState(0)
-  const [synced, setSynced] = useSyncedTab(block.sync)
-  const syncedIndex = synced === null ? -1 : block.tabs.findIndex((t) => t.title === synced)
-  const active = Math.min(syncedIndex >= 0 ? syncedIndex : local, Math.max(0, block.tabs.length - 1))
-  const baseId = useId()
+/** The underline tab strip shared by tab sets and command boxes. */
+function TabStrip({ titles, active, onSelect, label, baseId }: {
+  titles: string[]
+  active: number
+  onSelect: (index: number) => void
+  label: string
+  baseId: string
+}) {
   const reduced = useReducedMotion()
-  const codes = useMemo(() => codeOnlyTabs(block), [block])
-  const select = (index: number) => {
-    setLocal(index)
-    const title = block.tabs[index]?.title
-    if (block.sync && title !== undefined) setSynced(title)
-  }
-  const ids = block.tabs.map((_, i) => String(i))
-  const header = (
+  const ids = titles.map((_, i) => String(i))
+  return (
     <div
       className="docs-tabs-header"
       role="tablist"
-      aria-label={block.sync ? `${block.sync} options` : "Content tabs"}
-      onKeyDown={(event) => rovingKeyDown(event, ids, String(active), (id) => select(Number(id)))}
+      aria-label={label}
+      onKeyDown={(event) => rovingKeyDown(event, ids, String(active), (id) => onSelect(Number(id)))}
     >
-      {block.tabs.map((t, i) => (
+      {titles.map((title, i) => (
         <button
           key={i}
           id={`${baseId}-tab-${i}`}
@@ -152,7 +150,7 @@ function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, {
           aria-controls={`${baseId}-panel`}
           tabIndex={i === active ? 0 : -1}
           className={i === active ? "docs-tab-active" : ""}
-          onClick={() => select(i)}
+          onClick={() => onSelect(i)}
         >
           {i === active ? (
             <motion.span
@@ -161,11 +159,89 @@ function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, {
               transition={reduced ? { duration: 0 } : { type: "spring", bounce: 0.2, duration: 0.6 }}
             />
           ) : null}
-          <span className="docs-tab-label">{t.title}</span>
+          <span className="docs-tab-label">{title}</span>
         </button>
       ))}
     </div>
   )
+}
+
+/** `{% command %}`: one npm command, shown for the reader's package manager (synced page-wide). */
+function CommandBox({ block }: { block: CommandNode }) {
+  const [synced, setSynced] = useSyncedTab(block.sync ?? "pm")
+  const [local, setLocal] = useState<PackageManager>(PACKAGE_MANAGERS[0])
+  const active: PackageManager = synced && (PACKAGE_MANAGERS as readonly string[]).includes(synced) ? (synced as PackageManager) : local
+  const commands = useMemo(() => packageManagerCommands(block.command, block.overrides), [block.command, block.overrides])
+  const baseId = useId()
+  const index = PACKAGE_MANAGERS.indexOf(active)
+  const select = (i: number) => {
+    const pm = PACKAGE_MANAGERS[i]
+    setLocal(pm)
+    setSynced(pm)
+  }
+  return (
+    <div className="docs-tabs docs-tabs-code docs-command" data-sync={block.sync ?? "pm"} data-pm={active}>
+      <div className="docs-tabs-code-head">
+        <span className="docs-tabs-code-term" aria-hidden="true">
+          <Terminal width={12} height={12} strokeWidth={2.4} />
+        </span>
+        <TabStrip titles={[...PACKAGE_MANAGERS]} active={index} onSelect={select} label="Package manager" baseId={baseId} />
+        <span className="docs-tabs-code-title" />
+        <CopyButton text={commands[active]} label={`Copy ${active} command`} />
+      </div>
+      <div className="docs-tabs-code-body" role="tabpanel" id={`${baseId}-panel`} aria-labelledby={`${baseId}-tab-${index}`}>
+        <pre>
+          <HighlightedCode code={commands[active]} language="sh" lineNumbers={false} />
+        </pre>
+      </div>
+    </div>
+  )
+}
+
+function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, { type: "tabs" }> } & Renderers) {
+  const [local, setLocal] = useState(0)
+  const [synced, setSynced] = useSyncedTab(block.sync)
+  const syncedIndex = synced === null ? -1 : block.tabs.findIndex((t) => t.title === synced)
+  const active = Math.min(syncedIndex >= 0 ? syncedIndex : local, Math.max(0, block.tabs.length - 1))
+  const baseId = useId()
+  const codes = useMemo(() => codeOnlyTabs(block), [block])
+  const select = (index: number) => {
+    setLocal(index)
+    const title = block.tabs[index]?.title
+    if (block.sync && title !== undefined) setSynced(title)
+  }
+  const header = (
+    <TabStrip
+      titles={block.tabs.map((t) => t.title)}
+      active={active}
+      onSelect={select}
+      label={block.sync ? `${block.sync} options` : "Content tabs"}
+      baseId={baseId}
+    />
+  )
+
+  if (block.title) {
+    const Heading = `h${block.level ?? 2}` as const
+    const headingId = slugify(block.title)
+    return (
+      <section className="docs-tabs-section" data-sync={block.sync} aria-labelledby={headingId}>
+        <div className="docs-tabs-section-head">
+          <Heading id={headingId} className="docs-tabs-section-title">{block.title}</Heading>
+          <PillTabs
+            options={block.tabs.map((t, i) => ({ id: String(i), label: t.title }))}
+            value={String(active)}
+            onChange={(id) => select(Number(id))}
+            label={`${block.title}: ${block.sync ? `${block.sync} options` : "options"}`}
+            tabId={(id) => `${baseId}-tab-${id}`}
+            panelId={() => `${baseId}-panel`}
+          />
+        </div>
+        <div className="docs-tabs-section-body" role="tabpanel" id={`${baseId}-panel`} aria-labelledby={`${baseId}-tab-${active}`}>
+          <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
+        </div>
+      </section>
+    )
+  }
 
   if (codes) {
     const code = codes[active]
@@ -239,15 +315,18 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
         })
       }
       return (
-        <div className="docs-code">
-          {(block.title || block.language) && (
+        <div className="docs-code" data-language={block.language ?? undefined}>
+          {/* A header bar only when there's a title (file name) to show; otherwise just the code
+              with a floating copy button. */}
+          {block.title ? (
             <div className="docs-code-header">
               <span>{block.title}</span>
               <span className="docs-code-lang">{block.language}</span>
-              <CopyButton text={block.code} label={block.title ? `Copy ${block.title}` : "Copy code"} />
+              <CopyButton text={block.code} label={`Copy ${block.title}`} />
             </div>
+          ) : (
+            <CopyButton text={block.code} className="docs-code-copy-float" />
           )}
-          {!block.title && !block.language ? <CopyButton text={block.code} className="docs-code-copy-float" /> : null}
           <pre className={block.lineNumbers ? "docs-code-numbered" : ""}>
             <HighlightedCode
               code={block.code}
@@ -270,6 +349,8 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
     }
     case "tabs":
       return <Tabs block={block} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
+    case "command":
+      return block.command ? <CommandBox block={block} /> : null
     case "expandable":
       return (
         <details className="docs-expandable">
@@ -466,6 +547,15 @@ function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Bloc
 export interface DocRenderOptions {
   /** Resolves `{% demo %}` blocks. Provided through context, so nested renderers inherit it. */
   demoResolver?: DemoResolver
+  /**
+   * Runs the Preview of `{% demo %}` blocks that carry their files inline and have no
+   * resolver behind them. `PlaygroundStreamdown` (the package root's `GitbookStreamdown`)
+   * supplies an almost-node runtime by default; see `createAlmostNodeDemoRuntime`.
+   * Without one, such demos show their code with a short note.
+   */
+  demoRuntime?: InlineDemoRuntime
+  /** Extra npm dependencies inline demos may import (`{ "@brett_lamy/ui": "^1.2.0" }`). */
+  demoDependencies?: Record<string, string>
   /**
    * Render "Copy page ▾" (Copy / View as Markdown, Open in ChatGPT / Claude) above the content.
    * `true` uses the defaults; an object passes options to `DocPageActions`.
@@ -473,8 +563,27 @@ export interface DocRenderOptions {
   pageActions?: boolean | DocPageActionsOptions
 }
 
-function withDemoResolver(resolver: DemoResolver | undefined, children: ReactNode) {
-  return resolver ? <DocstreamDemoContext.Provider value={resolver}>{children}</DocstreamDemoContext.Provider> : children
+function withDemoContext({ demoResolver, demoRuntime, demoDependencies }: DocRenderOptions, children: ReactNode) {
+  let out = children
+  if (demoRuntime || demoDependencies) {
+    out = <DemoRuntimeProvider runtime={demoRuntime} dependencies={demoDependencies}>{out}</DemoRuntimeProvider>
+  }
+  return demoResolver ? <DocstreamDemoContext.Provider value={demoResolver}>{out}</DocstreamDemoContext.Provider> : out
+}
+
+/** Merges runtime options over the inherited ones, keeping a stable context value. */
+function DemoRuntimeProvider({ runtime, dependencies, children }: { runtime?: InlineDemoRuntime; dependencies?: Record<string, string>; children: ReactNode }) {
+  const inherited = useContext(DocstreamDemoRuntimeContext)
+  const depsKey = dependencies ? JSON.stringify(dependencies) : ""
+  const value = useMemo(
+    () => ({
+      runtime: runtime ?? inherited.runtime,
+      dependencies: dependencies || inherited.dependencies ? { ...inherited.dependencies, ...dependencies } : undefined,
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [runtime, inherited, depsKey],
+  )
+  return <DocstreamDemoRuntimeContext.Provider value={value}>{children}</DocstreamDemoRuntimeContext.Provider>
 }
 
 export function PageActionsBar({ markdown, options }: { markdown: string | (() => string); options: boolean | DocPageActionsOptions | undefined }) {
@@ -493,12 +602,14 @@ export function MarkdownContent({
   liveRenderer,
   sourceRenderer,
   demoResolver,
+  demoRuntime,
+  demoDependencies,
   pageActions,
   className,
 }: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
   const doc = useMemo(() => parseMarkdown(markdown), [markdown])
-  return withDemoResolver(
-    demoResolver,
+  return withDemoContext(
+    { demoResolver, demoRuntime, demoDependencies },
     <div data-docstream="" className={className}>
       <PageActionsBar markdown={markdown} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
@@ -512,11 +623,13 @@ export function DocsRenderer({
   liveRenderer,
   sourceRenderer,
   demoResolver,
+  demoRuntime,
+  demoDependencies,
   pageActions,
   markdown,
 }: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
-  return withDemoResolver(
-    demoResolver,
+  return withDemoContext(
+    { demoResolver, demoRuntime, demoDependencies },
     <article className="docs-article">
       <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />

package/src/docs/PageActions.tsx

@@ -1,5 +1,6 @@
-/* "Copy page ▾": copy the page as Markdown (with {% demo %} blocks resolved into their real files),
-   view it as Markdown, or open it in ChatGPT / Claude. */
+/* "Copy page ▾": copy the page as Markdown, view it as Markdown, or open it in ChatGPT / Claude.
+   Copy and View give renderable docstream Markdown: each {% demo %} keeps its tag and carries its
+   real files inline, so pasting the page into docstream renders the same page (demos included). */
 import { useEffect, useId, useRef, useState, type KeyboardEvent, type ReactNode } from "react"
 import { AnimatePresence, motion, useReducedMotion } from "framer-motion"
 import { ArrowUpRight, ChevronDown, FileText } from "lucide-react"
@@ -25,7 +26,10 @@ export interface DocPageActionsOptions {
   actions?: DocPageAction[]
   /** Final touch on the copied Markdown (e.g. append a "Source:" footer). */
   transform?: (markdown: string) => string
-  /** Options for resolving `{% demo %}` blocks. */
+  /**
+   * Options for resolving `{% demo %}` blocks. The default `format: "inline"` keeps the page
+   * renderable by docstream; `{ format: "plain" }` gives the pre-1.2 prose + fences form.
+   */
   demoOptions?: ResolveDemosOptions
   /** Overrides the resolver from context. */
   resolver?: DemoResolver
@@ -62,7 +66,7 @@ interface MenuItem {
   run?: () => void
 }
 
-/** Resolves the page Markdown (demos inlined) for copying or exporting. */
+/** The page as renderable Markdown (demo files inline) for copying or exporting. */
 async function pageMarkdown(props: DocPageActionsProps, resolver: DemoResolver | undefined) {
   const source = typeof props.markdown === "function" ? await props.markdown() : props.markdown
   const resolved = await resolveDemosToMarkdown(source, resolver, props.demoOptions)
@@ -106,7 +110,7 @@ export function DocPageActions(props: DocPageActionsProps) {
   }
 
   const all: MenuItem[] = [
-    { id: "copy", icon: <CopyIcon copied={false} />, label: "Copy as Markdown", hint: "Copy this page for LLMs", run: () => void copyPage() },
+    { id: "copy", icon: <CopyIcon copied={false} />, label: "Copy as Markdown", hint: "Copy this page, demos included", run: () => void copyPage() },
     props.markdownUrl
       ? { id: "view", icon: <FileText width={15} height={15} aria-hidden="true" />, label: "View as Markdown", hint: "Open the page as plain text", href: props.markdownUrl }
       : { id: "view", icon: <FileText width={15} height={15} aria-hidden="true" />, label: "View as Markdown", hint: "Open the page as plain text", run: () => void viewMarkdown() },
@@ -122,7 +126,7 @@ export function DocPageActions(props: DocPageActionsProps) {
   }
 
   const onMenuKey = (event: KeyboardEvent<HTMLDivElement>) => {
-    const entries = [...event.currentTarget.querySelectorAll<HTMLElement>("[role=menuitem]")]
+    const entries = Array.from(event.currentTarget.querySelectorAll<HTMLElement>("[role=menuitem]"))
     const index = entries.indexOf(document.activeElement as HTMLElement)
     let next = -1
     if (event.key === "ArrowDown") next = (index + 1) % entries.length