@brett_lamy/docstream 1.1.1 → 1.2.0

package/src/index.ts

@@ -13,25 +13,35 @@ export {
   DemoFullscreen,
   DemoViewer,
   DocstreamDemoContext,
+  DocstreamDemoRuntimeContext,
   createGlobDemoResolver,
   defaultDemoMarkdown,
+  inlineDemoMarkdown,
+  inlineDemoNode,
   demoComponentFrom,
   demoFromSearch,
   demoHref,
+  preloadDemos,
   resolveDemosToMarkdown,
   sortDemoFiles,
+  toInlineFiles,
   useDemoResolver,
+  useDemoRuntime,
 } from "./demo"
 export type {
   DemoComponent,
   DemoComponentProps,
   DemoFile,
   DemoFullscreenProps,
+  DemoMarkdownFormat,
   DemoMeta,
   DemoResolver,
+  DemoRuntimeOptions,
   DemoVariant,
   DemoViewerProps,
   GlobDemoResolverOptions,
+  InlineDemoRuntime,
+  InlineDemoRuntimeProps,
   ResolveDemosOptions,
   ResolvedDemo,
 } from "./demo"
@@ -52,8 +62,12 @@ export { VizEmbed } from "./viz"
 export type { VizEmbedProps } from "./viz"
 export { OpenApiOperation } from "./openapi/OpenApiOperation"
 export {
+  InlineDemoPreview,
   ReactCodePreview,
   ReactDemo,
+  almostNodeDemoRuntime,
+  createAlmostNodeDemoRuntime,
+  createInlineDemoProject,
   createReactDemoFiles,
   createAlmostNodeFilesystem,
   createAlmostNodeWorkspace,
@@ -65,6 +79,10 @@ export type {
   AlmostNodeFilesystemOptions,
   AlmostNodeWorkspace,
   AlmostNodeWorkspaceOptions,
+  AlmostNodeDemoRuntimeOptions,
+  InlineDemoPreviewProps,
+  InlineDemoProject,
+  InlineDemoProjectOptions,
   ReactCodePreviewProps,
   ReactDemoProps,
 } from "./playground"
@@ -79,7 +97,7 @@ export type {
   SourceReferenceClient,
 } from "./source"
 export { parseDemoVariants, parseMarkdown, parseBlocks, trimPartialInlineToken } from "./gitbook/parse"
-export { serializeBlocks, serializeMarkdown } from "./gitbook/serialize"
+export { fenceFor, serializeBlocks, serializeDemoFile, serializeMarkdown } from "./gitbook/serialize"
 export {
   footnoteDefinitions,
   parseInline,
@@ -91,3 +109,7 @@ export {
 export { Streamdown } from "streamdown"
 export type { StreamdownProps } from "streamdown"
 export type * from "./gitbook/ast"
+export { PACKAGE_MANAGERS, packageManagerCommands } from "./gitbook/package-managers"
+export { flattenBlocks, flattenForPlainMarkdown } from "./gitbook/flatten"
+export { documentOutline, slugify } from "./gitbook/outline"
+export type { OutlineEntry } from "./gitbook/outline"

package/src/playground/InlineDemoPreview.tsx

@@ -0,0 +1,77 @@
+/* Runs a `{% demo %}` block's inline files in almost-node — the Preview of a pasted,
+   self-contained demo when no resolver knows it. Just the iframe: the DemoViewer around it
+   supplies the header, variants, viewports, Code view and fullscreen. */
+import { useMemo, type ReactNode } from "react"
+
+import type { DemoFile, InlineDemoRuntime, InlineDemoRuntimeProps } from "../demo/types"
+import { createInlineDemoProject, type AlmostNodeWorkspaceOptions } from "./filesystem"
+import { useAlmostNodeServer } from "./ReactCodePreview"
+
+export interface InlineDemoPreviewProps extends InlineDemoRuntimeProps {
+  /** Preferred virtual port. almost-node picks the next free one if taken. */
+  port?: number
+  /** iframe sandbox value (same-origin lets the almost-node service worker route it). */
+  sandbox?: string
+  /** Extra options for `createAlmostNodeWorkspace` (e.g. `basePath` for static hosting). */
+  workspaceOptions?: Partial<AlmostNodeWorkspaceOptions>
+}
+
+function filesKey(files: DemoFile[], entry: string, dependencies: Record<string, string> | undefined) {
+  return JSON.stringify([entry, dependencies ?? null, files.map((f) => [f.path, f.content])])
+}
+
+export function InlineDemoPreview({
+  title,
+  files,
+  entry,
+  variant,
+  dependencies,
+  port = 4173,
+  sandbox = "allow-scripts allow-same-origin allow-forms allow-modals",
+  workspaceOptions,
+}: InlineDemoPreviewProps) {
+  // Content-keyed so re-renders (variant switches, parent state) never restart Vite.
+  const key = filesKey(files, entry, dependencies)
+  const project = useMemo(
+    () => {
+      try {
+        return { value: createInlineDemoProject(files, { entry, dependencies }) }
+      } catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) }
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key],
+  )
+  const { state, url, error } = useAlmostNodeServer({
+    files: project.value?.files ?? {},
+    port,
+    run: project.value ? 1 : 0,
+    workspaceOptions,
+  })
+
+  const message = project.error ?? error
+  if (message) return <pre className="docs-demo-error" role="alert">{message}</pre>
+  if (state !== "ready" || !url) {
+    return <div className="docs-demo-runtime-status" role="status">Starting almost-node…</div>
+  }
+  const src = project.value?.wrapped && variant !== undefined ? `${url}?variant=${encodeURIComponent(variant)}` : url
+  return <iframe key={src} title={title} className="docs-demo-runtime-frame" src={src} sandbox={sandbox} />
+}
+
+export interface AlmostNodeDemoRuntimeOptions {
+  port?: number
+  sandbox?: string
+  workspaceOptions?: Partial<AlmostNodeWorkspaceOptions>
+}
+
+/**
+ * An `InlineDemoRuntime` backed by almost-node (`@agent-wasm/core`, loaded lazily on first
+ * use). Pass it as `demoRuntime`; `PlaygroundStreamdown` uses one with default options.
+ */
+export function createAlmostNodeDemoRuntime(options: AlmostNodeDemoRuntimeOptions = {}): InlineDemoRuntime {
+  return (props): ReactNode => <InlineDemoPreview {...props} {...options} />
+}
+
+/** The default almost-node runtime (no base path, port 4173+). */
+export const almostNodeDemoRuntime: InlineDemoRuntime = createAlmostNodeDemoRuntime()

package/src/playground/PlaygroundStreamdown.tsx

@@ -1,7 +1,9 @@
-import { useMemo } from "react"
+import { useContext, useMemo } from "react"
 
 import { DocsRenderer, type DocRenderOptions, type LivePreviewRenderer, type SourceReferenceRenderer } from "../docs/DocsRenderer"
 import { parseMarkdown, trimPartialInlineToken } from "../gitbook/parse"
+import { DocstreamDemoRuntimeContext } from "../demo/context"
+import { almostNodeDemoRuntime } from "./InlineDemoPreview"
 import { ReactCodePreview } from "./ReactCodePreview"
 
 export interface PlaygroundStreamdownProps extends DocRenderOptions {
@@ -16,7 +18,8 @@ export interface PlaygroundStreamdownProps extends DocRenderOptions {
 /**
  * The full renderer variant. It keeps the optional almost-node playground
  * behind an explicit import boundary; markdown-only consumers should use the
- * `@brett_lamy/docstream/streamdown` entry instead.
+ * `@brett_lamy/docstream/streamdown` entry instead. Live code fences and
+ * `{% demo %}` blocks with inline files (and no resolver) run in almost-node.
  */
 export function PlaygroundStreamdown({
   children,
@@ -26,9 +29,14 @@ export function PlaygroundStreamdown({
   markdown,
   sourceRenderer,
   demoResolver,
+  demoRuntime,
+  demoDependencies,
   pageActions,
 }: PlaygroundStreamdownProps) {
   const content = markdown ?? children ?? ""
+  // Inline-file demos run in almost-node unless the host (or an outer renderer) chose a runtime.
+  const inheritedRuntime = useContext(DocstreamDemoRuntimeContext).runtime
+  const runtime = demoRuntime ?? inheritedRuntime ?? almostNodeDemoRuntime
   const doc = useMemo(
     () => parseMarkdown(isStreaming ? trimPartialInlineToken(content) : content),
     [content, isStreaming]
@@ -56,6 +64,8 @@ export function PlaygroundStreamdown({
         liveRenderer={liveRenderer}
         sourceRenderer={sourceRenderer}
         demoResolver={demoResolver}
+        demoRuntime={runtime}
+        demoDependencies={demoDependencies}
         pageActions={isStreaming ? false : pageActions}
       />
     </div>

package/src/playground/ReactCodePreview.tsx

@@ -53,7 +53,7 @@ export interface ReactDemoProps {
 
 export type ReactCodePreviewProps = ReactDemoProps
 
-type PreviewState = "idle" | "starting" | "ready" | "error"
+export type PreviewState = "idle" | "starting" | "ready" | "error"
 
 const DETACHED_SERVER_ENV = { ALMOSTNODE_DETACH_DEV_SERVERS: "1" }
 
@@ -79,43 +79,30 @@ function sourceText(files: AlmostNodeFiles, requestedPath: string): string | nul
   return typeof file.content === "string" ? file.content : new TextDecoder().decode(file.content)
 }
 
-/** Render a multi-file React/JSX/TSX project through almost-node's Vite server. */
-const NO_FILES: AlmostNodeFiles = {}
+export interface AlmostNodeServerOptions {
+  /** The complete project (see `createReactDemoFiles`). Keep its identity stable between renders. */
+  files: AlmostNodeFiles
+  port?: number
+  /** Start when > 0; bump to restart. 0 stops (and disposes) the server. */
+  run: number
+  workspaceOptions?: Partial<AlmostNodeWorkspaceOptions>
+  onReady?: (url: string) => void
+  onError?: (error: Error) => void
+}
 
-export function ReactDemo({
-  files = NO_FILES,
-  preview,
-  code: codeProp,
-  language,
-  status,
-  actions,
-  entry = "/src/main.jsx",
-  port = 4173,
-  height = 360,
-  codeFile,
-  collapsedCodeLines = 3,
-  expandedCodeLines = 30,
-  title = "Live React preview",
-  autoStart = true,
-  sandbox = "allow-scripts allow-same-origin allow-forms allow-modals",
-  workspaceOptions,
-  className,
-  onReady,
-  onError,
-}: ReactDemoProps) {
-  const inline = preview !== undefined
-  const [run, setRun] = useState(autoStart && !inline ? 1 : 0)
-  const [state, setState] = useState<PreviewState>(inline ? "ready" : autoStart ? "starting" : "idle")
+export interface AlmostNodeServerState {
+  state: PreviewState
+  url: string | null
+  error: string | null
+}
+
+/** Boots `vite` for `files` in an almost-node container; disposes it on change/unmount. */
+export function useAlmostNodeServer({ files, port = 4173, run, workspaceOptions, onReady, onError }: AlmostNodeServerOptions): AlmostNodeServerState {
+  const [state, setState] = useState<PreviewState>(run ? "starting" : "idle")
   const [url, setUrl] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
-  const displayedCodeFile = codeFile ?? entry
-  const code = useMemo(
-    () => codeProp ?? sourceText(files, displayedCodeFile),
-    [codeProp, displayedCodeFile, files],
-  )
 
   useEffect(() => {
-    if (inline) return
     if (!run) {
       setState("idle")
       setUrl(null)
@@ -132,8 +119,7 @@ export function ReactDemo({
 
     const start = async () => {
       try {
-        const projectFiles = createReactDemoFiles(files, { entry })
-        workspace = await createAlmostNodeWorkspace(projectFiles, {
+        workspace = await createAlmostNodeWorkspace(files, {
           ...workspaceOptions,
           env: { ...DETACHED_SERVER_ENV, ...workspaceOptions?.env },
           onServerReady: (serverPort, serverUrl) => {
@@ -173,7 +159,52 @@ export function ReactDemo({
       cancelled = true
       workspace?.dispose()
     }
-  }, [entry, files, inline, onError, onReady, port, run, workspaceOptions])
+  }, [files, onError, onReady, port, run, workspaceOptions])
+
+  return { state, url, error }
+}
+
+/** Render a multi-file React/JSX/TSX project through almost-node's Vite server. */
+const NO_FILES: AlmostNodeFiles = {}
+
+export function ReactDemo({
+  files = NO_FILES,
+  preview,
+  code: codeProp,
+  language,
+  status,
+  actions,
+  entry = "/src/main.jsx",
+  port = 4173,
+  height = 360,
+  codeFile,
+  collapsedCodeLines = 3,
+  expandedCodeLines = 30,
+  title = "Live React preview",
+  autoStart = true,
+  sandbox = "allow-scripts allow-same-origin allow-forms allow-modals",
+  workspaceOptions,
+  className,
+  onReady,
+  onError,
+}: ReactDemoProps) {
+  const inline = preview !== undefined
+  const [run, setRun] = useState(autoStart && !inline ? 1 : 0)
+  const projectFiles = useMemo(() => createReactDemoFiles(files, { entry }), [files, entry])
+  const { state: serverState, url, error } = useAlmostNodeServer({
+    files: projectFiles,
+    port,
+    run: inline ? 0 : run,
+    workspaceOptions,
+    onReady,
+    onError,
+  })
+  const state: PreviewState = inline ? "ready" : serverState
+  const displayedCodeFile = codeFile ?? entry
+  const code = useMemo(
+    () => codeProp ?? sourceText(files, displayedCodeFile),
+    [codeProp, displayedCodeFile, files],
+  )
 
   const wrapperClass = className ? `docs-react-demo ${className}` : "docs-react-demo"
   const running = state === "starting"

package/src/playground/filesystem.ts

@@ -154,6 +154,8 @@ export async function createAlmostNodeWorkspace(
 
 export interface ReactDemoFilesOptions {
   entry?: string
+  /** Extra npm dependencies for the generated package.json (ignored when the files bring one). */
+  dependencies?: Record<string, string>
 }
 
 /**
@@ -174,7 +176,7 @@ export function createReactDemoFiles(
         name: "docstream-react-demo",
         private: true,
         type: "module",
-        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0" },
+        dependencies: { react: "^19.0.0", "react-dom": "^19.0.0", ...options.dependencies },
       },
       null,
       2,
@@ -200,3 +202,83 @@ export function createReactDemoFiles(
 
   return map
 }
+
+export interface InlineDemoProjectOptions {
+  /** Entry file among `files` (relative path). Defaults to the first file. */
+  entry?: string
+  /** Extra npm dependencies (merged over a `package.json` among the files, if any). */
+  dependencies?: Record<string, string>
+}
+
+export interface InlineDemoProject {
+  /** Complete almost-node project: the demo under `/src/demo/`, a wrapper entry, package.json, index.html. */
+  files: Record<string, AlmostNodeFileContent>
+  /** The Vite entry to hand to `createReactDemoFiles` / `ReactDemo`. */
+  entry: string
+  /** Whether the entry is wrapped (so `?variant=` reaches the component as its `variant` prop). */
+  wrapped: boolean
+}
+
+/** Folder the inline demo's files are written to inside the almost-node project. */
+export const INLINE_DEMO_DIR = "/src/demo"
+const WRAPPER_ENTRY = "/src/__docstream_demo_entry.js"
+
+function selfMounting(source: string): boolean {
+  return /\bcreateRoot\s*\(|\bReactDOM\.render\s*\(|\bhydrateRoot\s*\(/.test(source)
+}
+
+/**
+ * Turn a `{% demo %}` block's inline files into a runnable almost-node project.
+ *
+ * The files go under `/src/demo/` (relative imports between them keep working). A tiny
+ * wrapper entry imports the entry file, takes its default export (or the first exported
+ * function), and renders it with `variant` read from the page's `?variant=` query — so
+ * switching variants just reloads the iframe, no new Vite server. An entry that mounts
+ * itself (`createRoot(…)`) is used directly instead, and receives no `variant`.
+ *
+ * A `package.json` among the files contributes its `dependencies`; `options.dependencies`
+ * are merged over them. Bare imports resolve through almost-node (installed packages, else
+ * esm.sh at the major version declared here), with `react`/`react-dom` provided.
+ */
+export function createInlineDemoProject(
+  files: readonly { path: string; content: string }[],
+  options: InlineDemoProjectOptions = {},
+): InlineDemoProject {
+  const map: Record<string, AlmostNodeFileContent> = {}
+  let packageDeps: Record<string, string> = {}
+  for (const file of files) {
+    const relative = file.path.replace(/^\.?\/+/, "")
+    if (relative === "package.json") {
+      try {
+        const pkg = JSON.parse(file.content) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        packageDeps = { ...pkg.devDependencies, ...pkg.dependencies }
+      } catch {
+        // Not JSON: keep it as a plain file.
+      }
+    }
+    map[normalizeAlmostNodePath(relative, INLINE_DEMO_DIR)] = file.content
+  }
+  const entryFile = files.find((f) => f.path === options.entry) ?? files[0]
+  if (!entryFile) throw new Error("An inline demo needs at least one file")
+  const entryPath = normalizeAlmostNodePath(entryFile.path.replace(/^\.?\/+/, ""), INLINE_DEMO_DIR)
+  const dependencies = { ...packageDeps, ...options.dependencies }
+  const wrapped = !selfMounting(entryFile.content)
+  if (wrapped) {
+    const specifier = `.${entryPath.slice("/src".length)}`
+    map[WRAPPER_ENTRY] = `import { createElement } from "react"
+import { createRoot } from "react-dom/client"
+import * as demo from ${JSON.stringify(specifier)}
+
+const Component = demo.default ?? Object.values(demo).find((value) => typeof value === "function")
+const variant = new URLSearchParams(location.search).get("variant")
+const props = variant === null ? {} : { variant }
+createRoot(document.getElementById("root")).render(
+  Component
+    ? createElement(Component, props)
+    : createElement("pre", null, ${JSON.stringify(`${entryFile.path} has no default export to render.`)}),
+)
+`
+  }
+  const entry = wrapped ? WRAPPER_ENTRY : entryPath
+  return { files: createReactDemoFiles(map, { entry, dependencies }), entry, wrapped }
+}

package/src/playground/index.ts

@@ -1,8 +1,11 @@
-export { ReactCodePreview, ReactDemo } from "./ReactCodePreview"
-export type { ReactCodePreviewProps, ReactDemoProps } from "./ReactCodePreview"
+export { ReactCodePreview, ReactDemo, useAlmostNodeServer } from "./ReactCodePreview"
+export type { AlmostNodeServerOptions, AlmostNodeServerState, PreviewState, ReactCodePreviewProps, ReactDemoProps } from "./ReactCodePreview"
+export { InlineDemoPreview, almostNodeDemoRuntime, createAlmostNodeDemoRuntime } from "./InlineDemoPreview"
+export type { AlmostNodeDemoRuntimeOptions, InlineDemoPreviewProps } from "./InlineDemoPreview"
 export {
   createAlmostNodeFilesystem,
   createAlmostNodeWorkspace,
+  createInlineDemoProject,
   createReactDemoFiles,
   normalizeAlmostNodeFiles,
   normalizeAlmostNodePath,
@@ -15,5 +18,7 @@ export type {
   AlmostNodeFilesystemOptions,
   AlmostNodeWorkspace,
   AlmostNodeWorkspaceOptions,
+  InlineDemoProject,
+  InlineDemoProjectOptions,
   ReactDemoFilesOptions,
 } from "./filesystem"

package/src/streamdown.tsx

@@ -8,8 +8,8 @@ export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/re
 export { DocPageActions } from "./docs/PageActions"
 export type { DocPageAction, DocPageActionsOptions, DocPageActionsProps } from "./docs/PageActions"
 export type { DocRenderOptions } from "./docs/DocsRenderer"
-export { DocstreamDemoContext, DemoFullscreen, DemoViewer } from "./demo"
-export type { DemoFile, DemoMeta, DemoResolver, DemoVariant } from "./demo"
+export { DocstreamDemoContext, DocstreamDemoRuntimeContext, DemoFullscreen, DemoViewer } from "./demo"
+export type { DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime, InlineDemoRuntimeProps } from "./demo"
 export type { CitationPreview, CitationPreviewResolver, DocstreamRefContextValue } from "./docs/reference"
 
 export interface GitbookStreamdownProps extends DocRenderOptions {
@@ -31,6 +31,8 @@ export function GitbookStreamdown({
   liveRenderer,
   sourceRenderer,
   demoResolver,
+  demoRuntime,
+  demoDependencies,
   pageActions,
 }: GitbookStreamdownProps) {
   const content = markdown ?? children ?? ""
@@ -52,6 +54,8 @@ export function GitbookStreamdown({
         liveRenderer={liveRenderer}
         sourceRenderer={sourceRenderer}
         demoResolver={demoResolver}
+        demoRuntime={demoRuntime}
+        demoDependencies={demoDependencies}
         pageActions={isStreaming ? false : pageActions}
       />
     </div>

package/src/styles.css

@@ -24,6 +24,10 @@
   --gb-pill-shadow: 0 1px 2px rgba(15, 15, 35, 0.14), 0 0 0 0.5px rgba(15, 15, 35, 0.1);
   --gb-hover: rgba(128, 128, 128, 0.12);
   --gb-menu-shadow: 0 14px 34px -10px rgba(15, 15, 35, 0.28), 0 2px 6px rgba(15, 15, 35, 0.08);
+  /* The terminal glyph in command boxes. Its own tokens (not --gb-panel-foreground), so a host
+     that sets panel colors to currentColor still gets a visible glyph. */
+  --gb-term-bg: rgba(128, 128, 128, 0.2);
+  --gb-term-fg: var(--gb-muted-foreground);
 
   /* Semantic hint palette — solid color plus precomputed tints. Matches the
      editor palette in @brett_lamy/docstream-editor/styles.css. */
@@ -148,6 +152,10 @@
   margin-block: 0.75em;
 }
 
+:is([data-docstream], .docs-article) [data-docstream-blocks] > .docs-tabs-section {
+  margin-block: 1.6em 0.9em;
+}
+
 :is([data-docstream], .docs-article) a {
   color: var(--gb-primary);
   text-decoration: underline;
@@ -1370,13 +1378,14 @@
   margin: -3px 0;
 }
 
+/* Untitled code blocks: no header bar, just the code and a copy button in its top-right corner. */
 .docs-code-copy-float {
   position: absolute;
-  top: 7px;
-  right: 7px;
+  top: 9px;
+  right: 9px;
   z-index: 1;
-  background: var(--gb-panel);
-  opacity: 0;
+  background: transparent;
+  opacity: 0.75;
 }
 
 .docs-code:hover .docs-code-copy-float,
@@ -1506,9 +1515,45 @@
   width: 20px;
   height: 20px;
   border-radius: 5px;
-  background: var(--gb-panel-foreground);
-  color: var(--gb-panel);
-  opacity: 0.85;
+  background: var(--gb-term-bg, rgba(128, 128, 128, 0.2));
+  color: var(--gb-term-fg, #71717a);
+}
+
+/* ---- Titled tabs (`{% tabs title="Installation" %}`): heading + pill switch, then the tab ---- */
+
+.docs-tabs-section-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 12px;
+}
+
+:is([data-docstream], .docs-article) .docs-tabs-section-head .docs-tabs-section-title {
+  margin: 0;
+  padding-bottom: 0;
+  border-bottom: 0;
+  scroll-margin-top: 80px;
+}
+
+.docs-tabs-section-body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.docs-tabs-section-body > [data-docstream-blocks] > * {
+  margin-block: 0 10px;
+}
+
+.docs-tabs-section-body > [data-docstream-blocks] > :last-child {
+  margin-bottom: 0;
+}
+
+.docs-tabs-section-body > [data-docstream-blocks] > p {
+  color: var(--gb-muted-foreground);
+  font-size: 0.93em;
 }
 
 .docs-tabs-code-title {
@@ -1900,9 +1945,12 @@
   opacity: 1;
 }
 
+/* Block-level demo roots fill the width (place-items: center would shrink them to their
+   content); content is centred vertically, and intrinsically sized roots horizontally. */
 .docs-demo-canvas {
   display: grid;
-  place-items: center;
+  align-content: center;
+  justify-items: stretch;
   box-sizing: border-box;
   min-height: 100%;
   padding: 28px 24px;
@@ -1910,9 +1958,14 @@
 }
 
 .docs-demo-canvas > * {
+  min-width: 0;
   max-width: 100%;
 }
 
+.docs-demo-canvas > :where(button, a, img, svg, video, canvas, input, select, textarea, label, span, code) {
+  justify-self: center;
+}
+
 .docs-demo-canvas-bleed {
   display: block;
   place-items: normal;
@@ -1924,6 +1977,45 @@
   max-width: none;
 }
 
+/* Inline-file demos: the runtime's iframe fills the frame. */
+.docs-demo-canvas-runtime {
+  display: flex;
+  flex-direction: column;
+}
+
+.docs-demo-canvas-runtime > * {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.docs-demo-runtime-frame {
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 120px;
+  border: 0;
+  background: #fff;
+}
+
+.docs-demo-runtime-status {
+  display: grid;
+  place-items: center;
+  height: 100%;
+  min-height: 120px;
+  color: var(--gb-muted-foreground);
+  font-size: 12.5px;
+}
+
+/* No runtime for an inline-file demo (or still streaming): a one-line note, then the code. */
+.docs-demo-note {
+  margin: 0;
+  padding: 8px 14px;
+  border-bottom: 1px solid var(--gb-border);
+  color: var(--gb-muted-foreground);
+  font-size: 12.5px;
+  line-height: 1.5;
+}
+
 .docs-demo-loading {
   display: grid;
   place-items: center;
@@ -2150,10 +2242,27 @@
 }
 
 .docs-demo-single-preview {
+  display: grid;
   min-height: 120px;
   background: var(--background, var(--gb-panel));
 }
 
+.docs-demo-status {
+  flex-shrink: 0;
+  padding: 3px 8px;
+  border-radius: 999px;
+  background: var(--gb-pill-track);
+  color: var(--gb-muted-foreground);
+  font-size: 11.5px;
+  font-weight: 600;
+  line-height: 1.2;
+  white-space: nowrap;
+}
+
+.docs-demo-variants-sized .docs-pill {
+  flex: 1 1 0;
+}
+
 /* Fullscreen overlay + deep link */
 
 .docs-demo-dialog {