@brett_lamy/docstream 1.4.0 → 1.6.0

package/dist/replay/stage-types.d.ts

@@ -0,0 +1,65 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { ReplayEvent } from './types.js';
+/** Imperative control over a mounted `ReplayStage`. Times are ms from the recording's start. */
+export interface ReplayStageHandle {
+    /** Play from `offset` (default: the current time; from 0 when at the end). */
+    play(offset?: number): void;
+    /** Pause, optionally jumping to `offset`. */
+    pause(offset?: number): void;
+    /** Jump to `ms`, keeping the play state. */
+    seek(ms: number): void;
+    toggle(): void;
+    getCurrentTime(): number;
+    getDuration(): number;
+    isPlaying(): boolean;
+}
+export interface ReplayStageLayout {
+    /** Recorded viewport size (px). */
+    width: number;
+    height: number;
+    /** How much the viewport is scaled to fit the stage box. */
+    scale: number;
+    /** Where the scaled viewport sits inside the box. */
+    offsetX: number;
+    offsetY: number;
+}
+export interface ReplayStageProps {
+    /** rrweb events; appended events are fed to the running player. */
+    events: ReplayEvent[];
+    autoplay?: boolean;
+    loop?: boolean;
+    /** Playback rate (1 = real time). */
+    speed?: number;
+    /** Fast-forward idle stretches longer than 5s (rrweb `skipInactive`). Default true. */
+    skipInactive?: boolean;
+    /** Where the paused player starts (ms). */
+    initialTime?: number;
+    /**
+     * `width` (default): scale down to the box width, height follows the recording's aspect.
+     * `contain`: fill the box (give it a height) and letterbox the viewport inside it.
+     */
+    fit?: 'width' | 'contain';
+    /** rrweb's own cursor. Hide it when drawing a pointer overlay. Default true. */
+    showMouse?: boolean;
+    /**
+     * Rendered over the page, in recorded-viewport coordinates (a box of `width × height` px
+     * scaled with the page). `var(--replay-scale)` holds the scale, so an overlay can
+     * counter-scale elements that should keep their on-screen size.
+     */
+    overlay?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Shown while the player chunk (rrweb) loads. */
+    fallback?: ReactNode;
+    onReady?(info: {
+        duration: number;
+        width: number;
+        height: number;
+    }): void;
+    /** Every frame while playing, and after each seek/pause. */
+    onTimeUpdate?(ms: number): void;
+    onPlayingChange?(playing: boolean): void;
+    onFinish?(): void;
+    onLayout?(layout: ReplayStageLayout): void;
+}
+//# sourceMappingURL=stage-types.d.ts.map

package/dist/replay/stage-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-types.d.ts","sourceRoot":"","sources":["../../src/replay/stage-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C,gGAAgG;AAChG,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,6CAA6C;IAC7C,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,4CAA4C;IAC5C,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,IAAI,IAAI,CAAA;IACd,cAAc,IAAI,MAAM,CAAA;IACxB,WAAW,IAAI,MAAM,CAAA;IACrB,SAAS,IAAI,OAAO,CAAA;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACzB,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,OAAO,CAAC,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IACzE,4DAA4D;IAC5D,YAAY,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,eAAe,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,IAAI,IAAI,CAAA;IACjB,QAAQ,CAAC,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAC3C"}

package/dist/replay/stage-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stage-types.js.map

package/dist/replay/stage-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-types.js","sourceRoot":"","sources":["../../src/replay/stage-types.ts"],"names":[],"mappings":""}

package/dist/replay/types.d.ts

