@coldsmirk/inkstone-monaco 0.17.1 → 0.19.0

package/README.md

@@ -16,6 +16,7 @@ Part of [inkstone](https://github.com/coldsmirk/inkstone). For a drop-in React c
 - **`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.
+- **`installDesignTokens()`** — defines the VS Code design tokens monaco-editor 0.56's chrome reads and the standalone editor never does ([microsoft/monaco-editor#5408](https://github.com/microsoft/monaco-editor/issues/5408)): `--vscode-cornerRadius-{small,medium,large,xLarge}` and `--vscode-shadow-{md,lg,xl}`, on `.monaco-editor` (the context menu's shadow root and a host's `overflowWidgetsDomNode` inherit them). Without them the context menu, completion, hover, and find widgets ship square and shadowless. Each resolves through the host's `--inkstone-radius-*` / `--inkstone-shadow-*` token first (see `@coldsmirk/inkstone-core`), then a fallback scale in the spirit of 0.55's look. `ensureMonacoHost` installs it; idempotent.
 - **`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.
 

package/dist/index.d.ts

@@ -51,6 +51,56 @@ type MonacoModule = typeof monacoEditor;
  */
 declare function ensureMonacoHost(options?: MonacoHostOptions): Promise<MonacoModule>;
 //#endregion
+//#region src/auto-imports.d.ts
+/**
+ * Options for {@link installAutoImportCompletions}.
+ */
+interface AutoImportCompletionOptions {
+  /**
+   * The module specifiers admitted as auto-import sources for this model, or undefined /
+   * empty to offer none. Consulted on every completion request, so the answer may follow the
+   * app's active editing surface.
+   */
+  admittedSources: (model: monacoEditor.editor.ITextModel) => readonly string[] | undefined;
+}
+/**
+ * Registers the auto-import completion provider on `monaco`'s `typescript` language id (the
+ * id also carries `.tsx` models — the model path decides JSX-ness). Additive beside the
+ * stock provider: entries are only unimported module exports from sources the app admits,
+ * labeled with their module, sorted after in-scope symbols by the language service's own
+ * `sortText`, and resolving one computes the import statement (merging into an existing
+ * import from the same module) as `additionalTextEdits`. A routed worker without the bundled
+ * subclass (a `getWorker` override) is detected on the first answer and the install disarms
+ * silently. Install once per app; repeated calls return the first install's disposable.
+ */
+declare function installAutoImportCompletions(monaco: MonacoModule, options: AutoImportCompletionOptions): monacoEditor.IDisposable;
+//#endregion
+//#region src/design-tokens.d.ts
+/**
+ * Define the VS Code design tokens Monaco's chrome reads but the standalone editor lacks —
+ * corner radii and widget shadows — on `.monaco-editor`, resolved through the host's
+ * `--inkstone-radius-*` / `--inkstone-shadow-*` tokens with inkstone's fallbacks. Installed by
+ * `ensureMonacoHost`; idempotent, so a host that brings monaco up on its own can call it too.
+ */
+declare function installDesignTokens(): void;
+//#endregion
+//#region src/hover-dead-band.d.ts
+/**
+ * The slice of a standalone editor the install touches — structural, so the install is
+ * testable without evaluating the monaco module (which jsdom cannot do).
+ */
+interface HoverDeadBandTargetEditor {
+  getContribution: (id: string) => unknown;
+}
+/**
+ * Keeps `editorInstance`'s content hover reachable by a slowly moving pointer: overrides the
+ * controller's on-the-widget test so the widget's pointer-active frame counts as the widget
+ * (see the file comment for the dead band this compensates). Installed by `<MonacoEditor>`
+ * on every editor; a monaco whose hover controller no longer matches the pinned shape is
+ * left untouched. Dispose to restore the stock test.
+ */
+declare function installHoverDeadBandFix(editorInstance: HoverDeadBandTargetEditor): monacoEditor.IDisposable;
+//#endregion
 //#region src/jsx-tag-closing.d.ts
 /**
  * The slice of a text model the install reads — a structural type, so the install is testable
@@ -325,4 +375,4 @@ declare class StreamingEditorController {
   discard(): void;
 }
 //#endregion
-export { DEFAULT_MONACO_OPTIONS, type JsxTagClosingTargetEditor, type JsxTagClosingTargetModel, type KeybindingTargetEditor, type MonacoBuiltInLanguage, type MonacoHostOptions, type MonacoLanguage, type MonacoModule, type MonacoUiLocale, type StreamTargetEditor, StreamingEditorController, type SwallowedKeybindings, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, installJsxTagClosing, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };
+export { type AutoImportCompletionOptions, DEFAULT_MONACO_OPTIONS, type HoverDeadBandTargetEditor, type JsxTagClosingTargetEditor, type JsxTagClosingTargetModel, type KeybindingTargetEditor, type MonacoBuiltInLanguage, type MonacoHostOptions, type MonacoLanguage, type MonacoModule, type MonacoUiLocale, type StreamTargetEditor, StreamingEditorController, type SwallowedKeybindings, disabledKeybindings, ensureMonacoHost, installAutoImportCompletions, installDesignTokens, installDisabledKeybindings, installHoverDeadBandFix, installJsxTagClosing, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };

package/dist/index.js

@@ -1,5 +1,147 @@
-import { CODE_FONT_FAMILY } from "@coldsmirk/inkstone-core";
+import { CODE_FONT_FAMILY, inkstoneRadius, inkstoneShadow } from "@coldsmirk/inkstone-core";
 import { shikiToMonaco } from "@shikijs/monaco";
+//#region src/auto-imports.ts
+const MISSING_LOOKUP_REJECTION$1 = "Missing requestHandler or method: getAutoImportCompletionsAtPosition";
+const MODE_BOOTING_REJECTIONS$1 = /* @__PURE__ */ new Set(["TypeScript not registered!", "JavaScript not registered!"]);
+const ENTRY_KINDS = {
+	function: "Function",
+	method: "Function",
+	class: "Class",
+	interface: "Interface",
+	module: "Module",
+	type: "Variable",
+	alias: "Variable"
+};
+function itemKind(monaco, kind) {
+	return monaco.languages.CompletionItemKind[ENTRY_KINDS[kind] ?? "Variable"];
+}
+function partsText(parts) {
+	return (parts ?? []).map((part) => part.text).join("");
+}
+const LEDGER_KEY = Symbol.for("coldsmirk.inkstone.autoImportCompletions");
+function ledgerOf() {
+	const holder = globalThis;
+	let ledger = holder[LEDGER_KEY];
+	if (!ledger) {
+		ledger = /* @__PURE__ */ new WeakMap();
+		holder[LEDGER_KEY] = ledger;
+	}
+	return ledger;
+}
+function classify(error) {
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+	if (message === MISSING_LOOKUP_REJECTION$1) return "disarm";
+	return MODE_BOOTING_REJECTIONS$1.has(message) ? "booting" : "failure";
+}
+function installAutoImportCompletions(monaco, options) {
+	const ledger = ledgerOf();
+	const installed = ledger.get(monaco);
+	if (installed) return installed;
+	let lookupUnsupported = false;
+	const disposable = monaco.languages.registerCompletionItemProvider("typescript", {
+		async provideCompletionItems(model, position) {
+			const sources = options.admittedSources(model);
+			if (lookupUnsupported || !sources || sources.length === 0) return { suggestions: [] };
+			const wordInfo = model.getWordUntilPosition(position);
+			const offset = model.getOffsetAt(position);
+			try {
+				const workerFor = await monaco.typescript.getTypeScriptWorker();
+				if (model.isDisposed()) return { suggestions: [] };
+				const info = await (await workerFor(model.uri)).getAutoImportCompletionsAtPosition(model.uri.toString(), offset, sources);
+				if (!info || model.isDisposed()) return { suggestions: [] };
+				const range = {
+					startLineNumber: position.lineNumber,
+					startColumn: wordInfo.startColumn,
+					endLineNumber: position.lineNumber,
+					endColumn: wordInfo.endColumn
+				};
+				return {
+					suggestions: info.entries.map((entry) => {
+						return {
+							label: {
+								label: entry.name,
+								description: entry.source
+							},
+							kind: itemKind(monaco, entry.kind),
+							insertText: entry.insertText ?? entry.name,
+							filterText: entry.name,
+							sortText: entry.sortText,
+							range,
+							uri: model.uri,
+							offset,
+							entry
+						};
+					}),
+					incomplete: info.isIncomplete
+				};
+			} catch (error) {
+				const verdict = classify(error);
+				if (verdict === "disarm") lookupUnsupported = true;
+				else if (verdict === "failure") console.error("inkstone: auto-import completion lookup failed", error);
+				return { suggestions: [] };
+			}
+		},
+		async resolveCompletionItem(item) {
+			const myItem = item;
+			if (!myItem.entry) return item;
+			try {
+				const details = await (await (await monaco.typescript.getTypeScriptWorker())(myItem.uri)).getAutoImportCompletionEntryDetails(myItem.uri.toString(), myItem.offset, myItem.entry.name, myItem.entry.source, myItem.entry.data);
+				const model = monaco.editor.getModel(myItem.uri);
+				if (!details || !model || model.isDisposed()) return item;
+				const fileName = myItem.uri.toString();
+				const additionalTextEdits = (details.codeActions ?? []).flatMap((action) => action.changes).filter((change) => change.fileName === fileName).flatMap((change) => change.textChanges).map((textChange) => {
+					const start = model.getPositionAt(textChange.span.start);
+					const end = model.getPositionAt(textChange.span.start + textChange.span.length);
+					return {
+						range: {
+							startLineNumber: start.lineNumber,
+							startColumn: start.column,
+							endLineNumber: end.lineNumber,
+							endColumn: end.column
+						},
+						text: textChange.newText
+					};
+				});
+				const documentation = partsText(details.documentation);
+				return {
+					...myItem,
+					additionalTextEdits,
+					detail: details.codeActions?.[0]?.description ?? partsText(details.displayParts),
+					...documentation && { documentation: { value: documentation } }
+				};
+			} catch (error) {
+				if (classify(error) === "failure") console.error("inkstone: auto-import details lookup failed", error);
+				return item;
+			}
+		}
+	});
+	const install = { dispose: () => {
+		ledger.delete(monaco);
+		disposable.dispose();
+	} };
+	ledger.set(monaco, install);
+	return install;
+}
+//#endregion
+//#region src/design-tokens.ts
+const DESIGN_TOKENS_STYLE_SELECTOR = "style[data-inkstone=\"monaco-design-tokens\"]";
+const DESIGN_TOKENS = [
+	`--vscode-cornerRadius-small: ${inkstoneRadius("small", "2px")}`,
+	`--vscode-cornerRadius-medium: ${inkstoneRadius("medium", "4px")}`,
+	`--vscode-cornerRadius-large: ${inkstoneRadius("large", "6px")}`,
+	`--vscode-cornerRadius-xLarge: ${inkstoneRadius("xlarge", "8px")}`,
+	`--vscode-shadow-md: ${inkstoneShadow("medium", "0 1px 4px var(--vscode-widget-shadow)")}`,
+	`--vscode-shadow-lg: ${inkstoneShadow("large", "0 2px 8px var(--vscode-widget-shadow)")}`,
+	`--vscode-shadow-xl: ${inkstoneShadow("xlarge", "0 4px 16px var(--vscode-widget-shadow)")}`
+];
+function installDesignTokens() {
+	if (document.querySelector(DESIGN_TOKENS_STYLE_SELECTOR)) return;
+	const style = document.createElement("style");
+	style.dataset.inkstone = "monaco-design-tokens";
+	style.textContent = `.monaco-editor { ${DESIGN_TOKENS.join("; ")}; }`;
+	document.head.append(style);
+}
+//#endregion
 //#region src/geometry-fixes.ts
 const HOVER_GEOMETRY_STYLE_SELECTOR = "style[data-inkstone=\"monaco-hover-geometry\"]";
 function installHoverGeometryFix() {
@@ -84,6 +226,7 @@ function ensureMonacoHost(options = {}) {
 		let restoreNls;
 		try {
 			if (locale === "zh-cn") restoreNls = await applyZhCnCatalog();
+			installDesignTokens();
 			installHoverGeometryFix();
 			installSuggestGeometryFix();
 			const monaco = await import("monaco-editor");
@@ -101,6 +244,29 @@ function ensureMonacoHost(options = {}) {
 	return attempt;
 }
 //#endregion
+//#region src/hover-dead-band.ts
+const CONTENT_HOVER_CONTRIBUTION = "editor.contrib.contentHover";
+const TOLERANCE = 4;
+function isContentHoverController(candidate) {
+	return typeof candidate === "object" && candidate !== null && typeof candidate._isMouseOnContentHoverWidget === "function";
+}
+function installHoverDeadBandFix(editorInstance) {
+	const controller = editorInstance.getContribution(CONTENT_HOVER_CONTRIBUTION);
+	if (!isContentHoverController(controller) || Object.hasOwn(controller, "_isMouseOnContentHoverWidget")) return { dispose: () => {} };
+	controller._isMouseOnContentHoverWidget = (mouseEvent) => {
+		const dom = controller._contentWidget?.getDomNode();
+		if (!dom) return false;
+		const rect = dom.getBoundingClientRect();
+		const view = dom.ownerDocument.defaultView;
+		const x = mouseEvent.event.posx - (view?.scrollX ?? 0);
+		const y = mouseEvent.event.posy - (view?.scrollY ?? 0);
+		return rect.width > 0 && rect.height > 0 && x >= rect.left - TOLERANCE && x <= rect.right + TOLERANCE && y >= rect.top - TOLERANCE && y <= rect.bottom + TOLERANCE;
+	};
+	return { dispose: () => {
+		delete controller._isMouseOnContentHoverWidget;
+	} };
+}
+//#endregion
 //#region src/jsx-tag-closing.ts
 const MISSING_LOOKUP_REJECTION = "Missing requestHandler or method: getJsxClosingTagAtPosition";
 const MODE_BOOTING_REJECTIONS = /* @__PURE__ */ new Set(["TypeScript not registered!", "JavaScript not registered!"]);
@@ -520,4 +686,4 @@ var StreamingEditorController = class {
 	}
 };
 //#endregion
-export { DEFAULT_MONACO_OPTIONS, StreamingEditorController, disabledKeybindings, ensureMonacoHost, installDisabledKeybindings, installJsxTagClosing, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };
+export { DEFAULT_MONACO_OPTIONS, StreamingEditorController, disabledKeybindings, ensureMonacoHost, installAutoImportCompletions, installDesignTokens, installDisabledKeybindings, installHoverDeadBandFix, installJsxTagClosing, modelValueMatches, monacoLanguages, reconcileModelValue, registerShikiHighlighting, replaceInEditor };

package/dist/workers/ts.worker.js

@@ -2,16 +2,65 @@
 // See editor.worker.js for why this indirection exists.
 //
 // Unlike its siblings this entry is not a bare re-export: it subclasses the stock worker to
-// expose `getJsxClosingTagAtPosition` — the language-service call behind auto-closing JSX
-// tags (`installJsxTagClosing` is the editor-side half) — which monaco's own worker never
-// proxied. The host's worker proxy forwards any method name, so the subclass only has to
-// exist here; nothing on the main thread changes.
+// expose language-service calls monaco's own worker never proxied — the host's worker proxy
+// forwards any method name, so the subclass only has to exist here; nothing on the main
+// thread changes for it to be callable:
+//  - `getJsxClosingTagAtPosition`, behind auto-closing JSX tags (`installJsxTagClosing` is
+//    the editor-side half);
+//  - the auto-import completion pair, behind `installAutoImportCompletions`: the stock worker
+//    calls `getCompletionsAtPosition` without preferences, so the service never surfaces
+//    unimported module exports, and its details call drops `source`/`data`, so the import
+//    text edit (`codeActions`) can never be requested. These two pass the module-export
+//    preferences through and return the entries verbatim.
 import { initialize, TypeScriptWorker } from "monaco-editor/language/typescript/ts.worker.js";
 
+// The preferences that make the language service surface unimported module exports and, on
+// the details call, compute their import edits. `allowIncompleteCompletions` lets it bound a
+// broad enumeration by the typed prefix and say so (`isIncomplete` → monaco re-queries).
+const AUTO_IMPORT_PREFERENCES = {
+  includeCompletionsForModuleExports: true,
+  includeCompletionsWithInsertText: true,
+  allowIncompleteCompletions: true
+};
+
 class JsxTypeScriptWorker extends TypeScriptWorker {
   getJsxClosingTagAtPosition(fileName, position) {
     return this.getLanguageService().getJsxClosingTagAtPosition(fileName, position);
   }
+
+  getAutoImportCompletionsAtPosition(fileName, position, admittedSources) {
+    const info = this.getLanguageService().getCompletionsAtPosition(fileName, position, AUTO_IMPORT_PREFERENCES);
+
+    if (!info) {
+      return;
+    }
+
+    // Only entries importable from an admitted specifier: the language service also offers
+    // every other module in the program (deep package paths included), which the editor-side
+    // policy has ruled out — filtering here keeps them off the wire entirely.
+    const admitted = new Set(admittedSources);
+
+    return {
+      isIncomplete: info.isIncomplete === true,
+      entries: info.entries.filter(entry => entry.source !== undefined && admitted.has(entry.source))
+    };
+  }
+
+  getAutoImportCompletionEntryDetails(fileName, position, entryName, source, data) {
+    // `data` must round-trip from the completion entry: without it the service cannot compute
+    // the import edit for a node_modules package (an ambient module happens to survive, but
+    // the contract is the pair). `semicolons: "insert"` makes the generated statement end in
+    // one, matching the house style of every template the editors seed.
+    return this.getLanguageService().getCompletionEntryDetails(
+      fileName,
+      position,
+      entryName,
+      { semicolons: "insert" },
+      source,
+      AUTO_IMPORT_PREFERENCES,
+      data
+    );
+  }
 }
 
 // Monaco's worker handshake is two-staged (`internal/common/initialize.js`, 0.56): a first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldsmirk/inkstone-monaco",
-  "version": "0.17.1",
+  "version": "0.19.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",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@shikijs/monaco": "^4.4.3",
-    "@coldsmirk/inkstone-core": "^0.17.1"
+    "@coldsmirk/inkstone-core": "^0.19.0"
   },
   "devDependencies": {
     "monaco-editor": "^0.56.0",