@brett_lamy/docstream 1.1.1 → 1.2.1

package/src/gitbook/ast.ts

@@ -11,6 +11,11 @@ export interface TextNode {
   strike?: boolean
   code?: boolean
   link?: string
+  /**
+   * The link sits inside the emphasis (`**[x](url)**`) rather than around it
+   * (`[**x**](url)`, the default). Kept so the source round-trips byte-for-byte.
+   */
+  linkInner?: true
 }
 
 /** Inline HTML image, optionally wrapped in a link — GitHub README badge style. */
@@ -94,6 +99,33 @@ export interface TabsNode {
    * the reader's last choice (matched by tab title), remembered across pages.
    */
   sync?: string
+  /**
+   * Section title (`{% tabs title="Installation" %}`). The tab set renders as a
+   * section: this title as a heading (with an anchor id), the tab switch as pill
+   * tabs right-aligned in that header, and the active tab's blocks below.
+   */
+  title?: string
+  /** Heading level of `title` (`level="3"`). Defaults to 2. */
+  level?: 2 | 3 | 4
+}
+
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun"
+
+/**
+ * A package-manager command box: `{% command %}npm install x{% endcommand %}`.
+ * The author writes one canonical npm / npx command; renderers derive the pnpm,
+ * yarn and bun forms (see `packageManagerCommands`), unless overridden per
+ * manager (`pnpm="…"`). The reader's manager is synced page-wide (and across
+ * pages) under `sync` — `"pm"` by default, the same key install `{% tabs %}` use.
+ */
+export interface CommandNode {
+  type: "command"
+  /** The npm / npx command (may span lines). */
+  command: string
+  /** Explicit commands for other managers, used verbatim instead of the derived ones. */
+  overrides?: Partial<Record<Exclude<PackageManager, "npm">, string>>
+  /** Sync key. Omitted means `"pm"`. */
+  sync?: string
 }
 
 export interface ExpandableNode {
@@ -156,11 +188,27 @@ export interface DemoVariantOption {
   label: string
 }
 
+/** One source file carried inline by a `{% demo %}` block (a titled fence). */
+export interface DemoInlineFile {
+  /** Path relative to the demo folder, from the fence's `title` (`index.tsx`, `parts/Card.tsx`). */
+  path: string
+  content: string
+  /** The fence's info-string language, when it has one. */
+  language?: string
+}
+
 /**
- * A file-backed live demo: `{% demo src="<page>/<example>" %}`. The example
- * folder (resolved by the host's `DemoResolver`) is the authority for the
- * component, its source files, and its defaults; attributes here override the
- * folder's `meta.json`.
+ * A live demo: `{% demo src="<page>/<example>" %}`. With a host `DemoResolver`
+ * that knows `src`, the example folder is the authority for the component, its
+ * source files and its defaults; attributes here override the folder's
+ * `meta.json`. The block form carries the files inline so the Markdown renders
+ * anywhere, resolver or not:
+ *
+ *     {% demo src="composer/scroll-fab" title="Scroll → FAB" %}
+ *     ```tsx title="index.tsx"
+ *     …
+ *     ```
+ *     {% enddemo %}
  */
 export interface DemoNode {
   type: "demo"
@@ -175,6 +223,16 @@ export interface DemoNode {
   variants?: DemoVariantOption[]
   /** Initial preview viewport for the multi-file viewer. */
   viewport?: DemoViewport
+  /** Entry file among the inline files (`entry="App.tsx"`). Defaults to the first file. */
+  entry?: string
+  /** Files carried inline by the block form, in document order. */
+  files?: DemoInlineFile[]
+  /**
+   * Set while streaming when the block's `{% enddemo %}` has not arrived yet: the
+   * files may still be growing, so renderers show code but hold off running it.
+   * Never serialized.
+   */
+  open?: true
 }
 
 export interface ColumnNode {
@@ -256,6 +314,7 @@ export type Block =
   | CodeBlockNode
   | HintNode
   | TabsNode
+  | CommandNode
   | ExpandableNode
   | StepperNode
   | EmbedNode

package/src/gitbook/flatten.ts

@@ -0,0 +1,47 @@
+import type { Block, DocumentNode } from "./ast"
+import { text } from "./ast"
+
+/**
+ * docstream-only presentation blocks as plain Markdown, for LLM prompts and tools that don't
+ * know docstream (`resolveDemosToMarkdown(…, { format: "plain" })`):
+ *
+ * - `{% command %}` → a ```` ```sh ```` fence with the npm command;
+ * - titled `{% tabs title="Installation" %}` → a `## Installation` heading, then each tab as a
+ *   bold label followed by its blocks.
+ *
+ * Everything else is kept (GitBook tags included — they're GitBook, not docstream).
+ */
+export function flattenForPlainMarkdown(doc: DocumentNode): DocumentNode {
+  return { ...doc, children: flattenBlocks(doc.children) }
+}
+
+export function flattenBlocks(blocks: Block[]): Block[] {
+  return blocks.flatMap((b): Block[] => {
+    switch (b.type) {
+      case "command":
+        return [{ type: "code", language: "sh", title: null, lineNumbers: true, code: b.command }]
+      case "tabs":
+        if (b.title) {
+          return [
+            { type: "heading", level: b.level ?? 2, children: [text(b.title)] },
+            ...b.tabs.flatMap((t): Block[] => [{ type: "paragraph", children: [text(t.title, { bold: true })] }, ...flattenBlocks(t.children)]),
+          ]
+        }
+        return [{ ...b, tabs: b.tabs.map((t) => ({ ...t, children: flattenBlocks(t.children) })) }]
+      case "hint":
+      case "expandable":
+      case "blockquote":
+        return [{ ...b, children: flattenBlocks(b.children) }]
+      case "stepper":
+        return [{ ...b, steps: b.steps.map((s) => ({ ...s, children: flattenBlocks(s.children) })) }]
+      case "columns":
+        return [{ ...b, columns: b.columns.map((c) => ({ ...c, children: flattenBlocks(c.children) })) }]
+      case "list":
+        return [{ ...b, items: b.items.map((item) => ({ ...item, children: flattenBlocks(item.children) })) }]
+      case "updates":
+        return [{ ...b, updates: b.updates.map((u) => ({ ...u, children: flattenBlocks(u.children) })) }]
+      default:
+        return [b]
+    }
+  })
+}

package/src/gitbook/index.ts

@@ -1,6 +1,10 @@
 // Pure GitBook markdown engine (no React, no mermaid/streamdown). Safe to import
 // in non-DOM environments such as a server-side AI agent or a Cloudflare Worker.
 export type * from "./ast"
-export { parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
-export { serializeBlocks, serializeMarkdown } from "./serialize"
+export { closesFence, demoBody, fenceOpener, fenceTracker, parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./parse"
+export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./serialize"
 export { footnoteDefinitions, parseInline, plainText, refDefinitions, serializeInline, serializeReference } from "./inline"
+export { PACKAGE_MANAGERS, packageManagerCommands } from "./package-managers"
+export { flattenBlocks, flattenForPlainMarkdown } from "./flatten"
+export { documentOutline, slugify } from "./outline"
+export type { OutlineEntry } from "./outline"

package/src/gitbook/inline.ts

@@ -155,7 +155,8 @@ export function parseInline(src: string, marks: Marks = {}): Inline[] {
       const m = rest.match(/^\[([^\]]*)\]\(([^)\s]+)\)/)
       if (m) {
         flush()
-        out.push(...parseInline(m[1], { ...marks, link: m[2] }))
+        const inner = marks.bold || marks.italic || marks.strike ? { linkInner: true as const } : {}
+        out.push(...parseInline(m[1], { ...marks, link: m[2], ...inner }))
         i += m[0].length
         continue
       }
@@ -228,25 +229,54 @@ function serializeImage(n: InlineImageNode): string {
   return n.link ? `<a href="${n.link}">${img}</a>` : img
 }
 
-// Serializes inline nodes back to markdown.
+// Serializes inline nodes back to markdown. Emphasis (bold / italic / strike) is kept open across
+// adjacent runs that share it, so `**bold [link](url) inside**` — three runs under one bold — comes back
+// as written instead of `**bold ****[link](url)**** inside**`.
+type Emphasis = "strike" | "italic" | "bold"
+const EMPHASIS: Emphasis[] = ["strike", "italic", "bold"] // outermost → innermost
+const MARKER: Record<Emphasis, string> = { strike: "~~", italic: "_", bold: "**" }
+
+function textBody(n: TextNode): string {
+  const s = n.code ? n.text : escapeText(n.text)
+  return n.code ? `\`${s}\`` : s
+}
+
 export function serializeInline(nodes: Inline[]): string {
-  return nodes
-    .map((n) => {
-      if (n.type === "image") return serializeImage(n)
-      if (n.type === "reference") return serializeReference(n)
-      // bare autolink: text identical to the URL, no other marks
-      if (n.link && n.text === n.link && !n.bold && !n.italic && !n.strike && !n.code) {
-        return n.link
-      }
-      let s = n.code ? n.text : escapeText(n.text)
-      if (n.code) s = `\`${s}\``
-      if (n.bold) s = `**${s}**`
-      if (n.italic) s = `_${s}_`
-      if (n.strike) s = `~~${s}~~`
-      if (n.link) s = `[${s}](${n.link})`
-      return s
-    })
-    .join("")
+  let out = ""
+  const open: Emphasis[] = []
+  const closeTo = (depth: number) => {
+    while (open.length > depth) out += MARKER[open.pop()!]
+  }
+  for (const n of nodes) {
+    if (n.type !== "text") {
+      closeTo(0)
+      out += n.type === "image" ? serializeImage(n) : serializeReference(n)
+      continue
+    }
+    // bare autolink: text identical to the URL, no other marks
+    if (n.link && n.text === n.link && !n.bold && !n.italic && !n.strike && !n.code) {
+      closeTo(0)
+      out += n.link
+      continue
+    }
+    const wanted = EMPHASIS.filter((m) => n[m])
+    // A link around its emphasis (`[**x**](url)`) is self-contained: close everything, wrap this run alone.
+    if (n.link && !(n.linkInner && wanted.length)) {
+      closeTo(0)
+      let s = textBody(n)
+      for (const m of [...wanted].reverse()) s = `${MARKER[m]}${s}${MARKER[m]}`
+      out += `[${s}](${n.link})`
+      continue
+    }
+    // Keep the longest prefix of open marks this run still wants, close the rest, open what's missing.
+    let keep = 0
+    while (keep < open.length && wanted.includes(open[keep])) keep++
+    closeTo(keep)
+    for (const m of wanted) if (!open.includes(m)) { open.push(m); out += MARKER[m] }
+    out += n.link ? `[${textBody(n)}](${n.link})` : textBody(n)
+  }
+  closeTo(0)
+  return out
 }
 
 export function plainText(nodes: Inline[]): string {

package/src/gitbook/outline.ts

@@ -0,0 +1,45 @@
+import type { Block, DocumentNode } from "./ast"
+import { plainText } from "./inline"
+
+/** Anchor id for a heading: `"Installation"` → `"installation"`. */
+export function slugify(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[̀-ͯ]/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "") || "section"
+  )
+}
+
+export interface OutlineEntry {
+  level: number
+  text: string
+  /** The anchor id docstream renders for titled tab sets; hosts may reuse it for headings. */
+  id: string
+}
+
+/**
+ * The page's headings for a table of contents — Markdown headings plus the titles of
+ * `{% tabs title="…" %}` sections — in document order (top level and inside hints,
+ * tabs, steppers, columns and expandables).
+ */
+export function documentOutline(doc: DocumentNode | Block[]): OutlineEntry[] {
+  const out: OutlineEntry[] = []
+  const walk = (blocks: Block[]) => {
+    for (const b of blocks) {
+      if (b.type === "heading") {
+        const text = plainText(b.children)
+        if (text) out.push({ level: b.level, text, id: slugify(text) })
+      } else if (b.type === "tabs") {
+        if (b.title) out.push({ level: b.level ?? 2, text: b.title, id: slugify(b.title) })
+        for (const t of b.tabs) walk(t.children)
+      } else if (b.type === "hint" || b.type === "expandable") walk(b.children)
+      else if (b.type === "stepper") for (const s of b.steps) walk(s.children)
+      else if (b.type === "columns") for (const c of b.columns) walk(c.children)
+    }
+  }
+  walk(Array.isArray(doc) ? doc : doc.children)
+  return out
+}

package/src/gitbook/package-managers.ts

@@ -0,0 +1,98 @@
+import type { CommandNode, PackageManager } from "./ast"
+
+/** Display order of the command box's manager tabs. The first is the default choice. */
+export const PACKAGE_MANAGERS: readonly PackageManager[] = ["pnpm", "npm", "yarn", "bun"]
+
+type Others = Exclude<PackageManager, "npm">
+
+const INSTALL = new Set(["install", "i", "add"])
+const UNINSTALL = new Set(["uninstall", "un", "remove", "rm", "r"])
+const LIFECYCLE = new Set(["test", "start", "stop", "restart"])
+
+/** npm install flags → per-manager flags. Unknown flags pass through unchanged. */
+const FLAGS: Record<string, Record<Others, string | null>> = {
+  "-D": { pnpm: "-D", yarn: "-D", bun: "-d" },
+  "--save-dev": { pnpm: "-D", yarn: "-D", bun: "-d" },
+  "-E": { pnpm: "-E", yarn: "-E", bun: "--exact" },
+  "--save-exact": { pnpm: "-E", yarn: "-E", bun: "--exact" },
+  "-O": { pnpm: "-O", yarn: "-O", bun: "--optional" },
+  "--save-optional": { pnpm: "-O", yarn: "-O", bun: "--optional" },
+  "-P": { pnpm: "-P", yarn: null, bun: null },
+  "--save-prod": { pnpm: "-P", yarn: null, bun: null },
+  "-S": { pnpm: null, yarn: null, bun: null },
+  "--save": { pnpm: null, yarn: null, bun: null },
+}
+
+function flags(args: string[], pm: Others): string[] {
+  return args.flatMap((arg) => {
+    const mapped = FLAGS[arg]
+    if (!mapped) return [arg]
+    const next = mapped[pm]
+    return next ? [next] : []
+  })
+}
+
+const join = (...parts: (string | string[])[]) => parts.flat().filter(Boolean).join(" ")
+
+/** One npm / npx invocation (already split into words) for another manager, or null if it isn't one. */
+function convertWords(words: string[], pm: Others): string | null {
+  const [head, sub, ...rest] = words
+  if (head === "npx") {
+    const args = words.slice(1).filter((w) => w !== "-y" && w !== "--yes")
+    return join(pm === "bun" ? "bunx" : `${pm} dlx`, args)
+  }
+  if (head !== "npm" || sub === undefined) return head === "npm" ? pm : null
+  if (sub === "exec" || sub === "x") {
+    const args = rest[0] === "--" ? rest.slice(1) : rest
+    return join(pm === "bun" ? "bunx" : `${pm} dlx`, args.filter((w) => w !== "-y" && w !== "--yes"))
+  }
+  if (INSTALL.has(sub)) {
+    const global = rest.some((w) => w === "-g" || w === "--global")
+    const args = rest.filter((w) => w !== "-g" && w !== "--global")
+    const packages = args.filter((w) => !w.startsWith("-"))
+    if (!packages.length && !global) return join(`${pm} install`, flags(args, pm))
+    if (global) return join(pm === "yarn" ? "yarn global add" : `${pm} add -g`, flags(args, pm))
+    return join(`${pm} add`, flags(args, pm))
+  }
+  if (sub === "ci") return `${pm} install --frozen-lockfile`
+  if (UNINSTALL.has(sub)) {
+    const global = rest.some((w) => w === "-g" || w === "--global")
+    const args = rest.filter((w) => w !== "-g" && w !== "--global")
+    return join(global ? (pm === "yarn" ? "yarn global remove" : `${pm} remove -g`) : `${pm} remove`, flags(args, pm))
+  }
+  if (sub === "run" || sub === "run-script") {
+    const [script, ...args] = rest
+    const tail = args[0] === "--" && pm !== "bun" ? args.slice(1) : args
+    return join(pm === "bun" ? "bun run" : pm, script ?? "", tail)
+  }
+  if (LIFECYCLE.has(sub)) return join(pm === "bun" ? "bun run" : pm, sub, rest[0] === "--" && pm !== "bun" ? rest.slice(1) : rest)
+  if (sub === "create" || (sub === "init" && rest.length && !rest[0].startsWith("-"))) return join(`${pm} create`, rest)
+  if (sub === "update" || sub === "up" || sub === "upgrade") return join(pm === "yarn" ? "yarn upgrade" : `${pm} update`, rest)
+  return join(pm, sub, rest)
+}
+
+/** One line (possibly `a && b`) for another manager. Lines that aren't npm/npx commands are kept. */
+function convertLine(line: string, pm: Others): string {
+  const indent = line.match(/^\s*/)![0]
+  return indent + line.trim().split(/\s+&&\s+/).map((segment) => {
+    const prompt = segment.match(/^\$\s+/)?.[0] ?? ""
+    const words = segment.slice(prompt.length).split(/\s+/).filter(Boolean)
+    const converted = words.length ? convertWords(words, pm) : null
+    return converted === null ? segment : prompt + converted
+  }).join(" && ")
+}
+
+/**
+ * The pnpm / yarn / bun forms of an npm / npx command:
+ * `npm install x` → `pnpm add x`, `yarn add x`, `bun add x` (with `-D`, `-E`, `-g`, …);
+ * `npx x` → `pnpm dlx x`, `yarn dlx x`, `bunx x`; `npm run s` → `pnpm s`, `yarn s`, `bun run s`;
+ * `npm create x` → `<pm> create x`. Other lines (comments, `cd`, …) are kept as they are.
+ * `overrides` replace a manager's derived command verbatim.
+ */
+export function packageManagerCommands(
+  npmCommand: string,
+  overrides: CommandNode["overrides"] = {},
+): Record<PackageManager, string> {
+  const derive = (pm: Others) => overrides[pm] ?? npmCommand.split("\n").map((line) => convertLine(line, pm)).join("\n")
+  return { npm: npmCommand, pnpm: derive("pnpm"), yarn: derive("yarn"), bun: derive("bun") }
+}

package/src/gitbook/parse.ts

@@ -1,6 +1,8 @@
 import type {
   Block,
   ColumnNode,
+  CommandNode,
+  DemoInlineFile,
   DemoLayout,
   DemoNode,
   DemoVariantOption,
@@ -92,13 +94,57 @@ function templateTag(line: string): TemplateTag | null {
   return { name: m[1], attrs: parseAttrs(m[2]) }
 }
 
+interface Fence {
+  char: "`" | "~"
+  length: number
+}
+
+/** A fence opener (```` ```ts title="x" ```` or `~~~`), or null. Backtick info strings cannot contain backticks. */
+export function fenceOpener(line: string): Fence | null {
+  const m = line.match(/^\s*(`{3,}|~{3,})(.*)$/)
+  if (!m) return null
+  if (m[1][0] === "`" && m[2].includes("`")) return null
+  return { char: m[1][0] as Fence["char"], length: m[1].length }
+}
+
+/** True when `line` closes `fence`: the same character, at least as many, nothing else. */
+export function closesFence(line: string, fence: Fence): boolean {
+  const trimmed = line.trim()
+  return trimmed.length >= fence.length && trimmed === fence.char.repeat(trimmed.length)
+}
+
+/** Tracks whether a line-by-line scan is inside a fenced code block. */
+export function fenceTracker() {
+  let open: Fence | null = null
+  return {
+    /** Feed the next line; returns true if the line is fence content or a fence delimiter. */
+    step(line: string): boolean {
+      if (open) {
+        if (closesFence(line, open)) open = null
+        return true
+      }
+      open = fenceOpener(line)
+      return open !== null
+    },
+    get inside() {
+      return open !== null
+    },
+  }
+}
+
 // Collects the lines between an opening {% name %} and its matching
-// {% endname %}, honoring nesting of the same tag.
+// {% endname %}, honoring nesting of the same tag. Tags inside fenced code
+// (a demo file, a Markdown sample) are content, not structure.
 function collectUntil(lines: string[], start: number, name: string): { body: string[]; next: number } {
   const body: string[] = []
   let depth = 1
   let i = start
+  const fences = fenceTracker()
   for (; i < lines.length; i++) {
+    if (fences.step(lines[i])) {
+      body.push(lines[i])
+      continue
+    }
     const tag = templateTag(lines[i])
     if (tag?.name === name) depth++
     if (tag?.name === `end${name}`) {
@@ -131,11 +177,10 @@ export function parseMarkdown(src: string): DocumentNode {
   refDefinitions.clear()
   footnoteDefinitions.clear()
   const content: string[] = []
-  let inFence = false
+  const fences = fenceTracker()
   for (const line of lines) {
     // Definition lines inside code fences are content, not definitions.
-    if (/^\s*(?:```|~~~)/.test(line)) inFence = !inFence
-    if (!inFence) {
+    if (!fences.step(line)) {
       // Footnote citation definitions first: [^id]: url "Optional Label"
       const foot = line.match(/^\[\^([^\]\s]+)\]:\s*(\S+)(?:\s+"([^"]*)")?\s*$/)
       if (foot) {
@@ -178,6 +223,97 @@ export function parseDemoVariants(raw: string): DemoVariantOption[] {
     .filter((v) => v.id)
 }
 
+/** `{% command %}npm install x{% endcommand %}` on one line. */
+const COMMAND_ONE_LINE_RE = /^\s*\{%\s*command(\s[^%]*?)?\s*%\}(.*?)\{%\s*endcommand\s*%\}\s*$/
+
+function commandNode(attrs: Record<string, string>, raw: string): CommandNode {
+  const overrides: NonNullable<CommandNode["overrides"]> = {}
+  for (const pm of ["pnpm", "yarn", "bun"] as const) if (attrs[pm]) overrides[pm] = attrs[pm]
+  return {
+    type: "command",
+    command: raw.replace(/^(?:[ \t]*\n)+/, "").replace(/(?:\n[ \t]*)+$/, "").trim(),
+    ...(Object.keys(overrides).length ? { overrides } : {}),
+    ...(attrs.sync && attrs.sync !== "pm" ? { sync: attrs.sync } : {}),
+  }
+}
+
+const ENDDEMO_RE = /^\s*\{%\s*enddemo\s*%\}\s*$/
+
+interface DemoBody {
+  files: DemoInlineFile[]
+  /** First line after the block. */
+  next: number
+  /** The input ended before `{% enddemo %}` (a block still streaming in). */
+  open: boolean
+}
+
+function fallbackPath(index: number, language: string | undefined): string {
+  const ext = language || "txt"
+  return index === 0 ? `index.${ext}` : `file-${index + 1}.${ext}`
+}
+
+/**
+ * The inline files of a `{% demo %}` block starting at `start` (the line after the tag).
+ *
+ * - `{% enddemo %}` right away: an empty block.
+ * - A fence right away: the block form. Fences (and blank lines) are files until
+ *   `{% enddemo %}`; any other line ends the block too. Reaching the end of input
+ *   first marks the block `open` (still streaming).
+ * - Blank lines, then fences: the block form only if `{% enddemo %}` closes it with
+ *   nothing but fences in between — otherwise the tag is self-closing and the fences
+ *   are ordinary code blocks, exactly as before 1.2.
+ * - Anything else: no body (self-closing tag).
+ */
+export function demoBody(lines: string[], start: number, selfClosing = false): DemoBody | null {
+  let j = start
+  if (j < lines.length && ENDDEMO_RE.test(lines[j])) return { files: [], next: j + 1, open: false }
+  // `{% demo … /%}` takes no files (a directly following `{% enddemo %}` is tolerated above).
+  if (selfClosing) return null
+  const immediate = j < lines.length && fenceOpener(lines[j]) !== null
+  if (!immediate) {
+    while (j < lines.length && !lines[j].trim()) j++
+    if (j >= lines.length) return null
+    if (ENDDEMO_RE.test(lines[j])) return { files: [], next: j + 1, open: false }
+    if (!fenceOpener(lines[j])) return null
+  }
+  const files: DemoInlineFile[] = []
+  while (j < lines.length) {
+    const line = lines[j]
+    if (!line.trim()) {
+      j++
+      continue
+    }
+    if (ENDDEMO_RE.test(line)) return { files, next: j + 1, open: false }
+    const fence = fenceOpener(line)
+    if (!fence) return immediate ? { files, next: j, open: false } : null
+    const info = line.trim().slice(fence.length).trim()
+    // `tsx title="index.tsx"` or just `title="index.tsx"` (no language).
+    const first = info.match(/^[^\s`]*/)?.[0] ?? ""
+    const language = first.includes("=") ? "" : first
+    const rest = language ? info.slice(language.length) : info
+    const attrs = parseAttrs(rest)
+    const content: string[] = []
+    j++
+    let closed = false
+    while (j < lines.length) {
+      if (closesFence(lines[j], fence)) {
+        closed = true
+        j++
+        break
+      }
+      content.push(lines[j])
+      j++
+    }
+    files.push({
+      path: (attrs.title ?? "").trim() || fallbackPath(files.length, language || undefined),
+      content: content.join("\n"),
+      ...(language ? { language } : {}),
+    })
+    if (!closed) break
+  }
+  return immediate ? { files, next: j, open: true } : null
+}
+
 function parseDemoTag(attrs: Record<string, string>): DemoNode {
   const variants = attrs.variants ? parseDemoVariants(attrs.variants) : []
   return {
@@ -189,6 +325,7 @@ function parseDemoTag(attrs: Record<string, string>): DemoNode {
     ...((DEMO_LAYOUTS as string[]).includes(attrs.layout) ? { layout: attrs.layout as DemoLayout } : {}),
     ...(variants.length ? { variants } : {}),
     ...((DEMO_VIEWPORTS as string[]).includes(attrs.viewport) ? { viewport: attrs.viewport as DemoViewport } : {}),
+    ...(attrs.entry ? { entry: attrs.entry } : {}),
   }
 }
 
@@ -201,6 +338,12 @@ export function trimPartialInlineToken(md: string): string {
   return md
     // A block tag still arriving (`{% demo src="butt`) would flash as a paragraph.
     .replace(/(^|\n)[ \t]*\{(?:%(?:(?!%\})[^\n])*)?$/, "$1")
+    // A one-line command still arriving (`{% command %}npm i x{% endcomm`): hold the line back
+    // until it closes. (The multi-line form, `{% command %}` alone on its line, renders as it grows.)
+    .replace(/(^|\n)[ \t]*\{%\s*command\b[^\n]*?%\}[ \t]*\S[^\n]*$/, (line: string, lead: string) =>
+      /\{%\s*endcommand\s*%\}\s*$/.test(line) ? line : lead)
+    // A fence still arriving (a lone ` or ``) would end a demo block and flash as text.
+    .replace(/(^|\n)[ \t]*(?:`{1,2}|~{1,2})$/, "$1")
     .replace(/\[\^[^\]]*$/, "")
     .replace(/(^|[\s([{])[@#][\w.-]*$/, "$1")
     .replace(/\\$/, "")
@@ -229,6 +372,14 @@ export function parseBlocks(lines: string[]): Block[] {
       continue
     }
 
+    const oneLine = line.match(COMMAND_ONE_LINE_RE)
+    if (oneLine) {
+      flushParagraph()
+      blocks.push(commandNode(parseAttrs(oneLine[1]), oneLine[2]))
+      i++
+      continue
+    }
+
     const tag = templateTag(line)
     if (tag) {
       flushParagraph()
@@ -245,7 +396,21 @@ export function parseBlocks(lines: string[]): Block[] {
 
       if (tag.name === "tabs") {
         const { body, next } = collectUntil(lines, i + 1, "tabs")
-        blocks.push({ type: "tabs", tabs: parseTabs(body), ...(tag.attrs.sync ? { sync: tag.attrs.sync } : {}) })
+        const level = Number(tag.attrs.level)
+        blocks.push({
+          type: "tabs",
+          tabs: parseTabs(body),
+          ...(tag.attrs.sync ? { sync: tag.attrs.sync } : {}),
+          ...(tag.attrs.title ? { title: tag.attrs.title } : {}),
+          ...(tag.attrs.title && (level === 3 || level === 4) ? { level: level as 3 | 4 } : {}),
+        })
+        i = next
+        continue
+      }
+
+      if (tag.name === "command") {
+        const { body, next } = collectUntil(lines, i + 1, "command")
+        blocks.push(commandNode(tag.attrs, body.join("\n")))
         i = next
         continue
       }
@@ -328,10 +493,16 @@ export function parseBlocks(lines: string[]): Block[] {
       }
 
       if (tag.name === "demo") {
-        blocks.push(parseDemoTag(tag.attrs))
+        const node = parseDemoTag(tag.attrs)
         i++
-        // tolerate an optional {% enddemo %}
-        if (i < lines.length && templateTag(lines[i])?.name === "enddemo") i++
+        // `{% demo … /%}` never has a body; otherwise look for inline files / {% enddemo %}.
+        const body = demoBody(lines, i, /\/\s*%\}\s*$/.test(line))
+        if (body) {
+          if (body.files.length) node.files = body.files
+          if (body.open) node.open = true
+          i = body.next
+        }
+        blocks.push(node)
         continue
       }