stream-mdx 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +16 -6
  2. package/README.md +88 -86
  3. package/dist/core.d.cts +1 -1
  4. package/dist/core.d.ts +1 -1
  5. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -1,15 +1,25 @@
1
1
  # stream-mdx
2
2
 
3
- ## 0.1.1
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Promote the current hardening and product-surface tranche as `0.5.0`.
8
+
9
+ This release rolls up:
10
+
11
+ - renderer/store correctness hardening
12
+ - seeded smoke and scheduler-parity release discipline
13
+ - benchmark methodology and comparison cleanup
14
+ - docs, showcase, and TUI/product surface maturation
4
15
 
5
16
  ### Patch Changes
6
17
 
7
- - Refine streaming scheduling and list layout, add worker append batching/debug state support, and refresh docs/README examples.
8
18
  - Updated dependencies
9
- - @stream-mdx/core@0.1.1
10
- - @stream-mdx/react@0.1.1
11
- - @stream-mdx/worker@0.1.1
12
- - @stream-mdx/plugins@0.1.1
19
+ - @stream-mdx/core@0.5.0
20
+ - @stream-mdx/plugins@0.5.0
21
+ - @stream-mdx/worker@0.5.0
22
+ - @stream-mdx/react@0.5.0
13
23
 
14
24
  ## 0.1.0
15
25
 
package/README.md CHANGED
@@ -1,14 +1,28 @@
1
1
  # `stream-mdx`
2
2
 
