@brett_lamy/docstream 1.4.0 → 1.6.0

package/src/demo/copy-demo.tsx

@@ -0,0 +1,102 @@
+/* "Copy demo": writes the docstream clipboard (Markdown with the demo's files inline, plus the
+   `application/x-docstream+json` payload) through react-aria's `useClipboard`, so pasting into
+   a docstream editor recreates the demo with its files. A button click has no copy event of
+   its own, so the button focuses itself and runs the browser's copy command; react-aria's
+   listener then fills the event's DataTransfer. Where that is unavailable, the Markdown is
+   copied as plain text (editors still parse its inline-file demos). */
+import { useEffect, useRef, useState, type DOMAttributes, type MutableRefObject } from "react"
+import { useClipboard } from "react-aria"
+import { CopyIcon, copyText } from "../docs/copy"
+import { docstreamClipboardItems, type DocstreamClipboard } from "./clipboard"
+
+export interface DocstreamCopy<T extends HTMLElement> {
+  ref: MutableRefObject<T | null>
+  /** react-aria `useClipboard`'s focus handlers: Cmd/Ctrl+C on the focused element copies too. */
+  props: DOMAttributes<T>
+  /** Copies; resolves false when there was nothing to copy. */
+  copy: () => Promise<boolean>
+}
+
+/**
+ * Copies a `DocstreamClipboard` (all three representations) from a click. Spread `props` on
+ * the triggering element (a focusable one, e.g. a `<button>`) and give it `ref`.
+ */
+export function useDocstreamCopy<T extends HTMLElement = HTMLButtonElement>(produce: () => DocstreamClipboard | null): DocstreamCopy<T> {
+  const ref = useRef<T | null>(null)
+  const latest = useRef(produce)
+  latest.current = produce
+  const wrote = useRef(false)
+  const { clipboardProps } = useClipboard({
+    getItems: () => {
+      const clip = latest.current()
+      return clip ? docstreamClipboardItems(clip) : []
+    },
+    onCopy: () => {
+      wrote.current = true
+    },
+  })
+
+  const copy = async (): Promise<boolean> => {
+    const clip = latest.current()
+    if (!clip) return false
+    const el = ref.current
+    wrote.current = false
+    if (el && typeof document !== "undefined" && typeof document.execCommand === "function") {
+      // The copy event targets the selection when there is one; clear it so it targets
+      // this (focused) element and nothing else — an editor around us — claims the event.
+      const selection = typeof window !== "undefined" ? window.getSelection() : null
+      const ranges: Range[] = []
+      if (selection) for (let i = 0; i < selection.rangeCount; i++) ranges.push(selection.getRangeAt(i))
+      try {
+        if (document.activeElement !== el) el.focus({ preventScroll: true })
+        selection?.removeAllRanges()
+        document.execCommand("copy")
+      } catch {
+        // fall through to the plain-text copy
+      } finally {
+        if (selection && ranges.length && !selection.rangeCount) for (const range of ranges) selection.addRange(range)
+      }
+    }
+    if (!wrote.current) await copyText(clip.text)
+    return true
+  }
+
+  return { ref, props: clipboardProps as DOMAttributes<T>, copy }
+}
+
+export interface CopyDemoButtonProps {
+  /** The clipboard to write, computed on click. `null` disables the copy. */
+  clipboard: () => DocstreamClipboard | null
+  label?: string
+  className?: string
+}
+
+/** Icon button: copies the demo (Markdown + files + docstream payload) and swaps to a tick. */
+export function CopyDemoButton({ clipboard, label = "Copy demo", className }: CopyDemoButtonProps) {
+  const { ref, props, copy } = useDocstreamCopy(clipboard)
+  const [copied, setCopied] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  useEffect(() => () => clearTimeout(timer.current), [])
+  return (
+    <button
+      {...props}
+      ref={ref}
+      type="button"
+      className={className ? `docs-copy ${className}` : "docs-copy"}
+      onClick={() => {
+        void copy().then((ok) => {
+          if (!ok) return
+          setCopied(true)
+          clearTimeout(timer.current)
+          timer.current = setTimeout(() => setCopied(false), 1600)
+        })
+      }}
+      aria-label={copied ? "Copied" : label}
+      title={copied ? "Copied" : `${label} (Markdown with its files — paste into a docstream editor)`}
+      data-copied={copied || undefined}
+      data-docstream-copy-demo=""
+    >
+      <CopyIcon copied={copied} />
+    </button>
+  )
+}

