@coldsmirk/inkstone-monaco 0.11.0 → 0.12.0

package/README.md

@@ -11,7 +11,11 @@ Part of [inkstone](https://github.com/coldsmirk/inkstone). For a drop-in React c
 - **`monacoLanguages`** — the sorted catalog of every built-in language id the installed Monaco registers (with the `MonacoBuiltInLanguage` union type behind it), held to the installed `monaco-editor` by an upgrade-tripwire test. These are *ids*, not display names (`proto`, `sol`, `aes`); an unknown id silently falls back to `plaintext`.
 - **`disabledKeybindings` / `installDisabledKeybindings`** — swallow the find/replace chords and the command palette's F1 for editors that opt in. Monaco's standalone keybinding service is page-global and its rules are permanent, so the install registers each chord once per monaco module's service (duplicate copies of this package share the ledger; independent monaco bundles register their own) and scopes it with a per-capability context key created on the opted-in editor; the chord table is held to the installed `monaco-editor` by an upgrade-tripwire test.
 - **Embedded-editor fix** — works around [microsoft/monaco-editor#5177](https://github.com/microsoft/monaco-editor/issues/5177) (find-widget button tooltips landing on top of the buttons they describe) with a `width: max-content` hover-layer style tagged `data-inkstone="monaco-hover-geometry"`; deleted the moment upstream fixes it. The tooltip layer positions against the editor's container — give that container `position: relative`.
-- **`StreamingEditorController`** — stream generated text into an editor without routing every token through app state: `begin()` / `append(chunk)` / `end()` / `discard()`, `attach(editor)` / `detach(editor)` with buffered replay for late-mounting editors (and for a model swapped onto the attached editor mid-stream, including after the final chunk), `isStreaming()` for the onChange guard, and `replace(old, new, all)` for exact edits that preserve undo/cursor/folds. The stream locks every editor it touches read-only and `end()` / `discard()` restore each one's own setting — by handle, so an editor detached mid-stream is restored too; `discard()` puts every displaced document back into the model it came from, and `end()` does the same for every model except the one keeping the streamed text. Full-buffer writes and restorations preserve each model's UTF-8 BOM. Editors and models the app disposed mid-stream are skipped, never touched — teardown can race the stream without wedging it.
+- **`StreamingEditorController`** — stream generated text into an editor without routing every token through app state: `begin()` / `append(chunk)` / `end()` / `discard()`, `attach(editor)` / `detach(editor)` with buffered replay for late-mounting editors (and for a model swapped onto the attached editor mid-stream, including after the final chunk), and `isStreaming()` for the onChange guard. The stream locks every editor it touches read-only and `end()` / `discard()` restore each one's own setting — by handle, so an editor detached mid-stream is restored too; `discard()` puts every displaced document back into the model it came from, and `end()` does the same for every model except the one keeping the streamed text. Full-buffer writes and restorations preserve each model's UTF-8 BOM. Editors and models the app disposed mid-stream are skipped, never touched — teardown can race the stream without wedging it.
+- **`replaceInEditor(editor, old, new, all)`** — exact find-and-replace on an editor handle via `executeEdits`, preserving undo/cursor/folds; returns whether the edit landed (`false` = no editor / empty search / no match / a read-only editor refused it — e.g. one locked by a stream in progress), so a tool-call handler knows to fall back to a state write.
+- **`registerShikiHighlighting(monaco, highlighter)`** — wire `@coldsmirk/inkstone-core`'s shared Shiki highlighter onto a monaco module, once per distinct module: registers the canonical grammar names as Monaco languages, applies `@shikijs/monaco`'s tokenizer/themes, and repairs its `setTheme` patch so non-Shiki theme ids (vs/vs-dark, caller-defined) keep Monaco's original path. A failed registration is restored and retried on the next call.
+- **`DEFAULT_MONACO_OPTIONS`** — the inkstone construction-option baseline (no minimap, 14px/1.6 type on the shared `--inkstone-font-family-code` token, embedded-friendly find widget, tuned completion, thin scrollbars). Spread it to extend: `{ ...DEFAULT_MONACO_OPTIONS, wordWrap: "on" }`.
+- **`reconcileModelValue` / `modelValueMatches`** — the controlled-value reconcile: diff an external value against a live model (normalized to the model's EOL) and apply one minimal `applyEdits` replace that never lands on the undo stack or moves a caret outside the changed region.
 
 ## Install
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { HighlighterCore } from "@coldsmirk/inkstone-core";
 import * as monacoEditor from "monaco-editor";
 import { editor } from "monaco-editor";
 
@@ -31,6 +32,24 @@ interface MonacoHostOptions {
  * The monaco module namespace, as resolved by {@link ensureMonacoHost}.
  */
 type MonacoModule = typeof monacoEditor;
+/**
+ * Bring up the shared Monaco host: UI locale, then the monaco module, then worker routing —
+ * fully offline, no CDN, workers bundled by the consumer's bundler.
+ *
+ * Idempotent and async-safe: every caller shares one promise, and the first call wins the
+ * configuration (`globalThis.MonacoEnvironment` is a single global — per-editor configuration
+ * would clobber whichever editor mounted first).
+ *
+ * The locale catalog must be evaluated **before** the monaco module: monaco resolves
+ * `localize()` calls against `globalThis._VSCODE_NLS_MESSAGES` as its modules evaluate.
+ * Owning both dynamic imports here turns that ordering footgun into a guarantee. The
+ * corollary: never `import "monaco-editor"` statically in app code — take the instance
+ * from this promise (type-only imports are fine, they erase).
+ *
+ * A failed bring-up is not cached: the slot resets so a later call retries the imports
+ * (both are idempotent), instead of replaying one transient failure — a chunk 404 after a
+ * redeploy, a flaky network — for the rest of the session.
+ */
 declare function ensureMonacoHost(options?: MonacoHostOptions): Promise<MonacoModule>;
 //#endregion
 //#region src/keybindings.d.ts
@@ -99,6 +118,46 @@ declare const monacoLanguages: readonly MonacoBuiltInLanguage[];
  */
 type MonacoLanguage = MonacoBuiltInLanguage | (string & Record<never, never>);
 //#endregion
+//#region src/options.d.ts
+/**
+ * Baseline construction options shared by every inkstone Monaco editor: no minimap, compact
+ * code type, in-place layout tracking, widgets floated above clipping containers, completion
+ * tuned for API-assisted editing, thin scrollbars, and an embedded-friendly find widget.
+ * Spread these to extend rather than replace: `options={{ ...DEFAULT_MONACO_OPTIONS, wordWrap: "on" }}`.
+ */
+declare const DEFAULT_MONACO_OPTIONS: editor.IStandaloneEditorConstructionOptions;
+//#endregion
+//#region src/reconcile.d.ts
+/**
+ * Reconcile `externalValue` into `model` as one minimal replace, or do nothing when the
+ * documents already match. Fires the model's content-change event synchronously when it
+ * edits — callers that must not re-enter their change callback silence it around this call.
+ */
+declare function reconcileModelValue(model: editor.ITextModel, externalValue: string): void;
+/**
+ * Whether an external value already matches the model after applying its EOL convention.
+ */
+declare function modelValueMatches(model: editor.ITextModel, externalValue: string): boolean;
+//#endregion
+//#region src/replace.d.ts
+/**
+ * Exact find-and-replace on a Monaco editor, located by character offset and applied via
+ * `executeEdits` — preserving the undo stack, cursor, and fold state. Returns whether it was
+ * applied (`false` = no editor / empty search / no match, or an editor that refused the edit
+ * because it is read-only — e.g. locked by a stream in progress; the caller falls back to a
+ * state write).
+ */
+declare function replaceInEditor(target: editor.ICodeEditor | null, search: string, replaceWith: string, all: boolean): boolean;
+//#endregion
+//#region src/shiki-bridge.d.ts
+/**
+ * Register the shared Shiki highlighter's languages, themes, and tokenizer on a monaco module —
+ * once per distinct module, whichever caller gets there first. Language services are
+ * unaffected: Shiki replaces syntax highlighting only. The module is recorded only after every
+ * registration succeeds, so a transient failure can retry on a later call.
+ */
+declare function registerShikiHighlighting(monaco: MonacoModule, highlighter: HighlighterCore): void;
+//#endregion
 //#region src/streaming.d.ts
 /**
  * The editor surface the controller drives — satisfied by any Monaco code editor
@@ -219,14 +278,6 @@ declare class StreamingEditorController {
    * where flushing the partial stream into the now-current document would corrupt it.
    */
   discard(): void;
-  /**
-   * Exact find-and-replace on the attached editor, located by character offset and applied
-   * via `executeEdits` — preserving the undo stack, cursor, and fold state. Returns whether
-   * it was applied (`false` = no editor / empty search / no match, or an editor that refused
-   * the edit because it is read-only — a stream in progress; the caller falls back to a state
-   * write).
-   */
-  replace(search: string, replaceWith: string, all: boolean): boolean;
 }
 //#endregion
-export { type KeybindingTargetEditor, type MonacoBuiltInLanguage, type MonacoHostOptions, type MonacoLanguage, type MonacoModule, type MonacoUiLocale, type StreamTargetEditor, StreamingEditorController, type SwallowedKeybindings, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, monacoLanguages };
+export { DEFAULT_MONACO_OPTIONS, type KeybindingTargetEditor, type MonacoBuiltInLanguage, type MonacoHostOptions, type MonacoLanguage, type MonacoModule, type MonacoUiLocale, type StreamTargetEditor, StreamingEditorController, type SwallowedKeybindings, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };

package/dist/index.js

@@ -1,3 +1,23 @@
+import { CODE_FONT_FAMILY } from "@coldsmirk/inkstone-core";
+import { shikiToMonaco } from "@shikijs/monaco";
+//#region src/geometry-fixes.ts
+const HOVER_GEOMETRY_STYLE_SELECTOR = "style[data-inkstone=\"monaco-hover-geometry\"]";
+function installHoverGeometryFix() {
+	if (document.querySelector(HOVER_GEOMETRY_STYLE_SELECTOR)) return;
+	const style = document.createElement("style");
+	style.dataset.inkstone = "monaco-hover-geometry";
+	style.textContent = ".context-view:has(> .workbench-hover-container) { width: max-content !important; }";
+	document.head.append(style);
+}
+const SUGGEST_GEOMETRY_STYLE_SELECTOR = "style[data-inkstone=\"monaco-suggest-geometry\"]";
+function installSuggestGeometryFix() {
+	if (document.querySelector(SUGGEST_GEOMETRY_STYLE_SELECTOR)) return;
+	const style = document.createElement("style");
+	style.dataset.inkstone = "monaco-suggest-geometry";
+	style.textContent = ".monaco-editor .suggest-widget .monaco-list .monaco-list-row > .contents > .main > .right > span.readMore.codicon.codicon-suggest-more-info::before { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }";
+	document.head.append(style);
+}
+//#endregion
 //#region src/host.ts
 const HOST_PROMISE_KEY = Symbol.for("coldsmirk.inkstone.monaco.hostPromise");
 const NLS_REGISTRY_KEY = Symbol.for("coldsmirk.inkstone.monaco.nlsRegistry");
@@ -55,22 +75,6 @@ function builtinGetWorker(label) {
 	const factory = WORKER_BY_LABEL[WORKER_ALIASES[label] ?? label];
 	return factory ? factory() : editorWorker();
 }
-const HOVER_GEOMETRY_STYLE_SELECTOR = "style[data-inkstone=\"monaco-hover-geometry\"]";
-function installHoverGeometryFix() {
-	if (document.querySelector(HOVER_GEOMETRY_STYLE_SELECTOR)) return;
-	const style = document.createElement("style");
-	style.dataset.inkstone = "monaco-hover-geometry";
-	style.textContent = ".context-view:has(> .workbench-hover-container) { width: max-content !important; }";
-	document.head.append(style);
-}
-const SUGGEST_GEOMETRY_STYLE_SELECTOR = "style[data-inkstone=\"monaco-suggest-geometry\"]";
-function installSuggestGeometryFix() {
-	if (document.querySelector(SUGGEST_GEOMETRY_STYLE_SELECTOR)) return;
-	const style = document.createElement("style");
-	style.dataset.inkstone = "monaco-suggest-geometry";
-	style.textContent = ".monaco-editor .suggest-widget .monaco-list .monaco-list-row > .contents > .main > .right > span.readMore.codicon.codicon-suggest-more-info::before { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }";
-	document.head.append(style);
-}
 function ensureMonacoHost(options = {}) {
 	const registry = globalThis;
 	const existing = registry[HOST_PROMISE_KEY];
@@ -234,6 +238,134 @@ const monacoLanguages = [
 	"yaml"
 ].toSorted();
 //#endregion
+//#region src/options.ts
+const DEFAULT_MONACO_OPTIONS = {
+	find: { addExtraSpaceOnTop: false },
+	minimap: { enabled: false },
+	fontSize: 14,
+	lineHeight: 1.6,
+	fontFamily: CODE_FONT_FAMILY,
+	scrollBeyondLastLine: false,
+	automaticLayout: true,
+	renderLineHighlight: "line",
+	smoothScrolling: true,
+	padding: {
+		top: 12,
+		bottom: 12
+	},
+	fixedOverflowWidgets: true,
+	quickSuggestions: {
+		other: true,
+		comments: false,
+		strings: true
+	},
+	wordBasedSuggestions: "off",
+	tabCompletion: "on",
+	scrollbar: {
+		alwaysConsumeMouseWheel: false,
+		verticalScrollbarSize: 8,
+		horizontalScrollbarSize: 8
+	}
+};
+//#endregion
+//#region src/reconcile.ts
+function reconcileModelValue(model, externalValue) {
+	const value = normalizeModelValue(model, externalValue);
+	const current = model.getValue();
+	if (value === current) return;
+	const shorter = Math.min(current.length, value.length);
+	let from = 0;
+	while (from < shorter && current.codePointAt(from) === value.codePointAt(from)) from += 1;
+	let currentEnd = current.length;
+	let valueEnd = value.length;
+	while (currentEnd > from && valueEnd > from && current.codePointAt(currentEnd - 1) === value.codePointAt(valueEnd - 1)) {
+		currentEnd -= 1;
+		valueEnd -= 1;
+	}
+	const start = model.getPositionAt(from);
+	const end = model.getPositionAt(currentEnd);
+	model.applyEdits([{
+		range: {
+			startLineNumber: start.lineNumber,
+			startColumn: start.column,
+			endLineNumber: end.lineNumber,
+			endColumn: end.column
+		},
+		text: value.slice(from, valueEnd)
+	}]);
+}
+function modelValueMatches(model, externalValue) {
+	return model.getValue() === normalizeModelValue(model, externalValue);
+}
+function normalizeModelValue(model, externalValue) {
+	return externalValue.split(/\r\n|\r|\n/).join(model.getEOL());
+}
+//#endregion
+//#region src/replace.ts
+function replaceInEditor(target, search, replaceWith, all) {
+	const model = target?.getModel();
+	if (search === "" || !target || !model) return false;
+	const source = model.getValue();
+	const offsets = [];
+	let from = 0;
+	for (;;) {
+		const index = source.indexOf(search, from);
+		if (index === -1) break;
+		offsets.push(index);
+		if (!all) break;
+		from = index + search.length;
+	}
+	if (offsets.length === 0) return false;
+	const edits = offsets.map((offset) => {
+		const start = model.getPositionAt(offset);
+		const end = model.getPositionAt(offset + search.length);
+		return {
+			range: {
+				startLineNumber: start.lineNumber,
+				startColumn: start.column,
+				endLineNumber: end.lineNumber,
+				endColumn: end.column
+			},
+			text: replaceWith
+		};
+	});
+	return target.executeEdits("inkstone-replace", edits);
+}
+//#endregion
+//#region src/shiki-bridge.ts
+const SHIKI_REGISTRY_KEY = Symbol.for("coldsmirk.inkstone.monaco.shikiRegistry");
+function registeredModules() {
+	const host = globalThis;
+	const existing = host[SHIKI_REGISTRY_KEY];
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new WeakSet();
+	host[SHIKI_REGISTRY_KEY] = created;
+	return created;
+}
+function registerShikiHighlighting(monaco, highlighter) {
+	const registry = registeredModules();
+	if (registry.has(monaco)) return;
+	const canonical = new Set(highlighter.getLoadedLanguages().map((id) => highlighter.getLanguage(id).name));
+	const registered = new Set(monaco.languages.getLanguages().map((registeredLanguage) => registeredLanguage.id));
+	for (const lang of canonical) if (!registered.has(lang)) monaco.languages.register({ id: lang });
+	const shikiThemes = new Set(highlighter.getLoadedThemes());
+	const originalCreate = monaco.editor.create;
+	const originalSetTheme = monaco.editor.setTheme;
+	try {
+		shikiToMonaco(highlighter, monaco);
+		const setShikiTheme = monaco.editor.setTheme;
+		monaco.editor.setTheme = (themeName) => {
+			if (shikiThemes.has(themeName)) setShikiTheme.call(monaco.editor, themeName);
+			else originalSetTheme.call(monaco.editor, themeName);
+		};
+	} catch (error) {
+		monaco.editor.create = originalCreate;
+		monaco.editor.setTheme = originalSetTheme;
+		throw error;
+	}
+	registry.add(monaco);
+}
+//#endregion
 //#region src/streaming.ts
 const UTF8_BOM = "";
 var StreamingEditorController = class {
@@ -341,35 +473,6 @@ var StreamingEditorController = class {
 			this.releaseAll();
 		}
 	}
-	replace(search, replaceWith, all) {
-		const model = this.editor?.getModel();
-		if (search === "" || !this.editor || !model) return false;
-		const source = model.getValue();
-		const offsets = [];
-		let from = 0;
-		for (;;) {
-			const index = source.indexOf(search, from);
-			if (index === -1) break;
-			offsets.push(index);
-			if (!all) break;
-			from = index + search.length;
-		}
-		if (offsets.length === 0) return false;
-		const edits = offsets.map((offset) => {
-			const start = model.getPositionAt(offset);
-			const end = model.getPositionAt(offset + search.length);
-			return {
-				range: {
-					startLineNumber: start.lineNumber,
-					startColumn: start.column,
-					endLineNumber: end.lineNumber,
-					endColumn: end.column
-				},
-				text: replaceWith
-			};
-		});
-		return this.editor.executeEdits("inkstone-stream-replace", edits);
-	}
 };
 //#endregion
-export { StreamingEditorController, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, monacoLanguages };
+export { DEFAULT_MONACO_OPTIONS, StreamingEditorController, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coldsmirk/inkstone-monaco",
-  "version": "0.11.0",
-  "description": "Framework-agnostic Monaco assembly: lazy offline host (all language workers bundled, no CDN), opt-in Simplified-Chinese UI via monaco's official NLS catalog, and a streaming editor controller for AI-typed content.",
+  "version": "0.12.0",
+  "description": "Framework-agnostic Monaco assembly: lazy offline host (all language workers bundled, no CDN), opt-in Simplified-Chinese UI via monaco's official NLS catalog, a streaming editor controller for AI-typed content, and the shared Shiki highlighting bridge.",
   "keywords": [
     "monaco",
     "monaco-editor",
@@ -34,6 +34,10 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@shikijs/monaco": "^4.3.1",
+    "@coldsmirk/inkstone-core": "^0.12.0"
+  },
   "devDependencies": {
     "monaco-editor": "^0.55.1"
   },