@brett_lamy/docstream 1.0.0 → 1.1.0

package/src/demo/context.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext } from "react"
+import type { DemoResolver } from "./types"
+
+/**
+ * The host's demo resolver. Renderers given a `demoResolver` prop provide it, so
+ * nested renderers (Markdown inside tabs, hints, a demo's own Markdown) inherit it.
+ */
+export const DocstreamDemoContext = createContext<DemoResolver | undefined>(undefined)
+
+export function useDemoResolver(override?: DemoResolver): DemoResolver | undefined {
+  const inherited = useContext(DocstreamDemoContext)
+  return override ?? inherited
+}

package/src/demo/glob.ts

@@ -0,0 +1,188 @@
+import type { DemoComponent, DemoFile, DemoMeta, DemoResolver } from "./types"
+
+type Lazy<T> = () => Promise<T>
+type MaybeLazy<T> = T | Lazy<T>
+
+export interface GlobDemoResolverOptions {
+  /**
+   * Entry modules, e.g. `import.meta.glob("./examples/*\/*\/index.tsx")`.
+   * Lazy (the default for `import.meta.glob`) or eager module objects both work.
+   */
+  modules: Record<string, MaybeLazy<unknown>>
+  /**
+   * Raw file contents, e.g.
+   * `import.meta.glob("./examples/**\/*.{ts,tsx,css,json}", { query: "?raw", import: "default" })`.
+   */
+  sources: Record<string, MaybeLazy<string>>
+  /**
+   * Folder metadata, e.g.
+   * `import.meta.glob("./examples/*\/*\/meta.json", { eager: true, import: "default" })`.
+   */
+  metas?: Record<string, MaybeLazy<DemoMeta | { default: DemoMeta }>>
+  /**
+   * The glob prefix the `<page>/<example>` ids are relative to, e.g. `"./examples"`.
+   * When omitted, a demo's id is the last two folders of its entry path.
+   */
+  root?: string
+  /** Default entry file name. Defaults to `index.tsx`; a folder's `meta.entry` wins. */
+  entry?: string
+  /** Hide files from the Code view (`meta.json` is always hidden). */
+  exclude?: (path: string, src: string) => boolean
+  /** Deep link for a demo alone, e.g. `(src) => demoHref(src)`. */
+  href?: DemoResolver["href"]
+}
+
+const LANGUAGES: Record<string, string> = { mjs: "js", cjs: "js", mts: "ts", cts: "ts", md: "markdown", yml: "yaml" }
+
+export function languageForPath(path: string): string | undefined {
+  const ext = path.split("/").pop()?.split(".").pop()?.toLowerCase()
+  if (!ext || ext === path) return undefined
+  return LANGUAGES[ext] ?? ext
+}
+
+const unwrap = async <T,>(value: MaybeLazy<T>): Promise<T> =>
+  typeof value === "function" ? (value as Lazy<T>)() : value
+
+function trimSlashes(path: string) {
+  return path.replace(/\\/g, "/").replace(/\/+$/, "")
+}
+
+/** Picks the component out of a loaded module: `default`, else the first function export. */
+export function demoComponentFrom(module: unknown, src = "demo"): DemoComponent {
+  if (typeof module === "function") return module as DemoComponent
+  const record = (module ?? {}) as Record<string, unknown>
+  const candidate =
+    typeof record.default === "function"
+      ? record.default
+      : Object.values(record).find((value) => typeof value === "function")
+  if (typeof candidate !== "function") throw new Error(`Demo ${src} has no default-exported component`)
+  return candidate as DemoComponent
+}
+
+/** Orders files entry first, then top-level before nested, then by path. */
+export function sortDemoFiles(files: DemoFile[], entry = "index.tsx"): DemoFile[] {
+  const depth = (path: string) => path.split("/").length
+  return [...files].sort((a, b) => {
+    if (a.path === entry) return -1
+    if (b.path === entry) return 1
+    return depth(a.path) - depth(b.path) || a.path.localeCompare(b.path)
+  })
+}
+
+/**
+ * Build a `DemoResolver` from Vite `import.meta.glob` maps. Each `<page>/<example>`
+ * folder holds an entry module (default export = the demo component, which receives
+ * `variant`), any number of source files, and an optional `meta.json`.
+ */
+export function createGlobDemoResolver(options: GlobDemoResolverOptions): DemoResolver {
+  const defaultEntry = options.entry ?? "index.tsx"
+  const root = options.root === undefined ? undefined : trimSlashes(options.root)
+
+  // Demo ids come from the entry modules: with `root`, the first two folders under it;
+  // without, the last two folders of each entry path.
+  const folders = new Map<string, string>() // src → folder prefix (with trailing slash)
+  for (const key of Object.keys(options.modules)) {
+    const path = key.replace(/\\/g, "/")
+    if (root !== undefined) {
+      const prefix = root ? `${root}/` : ""
+      if (!path.startsWith(prefix)) continue
+      const parts = path.slice(prefix.length).split("/")
+      if (parts.length < 3) continue
+      const src = `${parts[0]}/${parts[1]}`
+      if (!folders.has(src)) folders.set(src, `${prefix}${src}/`)
+    } else {
+      const parts = path.split("/").slice(0, -1)
+      if (parts.length < 2) continue
+      const src = parts.slice(-2).join("/")
+      if (!folders.has(src)) folders.set(src, `${parts.join("/")}/`)
+    }
+  }
+  /** The key's path relative to the demo folder, or null when it lives elsewhere. */
+  const inFolder = (src: string, key: string) => {
+    const prefix = folders.get(src)
+    const path = key.replace(/\\/g, "/")
+    return prefix && path.startsWith(prefix) ? path.slice(prefix.length) : null
+  }
+
+  const metaCache = new Map<string, Promise<DemoMeta | undefined>>()
+  const filesCache = new Map<string, Promise<DemoFile[]>>()
+  const loadCache = new Map<string, Promise<DemoComponent>>()
+
+  const meta = (src: string) => {
+    let hit = metaCache.get(src)
+    if (!hit) {
+      const key = Object.keys(options.metas ?? {}).find((k) => inFolder(src, k) === "meta.json")
+      hit = key
+        ? unwrap(options.metas![key]).then((m) => {
+            const value = m as DemoMeta & { default?: DemoMeta }
+            return value && typeof value === "object" && "default" in value && value.default ? value.default : value
+          })
+        : Promise.resolve(undefined)
+      metaCache.set(src, hit)
+    }
+    return hit
+  }
+
+  const entryFor = async (src: string) => (await meta(src))?.entry ?? defaultEntry
+
+  return {
+    list: () => [...folders.keys()].sort(),
+    meta,
+    files(src) {
+      let hit = filesCache.get(src)
+      if (!hit) {
+        hit = (async () => {
+          const entry = await entryFor(src)
+          const found = Object.entries(options.sources)
+            .map(([key, value]) => ({ path: inFolder(src, key), value }))
+            .filter((f): f is { path: string; value: MaybeLazy<string> } =>
+              !!f.path && f.path !== "meta.json" && !options.exclude?.(f.path, src))
+          const files = await Promise.all(found.map(async ({ path, value }) => {
+            const content = await unwrap(value)
+            return { path, content: typeof content === "string" ? content : String(content), language: languageForPath(path) }
+          }))
+          return sortDemoFiles(files, entry)
+        })()
+        filesCache.set(src, hit)
+      }
+      return hit
+    },
+    load(src) {
+      let hit = loadCache.get(src)
+      if (!hit) {
+        hit = (async () => {
+          const entry = await entryFor(src)
+          const keys = Object.keys(options.modules).filter((k) => inFolder(src, k) !== null)
+          const key = keys.find((k) => inFolder(src, k) === entry) ?? keys[0]
+          if (!key) throw new Error(`No demo module found for ${src}`)
+          return demoComponentFrom(await unwrap(options.modules[key]), src)
+        })()
+        hit.catch(() => loadCache.delete(src))
+        loadCache.set(src, hit)
+      }
+      return hit
+    },
+    ...(options.href ? { href: options.href } : {}),
+  }
+}
+
+/**
+ * The conventional deep link for one demo: `?demo=<src>` on the current page
+ * (or `base`). Hosts route it to `<DemoFullscreen>`; see `demoFromSearch`.
+ */
+export function demoHref(src: string, options: { base?: string; variant?: string; param?: string } = {}): string {
+  const base = options.base ?? (typeof location === "undefined" ? "/" : location.pathname)
+  const params = new URLSearchParams({ [options.param ?? "demo"]: src })
+  if (options.variant) params.set("variant", options.variant)
+  return `${base}?${params.toString().replace(/%2F/gi, "/")}`
+}
+
+/** Reads the `?demo=<src>` (and optional `variant`) deep link. */
+export function demoFromSearch(search?: string, param = "demo"): { src: string; variant?: string } | null {
+  const query = search ?? (typeof location === "undefined" ? "" : location.search)
+  const params = new URLSearchParams(query)
+  const src = params.get(param)
+  if (!src) return null
+  const variant = params.get("variant")
+  return variant ? { src, variant } : { src }
+}

