@brett_lamy/docstream-editor 1.0.1 → 1.2.0

package/README.md

@@ -13,6 +13,9 @@ TipTap editor components for Docstream GitBook-style markdown documents.
 - Code block syntax highlighting through [`gpu-lexer`](https://gpu-lexer.vercel.app/) (language-agnostic, WebGPU; plain text where WebGPU is unavailable).
 - Table, task list, heading, quote, and inline formatting support.
 - Preserves Docstream/GitBook block semantics when converting back to markdown.
+- Copy a docs page (docstream's "Copy page") and paste it in: the editor shows the same page and
+  serializes it back byte-for-byte — demos with their inline files, install command boxes, titled
+  tab sets and all.
 - Preserves mounted source-file/export provenance and can write edits to the real file through Vite.
 
 ## Installation
@@ -80,6 +83,10 @@ export interface GitbookEditorProps {
   onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
   onAttachmentRemove?: (ids: string[]) => void
   onAttachmentOpen?: (attachment: EditorAttachment) => void
+  demoResolver?: DemoResolver
+  demoRuntime?: InlineDemoRuntime
+  demoDependencies?: Record<string, string>
+  markdownPaste?: boolean
 }
 ```
 
@@ -89,6 +96,14 @@ export interface GitbookEditorProps {
   return `true` when the application handled the event.
 - `imagePaste`, `attachments`, `onAttachmentAdd`, `onAttachmentRemove`, `onAttachmentOpen`:
   how pasted/dropped images are handled — see [Pasted and dropped images](#pasted-and-dropped-images).
+- `demoResolver`: resolves `{% demo src %}` ids so demo blocks show a live, read-only
+  preview — see [Demo blocks](#demo-blocks).
+- `demoRuntime` / `demoDependencies`: run demos that carry their files inline and have no
+  resolver behind them — the same options as Docstream's `DocRenderOptions`.
+- `markdownPaste` (default `true`): plain-text Markdown pasted into the editor that contains
+  blocks (a "Copy page" export, `{% … %}` tags, fences, lists, headings …) is parsed into
+  editor blocks instead of pasted as literal text. Plain prose pastes as usual; HTML clipboards
+  keep TipTap's own handling (except VS Code's, which is treated as plain text).
 
 The editor tracks the last markdown it emitted so normal controlled updates do not continuously reset the TipTap document. Passing a different external `markdown` value replaces the editor content.
 
@@ -98,18 +113,23 @@ The editor supports common ProseMirror/TipTap content plus GitBook-flavored bloc
 
 - Headings
 - Paragraphs
-- Bold, italic, strike, inline code, and links
+- Bold, italic, strike, inline code, and links (a link inside emphasis, `**[x](url)**`, stays
+  distinct from emphasis inside a link, `[**x**](url)`)
 - Bullet, ordered, and task lists
 - Blockquotes
 - Code blocks
 - Tables
 - Hints
-- Tabs
+- Tabs (including `{% tabs sync="key" %}` sync groups, and titled sets
+  `{% tabs title="Installation" level="3" %}` rendered as a section heading with the switch on
+  its row — click the heading icon in the tab strip to add a title)
+- Package-manager command boxes (`{% command %}npm install x{% endcommand %}`, `/install command`)
 - Expandables
 - Steppers
 - Embeds
 - Content references
 - Component and Storybook source references
+- Live demos (`{% demo %}`), resolver-backed or carrying their files inline
 - Columns
 - Figures and images
 - OpenAPI operation placeholders
@@ -201,6 +221,45 @@ provenance, and refreshes the live component/story preview. Configure the mount
 with `docstreamSources()` from `@brett_lamy/docstream/vite` as shown in the
 Docstream README.
 
+## Demo blocks
+
+`{% demo src="<page>/<example>" %}` becomes a `gbDemo` atom node. Every tag
+attribute — `src`, `title`, `description`, `height`, `layout`, `variants`,
+`viewport`, `entry` — is kept on the node, and so are the files the block form
+carries inline (the titled fences between `{% demo … %}` and `{% enddemo %}`, as
+`files: { path, content, language? }[]`), so the block serializes back exactly as
+written. Docstream's "Copy page" writes every demo this way.
+
+The node shows a compact header with editable `src` and `title` inputs (insert
+one with `/demo`) and a **Files** toggle that opens a small file editor: a tab
+per file (rename it in place, mark it the entry, remove it), a code area, and
+`+` to add a file. Removing every file gives the one-line tag form again.
+
+Under the header, Docstream's read-only `DemoViewer` renders the demo: from the
+`demoResolver` when it knows `src`, otherwise from the inline files — so a
+pasted docs page looks like the docs page. Inline files run in the Preview
+through `demoRuntime` (e.g. `createAlmostNodeDemoRuntime()` from
+`@brett_lamy/docstream/playground`) with `demoDependencies`; without a runtime
+the viewer shows their code.
+
+```tsx
+import { createGlobDemoResolver } from "@brett_lamy/docstream/demo"
+import { GitbookEditor } from "@brett_lamy/docstream-editor"
+
+const demoResolver = createGlobDemoResolver({ /* see the Docstream README */ })
+
+<GitbookEditor markdown={markdown} onChange={setMarkdown} demoResolver={demoResolver} />
+```
+
+## Command boxes
+
+`{% command %}npm install @brett_lamy/ui{% endcommand %}` (or the block form, for
+several lines) becomes a `gbCommand` atom node rendered with Docstream's own
+command box: terminal glyph, pnpm / npm / yarn / bun switch (synced page-wide),
+copy button. When editable, the npm command and per-manager overrides
+(`pnpm="…"`, `yarn="…"`, `bun="…"`; the placeholder shows the derived command)
+are edited under the box. `sync` is preserved. Insert one with `/install command`.
+
 ## Slash Menu
 
 The editor includes a slash menu extension for inserting supported block structures. Type `/` in an empty paragraph to open block insertion options.
@@ -227,6 +286,7 @@ Exports:
 - `PMNode`
 - `EditorAttachment`
 - `serializeEditorMarkdown`
+- `markdownPasteContent` (the Markdown-paste parser behind `markdownPaste`)
 - `SourceFileEditor`
 - `SourceFileEditorProps`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -12,6 +12,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/__fixtures__",
     "README.md"
   ],
   "sideEffects": [
@@ -33,7 +34,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "1.0.0",
+    "@brett_lamy/docstream": "1.2.1",
     "gpu-lexer": "0.0.2",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -11,6 +11,7 @@ import {
 } from "lucide-react"
 
 import { parseMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
+import type { DemoResolver, InlineDemoRuntime } from "@brett_lamy/docstream/demo"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import {
   attachmentName,
@@ -20,7 +21,7 @@ import {
   readFileAsDataURL,
   type EditorAttachment,
 } from "./attachments"
-import { astToTiptap, serializeEditorMarkdown, tiptapToAst, type PMNode } from "./convert"
+import { astToTiptap, markdownPasteContent, serializeEditorMarkdown, tiptapToAst, type PMNode } from "./convert"
 import { createGitbookExtensions, type ReferenceSources } from "./extensions"
 import { EditorRuntimeProvider } from "./runtime"
 import type { SlashItem } from "./slash-menu"
@@ -86,6 +87,25 @@ export interface GitbookEditorProps {
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   /** Called when reading, writing, or previewing a file-backed source fails. */
   onSourceError?: (error: Error) => void
+  /**
+   * Resolves `{% demo src %}` ids. Demo blocks show docstream's (read-only) DemoViewer under
+   * their header: from the resolver when it knows `src`, otherwise from the files the block
+   * carries inline (a pasted Copy-page export), so the block looks like the docs page.
+   */
+  demoResolver?: DemoResolver
+  /**
+   * Runs the Preview of demos that carry their files inline and have no resolver behind them
+   * (as `DocRenderOptions.demoRuntime`), e.g. `createAlmostNodeDemoRuntime()` from
+   * `@brett_lamy/docstream/playground`. Without one, such demos show their code with a note.
+   */
+  demoRuntime?: InlineDemoRuntime
+  /** Extra npm dependencies inline demos may import (as `DocRenderOptions.demoDependencies`). */
+  demoDependencies?: Record<string, string>
+  /**
+   * Parse pasted plain-text Markdown that contains blocks (a docs page's "Copy page", a
+   * `{% … %}` block, a fence, a list …) into editor blocks instead of literal text (default true).
+   */
+  markdownPaste?: boolean
 }
 
 function ToolbarButton({
@@ -173,6 +193,10 @@ export function GitbookEditor({
   sourceAutoSave = true,
   onSourceSaved,
   onSourceError,
+  demoResolver,
+  demoRuntime,
+  demoDependencies,
+  markdownPaste = true,
 }: GitbookEditorProps) {
   // Tracks the markdown the editor itself produced, so external updates
   // (file switches) reset content but our own onChange echoes don't.
@@ -184,8 +208,8 @@ export function GitbookEditor({
   // Ids of the attachment chips in the document, to report removals.
   const attachmentIds = useRef<Set<string>>(new Set())
   // Latest callbacks for handlers the editor captured at creation.
-  const latest = useRef({ onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove })
-  latest.current = { onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove }
+  const latest = useRef({ onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove, markdownPaste })
+  latest.current = { onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove, markdownPaste }
   const editorRef = useRef<TiptapEditor | null>(null)
 
   // Pasted/dropped image files: image blocks ("inline") or attachment chips ("chip").
@@ -232,6 +256,27 @@ export function GitbookEditor({
     })
   }
 
+  // Plain-text Markdown (e.g. a docs page's "Copy page") becomes blocks, not literal text.
+  // Rich HTML clipboards keep ProseMirror's own handling; code editors (VS Code) also
+  // put styled HTML there, so their payload still counts as plain text.
+  const pasteMarkdown = (event: ClipboardEvent): boolean => {
+    const data = event.clipboardData
+    const ed = editorRef.current
+    if (!data || !ed) return false
+    const types = Array.from(data.types ?? [])
+    if (types.includes("text/html") && !types.includes("vscode-editor-data")) return false
+    const pasted = markdownPasteContent(data.getData("text/plain"))
+    if (!pasted?.content.length) return false
+    event.preventDefault()
+    if (pasted.citations) {
+      const known = new Map((citationsRef.current ?? []).map((c) => [c.id, c]))
+      for (const c of pasted.citations) known.set(c.id, c)
+      citationsRef.current = [...known.values()]
+    }
+    ed.chain().focus().insertContent(pasted.content).run()
+    return true
+  }
+
   const parseAndTrack = (md: string) => {
     const doc = parseMarkdown(md)
     citationsRef.current = doc.citations
@@ -254,10 +299,12 @@ export function GitbookEditor({
         if (latest.current.onPaste?.(event)) return true
         if (!view.editable || view.state.selection.$from.parent.type.spec.code) return false
         const files = imageFilesFrom(event.clipboardData, { ignoreWithText: true })
-        if (!files.length) return false
-        event.preventDefault()
-        insertImageFiles(files)
-        return true
+        if (files.length) {
+          event.preventDefault()
+          insertImageFiles(files)
+          return true
+        }
+        return latest.current.markdownPaste ? pasteMarkdown(event) : false
       },
       handleDrop: (view, event, _slice, moved) => {
         if (moved || !view.editable) return false
@@ -312,9 +359,12 @@ export function GitbookEditor({
     sourceAutoSave,
     ...(onSourceSaved ? { onSourceSaved } : {}),
     ...(onSourceError ? { onSourceError } : {}),
+    ...(demoResolver ? { demoResolver } : {}),
+    ...(demoRuntime ? { demoRuntime } : {}),
+    ...(demoDependencies ? { demoDependencies } : {}),
     ...(attachments ? { attachments } : {}),
     ...(onAttachmentOpen ? { onAttachmentOpen } : {}),
-  }), [attachments, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
+  }), [attachments, demoDependencies, demoResolver, demoRuntime, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
 
   if (!editor) return null
 

package/src/editor/convert.ts

@@ -1,7 +1,14 @@
 import {
+  parseMarkdown,
   plainText,
   serializeMarkdown,
   type Block,
+  type CitationDef,
+  type DemoLayout,
+  type CommandNode,
+  type DemoInlineFile,
+  type DemoNode,
+  type DemoViewport,
   type DocumentNode,
   type Inline,
   type ListItemNode,
@@ -56,7 +63,8 @@ function inlineToPM(nodes: Inline[]): PMNode[] {
       if (n.italic) marks.push({ type: "italic" })
       if (n.strike) marks.push({ type: "strike" })
       if (n.code) marks.push({ type: "code" })
-      if (n.link) marks.push({ type: "link", attrs: { href: n.link } })
+      // `inner` keeps `**[x](url)**` (link inside the emphasis) apart from `[**x**](url)`.
+      if (n.link) marks.push({ type: "link", attrs: { href: n.link, ...(n.linkInner ? { inner: true } : {}) } })
       return { type: "text", text: n.text, ...(marks.length ? { marks } : {}) }
     })
 }
@@ -93,20 +101,38 @@ function blockToPM(b: Block): PMNode {
           lineNumbers: b.lineNumbers,
           live: !!b.live,
           entry: b.entry ?? null,
+          collapsedCodeLines: b.collapsedCodeLines ?? null,
+          expandedCodeLines: b.expandedCodeLines ?? null,
         },
         content: b.code ? [{ type: "text", text: b.code }] : [],
       }
     case "hint":
       return { type: "gbHint", attrs: { style: b.style }, content: blocksPM(b.children) }
-    case "tabs":
+    case "tabs": {
+      const attrs = {
+        ...(b.sync ? { sync: b.sync } : {}),
+        ...(b.title ? { title: b.title } : {}),
+        ...(b.level ? { level: b.level } : {}),
+      }
       return {
         type: "gbTabs",
+        ...(Object.keys(attrs).length ? { attrs } : {}),
         content: b.tabs.map((t) => ({
           type: "gbTab",
           attrs: { title: t.title },
           content: blocksPM(t.children),
         })),
       }
+    }
+    case "command":
+      return {
+        type: "gbCommand",
+        attrs: {
+          command: b.command,
+          overrides: b.overrides && Object.keys(b.overrides).length ? { ...b.overrides } : null,
+          sync: b.sync ?? null,
+        },
+      }
     case "expandable":
       return {
         type: "gbExpandable",
@@ -132,8 +158,13 @@ function blockToPM(b: Block): PMNode {
       if (b.controls !== undefined) attrs.controls = b.controls
       return { type: "gbEmbed", attrs }
     }
-    case "content-ref":
-      return { type: "gbContentRef", attrs: { url: b.url, label: plainText(b.children) } }
+    case "content-ref": {
+      // GitBook writes the label as a link to the page (`[Card](card.md)`); remember
+      // whether this one was, so a plain label stays plain.
+      const only = b.children.length === 1 ? b.children[0] : undefined
+      const linked = only?.type === "text" && only.link === b.url && !only.bold && !only.italic && !only.strike && !only.code
+      return { type: "gbContentRef", attrs: { url: b.url, label: plainText(b.children), linked } }
+    }
     case "source-ref":
       return {
         type: "gbSourceRef",
@@ -145,6 +176,21 @@ function blockToPM(b: Block): PMNode {
           title: b.title ?? "",
         },
       }
+    case "demo":
+      return {
+        type: "gbDemo",
+        attrs: {
+          src: b.src,
+          title: b.title ?? "",
+          description: b.description ?? "",
+          height: b.height ?? "",
+          layout: b.layout ?? null,
+          variants: b.variants?.length ? b.variants.map((v) => ({ id: v.id, label: v.label })) : null,
+          viewport: b.viewport ?? null,
+          entry: b.entry ?? null,
+          files: b.files?.length ? b.files.map((f) => ({ ...f })) : null,
+        },
+      }
     case "columns":
       return {
         type: "gbColumns",
@@ -262,8 +308,12 @@ function pmTextToInline(nodes: PMNode[] | undefined): Inline[] {
         if (mark.type === "italic") inline.italic = true
         if (mark.type === "strike") inline.strike = true
         if (mark.type === "code") inline.code = true
-        if (mark.type === "link") inline.link = String(mark.attrs?.href ?? "")
+        if (mark.type === "link") {
+          inline.link = String(mark.attrs?.href ?? "")
+          if (mark.attrs?.inner) inline.linkInner = true
+        }
       }
+      if (inline.linkInner && !(inline.bold || inline.italic || inline.strike)) delete inline.linkInner
       return inline
     })
 }
@@ -286,7 +336,9 @@ function pmToBlock(n: PMNode): Block | null {
         level: (Number(n.attrs?.level) || 1) as 1 | 2 | 3 | 4 | 5 | 6,
         children: pmTextToInline(n.content),
       }
-    case "codeBlock":
+    case "codeBlock": {
+      const collapsed = Number(n.attrs?.collapsedCodeLines) || 0
+      const expanded = Number(n.attrs?.expandedCodeLines) || 0
       return {
         type: "code",
         language: (n.attrs?.language as string) || null,
@@ -294,15 +346,19 @@ function pmToBlock(n: PMNode): Block | null {
         lineNumbers: !!n.attrs?.lineNumbers,
         live: !!n.attrs?.live,
         entry: (n.attrs?.entry as string) || null,
+        ...(collapsed ? { collapsedCodeLines: collapsed } : {}),
+        ...(expanded ? { expandedCodeLines: expanded } : {}),
         code: n.content?.map((c) => c.text ?? "").join("") ?? "",
       }
+    }
     case "gbHint":
       return {
         type: "hint",
         style: (n.attrs?.style as never) ?? "info",
         children: pmToBlocks(n.content),
       }
-    case "gbTabs":
+    case "gbTabs": {
+      const level = Number(n.attrs?.level)
       return {
         type: "tabs",
         tabs: (n.content ?? []).map((t) => ({
@@ -310,7 +366,13 @@ function pmToBlock(n: PMNode): Block | null {
           title: String(t.attrs?.title ?? "Tab"),
           children: pmToBlocks(t.content),
         })),
+        ...(n.attrs?.sync ? { sync: String(n.attrs.sync) } : {}),
+        ...(n.attrs?.title ? { title: String(n.attrs.title) } : {}),
+        ...(level === 2 || level === 3 || level === 4 ? { level } : {}),
       }
+    }
+    case "gbCommand":
+      return pmToCommand(n.attrs ?? {})
     case "gbExpandable":
       return {
         type: "expandable",
@@ -339,12 +401,16 @@ function pmToBlock(n: PMNode): Block | null {
       if (typeof n.attrs?.controls === "boolean") embed.controls = n.attrs.controls
       return embed
     }
-    case "gbContentRef":
+    case "gbContentRef": {
+      const url = String(n.attrs?.url ?? "")
+      const label = String(n.attrs?.label ?? "")
+      const linked = n.attrs?.linked !== false && !!url && !!label
       return {
         type: "content-ref",
-        url: String(n.attrs?.url ?? ""),
-        children: [{ type: "text", text: String(n.attrs?.label ?? "") }],
+        url,
+        children: label ? [{ type: "text", text: label, ...(linked ? { link: url } : {}) }] : [],
       }
+    }
     case "gbSourceRef":
       return {
         type: "source-ref",
@@ -354,6 +420,8 @@ function pmToBlock(n: PMNode): Block | null {
         kind: n.attrs?.kind === "story" ? "story" : "component",
         ...(n.attrs?.title ? { title: String(n.attrs.title) } : {}),
       }
+    case "gbDemo":
+      return pmToDemo(n.attrs ?? {})
     case "gbColumns":
       return {
         type: "columns",
@@ -423,6 +491,60 @@ function pmToBlock(n: PMNode): Block | null {
   }
 }
 
+const DEMO_LAYOUTS: readonly string[] = ["auto", "single", "multi"] satisfies DemoLayout[]
+const DEMO_VIEWPORTS: readonly string[] = ["desktop", "tablet", "phone"] satisfies DemoViewport[]
+
+/** `gbDemo` attrs → `DemoNode`; also used by the node view to build the preview. */
+export function pmToDemo(a: Record<string, unknown>): DemoNode {
+  const variants = Array.isArray(a.variants)
+    ? (a.variants as Array<{ id?: unknown; label?: unknown }>)
+        .filter((v) => v && v.id)
+        .map((v) => ({ id: String(v.id), label: String(v.label || v.id) }))
+    : []
+  const layout = String(a.layout ?? "")
+  const files = pmDemoFiles(a.files)
+  const viewport = String(a.viewport ?? "")
+  return {
+    type: "demo",
+    src: String(a.src ?? ""),
+    ...(a.title ? { title: String(a.title) } : {}),
+    ...(a.description ? { description: String(a.description) } : {}),
+    ...(a.height ? { height: String(a.height) } : {}),
+    ...(DEMO_LAYOUTS.includes(layout) ? { layout: layout as DemoLayout } : {}),
+    ...(variants.length ? { variants } : {}),
+    ...(DEMO_VIEWPORTS.includes(viewport) ? { viewport: viewport as DemoViewport } : {}),
+    ...(a.entry ? { entry: String(a.entry) } : {}),
+    ...(files.length ? { files } : {}),
+  }
+}
+
+/** `gbDemo`'s `files` attr → inline demo files (malformed entries dropped). */
+export function pmDemoFiles(value: unknown): DemoInlineFile[] {
+  if (!Array.isArray(value)) return []
+  return (value as Array<Record<string, unknown> | null>)
+    .filter((f): f is Record<string, unknown> => !!f && typeof f === "object")
+    .map((f) => ({
+      path: String(f.path ?? ""),
+      content: String(f.content ?? ""),
+      ...(f.language ? { language: String(f.language) } : {}),
+    }))
+}
+
+const COMMAND_OVERRIDES = ["pnpm", "yarn", "bun"] as const
+
+/** `gbCommand` attrs → `CommandNode`; also used by the node view to render the box. */
+export function pmToCommand(a: Record<string, unknown>): CommandNode {
+  const raw = (a.overrides && typeof a.overrides === "object" ? a.overrides : {}) as Record<string, unknown>
+  const overrides: NonNullable<CommandNode["overrides"]> = {}
+  for (const pm of COMMAND_OVERRIDES) if (raw[pm]) overrides[pm] = String(raw[pm])
+  return {
+    type: "command",
+    command: String(a.command ?? ""),
+    ...(Object.keys(overrides).length ? { overrides } : {}),
+    ...(a.sync ? { sync: String(a.sync) } : {}),
+  }
+}
+
 function pmToBlocks(nodes: PMNode[] | undefined): Block[] {
   return (nodes ?? []).map(pmToBlock).filter((b): b is Block => b !== null)
 }
@@ -446,3 +568,17 @@ export function serializeEditorMarkdown(doc: DocumentNode): string {
     alt.includes("]") ? img : `![${alt}](${src})`
   )
 }
+
+/**
+ * Plain-text Markdown pasted into the editor (a docs page's "Copy page", a `{% … %}`
+ * block, a fence, a list, a heading…) as editor blocks, or null when the text is just
+ * prose — which the editor then pastes as text, as usual.
+ */
+export function markdownPasteContent(text: string): { content: PMNode[]; citations?: CitationDef[] } | null {
+  if (!text.trim()) return null
+  const doc = parseMarkdown(text)
+  const blocks = doc.children.some((b) => b.type !== "paragraph") || /(^|\n)\s*\{%\s*[a-z-]+/.test(text)
+  if (!blocks && !doc.citations?.length) return null
+  const content = astToTiptap(doc).content ?? []
+  return { content, ...(doc.citations?.length ? { citations: doc.citations } : {}) }
+}

package/src/editor/extensions.ts

@@ -2,7 +2,7 @@ import StarterKit from "@tiptap/starter-kit"
 import Placeholder from "@tiptap/extension-placeholder"
 import { TaskItem, TaskList } from "@tiptap/extension-list"
 import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table"
-import { getSchema, type AnyExtension } from "@tiptap/core"
+import { Extension, getSchema, type AnyExtension } from "@tiptap/core"
 import type { Schema } from "@tiptap/pm/model"
 import { GbCodeBlock, gitbookNodes } from "./nodes"
 import { SlashMenu, createSlashMenu, type SlashItem } from "./slash-menu"
@@ -15,6 +15,29 @@ export const GbTable = Table.extend({
   },
 })
 
+/**
+ * `inner` on the link mark: the link sits inside its emphasis (`**[x](url)**`)
+ * rather than around it (`[**x**](url)`). Kept so pasted Markdown round-trips
+ * byte-for-byte; newly created links default to the outer form.
+ */
+export const GbLinkInner = Extension.create({
+  name: "gbLinkInner",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["link"],
+        attributes: {
+          inner: {
+            default: null,
+            parseHTML: (element) => (element.hasAttribute("data-link-inner") ? true : null),
+            renderHTML: (attributes) => (attributes.inner ? { "data-link-inner": "" } : {}),
+          },
+        },
+      },
+    ]
+  },
+})
+
 export interface ReferenceSources {
   /** "@" — people, agents, … */
   mentions?: ReferenceSource
@@ -71,6 +94,7 @@ export function createGitbookExtensions(options: GitbookExtensionOptions = {}):
     TableHeader,
     TableCell,
     Placeholder.configure({ placeholder }),
+    GbLinkInner,
     ...gitbookNodes,
   ]
 

package/src/editor/nodes.tsx

@@ -10,11 +10,13 @@ import {
 } from "@tiptap/react"
 import {
   AlertTriangle,
+  AppWindow,
   AtSign,
   CheckCircle2,
   ChevronDown,
   FolderGit2,
   Hash,
+  Heading,
   Info,
   Link2,
   FileCode2,
@@ -26,10 +28,12 @@ import {
 import { DocsRenderer } from "@brett_lamy/docstream"
 import { resolveAsset } from "@brett_lamy/docstream/assets"
 import { OpenApiOperation } from "@brett_lamy/docstream/openapi"
-import type { DocumentNode, HintStyle, SourceRefNode } from "@brett_lamy/docstream/gitbook"
+import { packageManagerCommands, type DemoInlineFile, type DocumentNode, type HintStyle, type SourceRefNode } from "@brett_lamy/docstream/gitbook"
 import { ReactCodePreview } from "@brett_lamy/docstream/playground"
 import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
 import { VideoEmbed } from "@brett_lamy/docstream/video"
+import { DemoViewer } from "@brett_lamy/docstream/demo"
+import { pmToCommand, pmToDemo } from "./convert"
 import { SourceFileEditor } from "./SourceFileEditor"
 import { useEditorRuntime } from "./runtime"
 import { GbAttachment } from "./attachments"
@@ -132,9 +136,14 @@ function TabsView({ node, editor, getPos, updateAttributes }: NodeViewProps) {
     updateAttributes({ active: Math.max(0, active - (index <= active ? 1 : 0)) })
   }
 
-  return (
-    <NodeViewWrapper className="gb-tabs">
-      <div className="gb-tabs-header" contentEditable={false}>
+  const editable = editor.isEditable
+  const title = typeof node.attrs.title === "string" ? node.attrs.title : ""
+  const level = node.attrs.level === 3 || node.attrs.level === 4 ? node.attrs.level : 2
+  // `{% tabs title="…" %}`: the set renders as a section — heading, then the switch on its row.
+  const section = !!title || node.attrs.titled === true
+
+  const tabStrip = (
+    <>
         {titles.map((t, idx) => (
           <div
             key={idx}
@@ -158,11 +167,67 @@ function TabsView({ node, editor, getPos, updateAttributes }: NodeViewProps) {
             )}
           </div>
         ))}
-        {editor.isEditable && (
+        {editable && (
           <button className="gb-icon-btn" onClick={addTab} title="Add tab">
             <Plus className="size-3.5" />
           </button>
         )}
+        {editable && !section && (
+          <button
+            className="gb-icon-btn gb-tabs-add-title"
+            onClick={() => updateAttributes({ titled: true })}
+            title="Add a section title (renders the tabs as a titled section)"
+          >
+            <Heading className="size-3.5" />
+          </button>
+        )}
+    </>
+  )
+
+  if (section) {
+    const HeadingTag = `h${level}` as "h2" | "h3" | "h4"
+    return (
+      <NodeViewWrapper className="gb-tabs gb-tabs-section" data-level={level}>
+        <div className="gb-tabs-section-head" contentEditable={false}>
+          <HeadingTag className="gb-tabs-section-title">
+            {editable ? (
+              <input
+                className="gb-inline-input gb-tabs-section-input"
+                value={title}
+                placeholder="Section title…"
+                autoFocus={!title}
+                onChange={(e) => updateAttributes({ title: e.target.value || null })}
+                onBlur={(e) => {
+                  if (!e.target.value) updateAttributes({ title: null, titled: false })
+                }}
+              />
+            ) : (
+              title
+            )}
+          </HeadingTag>
+          {editable && (
+            <select
+              className="gb-tabs-level"
+              value={level}
+              title="Heading level"
+              onChange={(e) => updateAttributes({ level: Number(e.target.value) === 2 ? null : Number(e.target.value) })}
+            >
+              <option value={2}>H2</option>
+              <option value={3}>H3</option>
+              <option value={4}>H4</option>
+            </select>
+          )}
+          <div className="gb-tabs-pills">{tabStrip}</div>
+        </div>
+        <NodeViewContent className="gb-tabs-content" data-active={active} />
+      </NodeViewWrapper>
+    )
+  }
+
+  return (
+    <NodeViewWrapper className="gb-tabs">
+      <div className="gb-tabs-header" contentEditable={false}>
+        {tabStrip}
       </div>
       <NodeViewContent className="gb-tabs-content" data-active={active} />
     </NodeViewWrapper>
@@ -176,7 +241,28 @@ export const GbTabs = Node.create({
   defining: true,
   isolating: true,
   addAttributes() {
-    return { active: { default: 0, rendered: false } }
+    return {
+      active: { default: 0, rendered: false },
+      // `{% tabs sync="key" %}` — tab sets sharing a key follow the reader's last choice.
+      sync: {
+        default: null,
+        parseHTML: (element) => element.getAttribute("data-sync") || null,
+        renderHTML: (attributes) => (attributes.sync ? { "data-sync": attributes.sync } : {}),
+      },
+      // `{% tabs title="Installation" level="3" %}` — a titled set renders as a section heading.
+      title: {
+        default: null,
+        parseHTML: (element) => element.getAttribute("data-title") || null,
+        renderHTML: (attributes) => (attributes.title ? { "data-title": attributes.title } : {}),
+      },
+      level: {
+        default: null,
+        parseHTML: (element) => Number(element.getAttribute("data-level")) || null,
+        renderHTML: (attributes) => (attributes.level ? { "data-level": attributes.level } : {}),
+      },
+      // UI only: a title field is open but still empty.
+      titled: { default: false, rendered: false },
+    }
   },
   parseHTML() {
     return [{ tag: "div[data-gb-tabs]" }]
@@ -432,7 +518,8 @@ export const GbContentRef = Node.create({
   group: "block",
   atom: true,
   addAttributes() {
-    return { url: { default: "" }, label: { default: "" } }
+    // `linked`: the label is written as a link to the page (`[Card](card.md)`, GitBook's form).
+    return { url: { default: "" }, label: { default: "" }, linked: { default: true, rendered: false } }
   },
   parseHTML() {
     return [{ tag: "div[data-gb-content-ref]" }]
@@ -515,6 +602,308 @@ export const GbSourceRef = Node.create({
   },
 })
 
+// ---------- Demo ----------
+
+/** Inline demo files editor: a tab per file (path editable), a code area, add / remove. */
+function DemoFilesEditor({ files, entry, onChange }: {
+  files: DemoInlineFile[]
+  entry: string
+  onChange: (files: DemoInlineFile[], entry?: string | null) => void
+}) {
+  const [selected, setSelected] = useState(0)
+  const index = Math.min(selected, Math.max(0, files.length - 1))
+  const file = files[index]
+  const update = (patch: Partial<DemoInlineFile>) => {
+    const next = files.map((f, i) => {
+      if (i !== index) return f
+      const merged = { ...f, ...patch }
+      if (!merged.language) delete merged.language
+      return merged
+    })
+    // Renaming the entry file keeps it the entry.
+    const renamed = patch.path !== undefined && file && entry === file.path ? patch.path : undefined
+    onChange(next, renamed)
+  }
+  const add = () => {
+    const taken = new Set(files.map((f) => f.path))
+    let n = files.length + 1
+    let path = files.length ? `file${n}.tsx` : "index.tsx"
+    while (taken.has(path)) path = `file${++n}.tsx`
+    onChange([...files, { path, content: "", language: "tsx" }])
+    setSelected(files.length)
+  }
+  const remove = (i: number) => {
+    const removed = files[i]
+    onChange(files.filter((_, k) => k !== i), removed && entry === removed.path ? null : undefined)
+    setSelected(Math.max(0, i - 1))
+  }
+  return (
+    <div className="gb-demo-files">
+      <div className="gb-demo-files-tabs" role="tablist" aria-label="Demo files">
+        {files.map((f, i) => (
+          <div key={i} className={i === index ? "gb-demo-file-tab gb-demo-file-tab-active" : "gb-demo-file-tab"} onClick={() => setSelected(i)}>
+            {i === index ? (
+              <input
+                className="gb-demo-file-path"
+                value={f.path}
+                size={Math.max(f.path.length, 6)}
+                placeholder="index.tsx"
+                aria-label="File path"
+                onChange={(e) => update({ path: e.target.value })}
+              />
+            ) : (
+              <span>{f.path || "untitled"}</span>
+            )}
+            {f.path && entry === f.path ? <span className="gb-demo-file-entry">entry</span> : null}
+            <button type="button" className="gb-icon-btn" title={`Remove ${f.path || "file"}`} onClick={(e) => { e.stopPropagation(); remove(i) }}>
+              <X className="size-3" />
+            </button>
+          </div>
+        ))}
+        <button type="button" className="gb-icon-btn" title="Add file" onClick={add}>
+          <Plus className="size-3.5" />
+        </button>
+      </div>
+      {file ? (
+        <div className="gb-demo-file-body">
+          <div className="gb-demo-file-meta">
+            <input
+              className="gb-inline-input gb-demo-file-lang"
+              value={file.language ?? ""}
+              placeholder="lang"
+              aria-label="Language"
+              onChange={(e) => update({ language: e.target.value })}
+            />
+            <label className="gb-demo-file-entry-toggle">
+              <input
+                type="radio"
+                checked={entry ? entry === file.path : index === 0}
+                onChange={() => onChange(files, index === 0 ? null : file.path)}
+              />
+              Entry
+            </label>
+          </div>
+          <textarea
+            className="gb-demo-file-code"
+            value={file.content}
+            spellCheck={false}
+            rows={Math.min(24, Math.max(4, file.content.split("\n").length + 1))}
+            aria-label={`Edit ${file.path}`}
+            onChange={(e) => update({ content: e.target.value })}
+            onKeyDown={(e) => {
+              if (e.key !== "Tab" || e.shiftKey) return
+              e.preventDefault()
+              const el = e.currentTarget
+              const { selectionStart: a, selectionEnd: b } = el
+              update({ content: `${el.value.slice(0, a)}  ${el.value.slice(b)}` })
+              requestAnimationFrame(() => el.setSelectionRange(a + 2, a + 2))
+            }}
+          />
+        </div>
+      ) : (
+        <div className="gb-demo-files-empty">No inline files — the demo resolves from its <code>src</code>.</div>
+      )}
+    </div>
+  )
+}
+
+function DemoView({ node, updateAttributes, editor }: NodeViewProps) {
+  const editable = editor.isEditable
+  const { demoResolver, demoRuntime, demoDependencies } = useEditorRuntime()
+  const demo = useMemo(() => pmToDemo(node.attrs), [node.attrs])
+  const [filesOpen, setFilesOpen] = useState(false)
+  // Typing into `src` or a file would otherwise re-resolve / re-run every keystroke.
+  const src = useDebouncedValue(demo.src)
+  const files = useDebouncedValue(demo.files)
+  const entry = useDebouncedValue(demo.entry)
+  const hasFiles = !!demo.files?.length
+  // The resolver is the authority when it knows `src`; inline files stand in otherwise
+  // (DemoViewer falls back to them), so a pasted docs page looks like the page.
+  const preview = (!!demoResolver && !!src) || !!files?.length
+  const setFiles = (next: DemoInlineFile[], nextEntry?: string | null) => {
+    updateAttributes({
+      files: next.length ? next : null,
+      ...(nextEntry !== undefined ? { entry: nextEntry || null } : {}),
+    })
+  }
+  return (
+    <NodeViewWrapper className={preview || (editable && filesOpen) ? "gb-demo-block gb-demo-block-preview" : "gb-demo-block"} contentEditable={false}>
+      <div className="gb-demo">
+        <AppWindow className="size-4 shrink-0" />
+        {editable ? (
+          <>
+            <input className="gb-inline-input gb-demo-src" value={node.attrs.src} placeholder="page/example" onChange={(event) => updateAttributes({ src: event.target.value })} />
+            <input className="gb-inline-input gb-demo-title" value={node.attrs.title} placeholder="Title" onChange={(event) => updateAttributes({ title: event.target.value })} />
+            <button
+              type="button"
+              className={filesOpen ? "gb-demo-files-toggle gb-demo-files-toggle-active" : "gb-demo-files-toggle"}
+              title="Edit the files carried inline by this demo"
+              aria-expanded={filesOpen}
+              onClick={() => setFilesOpen((open) => !open)}
+            >
+              <FileCode2 className="size-3.5" />
+              {hasFiles ? `${demo.files!.length} file${demo.files!.length === 1 ? "" : "s"}` : "Files"}
+            </button>
+          </>
+        ) : (
+          <>
+            <code className="gb-demo-src">{demo.src || "demo"}</code>
+            {demo.title ? <span className="gb-demo-title">{demo.title}</span> : null}
+          </>
+        )}
+      </div>
+      {editable && filesOpen ? (
+        <DemoFilesEditor files={demo.files ?? []} entry={demo.entry ?? ""} onChange={setFiles} />
+      ) : null}
+      {preview ? (
+        <div className="gb-demo-preview">
+          <DemoViewer
+            key={src}
+            {...(demoResolver ? { resolver: demoResolver } : {})}
+            src={src}
+            title={demo.title}
+            description={demo.description}
+            height={demo.height}
+            layout={demo.layout}
+            variants={demo.variants}
+            viewport={demo.viewport}
+            files={files}
+            entry={entry}
+            {...(demoRuntime ? { runtime: demoRuntime } : {})}
+            {...(demoDependencies ? { dependencies: demoDependencies } : {})}
+          />
+        </div>
+      ) : null}
+    </NodeViewWrapper>
+  )
+}
+
+/**
+ * `{% demo %}` — every tag attribute is kept on the node, and the block form's inline
+ * files (`files`, in document order) with it, so it round-trips losslessly.
+ */
+export const GbDemo = Node.create({
+  name: "gbDemo",
+  group: "block",
+  atom: true,
+  addAttributes() {
+    return {
+      src: { default: "" },
+      title: { default: "" },
+      description: { default: "" },
+      height: { default: "" },
+      layout: { default: null },
+      variants: { default: null, rendered: false },
+      viewport: { default: null },
+      entry: { default: null },
+      // `{ path, content, language? }[]` — the files between `{% demo %}` and `{% enddemo %}`.
+      files: {
+        default: null,
+        rendered: false,
+        parseHTML: (element) => {
+          const raw = element.getAttribute("data-files")
+          if (!raw) return null
+          try {
+            return JSON.parse(raw)
+          } catch {
+            return null
+          }
+        },
+        renderHTML: (attributes) => (attributes.files ? { "data-files": JSON.stringify(attributes.files) } : {}),
+      },
+    }
+  },
+  parseHTML() {
+    return [{ tag: "div[data-gb-demo]" }]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return ["div", mergeAttributes(HTMLAttributes, { "data-gb-demo": node.attrs.src })]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(DemoView)
+  },
+})
+
+// ---------- Command (package-manager install box) ----------
+
+const COMMAND_MANAGERS = ["pnpm", "yarn", "bun"] as const
+
+function CommandView({ node, updateAttributes, editor }: NodeViewProps) {
+  const editable = editor.isEditable
+  const command = useMemo(() => pmToCommand(node.attrs), [node.attrs])
+  const derived = useMemo(() => packageManagerCommands(command.command), [command.command])
+  // docstream's own command box, so the editor shows exactly what readers get.
+  const doc = useMemo<DocumentNode>(() => ({ type: "doc", children: [command] }), [command])
+  const setOverride = (pm: (typeof COMMAND_MANAGERS)[number], value: string) => {
+    const next = { ...(command.overrides ?? {}) }
+    if (value) next[pm] = value
+    else delete next[pm]
+    updateAttributes({ overrides: Object.keys(next).length ? next : null })
+  }
+  return (
+    <NodeViewWrapper className="gb-command" contentEditable={false}>
+      {command.command ? (
+        <div className="gb-command-preview">
+          <DocsRenderer doc={doc} />
+        </div>
+      ) : null}
+      {editable ? (
+        <div className="gb-command-fields">
+          <label className="gb-command-field gb-command-field-npm">
+            <span>npm</span>
+            <textarea
+              className="gb-command-input"
+              value={command.command}
+              placeholder="npm install <package>"
+              spellCheck={false}
+              rows={Math.max(1, command.command.split("\n").length)}
+              onChange={(e) => updateAttributes({ command: e.target.value })}
+            />
+          </label>
+          {COMMAND_MANAGERS.map((pm) => (
+            <label key={pm} className="gb-command-field">
+              <span>{pm}</span>
+              <input
+                className="gb-inline-input gb-command-override"
+                value={command.overrides?.[pm] ?? ""}
+                placeholder={derived[pm] || `${pm} (derived)`}
+                spellCheck={false}
+                title={`Override the derived ${pm} command (leave empty to derive it)`}
+                onChange={(e) => setOverride(pm, e.target.value)}
+              />
+            </label>
+          ))}
+        </div>
+      ) : null}
+    </NodeViewWrapper>
+  )
+}
+
+/** `{% command %}npm install x{% endcommand %}` — one npm command shown for the reader's package manager. */
+export const GbCommand = Node.create({
+  name: "gbCommand",
+  group: "block",
+  atom: true,
+  addAttributes() {
+    return {
+      command: { default: "" },
+      // `{ pnpm?, yarn?, bun? }` — verbatim commands replacing the derived ones.
+      overrides: { default: null, rendered: false },
+      // Sync key; null means docstream's default ("pm").
+      sync: { default: null },
+    }
+  },
+  parseHTML() {
+    return [{ tag: "div[data-gb-command]" }]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return ["div", mergeAttributes(HTMLAttributes, { "data-gb-command": "" }), node.attrs.command]
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(CommandView)
+  },
+})
+
 // ---------- Columns ----------
 
 export const GbColumns = Node.create({
@@ -728,6 +1117,8 @@ export const GbCodeBlock = CodeBlock.extend({
       lineNumbers: { default: false },
       live: { default: false },
       entry: { default: null },
+      collapsedCodeLines: { default: null, rendered: false },
+      expandedCodeLines: { default: null, rendered: false },
     }
   },
   addNodeView() {
@@ -975,6 +1366,8 @@ export const gitbookNodes = [
   GbEmbed,
   GbContentRef,
   GbSourceRef,
+  GbDemo,
+  GbCommand,
   GbColumns,
   GbColumn,
   GbFigure,

package/src/editor/runtime.tsx

@@ -1,5 +1,6 @@
 import { createContext, useContext, type ReactNode } from "react"
 
+import type { DemoResolver, InlineDemoRuntime } from "@brett_lamy/docstream/demo"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
 import type { EditorAttachment } from "./attachments"
 
@@ -9,6 +10,9 @@ export interface EditorRuntimeOptions {
   sourceAutoSave?: boolean | number
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   onSourceError?: (error: Error) => void
+  demoResolver?: DemoResolver
+  demoRuntime?: InlineDemoRuntime
+  demoDependencies?: Record<string, string>
   attachments?: EditorAttachment[]
   onAttachmentOpen?: (attachment: EditorAttachment) => void
 }

package/src/editor/slash-menu.tsx

@@ -1,6 +1,7 @@
 import { Extension, type Editor, type Range } from "@tiptap/core"
 import Suggestion from "@tiptap/suggestion"
 import {
+  AppWindow,
   Columns2,
   FileCode2,
   Heading1,
@@ -22,6 +23,7 @@ import {
   SquareChevronDown,
   Superscript,
   Table as TableIcon,
+  Terminal,
   Webhook,
   Workflow,
   type LucideIcon,
@@ -71,6 +73,12 @@ export const SLASH_ITEMS: SlashItem[] = [
       ],
     }),
   },
+  {
+    title: "Install command",
+    keywords: "command npm pnpm yarn bun npx package manager install terminal shell",
+    icon: Terminal,
+    run: insertBlock({ type: "gbCommand", attrs: { command: "", overrides: null, sync: null } }),
+  },
   {
     title: "Expandable",
     keywords: "details accordion collapse",
@@ -101,6 +109,12 @@ export const SLASH_ITEMS: SlashItem[] = [
     icon: Link2,
     run: insertBlock({ type: "gbContentRef", attrs: { url: "", label: "Page link" } }),
   },
+  {
+    title: "Demo",
+    keywords: "example live preview component playground",
+    icon: AppWindow,
+    run: insertBlock({ type: "gbDemo", attrs: { src: "", title: "" } }),
+  },
   {
     title: "Columns",
     keywords: "two column layout",

package/src/index.ts

@@ -1,13 +1,13 @@
 export { GitbookEditor } from "./editor/Editor"
 export type { GitbookEditorProps, EditorAttachment } from "./editor/Editor"
-export { astToTiptap, tiptapToAst, serializeEditorMarkdown } from "./editor/convert"
+export { astToTiptap, tiptapToAst, serializeEditorMarkdown, markdownPasteContent } from "./editor/convert"
 export type { PMNode } from "./editor/convert"
 
 // Building blocks for composing a custom editor (e.g. with Yjs collaboration
 // or a bespoke slash menu) instead of the batteries-included GitbookEditor.
-export { createGitbookExtensions, getGitbookSchema, GbTable } from "./editor/extensions"
+export { createGitbookExtensions, getGitbookSchema, GbTable, GbLinkInner } from "./editor/extensions"
 export type { GitbookExtensionOptions, ReferenceSources } from "./editor/extensions"
-export { gitbookNodes, GbCodeBlock, GbReference } from "./editor/nodes"
+export { gitbookNodes, GbCodeBlock, GbCommand, GbDemo, GbReference } from "./editor/nodes"
 export { GbAttachment, formatBytes } from "./editor/attachments"
 export { SlashMenu, createSlashMenu, SLASH_ITEMS } from "./editor/slash-menu"
 export type { SlashItem } from "./editor/slash-menu"

package/src/styles.css

@@ -88,6 +88,126 @@
   width: 8rem;
 }
 
+.gb-demo {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  border: 1px solid var(--gb-border);
+  border-radius: var(--gb-radius);
+  padding: 0.65rem 0.8rem;
+  background: var(--gb-muted);
+}
+
+.gb-demo-block {
+  margin: 0.85em 0;
+}
+
+.gb-demo-block-preview > .gb-demo {
+  border-radius: var(--gb-radius) var(--gb-radius) 0 0;
+}
+
+.gb-demo-src {
+  flex: 1;
+}
+
+.gb-demo-title {
+  width: 12rem;
+}
+
+.gb-demo-preview {
+  border: 1px solid var(--gb-border);
+  border-top: 0;
+  border-radius: 0 0 var(--gb-radius) var(--gb-radius);
+  overflow: hidden;
+}
+
+.gb-demo-preview > * {
+  margin: 0;
+}
+
+.gb-demo-files-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  border: 1px solid var(--gb-border);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--gb-muted-foreground);
+  font-size: 12px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+.gb-demo-files-toggle-active { background: var(--gb-bg); color: var(--gb-text); }
+
+/* Inline demo files: a tab per file and a code area. */
+.gb-demo-files {
+  border: 1px solid var(--gb-border);
+  border-top: 0;
+  background: var(--gb-panel);
+}
+.gb-demo-block:not(.gb-demo-block-preview) .gb-demo-files,
+.gb-demo-files:last-child {
+  border-radius: 0 0 var(--gb-radius) var(--gb-radius);
+}
+.gb-demo-files-tabs {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 2px;
+  padding: 6px 8px 0;
+  border-bottom: 1px solid var(--gb-border);
+  background: var(--gb-muted);
+}
+.gb-demo-file-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 5px 10px;
+  border-radius: 8px 8px 0 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12px;
+  color: var(--gb-muted-foreground);
+  cursor: pointer;
+}
+.gb-demo-file-tab-active { background: var(--gb-panel); color: var(--gb-text); }
+.gb-demo-file-path { font: inherit; color: inherit; background: transparent; border: none; outline: none; }
+.gb-demo-file-entry {
+  padding: 0 5px;
+  border-radius: 4px;
+  background: var(--gb-accent);
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.gb-demo-file-body { display: flex; flex-direction: column; }
+.gb-demo-file-meta {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 4px 12px;
+  font-size: 12px;
+  color: var(--gb-muted-foreground);
+}
+.gb-demo-file-lang { width: 6rem; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.gb-demo-file-entry-toggle { display: inline-flex; align-items: center; gap: 4px; }
+.gb-demo-file-code {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  padding: 8px 12px 12px;
+  border: 0;
+  outline: none;
+  resize: vertical;
+  background: transparent;
+  color: var(--gb-code-fg);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12.5px;
+  line-height: 1.55;
+  tab-size: 2;
+}
+.gb-demo-files-empty { padding: 10px 12px; font-size: 12.5px; color: var(--gb-muted-foreground); }
+
 .gb-source-file-editor {
   border: 1px solid var(--gb-border);
   border-radius: var(--gb-radius);
@@ -369,6 +489,84 @@
 .gb-tabs-content .gb-tab > :first-child { margin-top: 0; }
 .gb-tabs-content .gb-tab > :last-child { margin-bottom: 0; }
 
+/* ── Titled tabs (mirrors .docs-tabs-section): heading + pill switch on one row ── */
+.gb-tabs-section {
+  border: 0;
+  border-radius: 0;
+  overflow: visible;
+  margin: 1.6em 0 0.9em;
+}
+.gb-tabs-section-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+.gb-tabs-section-title {
+  flex: 1;
+  min-width: 10rem;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.gb-tabs-section-input { width: 100%; font-weight: inherit; font-size: inherit; letter-spacing: inherit; }
+.gb-tabs-level {
+  font-size: 12px;
+  color: var(--gb-muted-foreground);
+  background: transparent;
+  border: 1px solid var(--gb-border);
+  border-radius: 6px;
+}
+.gb-tabs-pills {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  border-radius: 999px;
+  background: var(--gb-muted);
+}
+.gb-tabs-pills .gb-tabs-tab { padding: 4px 12px; border-radius: 999px; font-size: 13px; }
+.gb-tabs-pills .gb-tabs-tab-active { background: var(--gb-bg); box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08); }
+.gb-tabs-section > .gb-tabs-content { padding: 0; }
+
+/* ── Command box: docstream's own box, with the editable npm command + overrides below ── */
+.gb-command { margin: 0.85em 0; }
+.gb-command-preview .docs-article { margin: 0; padding: 0; max-width: none; }
+.gb-command-preview .docs-command { margin: 0; }
+.gb-command-fields {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 6px 10px;
+  margin-top: 6px;
+  padding: 8px 10px;
+  border: 1px dashed var(--gb-border);
+  border-radius: 10px;
+  font-size: 12.5px;
+}
+.gb-command-field { display: flex; align-items: baseline; gap: 6px; min-width: 0; }
+.gb-command-field > span {
+  flex-shrink: 0;
+  width: 2.8rem;
+  color: var(--gb-muted-foreground);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+.gb-command-field-npm { grid-column: 1 / -1; }
+.gb-command-input,
+.gb-command-override {
+  flex: 1;
+  min-width: 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 12.5px;
+}
+.gb-command-input {
+  resize: vertical;
+  background: transparent;
+  border: none;
+  outline: none;
+  color: inherit;
+}
+
 /* ── Expandable (mirrors .docs-expandable) ──────────────── */
 .gb-expandable {
   border: 1px solid var(--gb-border);