@pieceful/ravel-language-typescript 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# `@pieceful/ravel-language-typescript`
+
+An in-process native TypeScript/JavaScript language-service bridge for [Ravel](https://github.com/jostylr/ravel)
+virtual documents. It keeps TypeScript project state warm and normalizes native
+results to generated-document URIs and zero-based UTF-16 offset ranges. Ravel's
+routing layer is responsible for translating those ranges back to literate
+source.
+
+## Runtime setup
+
+TypeScript is an optional peer dependency so an editor or host may inject the
+compiler API it already owns:
+
+```js
+import { createTypeScriptLanguageBridgeWithApi } from "@pieceful/ravel-language-typescript";
+
+const bridge = createTypeScriptLanguageBridgeWithApi(typescript, {
+  currentDirectory: workspaceRoot,
+  configSearchRoot: workspaceRoot,
+});
+```
+
+The asynchronous `createTypeScriptLanguageBridge()` factory loads the
+`typescript` package when no API is injected. It reports
+`TYPESCRIPT_NOT_AVAILABLE` with an actionable message when neither is
+available.
+
+## Virtual file and project identity
+
+Each document must keep a stable `uri` and monotonically increasing `version`.
+For correct relative-import semantics it should also provide its declared
+artifact location in `fileName`, `path`, `artifactPath`, or `outputPath`. A
+host can instead provide `fileNameForDocument(document)`. Projection objects
+need no extra field: a safe relative `artifactId` such as `dist/app.ts` is the
+default declared artifact location. Absolute artifact IDs, URI-like IDs, and
+paths that escape the workspace are rejected and receive an isolated in-memory
+fallback path.
+
+The bridge selects a project in this order:
+
+1. `configFileForDocument(document, fileName)`;
+2. `document.tsconfigPath` or `document.metadata.tsconfigPath`;
+3. the bridge-level `tsconfigPath`;
+4. the nearest `tsconfig.json` above the declared artifact path; or
+5. an inferred project with safe TypeScript/JavaScript analysis defaults.
+
+Configuration lookup is confined to `configSearchRoot`, which defaults to
+`currentDirectory`; a relative value is resolved from `currentDirectory`.
+Upward discovery stops at that root. Explicit paths from a document, bridge
+option, or host callback are ignored when their lexical or canonical filesystem
+location is outside the root; lookup then falls back to a confined nearest
+config or an inferred project. This also prevents a config symlink beneath the
+root from selecting a file outside it. A host may widen the root deliberately
+when one trusted TypeScript project spans several workspace folders.
+
+`configSearchRoot` confines configuration selection; it is not a complete
+filesystem sandbox. Once a trusted host enables the adapter, TypeScript's
+configured-file processing, project references, standard library, module, and
+declaration resolution use the native filesystem host and may read dependencies
+outside that root. Hosts that need a stronger boundary must provide an explicit
+file-access-root policy or a more isolated adapter; this adapter does not yet
+implement such a filesystem sandbox. Ravel's VS Code host still confines
+locations returned to the editor, but this native read boundary keeps the
+strict M7 security gate open.
+
+Configured compiler options, path aliases, JSX mode, project references,
+standard libraries, and declaration packages are delegated to the native
+TypeScript project service. Open virtual files overlay filesystem reads and
+participate in ordinary module resolution without being written to disk.
+Each Ravel target-and-stage pair owns an isolated TypeScript project and
+document registry, even when two projections use the same `tsconfig.json` and
+artifact path. This prevents browser/server targets and authoring/assembled
+stages from contaminating one another while keeping each analysis context warm
+across edits. Moving an open document to another stage also moves it to that
+stage's project before later requests are served.
+
+The supported language IDs are `typescript`, `typescriptreact`, `javascript`,
+and `javascriptreact`. Semantic operations support authoring and assembled
+projections. Emitted or destructive transformed projections are intentionally
+not advertised for editable language features.
+
+## Lifecycle and cancellation
+
+`change` rejects stale updates and version regressions. Requests can carry an
+exact document version and are discarded when superseded. TypeScript's
+cancellation token observes the request's `AbortSignal`; because the compiler
+API is synchronous, cancellation is cooperative at native cancellation points
+and is checked again before returning a response.
+
+Open/change cancellation is commit-aware. Cancellation before project mutation
+publishes no document. If cancellation arrives after a project mutation commits,
+the bridge records the same committed entry before settling, so its retained
+document map and TypeScript project cannot diverge. Script versions include a
+per-project insertion sequence as well as the Ravel document version, ensuring
+a reopened or moved virtual file receives a fresh native snapshot identity.
+
+`restart()` rebuilds language services and reopens every current in-memory
+document. `dispose()` releases services and forgets document text. This adapter
+does not spawn a process and does not require a shadow workspace.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pieceful/ravel-language-typescript",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Native TypeScript and JavaScript language-service bridge for Ravel projections.",
+  "license": "MIT",
+  "author": "James Taylor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/language-typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
+  "homepage": "https://ravel.jostylr.com/",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "literate-programming",
+    "typescript",
+    "language-service"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@pieceful/ravel-language-bridge": "0.2.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,85 @@
+import type {
+  BridgeCapabilities,
+  BridgeRequestContext,
+  LanguageBridge,
+  LanguageRequest,
+  LanguageResponse,
+  TextChange,
+  VirtualDocumentLike
+} from "@pieceful/ravel-language-bridge";
+
+export interface TypeScriptBridgeOptions {
+  /** An already loaded `typescript` compiler API. */
+  typescript?: unknown;
+  /** Alternate module specifier used by the async factory. */
+  typescriptModule?: string;
+  loadTypeScript?: (specifier: string) => unknown | Promise<unknown>;
+  /** Base directory used for virtual artifact paths. */
+  currentDirectory?: string;
+  /**
+   * Allowlisted root for explicit and discovered tsconfig files. Defaults to
+   * currentDirectory; relative values are resolved from currentDirectory.
+   * Config paths outside its canonical filesystem location are ignored.
+   */
+  configSearchRoot?: string;
+  tsconfigPath?: string;
+  compilerOptions?: Record<string, unknown>;
+  fileNameForDocument?: (document: VirtualDocumentLike) => string | undefined;
+  configFileForDocument?: (document: VirtualDocumentLike, fileName: string) => string | undefined;
+  completionOptions?: Record<string, unknown>;
+  userPreferences?: Record<string, unknown>;
+  formatOptions?: Record<string, unknown>;
+}
+
+export interface GeneratedRange { start: number; end: number; }
+export interface GeneratedLocation {
+  uri: string;
+  range: GeneratedRange;
+  contextRange?: GeneratedRange;
+  name?: string;
+  kind?: string;
+  containerName?: string;
+  isWriteAccess?: boolean;
+  isDefinition?: boolean;
+}
+export interface GeneratedTextChange { range: GeneratedRange; text: string; }
+export interface GeneratedFileChanges {
+  uri: string;
+  version?: number;
+  textChanges: GeneratedTextChange[];
+  isNewFile?: boolean;
+}
+export interface TypeScriptDiagnostic {
+  uri: string;
+  range: GeneratedRange;
+  code: number;
+  severity: "error" | "warning" | "info" | "hint";
+  message: string;
+  source: "typescript";
+  related: Array<{ uri?: string; range?: GeneratedRange; message: string }>;
+}
+export interface TypeScriptCallItem {
+  name: string;
+  kind: string;
+  uri: string;
+  range: GeneratedRange;
+  selectionRange: GeneratedRange;
+  containerName?: string;
+  kindModifiers?: string;
+}
+
+export class TypeScriptLanguageBridge implements LanguageBridge {
+  readonly languageIds: readonly ["typescript", "typescriptreact", "javascript", "javascriptreact"];
+  readonly capabilities: BridgeCapabilities;
+  readonly state: string;
+  constructor(typescript: unknown, options?: TypeScriptBridgeOptions);
+  open(document: VirtualDocumentLike, signal?: AbortSignal): Promise<void>;
+  change(previous: VirtualDocumentLike, next: VirtualDocumentLike, changes?: readonly TextChange[], signal?: AbortSignal): Promise<void>;
+  close(document: VirtualDocumentLike): Promise<void>;
+  request<T extends LanguageRequest>(request: T, context?: BridgeRequestContext, signal?: AbortSignal): Promise<LanguageResponse<T>>;
+  restart(): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+export function createTypeScriptLanguageBridge(options?: TypeScriptBridgeOptions): Promise<TypeScriptLanguageBridge>;
+export function createTypeScriptLanguageBridgeWithApi(typescript: unknown, options?: TypeScriptBridgeOptions): TypeScriptLanguageBridge;

package/src/index.js

@@ -0,0 +1,46 @@
+import { TypeScriptLanguageBridge } from "./typescript-bridge.js";
+
+const isTypeScriptApi = (value) =>
+  value && typeof value.createLanguageService === "function" &&
+  value.ScriptSnapshot && value.sys;
+
+const normalizeTypeScriptApi = (module) => {
+  if (isTypeScriptApi(module)) return module;
+  if (isTypeScriptApi(module?.default)) return module.default;
+  throw new TypeError("The supplied module is not a TypeScript compiler API.");
+};
+
+/**
+ * Create a bridge with an already loaded TypeScript compiler API.
+ *
+ * This entry point is useful to hosts that already own a TypeScript runtime,
+ * including editors and deterministic tests.
+ */
+export const createTypeScriptLanguageBridgeWithApi = (typescript, options = {}) =>
+  new TypeScriptLanguageBridge(normalizeTypeScriptApi(typescript), options);
+
+/**
+ * Load the optional TypeScript peer dependency and create a bridge.
+ */
+export const createTypeScriptLanguageBridge = async (options = {}) => {
+  if (options.typescript !== undefined) {
+    return createTypeScriptLanguageBridgeWithApi(options.typescript, options);
+  }
+  const specifier = options.typescriptModule ?? "typescript";
+  let module;
+  try {
+    module = options.loadTypeScript
+      ? await options.loadTypeScript(specifier)
+      : await import(specifier);
+  } catch (error) {
+    const failure = new Error(
+      "TypeScript is not available. Install the optional `typescript` peer dependency or pass `options.typescript`.",
+      { cause: error }
+    );
+    failure.code = "TYPESCRIPT_NOT_AVAILABLE";
+    throw failure;
+  }
+  return createTypeScriptLanguageBridgeWithApi(module, options);
+};
+
+export { TypeScriptLanguageBridge } from "./typescript-bridge.js";

package/src/normalize.js

@@ -0,0 +1,227 @@
+import { pathToFileURL } from "node:url";
+
+export const rangeForSpan = (span) => span === undefined
+  ? undefined
+  : { start: span.start, end: span.start + span.length };
+
+export const displayParts = (parts) =>
+  typeof parts === "string"
+    ? parts
+    : Array.isArray(parts) ? parts.map((part) => part.text).join("") : "";
+
+const tagsFor = (tags) => tags?.map((tag) => ({
+  name: tag.name,
+  text: typeof tag.text === "string" ? tag.text : displayParts(tag.text)
+})) ?? [];
+
+export const diagnosticSeverity = (ts, category) => {
+  if (category === ts.DiagnosticCategory.Error) return "error";
+  if (category === ts.DiagnosticCategory.Warning) return "warning";
+  if (category === ts.DiagnosticCategory.Suggestion) return "hint";
+  return "info";
+};
+
+const diagnosticMessage = (ts, message) =>
+  ts.flattenDiagnosticMessageText(message, "\n");
+
+export const createNormalizers = (ts, project) => {
+  const uriForFile = (fileName) => project.uriForFile(fileName) ?? pathToFileURL(fileName).href;
+
+  const location = (entry) => ({
+    uri: uriForFile(entry.fileName),
+    range: rangeForSpan(entry.textSpan),
+    name: entry.name,
+    kind: entry.kind,
+    containerName: entry.containerName,
+    ...(entry.contextSpan === undefined ? {} : { contextRange: rangeForSpan(entry.contextSpan) }),
+    ...(entry.isWriteAccess === undefined ? {} : { isWriteAccess: entry.isWriteAccess }),
+    ...(entry.isDefinition === undefined ? {} : { isDefinition: entry.isDefinition })
+  });
+
+  const relatedDiagnostic = (related) => ({
+    uri: related.file ? uriForFile(related.file.fileName) : undefined,
+    range: related.start === undefined
+      ? undefined
+      : { start: related.start, end: related.start + (related.length ?? 0) },
+    message: diagnosticMessage(ts, related.messageText)
+  });
+
+  const diagnostic = (entry, fallbackFileName) => ({
+    uri: entry.file ? uriForFile(entry.file.fileName) : uriForFile(fallbackFileName),
+    range: entry.start === undefined
+      ? { start: 0, end: 0 }
+      : { start: entry.start, end: entry.start + (entry.length ?? 0) },
+    code: entry.code,
+    severity: diagnosticSeverity(ts, entry.category),
+    message: diagnosticMessage(ts, entry.messageText),
+    source: "typescript",
+    related: entry.relatedInformation?.map(relatedDiagnostic) ?? []
+  });
+
+  const textChange = (entry) => ({ range: rangeForSpan(entry.span), text: entry.newText });
+  const fileTextChanges = (entry) => ({
+    uri: uriForFile(entry.fileName),
+    version: project.versionForFile(entry.fileName),
+    textChanges: entry.textChanges.map(textChange),
+    ...(entry.isNewFile === undefined ? {} : { isNewFile: entry.isNewFile })
+  });
+
+  const callItem = (entry) => ({
+    name: entry.name,
+    kind: entry.kind,
+    uri: uriForFile(entry.file),
+    range: rangeForSpan(entry.span),
+    selectionRange: rangeForSpan(entry.selectionSpan),
+    containerName: entry.containerName,
+    kindModifiers: entry.kindModifiers
+  });
+
+  return {
+    uriForFile,
+    location,
+    diagnostic,
+    fileTextChanges,
+    callItem,
+    completion(result) {
+      if (!result) return { items: [], isGlobal: false, isMember: false, isNewIdentifier: false };
+      return {
+        isGlobal: result.isGlobalCompletion === true,
+        isMember: result.isMemberCompletion === true,
+        isNewIdentifier: result.isNewIdentifierLocation === true,
+        optionalReplacementSpan: rangeForSpan(result.optionalReplacementSpan),
+        defaultCommitCharacters: result.defaultCommitCharacters,
+        items: result.entries.map((entry) => ({
+          name: entry.name,
+          kind: entry.kind,
+          kindModifiers: entry.kindModifiers,
+          sortText: entry.sortText,
+          insertText: entry.insertText,
+          filterText: entry.filterText,
+          replacementSpan: rangeForSpan(entry.replacementSpan),
+          source: entry.source,
+          hasAction: entry.hasAction === true,
+          isRecommended: entry.isRecommended === true,
+          isSnippet: entry.isSnippet === true,
+          commitCharacters: entry.commitCharacters,
+          data: entry.data
+        }))
+      };
+    },
+    completionDetails(result) {
+      if (!result) return undefined;
+      return {
+        name: result.name,
+        kind: result.kind,
+        kindModifiers: result.kindModifiers,
+        display: displayParts(result.displayParts),
+        documentation: displayParts(result.documentation),
+        tags: tagsFor(result.tags),
+        source: displayParts(result.source),
+        codeActions: result.codeActions?.map((action) => ({
+          description: action.description,
+          commands: action.commands,
+          changes: action.changes.map(fileTextChanges)
+        })) ?? []
+      };
+    },
+    hover(result) {
+      if (!result) return undefined;
+      return {
+        range: rangeForSpan(result.textSpan),
+        kind: result.kind,
+        kindModifiers: result.kindModifiers,
+        display: displayParts(result.displayParts),
+        documentation: displayParts(result.documentation),
+        tags: tagsFor(result.tags)
+      };
+    },
+    signature(result) {
+      if (!result) return undefined;
+      return {
+        applicableSpan: rangeForSpan(result.applicableSpan),
+        selectedItemIndex: result.selectedItemIndex,
+        argumentIndex: result.argumentIndex,
+        argumentCount: result.argumentCount,
+        items: result.items.map((item) => ({
+          isVariadic: item.isVariadic,
+          prefix: displayParts(item.prefixDisplayParts),
+          separator: displayParts(item.separatorDisplayParts),
+          suffix: displayParts(item.suffixDisplayParts),
+          documentation: displayParts(item.documentation),
+          tags: tagsFor(item.tags),
+          parameters: item.parameters.map((parameter) => ({
+            name: parameter.name,
+            display: displayParts(parameter.displayParts),
+            documentation: displayParts(parameter.documentation),
+            tags: tagsFor(parameter.tags),
+            isOptional: parameter.isOptional === true
+          }))
+        }))
+      };
+    },
+    locations(result) {
+      return result?.map(location) ?? [];
+    },
+    diagnostics(result, fallbackFileName) {
+      return result.map((entry) => diagnostic(entry, fallbackFileName));
+    },
+    callItems(result) {
+      if (!result) return [];
+      return (Array.isArray(result) ? result : [result]).map(callItem);
+    },
+    incomingCalls(result) {
+      return result?.map((entry) => ({
+        from: callItem(entry.from),
+        fromRanges: entry.fromSpans.map(rangeForSpan)
+      })) ?? [];
+    },
+    outgoingCalls(result) {
+      return result?.map((entry) => ({
+        to: callItem(entry.to),
+        fromRanges: entry.fromSpans.map(rangeForSpan)
+      })) ?? [];
+    },
+    renameLocations(result, newName) {
+      const grouped = new Map();
+      for (const entry of result ?? []) {
+        const uri = uriForFile(entry.fileName);
+        let group = grouped.get(uri);
+        if (!group) {
+          group = {
+            uri,
+            version: project.versionForFile(entry.fileName),
+            textChanges: []
+          };
+          grouped.set(uri, group);
+        }
+        const prefix = entry.prefixText ?? "";
+        const suffix = entry.suffixText ?? "";
+        group.textChanges.push({
+          range: rangeForSpan(entry.textSpan),
+          text: prefix + newName + suffix
+        });
+      }
+      return [...grouped.values()];
+    }
+  };
+};
+
+export const flattenNavigationTree = (tree, uri) => {
+  const symbols = [];
+  const visit = (item, containerName) => {
+    for (const span of item.spans ?? []) {
+      symbols.push({
+        name: item.text,
+        kind: item.kind,
+        kindModifiers: item.kindModifiers,
+        uri,
+        range: rangeForSpan(span),
+        selectionRange: rangeForSpan(item.nameSpan ?? span),
+        containerName
+      });
+    }
+    for (const child of item.childItems ?? []) visit(child, item.text);
+  };
+  if (tree) visit(tree, undefined);
+  return symbols;
+};

package/src/typescript-bridge.js

@@ -0,0 +1,478 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  BRIDGE_ERROR_CODES,
+  LanguageBridgeError,
+  assertLanguageRequest,
+  assertVirtualDocument,
+  bridgeError,
+  createBridgeCapabilities,
+  requireLanguageRequestSupport,
+  throwIfAborted
+} from "@pieceful/ravel-language-bridge";
+import { createNormalizers, flattenNavigationTree, rangeForSpan } from "./normalize.js";
+import {
+  TypeScriptProject,
+  resolveConfigPath,
+  resolveVirtualFileName
+} from "./typescript-project.js";
+
+const languageIds = Object.freeze([
+  "typescript",
+  "typescriptreact",
+  "javascript",
+  "javascriptreact"
+]);
+const supportedStages = Object.freeze(["authoring", "assembled"]);
+
+const capabilities = createBridgeCapabilities({
+  completion: { stages: supportedStages, triggerCharacters: [".", "\"", "'", "/", "@", "<", "#", " "], resolveProvider: true },
+  completionDetails: { stages: supportedStages },
+  hover: { stages: supportedStages },
+  signatureHelp: { stages: supportedStages, triggerCharacters: ["(", ",", "<"] },
+  definition: { stages: supportedStages },
+  typeDefinition: { stages: supportedStages },
+  references: { stages: supportedStages },
+  documentSymbols: { stages: supportedStages },
+  workspaceSymbols: { stages: supportedStages, workspaceProvider: true },
+  diagnostics: { stages: supportedStages },
+  prepareCallHierarchy: { stages: supportedStages },
+  incomingCalls: { stages: supportedStages },
+  outgoingCalls: { stages: supportedStages },
+  prepareRename: { stages: supportedStages },
+  rename: { stages: supportedStages }
+});
+
+const requestUri = (request, context) =>
+  request.documentUri ?? context.document?.uri ?? context.documentUri;
+
+const compareDiagnostics = (left, right) =>
+  left.uri.localeCompare(right.uri) || left.range.start - right.range.start ||
+  left.range.end - right.range.end || String(left.code).localeCompare(String(right.code));
+
+const dedupeDiagnostics = (diagnostics) => {
+  const seen = new Set();
+  return diagnostics.filter((entry) => {
+    const key = [entry.uri, entry.range.start, entry.range.end, entry.code, entry.message].join("\0");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).sort(compareDiagnostics);
+};
+
+const positionFor = (request) => {
+  if (!Number.isInteger(request.position) || request.position < 0) {
+    throw new LanguageBridgeError(
+      BRIDGE_ERROR_CODES.INVALID_REQUEST,
+      request.kind + " requires a non-negative integer position."
+    );
+  }
+  return request.position;
+};
+
+const normalizeWorkspaceSymbol = (normalizers, item) => ({
+  name: item.name,
+  kind: item.kind,
+  kindModifiers: item.kindModifiers,
+  uri: normalizers.uriForFile(item.fileName),
+  range: rangeForSpan(item.textSpan),
+  selectionRange: rangeForSpan(item.matchKind === "exact" ? item.textSpan : item.textSpan),
+  containerName: item.containerName
+});
+
+export class TypeScriptLanguageBridge {
+  constructor(ts, options = {}) {
+    this.ts = ts;
+    const currentDirectory = path.resolve(options.currentDirectory ?? ts.sys.getCurrentDirectory());
+    this.options = {
+      currentDirectory,
+      configSearchRoot: path.resolve(currentDirectory, options.configSearchRoot ?? "."),
+      fileURLToPath,
+      compilerOptions: options.compilerOptions,
+      tsconfigPath: options.tsconfigPath,
+      configFileForDocument: options.configFileForDocument,
+      fileNameForDocument: options.fileNameForDocument,
+      completionOptions: options.completionOptions ?? {},
+      userPreferences: options.userPreferences ?? {},
+      formatOptions: options.formatOptions ?? {}
+    };
+    this.languageIds = languageIds;
+    this.capabilities = capabilities;
+    this.documents = new Map();
+    this.projects = new Map();
+    this.lifecycleState = "ready";
+    this.restartDocuments = undefined;
+  }
+
+  get state() { return this.lifecycleState; }
+
+  assertReady() {
+    if (this.lifecycleState === "disposed") {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.DISPOSED, "The TypeScript language bridge is disposed.");
+    }
+    if (this.lifecycleState === "failed") {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.CRASHED, "The TypeScript language bridge must be restarted.", { retryable: true });
+    }
+  }
+
+  projectKey(configPath, targetId, stage) {
+    const target = String(targetId ?? "default");
+    const projectionStage = String(stage ?? "assembled");
+    if (!configPath) {
+      return JSON.stringify([target, projectionStage, "inferred", this.options.currentDirectory]);
+    }
+    return JSON.stringify([target, projectionStage, "configured", path.normalize(configPath)]);
+  }
+
+  ensureProject(configPath, targetId, stage) {
+    const key = this.projectKey(configPath, targetId, stage);
+    let project = this.projects.get(key);
+    if (!project) {
+      project = new TypeScriptProject(
+        this.ts,
+        key,
+        configPath,
+        this.options,
+        this.ts.createDocumentRegistry(
+          this.ts.sys.useCaseSensitiveFileNames,
+          this.options.currentDirectory
+        )
+      );
+      this.projects.set(key, project);
+    }
+    return project;
+  }
+
+  createEntry(document) {
+    if (!this.languageIds.includes(document.languageId)) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.NOT_SUPPORTED,
+        "Unsupported TypeScript bridge language ID: " + document.languageId + ".",
+        { details: { languageId: document.languageId, supported: this.languageIds } }
+      );
+    }
+    const fileName = resolveVirtualFileName(document, this.options);
+    const configPath = resolveConfigPath(this.ts, document, fileName, this.options);
+    const project = this.ensureProject(configPath, document.targetId, document.stage);
+    return { uri: document.uri, document, fileName, project, configPath };
+  }
+
+  async open(document, signal) {
+    this.assertReady();
+    throwIfAborted(signal);
+    assertVirtualDocument(document);
+    const current = this.documents.get(document.uri);
+    if (current) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.DOCUMENT_COLLISION,
+        "The virtual document is already open: " + document.uri + ".",
+        { details: { uri: document.uri, version: current.document.version } }
+      );
+    }
+    try {
+      const entry = this.createEntry(document);
+      // Cancellation is accepted up to this commit boundary. Once the project
+      // and bridge indexes start changing, open must either finish or roll
+      // back; reporting ABORTED after a successful commit would leave callers
+      // believing the document is closed while it is actually open here.
+      throwIfAborted(signal);
+      entry.project.add(entry);
+      this.documents.set(document.uri, entry);
+    } catch (error) {
+      throw bridgeError(error, {
+        code: BRIDGE_ERROR_CODES.PROJECT_ERROR,
+        message: "TypeScript could not open " + document.uri + ": " + (error?.message ?? String(error)),
+        details: { uri: document.uri, version: document.version }
+      });
+    }
+  }
+
+  async change(previous, next, changes = [], signal) {
+    this.assertReady();
+    throwIfAborted(signal);
+    assertVirtualDocument(previous);
+    assertVirtualDocument(next);
+    const current = this.documents.get(previous.uri);
+    if (!current) {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.DOCUMENT_NOT_OPEN, "The virtual document is not open: " + previous.uri + ".");
+    }
+    if (current.document.version !== previous.version || next.uri !== previous.uri) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.STALE_DOCUMENT,
+        "The TypeScript change does not match the currently open document.",
+        { details: { currentVersion: current.document.version, previousVersion: previous.version, uri: previous.uri } }
+      );
+    }
+    if (next.version <= current.document.version) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.VERSION_REGRESSION,
+        "Virtual document versions must increase monotonically.",
+        { details: { currentVersion: current.document.version, nextVersion: next.version, uri: next.uri } }
+      );
+    }
+
+    let nextFileName;
+    let nextConfigPath;
+    let nextProject;
+    try {
+      nextFileName = resolveVirtualFileName(next, this.options);
+      nextConfigPath = resolveConfigPath(this.ts, next, nextFileName, this.options);
+      nextProject = this.ensureProject(nextConfigPath, next.targetId, next.stage);
+    } catch (error) {
+      throw bridgeError(error, {
+        code: BRIDGE_ERROR_CODES.PROJECT_ERROR,
+        message: "TypeScript could not update " + next.uri + ": " + (error?.message ?? String(error)),
+        details: { uri: next.uri, version: next.version }
+      });
+    }
+    // This is the change commit boundary. Do not observe cancellation again
+    // after removing the current entry: the rollback below only covers a
+    // failed commit, while a successful commit must be reported as success.
+    throwIfAborted(signal);
+    current.project.remove(current);
+    const entry = {
+      uri: next.uri,
+      document: next,
+      fileName: nextFileName,
+      project: nextProject,
+      configPath: nextConfigPath,
+      changes: [...changes]
+    };
+    try {
+      nextProject.add(entry);
+      this.documents.set(next.uri, entry);
+    } catch (error) {
+      current.project.add(current);
+      throw bridgeError(error, {
+        code: BRIDGE_ERROR_CODES.PROJECT_ERROR,
+        message: "TypeScript could not update " + next.uri + ": " + (error?.message ?? String(error)),
+        details: { uri: next.uri, version: next.version }
+      });
+    }
+  }
+
+  async close(document) {
+    this.assertReady();
+    assertVirtualDocument(document);
+    const current = this.documents.get(document.uri);
+    if (!current) {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.DOCUMENT_NOT_OPEN, "The virtual document is not open: " + document.uri + ".");
+    }
+    current.project.remove(current);
+    this.documents.delete(document.uri);
+  }
+
+  resolveRequest(request, context) {
+    const uri = requestUri(request, context);
+    if (typeof uri !== "string" || uri.length === 0) {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.INVALID_REQUEST, request.kind + " requires a document URI.");
+    }
+    const entry = this.documents.get(uri);
+    if (!entry) {
+      throw new LanguageBridgeError(BRIDGE_ERROR_CODES.DOCUMENT_NOT_OPEN, "The request document is not open: " + uri + ".");
+    }
+    const expectedVersion = context.version ?? context.document?.version;
+    if (expectedVersion !== undefined && expectedVersion !== entry.document.version) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.STALE_DOCUMENT,
+        "The request targets a stale virtual document version.",
+        { details: { expectedVersion, currentVersion: entry.document.version, uri } }
+      );
+    }
+    return entry;
+  }
+
+  async request(request, context = {}, signal) {
+    this.assertReady();
+    throwIfAborted(signal);
+    assertLanguageRequest(request);
+    requireLanguageRequestSupport(this, request, {
+      ...context,
+      stage: context.document?.stage ?? context.stage ?? "assembled"
+    });
+    const entry = this.resolveRequest(request, context);
+    const project = entry.project;
+    const service = project.service;
+    const normalizers = createNormalizers(this.ts, project);
+    project.activeSignal = signal;
+    try {
+      let result;
+      switch (request.kind) {
+        case "completion":
+          result = normalizers.completion(service.getCompletionsAtPosition(
+            entry.fileName,
+            positionFor(request),
+            { ...this.options.completionOptions, ...request.options },
+            request.formatOptions ?? this.options.formatOptions
+          ));
+          break;
+        case "completionDetails":
+          if (typeof request.name !== "string" || request.name.length === 0) {
+            throw new LanguageBridgeError(BRIDGE_ERROR_CODES.INVALID_REQUEST, "completionDetails requires an entry name.");
+          }
+          result = normalizers.completionDetails(service.getCompletionEntryDetails(
+            entry.fileName,
+            positionFor(request),
+            request.name,
+            request.formatOptions ?? this.options.formatOptions,
+            request.source,
+            { ...this.options.userPreferences, ...request.preferences },
+            request.data
+          ));
+          break;
+        case "hover":
+          result = normalizers.hover(service.getQuickInfoAtPosition(entry.fileName, positionFor(request)));
+          break;
+        case "signatureHelp":
+          result = normalizers.signature(service.getSignatureHelpItems(
+            entry.fileName,
+            positionFor(request),
+            {
+              triggerReason: { kind: "invoked" },
+              ...(request.options ?? {})
+            }
+          ));
+          break;
+        case "definition":
+          result = normalizers.locations(service.getDefinitionAtPosition(entry.fileName, positionFor(request)));
+          break;
+        case "typeDefinition":
+          result = normalizers.locations(service.getTypeDefinitionAtPosition(entry.fileName, positionFor(request)));
+          break;
+        case "references":
+          result = normalizers.locations(service.getReferencesAtPosition(entry.fileName, positionFor(request)));
+          break;
+        case "documentSymbols":
+          result = flattenNavigationTree(
+            service.getNavigationTree(entry.fileName),
+            normalizers.uriForFile(entry.fileName)
+          );
+          break;
+        case "workspaceSymbols":
+          result = service.getNavigateToItems(
+            typeof request.query === "string" ? request.query : "",
+            request.maximumResultCount,
+            request.excludeFileName,
+            request.excludeDtsFiles === true
+          ).map((item) => normalizeWorkspaceSymbol(normalizers, item));
+          break;
+        case "diagnostics": {
+          const categories = new Set(request.categories ?? ["configuration", "compilerOptions", "syntactic", "semantic", "suggestion"]);
+          const diagnostics = [];
+          if (categories.has("configuration")) {
+            diagnostics.push(...project.configuration.diagnostics.filter((diagnostic) =>
+              diagnostic.code !== 18003 || project.documents.size === 0));
+          }
+          if (categories.has("compilerOptions")) diagnostics.push(...service.getCompilerOptionsDiagnostics());
+          if (categories.has("syntactic")) diagnostics.push(...service.getSyntacticDiagnostics(entry.fileName));
+          if (categories.has("semantic")) diagnostics.push(...service.getSemanticDiagnostics(entry.fileName));
+          if (categories.has("suggestion")) diagnostics.push(...service.getSuggestionDiagnostics(entry.fileName));
+          result = dedupeDiagnostics(normalizers.diagnostics(diagnostics, entry.fileName));
+          break;
+        }
+        case "prepareCallHierarchy":
+          result = normalizers.callItems(service.prepareCallHierarchy(entry.fileName, positionFor(request)));
+          break;
+        case "incomingCalls":
+          result = normalizers.incomingCalls(service.provideCallHierarchyIncomingCalls(entry.fileName, positionFor(request)));
+          break;
+        case "outgoingCalls":
+          result = normalizers.outgoingCalls(service.provideCallHierarchyOutgoingCalls(entry.fileName, positionFor(request)));
+          break;
+        case "prepareRename": {
+          const info = service.getRenameInfo(
+            entry.fileName,
+            positionFor(request),
+            { allowRenameOfImportPath: request.allowRenameOfImportPath === true }
+          );
+          result = info.canRename
+            ? {
+                canRename: true,
+                range: rangeForSpan(info.triggerSpan),
+                placeholder: info.displayName,
+                fullDisplayName: info.fullDisplayName,
+                kind: info.kind,
+                kindModifiers: info.kindModifiers
+              }
+            : { canRename: false, reason: info.localizedErrorMessage };
+          break;
+        }
+        case "rename": {
+          if (typeof request.newName !== "string" || request.newName.length === 0) {
+            throw new LanguageBridgeError(BRIDGE_ERROR_CODES.INVALID_REQUEST, "rename requires a non-empty newName.");
+          }
+          const position = positionFor(request);
+          const info = service.getRenameInfo(
+            entry.fileName,
+            position,
+            { allowRenameOfImportPath: request.allowRenameOfImportPath === true }
+          );
+          result = info.canRename
+            ? {
+                canRename: true,
+                changes: normalizers.renameLocations(service.findRenameLocations(
+                  entry.fileName,
+                  position,
+                  request.findInStrings === true,
+                  request.findInComments === true,
+                  request.providePrefixAndSuffixTextForRename === true
+                ), request.newName)
+              }
+            : { canRename: false, reason: info.localizedErrorMessage, changes: [] };
+          break;
+        }
+      }
+      throwIfAborted(signal);
+      if (entry.document.version !== (context.version ?? context.document?.version ?? entry.document.version)) {
+        throw new LanguageBridgeError(BRIDGE_ERROR_CODES.STALE_DOCUMENT, "The language response was superseded by a newer projection.", { retryable: true });
+      }
+      return result;
+    } catch (error) {
+      if (signal?.aborted) throwIfAborted(signal);
+      throw bridgeError(error, {
+        code: BRIDGE_ERROR_CODES.PROJECT_ERROR,
+        message: "TypeScript " + request.kind + " failed: " + (error?.message ?? String(error)),
+        retryable: true,
+        details: { kind: request.kind, uri: entry.uri, version: entry.document.version }
+      });
+    } finally {
+      project.activeSignal = undefined;
+    }
+  }
+
+  async restart() {
+    if (this.lifecycleState === "disposed") this.assertReady();
+    this.lifecycleState = "restarting";
+    const documents = this.restartDocuments ??
+      [...this.documents.values()].map((entry) => entry.document);
+    this.restartDocuments = documents;
+    for (const project of this.projects.values()) project.dispose();
+    this.projects.clear();
+    this.documents.clear();
+    try {
+      for (const document of documents) {
+        const entry = this.createEntry(document);
+        entry.project.add(entry);
+        this.documents.set(entry.uri, entry);
+      }
+      this.lifecycleState = "ready";
+      this.restartDocuments = undefined;
+    } catch (error) {
+      this.lifecycleState = "failed";
+      throw bridgeError(error, {
+        code: BRIDGE_ERROR_CODES.CRASHED,
+        message: "The TypeScript language bridge could not restart.",
+        retryable: true
+      });
+    }
+  }
+
+  async dispose() {
+    if (this.lifecycleState === "disposed") return;
+    for (const project of this.projects.values()) project.dispose();
+    this.projects.clear();
+    this.documents.clear();
+    this.restartDocuments = undefined;
+    this.lifecycleState = "disposed";
+  }
+}

