stream-mdx 0.3.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.
- package/CHANGELOG.md +16 -6
- package/README.md +88 -86
- package/dist/worker/direct.cjs +30 -0
- package/dist/worker/direct.d.cts +1 -0
- package/dist/worker/direct.d.ts +1 -0
- package/dist/worker/direct.mjs +7 -0
- package/package.json +10 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,15 +1,25 @@
|
|
|
1
1
|
# stream-mdx
|
|
2
2
|
|
|
3
|
-
## 0.
|
|
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.
|
|
10
|
-
- @stream-mdx/
|
|
11
|
-
- @stream-mdx/worker@0.
|
|
12
|
-
- @stream-mdx/
|
|
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
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/stream-mdx)
|
|
4
|
+
[](https://stream-mdx.vercel.app/docs)
|
|
5
|
+
[](../../LICENSE)
|
|
4
6
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
33
|
+
Peer dependencies:
|
|
20
34
|
|
|
21
|
-
|
|
35
|
+
| Package | Range |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `react` | `>=18.2.0` |
|
|
38
|
+
| `react-dom` | `>=18.2.0` |
|
|
22
39
|
|
|
23
|
-
|
|
40
|
+
## Quickstart
|
|
24
41
|
|
|
25
|
-
|
|
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
|
-
###
|
|
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={{
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
78
|
+
> [!NOTE]
|
|
79
|
+
> `StreamingMarkdown` is a client component. In Next.js App Router, keep the import behind a `"use client"` boundary.
|
|
72
80
|
|
|
73
|
-
|
|
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
|
-
|
|
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
|
|
91
|
+
## Common Usage Patterns
|
|
89
92
|
|
|
90
|
-
|
|
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
|
-
|
|
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
|
-
|
|
116
|
-
|
|
117
|
-
If you're building a terminal UI, use:
|
|
99
|
+
### Append-only stream
|
|
118
100
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
## Docs
|
|
101
|
+
```tsx
|
|
102
|
+
<StreamingMarkdown stream={myAsyncIterable} worker="/workers/markdown-worker.js" caret="block" />
|
|
103
|
+
```
|
|
123
104
|
|
|
124
|
-
|
|
125
|
-
- Live demo: https://kmccleary3301.github.io/stream-mdx/demo
|
|
126
|
-
- Showcase: https://kmccleary3301.github.io/stream-mdx/showcase
|
|
127
|
-
- Manual: `docs/COMPREHENSIVE_PROJECT_DOCUMENTATION.md`
|
|
128
|
-
- API: `docs/PUBLIC_API.md`
|
|
129
|
-
- React integration: `docs/REACT_INTEGRATION_GUIDE.md`
|
|
130
|
-
- Plugins cookbook: `docs/STREAMING_MARKDOWN_PLUGINS_COOKBOOK.md`
|
|
131
|
-
- Status/architecture notes: `docs/STREAMING_MARKDOWN_V2_STATUS.md`
|
|
132
|
-
- Release checklist: `docs/STREAMING_MARKDOWN_RELEASE_CHECKLIST.md`
|
|
105
|
+
### Server / static snapshot compile
|
|
133
106
|
|
|
134
|
-
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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)
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/worker/direct.ts
|
|
21
|
+
var direct_exports = {};
|
|
22
|
+
__export(direct_exports, {
|
|
23
|
+
compileMarkdownSnapshotDirect: () => import_worker.compileMarkdownSnapshotDirect
|
|
24
|
+
});
|
|
25
|
+
module.exports = __toCommonJS(direct_exports);
|
|
26
|
+
var import_worker = require("@stream-mdx/worker");
|
|
27
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
28
|
+
0 && (module.exports = {
|
|
29
|
+
compileMarkdownSnapshotDirect
|
|
30
|
+
});
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { CompileMarkdownSnapshotDirectOptions, CompileMarkdownSnapshotDirectResult, SnapshotArtifactV1, compileMarkdownSnapshotDirect } from '@stream-mdx/worker';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { CompileMarkdownSnapshotDirectOptions, CompileMarkdownSnapshotDirectResult, SnapshotArtifactV1, compileMarkdownSnapshotDirect } from '@stream-mdx/worker';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stream-mdx",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "StreamMDX convenience package (re-exports @stream-mdx/*).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -41,6 +41,11 @@
|
|
|
41
41
|
"import": "./dist/worker/mdx-compile.mjs",
|
|
42
42
|
"require": "./dist/worker/mdx-compile.cjs"
|
|
43
43
|
},
|
|
44
|
+
"./worker/direct": {
|
|
45
|
+
"types": "./dist/worker/direct.d.ts",
|
|
46
|
+
"import": "./dist/worker/direct.mjs",
|
|
47
|
+
"require": "./dist/worker/direct.cjs"
|
|
48
|
+
},
|
|
44
49
|
"./worker/node": {
|
|
45
50
|
"types": "./dist/worker/node.d.ts",
|
|
46
51
|
"import": "./dist/worker/node.mjs",
|
|
@@ -114,10 +119,10 @@
|
|
|
114
119
|
"prepack": "npm run build"
|
|
115
120
|
},
|
|
116
121
|
"dependencies": {
|
|
117
|
-
"@stream-mdx/core": "0.
|
|
118
|
-
"@stream-mdx/plugins": "0.
|
|
119
|
-
"@stream-mdx/react": "0.
|
|
120
|
-
"@stream-mdx/worker": "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"
|
|
121
126
|
},
|
|
122
127
|
"peerDependencies": {
|
|
123
128
|
"react": ">=18.2.0",
|