@brett_lamy/docstream 1.19.1 → 1.20.1

package/dist/styles.css

@@ -3214,6 +3214,95 @@
   line-height: 1.5;
 }
 
+/* An example waiting for the page's env variables (frontmatter `env`). */
+.docs-demo-canvas-env {
+  display: grid;
+  place-items: center;
+  padding: 20px 14px;
+}
+.docs-env-gate {
+  display: grid;
+  gap: 10px;
+  width: min(100%, 420px);
+  padding: 14px 16px;
+  border: 1px solid var(--gb-border);
+  border-radius: 10px;
+  background: var(--gb-background);
+  color: var(--gb-foreground);
+  font-size: 13.5px;
+  line-height: 1.45;
+}
+.docs-env-gate-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+}
+.docs-env-gate-icon {
+  display: inline-grid;
+  place-items: center;
+  width: 26px;
+  height: 26px;
+  border-radius: 50%;
+  background: color-mix(in oklab, var(--gb-primary) 14%, transparent);
+  color: var(--gb-primary);
+  flex: none;
+}
+.docs-env-gate-list {
+  display: grid;
+  gap: 4px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.docs-env-gate-list li {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 12px;
+}
+.docs-env-gate-list span,
+.docs-env-gate-note {
+  color: var(--gb-muted-foreground);
+  font-size: 12.5px;
+}
+.docs-env-gate-form {
+  display: grid;
+  gap: 8px;
+}
+.docs-env-gate-form label {
+  display: grid;
+  gap: 4px;
+}
+.docs-env-gate-form input {
+  font: inherit;
+  padding: 6px 8px;
+  border: 1px solid var(--gb-border);
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+}
+.docs-env-gate-button {
+  justify-self: start;
+  font: inherit;
+  font-weight: 600;
+  padding: 6px 14px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--gb-primary);
+  color: var(--gb-primary-foreground, #fff);
+  cursor: pointer;
+}
+.docs-env-gate-button:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+.docs-env-gate-error {
+  margin: 0;
+  color: var(--gb-destructive, #d93025);
+  font-size: 12.5px;
+}
+
 .docs-demo-loading {
   display: grid;
   place-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "1.19.1",
+  "version": "1.20.1",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"

package/src/demo/DemoViewer.tsx

@@ -42,6 +42,7 @@ import { PathBreadcrumb } from "./PathBreadcrumb"
 import { languageForPath } from "./glob"
 import { useDemoVFSContext, useDemoVFSEntry, type DemoVFS } from "./vfs"
 import { cssToSurface, surfaceStyle, surfaceToCss } from "./surface"
+import { EnvGate, useEnvGate } from "../doc-env"
 import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types"
 
 export interface DemoViewerProps {
@@ -275,6 +276,7 @@ type PreviewSource =
   | { kind: "runtime"; render: (variant: string | undefined) => ReactNode }
   | { kind: "streaming" }
   | { kind: "unavailable" }
+  | { kind: "env"; names: readonly string[]; title: string }
 
 export const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead."
 
@@ -292,6 +294,13 @@ function DemoCanvas({ src, preview, variant, bleed, look }: {
   bleed?: boolean
   look?: CanvasLook
 }) {
+  if (preview.kind === "env") {
+    return (
+      <div className="docs-demo-canvas docs-demo-canvas-env" data-variant={variant}>
+        <EnvGate names={preview.names} title={preview.title} />
+      </div>
+    )
+  }
   if (preview.kind === "unavailable" || preview.kind === "streaming") {
     return (
       <div className="docs-demo-note" role="note" data-variant={variant}>
@@ -733,7 +742,13 @@ export function DemoViewer(props: DemoViewerProps) {
   const hookResolver = tryResolver ? resolver : undefined
   const meta = useMeta(hookResolver, src)
   const resolvedFiles = useFiles(hookResolver, src, near)
-  const component = useComponent(hookResolver, src, near)
+  // Declared env variables the demo's sources use gate it: the module isn't even imported until they're loaded.
+  const sourceTexts = useMemo(() => {
+    const list = resolvedFiles.status === "ready" ? resolvedFiles.value : !tryResolver || resolvedFiles.status === "error" ? inlineFiles : null
+    return list ? list.map((f) => f.content) : null
+  }, [tryResolver, inlineFiles, resolvedFiles])
+  const envGate = useEnvGate(sourceTexts)
+  const component = useComponent(hookResolver, src, near && envGate.open)
   const resolverFailed = meta.status === "error" || resolvedFiles.status === "error" || component.status === "error"
   const mode: "resolver" | "inline" | "none" =
     tryResolver && !(inlineFiles && resolverFailed) ? "resolver" : inlineFiles ? "inline" : "none"
@@ -766,13 +781,17 @@ export function DemoViewer(props: DemoViewerProps) {
   const baseId = useId()
 
   const { runtime, dependencies } = runtimeOptions
+  const envValues = envGate.values
+  const envMissing = envGate.missing
   const preview: PreviewSource = useMemo(() => {
+    if (mode === "inline" && props.streaming) return { kind: "streaming" }
+    if (envMissing?.length) return { kind: "env", names: envMissing, title }
     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 env = Object.keys(envValues).length ? { env: envValues } : {}
+    return { kind: "runtime", render: (v) => runtime({ src, title, files: inlineFiles, entry, variant: v, dependencies, ...env }) }
+  }, [mode, component, props.streaming, runtime, inlineFiles, src, title, dependencies, envMissing, envValues])
   const runnable = preview.kind !== "unavailable"
 
   if (mode === "none") {

package/src/demo/types.ts

@@ -80,6 +80,8 @@ export interface InlineDemoRuntimeProps {
   variant?: string
   /** Extra npm dependencies (`{ "@brett_lamy/ui": "^1.2.0" }`) the files may import. */
   dependencies?: Record<string, string>
+  /** The page's environment variables this demo uses (frontmatter `env`), as `process.env` for the demo. */
+  env?: Readonly<Record<string, string>>
 }
 
 /**

package/src/doc-env.tsx

@@ -0,0 +1,198 @@
+/* Environment variables for a document's examples.
+
+   A page declares the variables its examples need in its frontmatter:
+
+     ---
+     env: [GITHUB_TOKEN, NETLIFY_AUTH_TOKEN]
+     ---
+
+   An example (a `{% demo %}` or a live code fence) whose source mentions one of them does not
+   run straight away: it shows a gate that asks the host for the values — the host's
+   `DocstreamEnvHost.request` can read them from a keychain or start a login — and runs once it
+   has them. In-page demos read the values with `useDocstreamEnv()`; examples that run in
+   almost-node get them as `process.env.NAME`. Without a host the gate asks for the values
+   directly and keeps them in memory for the page. */
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type FormEvent, type ReactNode } from "react"
+
+export type DocstreamEnvValues = Readonly<Record<string, string>>
+
+/** How the host supplies values: a keychain, a login, a secrets manager. */
+export interface DocstreamEnvHost {
+  /**
+   * Resolves with the values it could get (unlocking a keychain or signing in as needed). Names it
+   * leaves out stay missing and the example stays gated; a rejection is shown on the gate.
+   */
+  request: (names: readonly string[]) => Promise<Record<string, string>>
+  /** The gate's button, e.g. "Load from Keychain". Default "Load Variables". */
+  label?: string
+  /** A short line about one variable, e.g. "Sign in with GitHub" — shown beside its name. */
+  describe?: (name: string) => string | undefined
+}
+
+export interface DocstreamEnv {
+  /** Variables this document declares. */
+  declared: readonly string[]
+  /** Values loaded so far (shared by every example on the page). */
+  values: DocstreamEnvValues
+  /** Asks the host (or the reader) for `names`; resolves with every value now known. */
+  request: (names: readonly string[]) => Promise<DocstreamEnvValues>
+  host?: DocstreamEnvHost
+  /** Keeps values the reader typed into a host-less gate. */
+  provide: (values: Record<string, string>) => void
+}
+
+const EMPTY: DocstreamEnvValues = Object.freeze({})
+const noRequest = () => Promise.resolve(EMPTY)
+
+const DocstreamEnvContext = createContext<DocstreamEnv>({ declared: [], values: EMPTY, request: noRequest, provide: () => {} })
+
+/** The page's variables and the values loaded so far. Demos call it to read their secrets. */
+export function useDocstreamEnv(): DocstreamEnv {
+  return useContext(DocstreamEnvContext)
+}
+
+/** Reads `env` from parsed frontmatter values: a list, or one comma/space separated string. */
+export function envNamesFromProperties(values: Record<string, unknown> | undefined): string[] {
+  const raw = values?.env
+  const list = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(/[\s,]+/) : []
+  return [...new Set(list.filter((v): v is string => typeof v === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(v)))]
+}
+
+/** The declared names `sources` mention (as whole identifiers), in declaration order. */
+export function usedEnvNames(sources: readonly string[], declared: readonly string[]): string[] {
+  if (!declared.length) return []
+  const text = sources.join("\n")
+  return declared.filter((name) => new RegExp(`(^|[^A-Za-z0-9_$])${name}(?![A-Za-z0-9_$])`).test(text))
+}
+
+export interface DocstreamEnvProviderProps {
+  /** Names declared by the document (merged with any declared further up). */
+  declared?: readonly string[]
+  host?: DocstreamEnvHost
+  children?: ReactNode
+}
+
+/**
+ * Holds a page's variables. The renderers add one from the frontmatter's `env`; a host may wrap
+ * the page in another to supply `host` (or pass `envHost` to the renderer). Values loaded by an
+ * outer provider are shared with inner ones.
+ */
+export function DocstreamEnvProvider({ declared = [], host, children }: DocstreamEnvProviderProps) {
+  const outer = useContext(DocstreamEnvContext)
+  const [own, setOwn] = useState<DocstreamEnvValues>(EMPTY)
+  const effectiveHost = host ?? outer.host
+  const values = useMemo(() => (own === EMPTY ? outer.values : { ...outer.values, ...own }), [outer.values, own])
+  const valuesRef = useRef(values)
+  valuesRef.current = values
+  const declaredKey = declared.join(",")
+  const allDeclared = useMemo(
+    () => [...new Set([...outer.declared, ...declared])],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [outer.declared, declaredKey],
+  )
+  const provide = useCallback((next: Record<string, string>) => setOwn((v) => ({ ...v, ...next })), [])
+  const request = useCallback(async (names: readonly string[]) => {
+    const missing = names.filter((n) => valuesRef.current[n] === undefined)
+    if (!missing.length || !effectiveHost) return valuesRef.current
+    const got = await effectiveHost.request(missing)
+    const kept = Object.fromEntries(Object.entries(got).filter(([k, v]) => missing.includes(k) && typeof v === "string"))
+    setOwn((v) => ({ ...v, ...kept }))
+    return { ...valuesRef.current, ...kept }
+  }, [effectiveHost])
+  const value = useMemo<DocstreamEnv>(
+    () => ({ declared: allDeclared, values, request, provide, ...(effectiveHost ? { host: effectiveHost } : {}) }),
+    [allDeclared, values, request, provide, effectiveHost],
+  )
+  return <DocstreamEnvContext.Provider value={value}>{children}</DocstreamEnvContext.Provider>
+}
+
+/** Which of an example's sources' declared variables are still missing. */
+export function useEnvGate(sources: readonly string[] | null) {
+  const env = useDocstreamEnv()
+  const key = sources ? sources.join("\u0000") : null
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const used = useMemo(() => (sources ? usedEnvNames(sources, env.declared) : null), [key, env.declared])
+  // A page that declares nothing never waits for its examples' sources.
+  const missing = !env.declared.length ? [] : used ? used.filter((n) => env.values[n] === undefined) : null
+  const values = useMemo(() => {
+    if (!used?.length) return EMPTY
+    return Object.fromEntries(used.map((n) => [n, env.values[n]!]).filter(([, v]) => v !== undefined)) as DocstreamEnvValues
+  }, [used, env.values])
+  return {
+    /** Unknown until the sources are; then the declared names they use. */
+    used,
+    /** null while the sources are loading. */
+    missing,
+    /** The example may run: no declared variable used, or all of them loaded. */
+    open: missing !== null && missing.length === 0,
+    /** The values of the variables this example uses. */
+    values,
+  }
+}
+
+/** The card an example shows until its variables are loaded. */
+export function EnvGate({ names, title }: { names: readonly string[]; title?: string }) {
+  const env = useDocstreamEnv()
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [typed, setTyped] = useState<Record<string, string>>({})
+  const host = env.host
+
+  const load = async () => {
+    setBusy(true)
+    setError(null)
+    try {
+      const got = await env.request(names)
+      const still = names.filter((n) => got[n] === undefined)
+      if (still.length) setError(`Still missing ${still.join(", ")}.`)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+  const submit = (event: FormEvent) => {
+    event.preventDefault()
+    const filled = Object.fromEntries(names.map((n) => [n, typed[n] ?? ""]).filter(([, v]) => v))
+    if (Object.keys(filled).length === names.length) env.provide(filled)
+    else setError("Fill in every variable to run the example.")
+  }
+
+  return (
+    <div className="docs-env-gate" role="group" aria-label={`${title ?? "Example"} needs environment variables`} data-docstream-env-gate="">
+      <div className="docs-env-gate-head">
+        <span className="docs-env-gate-icon" aria-hidden="true">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+            <circle cx="7.5" cy="15.5" r="5.5" /><path d="m21 2-9.6 9.6" /><path d="m15.5 7.5 3 3L22 7l-3-3" />
+          </svg>
+        </span>
+        <span>This example needs {names.length === 1 ? "a variable" : `${names.length} variables`} before it runs.</span>
+      </div>
+      {host ? (
+        <>
+          <ul className="docs-env-gate-list">
+            {names.map((n) => (
+              <li key={n}><code>{n}</code>{host.describe?.(n) ? <span>{host.describe(n)}</span> : null}</li>
+            ))}
+          </ul>
+          <button type="button" className="docs-env-gate-button" onClick={() => void load()} disabled={busy}>
+            {busy ? "Waiting…" : host.label ?? "Load Variables"}
+          </button>
+        </>
+      ) : (
+        <form className="docs-env-gate-form" onSubmit={submit}>
+          {names.map((n) => (
+            <label key={n}>
+              <code>{n}</code>
+              <input type="password" autoComplete="off" spellCheck={false} value={typed[n] ?? ""}
+                onChange={(e) => setTyped((t) => ({ ...t, [n]: e.target.value }))} />
+            </label>
+          ))}
+          <button type="submit" className="docs-env-gate-button">Run Example</button>
+          <span className="docs-env-gate-note">Kept in memory for this page only.</span>
+        </form>
+      )}
+      {error ? <p className="docs-env-gate-error" role="alert">{error}</p> : null}
+    </div>
+  )
+}

package/src/docs/DocsRenderer.tsx

@@ -40,6 +40,8 @@ import { ImageThumbnail, leadingThumbnail, thumbnailLabel } from "./ImageThumbna
 import { DocumentProperties } from "./DocumentProperties"
 import { TaskCheckbox, TaskStateChangeContext, type TaskStateChangeHandler } from "./TaskCheckbox"
 import { getTaskState } from "../gitbook/tasks"
+import { readDocumentProperties } from "../gitbook/properties"
+import { DocstreamEnvProvider, EnvGate, envNamesFromProperties, useEnvGate, type DocstreamEnvHost } from "../doc-env"
 import { plainText } from "../gitbook/inline"
 
 type MathRenderer = (formula: string) => string
@@ -88,6 +90,8 @@ export interface LivePreviewProps {
   title: string
   collapsedCodeLines?: number
   expandedCodeLines?: number
+  /** The page's environment variables this example uses (frontmatter `env`), once loaded. */
+  env?: Readonly<Record<string, string>>
 }
 
 export type LivePreviewRenderer = (props: LivePreviewProps) => ReactNode
@@ -380,14 +384,7 @@ function BlockView({ block, liveRenderer, sourceRenderer }: { block: Block } & R
         return <StrudelPlayer code={block.code} {...(block.title ? { title: block.title } : {})} />
       }
       if (block.live && isReactLanguage(block.language) && liveRenderer) {
-        const entry = block.entry ?? "/src/main.jsx"
-        return liveRenderer({
-          files: { [entry]: block.code },
-          entry,
-          title: block.title ?? "Live React preview",
-          collapsedCodeLines: block.collapsedCodeLines,
-          expandedCodeLines: block.expandedCodeLines,
-        })
+        return <LiveFence block={block} liveRenderer={liveRenderer} />
       }
       return (
         <div className="docs-code" data-language={block.language ?? undefined}>
@@ -673,6 +670,23 @@ function withoutLinks(nodes: Inline[]): Inline[] {
   })
 }
 
+/** A live code fence: gated on the page's env variables it mentions, then handed to the host's renderer. */
+function LiveFence({ block, liveRenderer }: { block: CodeBlockNode; liveRenderer: LivePreviewRenderer }) {
+  const sources = useMemo(() => [block.code], [block.code])
+  const gate = useEnvGate(sources)
+  const title = block.title ?? "Live React preview"
+  if (gate.missing?.length) return <EnvGate names={gate.missing} title={title} />
+  const entry = block.entry ?? "/src/main.jsx"
+  return liveRenderer({
+    files: { [entry]: block.code },
+    entry,
+    title,
+    collapsedCodeLines: block.collapsedCodeLines,
+    expandedCodeLines: block.expandedCodeLines,
+    ...(gate.used?.length ? { env: gate.values } : {}),
+  })
+}
+
 export interface DocRenderOptions {
   /** Make rendered task checkboxes interactive. Update the supplied item and re-render to persist a choice. */
   onTaskStateChange?: TaskStateChangeHandler
@@ -699,6 +713,24 @@ export interface DocRenderOptions {
    * `true` uses the defaults; an object passes options to `DocPageActions`.
    */
   pageActions?: boolean | DocPageActionsOptions
+  /**
+   * Supplies the values of the environment variables the page declares (frontmatter `env`), e.g.
+   * from a keychain or a login. Without one, gated examples ask the reader for the values.
+   */
+  envHost?: DocstreamEnvHost
+  /** Variables to declare in addition to the frontmatter's `env`. */
+  env?: readonly string[]
+}
+
+/** The variables a document declares in its frontmatter's `env`. */
+export function documentEnv(doc: DocumentNode): string[] {
+  return doc.properties ? envNamesFromProperties(readDocumentProperties(doc.properties).values) : []
+}
+
+function withEnv(doc: DocumentNode, { envHost, env }: DocRenderOptions, children: ReactNode) {
+  const declared = [...new Set([...(env ?? []), ...documentEnv(doc)])]
+  if (!declared.length && !envHost) return children
+  return <DocstreamEnvProvider declared={declared} host={envHost}>{children}</DocstreamEnvProvider>
 }
 
 function withDemoContext({ demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange }: DocRenderOptions, children: ReactNode) {
@@ -749,16 +781,18 @@ export function MarkdownContent({
   className,
   documentProperties = true,
   onTaskStateChange,
+  envHost,
+  env,
 }: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
   const doc = useMemo(() => parseMarkdown(markdown), [markdown])
   return withDemoContext(
     { demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange },
-    <div data-docstream="" className={className}>
+    withEnv(doc, { envHost, env }, <div data-docstream="" className={className}>
       <PageActionsBar markdown={markdown} options={pageActions} />
       {documentProperties && doc.properties ? <DocumentProperties properties={doc.properties} defaultOpen={typeof documentProperties === "object" && documentProperties.defaultOpen} /> : null}
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
-    </div>,
+    </div>),
   )
 }
 
@@ -774,15 +808,17 @@ export function DocsRenderer({
   markdown,
   documentProperties = true,
   onTaskStateChange,
+  envHost,
+  env,
 }: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
   return withDemoContext(
     { demoResolver, demoRuntime, demoDependencies, demoVFS, onTaskStateChange },
-    <article className="docs-article">
+    withEnv(doc, { envHost, env }, <article className="docs-article">
       <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
       {documentProperties && doc.properties ? <DocumentProperties properties={doc.properties} defaultOpen={typeof documentProperties === "object" && documentProperties.defaultOpen} /> : null}
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
       <CitationSources citations={doc.citations} />
-    </article>,
+    </article>),
   )
 }
 

package/src/index.ts

@@ -2,10 +2,12 @@
 // inline-file demos run only when the host passes a runtime — see `@brett_lamy/docstream/playground`.
 export { GitbookStreamdown } from "./streamdown"
 export type { GitbookStreamdownProps } from "./streamdown"
-export { DocsRenderer, MarkdownContent, MathFormula } from "./docs/DocsRenderer"
+export { DocsRenderer, MarkdownContent, MathFormula, documentEnv } from "./docs/DocsRenderer"
 export { TaskCheckbox, TASK_STATE_ICONS } from "./docs/TaskCheckbox"
 export type { TaskCheckboxProps, TaskStateChangeHandler } from "./docs/TaskCheckbox"
 export { TASK_STATES, getTaskState, taskMarker, taskStateFromMarker } from "./gitbook/tasks"
+export { DocstreamEnvProvider, EnvGate, envNamesFromProperties, useDocstreamEnv, useEnvGate, usedEnvNames } from "./doc-env"
+export type { DocstreamEnv, DocstreamEnvHost, DocstreamEnvProviderProps, DocstreamEnvValues } from "./doc-env"
 export { DocumentProperties } from "./docs/DocumentProperties"
 export type { DocumentPropertiesProps } from "./docs/DocumentProperties"
 export { readDocumentProperties, removeDocumentProperty, setDocumentProperty } from "./gitbook/properties"

package/src/playground/InlineDemoPreview.tsx

@@ -16,8 +16,8 @@ export interface InlineDemoPreviewProps extends InlineDemoRuntimeProps {
   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])])
+function filesKey(files: DemoFile[], entry: string, dependencies: Record<string, string> | undefined, env: InlineDemoRuntimeProps["env"]) {
+  return JSON.stringify([entry, dependencies ?? null, env ?? null, files.map((f) => [f.path, f.content])])
 }
 
 export function InlineDemoPreview({
@@ -26,16 +26,17 @@ export function InlineDemoPreview({
   entry,
   variant,
   dependencies,
+  env,
   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 key = filesKey(files, entry, dependencies, env)
   const project = useMemo(
     () => {
       try {
-        return { value: createInlineDemoProject(files, { entry, dependencies }) }
+        return { value: createInlineDemoProject(files, { entry, dependencies, ...(env ? { env } : {}) }) }
       } catch (error) {
         return { error: error instanceof Error ? error.message : String(error) }
       }

package/src/playground/PlaygroundStreamdown.tsx

@@ -5,6 +5,7 @@ import { DocstreamDemoRuntimeContext } from "../demo/context"
 import { GitbookStreamdown, type GitbookStreamdownProps } from "../streamdown"
 import { almostNodeDemoRuntime } from "./InlineDemoPreview"
 import { ReactCodePreview } from "./ReactCodePreview"
+import { injectEnv } from "./project"
 
 export type PlaygroundStreamdownProps = GitbookStreamdownProps
 
@@ -12,9 +13,11 @@ export type PlaygroundStreamdownProps = GitbookStreamdownProps
  * A `LivePreviewRenderer` that runs `live` React/JSX/TSX code fences in almost-node.
  * Pass it as `liveRenderer` to the root `GitbookStreamdown` / `DocsRenderer` (or the editor).
  */
-export const almostNodeLiveRenderer: LivePreviewRenderer = ({ files, entry, title, collapsedCodeLines, expandedCodeLines }) => (
+export const almostNodeLiveRenderer: LivePreviewRenderer = ({ files, entry, title, collapsedCodeLines, expandedCodeLines, env }) => (
   <ReactCodePreview
-    files={files}
+    files={env ? withEnv(files, entry, env) : files}
+    // The code panel shows the fence as written, not the env import.
+    {...(env ? { code: files[entry] } : {})}
     entry={entry}
     title={title}
     collapsedCodeLines={collapsedCodeLines}
@@ -22,6 +25,12 @@ export const almostNodeLiveRenderer: LivePreviewRenderer = ({ files, entry, titl
   />
 )
 
+function withEnv(files: Record<string, string>, entry: string, env: Readonly<Record<string, string>>) {
+  const map: Record<string, string> = { ...files }
+  injectEnv(map, entry, env)
+  return map
+}
+
 /**
  * `GitbookStreamdown` with the almost-node playground wired in: live code fences and
  * `{% demo %}` blocks with inline files (and no resolver) run in almost-node

package/src/playground/project.ts

@@ -118,6 +118,8 @@ export interface InlineDemoProjectOptions {
   entry?: string
   /** Extra npm dependencies (merged over a `package.json` among the files, if any). */
   dependencies?: Record<string, string>
+  /** Environment variables, set as `process.env` before the demo runs (see `injectEnv`). */
+  env?: Readonly<Record<string, string>>
 }
 
 export interface InlineDemoProject {
@@ -190,5 +192,23 @@ createRoot(document.getElementById("root")).render(
 `
   }
   const entry = wrapped ? WRAPPER_ENTRY : entryPath
+  if (options.env && Object.keys(options.env).length) injectEnv(map, entry, options.env)
   return { files: createReactDemoFiles(map, { entry, dependencies }), entry, wrapped }
 }
+
+/** Where `injectEnv` writes the values; the entry imports it first. */
+export const ENV_MODULE = "/src/docstream-env.js"
+
+/**
+ * Makes `env` the project's `process.env` (and `globalThis.__DOCSTREAM_ENV__`): writes a module that
+ * sets them and imports it at the top of `entry`, so it runs before anything the entry imports.
+ */
+export function injectEnv(map: Record<string, AlmostNodeFileContent>, entry: string, env: Readonly<Record<string, string>>) {
+  map[ENV_MODULE] = `const env = ${JSON.stringify(env)}
+globalThis.process = globalThis.process ?? { env: {} }
+globalThis.process.env = Object.assign(globalThis.process.env ?? {}, env)
+globalThis.__DOCSTREAM_ENV__ = env
+`
+  const source = map[entry]
+  if (typeof source === "string") map[entry] = `import ${JSON.stringify(ENV_MODULE)}\n${source}`
+}