@singapore-editor/lsp-plugin 0.1.1

package/dist/renameWidget.js

@@ -0,0 +1,117 @@
+import { createAnchoredSurface } from "@singapore-editor/plugin-ui/anchored-surface";
+//#region src/renameWidget.ts
+var THEME_VARIABLES = [
+	"--editor-background",
+	"--editor-popup-background",
+	"--editor-foreground",
+	"--editor-font-family",
+	"--editor-font-size"
+];
+/** Tighter than the tooltips: the input reads as attached to the symbol, not floating near it. */
+var RENAME_GAP_PX = 4;
+/**
+* The editor's own rename input: a small floating field anchored at the symbol.
+*
+* It exists so the engine is usable on its own. A host with its own dialog language passes
+* `onRequestRenameName` instead and this is never built.
+*/
+function createRenameWidgetController(options) {
+	const namespace = options.classNamespace ?? "lsp-plugin";
+	const element = options.document.createElement("div");
+	element.className = `${namespace}-rename`;
+	element.style.zIndex = "60";
+	element.style.display = "none";
+	element.style.background = "var(--editor-popup-background, var(--editor-background, #1e1e1e))";
+	const input = options.document.createElement("input");
+	input.className = `${namespace}-rename-input`;
+	input.type = "text";
+	input.spellcheck = false;
+	input.autocomplete = "off";
+	input.setAttribute("aria-label", "New name");
+	element.appendChild(input);
+	options.document.body.appendChild(element);
+	const surface = createAnchoredSurface({
+		element,
+		anchorClassName: `${namespace}-rename-anchor`,
+		preferredPlacement: "bottom",
+		alignment: "start",
+		gapPx: RENAME_GAP_PX
+	});
+	const promptState = {
+		removeAbortListener: null,
+		settle: null
+	};
+	function close(value) {
+		if (!promptState.settle) return;
+		const resolve = promptState.settle;
+		promptState.settle = null;
+		promptState.removeAbortListener?.();
+		promptState.removeAbortListener = null;
+		const heldFocus = element.contains(options.document.activeElement);
+		element.style.display = "none";
+		surface.release();
+		if (heldFocus) options.returnFocus?.();
+		resolve(value);
+	}
+	input.addEventListener("keydown", (event) => {
+		if (event.key === "Enter") {
+			event.preventDefault();
+			const next = input.value.trim();
+			close(next.length === 0 ? null : next);
+			return;
+		}
+		if (event.key === "Escape") {
+			event.preventDefault();
+			event.stopPropagation();
+			close(null);
+		}
+	});
+	input.addEventListener("blur", () => close(null));
+	return {
+		containsTarget: (target) => target instanceof Node && element.contains(target),
+		reanchor(anchor) {
+			if (!promptState.settle) return;
+			surface.place(anchor);
+		},
+		dispose() {
+			close(null);
+			surface.dispose();
+			element.remove();
+		},
+		prompt({ anchor, currentName, signal }) {
+			close(null);
+			if (signal.aborted) return Promise.resolve(null);
+			applyTheme(element, options.themeSource);
+			element.style.display = "block";
+			surface.place(anchor);
+			input.value = currentName;
+			input.focus();
+			input.select();
+			return beginRenamePrompt(promptState, signal, close);
+		}
+	};
+}
+function beginRenamePrompt(state, signal, close) {
+	return new Promise((resolve) => {
+		state.settle = resolve;
+		const handleAbort = () => close(null);
+		signal.addEventListener("abort", handleAbort, { once: true });
+		state.removeAbortListener = () => signal.removeEventListener("abort", handleAbort);
+		if (signal.aborted) close(null);
+	});
+}
+function applyTheme(element, source) {
+	const style = getComputedStyle(source);
+	for (const variable of THEME_VARIABLES) {
+		const value = style.getPropertyValue(variable);
+		if (value) {
+			element.style.setProperty(variable, value);
+			continue;
+		}
+		element.style.removeProperty(variable);
+	}
+}
+//#endregion
+export { createRenameWidgetController };
+
+//# sourceMappingURL=renameWidget.js.map