3
- High-performance streaming Markdown/MDX renderer for React with a worker-first pipeline, incremental patching, and backpressure guardrails.
3
+ [![npm version](https://img.shields.io/npm/v/stream-mdx?logo=npm&color=CB3837)](https://www.npmjs.com/package/stream-mdx)
4
+ [![Docs](https://img.shields.io/badge/docs-stream--mdx.vercel.app-000000?logo=vercel)](https://stream-mdx.vercel.app/docs)
5
+ [![License](https://img.shields.io/github/license/kmccleary3301/stream-mdx?color=2ea44f)](../../LICENSE)
4
6
 
5
- This is the **convenience** package:
7
+ `stream-mdx` is the convenience package for StreamMDX. If you want the standard React/browser integration without thinking about the scoped package layout, start here.
6
8
 
7
- - `stream-mdx` re-exports the main React API from `@stream-mdx/react`
8
- - `stream-mdx/{core,react,worker,plugins}` proxy to the scoped packages
9
- - `stream-mdx/plugins/*` proxies the common plugin entrypoints (helpful for pnpm users)
9
+ **Primary links**: [Root README](../../README.md) · [Docs site](https://stream-mdx.vercel.app/docs) · [Public API](../../docs/PUBLIC_API.md) · [React integration](../../docs/REACT_INTEGRATION_GUIDE.md)
10
10
 
11
- If you want maximum modularity (or you’re publishing your own library), install the scoped packages directly. Otherwise, start here.
11
+ ## What This Package Includes
12
+
13
+ `stream-mdx` re-exports the commonly used parts of the stack under stable app-facing import paths:
14
+
15
+ | Import | Resolves to | Use when |
16
+ | --- | --- | --- |
17
+ | `stream-mdx` | main React surface | You want `<StreamingMarkdown />` and the default types. |
18
+ | `stream-mdx/react` | `@stream-mdx/react` | You want the React surface explicitly. |
19
+ | `stream-mdx/worker` | `@stream-mdx/worker` | You need worker helpers or hosted worker utilities. |
20
+ | `stream-mdx/worker/node` | `@stream-mdx/worker/node` | You want Node `worker_threads` snapshot compilation. |
21
+ | `stream-mdx/worker/direct` | `@stream-mdx/worker/direct` | You need direct compile helpers in runtimes without `worker_threads`. |
22
+ | `stream-mdx/core` | `@stream-mdx/core` | You need lower-level types or perf helpers. |
23
+ | `stream-mdx/plugins/*` | `@stream-mdx/plugins/*` | You are customizing the worker/plugin layer. |
24
+
25
+ If you are building a framework integration or need absolute control over dependency edges, install the scoped packages directly instead.
12
26
 
13
27
  ## Install
14
28
 
@@ -16,22 +30,23 @@ If you want maximum modularity (or you’re publishing your own library), instal
16
30
  npm install stream-mdx
17
31
  ```
18
32
 
19
- ## Quickstart
33
+ Peer dependencies:
20
34
 
21
- ### 1) Copy the hosted worker bundle
35
+ | Package | Range |
36
+ | --- | --- |
37
+ | `react` | `>=18.2.0` |
38
+ | `react-dom` | `>=18.2.0` |
22
39
 
23
- In production you should host the worker bundle from static assets (stricter CSP, no `blob:`).
40
+ ## Quickstart
24
41
 
25
- After installing, copy the worker into your app:
42
+ ### 1. Host the worker bundle
26
43
 
27
44
  ```bash
28
45
  mkdir -p public/workers
29
46
  cp node_modules/@stream-mdx/worker/dist/hosted/markdown-worker.js public/workers/markdown-worker.js
30
47
  ```
31
48
 
32
- ### Next.js (App Router)
33
-
34
- `StreamingMarkdown` is a **client component**. Import it behind a `"use client"` boundary.
49
+ ### 2. Render Markdown in a client component
35
50
 
36
51
  ```tsx
37
52
  "use client";
@@ -43,100 +58,87 @@ export function Demo({ text }: { text: string }) {
43
58
  <StreamingMarkdown
44
59
  text={text}
45
60
  worker="/workers/markdown-worker.js"
46
- features={{ html: true, tables: true, math: true, mdx: true }}
61
+ features={{ tables: true, html: true, math: true, mdx: true, footnotes: true }}
47
62
  mdxCompileMode="worker"
63
+ prewarmLangs={["tsx", "bash", "json"]}
48
64
  />
49
65
  );
50
66
  }
51
67
  ```
52
68
 
53
- If you import `StreamingMarkdown` from a server component, you’ll typically see `useRef is not a function`. Fix by moving the import behind a `"use client"` boundary.
54
-
55
- ### Vite React
69
+ ### 3. Optional addon registration
56
70
 
57
71
  ```tsx
72
+ import { MermaidBlock } from "@stream-mdx/mermaid";
58
73
  import { StreamingMarkdown } from "stream-mdx";
59
74
 
60
- export default function App() {
61
- return (
62
- <StreamingMarkdown
63
- text="## Hello\n\nStreaming **markdown**"
64
- worker="/workers/markdown-worker.js"
65
- features={{ html: true, tables: true, math: true }}
66
- />
67
- );
68
- }
75
+ <StreamingMarkdown text={content} worker="/workers/markdown-worker.js" components={{ mermaid: MermaidBlock }} />;
69
76
  ```
70
77
 
71
- ## Configuration at a glance
78
+ > [!NOTE]
79
+ > `StreamingMarkdown` is a client component. In Next.js App Router, keep the import behind a `"use client"` boundary.
72
80
 
73
- - `text` / `stream`: provide a full string or an append-only `AsyncIterable<string>`.
74
- - `worker`: a `Worker`, `URL`, URL string, or factory; defaults to the built-in worker strategy and falls back to `/workers/markdown-worker.js`.
75
- - `features`: `{ html?, tables?, mdx?, math?, footnotes?, callouts? }`.
76
- - `mdxCompileMode`: `"worker"` (no server) or `"server"` (requires an endpoint; see docs).
77
- - `components` / `inlineComponents`: override block + inline renders (wrap code/math without losing incremental rendering).
78
- - `tableElements`: override table tags (e.g. Shadcn table wrappers).
79
- - `htmlElements`: override HTML tag renders (when HTML is enabled).
80
- - `mdxComponents`: MDX component registry (when MDX compilation is enabled).
81
- - `caret`: show a streaming caret while blocks are still in-flight.
82
- - `linkSafety`: intercept link clicks and require confirmation before navigation.
83
- - `deferHeavyBlocks`: defer heavy blocks (e.g. Mermaid) until in view/idle.
84
- - `scheduling`: patch scheduler/backpressure knobs.
81
+ ## Package-Specific Guidance
85
82
 
86
- ## Plugins
83
+ | Question | Recommendation |
84
+ | --- | --- |
85
+ | I just want the normal React integration. | Use `stream-mdx`. |
86
+ | I need the worker/runtime pieces separately. | Use `@stream-mdx/worker` and `@stream-mdx/core`. |
87
+ | I am building a server/static compilation pipeline. | Use `stream-mdx/worker/node` plus `@stream-mdx/react/server`. |
88
+ | I need plugin customization or a custom worker bundle. | Drop to `@stream-mdx/plugins/*`. |
89
+ | I am building a TUI or protocol consumer. | Use `@stream-mdx/protocol` and `@stream-mdx/tui`. |
87
90
 
88
- Common entrypoints (convenience package):
91
+ ## Common Usage Patterns
89
92
 
90
- - `stream-mdx/plugins/document`
91
- - `stream-mdx/plugins/tables`
92
- - `stream-mdx/plugins/html`
93
- - `stream-mdx/plugins/math`
94
- - `stream-mdx/plugins/mdx`
95
-
96
- Scoped equivalents:
97
-
98
- - `@stream-mdx/plugins/document` (etc)
99
-
100
- ## Addons
101
-
102
- - `@stream-mdx/mermaid` (optional Mermaid diagram renderer)
103
- - `@stream-mdx/theme-tailwind` (optional Tailwind theme CSS)
104
- - `@stream-mdx/tui` + `@stream-mdx/protocol` (terminal/CLI helpers)
105
-
106
- Example:
93
+ ### Simple static string
107
94
 
108
95
  ```tsx
109
- import { StreamingMarkdown } from "stream-mdx";
110
- import { MermaidBlock } from "@stream-mdx/mermaid";
111
-
112
- <StreamingMarkdown text={content} components={{ mermaid: MermaidBlock }} />;
96
+ <StreamingMarkdown text="# Hello\n\nStreaming **markdown**" worker="/workers/markdown-worker.js" />
113
97
  ```
114
98
 
115
- ## Terminal / TUI
116
-
117
- If you're building a terminal UI, use:
99
+ ### Append-only stream
118
100
 
119
- - `@stream-mdx/protocol` for stable event/type contracts
120
- - `@stream-mdx/tui` for NDJSON helpers and a snapshot store for applying patches
121
-
122
- ## Docs
101
+ ```tsx
102
+ <StreamingMarkdown stream={myAsyncIterable} worker="/workers/markdown-worker.js" caret="block" />
103
+ ```
123
104
 
124
- - Docs site: https://kmccleary3301.github.io/stream-mdx/
125
- - Live demo: https://kmccleary3301.github.io/stream-mdx/demo
126
- - Showcase: https://kmccleary3301.github.io/stream-mdx/showcase
127
- - Manual: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/COMPREHENSIVE_PROJECT_DOCUMENTATION.md
128
- - Public API: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/PUBLIC_API.md
129
- - React integration: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/REACT_INTEGRATION_GUIDE.md
130
- - Plugins cookbook: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md
131
- - Status/architecture: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/STREAMING_MARKDOWN_V2_STATUS.md
132
- - TUI/CLI protocol guide: https://github.com/kmccleary3301/stream-mdx/blob/main/docs/CLI_USAGE.md
105
+ ### Server / static snapshot compile
133
106
 
134
- ## Package map
107
+ ```tsx
108
+ import { ComponentRegistry, MarkdownBlocksRenderer } from "@stream-mdx/react/server";
109
+ import { compileMarkdownSnapshot } from "stream-mdx/worker/node";
110
+
111
+ const { blocks } = await compileMarkdownSnapshot({
112
+ text: "# Precompiled page\n\nThis was rendered from a snapshot.",
113
+ init: {
114
+ docPlugins: { tables: true, html: true, mdx: true, math: true, footnotes: true },
115
+ mdx: { compileMode: "server" },
116
+ },
117
+ });
118
+
119
+ return <MarkdownBlocksRenderer blocks={blocks} componentRegistry={new ComponentRegistry()} />;
120
+ ```
135
121
 
136
- - `stream-mdx` – React surface (`@stream-mdx/react`)
137
- - `stream-mdx/react` – React renderer + types
138
- - `stream-mdx/worker` – worker client + default worker helpers
139
- - `stream-mdx/plugins` – plugin registry + helpers
140
- - `stream-mdx/plugins/*` – common plugin entrypoints
141
- - `stream-mdx/core` – structured-clone-safe types + perf utilities
142
- - `@stream-mdx/theme-tailwind` – optional Tailwind theme CSS
122
+ ## Related Packages
123
+
124
+ | Package | Role |
125
+ | --- | --- |
126
+ | [`@stream-mdx/react`](../markdown-v2-react/README.md) | React renderer and server helpers |
127
+ | [`@stream-mdx/worker`](../markdown-v2-worker/README.md) | Worker utilities, hosted worker, Node helpers |
128
+ | [`@stream-mdx/core`](../markdown-v2-core/README.md) | Core types, snapshots, perf helpers |
129
+ | [`@stream-mdx/plugins`](../markdown-v2-plugins/README.md) | Worker/plugin primitives |
130
+ | [`@stream-mdx/mermaid`](../markdown-v2-mermaid/README.md) | Mermaid addon |
131
+ | [`@stream-mdx/protocol`](../markdown-v2-protocol/README.md) | Protocol contracts |
132
+ | [`@stream-mdx/tui`](../markdown-v2-tui/README.md) | TUI helpers |
133
+ | [`@stream-mdx/theme-tailwind`](../theme-tailwind/README.md) | Optional theme CSS |
134
+
135
+ ## Documentation
136
+
137
+ - [`../../docs/GETTING_STARTED.md`](../../docs/GETTING_STARTED.md)
138
+ - [`../../docs/PUBLIC_API.md`](../../docs/PUBLIC_API.md)
139
+ - [`../../docs/REACT_INTEGRATION_GUIDE.md`](../../docs/REACT_INTEGRATION_GUIDE.md)
140
+ - [`../../docs/TUI_GUIDE.md`](../../docs/TUI_GUIDE.md)
141
+ - [`../../docs/TUI_MINIMAL_EXAMPLE.md`](../../docs/TUI_MINIMAL_EXAMPLE.md)
142
+ - [`../../docs/SECURITY_MODEL.md`](../../docs/SECURITY_MODEL.md)
143
+ - [`../../docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md`](../../docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md)
144
+ - [`../../docs/BASELINE_UPDATE_POLICY.md`](../../docs/BASELINE_UPDATE_POLICY.md)
package/dist/core.d.cts CHANGED
@@ -11,6 +11,6 @@ import '@stream-mdx/plugins/math';
11
11
  import '@stream-mdx/plugins/mdx';
12
12
  import '@stream-mdx/plugins/registry';
13
13
  import '@stream-mdx/plugins/tables';
14
- import '@stream-mdx/plugins/math/renderer';
15
14
  import '@stream-mdx/worker/mdx-compile';
16
15
  import '@stream-mdx/worker/node';
16
+ import '@stream-mdx/plugins/math/renderer';
package/dist/core.d.ts CHANGED
@@ -11,6 +11,6 @@ import '@stream-mdx/plugins/math';
11
11
  import '@stream-mdx/plugins/mdx';
12
12
  import '@stream-mdx/plugins/registry';
13
13
  import '@stream-mdx/plugins/tables';
14
- import '@stream-mdx/plugins/math/renderer';
15
14
  import '@stream-mdx/worker/mdx-compile';
16
15
  import '@stream-mdx/worker/node';
16
+ import '@stream-mdx/plugins/math/renderer';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stream-mdx",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "StreamMDX convenience package (re-exports @stream-mdx/*).",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -119,10 +119,10 @@
119
119
  "prepack": "npm run build"
120
120
  },
121
121
  "dependencies": {
122
- "@stream-mdx/core": "0.4.0",
123
- "@stream-mdx/plugins": "0.4.0",
124
- "@stream-mdx/react": "0.4.0",
125
- "@stream-mdx/worker": "0.4.0"
122
+ "@stream-mdx/core": "0.5.0",
123
+ "@stream-mdx/plugins": "0.5.0",
124
+ "@stream-mdx/react": "0.5.0",
125
+ "@stream-mdx/worker": "0.5.0"
126
126
  },
127
127
  "peerDependencies": {
128
128
  "react": ">=18.2.0",