@manifest-configuration-language/browser 0.1.6 → 0.3.0

package/README.md

@@ -21,13 +21,17 @@ try {
 
 Call `runtime.warmUp()` to load the WebAssembly runtime before the first project operation. Pass `signal` and `timeoutMs` to warm-up or an operation to cancel it or set an upper bound for that call. Warm-up's timeout and `initializationTimeoutMs` bound worker startup; an operation's `timeoutMs` bounds execution after startup. Cancelling or timing out worker startup terminates that worker; the next queued operation can create a fresh worker. Cancelling or timing out an operation terminates its worker. Operations and warm-up are serialized because the current Go runtime uses one in-memory project root.
 
-Project files can be UTF-8 strings or `Uint8Array` values. UTF-8 files remain inline in the JSON request. The Browser SDK copies each `Uint8Array` and transfers its buffer to the Worker; the Worker sends only `{ "encoding": "binary" }` metadata in the request JSON and passes a path-to-`Uint8Array` map as the second argument to `mclWasm.run(requestJSON, binaryFiles)`. The Go runtime copies those bytes into its project filesystem. The SDK-owned and caller-owned arrays remain reusable after each operation.
+Project files can be UTF-8 strings or `Uint8Array` values. UTF-8 files remain inline in project updates. The Browser SDK copies each changed `Uint8Array` and transfers its buffer to the Worker; the Worker sends only `{ "encoding": "binary" }` metadata in the update JSON and passes a path-to-`Uint8Array` map to the Go/WASM project session. The Go runtime copies those bytes into its bounded project filesystem. The SDK-owned and caller-owned arrays remain reusable after each update.
+
+An open project is a Worker-backed session. Call `project.update(files)` with the complete next snapshot when project files change, then use the returned project handle for subsequent operations. The SDK validates changed files, sends only changed, added, and removed files to the Worker, and applies those deltas to a bounded in-memory Go/WASM filesystem. Each operation sends its entrypoint source and session ID; the project filesystem is not resent or rebuilt. If a canceled or timed-out operation terminates the Worker, the next operation restores the complete snapshot before running. Existing `runtime.parse`, `runtime.render`, and other source-based methods continue to use per-request files.
+
+`runtime.render` returns a `sourceMap` alongside the YAML. Each entry identifies a YAML document, a JSON Pointer within that document, and whether the output range covers a key or value. Source ranges use zero-based UTF-16 line and character positions with an exclusive end, matching LSP and CodeMirror positions; the engine converts its internal UTF-8 byte offsets before returning them. Source paths are project-relative. The source map is limited by `maxSourceMapBytes`; `sourceMap.complete` is false when the map was truncated or an MCL source range could not be resolved.
 
 `project.complete({ entrypoint, position })` returns the MCL language-service candidates for a zero-based UTF-16 position. Completion uses the same local project files as parsing and rendering, including schemas and Helm values schemas. It does not access a Kubernetes API server or any other network service.
 
-`project.definition({ entrypoint, position })` returns a project-relative declaration path and zero-based UTF-16 range for local and imported MCL declarations. `project.hover({ entrypoint, position })` returns declaration syntax, including explicit type annotations and function or rule signatures. Hover does not infer runtime value types, and both operations use only project files already supplied to the browser runtime.
+`project.definition({ entrypoint, position })` returns a project-relative declaration path and zero-based UTF-16 range for local and imported MCL declarations. `project.hover({ entrypoint, position })` returns declaration syntax, including explicit type annotations and function or rule signatures. `project.references({ entrypoint, position })` returns the declaration and references found in the supplied MCL project. These operations use only project files already supplied to the browser runtime.
 
-The package exports the completion, definition, and hover result types, `maxSourceBytes`, `maxProjectFiles`, `maxProjectFileBytes`, and `maxProjectBytes` so browser interfaces can consume the runtime's public types and limits.
+The package exports the completion, definition, hover, references, rename, and source map result types, `maxSourceBytes`, `maxSourceMapBytes`, `maxRenameNameLength`, `maxProjectFiles`, `maxProjectFileBytes`, and `maxProjectBytes` so browser interfaces can consume the runtime's public types and limits. `isValidProjectFileSet(paths)` checks path validity, duplicate paths, and file/directory conflicts before a UI creates or renames project files. `rename()` returns edits for local symbols and exported declarations, including qualified value and type references in the supplied MCL project. It returns no edits when a rename would be ambiguous or collide with an existing exported declaration.
 
 MCL decodes the request into a root-relative `io/fs` filesystem for project files, module imports, schemas, and dependency locks. Kubernetes resource scope checks use built-in metadata and CRDs in the project; unknown resource kinds can still be rendered. The runtime limits are defined in the [protocol schema](https://github.com/manifest-configuration-language/mcl/blob/main/cmd/mcl-wasm/protocol.schema.json). The worker blocks `fetch` after loading the WASM runtime assets, so MCL project evaluation cannot make external network requests.
 

package/dist/mcl.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/dist/mcl.wasm
-size: 96170429 bytes
-sha256: d08ad3914d8a2862e52db7dbc3ec43c38c1143dea99dda6c87383c7d59212c7d
+size: 96778456 bytes
+sha256: 037981cf0ac4773dca73ca1cd9ddffa8b9e9b25aedb15d8c72b1be8ea26c5558

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manifest-configuration-language/browser",
-  "version": "0.1.6",
+  "version": "0.3.0",
   "description": "Run MCL projects in a browser Web Worker using the Go WebAssembly runtime.",
   "repository": {
     "type": "git",

package/src/index.d.ts

@@ -13,22 +13,32 @@ import type {
   LintDiagnostic as ProtocolLintDiagnostic,
   ParseResult,
   RelatedLocation as ProtocolRelatedLocation,
+  ReferenceLocation as ProtocolReferenceLocation,
+  ReferencesResult as ProtocolReferencesResult,
   RenderResult,
+  RenameEdit as ProtocolRenameEdit,
+  RenameResult as ProtocolRenameResult,
   Request as WasmRequest,
   SourceRange as ProtocolSourceRange,
+  SourceMap as ProtocolSourceMap,
+  SourceMapEntry as ProtocolSourceMapEntry,
+  SourceMapOrigin as ProtocolSourceMapOrigin,
 } from "./protocol.js";
 
 export type MclOperation = WasmRequest["operation"];
 
 export declare const maxSourceBytes: number;
+export declare const maxSourceMapBytes: number;
+export declare const maxRenameNameLength: number;
 export declare const maxProjectFiles: number;
 export declare const maxProjectFileBytes: number;
 export declare const maxProjectBytes: number;
 export declare const maxProjectPathLength: number;
 export declare const maxProjectPathDepth: number;
 export declare function isValidProjectPath(path: unknown): path is string;
+export declare function isValidProjectFileSet(paths: readonly string[]): boolean;
 
-/** Root-relative project files passed to MCL's per-request filesystem. Uint8Array values are copied before transfer so callers can reuse them. */
+/** Root-relative project files passed to MCL's in-memory session filesystem. Uint8Array values are copied before transfer so callers can reuse them. */
 export type ProjectFile = string | Uint8Array;
 export type ProjectFiles = Readonly<Record<string, ProjectFile>>;
 
@@ -42,7 +52,14 @@ export type DefinitionResult = ProtocolDefinitionResult;
 export type DefinitionLocation = ProtocolDefinitionLocation;
 export type HoverResult = ProtocolHoverResult;
 export type HoverInfo = ProtocolHoverInfo;
+export type RenameEdit = ProtocolRenameEdit;
+export type RenameResult = ProtocolRenameResult;
+export type ReferenceLocation = ProtocolReferenceLocation;
+export type ReferencesResult = ProtocolReferencesResult;
 export type SourceRange = ProtocolSourceRange;
+export type SourceMap = ProtocolSourceMap;
+export type SourceMapEntry = ProtocolSourceMapEntry;
+export type SourceMapOrigin = ProtocolSourceMapOrigin;
 
 export type MclResult =
   | ({ operation: "parse" } & ParseResult)
@@ -50,6 +67,8 @@ export type MclResult =
   | ({ operation: "completion" } & ProtocolCompletionResult)
   | ({ operation: "definition" } & ProtocolDefinitionResult)
   | ({ operation: "hover" } & ProtocolHoverResult)
+  | ({ operation: "references" } & ProtocolReferencesResult)
+  | ({ operation: "rename" } & ProtocolRenameResult)
   | ({ operation: "format" } & FormatResult)
   | ({ operation: "check" } & CheckResult)
   | ({ operation: "evaluate" } & EvaluateResult)
@@ -67,22 +86,70 @@ export interface MclRuntime {
   parse(source: string, options?: RequestOptions): Promise<MclResult & { operation: "parse" }>;
   lint(source: string, options?: RequestOptions): Promise<MclResult & { operation: "lint" }>;
   format(source: string, options?: RequestOptions): Promise<MclResult & { operation: "format" }>;
-  check(source: string, files?: ProjectFiles, options?: RequestOptions): Promise<MclResult & { operation: "check" }>;
-  evaluate(source: string, files?: ProjectFiles, options?: RequestOptions): Promise<MclResult & { operation: "evaluate" }>;
-  render(source: string, files?: ProjectFiles, options?: RequestOptions): Promise<MclResult & { operation: "render" }>;
-  definition(source: string, options: PositionRequestOptions): Promise<MclResult & { operation: "definition" }>;
-  definition(source: string, files: ProjectFiles | undefined, options: PositionRequestOptions): Promise<MclResult & { operation: "definition" }>;
-  hover(source: string, options: PositionRequestOptions): Promise<MclResult & { operation: "hover" }>;
-  hover(source: string, files: ProjectFiles | undefined, options: PositionRequestOptions): Promise<MclResult & { operation: "hover" }>;
+  check(
+    source: string,
+    files?: ProjectFiles,
+    options?: RequestOptions,
+  ): Promise<MclResult & { operation: "check" }>;
+  evaluate(
+    source: string,
+    files?: ProjectFiles,
+    options?: RequestOptions,
+  ): Promise<MclResult & { operation: "evaluate" }>;
+  render(
+    source: string,
+    files?: ProjectFiles,
+    options?: RequestOptions,
+  ): Promise<MclResult & { operation: "render" }>;
+  definition(
+    source: string,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "definition" }>;
+  definition(
+    source: string,
+    files: ProjectFiles | undefined,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "definition" }>;
+  hover(
+    source: string,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "hover" }>;
+  hover(
+    source: string,
+    files: ProjectFiles | undefined,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "hover" }>;
+  references(
+    source: string,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "references" }>;
+  references(
+    source: string,
+    files: ProjectFiles | undefined,
+    options: PositionRequestOptions,
+  ): Promise<MclResult & { operation: "references" }>;
+  rename(
+    source: string,
+    options: RenameRequestOptions,
+  ): Promise<MclResult & { operation: "rename" }>;
+  rename(
+    source: string,
+    files: ProjectFiles | undefined,
+    options: RenameRequestOptions,
+  ): Promise<MclResult & { operation: "rename" }>;
   dispose(): void;
 }
 
 export interface MclProject {
+  /** Returns a new complete snapshot handle for this Worker session. Only changed files are sent on the next operation. */
+  update(files: ProjectFiles): MclProject;
   parse(options?: ProjectOperationOptions): Promise<MclResult & { operation: "parse" }>;
   lint(options?: ProjectOperationOptions): Promise<MclResult & { operation: "lint" }>;
   complete(options: ProjectCompletionOptions): Promise<MclResult & { operation: "completion" }>;
   definition(options: ProjectNavigationOptions): Promise<MclResult & { operation: "definition" }>;
   hover(options: ProjectNavigationOptions): Promise<MclResult & { operation: "hover" }>;
+  references(options: ProjectNavigationOptions): Promise<MclResult & { operation: "references" }>;
+  rename(options: ProjectRenameOptions): Promise<MclResult & { operation: "rename" }>;
   format(options?: ProjectOperationOptions): Promise<MclResult & { operation: "format" }>;
   check(options?: ProjectOperationOptions): Promise<MclResult & { operation: "check" }>;
   evaluate(options?: ProjectOperationOptions): Promise<MclResult & { operation: "evaluate" }>;
@@ -106,11 +173,19 @@ export interface ProjectNavigationOptions extends ProjectOperationOptions {
   position: CompletionPosition;
 }
 
+export interface ProjectRenameOptions extends ProjectNavigationOptions {
+  newName: string;
+}
+
 export interface PositionRequestOptions extends RequestOptions {
   entrypoint?: string;
   position: CompletionPosition;
 }
 
+export interface RenameRequestOptions extends PositionRequestOptions {
+  newName: string;
+}
+
 export declare class MclRuntimeError extends Error {
   readonly code: string;
   readonly path?: string;

package/src/index.js

@@ -4,14 +4,31 @@ import {
   maxProjectFiles,
   maxProjectPathDepth,
   maxProjectPathLength,
+  maxRenameNameLength,
   maxSourceBytes,
+  maxSourceMapBytes,
 } from "./limits.js";
 
-export { maxProjectBytes, maxProjectFileBytes, maxProjectFiles, maxProjectPathDepth, maxProjectPathLength, maxSourceBytes };
+export {
+  maxProjectBytes,
+  maxProjectFileBytes,
+  maxProjectFiles,
+  maxProjectPathDepth,
+  maxProjectPathLength,
+  maxRenameNameLength,
+  maxSourceBytes,
+  maxSourceMapBytes,
+};
 
 export function isValidProjectPath(value) {
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("/") ||
-    /^[a-z]:/i.test(value) || value.includes("\\") || value.includes("\0")) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.startsWith("/") ||
+    /^[a-z]:/i.test(value) ||
+    value.includes("\\") ||
+    value.includes("\0")
+  ) {
     return false;
   }
   let pathLength = 0;
@@ -23,6 +40,25 @@ export function isValidProjectPath(value) {
   return value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
 }
 
+export function isValidProjectFileSet(paths) {
+  if (!Array.isArray(paths)) return false;
+  const files = new Set();
+  const directories = new Set();
+  for (const filePath of paths) {
+    if (!isValidProjectPath(filePath) || files.has(filePath) || directories.has(filePath))
+      return false;
+    let separator = filePath.indexOf("/");
+    while (separator !== -1) {
+      const directory = filePath.slice(0, separator);
+      if (files.has(directory)) return false;
+      directories.add(directory);
+      separator = filePath.indexOf("/", separator + 1);
+    }
+    files.add(filePath);
+  }
+  return true;
+}
+
 const defaultInitializationTimeoutMs = 30_000;
 const defaultOperationTimeoutMs = 10_000;
 const wasmURL = new URL("../dist/mcl.wasm", import.meta.url).href;
@@ -43,7 +79,9 @@ export class MclRuntimeError extends Error {
 }
 
 export function createMclRuntime(options = {}) {
-  const workerFactory = options.workerFactory ?? (() => new Worker(new URL("./worker.js", import.meta.url), { type: "module" }));
+  const workerFactory =
+    options.workerFactory ??
+    (() => new Worker(new URL("./worker.js", import.meta.url), { type: "module" }));
   const initializationTimeoutMs = options.initializationTimeoutMs ?? defaultInitializationTimeoutMs;
   let worker;
   let ready;
@@ -51,6 +89,7 @@ export function createMclRuntime(options = {}) {
   let queue = Promise.resolve();
   let sequence = 0;
   let workerGeneration = 0;
+  let workerProject;
   let stopCurrent;
   let stopInitialization;
 
@@ -60,6 +99,7 @@ export function createMclRuntime(options = {}) {
     const currentWorker = workerFactory();
     worker = currentWorker;
     workerGeneration++;
+    workerProject = undefined;
     let resolveReady;
     let rejectReady;
     const initialization = new Promise((resolve, reject) => {
@@ -67,7 +107,10 @@ export function createMclRuntime(options = {}) {
       rejectReady = reject;
     });
     ready = initialization;
-    const timer = setTimeout(() => fail(new Error("MCL WebAssembly initialization timed out")), initializationTimeoutMs);
+    const timer = setTimeout(
+      () => fail(new Error("MCL WebAssembly initialization timed out")),
+      initializationTimeoutMs,
+    );
     const onMessage = (event) => {
       if (event.data?.type === "ready") {
         clearTimeout(timer);
@@ -122,14 +165,111 @@ export function createMclRuntime(options = {}) {
     }
   }
 
-  async function execute(operation, source, files, requestOptions = {}, entrypoint = "main.mcl", position) {
+  async function syncProjectToWorker(project, requestOptions, currentWorker, currentGeneration) {
+    const previous = workerProject;
+    const reset = !previous || previous.id !== project.id;
+    const previousFiles = reset ? Object.create(null) : previous.snapshot.files;
+    const updates = Object.create(null);
+    const binaryFiles = Object.create(null);
+    const transferables = [];
+    const deleted = [];
+    for (const [filePath, content] of Object.entries(project.snapshot.files)) {
+      if (
+        !reset &&
+        Object.hasOwn(previousFiles, filePath) &&
+        sameContent(previousFiles[filePath], content)
+      )
+        continue;
+      if (typeof content === "string") {
+        updates[filePath] = { encoding: "utf8", content };
+      } else {
+        const copy = new Uint8Array(content);
+        updates[filePath] = { encoding: "binary" };
+        binaryFiles[filePath] = copy;
+        transferables.push(copy.buffer);
+      }
+    }
+    if (!reset) {
+      for (const filePath of Object.keys(previousFiles)) {
+        if (!Object.hasOwn(project.snapshot.files, filePath)) deleted.push(filePath);
+      }
+    }
+    if (!reset && Object.keys(updates).length === 0 && deleted.length === 0) return;
+
+    const requestId = ++sequence;
+    const update = JSON.stringify({ reset, files: updates, deleted });
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        currentWorker.removeEventListener("message", onMessage);
+        currentWorker.removeEventListener("error", onError);
+        requestOptions.signal?.removeEventListener("abort", onAbort);
+      };
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (stopCurrent === stop) stopCurrent = undefined;
+        callback(value);
+      };
+      const onMessage = (event) => {
+        if (worker !== currentWorker || workerGeneration !== currentGeneration) return;
+        const response = event.data;
+        if (response?.type !== "project-updated" || response.requestId !== requestId) return;
+        if (!response.value.ok) finish(reject, new MclRuntimeError(response.value.error));
+        else {
+          workerProject = { id: project.id, snapshot: project.snapshot };
+          finish(resolve);
+        }
+      };
+      const stop = (error) => {
+        finish(reject, error);
+        currentWorker.terminate();
+        if (worker === currentWorker) {
+          worker = undefined;
+          ready = undefined;
+          workerProject = undefined;
+        }
+      };
+      const onError = (event) => stop(new Error(event.message || "MCL worker failed"));
+      const onAbort = () => stop(new DOMException("The operation was aborted", "AbortError"));
+      currentWorker.addEventListener("message", onMessage);
+      currentWorker.addEventListener("error", onError);
+      requestOptions.signal?.addEventListener("abort", onAbort, { once: true });
+      stopCurrent = stop;
+      if (requestOptions.signal?.aborted) return onAbort();
+      try {
+        currentWorker.postMessage(
+          { type: "project-update", requestId, projectId: project.id, update, binaryFiles },
+          transferables,
+        );
+      } catch (error) {
+        stop(error);
+      }
+    });
+  }
+
+  async function execute(
+    operation,
+    source,
+    files,
+    requestOptions = {},
+    entrypoint = "main.mcl",
+    position,
+    project,
+  ) {
     const signal = requestOptions.signal;
     if (signal?.aborted) throw new DOMException("The operation was aborted", "AbortError");
     const run = async () => {
       if (disposed) throw new Error("MCL runtime has been disposed");
-      if (requestOptions.signal?.aborted) throw new DOMException("The operation was aborted", "AbortError");
-      const timeoutMs = requestOptions.timeoutMs ?? options.operationTimeoutMs ?? defaultOperationTimeoutMs;
-      const timeoutError = new MclRuntimeError({ code: "MCL-WASM-TIMEOUT", message: "MCL operation timed out" });
+      if (requestOptions.signal?.aborted)
+        throw new DOMException("The operation was aborted", "AbortError");
+      const timeoutMs =
+        requestOptions.timeoutMs ?? options.operationTimeoutMs ?? defaultOperationTimeoutMs;
+      const timeoutError = new MclRuntimeError({
+        code: "MCL-WASM-TIMEOUT",
+        message: "MCL operation timed out",
+      });
       let timer;
       try {
         if (timeoutMs <= 0) throw timeoutError;
@@ -138,11 +278,23 @@ export function createMclRuntime(options = {}) {
           else stopInitialization?.(timeoutError);
         }, timeoutMs);
         await waitUntilReady(requestOptions.signal);
-        if (requestOptions.signal?.aborted) throw new DOMException("The operation was aborted", "AbortError");
-        const preparedFiles = prepareFilesForTransfer(source, files, entrypoint);
-        const requestId = ++sequence;
+        if (requestOptions.signal?.aborted)
+          throw new DOMException("The operation was aborted", "AbortError");
         const currentWorker = worker;
         const currentGeneration = workerGeneration;
+        if (project) {
+          await syncProjectToWorker(
+            project,
+            requestOptions,
+            currentWorker,
+            currentGeneration,
+            timeoutError,
+          );
+        }
+        const preparedFiles = project
+          ? undefined
+          : prepareFilesForTransfer(source, files, entrypoint);
+        const requestId = ++sequence;
         return await new Promise((resolve, reject) => {
           let settled = false;
           const cleanup = () => {
@@ -163,7 +315,8 @@ export function createMclRuntime(options = {}) {
             const response = event.data;
             if (response?.type !== "response" || response.requestId !== requestId) return;
             if (!response.value.ok) finish(reject, new MclRuntimeError(response.value.error));
-            else if (operation === "lint") finish(resolve, { operation, diagnostics: response.value.result });
+            else if (operation === "lint")
+              finish(resolve, { operation, diagnostics: response.value.result });
             else finish(resolve, { operation, ...response.value.result });
           };
           const onError = (event) => stop(new Error(event.message || "MCL worker failed"));
@@ -181,7 +334,18 @@ export function createMclRuntime(options = {}) {
           requestOptions.signal?.addEventListener("abort", onAbort, { once: true });
           stopCurrent = stop;
           try {
-            currentWorker.postMessage({ type: "run", requestId, operation, source, files: preparedFiles.files, entrypoint, position }, preparedFiles.transferables);
+            const message = {
+              type: "run",
+              requestId,
+              operation,
+              source,
+              entrypoint,
+              position,
+              newName: requestOptions.newName,
+            };
+            if (project) message.projectId = project.id;
+            else message.files = preparedFiles.files;
+            currentWorker.postMessage(message, preparedFiles?.transferables ?? []);
           } catch (error) {
             stop(error);
           }
@@ -201,17 +365,23 @@ export function createMclRuntime(options = {}) {
       signal.addEventListener("abort", onAbort, { once: true });
       if (signal.aborted) onAbort();
     });
-    return Promise.race([result, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+    return Promise.race([result, aborted]).finally(() =>
+      signal.removeEventListener("abort", onAbort),
+    );
   }
 
   function warmUp(requestOptions = {}) {
     const signal = requestOptions.signal;
-    if (signal?.aborted) return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
+    if (signal?.aborted)
+      return Promise.reject(new DOMException("The operation was aborted", "AbortError"));
     const run = async () => {
       if (disposed) throw new Error("MCL runtime has been disposed");
       if (signal?.aborted) throw new DOMException("The operation was aborted", "AbortError");
       const timeoutMs = requestOptions.timeoutMs ?? initializationTimeoutMs;
-      const timeoutError = new MclRuntimeError({ code: "MCL-WASM-TIMEOUT", message: "MCL WebAssembly initialization timed out" });
+      const timeoutError = new MclRuntimeError({
+        code: "MCL-WASM-TIMEOUT",
+        message: "MCL WebAssembly initialization timed out",
+      });
       let timer;
       try {
         if (timeoutMs <= 0) throw timeoutError;
@@ -230,48 +400,115 @@ export function createMclRuntime(options = {}) {
       signal.addEventListener("abort", onAbort, { once: true });
       if (signal.aborted) onAbort();
     });
-    return Promise.race([result, aborted]).finally(() => signal.removeEventListener("abort", onAbort));
+    return Promise.race([result, aborted]).finally(() =>
+      signal.removeEventListener("abort", onAbort),
+    );
   }
 
   function openProject(files) {
+    const snapshot = createProjectSnapshot(files);
+    const id = `mcl-project-${++sequence}`;
+    return makeProject(id, snapshot);
+  }
+
+  function sameContent(left, right) {
+    if (left === right) return true;
+    if (typeof left !== typeof right) return false;
+    if (typeof left === "string") return left === right;
+    if (left.byteLength !== right.byteLength) return false;
+    for (let index = 0; index < left.byteLength; index++) {
+      if (left[index] !== right[index]) return false;
+    }
+    return true;
+  }
+
+  function createProjectSnapshot(files, previous) {
     const entries = Object.entries(files ?? {});
-    if (entries.length === 0) throw new TypeError("Project must contain at least one MCL source file");
-    if (entries.length > maxProjectFiles) throw new RangeError(`Project has more than ${maxProjectFiles} files`);
+    if (entries.length === 0)
+      throw new TypeError("Project must contain at least one MCL source file");
+    if (entries.length > maxProjectFiles)
+      throw new RangeError(`Project has more than ${maxProjectFiles} files`);
+    if (!isValidProjectFileSet(entries.map(([filePath]) => filePath)))
+      throw new TypeError(
+        "Project file paths must be valid and cannot conflict with a file or directory path",
+      );
     let totalBytes = 0;
-    // Project paths are user controlled; a null prototype keeps names such as
-    // `__proto__` as ordinary file paths instead of mutating the file map.
     const projectFiles = Object.create(null);
-    for (const [filePath, content] of entries) {
-      if (!isSafeRelativePath(filePath)) throw new TypeError(`Invalid project file path: ${filePath}`);
-      if (typeof content !== "string" && !(content instanceof Uint8Array)) throw new TypeError(`Project file ${filePath} must be a string or Uint8Array`);
-      const fileBytes = typeof content === "string" ? new TextEncoder().encode(content).byteLength : content.byteLength;
-      if (fileBytes > maxProjectFileBytes) throw new RangeError(`Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`);
+    const fileSizes = Object.create(null);
+    for (const [filePath, input] of entries) {
+      if (typeof input !== "string" && !(input instanceof Uint8Array))
+        throw new TypeError(`Project file ${filePath} must be a string or Uint8Array`);
+      const previousContent = previous?.files[filePath];
+      const unchanged = previousContent !== undefined && sameContent(previousContent, input);
+      const content = unchanged
+        ? previousContent
+        : typeof input === "string"
+          ? input
+          : new Uint8Array(input);
+      const fileBytes = unchanged
+        ? previous.sizes[filePath]
+        : typeof content === "string"
+          ? new TextEncoder().encode(content).byteLength
+          : content.byteLength;
+      if (!unchanged && fileBytes > maxProjectFileBytes)
+        throw new RangeError(
+          `Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`,
+        );
       totalBytes += fileBytes;
-      if (totalBytes > maxProjectBytes) throw new RangeError(`Project files exceed the ${maxProjectBytes}-byte limit`);
-      projectFiles[filePath] = typeof content === "string" ? content : new Uint8Array(content);
+      if (totalBytes > maxProjectBytes)
+        throw new RangeError(`Project files exceed the ${maxProjectBytes}-byte limit`);
+      projectFiles[filePath] = content;
+      fileSizes[filePath] = fileBytes;
     }
+    const sourcePaths = Object.keys(projectFiles)
+      .filter((filePath) => filePath.endsWith(".mcl"))
+      .sort();
+    if (sourcePaths.length === 0)
+      throw new TypeError("Project must contain at least one MCL source file");
+    const defaultEntrypoint = Object.hasOwn(projectFiles, "main.mcl")
+      ? "main.mcl"
+      : sourcePaths.length === 1
+        ? sourcePaths[0]
+        : undefined;
+    return Object.freeze({
+      files: Object.freeze(projectFiles),
+      sizes: Object.freeze(fileSizes),
+      defaultEntrypoint,
+    });
+  }
 
-    const sourcePaths = Object.keys(projectFiles).filter((filePath) => filePath.endsWith(".mcl")).sort();
-    const defaultEntrypoint = Object.hasOwn(projectFiles, "main.mcl") ? "main.mcl" : sourcePaths.length === 1 ? sourcePaths[0] : undefined;
+  function makeProject(id, snapshot) {
     const runProjectOperation = async (operation, requestOptions = {}) => {
-      const entrypoint = requestOptions.entrypoint ?? defaultEntrypoint;
-      if (!entrypoint) throw new TypeError("Set entrypoint when the project has multiple MCL source files");
-      if (!isSafeRelativePath(entrypoint) || !Object.hasOwn(projectFiles, entrypoint)) throw new TypeError(`Project entrypoint does not exist: ${entrypoint}`);
-      const entry = projectFiles[entrypoint];
-      const source = typeof entry === "string" ? entry : new TextDecoder("utf-8", { fatal: true }).decode(entry);
+      const entrypoint = requestOptions.entrypoint ?? snapshot.defaultEntrypoint;
+      if (!entrypoint)
+        throw new TypeError("Set entrypoint when the project has multiple MCL source files");
+      if (!isSafeRelativePath(entrypoint) || !Object.hasOwn(snapshot.files, entrypoint))
+        throw new TypeError(`Project entrypoint does not exist: ${entrypoint}`);
+      const entry = snapshot.files[entrypoint];
+      const source =
+        typeof entry === "string" ? entry : new TextDecoder("utf-8", { fatal: true }).decode(entry);
       const sourceBytes = new TextEncoder().encode(source).byteLength;
-      if (sourceBytes > maxSourceBytes) throw new RangeError(`Source exceeds the ${maxSourceBytes}-byte limit`);
-      const projectBytes = Object.values(projectFiles).reduce((total, file) => total + (typeof file === "string" ? new TextEncoder().encode(file).byteLength : file.byteLength), 0);
-      if (projectBytes > maxProjectBytes) throw new RangeError(`Project files exceed the ${maxProjectBytes}-byte limit`);
-      const otherFiles = Object.fromEntries(Object.entries(projectFiles).filter(([filePath]) => filePath !== entrypoint));
-      return execute(operation, source, otherFiles, requestOptions, entrypoint, requestOptions.position);
+      if (sourceBytes > maxSourceBytes)
+        throw new RangeError(`Source exceeds the ${maxSourceBytes}-byte limit`);
+      return execute(
+        operation,
+        source,
+        undefined,
+        requestOptions,
+        entrypoint,
+        requestOptions.position,
+        { id, snapshot },
+      );
     };
     return Object.freeze({
+      update: (nextFiles) => makeProject(id, createProjectSnapshot(nextFiles, snapshot)),
       parse: (requestOptions) => runProjectOperation("parse", requestOptions),
       lint: (requestOptions) => runProjectOperation("lint", requestOptions),
       complete: (requestOptions) => runProjectOperation("completion", requestOptions),
       definition: (requestOptions) => runProjectOperation("definition", requestOptions),
       hover: (requestOptions) => runProjectOperation("hover", requestOptions),
+      references: (requestOptions) => runProjectOperation("references", requestOptions),
+      rename: (requestOptions) => runProjectOperation("rename", requestOptions),
       format: (requestOptions) => runProjectOperation("format", requestOptions),
       check: (requestOptions) => runProjectOperation("check", requestOptions),
       evaluate: (requestOptions) => runProjectOperation("evaluate", requestOptions),
@@ -284,23 +521,33 @@ export function createMclRuntime(options = {}) {
   }
 
   function prepareFilesForTransfer(source, files, entrypoint) {
-    if (!isSafeRelativePath(entrypoint)) throw new TypeError(`Invalid project entrypoint: ${entrypoint}`);
+    if (!isSafeRelativePath(entrypoint))
+      throw new TypeError(`Invalid project entrypoint: ${entrypoint}`);
     const sourceBytes = new TextEncoder().encode(source).byteLength;
-    if (sourceBytes > maxSourceBytes) throw new RangeError(`Source exceeds the ${maxSourceBytes}-byte limit`);
+    if (sourceBytes > maxSourceBytes)
+      throw new RangeError(`Source exceeds the ${maxSourceBytes}-byte limit`);
     const entries = Object.entries(files ?? {});
-    if (entries.length + 1 > maxProjectFiles) throw new RangeError(`Project has more than ${maxProjectFiles} files`);
+    if (entries.length + 1 > maxProjectFiles)
+      throw new RangeError(`Project has more than ${maxProjectFiles} files`);
     let totalBytes = sourceBytes;
     const transferredFiles = Object.create(null);
     const transferables = [];
     for (const [filePath, content] of entries) {
-      if (!isSafeRelativePath(filePath) || filePath === entrypoint) throw new TypeError(`Invalid project file path: ${filePath}`);
+      if (!isSafeRelativePath(filePath) || filePath === entrypoint)
+        throw new TypeError(`Invalid project file path: ${filePath}`);
       if (typeof content === "string") {
         const fileBytes = new TextEncoder().encode(content).byteLength;
-        if (fileBytes > maxProjectFileBytes) throw new RangeError(`Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`);
+        if (fileBytes > maxProjectFileBytes)
+          throw new RangeError(
+            `Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`,
+          );
         totalBytes += fileBytes;
         transferredFiles[filePath] = content;
       } else if (content instanceof Uint8Array) {
-        if (content.byteLength > maxProjectFileBytes) throw new RangeError(`Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`);
+        if (content.byteLength > maxProjectFileBytes)
+          throw new RangeError(
+            `Project file ${filePath} exceeds the ${maxProjectFileBytes}-byte limit`,
+          );
         totalBytes += content.byteLength;
         const copy = new Uint8Array(content);
         transferredFiles[filePath] = copy;
@@ -308,7 +555,8 @@ export function createMclRuntime(options = {}) {
       } else {
         throw new TypeError(`Project file ${filePath} must be a string or Uint8Array`);
       }
-      if (totalBytes > maxProjectBytes) throw new RangeError(`Project files exceed the ${maxProjectBytes}-byte limit`);
+      if (totalBytes > maxProjectBytes)
+        throw new RangeError(`Project files exceed the ${maxProjectBytes}-byte limit`);
     }
     return { files: transferredFiles, transferables };
   }
@@ -317,7 +565,14 @@ export function createMclRuntime(options = {}) {
     const files = requestOptions === undefined ? undefined : filesOrOptions;
     const options = requestOptions ?? filesOrOptions;
     if (!options?.position) throw new TypeError("A source position is required");
-    return execute(operation, source, files, options, options.entrypoint ?? "main.mcl", options.position);
+    return execute(
+      operation,
+      source,
+      files,
+      options,
+      options.entrypoint ?? "main.mcl",
+      options.position,
+    );
   }
 
   return {
@@ -329,8 +584,14 @@ export function createMclRuntime(options = {}) {
     check: (source, files, requestOptions) => execute("check", source, files, requestOptions),
     evaluate: (source, files, requestOptions) => execute("evaluate", source, files, requestOptions),
     render: (source, files, requestOptions) => execute("render", source, files, requestOptions),
-    definition: (source, filesOrOptions, requestOptions) => runSourceNavigation("definition", source, filesOrOptions, requestOptions),
-    hover: (source, filesOrOptions, requestOptions) => runSourceNavigation("hover", source, filesOrOptions, requestOptions),
+    definition: (source, filesOrOptions, requestOptions) =>
+      runSourceNavigation("definition", source, filesOrOptions, requestOptions),
+    hover: (source, filesOrOptions, requestOptions) =>
+      runSourceNavigation("hover", source, filesOrOptions, requestOptions),
+    references: (source, filesOrOptions, requestOptions) =>
+      runSourceNavigation("references", source, filesOrOptions, requestOptions),
+    rename: (source, filesOrOptions, requestOptions) =>
+      runSourceNavigation("rename", source, filesOrOptions, requestOptions),
     dispose() {
       if (disposed) return;
       disposed = true;

package/src/limits.js

@@ -4,6 +4,8 @@ export const maxProjectFiles = 4096;
 export const maxProjectFileBytes = 16777216;
 export const maxProjectBytes = 67108864;
 export const maxOutputBytes = 1048576;
+export const maxSourceMapBytes = 1048576;
+export const maxRenameNameLength = 256;
 export const evaluationTimeoutMillis = 4000;
 export const maxProjectPathLength = 512;
 export const maxProjectPathDepth = 64;

package/src/protocol.d.ts

@@ -4,8 +4,20 @@ export type MCLWebAssemblyRequestAndResponseProtocol = Request | Response;
 export type Request = {
   requestId?: number;
   revision?: number;
-  operation: "parse" | "lint" | "format" | "check" | "evaluate" | "render" | "completion" | "definition" | "hover";
+  operation:
+    | "parse"
+    | "lint"
+    | "format"
+    | "check"
+    | "evaluate"
+    | "render"
+    | "completion"
+    | "definition"
+    | "hover"
+    | "references"
+    | "rename";
   position?: CompletionPosition;
+  newName?: string;
   entrypoint?: ProjectPath;
   /**
    * UTF-8 entrypoint source, limited by the runtime.
@@ -30,6 +42,8 @@ export type FileInput = {
   content?: string;
 };
 export type LintResult = LintDiagnostic[];
+export type ProjectPath1 = ProjectPath2;
+export type ProjectPath2 = string;
 
 export interface CompletionPosition {
   line: number;
@@ -48,7 +62,9 @@ export interface Response {
     | RenderResult
     | CompletionResult
     | DefinitionResult
-    | HoverResult;
+    | HoverResult
+    | ReferencesResult
+    | RenameResult;
   error?: Error;
 }
 export interface ParseResult {
@@ -78,6 +94,35 @@ export interface EvaluateResult {
 export interface RenderResult {
   yaml: string;
   artifacts: number;
+  sourceMap: SourceMap;
+}
+/**
+ * Source map entries are limited by maxSourceMapBytes. Ranges use zero-based UTF-16 line and character positions with an exclusive end.
+ */
+export interface SourceMap {
+  complete: boolean;
+  entries: SourceMapEntry[];
+}
+export interface SourceMapEntry {
+  document: number;
+  /**
+   * JSON Pointer into the rendered YAML document.
+   */
+  path: string;
+  kind: "key" | "value";
+  output: SourceRange;
+  sources: SourceMapOrigin[];
+}
+export interface SourceRange {
+  start: CompletionPosition;
+  end: CompletionPosition;
+}
+export interface SourceMapOrigin {
+  path: ProjectPath1;
+  range: SourceRange;
+  kind: "mcl" | "mcl-overlay-base" | "mcl-overlay-patch";
+  multiplicity: "unique" | "repeated" | "ambiguous";
+  occurrences: number;
 }
 export interface CompletionResult {
   isIncomplete: boolean;
@@ -95,10 +140,6 @@ export interface DefinitionLocation {
   path: string;
   range: SourceRange;
 }
-export interface SourceRange {
-  start: CompletionPosition;
-  end: CompletionPosition;
-}
 export interface HoverResult {
   hover: HoverInfo | null;
 }
@@ -106,6 +147,21 @@ export interface HoverInfo {
   contents: string;
   range: SourceRange;
 }
+export interface ReferencesResult {
+  references: ReferenceLocation[];
+}
+export interface ReferenceLocation {
+  path: ProjectPath1;
+  range: SourceRange;
+}
+export interface RenameResult {
+  edits: RenameEdit[];
+}
+export interface RenameEdit {
+  path: ProjectPath1;
+  range: SourceRange;
+  newText: string;
+}
 export interface Error {
   code: string;
   message: string;

package/src/worker.js

@@ -21,7 +21,8 @@ const originalNetworkAPIs = new Map(
 );
 
 function denyNetworkAccess() {
-  globalThis.fetch = () => Promise.reject(new TypeError("Network access is disabled in the MCL runtime"));
+  globalThis.fetch = () =>
+    Promise.reject(new TypeError("Network access is disabled in the MCL runtime"));
   for (const [name] of originalNetworkAPIs) {
     Object.defineProperty(globalThis, name, {
       configurable: true,
@@ -43,16 +44,35 @@ async function probeNetworkAccess(url) {
   }
 
   const availableAPIs = ["fetch", ...originalNetworkAPIs.keys()];
-  const blockedAPIs = availableAPIs.filter(
-    (name) => name === "fetch" ? globalThis.fetch !== originalFetch : globalThis[name] !== originalNetworkAPIs.get(name),
+  const blockedAPIs = availableAPIs.filter((name) =>
+    name === "fetch"
+      ? globalThis.fetch !== originalFetch
+      : globalThis[name] !== originalNetworkAPIs.get(name),
   );
   return { fetchBlocked, availableAPIs, blockedAPIs };
 }
 
+function waitForWasmReady() {
+  return new Promise((resolve) => {
+    Object.defineProperty(globalThis, "mclWasmReady", {
+      configurable: true,
+      set(value) {
+        Object.defineProperty(globalThis, "mclWasmReady", {
+          configurable: true,
+          writable: true,
+          value,
+        });
+        if (value === true) resolve();
+      },
+    });
+  });
+}
+
 async function initialize() {
   if (initialized) return initialized;
   initialized = (async () => {
-    if (!runtimeAssets?.wasmURL || !runtimeAssets?.wasmExecURL) throw new Error("MCL runtime assets were not configured");
+    if (!runtimeAssets?.wasmURL || !runtimeAssets?.wasmExecURL)
+      throw new Error("MCL runtime assets were not configured");
     await import(runtimeAssets.wasmExecURL);
     const go = new Go();
     const response = await runtimeFetch(runtimeAssets.wasmURL);
@@ -65,8 +85,13 @@ async function initialize() {
     } catch {
       ({ instance } = await WebAssembly.instantiate(await response.arrayBuffer(), go.importObject));
     }
-    void go.run(instance);
-    while (!globalThis.mclWasmReady) await new Promise((resolve) => setTimeout(resolve, 0));
+    const wasmReady = waitForWasmReady();
+    await Promise.race([
+      wasmReady,
+      go.run(instance).then(() => {
+        throw new Error("MCL WebAssembly exited before initialization completed");
+      }),
+    ]);
     postMessage({ type: "ready" });
   })().catch((error) => {
     postMessage({ type: "fatal", message: error instanceof Error ? error.message : String(error) });
@@ -105,6 +130,29 @@ self.addEventListener("message", async (event) => {
     initialize().catch(() => {});
     return;
   }
+  if (message?.type === "project-update") {
+    try {
+      await initialize();
+      const binaryFiles = message.binaryFiles ?? Object.create(null);
+      const result = JSON.parse(
+        globalThis.mclWasm.updateProject(message.projectId, message.update, binaryFiles),
+      );
+      postMessage({ type: "project-updated", requestId: message.requestId, value: result });
+    } catch (error) {
+      postMessage({
+        type: "project-updated",
+        requestId: message.requestId,
+        value: {
+          ok: false,
+          error: {
+            code: "MCL-WASM-PROJECT",
+            message: error instanceof Error ? error.message : String(error),
+          },
+        },
+      });
+    }
+    return;
+  }
   if (message?.type !== "run") return;
   try {
     await initialize();
@@ -114,11 +162,20 @@ self.addEventListener("message", async (event) => {
       revision: message.requestId,
       operation: message.operation,
       entrypoint: message.entrypoint,
+      newName: message.newName,
       position: message.position,
       source: message.source,
       files: encodedFiles.files,
     };
-    const value = JSON.parse(globalThis.mclWasm.run(JSON.stringify(request), encodedFiles.binaryFiles));
+    const value = JSON.parse(
+      message.projectId === undefined
+        ? globalThis.mclWasm.run(JSON.stringify(request), encodedFiles.binaryFiles)
+        : globalThis.mclWasm.run(
+            JSON.stringify(request),
+            encodedFiles.binaryFiles,
+            message.projectId,
+          ),
+    );
     postMessage({
       type: "response",
       requestId: message.requestId,
@@ -130,7 +187,10 @@ self.addEventListener("message", async (event) => {
       requestId: message.requestId,
       value: {
         ok: false,
-        error: { code: "MCL-WASM-INPUT", message: error instanceof Error ? error.message : String(error) },
+        error: {
+          code: "MCL-WASM-INPUT",
+          message: error instanceof Error ? error.message : String(error),
+        },
       },
     });
   }