package/dist/renameWidget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renameWidget.js","names":[],"sources":["../src/renameWidget.ts"],"sourcesContent":["import { createAnchoredSurface } from '@singapore-editor/plugin-ui/anchored-surface'\n\nexport type RenameWidgetOptions = {\n  readonly document: Document\n  /** Element whose computed style carries the editor theme variables. */\n  readonly themeSource: HTMLElement\n  readonly classNamespace?: string\n  /** Called when the prompt closes while it holds focus, which hiding it would otherwise strand. */\n  readonly returnFocus?: () => void\n}\n\ntype RenameWidgetPrompt = {\n  readonly anchor: DOMRect\n  readonly currentName: string\n  readonly signal: AbortSignal\n}\n\nexport type RenameWidgetController = {\n  /** Shows the input and resolves with the new name, or null when dismissed. */\n  prompt(options: RenameWidgetPrompt): Promise<string | null>\n  /** Moves an open prompt to where the symbol is drawn now. */\n  reanchor(anchor: DOMRect): void\n  containsTarget(target: EventTarget | null): boolean\n  dispose(): void\n}\n\ntype RenamePromptState = {\n  removeAbortListener: (() => void) | null\n  settle: ((value: string | null) => void) | null\n}\n\nconst THEME_VARIABLES = [\n  '--editor-background',\n  '--editor-popup-background',\n  '--editor-foreground',\n  '--editor-font-family',\n  '--editor-font-size',\n] as const\n\n/** Tighter than the tooltips: the input reads as attached to the symbol, not floating near it. */\nconst RENAME_GAP_PX = 4\n\n/**\n * The editor's own rename input: a small floating field anchored at the symbol.\n *\n * It exists so the engine is usable on its own. A host with its own dialog language passes\n * `onRequestRenameName` instead and this is never built.\n */\nexport function createRenameWidgetController(options: RenameWidgetOptions): RenameWidgetController {\n  const namespace = options.classNamespace ?? 'lsp-plugin'\n  const element = options.document.createElement('div')\n  element.className = `${namespace}-rename`\n  element.style.zIndex = '60'\n  element.style.display = 'none'\n  element.style.background = 'var(--editor-popup-background, var(--editor-background, #1e1e1e))'\n\n  const input = options.document.createElement('input')\n  input.className = `${namespace}-rename-input`\n  input.type = 'text'\n  input.spellcheck = false\n  input.autocomplete = 'off'\n  input.setAttribute('aria-label', 'New name')\n  element.appendChild(input)\n  options.document.body.appendChild(element)\n  const surface = createAnchoredSurface({\n    element,\n    anchorClassName: `${namespace}-rename-anchor`,\n    // Below the symbol, so the word being renamed stays readable while the new one is typed.\n    preferredPlacement: 'bottom',\n    alignment: 'start',\n    gapPx: RENAME_GAP_PX,\n  })\n\n  const promptState: RenamePromptState = {\n    removeAbortListener: null,\n    settle: null,\n  }\n\n  function close(value: string | null): void {\n    if (!promptState.settle) return\n\n    const resolve = promptState.settle\n    promptState.settle = null\n    promptState.removeAbortListener?.()\n    promptState.removeAbortListener = null\n    // A close from a click elsewhere has already moved focus; Enter and Escape leave it here.\n    const heldFocus = element.contains(options.document.activeElement)\n    element.style.display = 'none'\n    surface.release()\n    if (heldFocus) options.returnFocus?.()\n    resolve(value)\n  }\n\n  input.addEventListener('keydown', (event) => {\n    if (event.key === 'Enter') {\n      event.preventDefault()\n      // An unchanged or empty name is a cancel: renaming a symbol to itself is a no-op edit, and to\n      // nothing is not a rename at all.\n      const next = input.value.trim()\n      close(next.length === 0 ? null : next)\n      return\n    }\n    if (event.key === 'Escape') {\n      event.preventDefault()\n      event.stopPropagation()\n      close(null)\n    }\n  })\n  input.addEventListener('blur', () => close(null))\n\n  return {\n    containsTarget: (target) => target instanceof Node && element.contains(target),\n    reanchor(anchor) {\n      if (!promptState.settle) return\n\n      surface.place(anchor)\n    },\n    dispose() {\n      close(null)\n      surface.dispose()\n      element.remove()\n    },\n    prompt({ anchor, currentName, signal }) {\n      // A prompt already open is dismissed first, because dismissing it hides the element and takes\n      // the anchor out of the page — done afterwards it would undo the showing it comes with.\n      close(null)\n      if (signal.aborted) return Promise.resolve(null)\n\n      applyTheme(element, options.themeSource)\n      element.style.display = 'block'\n      surface.place(anchor)\n      input.value = currentName\n      input.focus()\n      // Selected, so typing replaces the old name — the common case — while arrow keys still edit it.\n      input.select()\n\n      return beginRenamePrompt(promptState, signal, close)\n    },\n  }\n}\n\nfunction beginRenamePrompt(\n  state: RenamePromptState,\n  signal: AbortSignal,\n  close: (value: string | null) => void,\n): Promise<string | null> {\n  return new Promise((resolve) => {\n    state.settle = resolve\n    const handleAbort = () => close(null)\n    signal.addEventListener('abort', handleAbort, { once: true })\n    state.removeAbortListener = () => signal.removeEventListener('abort', handleAbort)\n    if (signal.aborted) close(null)\n  })\n}\n\nfunction applyTheme(element: HTMLElement, source: HTMLElement): void {\n  const style = getComputedStyle(source)\n  for (const variable of THEME_VARIABLES) {\n    const value = style.getPropertyValue(variable)\n    if (value) {\n      element.style.setProperty(variable, value)\n      continue\n    }\n    element.style.removeProperty(variable)\n  }\n}\n"],"mappings":";;AA+BA,IAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;AACF;;AAGA,IAAM,gBAAgB;;;;;;;AAQtB,SAAgB,6BAA6B,SAAsD;CACjG,MAAM,YAAY,QAAQ,kBAAkB;CAC5C,MAAM,UAAU,QAAQ,SAAS,cAAc,KAAK;CACpD,QAAQ,YAAY,GAAG,UAAU;CACjC,QAAQ,MAAM,SAAS;CACvB,QAAQ,MAAM,UAAU;CACxB,QAAQ,MAAM,aAAa;CAE3B,MAAM,QAAQ,QAAQ,SAAS,cAAc,OAAO;CACpD,MAAM,YAAY,GAAG,UAAU;CAC/B,MAAM,OAAO;CACb,MAAM,aAAa;CACnB,MAAM,eAAe;CACrB,MAAM,aAAa,cAAc,UAAU;CAC3C,QAAQ,YAAY,KAAK;CACzB,QAAQ,SAAS,KAAK,YAAY,OAAO;CACzC,MAAM,UAAU,sBAAsB;EACpC;EACA,iBAAiB,GAAG,UAAU;EAE9B,oBAAoB;EACpB,WAAW;EACX,OAAO;CACT,CAAC;CAED,MAAM,cAAiC;EACrC,qBAAqB;EACrB,QAAQ;CACV;CAEA,SAAS,MAAM,OAA4B;EACzC,IAAI,CAAC,YAAY,QAAQ;EAEzB,MAAM,UAAU,YAAY;EAC5B,YAAY,SAAS;EACrB,YAAY,sBAAsB;EAClC,YAAY,sBAAsB;EAElC,MAAM,YAAY,QAAQ,SAAS,QAAQ,SAAS,aAAa;EACjE,QAAQ,MAAM,UAAU;EACxB,QAAQ,QAAQ;EAChB,IAAI,WAAW,QAAQ,cAAc;EACrC,QAAQ,KAAK;CACf;CAEA,MAAM,iBAAiB,YAAY,UAAU;EAC3C,IAAI,MAAM,QAAQ,SAAS;GACzB,MAAM,eAAe;GAGrB,MAAM,OAAO,MAAM,MAAM,KAAK;GAC9B,MAAM,KAAK,WAAW,IAAI,OAAO,IAAI;GACrC;EACF;EACA,IAAI,MAAM,QAAQ,UAAU;GAC1B,MAAM,eAAe;GACrB,MAAM,gBAAgB;GACtB,MAAM,IAAI;EACZ;CACF,CAAC;CACD,MAAM,iBAAiB,cAAc,MAAM,IAAI,CAAC;CAEhD,OAAO;EACL,iBAAiB,WAAW,kBAAkB,QAAQ,QAAQ,SAAS,MAAM;EAC7E,SAAS,QAAQ;GACf,IAAI,CAAC,YAAY,QAAQ;GAEzB,QAAQ,MAAM,MAAM;EACtB;EACA,UAAU;GACR,MAAM,IAAI;GACV,QAAQ,QAAQ;GAChB,QAAQ,OAAO;EACjB;EACA,OAAO,EAAE,QAAQ,aAAa,UAAU;GAGtC,MAAM,IAAI;GACV,IAAI,OAAO,SAAS,OAAO,QAAQ,QAAQ,IAAI;GAE/C,WAAW,SAAS,QAAQ,WAAW;GACvC,QAAQ,MAAM,UAAU;GACxB,QAAQ,MAAM,MAAM;GACpB,MAAM,QAAQ;GACd,MAAM,MAAM;GAEZ,MAAM,OAAO;GAEb,OAAO,kBAAkB,aAAa,QAAQ,KAAK;EACrD;CACF;AACF;AAEA,SAAS,kBACP,OACA,QACA,OACwB;CACxB,OAAO,IAAI,SAAS,YAAY;EAC9B,MAAM,SAAS;EACf,MAAM,oBAAoB,MAAM,IAAI;EACpC,OAAO,iBAAiB,SAAS,aAAa,EAAE,MAAM,KAAK,CAAC;EAC5D,MAAM,4BAA4B,OAAO,oBAAoB,SAAS,WAAW;EACjF,IAAI,OAAO,SAAS,MAAM,IAAI;CAChC,CAAC;AACH;AAEA,SAAS,WAAW,SAAsB,QAA2B;CACnE,MAAM,QAAQ,iBAAiB,MAAM;CACrC,KAAK,MAAM,YAAY,iBAAiB;EACtC,MAAM,QAAQ,MAAM,iBAAiB,QAAQ;EAC7C,IAAI,OAAO;GACT,QAAQ,MAAM,YAAY,UAAU,KAAK;GACzC;EACF;EACA,QAAQ,MAAM,eAAe,QAAQ;CACvC;AACF"}

package/dist/semanticTokenDecoder.d.ts

@@ -0,0 +1,81 @@
+import type { SemanticTokenSpan } from '@singapore-editor/core/syntax';
+import type * as lsp from 'vscode-languageserver-protocol';
+/**
+ * What the decoder threw away, one count per rejection rule.
+ *
+ * Counts rather than samples, and all of them zero in the healthy case. They exist because every
+ * rule below discards input from an untrusted source, and a silent discard is indistinguishable
+ * from a server that simply sent fewer tokens — which is how a legend ends up two thirds on the
+ * floor while everything looks like it is working.
+ *
+ * The decoder neither aggregates nor logs. Whether these are summed per server, reported once per
+ * session, or ignored is the host's policy, on the host's side of the seam: this package does not
+ * know what a session is, or which server answered.
+ */
+export type SemanticTokenDecodeDrops = {
+    /** Rule 2: `tokenTypeIndex` outside the legend. Tuple dropped, cursor still advanced. */
+    readonly outOfLegendType: number;
+    /** Rule 4: zero-length tuple. */
+    readonly zeroLength: number;
+    /**
+     * Rule 5: the token began past the end of the text it addresses — either because `deltaLine` ran
+     * past the last line, or because `character` ran past the end of the line it did reach. Both axes
+     * of the same failure, and both usually mean one thing: the response describes a longer document
+     * than the `lineStarts` and `textLength` it was decoded against, i.e. the host's own snapshot has
+     * moved. Counting that under `zeroLength` would point the host at the server.
+     *
+     * The character axis is checked against `lineStarts[line + 1]`, not against `textLength`. Clamped
+     * to the document alone, a `character` past the end of line 1 of a long file is still a valid
+     * offset — one somewhere on line 3 — so the tuple decoded to a plausible span over unrelated text
+     * and reported nothing.
+     */
+    readonly pastEndOfDocument: number;
+    /** Rule 3: modifier bits beyond the legend's length. The SPAN SURVIVES; only the bits are lost. */
+    readonly unknownModifierBits: number;
+    /**
+     * A trailing partial tuple, or a tuple carrying a value that is not a non-negative integer.
+     * Neither is one of the five rules — it is input that was never a 5-tuple to begin with — but a
+     * truncated frame that decoded to silence would be indistinguishable from a short answer.
+     */
+    readonly malformedTuple: number;
+};
+export type SemanticTokenDecodeResult = {
+    readonly spans: readonly SemanticTokenSpan[];
+    readonly drops: SemanticTokenDecodeDrops;
+};
+export type SemanticTokenDecodeDocument = {
+    /** Offset of the first character of every line, ascending. */
+    readonly lineStarts: readonly number[];
+    /** Length of the document text in UTF-16 code units. Every offset is clamped to it. */
+    readonly textLength: number;
+};
+/**
+ * Turns an LSP semantic-tokens response into absolute spans with names on them.
+ *
+ * This is the one decoder. It lives in this package rather than in the editor because it is on the
+ * *request* side of the seam — it runs on the host's schedule, against the host's legend, and the
+ * editor's paint layer never sees a legend or a 5-tuple. A second implementation anywhere is a
+ * defect: the relative cursor below is stateful, and its rejection rules are the kind that produce
+ * plausible wrong offsets rather than exceptions. A copy that drops an out-of-legend tuple without
+ * advancing the cursor corrupts every span after it and still paints something.
+ *
+ * Five rules, each of which exists because a real server violates it:
+ *
+ * 1. **Decode by index. Never invert the legend into a name-to-index map.** Real legends ship the
+ *    same name at several indices — one server ships `variable` at three and `function` at two — and
+ *    an inverted map silently mis-decodes every duplicate.
+ * 2. **An out-of-legend `tokenTypeIndex` drops the tuple but still advances the cursor.**
+ * 3. **Modifier bits beyond the legend's length are ignored, not errors.** The bitset is 32 bits
+ *    wide and a legend may declare six.
+ * 4. **Zero-length tuples are dropped.** They cannot paint and they are common in the wild.
+ * 5. **Every offset is clamped to the document length**, and a tuple that begins past the end of
+ *    the text it addresses — `deltaLine` past the last line, or `character` past the end of the
+ *    line it reached — is dropped rather than throwing. Only the *start* is held to the line: an
+ *    `end` beyond it is a multi-line span, which is a thing this decoder emits on purpose.
+ *
+ * Offsets come out absolute, in UTF-16 code units, which needs no encoding conversion at all: the
+ * client declares `general.positionEncodings: ['utf-16']`, UTF-16 code units are JavaScript string
+ * indices, and the editor's paint APIs take offsets.
+ */
+export declare function decodeSemanticTokens(data: ArrayLike<number>, legend: lsp.SemanticTokensLegend, document: SemanticTokenDecodeDocument): SemanticTokenDecodeResult;
+//# sourceMappingURL=semanticTokenDecoder.d.ts.map

package/dist/semanticTokenDecoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokenDecoder.d.ts","sourceRoot":"","sources":["../src/semanticTokenDecoder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,KAAK,KAAK,GAAG,MAAM,gCAAgC,CAAA;AAE1D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,iCAAiC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,mGAAmG;IACnG,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;IACpC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAC5C,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B,CAAA;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,GAAG,CAAC,oBAAoB,EAChC,QAAQ,EAAE,2BAA2B,GACpC,yBAAyB,CAoG3B"}

package/dist/semanticTokenDecoder.js

@@ -0,0 +1,132 @@
+//#region src/semanticTokenDecoder.ts
+var TUPLE_LENGTH = 5;
+var MODIFIER_BITS = 32;
+/**
+* Turns an LSP semantic-tokens response into absolute spans with names on them.
+*
+* This is the one decoder. It lives in this package rather than in the editor because it is on the
+* *request* side of the seam — it runs on the host's schedule, against the host's legend, and the
+* editor's paint layer never sees a legend or a 5-tuple. A second implementation anywhere is a
+* defect: the relative cursor below is stateful, and its rejection rules are the kind that produce
+* plausible wrong offsets rather than exceptions. A copy that drops an out-of-legend tuple without
+* advancing the cursor corrupts every span after it and still paints something.
+*
+* Five rules, each of which exists because a real server violates it:
+*
+* 1. **Decode by index. Never invert the legend into a name-to-index map.** Real legends ship the
+*    same name at several indices — one server ships `variable` at three and `function` at two — and
+*    an inverted map silently mis-decodes every duplicate.
+* 2. **An out-of-legend `tokenTypeIndex` drops the tuple but still advances the cursor.**
+* 3. **Modifier bits beyond the legend's length are ignored, not errors.** The bitset is 32 bits
+*    wide and a legend may declare six.
+* 4. **Zero-length tuples are dropped.** They cannot paint and they are common in the wild.
+* 5. **Every offset is clamped to the document length**, and a tuple that begins past the end of
+*    the text it addresses — `deltaLine` past the last line, or `character` past the end of the
+*    line it reached — is dropped rather than throwing. Only the *start* is held to the line: an
+*    `end` beyond it is a multi-line span, which is a thing this decoder emits on purpose.
+*
+* Offsets come out absolute, in UTF-16 code units, which needs no encoding conversion at all: the
+* client declares `general.positionEncodings: ['utf-16']`, UTF-16 code units are JavaScript string
+* indices, and the editor's paint APIs take offsets.
+*/
+function decodeSemanticTokens(data, legend, document) {
+	const spans = [];
+	const tokenTypes = legend.tokenTypes;
+	const tokenModifiers = legend.tokenModifiers;
+	const lineStarts = document.lineStarts;
+	const textLength = document.textLength;
+	let outOfLegendType = 0;
+	let zeroLength = 0;
+	let pastEndOfDocument = 0;
+	let unknownModifierBits = 0;
+	let malformedTuple = 0;
+	let line = 0;
+	let character = 0;
+	let index = 0;
+	for (; index + TUPLE_LENGTH <= data.length; index += TUPLE_LENGTH) {
+		const deltaLine = data[index];
+		const deltaStartChar = data[index + 1];
+		const length = data[index + 2];
+		const tokenTypeIndex = data[index + 3];
+		const modifierBitset = data[index + 4];
+		if (!isUnsignedInteger(deltaLine) || !isUnsignedInteger(deltaStartChar) || !isUnsignedInteger(length) || !isUnsignedInteger(tokenTypeIndex) || !isUnsignedInteger(modifierBitset)) {
+			malformedTuple += 1;
+			break;
+		}
+		line += deltaLine;
+		character = deltaLine === 0 ? character + deltaStartChar : deltaStartChar;
+		if (line >= lineStarts.length) {
+			pastEndOfDocument += 1;
+			continue;
+		}
+		if (length === 0) {
+			zeroLength += 1;
+			continue;
+		}
+		const tokenType = tokenTypes[tokenTypeIndex];
+		if (tokenType === void 0) {
+			outOfLegendType += 1;
+			continue;
+		}
+		const lineStart = lineStarts[line];
+		const lineEnd = lineStarts[line + 1] ?? textLength;
+		const start = clampOffset(lineStart + character, textLength);
+		const end = clampOffset(lineStart + character + length, textLength);
+		if (end <= start || start >= lineEnd) {
+			pastEndOfDocument += 1;
+			continue;
+		}
+		const modifiers = decodeModifiers(modifierBitset, tokenModifiers);
+		if (modifiers.unknownBits) unknownModifierBits += 1;
+		spans.push(modifiers.names.length > 0 ? {
+			end,
+			start,
+			tokenModifiers: modifiers.names,
+			tokenType
+		} : {
+			end,
+			start,
+			tokenType
+		});
+	}
+	if (index < data.length && malformedTuple === 0) malformedTuple += 1;
+	return {
+		drops: {
+			malformedTuple,
+			outOfLegendType,
+			pastEndOfDocument,
+			unknownModifierBits,
+			zeroLength
+		},
+		spans
+	};
+}
+function decodeModifiers(bitset, tokenModifiers) {
+	if (bitset === 0) return {
+		names: [],
+		unknownBits: false
+	};
+	const names = [];
+	let unknownBits = false;
+	for (let bit = 0; bit < MODIFIER_BITS; bit += 1) {
+		if ((bitset & 1 << bit) === 0) continue;
+		const name = tokenModifiers[bit];
+		if (name === void 0) unknownBits = true;
+		else names.push(name);
+	}
+	return {
+		names,
+		unknownBits
+	};
+}
+function isUnsignedInteger(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+function clampOffset(offset, textLength) {
+	if (offset < 0) return 0;
+	return offset > textLength ? textLength : offset;
+}
+//#endregion
+export { decodeSemanticTokens };
+
+//# sourceMappingURL=semanticTokenDecoder.js.map

package/dist/semanticTokenDecoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokenDecoder.js","names":[],"sources":["../src/semanticTokenDecoder.ts"],"sourcesContent":["import type { SemanticTokenSpan } from '@singapore-editor/core/syntax'\nimport type * as lsp from 'vscode-languageserver-protocol'\n\n/**\n * What the decoder threw away, one count per rejection rule.\n *\n * Counts rather than samples, and all of them zero in the healthy case. They exist because every\n * rule below discards input from an untrusted source, and a silent discard is indistinguishable\n * from a server that simply sent fewer tokens — which is how a legend ends up two thirds on the\n * floor while everything looks like it is working.\n *\n * The decoder neither aggregates nor logs. Whether these are summed per server, reported once per\n * session, or ignored is the host's policy, on the host's side of the seam: this package does not\n * know what a session is, or which server answered.\n */\nexport type SemanticTokenDecodeDrops = {\n  /** Rule 2: `tokenTypeIndex` outside the legend. Tuple dropped, cursor still advanced. */\n  readonly outOfLegendType: number\n  /** Rule 4: zero-length tuple. */\n  readonly zeroLength: number\n  /**\n   * Rule 5: the token began past the end of the text it addresses — either because `deltaLine` ran\n   * past the last line, or because `character` ran past the end of the line it did reach. Both axes\n   * of the same failure, and both usually mean one thing: the response describes a longer document\n   * than the `lineStarts` and `textLength` it was decoded against, i.e. the host's own snapshot has\n   * moved. Counting that under `zeroLength` would point the host at the server.\n   *\n   * The character axis is checked against `lineStarts[line + 1]`, not against `textLength`. Clamped\n   * to the document alone, a `character` past the end of line 1 of a long file is still a valid\n   * offset — one somewhere on line 3 — so the tuple decoded to a plausible span over unrelated text\n   * and reported nothing.\n   */\n  readonly pastEndOfDocument: number\n  /** Rule 3: modifier bits beyond the legend's length. The SPAN SURVIVES; only the bits are lost. */\n  readonly unknownModifierBits: number\n  /**\n   * A trailing partial tuple, or a tuple carrying a value that is not a non-negative integer.\n   * Neither is one of the five rules — it is input that was never a 5-tuple to begin with — but a\n   * truncated frame that decoded to silence would be indistinguishable from a short answer.\n   */\n  readonly malformedTuple: number\n}\n\nexport type SemanticTokenDecodeResult = {\n  readonly spans: readonly SemanticTokenSpan[]\n  readonly drops: SemanticTokenDecodeDrops\n}\n\nexport type SemanticTokenDecodeDocument = {\n  /** Offset of the first character of every line, ascending. */\n  readonly lineStarts: readonly number[]\n  /** Length of the document text in UTF-16 code units. Every offset is clamped to it. */\n  readonly textLength: number\n}\n\nconst TUPLE_LENGTH = 5\nconst MODIFIER_BITS = 32\n\n/**\n * Turns an LSP semantic-tokens response into absolute spans with names on them.\n *\n * This is the one decoder. It lives in this package rather than in the editor because it is on the\n * *request* side of the seam — it runs on the host's schedule, against the host's legend, and the\n * editor's paint layer never sees a legend or a 5-tuple. A second implementation anywhere is a\n * defect: the relative cursor below is stateful, and its rejection rules are the kind that produce\n * plausible wrong offsets rather than exceptions. A copy that drops an out-of-legend tuple without\n * advancing the cursor corrupts every span after it and still paints something.\n *\n * Five rules, each of which exists because a real server violates it:\n *\n * 1. **Decode by index. Never invert the legend into a name-to-index map.** Real legends ship the\n *    same name at several indices — one server ships `variable` at three and `function` at two — and\n *    an inverted map silently mis-decodes every duplicate.\n * 2. **An out-of-legend `tokenTypeIndex` drops the tuple but still advances the cursor.**\n * 3. **Modifier bits beyond the legend's length are ignored, not errors.** The bitset is 32 bits\n *    wide and a legend may declare six.\n * 4. **Zero-length tuples are dropped.** They cannot paint and they are common in the wild.\n * 5. **Every offset is clamped to the document length**, and a tuple that begins past the end of\n *    the text it addresses — `deltaLine` past the last line, or `character` past the end of the\n *    line it reached — is dropped rather than throwing. Only the *start* is held to the line: an\n *    `end` beyond it is a multi-line span, which is a thing this decoder emits on purpose.\n *\n * Offsets come out absolute, in UTF-16 code units, which needs no encoding conversion at all: the\n * client declares `general.positionEncodings: ['utf-16']`, UTF-16 code units are JavaScript string\n * indices, and the editor's paint APIs take offsets.\n */\nexport function decodeSemanticTokens(\n  data: ArrayLike<number>,\n  legend: lsp.SemanticTokensLegend,\n  document: SemanticTokenDecodeDocument,\n): SemanticTokenDecodeResult {\n  const spans: SemanticTokenSpan[] = []\n  const tokenTypes = legend.tokenTypes\n  const tokenModifiers = legend.tokenModifiers\n  const lineStarts = document.lineStarts\n  const textLength = document.textLength\n\n  let outOfLegendType = 0\n  let zeroLength = 0\n  let pastEndOfDocument = 0\n  let unknownModifierBits = 0\n  let malformedTuple = 0\n\n  let line = 0\n  let character = 0\n  let index = 0\n\n  for (; index + TUPLE_LENGTH <= data.length; index += TUPLE_LENGTH) {\n    const deltaLine = data[index] as number\n    const deltaStartChar = data[index + 1] as number\n    const length = data[index + 2] as number\n    const tokenTypeIndex = data[index + 3] as number\n    const modifierBitset = data[index + 4] as number\n\n    if (\n      !isUnsignedInteger(deltaLine) ||\n      !isUnsignedInteger(deltaStartChar) ||\n      !isUnsignedInteger(length) ||\n      !isUnsignedInteger(tokenTypeIndex) ||\n      !isUnsignedInteger(modifierBitset)\n    ) {\n      // The cursor cannot be advanced by a value that is not a number, and guessing would put every\n      // later span at a plausible wrong offset. Stop rather than corrupt the rest.\n      malformedTuple += 1\n      break\n    }\n\n    // Advance first, unconditionally: every rule below may reject the tuple, and a rejection that\n    // skipped the advance would shift every span after it.\n    line += deltaLine\n    character = deltaLine === 0 ? character + deltaStartChar : deltaStartChar\n\n    if (line >= lineStarts.length) {\n      pastEndOfDocument += 1\n      continue\n    }\n    if (length === 0) {\n      zeroLength += 1\n      continue\n    }\n\n    // Rule 1: by index. Inverting the legend would collapse the duplicate names real legends carry.\n    const tokenType = tokenTypes[tokenTypeIndex]\n    if (tokenType === undefined) {\n      outOfLegendType += 1\n      continue\n    }\n\n    const lineStart = lineStarts[line] as number\n    // Where the line the tuple addresses actually stops. LSP's own `Position` rule says a character\n    // past the end of a line means the end of that line, so a `character` beyond it describes text\n    // that is not there — and clamping only to `textLength` cannot see that: `lineStart + character`\n    // lands on a perfectly valid offset somewhere further down the file. A stale host snapshot after\n    // a line was shortened produced exactly that, and the span painted on an unrelated line with\n    // every drop counter still reading zero.\n    const lineEnd = lineStarts[line + 1] ?? textLength\n    const start = clampOffset(lineStart + character, textLength)\n    const end = clampOffset(lineStart + character + length, textLength)\n    // A tuple that clamped away to nothing is not a zero-length tuple — it arrived with a real\n    // length and began past the end of the text it addresses. Same failure as `deltaLine`\n    // overrunning, one axis over, so it is counted the same way. `end` is deliberately NOT clamped\n    // to the line: a span crossing a newline is a thing this decoder produces on purpose, for a\n    // client that declared `multilineTokenSupport`.\n    if (end <= start || start >= lineEnd) {\n      pastEndOfDocument += 1\n      continue\n    }\n\n    const modifiers = decodeModifiers(modifierBitset, tokenModifiers)\n    if (modifiers.unknownBits) unknownModifierBits += 1\n\n    spans.push(\n      modifiers.names.length > 0\n        ? { end, start, tokenModifiers: modifiers.names, tokenType }\n        : { end, start, tokenType },\n    )\n  }\n\n  if (index < data.length && malformedTuple === 0) malformedTuple += 1\n\n  return {\n    drops: {\n      malformedTuple,\n      outOfLegendType,\n      pastEndOfDocument,\n      unknownModifierBits,\n      zeroLength,\n    },\n    spans,\n  }\n}\n\nfunction decodeModifiers(\n  bitset: number,\n  tokenModifiers: readonly string[],\n): { readonly names: readonly string[]; readonly unknownBits: boolean } {\n  if (bitset === 0) return { names: [], unknownBits: false }\n\n  const names: string[] = []\n  let unknownBits = false\n  for (let bit = 0; bit < MODIFIER_BITS; bit += 1) {\n    if ((bitset & (1 << bit)) === 0) continue\n\n    const name = tokenModifiers[bit]\n    // Rule 3: a bit the legend does not name is ignored rather than fatal, and the span survives it\n    // — losing a modifier costs a shade of colour, where dropping the span costs the colour itself.\n    if (name === undefined) unknownBits = true\n    else names.push(name)\n  }\n\n  return { names, unknownBits }\n}\n\nfunction isUnsignedInteger(value: number): boolean {\n  return Number.isInteger(value) && value >= 0\n}\n\nfunction clampOffset(offset: number, textLength: number): number {\n  if (offset < 0) return 0\n  return offset > textLength ? textLength : offset\n}\n"],"mappings":";AAuDA,IAAM,eAAe;AACrB,IAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BtB,SAAgB,qBACd,MACA,QACA,UAC2B;CAC3B,MAAM,QAA6B,CAAC;CACpC,MAAM,aAAa,OAAO;CAC1B,MAAM,iBAAiB,OAAO;CAC9B,MAAM,aAAa,SAAS;CAC5B,MAAM,aAAa,SAAS;CAE5B,IAAI,kBAAkB;CACtB,IAAI,aAAa;CACjB,IAAI,oBAAoB;CACxB,IAAI,sBAAsB;CAC1B,IAAI,iBAAiB;CAErB,IAAI,OAAO;CACX,IAAI,YAAY;CAChB,IAAI,QAAQ;CAEZ,OAAO,QAAQ,gBAAgB,KAAK,QAAQ,SAAS,cAAc;EACjE,MAAM,YAAY,KAAK;EACvB,MAAM,iBAAiB,KAAK,QAAQ;EACpC,MAAM,SAAS,KAAK,QAAQ;EAC5B,MAAM,iBAAiB,KAAK,QAAQ;EACpC,MAAM,iBAAiB,KAAK,QAAQ;EAEpC,IACE,CAAC,kBAAkB,SAAS,KAC5B,CAAC,kBAAkB,cAAc,KACjC,CAAC,kBAAkB,MAAM,KACzB,CAAC,kBAAkB,cAAc,KACjC,CAAC,kBAAkB,cAAc,GACjC;GAGA,kBAAkB;GAClB;EACF;EAIA,QAAQ;EACR,YAAY,cAAc,IAAI,YAAY,iBAAiB;EAE3D,IAAI,QAAQ,WAAW,QAAQ;GAC7B,qBAAqB;GACrB;EACF;EACA,IAAI,WAAW,GAAG;GAChB,cAAc;GACd;EACF;EAGA,MAAM,YAAY,WAAW;EAC7B,IAAI,cAAc,KAAA,GAAW;GAC3B,mBAAmB;GACnB;EACF;EAEA,MAAM,YAAY,WAAW;EAO7B,MAAM,UAAU,WAAW,OAAO,MAAM;EACxC,MAAM,QAAQ,YAAY,YAAY,WAAW,UAAU;EAC3D,MAAM,MAAM,YAAY,YAAY,YAAY,QAAQ,UAAU;EAMlE,IAAI,OAAO,SAAS,SAAS,SAAS;GACpC,qBAAqB;GACrB;EACF;EAEA,MAAM,YAAY,gBAAgB,gBAAgB,cAAc;EAChE,IAAI,UAAU,aAAa,uBAAuB;EAElD,MAAM,KACJ,UAAU,MAAM,SAAS,IACrB;GAAE;GAAK;GAAO,gBAAgB,UAAU;GAAO;EAAU,IACzD;GAAE;GAAK;GAAO;EAAU,CAC9B;CACF;CAEA,IAAI,QAAQ,KAAK,UAAU,mBAAmB,GAAG,kBAAkB;CAEnE,OAAO;EACL,OAAO;GACL;GACA;GACA;GACA;GACA;EACF;EACA;CACF;AACF;AAEA,SAAS,gBACP,QACA,gBACsE;CACtE,IAAI,WAAW,GAAG,OAAO;EAAE,OAAO,CAAC;EAAG,aAAa;CAAM;CAEzD,MAAM,QAAkB,CAAC;CACzB,IAAI,cAAc;CAClB,KAAK,IAAI,MAAM,GAAG,MAAM,eAAe,OAAO,GAAG;EAC/C,KAAK,SAAU,KAAK,SAAU,GAAG;EAEjC,MAAM,OAAO,eAAe;EAG5B,IAAI,SAAS,KAAA,GAAW,cAAc;OACjC,MAAM,KAAK,IAAI;CACtB;CAEA,OAAO;EAAE;EAAO;CAAY;AAC9B;AAEA,SAAS,kBAAkB,OAAwB;CACjD,OAAO,OAAO,UAAU,KAAK,KAAK,SAAS;AAC7C;AAEA,SAAS,YAAY,QAAgB,YAA4B;CAC/D,IAAI,SAAS,GAAG,OAAO;CACvB,OAAO,SAAS,aAAa,aAAa;AAC5C"}

package/dist/semanticTokens.d.ts

@@ -0,0 +1,47 @@
+import type { EditorDisposable, EditorViewContributionContext, EditorViewContributionUpdateKind, EditorViewSnapshot, SemanticTokenLayer, SemanticTokenLayerOptions } from '@singapore-editor/core/extensions';
+import type { LanguageServerConnectionContext } from './connectionContext';
+/** Which document a layer was created for. A layer never spans two. */
+export type LanguageServerSemanticTokensDocument = {
+    readonly documentId: string;
+    readonly languageId: string | null;
+};
+export type LanguageServerSemanticTokensOptions = Omit<SemanticTokenLayerOptions, 'name'> & {
+    /** Namespaced within the view. Defaults to `semantic`. */
+    readonly name?: string;
+    /**
+     * Receives the layer the view contribution created.
+     *
+     * A host cannot construct one itself: a layer needs a viewport, a snapshot and a lifecycle, and
+     * all three belong to the contribution. Returning a disposable ties the host's own request-side
+     * controller to the layer, in the shape `onConnectionCreated` already uses.
+     *
+     * **A layer never spans two documents or two language ids.** A change to either disposes the one
+     * the host is holding and delivers a *new* one through a second call carrying the new identity —
+     * so `clear()` across a document change is a call on a dead handle, not a reset.
+     */
+    onLayer?(layer: SemanticTokenLayer, document: LanguageServerSemanticTokensDocument): EditorDisposable | void;
+};
+export type LanguageServerSemanticTokensOwner = {
+    readonly id: string;
+    readonly connection: LanguageServerConnectionContext;
+};
+export type LanguageServerSemanticTokensOwnerOptions = LanguageServerSemanticTokensOptions & {
+    dispose?(): void;
+};
+export type LanguageServerSemanticTokensFactory = (owner: LanguageServerSemanticTokensOwner) => LanguageServerSemanticTokensOwnerOptions;
+/**
+ * Owns the semantic token layer's lifetime on the contribution's behalf.
+ *
+ * The contribution itself is per *view* and outlives a document change; the contract says a layer
+ * does not. So the identity is watched here, and a document or language change tears the layer down
+ * and hands the host a fresh one rather than quietly re-pointing the old one at different text.
+ */
+export declare class SemanticTokenLayerOwner {
+    #private;
+    private readonly context;
+    private readonly options;
+    constructor(context: EditorViewContributionContext, options: LanguageServerSemanticTokensOptions);
+    update(snapshot: EditorViewSnapshot, kind: EditorViewContributionUpdateKind): void;
+    dispose(): void;
+}
+//# sourceMappingURL=semanticTokens.d.ts.map

package/dist/semanticTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokens.d.ts","sourceRoot":"","sources":["../src/semanticTokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,6BAA6B,EAC7B,gCAAgC,EAChC,kBAAkB,EAClB,kBAAkB,EAElB,yBAAyB,EAC1B,MAAM,mCAAmC,CAAA;AAG1C,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAA;AAE1E,uEAAuE;AACvE,MAAM,MAAM,oCAAoC,GAAG;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC,CAAA;AAED,MAAM,MAAM,mCAAmC,GAAG,IAAI,CAAC,yBAAyB,EAAE,MAAM,CAAC,GAAG;IAC1F,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,CACN,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,oCAAoC,GAC7C,gBAAgB,GAAG,IAAI,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,iCAAiC,GAAG;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,+BAA+B,CAAA;CACrD,CAAA;AAED,MAAM,MAAM,wCAAwC,GAAG,mCAAmC,GAAG;IAC3F,OAAO,CAAC,IAAI,IAAI,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,mCAAmC,GAAG,CAChD,KAAK,EAAE,iCAAiC,KACrC,wCAAwC,CAAA;AAE7C;;;;;;GAMG;AACH,qBAAa,uBAAuB;;IAQhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,6BAA6B,EACtC,OAAO,EAAE,mCAAmC;IAGxD,MAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,gCAAgC,GAAG,IAAI;IAgBlF,OAAO,IAAI,IAAI;CA6BvB"}

package/dist/semanticTokens.js

@@ -0,0 +1,68 @@
+import { createSemanticTokenLayer } from "@singapore-editor/core/extensions";
+//#region src/semanticTokens.ts
+/**
+* Owns the semantic token layer's lifetime on the contribution's behalf.
+*
+* The contribution itself is per *view* and outlives a document change; the contract says a layer
+* does not. So the identity is watched here, and a document or language change tears the layer down
+* and hands the host a fresh one rather than quietly re-pointing the old one at different text.
+*/
+var SemanticTokenLayerOwner = class {
+	context;
+	options;
+	#layer = null;
+	#registration = null;
+	#documentId = null;
+	#languageId = null;
+	#disposed = false;
+	constructor(context, options) {
+		this.context = context;
+		this.options = options;
+	}
+	update(snapshot, kind) {
+		if (this.#disposed) return;
+		const documentId = snapshot.documentId;
+		if (documentId === null || kind === "clear") {
+			this.#tearDown();
+			return;
+		}
+		if (documentId !== this.#documentId || snapshot.languageId !== this.#languageId) {
+			this.#tearDown();
+			this.#create(documentId, snapshot.languageId);
+		}
+		this.#layer?.update(snapshot, kind);
+	}
+	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#tearDown();
+	}
+	#create(documentId, languageId) {
+		const layer = createSemanticTokenLayer(this.context, {
+			name: this.options.name ?? "semantic",
+			onRangeNeeded: this.options.onRangeNeeded,
+			onResyncRequired: this.options.onResyncRequired,
+			scopeAliases: this.options.scopeAliases,
+			viewportDelayMs: this.options.viewportDelayMs
+		});
+		this.#layer = layer;
+		this.#documentId = documentId;
+		this.#languageId = languageId;
+		this.#registration = this.options.onLayer?.(layer, {
+			documentId,
+			languageId
+		}) ?? null;
+	}
+	#tearDown() {
+		this.#registration?.dispose();
+		this.#registration = null;
+		this.#layer?.dispose();
+		this.#layer = null;
+		this.#documentId = null;
+		this.#languageId = null;
+	}
+};
+//#endregion
+export { SemanticTokenLayerOwner };
+
+//# sourceMappingURL=semanticTokens.js.map

package/dist/semanticTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticTokens.js","names":[],"sources":["../src/semanticTokens.ts"],"sourcesContent":["import type {\n  EditorDisposable,\n  EditorViewContributionContext,\n  EditorViewContributionUpdateKind,\n  EditorViewSnapshot,\n  SemanticTokenLayer,\n  SemanticTokenLayerController,\n  SemanticTokenLayerOptions,\n} from '@singapore-editor/core/extensions'\nimport { createSemanticTokenLayer } from '@singapore-editor/core/extensions'\n\nimport type { LanguageServerConnectionContext } from './connectionContext'\n\n/** Which document a layer was created for. A layer never spans two. */\nexport type LanguageServerSemanticTokensDocument = {\n  readonly documentId: string\n  readonly languageId: string | null\n}\n\nexport type LanguageServerSemanticTokensOptions = Omit<SemanticTokenLayerOptions, 'name'> & {\n  /** Namespaced within the view. Defaults to `semantic`. */\n  readonly name?: string\n  /**\n   * Receives the layer the view contribution created.\n   *\n   * A host cannot construct one itself: a layer needs a viewport, a snapshot and a lifecycle, and\n   * all three belong to the contribution. Returning a disposable ties the host's own request-side\n   * controller to the layer, in the shape `onConnectionCreated` already uses.\n   *\n   * **A layer never spans two documents or two language ids.** A change to either disposes the one\n   * the host is holding and delivers a *new* one through a second call carrying the new identity —\n   * so `clear()` across a document change is a call on a dead handle, not a reset.\n   */\n  onLayer?(\n    layer: SemanticTokenLayer,\n    document: LanguageServerSemanticTokensDocument,\n  ): EditorDisposable | void\n}\n\nexport type LanguageServerSemanticTokensOwner = {\n  readonly id: string\n  readonly connection: LanguageServerConnectionContext\n}\n\nexport type LanguageServerSemanticTokensOwnerOptions = LanguageServerSemanticTokensOptions & {\n  dispose?(): void\n}\n\nexport type LanguageServerSemanticTokensFactory = (\n  owner: LanguageServerSemanticTokensOwner,\n) => LanguageServerSemanticTokensOwnerOptions\n\n/**\n * Owns the semantic token layer's lifetime on the contribution's behalf.\n *\n * The contribution itself is per *view* and outlives a document change; the contract says a layer\n * does not. So the identity is watched here, and a document or language change tears the layer down\n * and hands the host a fresh one rather than quietly re-pointing the old one at different text.\n */\nexport class SemanticTokenLayerOwner {\n  #layer: SemanticTokenLayerController | null = null\n  #registration: EditorDisposable | null = null\n  #documentId: string | null = null\n  #languageId: string | null = null\n  #disposed = false\n\n  public constructor(\n    private readonly context: EditorViewContributionContext,\n    private readonly options: LanguageServerSemanticTokensOptions,\n  ) {}\n\n  public update(snapshot: EditorViewSnapshot, kind: EditorViewContributionUpdateKind): void {\n    if (this.#disposed) return\n\n    const documentId = snapshot.documentId\n    if (documentId === null || kind === 'clear') {\n      this.#tearDown()\n      return\n    }\n    if (documentId !== this.#documentId || snapshot.languageId !== this.#languageId) {\n      this.#tearDown()\n      this.#create(documentId, snapshot.languageId)\n    }\n\n    this.#layer?.update(snapshot, kind)\n  }\n\n  public dispose(): void {\n    if (this.#disposed) return\n\n    this.#disposed = true\n    this.#tearDown()\n  }\n\n  #create(documentId: string, languageId: string | null): void {\n    const layer = createSemanticTokenLayer(this.context, {\n      name: this.options.name ?? 'semantic',\n      onRangeNeeded: this.options.onRangeNeeded,\n      onResyncRequired: this.options.onResyncRequired,\n      scopeAliases: this.options.scopeAliases,\n      viewportDelayMs: this.options.viewportDelayMs,\n    })\n    this.#layer = layer\n    this.#documentId = documentId\n    this.#languageId = languageId\n    this.#registration = this.options.onLayer?.(layer, { documentId, languageId }) ?? null\n  }\n\n  #tearDown(): void {\n    this.#registration?.dispose()\n    this.#registration = null\n    this.#layer?.dispose()\n    this.#layer = null\n    this.#documentId = null\n    this.#languageId = null\n  }\n}\n"],"mappings":";;;;;;;;;AA2DA,IAAa,0BAAb,MAAqC;CAQhB;CACA;CARnB,SAA8C;CAC9C,gBAAyC;CACzC,cAA6B;CAC7B,cAA6B;CAC7B,YAAY;CAEZ,YACE,SACA,SACA;EAFiB,KAAA,UAAA;EACA,KAAA,UAAA;CAChB;CAEH,OAAc,UAA8B,MAA8C;EACxF,IAAI,KAAK,WAAW;EAEpB,MAAM,aAAa,SAAS;EAC5B,IAAI,eAAe,QAAQ,SAAS,SAAS;GAC3C,KAAK,UAAU;GACf;EACF;EACA,IAAI,eAAe,KAAK,eAAe,SAAS,eAAe,KAAK,aAAa;GAC/E,KAAK,UAAU;GACf,KAAK,QAAQ,YAAY,SAAS,UAAU;EAC9C;EAEA,KAAK,QAAQ,OAAO,UAAU,IAAI;CACpC;CAEA,UAAuB;EACrB,IAAI,KAAK,WAAW;EAEpB,KAAK,YAAY;EACjB,KAAK,UAAU;CACjB;CAEA,QAAQ,YAAoB,YAAiC;EAC3D,MAAM,QAAQ,yBAAyB,KAAK,SAAS;GACnD,MAAM,KAAK,QAAQ,QAAQ;GAC3B,eAAe,KAAK,QAAQ;GAC5B,kBAAkB,KAAK,QAAQ;GAC/B,cAAc,KAAK,QAAQ;GAC3B,iBAAiB,KAAK,QAAQ;EAChC,CAAC;EACD,KAAK,SAAS;EACd,KAAK,cAAc;EACnB,KAAK,cAAc;EACnB,KAAK,gBAAgB,KAAK,QAAQ,UAAU,OAAO;GAAE;GAAY;EAAW,CAAC,KAAK;CACpF;CAEA,YAAkB;EAChB,KAAK,eAAe,QAAQ;EAC5B,KAAK,gBAAgB;EACrB,KAAK,QAAQ,QAAQ;EACrB,KAAK,SAAS;EACd,KAAK,cAAc;EACnB,KAAK,cAAc;CACrB;AACF"}

package/dist/serverSet.d.ts

@@ -0,0 +1,69 @@
+import type { LspRequestOptions, LspWorkspace } from '@singapore-editor/lsp';
+import type * as lsp from 'vscode-languageserver-protocol';
+import type { AcquiredLanguageServerLane } from './lane';
+import { type LanguageServerFeatureId, type LanguageServerFeatureRanks, type OnApplyWorkspaceEdit, type WorkspaceEditOriginGuard } from './types';
+export type LanguageServerSetLane = {
+    readonly id: string;
+    readonly features: LanguageServerFeatureRanks;
+    readonly connection: AcquiredLanguageServerLane;
+    readonly onInteractiveReady?: () => void;
+    readonly onApplyWorkspaceEdit?: OnApplyWorkspaceEdit;
+    readonly onRequestError?: (method: string, error: unknown) => void;
+};
+export type LanguageServerLaneResult = {
+    readonly lane: LanguageServerSetLane;
+    readonly provenance?: LanguageServerCodeActionProvenance;
+    readonly result: unknown;
+};
+export type LanguageServerHoverUpdate = {
+    /** Hover answers in feature-rank order, regardless of the order in which they resolved. */
+    readonly hovers: readonly lsp.Hover[];
+    /** True until every ready hover lane has either answered or failed. */
+    readonly pending: boolean;
+};
+export type LanguageServerFeatureRouter = {
+    canResolveCodeActions(): boolean;
+    hasReady(feature: LanguageServerFeatureId, method?: string): boolean;
+    request<TResult = unknown, TParams = unknown>(method: string, params?: TParams, options?: LspRequestOptions): Promise<TResult>;
+};
+export type LanguageServerCodeActionRouter = LanguageServerFeatureRouter & {
+    ownerOf(value: unknown): LanguageServerSetLane | null;
+    provenanceOf(value: unknown): LanguageServerCodeActionProvenance | null;
+    resolveOwnedCodeAction(action: lsp.CodeAction, options: LspRequestOptions): Promise<LanguageServerOwnedCodeAction | null>;
+};
+export type LanguageServerCodeActionProvenance = {
+    readonly guard: WorkspaceEditOriginGuard;
+    readonly lane: LanguageServerSetLane;
+};
+export type LanguageServerOwnedCodeAction = LanguageServerCodeActionProvenance & {
+    readonly action: lsp.CodeAction;
+};
+export declare class LanguageServerSet {
+    #private;
+    constructor(lanes: readonly LanguageServerSetLane[]);
+    declared(feature: LanguageServerFeatureId): readonly LanguageServerSetLane[];
+    ready(feature: LanguageServerFeatureId, method?: string): readonly LanguageServerSetLane[];
+    hasReady(feature: LanguageServerFeatureId, method?: string): boolean;
+    canResolveCodeActions(): boolean;
+    ownerOf(value: unknown): LanguageServerSetLane | null;
+    provenanceOf(value: unknown): LanguageServerCodeActionProvenance | null;
+    request<TResult = unknown, TParams = unknown>(method: string, params?: TParams, options?: LspRequestOptions): Promise<TResult>;
+    requestHover<TParams>(params: TParams | undefined, options?: LspRequestOptions, onUpdate?: (update: LanguageServerHoverUpdate) => void): Promise<lsp.Hover | null>;
+    private requestHoverLane;
+    mergedArray<TParams>(feature: 'codeActions', method: string, params: TParams | undefined, options: LspRequestOptions): Promise<unknown[]>;
+    mergeArrayResults(feature: 'codeActions', results: readonly LanguageServerLaneResult[]): unknown[];
+    resolveCodeAction<TParams>(params: TParams | undefined, options: LspRequestOptions): Promise<lsp.CodeAction | NonNullable<TParams> | null>;
+    resolveOwnedCodeAction(action: lsp.CodeAction, options: LspRequestOptions): Promise<LanguageServerOwnedCodeAction | null>;
+    requestSingle<TParams, TResult = unknown>(lane: LanguageServerSetLane | undefined, method: string, params: TParams | undefined, options: LspRequestOptions, fallback: TResult, transform?: (result: unknown) => TResult): Promise<TResult>;
+    requestFirst<TParams, TResult = unknown>(feature: LanguageServerFeatureId, method: string, params: TParams | undefined, options: LspRequestOptions | undefined, fallback: TResult, accepts?: (result: unknown) => boolean): Promise<TResult>;
+    requestOwner<TParams, TResult = unknown>(feature: LanguageServerFeatureId, method: string, params: TParams | undefined, options: LspRequestOptions | undefined, fallback: TResult): Promise<TResult>;
+    requestAll<TParams>(feature: LanguageServerFeatureId, method: string, params: TParams | undefined, options: LspRequestOptions): Promise<readonly LanguageServerLaneResult[]>;
+    private requestLane;
+}
+export declare function rankedLanguageServerLanes<TLane extends {
+    readonly features: LanguageServerFeatureRanks;
+}>(lanes: readonly TLane[], feature: LanguageServerFeatureId): readonly TLane[];
+export declare function allLanguageServerFeatures(rank?: number): LanguageServerFeatureRanks;
+export declare function laneSupports(lane: LanguageServerSetLane, feature: LanguageServerFeatureId, method?: string): boolean;
+export declare function captureWorkspaceEditOriginGuard(workspace: LspWorkspace): WorkspaceEditOriginGuard;
+//# sourceMappingURL=serverSet.d.ts.map

package/dist/serverSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverSet.d.ts","sourceRoot":"","sources":["../src/serverSet.ts"],"names":[],"mappings":"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"}