@brett_lamy/docstream 1.1.0 → 1.2.0

package/src/demo/DemoViewer.tsx

@@ -1,5 +1,12 @@
 /* The demo viewer for `{% demo src="<page>/<example>" %}`.
 
+   Where the files come from:
+   - a host `DemoResolver` that knows `src`: the component renders in-page; the Code view shows
+     the resolver's files (they win over any inline copy);
+   - otherwise the block's inline files (`{% demo %}` + fences + `{% enddemo %}`): the Preview
+     runs them through the `InlineDemoRuntime` in context (almost-node in the playground entry),
+     or, without one, the viewer opens on the Code view with a short note — never an empty box.
+
    Multi-file demos get the gallery viewer: a header (title, description, Preview | Code, variants,
    viewport widths, copy, fullscreen), a resizable preview frame on a dotted stage, and a Code view
    with a file tree and highlighted source. Single-file demos keep the ReactDemo card: the preview,
@@ -28,10 +35,10 @@ import { CollapsibleCode } from "../docs/CollapsibleCode"
 import { HighlightedCode } from "../docs/HighlightedCode"
 import { CopyButton } from "../docs/copy"
 import { PillTabs, Segmented, rovingKeyDown } from "../docs/controls"
-import { useDemoResolver } from "./context"
+import { useDemoResolver, useDemoRuntime } from "./context"
 import { languageForPath } from "./glob"
-import { defaultDemoMarkdown } from "./markdown"
-import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant } from "./types"
+import { inlineDemoMarkdown } from "./markdown"
+import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types"
 
 export interface DemoViewerProps {
   /** `<page>/<example>` id handed to the resolver. */
@@ -46,6 +53,19 @@ export interface DemoViewerProps {
   variants?: DemoVariant[]
   /** Initial viewport of the multi-file preview. */
   viewport?: DemoViewport
+  /**
+   * Files carried inline by the block (entry first unless `entry` says otherwise). Used when
+   * no resolver knows `src`, or the resolver fails for it.
+   */
+  files?: DemoFile[]
+  /** Entry among `files`. Defaults to the first file. */
+  entry?: string
+  /** The block is still streaming in: show its code, but don't run it yet. */
+  streaming?: boolean
+  /** Runs inline files in the Preview. Defaults to the runtime in context (`demoRuntime`). */
+  runtime?: InlineDemoRuntime
+  /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
+  dependencies?: Record<string, string>
   className?: string
 }
 
@@ -60,6 +80,29 @@ function cacheFor(resolver: DemoResolver) {
   return cache
 }
 
+/**
+ * Resolve demos ahead of rendering (meta, files and component), so the first render — including
+ * server rendering and static export — shows them resolved instead of loading. Failures are
+ * remembered too, so inline-file fallbacks apply immediately.
+ */
+export async function preloadDemos(resolver: DemoResolver, srcs: string[]): Promise<void> {
+  const cache = cacheFor(resolver)
+  const settle = async (key: string, run: () => Promise<unknown>) => {
+    try {
+      cache.set(key, { status: "ready", value: await run() })
+    } catch (cause) {
+      cache.set(key, { status: "error", error: cause instanceof Error ? cause : new Error(String(cause)) })
+    }
+  }
+  await Promise.all(
+    srcs.flatMap((src) => [
+      settle(`meta:${src}`, () => resolver.meta(src)),
+      settle(`files:${src}`, () => resolver.files(src)),
+      settle(`load:${src}`, () => resolver.load(src)),
+    ]),
+  )
+}
+
 /** Resolves `run()` once `active`, remembering settled values so remounts don't flash. */
 function useResolved<T>(resolver: DemoResolver | undefined, key: string, active: boolean, run: () => Promise<T>): Loaded<T> {
   const cached = resolver ? (cacheFor(resolver).get(key) as Loaded<T> | undefined) : undefined
@@ -174,15 +217,50 @@ function cssLength(value: number | string | undefined, fallback: string): string
   return /^\d+(?:\.\d+)?$/.test(value.trim()) ? `${value.trim()}px` : value
 }
 
