stream-monaco 0.0.18 → 0.0.20

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 (18) hide show
  1. package/README.md +224 -58
  2. package/README.zh-CN.md +197 -62
  3. package/dist/{index.base-8XcpTBc-.d.cts → index.base-Bt_RWV_F.d.ts} +122 -46
  4. package/dist/{index.base-vwv4Hlby.d.ts → index.base-DMJ2aLjO.d.cts} +122 -45
  5. package/dist/index.cjs +1 -1
  6. package/dist/index.d.cts +5 -5
  7. package/dist/index.d.ts +5 -5
  8. package/dist/index.js +1 -1
  9. package/dist/index.legacy.cjs +11 -11
  10. package/dist/index.legacy.d.cts +2 -2
  11. package/dist/index.legacy.d.ts +2 -2
  12. package/dist/index.legacy.js +21 -21
  13. package/dist/preloadMonacoWorkers.shared-B2kXtXTi.cjs +6139 -0
  14. package/dist/preloadMonacoWorkers.shared-C-OxtyGI.js +6057 -0
  15. package/package.json +18 -2
  16. package/dist/chunk-CHLpw0oG.js +0 -25
  17. package/dist/preloadMonacoWorkers.shared-BNWvrH2U.cjs +0 -2976
  18. package/dist/preloadMonacoWorkers.shared-CieE-OSf.js +0 -2871
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- ## stream-monaco
1
+ # stream-monaco
2
2
 
