@brett_lamy/docstream 1.2.4 → 1.4.0

package/README.md

@@ -13,7 +13,7 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
   Markdown vs HTML images, blank lines between blocks, list markers, fences, table layout and tag lines as written).
   Layout-only fields (`gap`, `raw`, `opening`, …) are recorded only where the source differs from the default
   output, and are ignored once they no longer fit an edited node.
-- Syntax-highlighted code blocks through `lowlight`.
+- Syntax-highlighted code blocks through `gpu-lexer`; Mermaid diagrams and KaTeX math load on first use.
 - GitBook block support for hints, tabs, expandables, steppers, embeds, content refs, columns, figures, tables, math, dividers, updates, and OpenAPI operations.
 - CSS exported as a stable package entrypoint so host apps can theme with CSS variables or shadcn-style design tokens.
 - Attribute-aware direct video embeds for muted, looping inline clips in long-form posts.
@@ -23,10 +23,31 @@ GitBook-aware markdown rendering for React applications and AI streaming surface
 ## Installation
 
 ```sh
-npm install @brett_lamy/docstream react
+pnpm add @brett_lamy/docstream
+# or: npm install @brett_lamy/docstream
+```
+
+React and React DOM are peer dependencies and must be provided by your app.
+Nothing in docstream's dependency tree runs an install script, so
+`pnpm add` succeeds with no build-script prompts (no `ERR_PNPM_IGNORED_BUILDS`).
+Heavy renderers are loaded only when a page needs them: Mermaid for
+` ```mermaid ` fences, KaTeX for math blocks, rrweb for replay event lists.
+
+Two features are opt-in, each behind its own entry and an **optional** peer
+dependency that the rest of the package never references:
+
+| Entry | Install to use it | What it adds |
+| --- | --- | --- |
+| `@brett_lamy/docstream/playground` | `@agent-wasm/core` (almost-node, an in-browser Node runtime) | Live React code fences and runnable inline `{% demo %}` files |
+| `@brett_lamy/docstream/viz` | `@brett_lamy/viz-engine` | `VizEmbed` |
+
+```sh
+pnpm add @agent-wasm/core   # only if you import @brett_lamy/docstream/playground
 ```
 
-React is a peer dependency and must be provided by your app.
+Without the playground, live code fences render as highlighted code (or through
+a `liveRenderer` you pass), and inline-file demos open on their Code view with a
+short "needs the playground runtime" note.
 
 ## Basic Setup
 
@@ -50,11 +71,12 @@ If your TypeScript app checks CSS side-effect imports, include Vite's standard e
 
 Use `GitbookStreamdown` when markdown may arrive incrementally from an AI stream. The component accepts either `markdown` or string children.
 
-Markdown-only applications can import the renderer from the `streamdown`
-subpath. This keeps optional playground integrations out of the host bundle:
+The package root's `GitbookStreamdown` is the same component as the
+`@brett_lamy/docstream/streamdown` entry. For live code fences and runnable
+inline demos, import the playground variant instead (requires `@agent-wasm/core`):
 
 ```tsx
-import { GitbookStreamdown } from "@brett_lamy/docstream/streamdown"
+import { GitbookStreamdown } from "@brett_lamy/docstream/playground" // = PlaygroundStreamdown
 ```
 
 ```tsx
@@ -367,13 +389,15 @@ what it did before 1.2: a demo, then a code block. While streaming, a block whos
 | inline files | no runtime (e.g. the `/streamdown` entry) | a one-line note; the viewer opens on Code | the inline files |
 | `src` only | no resolver | a placeholder chip | — |
 