-/** The rendered component on its canvas. */
-function DemoCanvas({ src, component, variant, bleed }: {
+/** What fills the preview: a resolved component, an inline-demo runtime, or a note. */
+type PreviewSource =
+  | { kind: "component"; component: Loaded<DemoComponent> }
+  | { kind: "runtime"; render: (variant: string | undefined) => ReactNode }
+  | { kind: "streaming" }
+  | { kind: "unavailable" }
+
+export const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead."
+
+/** The rendered demo on its canvas. */
+/** The canvas's class and inline style from `meta.className` / `meta.surface`. */
+interface CanvasLook {
+  className?: string
+  surface?: Record<string, string | number>
+}
+
+function DemoCanvas({ src, preview, variant, bleed, look }: {
   src: string
-  component: Loaded<DemoComponent>
+  preview: PreviewSource
   variant: string | undefined
   bleed?: boolean
+  look?: CanvasLook
 }) {
+  if (preview.kind === "unavailable" || preview.kind === "streaming") {
+    return (
+      <div className="docs-demo-note" role="note" data-variant={variant}>
+        {preview.kind === "streaming" ? "The demo is still arriving; its preview starts once the block is complete." : NO_RUNTIME_NOTE}
+      </div>
+    )
+  }
+  if (preview.kind === "runtime") {
+    return (
+      <div className="docs-demo-canvas docs-demo-canvas-bleed docs-demo-canvas-runtime" data-variant={variant}>
+        <DemoErrorBoundary src={src || "demo"}>{preview.render(variant)}</DemoErrorBoundary>
+      </div>
+    )
+  }
+  const { component } = preview
   return (
-    <div className={bleed ? "docs-demo-canvas docs-demo-canvas-bleed" : "docs-demo-canvas"} data-variant={variant}>
+    <div
+      className={["docs-demo-canvas", bleed ? "docs-demo-canvas-bleed" : "", look?.className ?? ""].filter(Boolean).join(" ")}
+      style={look?.surface as CSSProperties | undefined}
+      data-variant={variant}
+    >
       {component.status === "ready" ? (
         <DemoErrorBoundary src={src}>
           {createElement(component.value, variant === undefined ? {} : { variant })}
@@ -371,7 +449,7 @@ function CodeView({ src, files, height, id }: { src: string; files: DemoFile[];
       </div>
       <div className="docs-demo-source" role="tabpanel" id={panelId} aria-labelledby={file ? tabId(file.path) : undefined}>
         <div className="docs-demo-source-h">
-          <span className="docs-demo-source-path">{src}/{file?.path}</span>
+          <span className="docs-demo-source-path">{src && file ? `${src}/${file.path}` : file?.path}</span>
           {file ? <CopyButton text={file.content} label={`Copy ${file.path}`} /> : null}
         </div>
         <div className="docs-demo-source-body" tabIndex={0} aria-label={file ? `${file.path} source` : undefined}>
@@ -405,18 +483,32 @@ function NewTabLink({ href, title }: { href: string | undefined; title: string }
   )
 }
 
-function VariantSwitch({ variants, value, onChange, title }: {
+function VariantSwitch({ variants, value, onChange, title, width }: {
   variants: DemoVariant[] | undefined
   value: string | undefined
   onChange: (id: string) => void
   title: string
+  width?: number | string
 }) {
   if (!variants?.length || value === undefined) return null
-  return <Segmented options={variants} value={value} onChange={onChange} label={`${title} variant`} className="docs-demo-variants" />
+  return (
+    <Segmented
+      options={variants}
+      value={value}
+      onChange={onChange}
+      label={`${title} variant`}
+      className={width === undefined ? "docs-demo-variants" : "docs-demo-variants docs-demo-variants-sized"}
+      style={width === undefined ? undefined : { width: typeof width === "number" ? `${width}px` : width }}
+    />
+  )
+}
+
+function StatusBadge({ status }: { status: string | undefined }) {
+  return status ? <span className="docs-demo-status">{status}</span> : null
 }
 
 /** A full-viewport overlay (native modal dialog: top layer, focus trap, Esc to close). */
-function FullscreenDialog({ open, onClose, title, src, variants, variant, onVariant, component, bleed, href }: {
+function FullscreenDialog({ open, onClose, title, src, variants, variant, onVariant, preview, bleed, look, variantsWidth, href }: {
   open: boolean
   onClose: () => void
   title: string
@@ -424,8 +516,10 @@ function FullscreenDialog({ open, onClose, title, src, variants, variant, onVari
   variants: DemoVariant[] | undefined
   variant: string | undefined
   onVariant: (id: string) => void
-  component: Loaded<DemoComponent>
+  preview: PreviewSource
   bleed?: boolean
+  look?: CanvasLook
+  variantsWidth?: number | string
   href?: string
 }) {
   const ref = useRef<HTMLDialogElement | null>(null)
@@ -448,14 +542,14 @@ function FullscreenDialog({ open, onClose, title, src, variants, variant, onVari
             <span id={titleId} className="docs-demo-title">{title}</span>
             <span className="docs-demo-dialog-src">{src}</span>
             <span className="docs-demo-spacer" />
-            <VariantSwitch variants={variants} value={variant} onChange={onVariant} title={title} />
+            <VariantSwitch variants={variants} value={variant} onChange={onVariant} title={title} width={variantsWidth} />
             <NewTabLink href={href} title={title} />
             <button type="button" className="docs-demo-icon-btn" onClick={onClose} aria-label="Close fullscreen" title="Close (Esc)" autoFocus>
               <X width={16} height={16} aria-hidden="true" />
             </button>
           </div>
           <div className="docs-demo-dialog-stage">
-            <DemoCanvas src={src} component={component} variant={variant} bleed={bleed} />
+            <DemoCanvas src={src} preview={preview} variant={variant} bleed={bleed} look={look} />
           </div>
         </div>
       ) : null}
@@ -467,16 +561,34 @@ function FullscreenDialog({ open, onClose, title, src, variants, variant, onVari
 
 type ViewTab = "preview" | "code"
 
+/** Inline files, entry first. */
+function orderInline(files: DemoFile[] | undefined, entry: string | undefined): DemoFile[] | undefined {
+  if (!files?.length) return undefined
+  const index = entry ? files.findIndex((f) => f.path === entry) : -1
+  return index > 0 ? [files[index], ...files.slice(0, index), ...files.slice(index + 1)] : files
+}
+
 export function DemoViewer(props: DemoViewerProps) {
   const resolver = useDemoResolver(props.resolver)
+  const runtimeOptions = useDemoRuntime({ runtime: props.runtime, dependencies: props.dependencies })
   const { src } = props
   const [ref, near] = useNearViewport<HTMLElement>()
-  const meta = useMeta(resolver, src)
-  const files = useFiles(resolver, src, near)
-  const component = useComponent(resolver, src, near)
-  const metaValue = meta.status === "ready" ? meta.value : undefined
-
-  const title = props.title ?? metaValue?.title ?? src.split("/").pop() ?? src
+  const inlineFiles = useMemo(() => orderInline(props.files, props.entry), [props.files, props.entry])
+
+  // A resolver is consulted unless the block brings its own files and the resolver
+  // says (via `list()`) that it does not know this src.
+  const tryResolver = !!resolver && !(inlineFiles && (!src || (resolver.list ? !resolver.list().includes(src) : false)))
+  const hookResolver = tryResolver ? resolver : undefined
+  const meta = useMeta(hookResolver, src)
+  const resolvedFiles = useFiles(hookResolver, src, near)
+  const component = useComponent(hookResolver, src, near)
+  const resolverFailed = meta.status === "error" || resolvedFiles.status === "error" || component.status === "error"
+  const mode: "resolver" | "inline" | "none" =
+    tryResolver && !(inlineFiles && resolverFailed) ? "resolver" : inlineFiles ? "inline" : "none"
+
+  const metaValue = mode === "resolver" && meta.status === "ready" ? meta.value : undefined
+  const files: Loaded<DemoFile[]> = mode === "inline" ? { status: "ready", value: inlineFiles! } : resolvedFiles
+  const title = props.title ?? metaValue?.title ?? (src.split("/").pop() || "Demo")
   const description = props.description ?? metaValue?.description
   const variants = props.variants?.length ? props.variants : metaValue?.variants
   const [chosenVariant, setVariant] = useState<string | undefined>(undefined)
@@ -489,11 +601,24 @@ export function DemoViewer(props: DemoViewerProps) {
     layoutPref !== "auto" ? layoutPref : fileList ? (fileList.length > 1 ? "multi" : "single") : null
   const heightValue = props.height ?? metaValue?.height
   const bleed = metaValue?.bleed
+  const look: CanvasLook | undefined = metaValue
+  const variantsWidth = metaValue?.variantsWidth
+  const status = metaValue?.status
   const [fullscreen, setFullscreen] = useState(false)
-  const href = resolver?.href?.(src, variant ? { variant } : undefined)
+  const href = mode === "resolver" ? resolver?.href?.(src, variant ? { variant } : undefined) : undefined
   const baseId = useId()
 
-  if (!resolver) {
+  const { runtime, dependencies } = runtimeOptions
+  const preview: PreviewSource = useMemo(() => {
+    if (mode !== "inline") return { kind: "component", component }
+    if (props.streaming) return { kind: "streaming" }
+    if (!runtime || !inlineFiles) return { kind: "unavailable" }
+    const entry = inlineFiles[0].path
+    return { kind: "runtime", render: (v) => runtime({ src, title, files: inlineFiles, entry, variant: v, dependencies }) }
+  }, [mode, component, props.streaming, runtime, inlineFiles, src, title, dependencies])
+  const runnable = preview.kind !== "unavailable"
+
+  if (mode === "none") {
     return (
       <div className="docs-source-ref" data-docstream-demo="" data-demo-src={src}>
         <FileCode2 width={16} height={16} aria-hidden="true" />
@@ -503,6 +628,18 @@ export function DemoViewer(props: DemoViewerProps) {
     )
   }
 
+  const node: DemoNode = {
+    type: "demo",
+    src,
+    ...(props.title ? { title: props.title } : {}),
+    ...(props.description ? { description: props.description } : {}),
+    ...(props.height !== undefined ? { height: String(props.height) } : {}),
+    ...(props.layout ? { layout: props.layout } : {}),
+    ...(props.variants?.length ? { variants: props.variants } : {}),
+    ...(props.viewport ? { viewport: props.viewport } : {}),
+  }
+  const copyDemo = () => inlineDemoMarkdown(node, fileList ?? [], metaValue)
+
   const dialog = (
     <FullscreenDialog
       open={fullscreen}
@@ -512,8 +649,10 @@ export function DemoViewer(props: DemoViewerProps) {
       variants={variants}
       variant={variant}
       onVariant={setVariant}
-      component={component}
+      preview={preview}
       bleed={bleed}
+      look={look}
+      variantsWidth={variantsWidth}
       href={href}
     />
   )
@@ -522,7 +661,7 @@ export function DemoViewer(props: DemoViewerProps) {
   if (layout === "single") {
     const file = fileList?.[0]
     return (
-      <section ref={ref} className={wrapper("single")} data-docstream-demo="" data-demo-src={src} aria-labelledby={`${baseId}-title`}>
+      <section ref={ref} className={wrapper("single")} data-docstream-demo="" data-demo-src={src} data-demo-mode={mode} aria-labelledby={`${baseId}-title`}>
         <div className="docs-react-demo">
           <header className="docs-react-demo-header docs-demo-single-head">
             <span className="docs-demo-heading">
@@ -530,17 +669,27 @@ export function DemoViewer(props: DemoViewerProps) {
               {description ? <span className="docs-demo-desc"><InlineMarkdown text={description} /></span> : null}
             </span>
             <span className="docs-demo-spacer" />
-            <VariantSwitch variants={variants} value={variant} onChange={setVariant} title={title} />
-            <FullscreenButton onOpen={() => setFullscreen(true)} title={title} />
+            <StatusBadge status={status} />
+            <VariantSwitch variants={variants} value={variant} onChange={setVariant} title={title} width={variantsWidth} />
+            {runnable ? <FullscreenButton onOpen={() => setFullscreen(true)} title={title} /> : null}
           </header>
-          <div className="docs-react-demo-preview docs-demo-single-preview" style={{ height: cssLength(heightValue, "auto") }}>
-            {near ? <DemoCanvas src={src} component={component} variant={variant} bleed={bleed} /> : <Spinner />}
-          </div>
+          {runnable ? (
+            <div
+              className="docs-react-demo-preview docs-demo-single-preview"
+              // A hint, not a cap: in-page components may grow past it. An iframe needs a real height.
+              style={preview.kind === "runtime" ? { height: cssLength(heightValue, "360px") } : { minHeight: cssLength(heightValue, "120px") }}
+            >
+              {near ? <DemoCanvas src={src} preview={preview} variant={variant} bleed={bleed} look={look} /> : <Spinner />}
+            </div>
+          ) : (
+            <DemoCanvas src={src} preview={preview} variant={variant} />
+          )}
           {file ? (
             <CollapsibleCode
               code={file.content.replace(/\n+$/, "")}
               language={file.language ?? languageForPath(file.path) ?? null}
               copyLabel={`Copy ${file.path}`}
+              {...(runnable ? {} : { collapsedLines: 12 })}
             />
           ) : null}
         </div>
@@ -554,6 +703,7 @@ export function DemoViewer(props: DemoViewerProps) {
       rootRef={ref}
       className={wrapper(layout ?? "pending")}
       baseId={baseId}
+      mode={mode}
       src={src}
       title={title}
       description={description}
@@ -561,22 +711,27 @@ export function DemoViewer(props: DemoViewerProps) {
       variant={variant}
       onVariant={setVariant}
       files={files}
-      component={component}
+      preview={preview}
       near={near}
       height={cssLength(heightValue, "480px")}
       viewport={props.viewport}
       bleed={bleed}
+      look={look}
+      status={status}
+      variantsWidth={variantsWidth}
       href={href}
       onFullscreen={() => setFullscreen(true)}
+      copyDemo={fileList?.length ? copyDemo : undefined}
       dialog={dialog}
     />
   )
 }
 
-function MultiFileViewer({ rootRef, className, baseId, src, title, description, variants, variant, onVariant, files, component, near, height, viewport, bleed, href, onFullscreen, dialog }: {
+function MultiFileViewer({ rootRef, className, baseId, mode, src, title, description, variants, variant, onVariant, files, preview, near, height, viewport, bleed, look, status, variantsWidth, href, onFullscreen, copyDemo, dialog }: {
   rootRef: MutableRefObject<HTMLElement | null>
   className: string
   baseId: string
+  mode: "resolver" | "inline"
   src: string
   title: string
   description: string | undefined
@@ -584,28 +739,31 @@ function MultiFileViewer({ rootRef, className, baseId, src, title, description,
   variant: string | undefined
   onVariant: (id: string) => void
   files: Loaded<DemoFile[]>
-  component: Loaded<DemoComponent>
+  preview: PreviewSource
   near: boolean
   height: string
   viewport: DemoViewport | undefined
   bleed: boolean | undefined
+  look: CanvasLook | undefined
+  status: string | undefined
+  variantsWidth: number | string | undefined
   href: string | undefined
   onFullscreen: () => void
+  copyDemo: (() => string) | undefined
   dialog: ReactNode
 }) {
-  const [tab, setTab] = useState<ViewTab>("preview")
+  const runnable = preview.kind !== "unavailable"
+  // Nothing to preview without a runtime: open on the code rather than an empty frame.
+  const [tab, setTab] = useState<ViewTab>(runnable ? "preview" : "code")
   const [width, setWidth] = useState<number | null>(() => VIEWPORTS.find((v) => v.id === viewport)?.width ?? null)
   const [codeSeen, setCodeSeen] = useState(false)
   useEffect(() => {
     if (tab === "code") setCodeSeen(true)
   }, [tab])
   const activeViewport = width === null ? "desktop" : VIEWPORTS.find((v) => v.width === width)?.id
-  const fileList = files.status === "ready" ? files.value : null
-  const allFiles = () =>
-    defaultDemoMarkdown({ node: { type: "demo", src } as DemoNode, meta: undefined, files: fileList ?? [], title })
 
   return (
-    <section ref={rootRef} className={className} data-docstream-demo="" data-demo-src={src} aria-labelledby={`${baseId}-title`}>
+    <section ref={rootRef} className={className} data-docstream-demo="" data-demo-src={src} data-demo-mode={mode} aria-labelledby={`${baseId}-title`}>
       <div className="docs-demo-head">
         <div className="docs-demo-heading">
           <div id={`${baseId}-title`} className="docs-demo-title">{title}</div>
@@ -620,8 +778,9 @@ function MultiFileViewer({ rootRef, className, baseId, src, title, description,
             tabId={(id) => `${baseId}-tab-${id}`}
             panelId={(id) => `${baseId}-panel-${id}`}
           />
-          <VariantSwitch variants={variants} value={variant} onChange={onVariant} title={title} />
-          {tab === "preview" ? (
+          <StatusBadge status={status} />
+          <VariantSwitch variants={variants} value={variant} onChange={onVariant} title={title} width={variantsWidth} />
+          {tab === "preview" && runnable ? (
             <div className="docs-demo-viewports" role="group" aria-label="Preview width">
               {VIEWPORTS.map(({ id, label, width: w, Icon }) => (
                 <button
@@ -638,18 +797,23 @@ function MultiFileViewer({ rootRef, className, baseId, src, title, description,
               ))}
             </div>
           ) : null}
-          {fileList?.length ? <CopyButton text={allFiles} label="Copy all files as Markdown" className="docs-demo-icon-btn" /> : null}
-          <FullscreenButton onOpen={onFullscreen} title={title} />
+          {copyDemo ? <CopyButton text={copyDemo} label="Copy demo as Markdown" className="docs-demo-icon-btn" /> : null}
+          {runnable ? <FullscreenButton onOpen={onFullscreen} title={title} /> : null}
           <NewTabLink href={href} title={title} />
         </div>
       </div>
       <div className="docs-demo-body">
         <div id={`${baseId}-panel-preview`} role="tabpanel" aria-labelledby={`${baseId}-tab-preview`} hidden={tab !== "preview"}>
-          <PreviewStage width={width} onResize={setWidth} height={height}>
-            {near ? <DemoCanvas src={src} component={component} variant={variant} bleed={bleed} /> : <Spinner />}
-          </PreviewStage>
+          {runnable ? (
+            <PreviewStage width={width} onResize={setWidth} height={height}>
+              {near ? <DemoCanvas src={src} preview={preview} variant={variant} bleed={bleed} look={look} /> : <Spinner />}
+            </PreviewStage>
+          ) : (
+            <DemoCanvas src={src} preview={preview} variant={variant} />
+          )}
         </div>
         <div id={`${baseId}-panel-code`} role="tabpanel" aria-labelledby={`${baseId}-tab-code`} hidden={tab !== "code"}>
+          {!runnable && tab === "code" ? <DemoCanvas src={src} preview={preview} variant={variant} /> : null}
           {codeSeen || tab === "code" ? (
             files.status === "ready" ? (
               <CodeView src={src} files={files.value} height={height} id={baseId} />
@@ -666,7 +830,7 @@ function MultiFileViewer({ rootRef, className, baseId, src, title, description,
   )
 }
 
-/** Renders a parsed `{% demo %}` block with the resolver from context. */
+/** Renders a parsed `{% demo %}` block with the resolver and runtime from context. */
 export function DemoBlock({ node }: { node: DemoNode }) {
   return (
     <DemoViewer
@@ -677,6 +841,9 @@ export function DemoBlock({ node }: { node: DemoNode }) {
       layout={node.layout}
       variants={node.variants}
       viewport={node.viewport}
+      files={node.files}
+      entry={node.entry}
+      streaming={node.open}
     />
   )
 }
@@ -699,7 +866,7 @@ export function DemoFullscreen({ src, resolver: override, variant, className, st
   if (!resolver) return <DemoError message={`No demo resolver for ${src}`} />
   return (
     <div className={className ? `docs-demo-fullscreen ${className}` : "docs-demo-fullscreen"} style={style} data-demo-src={src}>
-      <DemoCanvas src={src} component={component} variant={chosen} bleed={metaValue?.bleed} />
+      <DemoCanvas src={src} preview={{ kind: "component", component }} variant={chosen} bleed={metaValue?.bleed} look={metaValue} />
     </div>
   )
 }

package/src/demo/context.ts

@@ -1,5 +1,5 @@
 import { createContext, useContext } from "react"
-import type { DemoResolver } from "./types"
+import type { DemoResolver, DemoRuntimeOptions } from "./types"
 
 /**
  * The host's demo resolver. Renderers given a `demoResolver` prop provide it, so
@@ -11,3 +11,19 @@ export function useDemoResolver(override?: DemoResolver): DemoResolver | undefin
   const inherited = useContext(DocstreamDemoContext)
   return override ?? inherited
 }
+
+/**
+ * How inline-file demos without a resolver run their Preview (`demoRuntime`) and which
+ * extra npm packages they may import (`demoDependencies`). Provided by the renderers.
+ */
+export const DocstreamDemoRuntimeContext = createContext<DemoRuntimeOptions>({})
+
+export function useDemoRuntime(override?: DemoRuntimeOptions): DemoRuntimeOptions {
+  const inherited = useContext(DocstreamDemoRuntimeContext)
+  return {
+    runtime: override?.runtime ?? inherited.runtime,
+    dependencies: override?.dependencies || inherited.dependencies
+      ? { ...inherited.dependencies, ...override?.dependencies }
+      : undefined,
+  }
+}

package/src/demo/glob.ts

@@ -12,13 +12,15 @@ export interface GlobDemoResolverOptions {
   /**
    * Raw file contents, e.g.
    * `import.meta.glob("./examples/**\/*.{ts,tsx,css,json}", { query: "?raw", import: "default" })`.
+   * Values are file text (or loaders of it); no `<string>` generic is needed. A module
+   * object with a string `default` (a `?raw` glob without `import: "default"`) also works.
    */
-  sources: Record<string, MaybeLazy<string>>
+  sources: Record<string, MaybeLazy<unknown>>
   /**
    * Folder metadata, e.g.
    * `import.meta.glob("./examples/*\/*\/meta.json", { eager: true, import: "default" })`.
    */
-  metas?: Record<string, MaybeLazy<DemoMeta | { default: DemoMeta }>>
+  metas?: Record<string, MaybeLazy<unknown>>
   /**
    * The glob prefix the `<page>/<example>` ids are relative to, e.g. `"./examples"`.
    * When omitted, a demo's id is the last two folders of its entry path.
@@ -135,11 +137,17 @@ export function createGlobDemoResolver(options: GlobDemoResolverOptions): DemoRe
           const entry = await entryFor(src)
           const found = Object.entries(options.sources)
             .map(([key, value]) => ({ path: inFolder(src, key), value }))
-            .filter((f): f is { path: string; value: MaybeLazy<string> } =>
+            .filter((f): f is { path: string; value: MaybeLazy<unknown> } =>
               !!f.path && f.path !== "meta.json" && !options.exclude?.(f.path, src))
           const files = await Promise.all(found.map(async ({ path, value }) => {
             const content = await unwrap(value)
-            return { path, content: typeof content === "string" ? content : String(content), language: languageForPath(path) }
+            const text =
+              typeof content === "string"
+                ? content
+                : content && typeof content === "object" && typeof (content as { default?: unknown }).default === "string"
+                  ? (content as { default: string }).default
+                  : String(content)
+            return { path, content: text, language: languageForPath(path) }
           }))
           return sortDemoFiles(files, entry)
         })()

package/src/demo/index.ts

@@ -1,5 +1,5 @@
-export { DocstreamDemoContext, useDemoResolver } from "./context"
-export { DemoBlock, DemoFullscreen, DemoViewer } from "./DemoViewer"
+export { DocstreamDemoContext, DocstreamDemoRuntimeContext, useDemoResolver, useDemoRuntime } from "./context"
+export { DemoBlock, DemoFullscreen, DemoViewer, preloadDemos } from "./DemoViewer"
 export type { DemoFullscreenProps, DemoViewerProps } from "./DemoViewer"
 export {
   createGlobDemoResolver,
@@ -10,6 +10,16 @@ export {
   sortDemoFiles,
 } from "./glob"
 export type { GlobDemoResolverOptions } from "./glob"
-export { defaultDemoMarkdown, resolveDemosToMarkdown } from "./markdown"
-export type { ResolveDemosOptions, ResolvedDemo } from "./markdown"
-export type { DemoComponent, DemoComponentProps, DemoFile, DemoMeta, DemoResolver, DemoVariant } from "./types"
+export { defaultDemoMarkdown, inlineDemoMarkdown, inlineDemoNode, resolveDemosToMarkdown, toInlineFiles } from "./markdown"
+export type { DemoMarkdownFormat, ResolveDemosOptions, ResolvedDemo } from "./markdown"
+export type {
+  DemoComponent,
+  DemoComponentProps,
+  DemoFile,
+  DemoMeta,
+  DemoResolver,
+  DemoRuntimeOptions,
+  DemoVariant,
+  InlineDemoRuntime,
+  InlineDemoRuntimeProps,
+} from "./types"