package/src/typescript-project.js

@@ -0,0 +1,343 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { BRIDGE_ERROR_CODES, LanguageBridgeError } from "@pieceful/ravel-language-bridge";
+
+const languageExtensions = Object.freeze({
+  typescript: ".ts",
+  typescriptreact: ".tsx",
+  javascript: ".js",
+  javascriptreact: ".jsx"
+});
+
+const languageScriptKind = (ts, languageId, fileName) => {
+  if (languageId === "typescript") return ts.ScriptKind.TS;
+  if (languageId === "typescriptreact") return ts.ScriptKind.TSX;
+  if (languageId === "javascript") return ts.ScriptKind.JS;
+  if (languageId === "javascriptreact") return ts.ScriptKind.JSX;
+  return ts.getScriptKindFromFileName?.(fileName) ?? ts.ScriptKind.Unknown;
+};
+
+const hash = (text) => {
+  let value = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    value ^= text.charCodeAt(index);
+    value = Math.imul(value, 16777619);
+  }
+  return (value >>> 0).toString(36);
+};
+
+const absolute = (currentDirectory, value) =>
+  path.isAbsolute(value) ? path.normalize(value) : path.resolve(currentDirectory, value);
+
+const comparablePath = (ts, value) => {
+  const resolved = path.resolve(value);
+  return ts.sys.useCaseSensitiveFileNames ? resolved : resolved.toLowerCase();
+};
+
+const containedIn = (ts, root, candidate) => {
+  const relative = path.relative(
+    comparablePath(ts, root),
+    comparablePath(ts, candidate)
+  );
+  return relative === "" ||
+    relative !== ".." && !relative.startsWith(".." + path.sep) &&
+    !path.isAbsolute(relative);
+};
+
+// Resolve the nearest existing ancestor so a not-yet-created config beneath a
+// symlinked directory is checked against the directory's canonical location.
+const canonicalPotentialPath = (ts, value) => {
+  const original = path.resolve(value);
+  if (typeof ts.sys.realpath !== "function") return original;
+  const suffix = [];
+  let current = original;
+  while (true) {
+    const exists = ts.sys.fileExists?.(current) === true ||
+      ts.sys.directoryExists?.(current) === true;
+    if (exists) {
+      try {
+        const canonical = ts.sys.realpath(current);
+        if (typeof canonical === "string" && canonical.length > 0) {
+          return path.resolve(canonical, ...suffix);
+        }
+      } catch {
+        // Continue with the nearest existing parent. A failed realpath must not
+        // turn an outside candidate into an allowed path.
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return original;
+    suffix.unshift(path.basename(current));
+    current = parent;
+  }
+};
+
+const confinedConfigPath = (ts, value, options) => {
+  const candidate = absolute(options.currentDirectory, value);
+  const root = path.resolve(options.configSearchRoot ?? options.currentDirectory);
+  if (!containedIn(ts, root, candidate)) return undefined;
+  const canonicalRoot = canonicalPotentialPath(ts, root);
+  const canonicalCandidate = canonicalPotentialPath(ts, candidate);
+  return containedIn(ts, canonicalRoot, canonicalCandidate)
+    ? canonicalCandidate
+    : undefined;
+};
+
+const discoverConfigPath = (ts, fileName, options) => {
+  const root = path.resolve(options.configSearchRoot ?? options.currentDirectory);
+  let directory = path.dirname(path.resolve(fileName));
+  if (!containedIn(ts, root, directory) ||
+      !containedIn(ts, canonicalPotentialPath(ts, root), canonicalPotentialPath(ts, directory))) {
+    return undefined;
+  }
+  while (containedIn(ts, root, directory)) {
+    const candidate = path.join(directory, "tsconfig.json");
+    if (ts.sys.fileExists(candidate)) {
+      const confined = confinedConfigPath(ts, candidate, options);
+      if (confined) return confined;
+    }
+    if (comparablePath(ts, directory) === comparablePath(ts, root)) break;
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return undefined;
+};
+
+const safeRelativeArtifactPath = (value) => {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0") ||
+      path.isAbsolute(value) || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) return undefined;
+  const normalized = path.normalize(value);
+  if (normalized === "." || normalized === ".." || normalized.startsWith(".." + path.sep)) {
+    return undefined;
+  }
+  return normalized;
+};
+
+export const resolveVirtualFileName = (document, options) => {
+  const configured = options.fileNameForDocument?.(document) ??
+    document.fileName ?? document.path ?? document.artifactPath ?? document.outputPath ??
+    document.metadata?.fileName ?? document.metadata?.artifactPath ?? document.metadata?.outputPath;
+  if (typeof configured === "string" && configured.length > 0) {
+    return absolute(options.currentDirectory, configured);
+  }
+  if (document.uri.startsWith("file:")) {
+    return options.fileURLToPath(document.uri);
+  }
+  const artifactPath = safeRelativeArtifactPath(document.artifactId);
+  if (artifactPath !== undefined) return path.resolve(options.currentDirectory, artifactPath);
+  const extension = languageExtensions[document.languageId] ?? ".txt";
+  const base = String(document.artifactId ?? "projection")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^[-.]+|[-.]+$/g, "") || "projection";
+  return path.join(options.currentDirectory, ".ravel-virtual", hash(document.uri) + "-" + base + extension);
+};
+
+export const resolveConfigPath = (ts, document, fileName, options) => {
+  const configured = options.configFileForDocument?.(document, fileName) ??
+    document.tsconfigPath ?? document.metadata?.tsconfigPath ?? options.tsconfigPath;
+  if (typeof configured === "string" && configured.length > 0) {
+    const confined = confinedConfigPath(ts, configured, options);
+    if (confined) return confined;
+  }
+  return discoverConfigPath(ts, fileName, options);
+};
+
+const inferredOptions = (ts, overrides = {}) => ({
+  target: ts.ScriptTarget.ES2022 ?? ts.ScriptTarget.ES2020,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler ?? ts.ModuleResolutionKind.Node10 ?? ts.ModuleResolutionKind.NodeJs,
+  allowJs: true,
+  checkJs: true,
+  jsx: ts.JsxEmit.Preserve,
+  allowNonTsExtensions: true,
+  ...(ts.ModuleDetectionKind?.Force === undefined
+    ? {}
+    : { moduleDetection: ts.ModuleDetectionKind.Force }),
+  ...overrides
+});
+
+const readConfiguredProject = (ts, configPath, overrides) => {
+  if (!configPath) return {
+    currentDirectory: undefined,
+    fileNames: [],
+    options: inferredOptions(ts, overrides),
+    diagnostics: []
+  };
+  const read = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (read.error) {
+    return {
+      currentDirectory: path.dirname(configPath),
+      fileNames: [],
+      options: inferredOptions(ts, overrides),
+      diagnostics: [read.error]
+    };
+  }
+  const parsed = ts.parseJsonConfigFileContent(
+    read.config,
+    ts.sys,
+    path.dirname(configPath),
+    overrides,
+    configPath
+  );
+  return {
+    currentDirectory: path.dirname(configPath),
+    fileNames: parsed.fileNames,
+    options: { ...parsed.options, allowNonTsExtensions: true },
+    diagnostics: parsed.errors ?? [],
+    projectReferences: parsed.projectReferences
+  };
+};
+
+export class TypeScriptProject {
+  constructor(ts, key, configPath, options, documentRegistry) {
+    this.ts = ts;
+    this.key = key;
+    this.configPath = configPath;
+    this.options = options;
+    this.documents = new Map();
+    this.uriByCanonicalFile = new Map();
+    this.scriptVersionSequence = 0;
+    this.projectVersion = 0;
+    this.activeSignal = undefined;
+    this.configuration = readConfiguredProject(ts, configPath, options.compilerOptions);
+    this.currentDirectory = this.configuration.currentDirectory ?? options.currentDirectory;
+    this.configuredFiles = new Set(this.configuration.fileNames.map((file) => this.canonical(file)));
+    this.host = this.createHost();
+    this.service = ts.createLanguageService(this.host, documentRegistry);
+  }
+
+  canonical(fileName) {
+    const normalized = path.normalize(fileName);
+    return this.ts.sys.useCaseSensitiveFileNames ? normalized : normalized.toLowerCase();
+  }
+
+  uriForFile(fileName) {
+    return this.uriByCanonicalFile.get(this.canonical(fileName)) ?? pathToFileURL(fileName).href;
+  }
+
+  versionForFile(fileName) {
+    return this.documents.get(this.canonical(fileName))?.document.version;
+  }
+
+  add(entry) {
+    const key = this.canonical(entry.fileName);
+    const collision = this.documents.get(key);
+    if (collision && collision.uri !== entry.uri) {
+      throw new LanguageBridgeError(
+        BRIDGE_ERROR_CODES.DOCUMENT_COLLISION,
+        "Two virtual documents resolve to the same TypeScript file: " + entry.fileName + ".",
+        { details: { firstUri: collision.uri, secondUri: entry.uri, fileName: entry.fileName } }
+      );
+    }
+    entry.scriptKind = languageScriptKind(this.ts, entry.document.languageId, entry.fileName);
+    const documentVersion = String(entry.document.version);
+    // TypeScript caches snapshots by the host's script-version token. Ravel
+    // document versions may restart after a same-path projection is closed and
+    // reopened, so every insertion gets a fresh token, including later reopens.
+    entry.scriptVersion = documentVersion + ":r" + String(++this.scriptVersionSequence);
+    this.documents.set(key, entry);
+    this.uriByCanonicalFile.set(key, entry.uri);
+    this.projectVersion += 1;
+  }
+
+  remove(entry) {
+    const key = this.canonical(entry.fileName);
+    this.documents.delete(key);
+    this.uriByCanonicalFile.delete(key);
+    this.projectVersion += 1;
+  }
+
+  createHost() {
+    const ts = this.ts;
+    const project = this;
+    const sys = ts.sys;
+    const virtualEntry = (fileName) => project.documents.get(project.canonical(fileName));
+    const virtualDirectoryExists = (directory) => {
+      const prefix = project.canonical(directory).replace(/[\\/]+$/, "") + path.sep;
+      return [...project.documents.keys()].some((fileName) => fileName.startsWith(prefix));
+    };
+    const virtualDirectories = (directory) => {
+      const prefix = project.canonical(directory).replace(/[\\/]+$/, "") + path.sep;
+      const directories = new Set();
+      for (const fileName of project.documents.keys()) {
+        if (!fileName.startsWith(prefix)) continue;
+        const remainder = fileName.slice(prefix.length);
+        const separator = remainder.indexOf(path.sep);
+        if (separator >= 0) directories.add(path.join(directory, remainder.slice(0, separator)));
+      }
+      return [...directories];
+    };
+    const host = {
+      getCompilationSettings: () => project.configuration.options,
+      getCurrentDirectory: () => project.currentDirectory,
+      getDefaultLibFileName: (options) => ts.getDefaultLibFilePath(options),
+      getNewLine: () => sys.newLine,
+      getProjectReferences: () => project.configuration.projectReferences,
+      getProjectVersion: () => String(project.projectVersion),
+      getScriptFileNames: () => {
+        const configured = project.configuration.fileNames;
+        const virtual = [...project.documents.values()].map((entry) => entry.fileName);
+        return [...new Set([...configured, ...virtual])];
+      },
+      getScriptKind: (fileName) => virtualEntry(fileName)?.scriptKind ??
+        ts.getScriptKindFromFileName?.(fileName),
+      getScriptSnapshot: (fileName) => {
+        const entry = virtualEntry(fileName);
+        if (entry) return ts.ScriptSnapshot.fromString(entry.document.text);
+        const text = sys.readFile(fileName);
+        return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+      },
+      getScriptVersion: (fileName) => {
+        const entry = virtualEntry(fileName);
+        if (entry) return entry.scriptVersion;
+        return String(sys.getModifiedTime?.(fileName)?.valueOf() ?? 0);
+      },
+      fileExists: (fileName) => virtualEntry(fileName) !== undefined || sys.fileExists(fileName),
+      readFile: (fileName, encoding) => virtualEntry(fileName)?.document.text ?? sys.readFile(fileName, encoding),
+      readDirectory: (...args) => sys.readDirectory(...args),
+      directoryExists: (directory) => virtualDirectoryExists(directory) || sys.directoryExists?.(directory) === true,
+      getDirectories: (directory) => [...new Set([
+        ...(sys.getDirectories?.(directory) ?? []),
+        ...virtualDirectories(directory)
+      ])],
+      realpath: (fileName) => virtualEntry(fileName)?.fileName ?? sys.realpath?.(fileName) ?? fileName,
+      useCaseSensitiveFileNames: () => sys.useCaseSensitiveFileNames,
+      getCancellationToken: () => ({
+        isCancellationRequested: () => project.activeSignal?.aborted === true,
+        throwIfCancellationRequested: () => {
+          if (!project.activeSignal?.aborted) return;
+          if (typeof ts.OperationCanceledException === "function") throw new ts.OperationCanceledException();
+          throw project.activeSignal.reason ?? new Error("TypeScript operation cancelled.");
+        }
+      })
+    };
+    if (typeof ts.resolveModuleName === "function") {
+      host.resolveModuleNames = (moduleNames, containingFile, _reusedNames, redirectedReference, compilerOptions) =>
+        moduleNames.map((moduleName) => ts.resolveModuleName(
+          moduleName,
+          containingFile,
+          compilerOptions ?? project.configuration.options,
+          host,
+          undefined,
+          redirectedReference
+        ).resolvedModule);
+      host.resolveModuleNameLiterals = (moduleLiterals, containingFile, redirectedReference, compilerOptions) =>
+        moduleLiterals.map((literal) => ({
+          resolvedModule: ts.resolveModuleName(
+            literal.text,
+            containingFile,
+            compilerOptions ?? project.configuration.options,
+            host,
+            undefined,
+            redirectedReference
+          ).resolvedModule
+        }));
+    }
+    return host;
+  }
+
+  dispose() {
+    this.service.dispose();
+  }
+}