package/src/demo/index.ts

@@ -1,5 +1,32 @@
-export { DocstreamDemoContext, DocstreamDemoRuntimeContext, useDemoResolver, useDemoRuntime } from "./context"
-export { DemoBlock, DemoFullscreen, DemoViewer, preloadDemos } from "./DemoViewer"
+export { DocstreamDemoContext, DocstreamDemoRuntimeContext, DocstreamDemoVFSContext, useDemoResolver, useDemoRuntime } from "./context"
+export { DemoBlock, DemoFullscreen, DemoViewer, peekDemoSource, prefetchDemoSources, preloadDemos } from "./DemoViewer"
+export {
+  DOCSTREAM_CLIPBOARD_TYPE,
+  collectDemoNodes,
+  createDocstreamClipboard,
+  createDocstreamClipboardFromMarkdown,
+  demoNodeMeta,
+  docstreamClipboardItems,
+  docstreamPayloadFromMarkdown,
+  hasDocstreamClipboard,
+  mapDemoNodes,
+  parseDocstreamClipboard,
+  readDocstreamClipboard,
+  readDocstreamClipboardItems,
+  writeDocstreamClipboard,
+} from "./clipboard"
+export type {
+  CreateDocstreamClipboardOptions,
+  DemoSourceSnapshot,
+  DocstreamClipboard,
+  DocstreamClipboardItem,
+  DocstreamClipboardPayload,
+  DocstreamDropItem,
+} from "./clipboard"
+export { CopyDemoButton, useDocstreamCopy } from "./copy-demo"
+export type { CopyDemoButtonProps, DocstreamCopy } from "./copy-demo"
+export { createDemoVFS, useDemoVFS, useDemoVFSContext, useDemoVFSEntry, useDemoVFSFiles } from "./vfs"
+export type { DemoVFS, DemoVFSChange, DemoVFSEntry, DemoVFSResolverOptions } from "./vfs"
 export type { DemoFullscreenProps, DemoViewerProps } from "./DemoViewer"
 export {
   createGlobDemoResolver,

package/src/demo/vfs.ts

@@ -0,0 +1,197 @@
+/* The demo virtual file system: demo files held in memory by `src`, for demos no host
+   resolver knows — typically ones pasted from another docstream page or editor.
+
+   - `DemoViewer` reads it from context (`DocstreamDemoVFSContext`, or a renderer's `demoVFS`):
+     a block with no inline files whose `src` is in the VFS shows the VFS files exactly like
+     inline files (the host resolver still wins when it knows `src`; the Preview runs through
+     the `demoRuntime`, else the Code view opens with the "needs runtime" note).
+   - `vfs.resolver({ resolver, runtime })` is the same thing as a `DemoResolver`, layered over
+     a host resolver: `files` / `meta` from the host when it knows `src`, else from the VFS;
+     `load` from the host, else a component that runs the VFS files through the runtime.
+   - One VFS may be shared by several editors / renderers; `subscribe` reports changes so a
+     host can persist pasted files. */
+import { useContext, useRef, useSyncExternalStore } from "react"
+import { DocstreamDemoVFSContext } from "./context"
+import type { DemoComponentProps, DemoFile, DemoMeta, DemoResolver, InlineDemoRuntime } from "./types"
+
+export interface DemoVFSEntry {
+  /** Entry first (or `meta.entry`), paths relative to the demo folder. */
+  files: DemoFile[]
+  /** `meta.json`-style defaults, usually the `{% demo %}` tag's attributes. */
+  meta?: DemoMeta
+}
+
+export interface DemoVFSChange {
+  src: string
+  /** The new entry; `undefined` when `src` was removed. */
+  entry: DemoVFSEntry | undefined
+}
+
+export interface DemoVFSResolverOptions {
+  /** The host resolver, consulted first. */
+  resolver?: DemoResolver
+  /** Runs VFS files for `load(src)`. Without one, `load` rejects for VFS-only demos. */
+  runtime?: InlineDemoRuntime
+  /** Extra npm dependencies handed to the runtime. */
+  dependencies?: Record<string, string>
+}
+
+export interface DemoVFS {
+  get(src: string): DemoVFSEntry | undefined
+  has(src: string): boolean
+  /** Every `src` held, in insertion order. */
+  list(): string[]
+  /** Adds or replaces `src`. A no-op (and no change event) when nothing differs. */
+  set(src: string, files: DemoFile[], meta?: DemoMeta): void
+  delete(src: string): boolean
+  clear(): void
+  /** Everything held, as `{ [src]: entry }`. The object is stable until the next change. */
+  snapshot(): Readonly<Record<string, DemoVFSEntry>>
+  /** Files only, as `{ [src]: files }` (what a host usually persists). Stable until the next change. */
+  files(): Readonly<Record<string, DemoFile[]>>
+  subscribe(listener: (change: DemoVFSChange) => void): () => void
+  /** This VFS as a `DemoResolver` layered over a host resolver. */
+  resolver(options?: DemoVFSResolverOptions): DemoResolver
+}
+
+const RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead."
+
+function cleanFiles(files: DemoFile[]): DemoFile[] {
+  return files
+    .filter((f) => f && typeof f.path === "string" && typeof f.content === "string")
+    .map((f) => ({ path: f.path, content: f.content, ...(f.language ? { language: f.language } : {}) }))
+}
+
+function entryFirst(files: DemoFile[], entry: string | undefined): DemoFile[] {
+  const index = entry ? files.findIndex((f) => f.path === entry) : -1
+  return index > 0 ? [files[index], ...files.slice(0, index), ...files.slice(index + 1)] : files
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+/** A new, empty (or pre-filled) demo VFS. */
+export function createDemoVFS(initial?: Record<string, DemoFile[] | DemoVFSEntry>): DemoVFS {
+  const entries = new Map<string, DemoVFSEntry>()
+  const listeners = new Set<(change: DemoVFSChange) => void>()
+  let snap: Record<string, DemoVFSEntry> | null = null
+  let fileSnap: Record<string, DemoFile[]> | null = null
+
+  const put = (src: string, files: DemoFile[], meta?: DemoMeta) => {
+    const entry: DemoVFSEntry = { files: cleanFiles(files), ...(meta && Object.keys(meta).length ? { meta } : {}) }
+    const prev = entries.get(src)
+    if (prev && same(prev, entry)) return undefined
+    entries.set(src, entry)
+    return entry
+  }
+  const emit = (change: DemoVFSChange) => {
+    snap = null
+    fileSnap = null
+    for (const listener of Array.from(listeners)) listener(change)
+  }
+
+  for (const [src, value] of Object.entries(initial ?? {})) {
+    if (Array.isArray(value)) put(src, value)
+    else if (value) put(src, value.files, value.meta)
+  }
+
+  const vfs: DemoVFS = {
+    get: (src) => entries.get(src),
+    has: (src) => entries.has(src),
+    list: () => Array.from(entries.keys()),
+    set(src, files, meta) {
+      const entry = put(src, files, meta)
+      if (entry) emit({ src, entry })
+    },
+    delete(src) {
+      if (!entries.delete(src)) return false
+      emit({ src, entry: undefined })
+      return true
+    },
+    clear() {
+      for (const src of Array.from(entries.keys())) vfs.delete(src)
+    },
+    snapshot() {
+      if (!snap) snap = Object.fromEntries(entries)
+      return snap
+    },
+    files() {
+      if (!fileSnap) fileSnap = Object.fromEntries(Array.from(entries, ([src, e]) => [src, e.files]))
+      return fileSnap
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    resolver: (options) => layeredResolver(vfs, options ?? {}),
+  }
+  return vfs
+}
+
+function layeredResolver(vfs: DemoVFS, { resolver: host, runtime, dependencies }: DemoVFSResolverOptions): DemoResolver {
+  // Whether the host should be asked first: it lists `src`, or it can't list at all.
+  const hostFirst = (src: string) => !!host && (!host.list || host.list().includes(src) || !vfs.has(src))
+  const fromVfs = (src: string) => {
+    const entry = vfs.get(src)
+    if (!entry) throw new Error(`Unknown demo: ${src}`)
+    return entry
+  }
+  async function pick<T>(src: string, viaHost: (host: DemoResolver) => Promise<T>, viaVfs: (entry: DemoVFSEntry) => T): Promise<T> {
+    if (hostFirst(src)) {
+      try {
+        return await viaHost(host!)
+      } catch (error) {
+        if (!vfs.has(src)) throw error
+      }
+    }
+    return viaVfs(fromVfs(src))
+  }
+  const layered: DemoResolver = {
+    list: () => Array.from(new Set([...(host?.list?.() ?? []), ...vfs.list()])),
+    meta: (src) => pick(src, (h) => h.meta(src), (e) => e.meta),
+    files: (src) => pick(src, (h) => h.files(src), (e) => entryFirst(e.files, e.meta?.entry)),
+    load: (src) =>
+      pick(src, (h) => h.load(src), (e) => {
+        if (!runtime) throw new Error(RUNTIME_NOTE)
+        const files = entryFirst(e.files, e.meta?.entry)
+        const title = e.meta?.title ?? (src.split("/").pop() || "Demo")
+        const VfsDemo = ({ variant }: DemoComponentProps) =>
+          runtime({ src, title, files, entry: files[0]?.path ?? "index.tsx", ...(variant ? { variant } : {}), ...(dependencies ? { dependencies } : {}) })
+        VfsDemo.displayName = `VfsDemo(${src})`
+        return VfsDemo as never
+      }),
+  }
+  if (host?.href) layered.href = (src, options) => (hostFirst(src) ? host.href!(src, options) : undefined)
+  return layered
+}
+
+/**
+ * A demo VFS owned by the calling component (created once). Pass it as `demoVFS` to several
+ * editors / renderers to share pasted demo files between them.
+ */
+export function useDemoVFS(initial?: Record<string, DemoFile[] | DemoVFSEntry>): DemoVFS {
+  const ref = useRef<DemoVFS | null>(null)
+  if (!ref.current) ref.current = createDemoVFS(initial)
+  return ref.current
+}
+
+/** The VFS in context (a renderer's or editor's `demoVFS`), unless `override` is given. */
+export function useDemoVFSContext(override?: DemoVFS): DemoVFS | undefined {
+  const inherited = useContext(DocstreamDemoVFSContext)
+  return override ?? inherited
+}
+
+const EMPTY: Readonly<Record<string, DemoFile[]>> = Object.freeze({})
+const noop = () => () => {}
+
+/** `{ [src]: files }` of a VFS, re-rendering on change. */
+export function useDemoVFSFiles(vfs: DemoVFS | undefined): Readonly<Record<string, DemoFile[]>> {
+  return useSyncExternalStore(vfs ? vfs.subscribe : noop, () => (vfs ? vfs.files() : EMPTY), () => (vfs ? vfs.files() : EMPTY))
+}
+
+/** One VFS entry, re-rendering when it changes. */
+export function useDemoVFSEntry(vfs: DemoVFS | undefined, src: string): DemoVFSEntry | undefined {
+  const snapshot = useSyncExternalStore(vfs ? vfs.subscribe : noop, () => vfs?.snapshot(), () => vfs?.snapshot())
+  return src ? snapshot?.[src] : undefined
+}

package/src/docs/DocsRenderer.tsx

@@ -16,7 +16,8 @@ import { slugify } from "../gitbook/outline"
 import { resolveAsset } from "../assets"
 import { parseMarkdown } from "../gitbook/parse"
 import { serializeMarkdown } from "../gitbook/serialize"
-import { DocstreamDemoContext, DocstreamDemoRuntimeContext } from "../demo/context"
+import { DocstreamDemoContext, DocstreamDemoRuntimeContext, DocstreamDemoVFSContext } from "../demo/context"
+import type { DemoVFS } from "../demo/vfs"
 import { DemoBlock } from "../demo/DemoViewer"
 import type { DemoResolver, InlineDemoRuntime } from "../demo/types"
 import { CopyButton } from "./copy"
@@ -592,6 +593,11 @@ export interface DocRenderOptions {
   demoRuntime?: InlineDemoRuntime
   /** Extra npm dependencies inline demos may import (`{ "@brett_lamy/ui": "^1.2.0" }`). */
   demoDependencies?: Record<string, string>
+  /**
+   * Demo files held in memory by `src` (`createDemoVFS` / `useDemoVFS`), e.g. demos pasted
+   * into an editor. Blocks without inline files use them when no resolver knows `src`.
+   */
+  demoVFS?: DemoVFS
   /**
    * Render "Copy page ▾" (Copy / View as Markdown, Open in ChatGPT / Claude) above the content.
    * `true` uses the defaults; an object passes options to `DocPageActions`.
@@ -599,8 +605,9 @@ export interface DocRenderOptions {
   pageActions?: boolean | DocPageActionsOptions
 }
 
-function withDemoContext({ demoResolver, demoRuntime, demoDependencies }: DocRenderOptions, children: ReactNode) {
+function withDemoContext({ demoResolver, demoRuntime, demoDependencies, demoVFS }: DocRenderOptions, children: ReactNode) {
   let out = children
+  if (demoVFS) out = <DocstreamDemoVFSContext.Provider value={demoVFS}>{out}</DocstreamDemoVFSContext.Provider>
   if (demoRuntime || demoDependencies) {
     out = <DemoRuntimeProvider runtime={demoRuntime} dependencies={demoDependencies}>{out}</DemoRuntimeProvider>
   }
@@ -640,12 +647,13 @@ export function MarkdownContent({
   demoResolver,
   demoRuntime,
   demoDependencies,
+  demoVFS,
   pageActions,
   className,
 }: { markdown: string; className?: string } & Renderers & DocRenderOptions) {
   const doc = useMemo(() => parseMarkdown(markdown), [markdown])
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS },
     <div data-docstream="" className={className}>
       <PageActionsBar markdown={markdown} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />
@@ -661,11 +669,12 @@ export function DocsRenderer({
   demoResolver,
   demoRuntime,
   demoDependencies,
+  demoVFS,
   pageActions,
   markdown,
 }: { doc: DocumentNode; /** Source for page actions; defaults to `serializeMarkdown(doc)`. */ markdown?: string } & Renderers & DocRenderOptions) {
   return withDemoContext(
-    { demoResolver, demoRuntime, demoDependencies },
+    { demoResolver, demoRuntime, demoDependencies, demoVFS },
     <article className="docs-article">
       <PageActionsBar markdown={markdown ?? (() => serializeMarkdown(doc))} options={pageActions} />
       <Blocks blocks={doc.children} liveRenderer={liveRenderer} sourceRenderer={sourceRenderer} />

package/src/index.ts

@@ -16,7 +16,21 @@ export {
   DemoViewer,
   DocstreamDemoContext,
   DocstreamDemoRuntimeContext,
+  DocstreamDemoVFSContext,
+  DOCSTREAM_CLIPBOARD_TYPE,
+  CopyDemoButton,
+  createDemoVFS,
+  createDocstreamClipboard,
+  createDocstreamClipboardFromMarkdown,
   createGlobDemoResolver,
+  docstreamClipboardItems,
+  parseDocstreamClipboard,
+  peekDemoSource,
+  prefetchDemoSources,
+  readDocstreamClipboard,
+  readDocstreamClipboardItems,
+  useDemoVFS,
+  useDemoVFSFiles,
   defaultDemoMarkdown,
   inlineDemoMarkdown,
   inlineDemoNode,
@@ -41,6 +55,11 @@ export type {
   DemoRuntimeOptions,
   DemoVariant,
   DemoViewerProps,
+  DemoVFS,
+  DemoVFSChange,
+  DemoVFSEntry,
+  DocstreamClipboard,
+  DocstreamClipboardPayload,
   GlobDemoResolverOptions,
   InlineDemoRuntime,
   InlineDemoRuntimeProps,
@@ -57,6 +76,7 @@ export type {
   ReplayPreviewProps,
   ReplaySource,
 } from "./replay/ReplayPreview"
+export type { ReplayEvent } from "./replay/types"
 export { isReplayQaUrl, normalizeReplayEmbedUrl } from "./replay/url"
 export { VideoEmbed } from "./video"
 export type { VideoEmbedProps } from "./video"

package/src/replay/NativeReplay.tsx

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { EventType, Replayer } from 'rrweb';
 import type { eventWithTime } from 'rrweb';
 import { sanitizeReplayEvent } from './sanitize';
+import type { ReplayEvent } from './types';
 import 'rrweb/dist/style.css';
 
 const DEFAULT_SPEEDS = [0.5, 1, 2, 4, 8];
@@ -15,7 +16,7 @@ export default function NativeReplay({
   loop = false,
   speeds = DEFAULT_SPEEDS,
 }: {
-  events: eventWithTime[];
+  events: ReplayEvent[];
   autoplay?: boolean;
   loop?: boolean;
   speeds?: number[];
@@ -36,7 +37,10 @@ export default function NativeReplay({
   const autoplayRef = useRef(autoplay);
 
   const prepared = useMemo(
-    () => events.map((event) => sanitizeReplayEvent(event)).sort((a, b) => a.timestamp - b.timestamp),
+    () =>
+      events
+        .map((event) => sanitizeReplayEvent(event))
+        .sort((a, b) => a.timestamp - b.timestamp) as unknown as eventWithTime[],
     [events],
   );
   const hasSnapshot = prepared.some((event) => event.type === EventType.FullSnapshot);

package/src/replay/ReplayPreview.tsx

@@ -1,5 +1,5 @@
 import { Suspense, lazy, useEffect, useState } from 'react';
-import type { eventWithTime } from 'rrweb';
+import type { ReplayEvent } from './types';
 import { normalizeReplayEmbedUrl } from './url';
 
 export interface ReplayPageSource {
@@ -10,7 +10,7 @@ export interface ReplayPageSource {
 
 export interface ReplayEventsSource {
   kind: 'events';
-  events: eventWithTime[];
+  events: ReplayEvent[];
 }
 
 export interface ReplayEventsUrlSource {
@@ -21,7 +21,7 @@ export interface ReplayEventsUrlSource {
 
 export type ReplaySource =
   | string
-  | eventWithTime[]
+  | ReplayEvent[]
   | ReplayPageSource
   | ReplayEventsSource
   | ReplayEventsUrlSource;
@@ -84,7 +84,7 @@ function ReplayFrame({ source, title }: { source: ReplayPageSource; title?: stri
 // rrweb (and its stylesheet) load on first use of an event-based source.
 const LazyNativeReplay = lazy(() => import('./NativeReplay'));
 
-function NativeReplay(props: { events: eventWithTime[]; autoplay?: boolean; loop?: boolean; speeds?: number[] }) {
+function NativeReplay(props: { events: ReplayEvent[]; autoplay?: boolean; loop?: boolean; speeds?: number[] }) {
   return (
     <Suspense fallback={<div className="replay-preview__empty">Loading replay…</div>}>
       <LazyNativeReplay {...props} />
@@ -103,7 +103,7 @@ function RemoteReplay({
   loop?: boolean;
   speeds?: number[];
 }) {
-  const [events, setEvents] = useState<eventWithTime[] | null>(null);
+  const [events, setEvents] = useState<ReplayEvent[] | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
@@ -120,7 +120,7 @@ function RemoteReplay({
             ? (body as { events: unknown[] }).events
             : null;
         if (!value) throw new Error('Replay event endpoint must return an event array or { events }');
-        return value as eventWithTime[];
+        return value as ReplayEvent[];
       })
       .then(setEvents)
       .catch((reason: unknown) => {

package/src/replay/ReplayStage.tsx

@@ -0,0 +1,28 @@
+/* The eager half of the headless stage: a lazy boundary around `ReplayStageImpl`, so importing
+   `ReplayStage` never pulls in rrweb — it (and its stylesheet) load on first render. */
+import { Suspense, forwardRef, lazy } from 'react'
+import type { ReplayStageHandle, ReplayStageProps } from './stage-types'
+
+const load = () => import('./ReplayStageImpl')
+const LazyReplayStage = lazy(load)
+
+/** Start loading the rrweb player chunk ahead of the first `ReplayStage` render. */
+export function preloadReplayStage(): Promise<unknown> {
+  return load()
+}
+
+/**
+ * A headless rrweb player: the recorded page, fitted to its box, with no controls. Drive it
+ * through the ref (`play`, `pause`, `seek`, …) and the `onTimeUpdate` / `onPlayingChange`
+ * callbacks to build custom player chrome. Requires the optional `rrweb` peer.
+ */
+export const ReplayStage = forwardRef<ReplayStageHandle, ReplayStageProps>(function ReplayStage(
+  { fallback = null, ...props },
+  ref,
+) {
+  return (
+    <Suspense fallback={fallback}>
+      <LazyReplayStage ref={ref} {...props} />
+    </Suspense>
+  )
+})