@@ -0,0 +1,39 @@
+/** One recorded rrweb event. rrweb's own `eventWithTime` is assignable to it. */
+export interface ReplayEvent {
+    type: number;
+    data: unknown;
+    timestamp: number;
+    delay?: number;
+}
+/** rrweb `EventType`. */
+export declare const ReplayEventType: {
+    readonly DomContentLoaded: 0;
+    readonly Load: 1;
+    readonly FullSnapshot: 2;
+    readonly IncrementalSnapshot: 3;
+    readonly Meta: 4;
+    readonly Custom: 5;
+    readonly Plugin: 6;
+};
+/** rrweb `IncrementalSource` (the subset the helpers read). */
+export declare const ReplayIncrementalSource: {
+    readonly Mutation: 0;
+    readonly MouseMove: 1;
+    readonly MouseInteraction: 2;
+    readonly Scroll: 3;
+    readonly ViewportResize: 4;
+    readonly Input: 5;
+    readonly TouchMove: 6;
+    readonly Drag: 12;
+};
+/** rrweb `MouseInteractions` (the subset the helpers read). */
+export declare const ReplayMouseInteraction: {
+    readonly MouseUp: 0;
+    readonly MouseDown: 1;
+    readonly Click: 2;
+    readonly ContextMenu: 3;
+    readonly DblClick: 4;
+    readonly TouchStart: 7;
+    readonly TouchEnd: 9;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/replay/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/replay/types.ts"],"names":[],"mappings":"AAKA,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,yBAAyB;AACzB,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAA;AAEV,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB;;;;;;;;;CAS1B,CAAA;AAEV,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB;;;;;;;;CAQzB,CAAA"}

package/dist/replay/types.js

@@ -0,0 +1,36 @@
+/* rrweb's event shape and the numeric enums the replay helpers read, declared locally so the
+   eager replay modules (and their published declarations) never import rrweb. rrweb is an
+   optional peer: only the lazily loaded player chunk (`ReplayStageImpl` / `NativeReplay`)
+   imports it, so hosts that never play native events don't need it installed. */
+/** rrweb `EventType`. */
+export const ReplayEventType = {
+    DomContentLoaded: 0,
+    Load: 1,
+    FullSnapshot: 2,
+    IncrementalSnapshot: 3,
+    Meta: 4,
+    Custom: 5,
+    Plugin: 6,
+};
+/** rrweb `IncrementalSource` (the subset the helpers read). */
+export const ReplayIncrementalSource = {
+    Mutation: 0,
+    MouseMove: 1,
+    MouseInteraction: 2,
+    Scroll: 3,
+    ViewportResize: 4,
+    Input: 5,
+    TouchMove: 6,
+    Drag: 12,
+};
+/** rrweb `MouseInteractions` (the subset the helpers read). */
+export const ReplayMouseInteraction = {
+    MouseUp: 0,
+    MouseDown: 1,
+    Click: 2,
+    ContextMenu: 3,
+    DblClick: 4,
+    TouchStart: 7,
+    TouchEnd: 9,
+};
+//# sourceMappingURL=types.js.map

package/dist/replay/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/replay/types.ts"],"names":[],"mappings":"AAAA;;;iFAGiF;AAUjF,yBAAyB;AACzB,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,gBAAgB,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC;IACP,YAAY,EAAE,CAAC;IACf,mBAAmB,EAAE,CAAC;IACtB,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;CACD,CAAA;AAEV,+DAA+D;AAC/D,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;IACZ,gBAAgB,EAAE,CAAC;IACnB,MAAM,EAAE,CAAC;IACT,cAAc,EAAE,CAAC;IACjB,KAAK,EAAE,CAAC;IACR,SAAS,EAAE,CAAC;IACZ,IAAI,EAAE,EAAE;CACA,CAAA;AAEV,+DAA+D;AAC/D,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO,EAAE,CAAC;IACV,SAAS,EAAE,CAAC;IACZ,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;CACH,CAAA"}

package/dist/streamdown.d.ts

@@ -15,5 +15,5 @@ export interface GitbookStreamdownProps extends DocRenderOptions {
     isStreaming?: boolean;
     markdown?: string;
 }
-export declare function GitbookStreamdown({ children, className, isAnimating, isStreaming, markdown, liveRenderer, sourceRenderer, demoResolver, demoRuntime, demoDependencies, pageActions, }: GitbookStreamdownProps): import("react").JSX.Element;
+export declare function GitbookStreamdown({ children, className, isAnimating, isStreaming, markdown, liveRenderer, sourceRenderer, demoResolver, demoRuntime, demoDependencies, demoVFS, pageActions, }: GitbookStreamdownProps): import("react").JSX.Element;
 //# sourceMappingURL=streamdown.d.ts.map

package/dist/streamdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streamdown.d.ts","sourceRoot":"","sources":["../src/streamdown.tsx"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAKjI,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACnG,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACtG,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAA;AACtH,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAE1G,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAClC,cAAc,CAAC,EAAE,uBAAuB,CAAA;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,WAAW,GACZ,EAAE,sBAAsB,+BA0BxB"}
+{"version":3,"file":"streamdown.d.ts","sourceRoot":"","sources":["../src/streamdown.tsx"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAA;AAKjI,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACnG,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACtG,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAA;AACtH,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAE1G,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAClC,cAAc,CAAC,EAAE,uBAAuB,CAAA;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,WAAW,GACZ,EAAE,sBAAsB,+BA2BxB"}

package/dist/streamdown.js

@@ -7,9 +7,9 @@ import { parseMarkdown, trimPartialInlineToken } from "./gitbook/parse.js";
 export { CitationSources, DocstreamRefContext, InlineReference } from "./docs/reference.js";
 export { DocPageActions } from "./docs/PageActions.js";
 export { DocstreamDemoContext, DocstreamDemoRuntimeContext, DemoFullscreen, DemoViewer } from "./demo/index.js";
-export function GitbookStreamdown({ children, className, isAnimating, isStreaming = false, markdown, liveRenderer, sourceRenderer, demoResolver, demoRuntime, demoDependencies, pageActions, }) {
+export function GitbookStreamdown({ children, className, isAnimating, isStreaming = false, markdown, liveRenderer, sourceRenderer, demoResolver, demoRuntime, demoDependencies, demoVFS, pageActions, }) {
     const content = markdown ?? children ?? "";
     const gitbookDoc = useMemo(() => parseMarkdown(isStreaming ? trimPartialInlineToken(content) : content), [content, isStreaming]);
-    return (_jsx("div", { "aria-busy": isAnimating ?? isStreaming, className: className, "data-docstream": "", "data-streaming": isStreaming ? "" : undefined, children: _jsx(DocsRenderer, { doc: gitbookDoc, markdown: content, liveRenderer: liveRenderer, sourceRenderer: sourceRenderer, demoResolver: demoResolver, demoRuntime: demoRuntime, demoDependencies: demoDependencies, pageActions: isStreaming ? false : pageActions }) }));
+    return (_jsx("div", { "aria-busy": isAnimating ?? isStreaming, className: className, "data-docstream": "", "data-streaming": isStreaming ? "" : undefined, children: _jsx(DocsRenderer, { doc: gitbookDoc, markdown: content, liveRenderer: liveRenderer, sourceRenderer: sourceRenderer, demoResolver: demoResolver, demoRuntime: demoRuntime, demoDependencies: demoDependencies, demoVFS: demoVFS, pageActions: isStreaming ? false : pageActions }) }));
 }
 //# sourceMappingURL=streamdown.js.map

package/dist/streamdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"streamdown.js","sourceRoot":"","sources":["../src/streamdown.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAiF,MAAM,qBAAqB,CAAA;AACjI,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAEvE,uEAAuE;AACvE,yDAAyD;AACzD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGnD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AActG,MAAM,UAAU,iBAAiB,CAAC,EAChC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAW,GAAG,KAAK,EACnB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,WAAW,GACY;IACvB,MAAM,OAAO,GAAG,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAA;IAC1C,MAAM,UAAU,GAAG,OAAO,CACxB,GAAG,EAAE,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAC5E,CAAC,OAAO,EAAE,WAAW,CAAC,CACvB,CAAA;IAED,OAAO,CACL,2BACa,WAAW,IAAI,WAAW,EACrC,SAAS,EAAE,SAAS,oBACL,EAAE,oBACD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,YAE5C,KAAC,YAAY,IACX,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,OAAO,EACjB,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,EAC9B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,GAC9C,GACE,CACP,CAAA;AACH,CAAC"}
+{"version":3,"file":"streamdown.js","sourceRoot":"","sources":["../src/streamdown.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,YAAY,EAAiF,MAAM,qBAAqB,CAAA;AACjI,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAEvE,uEAAuE;AACvE,yDAAyD;AACzD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGnD,OAAO,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AActG,MAAM,UAAU,iBAAiB,CAAC,EAChC,QAAQ,EACR,SAAS,EACT,WAAW,EACX,WAAW,GAAG,KAAK,EACnB,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,OAAO,EACP,WAAW,GACY;IACvB,MAAM,OAAO,GAAG,QAAQ,IAAI,QAAQ,IAAI,EAAE,CAAA;IAC1C,MAAM,UAAU,GAAG,OAAO,CACxB,GAAG,EAAE,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAC5E,CAAC,OAAO,EAAE,WAAW,CAAC,CACvB,CAAA;IAED,OAAO,CACL,2BACa,WAAW,IAAI,WAAW,EACrC,SAAS,EAAE,SAAS,oBACL,EAAE,oBACD,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,YAE5C,KAAC,YAAY,IACX,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,OAAO,EACjB,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,EAC9B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,gBAAgB,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,GAC9C,GACE,CACP,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "GitBook-aware readonly markdown and AI stream renderer.",
   "publishConfig": {
     "access": "public"
@@ -112,7 +112,7 @@
     "katex": "^0.18.5",
     "lucide-react": "^1.17.0",
     "mermaid": "^11.15.0",
-    "rrweb": "2.0.0-alpha.20",
+    "react-aria": "^3.52.1",
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
@@ -120,6 +120,7 @@
     "@brett_lamy/viz-engine": ">=0.2.0",
     "react": ">=18",
     "react-dom": ">=18",
+    "rrweb": "2.0.0-alpha.20",
     "vite": ">=5"
   },
   "peerDependenciesMeta": {
@@ -131,6 +132,9 @@
     },
     "vite": {
       "optional": true
+    },
+    "rrweb": {
+      "optional": true
     }
   },
   "repository": {
@@ -142,6 +146,9 @@
     "@brett_lamy/viz-engine": "^0.2.1",
     "@types/node": "^24.0.0",
     "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.7",
+    "happy-dom": "^20.14.5",
+    "rrweb": "2.0.0-alpha.20",
     "typescript": "^5.5.4",
     "vite": "^7.0.0",
     "vitest": "^3.2.4"

package/src/demo/DemoViewer.tsx

@@ -24,7 +24,7 @@ import {
   type KeyboardEvent as ReactKeyboardEvent,
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
-  type MutableRefObject,
+  type Ref,
 } from "react"
 import { motion, useReducedMotion } from "framer-motion"
 import { ExternalLink, FileCode2, Folder, Maximize2, Monitor, Smartphone, Tablet, X } from "lucide-react"
@@ -36,8 +36,10 @@ import { HighlightedCode } from "../docs/HighlightedCode"
 import { CopyButton } from "../docs/copy"
 import { PillTabs, Segmented, rovingKeyDown } from "../docs/controls"
 import { useDemoResolver, useDemoRuntime } from "./context"
+import { createDocstreamClipboard, type DemoSourceSnapshot, type DocstreamClipboard } from "./clipboard"
+import { CopyDemoButton } from "./copy-demo"
 import { languageForPath } from "./glob"
-import { inlineDemoMarkdown } from "./markdown"
+import { useDemoVFSContext, useDemoVFSEntry, type DemoVFS } from "./vfs"
 import { cssToSurface, surfaceStyle, surfaceToCss } from "./surface"
 import type { DemoComponent, DemoFile, DemoMeta, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types"
 
@@ -67,6 +69,11 @@ export interface DemoViewerProps {
   runtime?: InlineDemoRuntime
   /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
   dependencies?: Record<string, string>
+  /**
+   * Demo files held in memory by `src` (pasted demos). Used, like inline files, when the block
+   * has none of its own and no resolver knows `src`. Defaults to the VFS in context (`demoVFS`).
+   */
+  vfs?: DemoVFS
   /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
   className?: string
   /*
@@ -120,6 +127,32 @@ export async function preloadDemos(resolver: DemoResolver, srcs: string[]): Prom
   )
 }
 
+/**
+ * Fetch demos' meta and files (not their components) into the viewer's cache, so
+ * `peekDemoSource` can answer synchronously — e.g. when a copy event needs a demo's files.
+ */
+export async function prefetchDemoSources(resolver: DemoResolver, srcs: string[]): Promise<void> {
+  const cache = cacheFor(resolver)
+  const settle = async (key: string, run: () => Promise<unknown>) => {
+    if (cache.get(key)?.status === "ready") return
+    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))]))
+}
+
+/** A demo's files (and meta) if the resolver has already delivered them (viewer, `preloadDemos`, `prefetchDemoSources`). */
+export function peekDemoSource(resolver: DemoResolver, src: string): DemoSourceSnapshot | undefined {
+  const cache = settled.get(resolver)
+  const files = cache?.get(`files:${src}`)
+  if (files?.status !== "ready" || !(files.value as DemoFile[]).length) return undefined
+  const meta = cache?.get(`meta:${src}`)
+  return { files: files.value as DemoFile[], ...(meta?.status === "ready" && meta.value ? { meta: meta.value as DemoMeta } : {}) }
+}
+
 /** 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
@@ -165,10 +198,11 @@ const useComponent = (resolver: DemoResolver | undefined, src: string, active: b
 
 /** True once the element has come within `margin` of the viewport (stays true). */
 function useNearViewport<T extends Element>(margin = "400px 0px") {
-  const ref = useRef<T | null>(null)
+  // A callback ref, so an element that appears later (a VFS demo arriving) is observed too.
+  const [el, setEl] = useState<T | null>(null)
+  const ref = useMemo(() => (node: T | null) => setEl(node), [])
   const [near, setNear] = useState(false)
   useEffect(() => {
-    const el = ref.current
     if (!el || near) return
     if (typeof IntersectionObserver === "undefined") {
       setNear(true)
@@ -179,7 +213,7 @@ function useNearViewport<T extends Element>(margin = "400px 0px") {
     }, { rootMargin: margin })
     observer.observe(el)
     return () => observer.disconnect()
-  }, [near, margin])
+  }, [el, near, margin])
   return [ref, near] as const
 }
 
@@ -594,7 +628,12 @@ export function DemoViewer(props: DemoViewerProps) {
   const runtimeOptions = useDemoRuntime({ runtime: props.runtime, dependencies: props.dependencies })
   const { src } = props
   const [ref, near] = useNearViewport<HTMLElement>()
-  const inlineFiles = useMemo(() => orderInline(props.files, props.entry), [props.files, props.entry])
+  const vfs = useDemoVFSContext(props.vfs)
+  // Pasted demos: files held by the VFS stand in for inline files the block doesn't carry.
+  const vfsEntry = useDemoVFSEntry(vfs, props.files?.length ? "" : src)
+  const ownFiles = props.files?.length ? props.files : vfsEntry?.files
+  const ownEntry = props.files?.length ? props.entry : props.entry ?? vfsEntry?.meta?.entry
+  const inlineFiles = useMemo(() => orderInline(ownFiles, ownEntry), [ownFiles, ownEntry])
 
   // A resolver is consulted unless the block brings its own files and the resolver
   // says (via `list()`) that it does not know this src.
@@ -607,7 +646,7 @@ export function DemoViewer(props: DemoViewerProps) {
   const mode: "resolver" | "inline" | "none" =
     tryResolver && !(inlineFiles && resolverFailed) ? "resolver" : inlineFiles ? "inline" : "none"
 
-  const metaValue = mode === "resolver" && meta.status === "ready" ? meta.value : undefined
+  const metaValue = mode === "resolver" ? (meta.status === "ready" ? meta.value : undefined) : mode === "inline" && !props.files?.length ? vfsEntry?.meta : 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
@@ -669,7 +708,12 @@ export function DemoViewer(props: DemoViewerProps) {
     ...(props.surface ? { surface: typeof props.surface === "string" ? props.surface : surfaceToCss(props.surface) } : {}),
     ...(props.variantsWidth !== undefined && props.variantsWidth !== "" ? { variantsWidth: String(props.variantsWidth) } : {}),
   }
-  const copyDemo = () => inlineDemoMarkdown(node, fileList ?? [], metaValue)
+  // "Copy demo": the exact block (src-only stays src-only; inline files stay inline) plus its files.
+  const copyDemo = (): DocstreamClipboard | null => {
+    if (!fileList?.length) return null
+    const exact: DemoNode = props.files?.length ? { ...node, ...(props.entry ? { entry: props.entry } : {}), files: props.files.map((f) => ({ ...f })) } : node
+    return createDocstreamClipboard({ type: "doc", children: [exact] }, { lookup: () => ({ files: fileList, ...(metaValue ? { meta: metaValue } : {}) }) })
+  }
 
   const dialog = (
     <FullscreenDialog
@@ -702,6 +746,7 @@ export function DemoViewer(props: DemoViewerProps) {
             <span className="docs-demo-spacer" />
             <StatusBadge status={status} />
             <VariantSwitch variants={variants} value={variant} onChange={setVariant} title={title} width={variantsWidth} />
+            {fileList?.length ? <CopyDemoButton clipboard={copyDemo} className="docs-demo-icon-btn" /> : null}
             {runnable ? <FullscreenButton onOpen={() => setFullscreen(true)} title={title} /> : null}
           </header>
           {runnable ? (
@@ -766,7 +811,7 @@ export function DemoViewer(props: DemoViewerProps) {
 }
 
 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>
+  rootRef: Ref<HTMLElement>
   className: string
   baseId: string
   mode: "resolver" | "inline"
@@ -787,7 +832,7 @@ function MultiFileViewer({ rootRef, className, baseId, mode, src, title, descrip
   variantsWidth: number | string | undefined
   href: string | undefined
   onFullscreen: () => void
-  copyDemo: (() => string) | undefined
+  copyDemo: (() => DocstreamClipboard | null) | undefined
   dialog: ReactNode
 }) {
   const runnable = preview.kind !== "unavailable"
@@ -835,7 +880,7 @@ function MultiFileViewer({ rootRef, className, baseId, mode, src, title, descrip
               ))}
             </div>
           ) : null}
-          {copyDemo ? <CopyButton text={copyDemo} label="Copy demo as Markdown" className="docs-demo-icon-btn" /> : null}
+          {copyDemo ? <CopyDemoButton clipboard={copyDemo} className="docs-demo-icon-btn" /> : null}
           {runnable ? <FullscreenButton onOpen={onFullscreen} title={title} /> : null}
           <NewTabLink href={href} title={title} />
         </div>

package/src/demo/clipboard.ts

@@ -0,0 +1,228 @@
+/* Copy / paste of docstream content that contains `{% demo %}` blocks.
+
+   A copy writes one clipboard item with three representations (react-aria `DragItem` shape,
+   so `useClipboard` / `useDrag` can write it; `writeDocstreamClipboard` writes it to a raw
+   `DataTransfer`):
+
+   - `text/plain` and `text/markdown`: renderable docstream Markdown — every demo carries its
+     files inline (`{% demo … %}` + titled fences + `{% enddemo %}`), resolver files included,
+     so pasting it anywhere (a docs page, an LLM, another editor) still renders;
+   - `application/x-docstream+json` (`DOCSTREAM_CLIPBOARD_TYPE`): a `DocstreamClipboardPayload`
+     — the exact Markdown (src-only demos stay src-only), plus every demo's files and meta by
+     `src`, so a docstream editor can restore the structure and register the files in its
+     `DemoVFS`. */
+import type { DemoNode, DocumentNode } from "../gitbook/ast"
+import { parseMarkdown } from "../gitbook/parse"
+import { serializeMarkdown } from "../gitbook/serialize"
+import { inlineDemoNode, toInlineFiles } from "./markdown"
+import { cssToSurface } from "./surface"
+import type { DemoFile, DemoMeta } from "./types"
+
+export const DOCSTREAM_CLIPBOARD_TYPE = "application/x-docstream+json"
+
+export interface DocstreamClipboardPayload {
+  /** Always `"docstream"`. */
+  kind: "docstream"
+  version: 1
+  /** The copied content as docstream Markdown, structure exactly as it was. */
+  markdown: string
+  /** Every demo's files by `src` (inline files, or the resolver's for src-only demos). */
+  files: Record<string, DemoFile[]>
+  /** `meta.json`-style defaults by `src` (the resolver's meta, else the tag's attributes). */
+  meta: Record<string, DemoMeta>
+}
+
+/** A demo's files (and meta) as the copying side knows them. */
+export interface DemoSourceSnapshot {
+  files: DemoFile[]
+  meta?: DemoMeta
+}
+
+export interface DocstreamClipboard {
+  payload: DocstreamClipboardPayload
+  /** The renderable Markdown (demos inlined) written as `text/plain` / `text/markdown`. */
+  text: string
+}
+
+/** A react-aria `DragItem`: one representation per MIME type. */
+export type DocstreamClipboardItem = Record<string, string>
+
+/** Every `{% demo %}` node in a document (inside tabs, hints, lists …), in document order. */
+export function collectDemoNodes(doc: DocumentNode): DemoNode[] {
+  const out: DemoNode[] = []
+  const walk = (value: unknown) => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item)
+      return
+    }
+    if (!value || typeof value !== "object") return
+    const node = value as { type?: unknown }
+    if (node.type === "demo") {
+      out.push(value as DemoNode)
+      return
+    }
+    for (const child of Object.values(value)) if (child && typeof child === "object") walk(child)
+  }
+  walk(doc.children)
+  return out
+}
+
+/** A copy of `doc` with every demo node replaced by `map(node)`. */
+export function mapDemoNodes(doc: DocumentNode, map: (node: DemoNode) => DemoNode): DocumentNode {
+  const walk = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(walk)
+    if (!value || typeof value !== "object") return value
+    if ((value as { type?: unknown }).type === "demo") return map(value as DemoNode)
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value)) out[k] = v && typeof v === "object" ? walk(v) : v
+    return out
+  }
+  return walk(doc) as DocumentNode
+}
+
+/** A demo tag's attributes as `meta.json`-style defaults. */
+export function demoNodeMeta(node: DemoNode): DemoMeta {
+  const meta: DemoMeta = {}
+  if (node.title) meta.title = node.title
+  if (node.description) meta.description = node.description
+  if (node.height) meta.height = /^\d+(?:\.\d+)?$/.test(node.height) ? Number(node.height) : node.height
+  if (node.layout) meta.layout = node.layout
+  if (node.variants?.length) meta.variants = node.variants.map((v) => ({ ...v }))
+  if (node.entry) meta.entry = node.entry
+  if (node.status) meta.status = node.status
+  if (node.bleed !== undefined) meta.bleed = node.bleed
+  if (node.className) meta.className = node.className
+  if (node.surface) meta.surface = cssToSurface(node.surface)
+  if (node.variantsWidth) meta.variantsWidth = node.variantsWidth
+  return meta
+}
+
+export interface CreateDocstreamClipboardOptions {
+  /**
+   * Files (and meta) for demos that don't carry theirs inline — the host resolver's, read
+   * synchronously (see `peekDemoSource`), or a `DemoVFS`'s. Demos it can't answer for stay
+   * src-only in both representations.
+   */
+  lookup?: (node: DemoNode) => DemoSourceSnapshot | undefined
+  /** Markdown serializer. Defaults to docstream's `serializeMarkdown`. */
+  serialize?: (doc: DocumentNode) => string
+}
+
+/** The clipboard representations of a document (or a selection of one). */
+export function createDocstreamClipboard(doc: DocumentNode, options: CreateDocstreamClipboardOptions = {}): DocstreamClipboard {
+  const serialize = options.serialize ?? serializeMarkdown
+  const files: Record<string, DemoFile[]> = {}
+  const meta: Record<string, DemoMeta> = {}
+  const inlined = mapDemoNodes(doc, (node) => {
+    if (node.files?.length) {
+      if (node.src) {
+        files[node.src] = toInlineFiles(node.files)
+        const tagMeta = demoNodeMeta(node)
+        if (Object.keys(tagMeta).length) meta[node.src] = tagMeta
+      }
+      return node
+    }
+    const found = node.src ? options.lookup?.(node) : undefined
+    if (!found?.files.length) return node
+    files[node.src] = toInlineFiles(found.files)
+    const merged = { ...found.meta, ...demoNodeMeta(node) }
+    if (Object.keys(merged).length) meta[node.src] = merged
+    return inlineDemoNode(node, found.files, found.meta)
+  })
+  return {
+    payload: { kind: "docstream", version: 1, markdown: serialize(doc), files, meta },
+    text: serialize(inlined),
+  }
+}
+
+/** Parse the Markdown of a copied docstream selection (or a single demo). */
+export function createDocstreamClipboardFromMarkdown(markdown: string, options: CreateDocstreamClipboardOptions = {}): DocstreamClipboard {
+  const clip = createDocstreamClipboard(parseMarkdown(markdown), options)
+  // Keep the author's bytes for the exact representation.
+  return { ...clip, payload: { ...clip.payload, markdown } }
+}
+
+/** The clipboard as react-aria `DragItem`s (for `useClipboard`'s `getItems` / `useDrag`). */
+export function docstreamClipboardItems(clip: DocstreamClipboard): DocstreamClipboardItem[] {
+  return [
+    {
+      "text/plain": clip.text,
+      "text/markdown": clip.text,
+      [DOCSTREAM_CLIPBOARD_TYPE]: JSON.stringify(clip.payload),
+    },
+  ]
+}
+
+/** Writes the representations straight onto a `DataTransfer` (a copy / cut / dragstart event's). */
+export function writeDocstreamClipboard(data: Pick<DataTransfer, "setData">, clip: DocstreamClipboard): void {
+  for (const [type, value] of Object.entries(docstreamClipboardItems(clip)[0])) data.setData(type, value)
+}
+
+/** Validates a `DOCSTREAM_CLIPBOARD_TYPE` string. */
+export function parseDocstreamClipboard(json: string | null | undefined): DocstreamClipboardPayload | null {
+  if (!json) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(json)
+  } catch {
+    return null
+  }
+  if (!raw || typeof raw !== "object") return null
+  const value = raw as Partial<DocstreamClipboardPayload>
+  if (value.kind !== "docstream" || typeof value.markdown !== "string") return null
+  const files: Record<string, DemoFile[]> = {}
+  for (const [src, list] of Object.entries(value.files && typeof value.files === "object" ? value.files : {})) {
+    if (!Array.isArray(list)) continue
+    const clean = list
+      .filter((f): f is DemoFile => !!f && typeof f === "object" && typeof f.path === "string" && typeof f.content === "string")
+      .map((f) => ({ path: f.path, content: f.content, ...(typeof f.language === "string" && f.language ? { language: f.language } : {}) }))
+    if (clean.length) files[src] = clean
+  }
+  const meta: Record<string, DemoMeta> = {}
+  for (const [src, m] of Object.entries(value.meta && typeof value.meta === "object" ? value.meta : {})) {
+    if (m && typeof m === "object") meta[src] = m as DemoMeta
+  }
+  return { kind: "docstream", version: 1, markdown: value.markdown, files, meta }
+}
+
+function hasType(types: ArrayLike<string> | null | undefined, type: string) {
+  return !!types && Array.prototype.indexOf.call(types, type) >= 0
+}
+
+/** True when a `DataTransfer` carries a docstream payload. */
+export function hasDocstreamClipboard(data: Pick<DataTransfer, "types"> | null | undefined): boolean {
+  return hasType(data?.types, DOCSTREAM_CLIPBOARD_TYPE)
+}
+
+/** The docstream payload on a paste / drop `DataTransfer`, if any. */
+export function readDocstreamClipboard(data: Pick<DataTransfer, "getData" | "types"> | null | undefined): DocstreamClipboardPayload | null {
+  if (!data || !hasDocstreamClipboard(data)) return null
+  return parseDocstreamClipboard(data.getData(DOCSTREAM_CLIPBOARD_TYPE))
+}
+
+/** Minimal react-aria `DropItem` shape (text items). */
+export interface DocstreamDropItem {
+  kind: string
+  types?: Set<string>
+  getText?: (type: string) => Promise<string>
+}
+
+/** The docstream payload among react-aria `DropItem`s (`useClipboard`'s `onPaste`, `useDrop`). */
+export async function readDocstreamClipboardItems(items: readonly DocstreamDropItem[]): Promise<DocstreamClipboardPayload | null> {
+  for (const item of items) {
+    if (item.kind === "text" && item.types?.has(DOCSTREAM_CLIPBOARD_TYPE) && item.getText) {
+      const payload = parseDocstreamClipboard(await item.getText(DOCSTREAM_CLIPBOARD_TYPE))
+      if (payload) return payload
+    }
+  }
+  return null
+}
+
+/**
+ * A payload for Markdown that arrived without one (only `text/plain` / `text/markdown`):
+ * inline-file demos give their files by `src`.
+ */
+export function docstreamPayloadFromMarkdown(markdown: string): DocstreamClipboardPayload {
+  const { payload } = createDocstreamClipboardFromMarkdown(markdown)
+  return payload
+}

package/src/demo/context.ts

@@ -27,3 +27,10 @@ export function useDemoRuntime(override?: DemoRuntimeOptions): DemoRuntimeOption
       : undefined,
   }
 }
+
+/**
+ * Demo files held in memory by `src` (a `DemoVFS`), e.g. demos pasted from another page or
+ * editor. `DemoViewer` falls back to them when a block has no inline files; the host
+ * resolver still wins when it knows `src`. Provided by renderers' / editors' `demoVFS`.
+ */
+export const DocstreamDemoVFSContext = createContext<import("./vfs").DemoVFS | undefined>(undefined)