package/src/demo/index.ts

@@ -0,0 +1,15 @@
+export { DocstreamDemoContext, useDemoResolver } from "./context"
+export { DemoBlock, DemoFullscreen, DemoViewer } from "./DemoViewer"
+export type { DemoFullscreenProps, DemoViewerProps } from "./DemoViewer"
+export {
+  createGlobDemoResolver,
+  demoComponentFrom,
+  demoFromSearch,
+  demoHref,
+  languageForPath,
+  sortDemoFiles,
+} from "./glob"
+export type { GlobDemoResolverOptions } from "./glob"
+export { defaultDemoMarkdown, resolveDemosToMarkdown } from "./markdown"
+export type { ResolveDemosOptions, ResolvedDemo } from "./markdown"
+export type { DemoComponent, DemoComponentProps, DemoFile, DemoMeta, DemoResolver, DemoVariant } from "./types"

package/src/demo/markdown.ts

@@ -0,0 +1,102 @@
+import type { DemoNode } from "../gitbook/ast"
+import { parseMarkdown } from "../gitbook/parse"
+import type { DemoFile, DemoMeta, DemoResolver } from "./types"
+import { languageForPath } from "./glob"
+
+export interface ResolveDemosOptions {
+  /** 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).
+   */
+  render?: (demo: ResolvedDemo) => string
+}
+
+export interface ResolvedDemo {
+  node: DemoNode
+  meta: DemoMeta | undefined
+  files: DemoFile[]
+  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)
+}
+
+function titleFor(src: string, node: DemoNode, meta: DemoMeta | undefined) {
+  return node.title ?? meta?.title ?? src.split("/").pop() ?? src
+}
+
+export function defaultDemoMarkdown(demo: ResolvedDemo, filePath?: ResolveDemosOptions["filePath"]): string {
+  const { node, meta, files, title } = demo
+  const description = node.description ?? meta?.description
+  const variants = node.variants ?? meta?.variants
+  const parts = [`**Example — ${title}**`]
+  if (description) parts.push(description)
+  if (variants?.length) {
+    parts.push(`Variants (the \`variant\` prop): ${variants.map((v) => `\`${v.id}\`${v.label !== v.id ? ` (${v.label})` : ""}`).join(", ")}.`)
+  }
+  if (!files.length) parts.push(`> Demo \`${node.src}\` has no source files.`)
+  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 body = file.content.replace(/\n+$/, "")
+    parts.push(`${fence}${language} title="${title}"\n${body}\n${fence}`)
+  }
+  return parts.join("\n\n")
+}
+
+/**
+ * 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.
+ */
+export async function resolveDemosToMarkdown(
+  markdown: string,
+  resolver: DemoResolver | undefined,
+  options: ResolveDemosOptions = {},
+): Promise<string> {
+  const lines = markdown.split("\n")
+  const jobs: { index: number; drop: number; promise: Promise<string> }[] = []
+  let fence: string | null = null
+  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 (node?.type !== "demo") continue
+    const drop = END_RE.test(lines[i + 1] ?? "") ? 1 : 0
+    jobs.push({ index: i, drop, promise: renderDemo(node, resolver, options) })
+  }
+  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])
+  }
+  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)}`
+  }
+}

package/src/demo/types.ts

@@ -0,0 +1,53 @@
+import type { ComponentType } from "react"
+import type { DemoLayout, DemoVariantOption } from "../gitbook/ast"
+
+export type DemoVariant = DemoVariantOption
+
+/** Defaults for a demo folder, usually its `meta.json`. `{% demo %}` attributes override them. */
+export interface DemoMeta {
+  title?: string
+  description?: string
+  /** Preview height: pixels, or any CSS length (`"60vh"`, `"auto"`). */
+  height?: number | string
+  variants?: DemoVariant[]
+  /** Entry file, relative to the demo folder. Defaults to `index.tsx`. */
+  entry?: string
+  layout?: DemoLayout
+  /** Drop the padded preview surface for demos that bring their own full-bleed frame. */
+  bleed?: boolean
+}
+
+export interface DemoFile {
+  /** Path relative to the demo folder (`index.tsx`, `parts/Card.tsx`). */
+  path: string
+  content: string
+  /** Highlighting language; defaults to the file extension. */
+  language?: string
+}
+
+/** Props the loaded demo component receives. */
+export interface DemoComponentProps {
+  variant?: string
+}
+
+export type DemoComponent = ComponentType<DemoComponentProps>
+
+/**
+ * How a host turns `{% demo src="<page>/<example>" %}` into something renderable.
+ * `createGlobDemoResolver` builds one from Vite `import.meta.glob` maps.
+ */
+export interface DemoResolver {
+  /** Every known demo id (optional; used by tooling and llms.txt generators). */
+  list?(): string[]
+  meta(src: string): Promise<DemoMeta | undefined>
+  /** The demo's source files, entry first. These are exactly what the Code view shows. */
+  files(src: string): Promise<DemoFile[]>
+  /** The component to render in-page. */
+  load(src: string): Promise<DemoComponent>
+  /**
+   * Optional deep link that renders the demo alone (e.g. `?demo=<src>`); the host
+   * routes it to `<DemoFullscreen>`. When present, the viewer shows an
+   * "Open in new tab" link next to its in-page fullscreen button.
+   */
+  href?(src: string, options?: { variant?: string }): string | undefined
+}

package/src/docs/CollapsibleCode.tsx

@@ -0,0 +1,54 @@
+import { useId, useState, type CSSProperties } from "react"
+import { HighlightedCode } from "./HighlightedCode"
+import { CopyButton } from "./copy"
+
+export interface CollapsibleCodeProps {
+  code: string
+  language: string | null
+  /** Lines visible while collapsed. Defaults to 3. */
+  collapsedLines?: number
+  /** Lines visible when expanded before the panel scrolls. Defaults to 30. */
+  expandedLines?: number
+  /** Show a copy button in the panel corner. Defaults to true. */
+  copy?: boolean
+  copyLabel?: string
+}
+
+function positiveLineCount(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
+}
+
+/** The line-numbered code panel under a demo: a few lines, then "View Code" to expand. */
+export function CollapsibleCode({ code, language, collapsedLines, expandedLines, copy = true, copyLabel }: CollapsibleCodeProps) {
+  const [expanded, setExpanded] = useState(false)
+  const panelId = useId()
+  const collapsed = positiveLineCount(collapsedLines, 3)
+  const expandedCount = Math.max(collapsed, positiveLineCount(expandedLines, 30))
+  const total = code.split("\n").length
+  const needsToggle = total > collapsed
+  const isOpen = expanded || !needsToggle
+  return (
+    <div className="docs-react-demo-code" data-expanded={isOpen || undefined}>
+      <pre
+        id={panelId}
+        className={isOpen ? "docs-react-demo-code-body docs-react-demo-code-body-expanded" : "docs-react-demo-code-body"}
+        data-toggle={needsToggle || undefined}
+        style={{ "--docs-react-demo-code-lines": isOpen ? expandedCount : collapsed } as CSSProperties}
+      >
+        <HighlightedCode code={code} language={language} lineNumbers />
+      </pre>
+      {copy ? <CopyButton text={code} label={copyLabel} className="docs-react-demo-code-copy" /> : null}
+      {needsToggle ? (
+        <button
+          type="button"
+          className="docs-react-demo-code-toggle"
+          aria-controls={panelId}
+          aria-expanded={expanded}
+          onClick={() => setExpanded((value) => !value)}
+        >
+          {expanded ? "Hide Code" : "View Code"}
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/src/docs/DocsRenderer.tsx

@@ -1,5 +1,5 @@
-import { useState, type ReactNode } from "react"
-import { LayoutGroup, motion } from "framer-motion"
+import { useId, useMemo, useState, type ReactNode } from "react"
+import { motion, useReducedMotion } from "framer-motion"
 import "katex/dist/katex.min.css"
 import {
   AlertTriangle,
@@ -7,12 +7,21 @@ import {
   ChevronRight,
   File,
   Info,
+  Terminal,
   XCircle,
 } from "lucide-react"
 
-import type { Block, DocumentNode, Inline, SourceRefNode } from "../gitbook/ast"
+import type { Block, CodeBlockNode, DocumentNode, Inline, SourceRefNode } from "../gitbook/ast"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
+import { serializeMarkdown } from "../gitbook/serialize"
+import { DocstreamDemoContext } from "../demo/context"
+import { DemoBlock } from "../demo/DemoViewer"
+import type { DemoResolver } from "../demo/types"
+import { CopyButton } from "./copy"
+import { rovingKeyDown } from "./controls"
+import { DocPageActions, type DocPageActionsOptions } from "./PageActions"
+import { useSyncedTab } from "./tabs-sync"
 import { ReplayPreview, isReplayQaUrl } from "../replay"
 import { VideoEmbed } from "../video"
 import { OpenApiOperation } from "../openapi/OpenApiOperation"
@@ -97,34 +106,96 @@ interface Renderers {
   sourceRenderer?: SourceReferenceRenderer
 }
 
+const SHELL_LANGUAGES = new Set(["sh", "bash", "shell", "zsh", "console", "shellsession", "powershell", "ps1", "bat", "cmd"])
+
+/** A tab set whose every tab is exactly one code block renders as one code block with tabs in its header. */
+function codeOnlyTabs(block: Extract<Block, { type: "tabs" }>): CodeBlockNode[] | null {
+  if (!block.tabs.length) return null
+  const codes: CodeBlockNode[] = []
+  for (const tab of block.tabs) {
+    const only = tab.children.length === 1 ? tab.children[0] : null
+    if (!only || only.type !== "code" || only.live || only.language === "mermaid") return null
+    codes.push(only)
+  }
+  return codes
+}
+
 function Tabs({ block, liveRenderer, sourceRenderer }: { block: Extract<Block, { type: "tabs" }> } & Renderers) {
-  const [active, setActive] = useState(0)
-  return (
-    <div className="docs-tabs">
-      <LayoutGroup>
-        <div className="docs-tabs-header" role="tablist" aria-label="Content tabs">
-          {block.tabs.map((t, i) => (
-            <button
-              key={i}
-              type="button"
-              role="tab"
-              aria-selected={i === active}
-              className={i === active ? "docs-tab-active" : ""}
-              onClick={() => setActive(i)}
-            >
-              {i === active ? (
-                <motion.span
-                  className="docs-tab-indicator"
-                  layoutId="docs-tab-indicator"
-                  transition={{ type: "spring", bounce: 0.2, duration: 0.6 }}
-                />
-              ) : null}
-              <span className="docs-tab-label">{t.title}</span>
-            </button>
-          ))}
+  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 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 = (
+    <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)))}
+    >
+      {block.tabs.map((t, i) => (
+        <button
+          key={i}
+          id={`${baseId}-tab-${i}`}
+          type="button"
+          role="tab"
+          data-roving=""
+          aria-selected={i === active}
+          aria-controls={`${baseId}-panel`}
+          tabIndex={i === active ? 0 : -1}
+          className={i === active ? "docs-tab-active" : ""}
+          onClick={() => select(i)}
+        >
+          {i === active ? (
+            <motion.span
+              className="docs-tab-indicator"
+              layoutId={`docs-tab-indicator-${baseId}`}
+              transition={reduced ? { duration: 0 } : { type: "spring", bounce: 0.2, duration: 0.6 }}
+            />
+          ) : null}
+          <span className="docs-tab-label">{t.title}</span>
+        </button>
+      ))}
+    </div>
+  )
+
+  if (codes) {
+    const code = codes[active]
+    const shell = codes.every((c) => c.language && SHELL_LANGUAGES.has(c.language.toLowerCase()))
+    const numbered = code.lineNumbers && code.code.includes("\n") && !shell
+    return (
+      <div className="docs-tabs docs-tabs-code" data-sync={block.sync}>
+        <div className="docs-tabs-code-head">
+          {shell ? (
+            <span className="docs-tabs-code-term" aria-hidden="true">
+              <Terminal width={12} height={12} strokeWidth={2.4} />
+            </span>
+          ) : null}
+          {header}
+          <span className="docs-tabs-code-title">{code.title}</span>
+          <CopyButton text={code.code} label={`Copy ${block.tabs[active]?.title ?? "code"}`} />
         </div>
-      </LayoutGroup>
-      <div className="docs-tabs-body" role="tabpanel">
+        <div className="docs-tabs-code-body" role="tabpanel" id={`${baseId}-panel`} aria-labelledby={`${baseId}-tab-${active}`}>
+          <pre className={numbered ? "docs-code-numbered" : ""}>
+            <HighlightedCode code={code.code} language={code.language} lineNumbers={numbered} />
+          </pre>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="docs-tabs" data-sync={block.sync}>
+      {header}
+      <div className="docs-tabs-body" role="tabpanel" id={`${baseId}-panel`} aria-labelledby={`${baseId}-tab-${active}`}>
         <Blocks blocks={block.tabs[active]?.children ?? []} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       </div>
     </div>
@@ -173,8 +244,10 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
             <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"} />
             </div>
           )}
+          {!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}
@@ -265,6 +338,8 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
           <code>{block.mount}:{block.path}</code>
         </div>
       )
+    case "demo":
+      return <DemoBlock node={block} />
     case "columns":
       return (
         <div className="docs-columns">
@@ -388,28 +463,64 @@ function Blocks({ blocks, inline, liveRenderer, sourceRenderer }: { blocks: Bloc
   )
 }
 
+export interface DocRenderOptions {
+  /** Resolves `{% demo %}` blocks. Provided through context, so nested renderers inherit it. */
+  demoResolver?: DemoResolver
+  /**
+   * Render "Copy page ▾" (Copy / View as Markdown, Open in ChatGPT / Claude) above the content.
+   * `true` uses the defaults; an object passes options to `DocPageActions`.
+   */
+  pageActions?: boolean | DocPageActionsOptions
+}
+
+function withDemoResolver(resolver: DemoResolver | undefined, children: ReactNode) {
+  return resolver ? <DocstreamDemoContext.Provider value={resolver}>{children}</DocstreamDemoContext.Provider> : children
+}
+
+export function PageActionsBar({ markdown, options }: { markdown: string | (() => string); options: boolean | DocPageActionsOptions | undefined }) {
+  if (!options) return null
+  return (
+    <div className="docs-page-actions-bar">
+      <DocPageActions markdown={markdown} {...(options === true ? {} : options)} />
+    </div>
+  )
+}
+
 // Renders a markdown string inline — used for embedded markdown like
 // OpenAPI descriptions, which can themselves contain GitBook blocks.
 export function MarkdownContent({
   markdown,
   liveRenderer,
   sourceRenderer,
+  demoResolver,
+  pageActions,
   className,
-}: { markdown: string; className?: string } & Renderers) {
-  const doc = parseMarkdown(markdown)
-  return (
+}: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
+  const doc = useMemo(() => parseMarkdown(markdown), [markdown])
+  return withDemoResolver(
+    demoResolver,
     <div data-docstream="" className={className}>
+      <PageActionsBar markdown={markdown} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
-    </div>
+    </div>,
   )
 }
 
-export function DocsRenderer({ doc, liveRenderer, sourceRenderer }: { doc: DocumentNode } & Renderers) {
-  return (
+export function DocsRenderer({
+  doc,
+  liveRenderer,
+  sourceRenderer,
+  demoResolver,
+  pageActions,
+  markdown,
+}: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
+  return withDemoResolver(
+    demoResolver,
     <article className="docs-article">
+      <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
-    </article>
+    </article>,
   )
 }