3
3
  [![NPM version](https://img.shields.io/npm/v/stream-monaco?color=a1b858&label=)](https://www.npmjs.com/package/stream-monaco)
4
4
  [![中文版](https://img.shields.io/badge/docs-中文文档-blue)](README.zh-CN.md)
@@ -6,6 +6,8 @@
6
6
  [![Bundle size](https://img.shields.io/bundlephobia/minzip/stream-monaco)](https://bundlephobia.com/package/stream-monaco)
7
7
  [![License](https://img.shields.io/npm/l/stream-monaco)](./LICENSE)
8
8
 
9
+ Streaming Monaco Editor integration with Shiki syntax highlighting. Framework-agnostic core for Vue, React, Svelte, Solid, Preact, and Vanilla JS.
10
+
9
11
  ### Introduction
10
12
 
11
13
  stream-monaco provides a framework-agnostic core for integrating Monaco Editor with Shiki syntax highlighting, optimized for streaming updates and efficient highlighting. It works great without Vue, while also offering a Vue-friendly API and examples.
@@ -35,6 +37,7 @@ The package exports helpers around theme/highlighter for advanced use:
35
37
  - `getOrCreateHighlighter(themes, languages): Promise<Highlighter>` — get or create a highlighter (managed by internal cache). If you need to call `codeToHtml` or `setTheme` manually, use this and handle loading/errors.
36
38
 
37
39
  Note:
40
+
38
41
  - If the target theme is already included in the `themes` you passed to `useMonaco()`, calling `monaco.editor.setTheme(themeName)` is fine.
39
42
  - If you switch to a theme that was not pre-registered (e.g. dynamic theme name like `andromeeda`), prefer `await setTheme(themeName)` from `useMonaco()`. It will ensure the theme is registered, and when possible it will also try to `loadTheme` on the underlying Shiki highlighter to avoid "Theme not found, you may need to load it first" errors.
40
43
 
@@ -42,49 +45,98 @@ Config: `useMonaco()` does not auto-sync an external Shiki highlighter; if you n
42
45
 
43
46
  ### API Reference
44
47
 
45
- #### useMonaco() Returns
46
-
47
- The `useMonaco()` function returns an object with the following methods:
48
-
49
- ##### Editor Management
50
- - **`createEditor(container, code, language)`** - Create and mount Monaco editor to a container
51
- - **`createDiffEditor(container, originalCode, modifiedCode, language)`** - Create and mount Diff editor
52
- - **`cleanupEditor()`** - Destroy editor and cleanup resources
53
- - **`getEditorView()`** - Get current editor instance (IStandaloneCodeEditor | null)
54
- - **`getDiffEditorView()`** - Get current Diff editor instance (IStandaloneDiffEditor | null)
55
- - **`getEditor()`** - Get Monaco's static editor object for calling static methods
56
-
57
- ##### Code Operations
58
- - **`updateCode(newCode, language)`** - Update editor content and language (incremental update when possible)
59
- - **`appendCode(appendText, language?)`** - Append text to the end of editor (optimized for streaming)
60
- - **`getCode()`** - **Get current code from editor**
61
- - Returns `string` for normal editor
62
- - Returns `{ original: string, modified: string }` for diff editor
63
- - Returns `null` if no editor exists
64
- - **Use case**: Get the latest code after user manually edits the editor or after programmatic updates
65
-
66
- ##### Diff Editor Operations
67
- - **`updateDiff(originalCode, modifiedCode, language?)`** - Update both sides of diff editor
68
- - **`updateOriginal(newCode, language?)`** - Update only the original side
69
- - **`updateModified(newCode, language?)`** - Update only the modified side
70
- - **`appendOriginal(appendText, language?)`** - Append to original side (streaming)
71
- - **`appendModified(appendText, language?)`** - Append to modified side (streaming)
72
- - **`getDiffModels()`** - Get both diff models: `{ original, modified }`
73
-
74
- ##### Theme & Language
75
- - **`setTheme(theme)`** - Switch editor theme (returns Promise)
76
- - **`setLanguage(language)`** - Switch editor language
77
- - **`getCurrentTheme()`** - Get current theme name
78
-
79
- ##### Performance Control
80
- - **`setUpdateThrottleMs(ms)`** - Change update throttle at runtime
81
- - **`getUpdateThrottleMs()`** - Get current throttle value
48
+ #### useMonaco(options?)
49
+
50
+ ##### Parameters
51
+
52
+ | Parameter | Type | Default | Description |
53
+ | --------------------------- | ------------------------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------ |
54
+ | `MAX_HEIGHT` | `number \| string` | `500` | Maximum editor height |
55
+ | `readOnly` | `boolean` | `true` | Whether the editor is read-only |
56
+ | `themes` | `MonacoTheme[]` | `['vitesse-dark', 'vitesse-light']` | Theme list; should include at least one dark and one light theme |
57
+ | `languages` | `MonacoLanguage[]` | built-in default language list | Languages to register |
58
+ | `theme` | `string` | - | Initial theme name |
59
+ | `isCleanOnBeforeCreate` | `boolean` | `true` | Whether to dispose previously registered resources before creating a new editor |
60
+ | `onBeforeCreate` | `function` | - | Hook called before editor creation |
61
+ | `autoScrollOnUpdate` | `boolean` | `true` | Auto-scroll when content updates and the viewport is already near the bottom |
62
+ | `autoScrollInitial` | `boolean` | `true` | Whether auto-scroll starts enabled |
63
+ | `autoScrollThresholdPx` | `number` | `32` | Pixel threshold for considering the viewport "near bottom" |
64
+ | `autoScrollThresholdLines` | `number` | `2` | Line-based threshold for considering the viewport "near bottom" |
65
+ | `diffAutoScroll` | `boolean` | `true` | Whether diff auto-scroll is enabled for the modified side |
66
+ | `diffHideUnchangedRegions` | `boolean \| object` | `true` | Fold unchanged regions in diff mode; accepts Monaco `hideUnchangedRegions` config too |
67
+ | `diffLineStyle` | `'background' \| 'bar'` | `'background'` | Controls whether changed lines are emphasized more as filled blocks or review-style bars |
68
+ | `diffAppearance` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Controls the diff shell chrome appearance while token colors still follow the active theme |
69
+ | `diffUnchangedRegionStyle` | `'line-info' \| 'line-info-basic' \| 'metadata' \| 'simple'` | `'line-info'` | Controls how collapsed unchanged regions are rendered |
70
+ | `diffHunkActionsOnHover` | `boolean` | `false` | Enables split upper/lower hunk hover actions: `Revert` / `Stage` |
71
+ | `diffHunkHoverHideDelayMs` | `number` | `160` | Hide delay for hunk hover action widgets |
72
+ | `onDiffHunkAction` | `function` | - | Hunk action callback; return `false` to skip built-in edits |
73
+ | `revealDebounceMs` | `number` | `75` | Debounce for auto-reveal during streaming updates |
74
+ | `revealStrategy` | `'bottom' \| 'centerIfOutside' \| 'center'` | `'centerIfOutside'` | Reveal strategy used when auto-scrolling |
75
+ | `revealBatchOnIdleMs` | `number \| undefined` | - | Final idle-time reveal window for append-heavy scenarios |
76
+ | `updateThrottleMs` | `number` | `50` | Time-based throttle for `updateCode` |
77
+ | `diffUpdateThrottleMs` | `number` | `50` | Time-based throttle for diff streaming updates |
78
+ | `minimalEditMaxChars` | `number` | built-in constant | Fallback to `setValue` when documents are too large for minimal-edit diffing |
79
+ | `minimalEditMaxChangeRatio` | `number` | built-in constant | Fallback to `setValue` when the change ratio is too large |
80
+
81
+ `MonacoOptions` also includes Monaco's native editor and diff-editor construction options, so you can pass options such as `renderSideBySide`, `ignoreTrimWhitespace`, `originalEditable`, or `enableSplitViewResizing` directly.
82
+
83
+ ##### Returns
84
+
85
+ | Method / property | Type | Description |
86
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
87
+ | `createEditor` | `(container: HTMLElement, code: string, language: string) => Promise<MonacoEditorInstance>` | Create and mount a standalone editor |
88
+ | `createDiffEditor` | `(container: HTMLElement, original: string, modified: string, language: string) => Promise<MonacoDiffEditorInstance>` | Create and mount a diff editor |
89
+ | `cleanupEditor` | `() => void` | Dispose editor instances and cleanup resources |
90
+ | `safeClean` | `() => void` | Cancel pending update queues/RAFs without fully tearing down the integration |
91
+ | `updateCode` | `(newCode: string, codeLanguage: string) => void` | Update single-editor content and language |
92
+ | `appendCode` | `(appendText: string, codeLanguage?: string) => void` | Append to the single editor, optimized for streaming |
93
+ | `updateDiff` | `(original: string, modified: string, codeLanguage?: string) => void` | Update both sides of a diff editor |
94
+ | `updateOriginal` | `(newCode: string, codeLanguage?: string) => void` | Update only the original side |
95
+ | `updateModified` | `(newCode: string, codeLanguage?: string) => void` | Update only the modified side |
96
+ | `appendOriginal` | `(appendText: string, codeLanguage?: string) => void` | Append to the original side |
97
+ | `appendModified` | `(appendText: string, codeLanguage?: string) => void` | Append to the modified side |
98
+ | `setDiffModels` | `(models: DiffModelPair, options?: DiffModelTransitionOptions) => Promise<void>` | Swap the whole diff model pair in place; same-content swaps prewarm Monaco's diff view model and preserve view state by default |
99
+ | `setTheme` | `(theme: MonacoTheme, force?: boolean) => Promise<void>` | Switch editor theme; `force=true` re-applies even if the theme is already active |
100
+ | `refreshDiffPresentation` | `() => void` | Recompute diff chrome / unchanged overlay presentation without remounting |
101
+ | `setLanguage` | `(language: MonacoLanguage) => void` | Switch editor language |
102
+ | `getCurrentTheme` | `() => string` | Get the current theme name |
103
+ | `getEditor` | `() => typeof monaco.editor` | Get Monaco's static editor API |
104
+ | `getEditorView` | `() => MonacoEditorInstance \| null` | Get the current standalone editor instance |
105
+ | `getDiffEditorView` | `() => MonacoDiffEditorInstance \| null` | Get the current diff editor instance |
106
+ | `getDiffModels` | `() => DiffModels` | Get both diff models |
107
+ | `getMonacoInstance` | `() => typeof monaco` | Get the Monaco module instance |
108
+ | `setUpdateThrottleMs` | `(ms: number) => void` | Change `updateCode` throttling at runtime |
109
+ | `getUpdateThrottleMs` | `() => number` | Get the current `updateCode` throttle value |
110
+ | `getCode` | `() => MonacoCodeValue` | Get the latest code value from the current editor or diff editor |
111
+
112
+ ##### Exported TypeScript helpers
113
+
114
+ The package exports named types for diff integration too:
115
+
116
+ - `UseMonacoReturn`
117
+ - `MonacoOptions`
118
+ - `MonacoTheme`
119
+ - `MonacoLanguage`
120
+ - `DiffHideUnchangedRegions`
121
+ - `DiffLineStyle`
122
+ - `DiffAppearance`
123
+ - `DiffUnchangedRegionStyle`
124
+ - `DiffModels`
125
+ - `DiffModelPair`
126
+ - `DiffModelTransitionOptions`
127
+ - `DiffCodeValue`
128
+ - `MonacoCodeValue`
129
+ - `DiffHunkActionContext`
130
+
131
+ For a more complete integration walkthrough, see [Diff Integration Guide](docs/diff-integration.md).
82
132
 
83
133
  #### Diff streaming highlight tip
84
134
 
85
135
  Monaco's diff computation is async and cancels/restarts when models change. If you stream updates too frequently (e.g. per token / every frame), the diff may only finish once streaming stops, so the difference highlights appear "at the end".
86
136
 
87
- - Set `diffUpdateThrottleMs` (default: 50) to let the diff worker complete intermediate computations during streaming.
137
+ - Set `diffUpdateThrottleMs` to let the diff worker complete intermediate computations during streaming.
138
+ - The library defaults to `50ms`.
139
+ - When `diffHideUnchangedRegions` is enabled, unchanged-region folding is deferred until diff streaming goes idle to avoid collapsing and re-expanding while content is still arriving.
88
140
  - Set it to `0` to restore pure RAF batching (most responsive, but may delay diff highlights under heavy streaming).
89
141
 
90
142
  ### Install
@@ -160,12 +212,22 @@ export function MonacoEditor() {
160
212
  })
161
213
 
162
214
  useEffect(() => {
163
- if (containerRef.current)
164
- createEditor(containerRef.current, 'console.log("Hello, Monaco!")', 'typescript')
215
+ if (containerRef.current) {
216
+ createEditor(
217
+ containerRef.current,
218
+ 'console.log("Hello, Monaco!")',
219
+ 'typescript',
220
+ )
221
+ }
165
222
  return () => cleanupEditor()
166
223
  }, [])
167
224
 
168
- return <div ref={containerRef} style={{ height: 500, border: '1px solid #e0e0e0' }} />
225
+ return (
226
+ <div
227
+ ref={containerRef}
228
+ style={{ height: 500, border: '1px solid #e0e0e0' }}
229
+ />
230
+ )
169
231
  }
170
232
  ```
171
233
 
@@ -260,18 +322,10 @@ function getCurrentCode() {
260
322
  <template>
261
323
  <div>
262
324
  <div class="controls">
263
- <button @click="switchTheme('github-dark')">
264
- Dark
265
- </button>
266
- <button @click="switchTheme('github-light')">
267
- Light
268
- </button>
269
- <button @click="switchLanguage('typescript')">
270
- TypeScript
271
- </button>
272
- <button @click="switchLanguage('python')">
273
- Python
274
- </button>
325
+ <button @click="switchTheme('github-dark')">Dark</button>
326
+ <button @click="switchTheme('github-light')">Light</button>
327
+ <button @click="switchLanguage('typescript')">TypeScript</button>
328
+ <button @click="switchLanguage('python')">Python</button>
275
329
  </div>
276
330
  <div ref="editorContainer" class="editor" />
277
331
  </div>
@@ -362,6 +416,10 @@ const {
362
416
  languages: ['javascript', 'typescript'],
363
417
  readOnly: true,
364
418
  MAX_HEIGHT: 500,
419
+ // Collapse long unchanged regions automatically.
420
+ diffHideUnchangedRegions: true,
421
+ // Hover a changed hunk to show split upper/lower Revert/Stage actions.
422
+ diffHunkActionsOnHover: true,
365
423
  })
366
424
 
367
425
  const original = `export function add(a: number, b: number) {\n return a + b\n}`
@@ -378,6 +436,112 @@ onMounted(async () => {
378
436
  </template>
379
437
  ```
380
438
 
439
+ Diff UX options:
440
+
441
+ - `diffHideUnchangedRegions` (default `true`): fold unchanged ranges (can pass Monaco `hideUnchangedRegions` object).
442
+ - `diffLineStyle` (default `background`): choose the changed-line emphasis style. Use `bar` for a subtler review-style leading bar treatment.
443
+ - `diffAppearance` (default `auto`): controls the diff shell chrome; use `light` / `dark` to force the surface style while keeping token colors theme-driven.
444
+ - `diffUnchangedRegionStyle` (default `line-info`): choose collapsed unchanged-region rendering: `line-info`, `line-info-basic`, and `metadata` use compact 32px rows, while `line-info-basic` keeps the wider legacy rail and `simple` uses a tighter 28px row.
445
+ - `diffHunkActionsOnHover` (default `false`): explicitly set `true` to enable split upper/lower `Revert` and `Stage` on hunk hover.
446
+ - `onDiffHunkAction(context)` (optional): return `false` to intercept and skip built-in model edits.
447
+ - Built-in `Revert` / `Stage` only edit Monaco models locally. They do not run `git revert`, `git add`, or `git stash` unless you intercept `onDiffHunkAction` and connect your own backend flow.
448
+
449
+ Full integration guide:
450
+
451
+ - [Diff Integration Guide](docs/diff-integration.md)
452
+ - exported TS helpers include `UseMonacoReturn`, `DiffLineStyle`, `DiffAppearance`, `DiffUnchangedRegionStyle`, `DiffModels`, and `DiffHunkActionContext`
453
+
454
+ Example 1: enable unchanged folding + hover Revert/Stage
455
+
456
+ ```ts
457
+ const { createDiffEditor } = useMonaco({
458
+ themes: ['vitesse-dark', 'vitesse-light'],
459
+ languages: ['typescript'],
460
+ readOnly: true,
461
+ diffHideUnchangedRegions: {
462
+ enabled: true,
463
+ contextLineCount: 2,
464
+ minimumLineCount: 4,
465
+ revealLineCount: 2,
466
+ },
467
+ diffLineStyle: 'bar',
468
+ diffHunkActionsOnHover: true,
469
+ })
470
+
471
+ await createDiffEditor(container, original, modified, 'typescript')
472
+ ```
473
+
474
+ Example 2: fully intercept Revert/Stage and handle your own Git/stash/patch flow
475
+
476
+ ```ts
477
+ useMonaco({
478
+ diffHideUnchangedRegions: true,
479
+ diffHunkActionsOnHover: true,
480
+ onDiffHunkAction: async (ctx) => {
481
+ const {
482
+ action, // 'revert' | 'stage'
483
+ side, // 'upper' | 'lower'
484
+ lineChange,
485
+ originalModel,
486
+ modifiedModel,
487
+ } = ctx
488
+
489
+ await saveHunkAction({
490
+ action,
491
+ side,
492
+ range: lineChange,
493
+ original: originalModel.getValue(),
494
+ modified: modifiedModel.getValue(),
495
+ })
496
+
497
+ // false => skip built-in edit, fully controlled by user code
498
+ // true/undefined => continue built-in edit
499
+ return false
500
+ },
501
+ })
502
+ ```
503
+
504
+ Example 3: backend returns refreshed file contents, then the client calls `updateDiff(...)`
505
+
506
+ ```ts
507
+ const monaco = useMonaco({
508
+ diffHideUnchangedRegions: true,
509
+ diffHunkActionsOnHover: true,
510
+ onDiffHunkAction: async (ctx) => {
511
+ const response = await fetch('/api/git/hunks/apply', {
512
+ method: 'POST',
513
+ headers: { 'content-type': 'application/json' },
514
+ body: JSON.stringify({
515
+ action: ctx.action,
516
+ side: ctx.side,
517
+ range: ctx.lineChange,
518
+ original: ctx.originalModel.getValue(),
519
+ modified: ctx.modifiedModel.getValue(),
520
+ }),
521
+ })
522
+
523
+ const next = await response.json()
524
+ monaco.updateDiff(next.original, next.modified, 'typescript')
525
+ return false
526
+ },
527
+ })
528
+ ```
529
+
530
+ Important:
531
+
532
+ - Hover `Revert` is hunk-level undo, not `git revert <commit>`.
533
+ - Hover `Stage` is closer to `git add -p` / `git apply --cached`.
534
+ - If you want a stash flow, treat `onDiffHunkAction` as a patch-intent callback and hand the selected half-hunk to your backend stash or patch queue.
535
+ - If your backend returns refreshed file contents, `updateDiff(...)` is the most direct way to reflect the Git-applied result in the diff UI. The repo includes `pnpm run validate:diff-hunk-update-diff-flow` for that pattern.
536
+ - See [Diff Integration Guide](docs/diff-integration.md) for a concrete Git binding pattern.
537
+
538
+ Visual review helpers:
539
+
540
+ - `pnpm run shot:diff-ux -- background /tmp/stream-monaco-diff-reference.png pierre-reference`
541
+ Captures the Pierre-like reference scene with a fixed viewport, file chrome, and `-1 / +1` single-hunk diff. Pass an optional fourth argument such as `snazzy-light`.
542
+ - `pnpm run compare:diff-ux -- /tmp/stream-monaco-diff-reference.png background pierre-reference`
543
+ Re-captures the same scene and prints screenshot metrics such as `diffPixels`, `mismatchRatio`, and `exactMatch`. Pass an optional final theme argument to compare the exact same palette.
544
+
381
545
  ### Shiki highlighter (advanced)
382
546
 
383
547
  If you also render Shiki snippets outside Monaco:
@@ -419,7 +583,7 @@ For pure tail-append, prefer explicit `appendCode` / `appendOriginal` / `appendM
419
583
 
420
584
  ### Best practices
421
585
 
422
- 1) Performance: only load required languages
586
+ 1. Performance: only load required languages
423
587
 
424
588
  ```ts
425
589
  const { createEditor } = useMonaco({
@@ -428,7 +592,7 @@ const { createEditor } = useMonaco({
428
592
  })
429
593
  ```
430
594
 
431
- 2) Memory management: dispose on unmount
595
+ 2. Memory management: dispose on unmount
432
596
 
433
597
  ```vue
434
598
  <script setup>
@@ -443,7 +607,7 @@ onUnmounted(() => {
443
607
  </script>
444
608
  ```
445
609
 
446
- 3) Follow system theme (via your own dark state) and call `setTheme` accordingly.
610
+ 3. Follow system theme (via your own dark state) and call `setTheme` accordingly.
447
611
 
448
612
  ### Use without Vue (Vanilla)
449
613
 
@@ -523,7 +687,9 @@ If you load Monaco via CDN/AMD (e.g. `<script src=".../vs/loader.js">`), `stream
523
687
  ```ts
524
688
  import { ensureMonacoWorkersLegacy } from 'stream-monaco/legacy'
525
689
 
526
- ensureMonacoWorkersLegacy({ baseUrl: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.52.2/min/' })
690
+ ensureMonacoWorkersLegacy({
691
+ baseUrl: 'https://cdn.jsdelivr.net/npm/monaco-editor@0.52.2/min/',
692
+ })
527
693
  ```
528
694
 
529
695
  ### Development