-The package root's `GitbookStreamdown` (`PlaygroundStreamdown`) runs inline demos
-in almost-node by default. Elsewhere pass `demoRuntime`:
+`PlaygroundStreamdown` (also exported as `GitbookStreamdown` from
+`@brett_lamy/docstream/playground`) runs inline demos in almost-node by default.
+Elsewhere pass `demoRuntime` (and `liveRenderer` for live code fences):
 
 ```tsx
 import { createAlmostNodeDemoRuntime } from "@brett_lamy/docstream/playground"
 
 const demoRuntime = createAlmostNodeDemoRuntime({ workspaceOptions: { basePath: "/docs" } })
+// live code fences: import { almostNodeLiveRenderer } from "@brett_lamy/docstream/playground"
 
 <MarkdownContent markdown={page} demoResolver={demoResolver} demoRuntime={demoRuntime}
   demoDependencies={{ "@brett_lamy/ui": "^1.2.0" }} />
@@ -546,7 +570,8 @@ You can also resolve paths yourself with `resolveAsset`.
 - `resolveDemosToMarkdown(markdown, resolver, { format })`: Gives each `{% demo %}` its real files inline — renderable docstream by default, `format: "plain"` for LLM prompts (pure, async).
 - `inlineDemoMarkdown(node, files, meta)`: One demo as a pasteable block-form `{% demo %}`.
 - `preloadDemos(resolver, srcs)`: Settle resolver demos before the first render (SSR, static export).
-- `createAlmostNodeDemoRuntime(options)` / `InlineDemoPreview` / `createInlineDemoProject(files, { entry, dependencies })` (`/playground`): Run inline demo files in almost-node.
+- `createAlmostNodeDemoRuntime(options)` / `InlineDemoPreview` (`/playground`): Run inline demo files in almost-node. `createInlineDemoProject(files, { entry, dependencies })` (root and `/playground`) builds the runnable project as plain data.
+- `PlaygroundStreamdown`, `almostNodeLiveRenderer`, `ReactDemo` / `ReactCodePreview`, `createAlmostNodeWorkspace`, `useAlmostNodeServer` (`/playground` only): the almost-node playground.
 - `DocPageActions`: The "Copy page ▾" menu.
 
 ### Parser and Serializer
@@ -607,21 +632,58 @@ import { ReactDemo } from "@brett_lamy/docstream/playground"
 
 ## Bundler Notes
 
-This release ships TypeScript and TSX source through ESM exports:
+Since 1.4 the package ships compiled ES modules (ES2022, `react-jsx`) with type
+declarations and declaration maps — one file per source module in `dist/`,
+dependencies left as imports, lazy features (Mermaid, KaTeX, rrweb, the
+playground's almost-node) still behind dynamic `import()`:
 
 ```json
 {
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./dist/styles.css"
   }
 }
 ```
 
-It is validated with Vite and modern TypeScript `moduleResolution: "Bundler"`. Plain Node.js, CommonJS, or tooling that does not transpile TypeScript in dependencies may need a future precompiled JS build.
+No bundler configuration is needed: Vite pre-bundles docstream like any other
+dependency (no `optimizeDeps` entries), Next.js and webpack consume it as plain
+ESM, and your type-check reads `.d.ts` files instead of docstream's sources. The
+`@brett_lamy/docstream/vite` entry is a Node-only Vite plugin; import it from
+`vite.config.ts`, never from browser code.
+
+The TypeScript sources are published too, behind a `source` export condition, for
+monorepos that want to compile docstream from source (e.g. Vite
+`resolve.conditions: ["source", ...]` or TypeScript `customConditions`).
+
+## Migrating to 1.4
+
+No API changes. Exports now resolve to `dist/*.js` + `dist/*.d.ts` instead of
+`src/*.ts(x)`; drop any `optimizeDeps.include` / `exclude` or
+`transpilePackages` entries you added for docstream, and any `lib` / `types`
+settings you added only so your type-check could compile docstream's sources.
+
+## Migrating to 1.3
+
+1.3 moves everything that touches almost-node (`@agent-wasm/core`) out of the
+package root, so installing docstream no longer drags a WASM Node runtime and
+native compressors into every app. `@agent-wasm/core` is now an optional peer.
+
+| 1.2 (root import) | 1.3 |
+| --- | --- |
+| `GitbookStreamdown` (ran live code + inline demos in almost-node) | Root `GitbookStreamdown` renders them as code unless you pass `liveRenderer` / `demoRuntime`. For the old behaviour: `import { GitbookStreamdown } from "@brett_lamy/docstream/playground"` and install `@agent-wasm/core`. |
+| `ReactCodePreview`, `ReactDemo`, `InlineDemoPreview`, `almostNodeDemoRuntime`, `createAlmostNodeDemoRuntime`, `createAlmostNodeFilesystem`, `createAlmostNodeWorkspace` and their option/prop types | `@brett_lamy/docstream/playground` |
+| `VizEmbed`, `VizEmbedProps` | `@brett_lamy/docstream/viz`, and install `@brett_lamy/viz-engine` (now an optional peer, no longer a dependency) |
+| `Streamdown`, `StreamdownProps` (re-export of `streamdown`) | Removed: install `streamdown` and import it directly |
+
+`createInlineDemoProject`, `createReactDemoFiles` and the `AlmostNodeFile*` data
+types stay on the root (they are plain data helpers). Math blocks now show their
+TeX source for a moment while KaTeX loads.
 
 ## Related Package
 

package/dist/assets.d.ts

@@ -0,0 +1,3 @@
+export declare function setAssetBase(repo: string | null, branch: string | null, filePath: string | null): void;
+export declare function resolveAsset(src: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAMA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,QAO/F;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD"}

package/dist/assets.js

@@ -0,0 +1,20 @@
+// Resolves repo-relative image paths (e.g. "readme-assets/logo.svg") against
+// the raw.githubusercontent.com URL of the file being edited. The AST keeps
+// the original relative src; only rendering resolves it.
+let assetBase = null;
+export function setAssetBase(repo, branch, filePath) {
+    if (!repo || !branch || !filePath) {
+        assetBase = null;
+        return;
+    }
+    const dir = filePath.includes("/") ? filePath.slice(0, filePath.lastIndexOf("/") + 1) : "";
+    assetBase = `https://raw.githubusercontent.com/${repo}/${branch}/${dir}`;
+}
+export function resolveAsset(src) {
+    if (!src || /^(https?:|data:|blob:)/i.test(src))
+        return src;
+    if (!assetBase)
+        return src;
+    return assetBase + src.replace(/^\.\//, "");
+}
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,yDAAyD;AAEzD,IAAI,SAAS,GAAkB,IAAI,CAAA;AAEnC,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,MAAqB,EAAE,QAAuB;IAC9F,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,SAAS,GAAG,IAAI,CAAA;QAChB,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1F,SAAS,GAAG,qCAAqC,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAA;AAC1E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,GAAG,IAAI,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAC3D,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAA;IAC1B,OAAO,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AAC7C,CAAC"}

package/dist/demo/DemoViewer.d.ts

@@ -0,0 +1,64 @@
+import { type CSSProperties } from "react";
+import type { DemoLayout, DemoNode, DemoViewport } from "../gitbook/ast.js";
+import type { DemoFile, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types.js";
+export interface DemoViewerProps {
+    /** `<page>/<example>` id handed to the resolver. */
+    src: string;
+    /** Defaults to the nearest `demoResolver` provided to a renderer. */
+    resolver?: DemoResolver;
+    title?: string;
+    description?: string;
+    /** Preview height (px number, digits, or any CSS length). */
+    height?: number | string;
+    layout?: DemoLayout;
+    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>;
+    /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
+    className?: string;
+    /** Status shown in the header (`meta.status`). */
+    status?: string;
+    /** Full-bleed canvas without the padded surface (`meta.bleed`). */
+    bleed?: boolean;
+    /** Extra class on the preview canvas (`meta.className`). */
+    canvasClassName?: string;
+    /** Canvas inline style: an object like `meta.surface`, or CSS declarations as in the tag's `surface`. */
+    surface?: Record<string, string | number> | string;
+    /** Width of the variant switch (`meta.variantsWidth`). */
+    variantsWidth?: number | string;
+}
+/**
+ * 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 declare function preloadDemos(resolver: DemoResolver, srcs: string[]): Promise<void>;
+export declare const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead.";
+export declare function DemoViewer(props: DemoViewerProps): import("react").JSX.Element;
+/** Renders a parsed `{% demo %}` block with the resolver and runtime from context. */
+export declare function DemoBlock({ node }: {
+    node: DemoNode;
+}): import("react").JSX.Element;
+export interface DemoFullscreenProps {
+    src: string;
+    resolver?: DemoResolver;
+    variant?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** One demo filling the viewport, for a `?demo=<src>` deep link the host routes. */
+export declare function DemoFullscreen({ src, resolver: override, variant, className, style }: DemoFullscreenProps): import("react").JSX.Element;
+//# sourceMappingURL=DemoViewer.d.ts.map

package/dist/demo/DemoViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DemoViewer.d.ts","sourceRoot":"","sources":["../../src/demo/DemoViewer.tsx"],"names":[],"mappings":"AAcA,OAAO,EAQL,KAAK,aAAa,EAKnB,MAAM,OAAO,CAAA;AAId,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAUxE,OAAO,KAAK,EAAiB,QAAQ,EAAY,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAE9G,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,qEAAqE;IACrE,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAA;IACxB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;IAClB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAA;IAMlB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,yGAAyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAA;IAClD,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAChC;AAaD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBxF;AA2HD,eAAO,MAAM,eAAe,0EAA0E,CAAA;AA4VtG,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA8KhD;AAyGD,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,+BAoBrD;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,mBAAmB,+BAYzG"}