From 24e5a7cab09120fb279e3c644e12cc41a629a50d Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 12:17:55 +0530
Subject: [PATCH 1/9] feat(lsp): JSHint defers to the language server; expose
 server lifecycle events

On desktop the TypeScript language server (vtsls) always lints JS, yet JSHint
still also linted plain-JS projects (it only deferred to ESLint), so the Problems
panel showed duplicate diagnostics. JSHint now defers to the language server the
same way it defers to ESLint: it runs only when it is the sole JS diagnostics
source, when a .jshintrc opts it in, or as a fallback when no server is running.
ESLint and the language server keep coexisting (rules vs. compiler), like VS Code.
Browser is unchanged - no server there, so JSHint stays the JS linter.

- LSPClient: add isLintingProviderActive(languageId); make the module an
  EventDispatcher exposing EVENT_LANGUAGE_SERVER_STARTED / _STOPPED for extensions.
  A new _announceServerStarted() fires STARTED and re-runs inspection on every path
  that brings a server up (initial start, restart, crash auto-restart) - so linters
  that defer re-evaluate even on a clean file, whose empty publishDiagnostics
  wouldn't otherwise trigger a re-run.
- JSHint: resolve a desktop-only LSPClient handle and defer in canInspect, deriving
  the language id from LanguageManager.
- Tests: new "defers JSHint to the language server in a plain JS project" spec;
  update the two ESLint-failure-fallback specs to expect the LSP (not JSHint) to
  cover the file on desktop.
---
 src/extensions/default/JSLint/JSHint.js       | 30 ++++++++-
 .../default/TypeScriptSupport/unittests.js    | 29 +++++++-
 src/languageTools/LSPClient.js                | 67 ++++++++++++++++++-
 test/spec/Extn-ESLint-integ-test.js           | 38 ++++++++---
 4 files changed, 148 insertions(+), 16 deletions(-)

diff --git a/src/extensions/default/JSLint/JSHint.js b/src/extensions/default/JSLint/JSHint.js
index 83e569ce4b..ae62d95674 100644
--- a/src/extensions/default/JSLint/JSHint.js
+++ b/src/extensions/default/JSLint/JSHint.js
@@ -40,8 +40,29 @@ define(function (require, exports, module) {
         FileSystem         = brackets.getModule("filesystem/FileSystem"),
         IndexingWorker     = brackets.getModule("worker/IndexingWorker"),
         Metrics            = brackets.getModule("utils/Metrics"),
+        LanguageManager    = brackets.getModule("language/LanguageManager"),
         ESLint       = require("./ESLint");
 
+    // JSHint defers to the TypeScript language service (vtsls) when it is linting the file (see
+    // canInspect). Its module (languageTools/LSPClient) is loaded lazily and only on desktop - it's
+    // intentionally kept out of the browser build - so resolve a handle there to query its state. When
+    // a server starts/stops, LSPClient re-runs inspection itself, so JSHint doesn't track that here. In
+    // the browser there is no LSP, so _lspClient stays null and JSHint keeps linting as before.
+    let _lspClient = null;
+    if (Phoenix.isNativeApp) {
+        brackets.getModule(["languageTools/LSPClient"], function (LSPClient) {
+            _lspClient = LSPClient;
+        });
+    }
+
+    function _lspLintingActive(fullPath) {
+        if (!_lspClient) {
+            return false;
+        }
+        const language = LanguageManager.getLanguageForPath(fullPath);
+        return !!language && _lspClient.isLintingProviderActive(language.getId());
+    }
+
     if(Phoenix.isTestWindow) {
         IndexingWorker.on("JsHint_extension_Loaded", ()=>{
             window._JsHintExtensionReadyToIntegTest = true;
@@ -269,9 +290,12 @@ define(function (require, exports, module) {
         scanFileAsync: lintOneFile,
         canInspect: function (fullPath) {
             return !prefs.get(PREFS_JSHINT_DISABLED) && fullPath && !fullPath.endsWith(".min.js")
-                && (isJSHintConfigActive() || !ESLint.isESLintActive());
-            // if there is no linter, then we use jsHint as the default linter as it works in browser and native apps.
-            // remove ESLint.isESLintActive() once we add typescript language service that supports browser.
+                && (isJSHintConfigActive()
+                    || (!ESLint.isESLintActive() && !_lspLintingActive(fullPath)));
+            // JSHint is the default JS linter only when nothing richer is linting the file: it defers
+            // to ESLint and to the TypeScript language service (vtsls, desktop). It still runs when a
+            // .jshintrc opts in explicitly, and as a fallback when neither is active (e.g. the browser,
+            // where there is no LSP, or when the language server isn't running).
         }
     });
 
diff --git a/src/extensions/default/TypeScriptSupport/unittests.js b/src/extensions/default/TypeScriptSupport/unittests.js
index 097a97721e..551edd9381 100644
--- a/src/extensions/default/TypeScriptSupport/unittests.js
+++ b/src/extensions/default/TypeScriptSupport/unittests.js
@@ -18,7 +18,7 @@
  *
  */
 
-/*global describe, it, expect, beforeAll, afterAll, awaitsFor, awaitsForDone */
+/*global describe, it, expect, beforeAll, afterAll, awaitsFor, awaitsForDone, path, jsPromise */
 
 define(function (require, exports, module) {
 
@@ -125,6 +125,33 @@ define(function (require, exports, module) {
             expect(panelText().includes(IMPLICIT_ANY_MESSAGE)).toBe(false);
         }, 75000);
 
+        it("defers JSHint to the language server in a plain JS project", async function () {
+            // The language server is the JS linter on desktop, so the legacy JSHint linter must defer
+            // to it: the file below would draw a "Missing semicolon. jshint (W033)" nag if JSHint ran,
+            // but it must not appear. (No .jshintrc, so JSHint isn't explicitly opted in.)
+            const FileSystem = testWindow.brackets.test.FileSystem;
+            const LSPClient = await new Promise(function (resolve) {
+                testWindow.brackets.getModule(["languageTools/LSPClient"], resolve);
+            });
+            // A plain JS project (js-plain has no jsconfig/tsconfig). Add a file JSHint would flag.
+            const projectPath = await SpecRunnerUtils.getTempTestDirectory(testRootSpec + "js-plain");
+            await jsPromise(SpecRunnerUtils.createTextFile(
+                path.join(projectPath, "missing-semicolon.js"), 'console.log("hello")\n', FileSystem));
+            await SpecRunnerUtils.loadProjectInTestWindow(projectPath);
+            await awaitsForDone(SpecRunnerUtils.openProjectFiles(["missing-semicolon.js"]),
+                "open missing-semicolon.js");
+
+            // The deferral only holds while the server is the active JS linter - wait for that.
+            await awaitsFor(function () {
+                return LSPClient.isLintingProviderActive("javascript");
+            }, "the language server to be the active JS linter", 30000);
+            // The file is valid JS, so the server reports nothing; let inspection settle clean.
+            await awaitsFor(function () {
+                return $("#status-inspection").hasClass("inspection-valid");
+            }, "inspection to settle with no problems", 30000);
+            expect(panelText().toLowerCase().includes("jshint")).toBe(false);
+        }, 45000);
+
         // ----- hover quick-actions (Go to Definition / Find Usages) -------------------------------
 
         // Query the hover popover at a position the same way QuickViewManager does internally.
diff --git a/src/languageTools/LSPClient.js b/src/languageTools/LSPClient.js
index 6e4441e10a..4478fdf117 100644
--- a/src/languageTools/LSPClient.js
+++ b/src/languageTools/LSPClient.js
@@ -64,7 +64,28 @@ define(function (require, exports, module) {
         JumpToDefManager        = require("features/JumpToDefManager"),
         FindReferencesManager   = require("features/FindReferencesManager"),
         QuickViewManager        = require("features/QuickViewManager"),
-        CodeInspection          = require("language/CodeInspection");
+        CodeInspection          = require("language/CodeInspection"),
+        EventDispatcher         = require("utils/EventDispatcher");
+
+    EventDispatcher.makeEventDispatcher(exports);
+
+    /**
+     * Fired when a language server has finished (re)starting and is now serving/linting its languages.
+     * Handler args: `{ serverId, languages }`. Exposed for extensions that want to react to a server
+     * becoming available - it's loaded lazily, so they can't observe its startup directly.
+     * @const {string}
+     */
+    const EVENT_LANGUAGE_SERVER_STARTED = "languageServerStarted";
+
+    /**
+     * Fired when a language server's process has stopped. Note a normal project switch does NOT stop
+     * the server - it is repointed in place via workspace/didChangeWorkspaceFolders. This fires only
+     * when the process is actually recycled: the restart fallback (for servers that can't change
+     * workspace folders live) and manual restarts, each followed by EVENT_LANGUAGE_SERVER_STARTED once
+     * back up. Handler args: `{ serverId, languages }`.
+     * @const {string}
+     */
+    const EVENT_LANGUAGE_SERVER_STOPPED = "languageServerStopped";
 
     const LSP_CONNECTOR_ID = "ph-lsp";
     // Relative path required on the node side (resolved from src-node/utils.js). Lazy-loads the
@@ -225,6 +246,7 @@ define(function (require, exports, module) {
             }
             _startAndInit(client).then(function () {
                 client._crashCount = 0;
+                _announceServerStarted(client);
                 DocumentSync.openSupportedDocuments(client);
             }).catch(function (err) {
                 console.error("[LSP] auto-restart failed", client.serverId, err && (err.message || err));
@@ -622,6 +644,21 @@ define(function (require, exports, module) {
         });
     }
 
+    /**
+     * Announce that `client`'s server has (re)started and is now serving its languages: notify
+     * listeners (EVENT_LANGUAGE_SERVER_STARTED) and re-run inspection so any linter that defers to a
+     * language server (e.g. JSHint -> the TS service) drops its now-redundant results - even on a
+     * clean file, where the server's empty publishDiagnostics wouldn't trigger a re-run. Called from
+     * every path that brings a server up: initial registration, restart, and crash auto-restart.
+     */
+    function _announceServerStarted(client) {
+        exports.trigger(EVENT_LANGUAGE_SERVER_STARTED, {
+            serverId: client.serverId,
+            languages: client.languages
+        });
+        CodeInspection.requestRun();
+    }
+
     /**
      * Register and start a language server, wiring all providers into the editor.
      *
@@ -654,6 +691,7 @@ define(function (require, exports, module) {
             DocumentSync.openSupportedDocuments(client);
             DocumentHighlight.init();
             DocumentHighlight.registerClient(client);
+            _announceServerStarted(client);
             return client;
         } catch (err) {
             console.error("[LSP] failed to start server", config.serverId, err && (err.message || err));
@@ -745,6 +783,7 @@ define(function (require, exports, module) {
         await stopServerProcess(client);
         try {
             await _startAndInit(client);
+            _announceServerStarted(client);
             DocumentSync.openSupportedDocuments(client);
             // The find-references command's enabled state is computed on file switch; on a project
             // switch that happens while the server is still restarting (capabilities not yet
@@ -782,6 +821,29 @@ define(function (require, exports, module) {
         }
         await conn.execPeer("stopServer", { serverId: client.serverId });
         client._stopping = false;
+        exports.trigger(EVENT_LANGUAGE_SERVER_STOPPED, {
+            serverId: client.serverId,
+            languages: client.languages
+        });
+    }
+
+    /**
+     * Whether a successfully-initialised language server is currently providing diagnostics
+     * (linting) for the given Phoenix language id. Gated on `capabilities` - which is only set
+     * after a successful `initialize` - so a server that failed to start does not suppress a
+     * fallback linter (e.g. JSHint). Returns false in the browser, where no servers are registered.
+     *
+     * @param {string} languageId - Phoenix language id (e.g. "javascript")
+     * @return {boolean}
+     */
+    function isLintingProviderActive(languageId) {
+        for (const client of clients.values()) {
+            if (client.lintingProvider && client.capabilities &&
+                    client.languages && client.languages.indexOf(languageId) !== -1) {
+                return true;
+            }
+        }
+        return false;
     }
 
     exports.registerLanguageServer = registerLanguageServer;
@@ -789,4 +851,7 @@ define(function (require, exports, module) {
     exports.changeWorkspaceRoot = changeWorkspaceRoot;
     exports.pathToServerUri = pathToServerUri;
     exports.serverUriToVfsUri = serverUriToVfsUri;
+    exports.isLintingProviderActive = isLintingProviderActive;
+    exports.EVENT_LANGUAGE_SERVER_STARTED = EVENT_LANGUAGE_SERVER_STARTED;
+    exports.EVENT_LANGUAGE_SERVER_STOPPED = EVENT_LANGUAGE_SERVER_STOPPED;
 });
diff --git a/test/spec/Extn-ESLint-integ-test.js b/test/spec/Extn-ESLint-integ-test.js
index 0317659e94..44ff01065a 100644
--- a/test/spec/Extn-ESLint-integ-test.js
+++ b/test/spec/Extn-ESLint-integ-test.js
@@ -147,17 +147,31 @@ define(function (require, exports, module) {
             await _waitForProblemsPanelVisible(true);
         }
 
-        it("should show JSHint in desktop app if ESLint load failed for project", async function () {
+        // Wait until the TypeScript language server is the active JS linter. On desktop JSHint defers
+        // to it, so assertions about JSHint being absent are only meaningful once it's up.
+        async function _waitForLSPLintingJS() {
+            const LSPClient = await new Promise(function (resolve) {
+                testWindow.brackets.getModule(["languageTools/LSPClient"], resolve);
+            });
+            await awaitsFor(function () {
+                return LSPClient.isLintingProviderActive("javascript");
+            }, "the language server to be linting JavaScript", 30000);
+        }
+
+        it("should defer JSHint to the LSP even when ESLint load failed (desktop)", async function () {
             await SpecRunnerUtils.parkProject();
             await _openSimpleES6Project();
+            // ESLint can't load (no node_modules) -> it surfaces the npm-install message...
             await awaitsFor(async ()=>{
                 await _fileSwitcherroForESLintFailDetection();
                 return $("#problems-panel").text().includes(Strings.DESCRIPTION_ESLINT_DO_NPM_INSTALL);
             }, "ESLint error to be shown", 3000, 300);
-            await awaitsFor(()=>{
-                return $("#problems-panel").text().includes(JSHintErrorES6Error_js);
-            }, "JShint error to be shown");
-        }, 5000);
+            // ...but JSHint does NOT step in: on desktop the language server is the JS linter, so
+            // JSHint defers to it instead of being the ESLint-failure fallback.
+            await _waitForLSPLintingJS();
+            await awaits(100); // give JSHint time to run if it were going to
+            expect($("#problems-panel").text().includes("JSHint")).toBeFalse();
+        }, 40000);
 
         describe("ES6 project", function () {
             let es6ProjectPath;
@@ -180,13 +194,15 @@ define(function (require, exports, module) {
                 await _loadAndValidateES6Project();
             }, 30000);
 
-            it("should show ESLint and JSHint in desktop app for es6 project or below", async function () {
+            it("should show ESLint failure but defer JSHint to the LSP (es6 project, desktop)", async function () {
                 await _loadAndValidateES6Project();
-                await awaitsFor(async ()=>{
-                    await _fileSwitcherroForESLintFailDetection();
-                    return $("#problems-panel").text().includes(JSHintErrorES6Error_js);
-                }, "JShint error to be shown", 3000, 300);
-            }, 30000);
+                // ESLint v6 is unsupported, so ESLint surfaces its "load failed" message - but JSHint
+                // defers to the language server (the JS linter on desktop) rather than stepping in.
+                await _fileSwitcherroForESLintFailDetection();
+                await _waitForLSPLintingJS();
+                await awaits(100);
+                expect($("#problems-panel").text().includes("JSHint")).toBeFalse();
+            }, 40000);
         });
 
         describe("ES7 and JSHint project", function () {

From 2ebfbcf1b17e7011ae797998abee484bf7c8db33 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 13:21:08 +0530
Subject: [PATCH 2/9] feat(lsp): start the TypeScript server lazily, repoint
 only on project switch

The server was spawned eagerly on app boot and repointed on every project switch,
regardless of language - so a Python-only project still ran vtsls and re-indexed
it on switch. Mirror VS Code's onLanguage model instead: start the server only
when a served-language (JS/TS/JSX/TSX) file is the active editor, and repoint
(workspace/didChangeWorkspaceFolders) only when a served file is active right
after a project switch - never on ordinary file switches. Once started the server
stays alive idle (no proactive shutdown).

- main.js: _ensureServerForActiveEditor() driven by activeEditorChange + an initial
  evaluation; a pendingRepoint flag (set on EVENT_PROJECT_OPEN) gates the repoint so
  file switches don't touch the workspace-folder/restart machinery. Report a start
  failure via window.logger.reportError, deduped (start is retried lazily). Drop the
  eager appReady start and the now-meaningless readiness flag.
- LSPClient.changeWorkspaceRoot: check same-root first so a redundant call is a no-op
  and never restarts a server that lacks live workspace-folder support.
- tests: the lazy "never started" state isn't observable in the reused integration
  window (keep-alive, no stop path), so don't assert it; drop the readiness-flag wait
  (window load already guarantees the extension's appReady ran).
---
 .../default/TypeScriptSupport/main.js         | 89 +++++++++++++++----
 .../default/TypeScriptSupport/unittests.js    |  8 +-
 src/languageTools/LSPClient.js                | 16 ++--
 3 files changed, 84 insertions(+), 29 deletions(-)

diff --git a/src/extensions/default/TypeScriptSupport/main.js b/src/extensions/default/TypeScriptSupport/main.js
index 3ab4165db3..af4ee71838 100644
--- a/src/extensions/default/TypeScriptSupport/main.js
+++ b/src/extensions/default/TypeScriptSupport/main.js
@@ -33,6 +33,7 @@ define(function (require, exports, module) {
     const AppInit = brackets.getModule("utils/AppInit"),
         ProjectManager = brackets.getModule("project/ProjectManager"),
         DocumentManager = brackets.getModule("document/DocumentManager"),
+        EditorManager = brackets.getModule("editor/EditorManager"),
         FileSystem = brackets.getModule("filesystem/FileSystem"),
         NodeConnector = brackets.getModule("NodeConnector"),
         CodeIntelligence = require("./CodeIntelligence");
@@ -203,8 +204,7 @@ define(function (require, exports, module) {
      * @return {boolean}
      */
     function canRun() {
-        return typeof Phoenix !== "undefined" && Phoenix.isNativeApp &&
-            NodeConnector.isNodeAvailable && NodeConnector.isNodeAvailable();
+        return Phoenix.isNativeApp && NodeConnector.isNodeAvailable();
     }
 
     /**
@@ -252,23 +252,71 @@ define(function (require, exports, module) {
         }
     }
 
-    // Begin loading the LSP framework as soon as the (desktop-only) extension loads - the
-    // reliable moment for module loading - so it is ready by the time start() runs.
+    // Begin loading the LSP framework as soon as the (desktop-only) extension loads - the reliable
+    // moment for module loading - so it is ready by the time we first need it. This only loads the
+    // module; it does not spawn the server (that happens lazily, on the first served-language file).
     if (canRun()) {
         loadLSPClient();
     }
 
+    /**
+     * True when the active editor holds a language this server handles (JS/TS/JSX/TSX).
+     * @return {boolean}
+     */
+    function _isServedLanguageActive() {
+        const editor = EditorManager.getActiveEditor();
+        return !!(editor && SUPPORTED_LANGUAGES.indexOf(editor.getLanguageForSelection().getId()) !== -1);
+    }
+
+    let starting = false;
+    let pendingRepoint = false;     // a project switch happened; repoint once a served file is active there
+    let initErrorReported = false;  // start() is retried lazily, so report a failure to telemetry only once
+
+    /**
+     * Lazily start the language server when a served-language file is active, and - only right after a
+     * project switch - repoint the running server at the new root. Mirrors VS Code's onLanguage model:
+     * a project with no JS/TS file opened never spawns vtsls; switching to a non-JS project leaves the
+     * idle server where it was; and plain file switches within a project never touch the
+     * workspace-folder / restart machinery (so they can't interfere with a crash auto-restart).
+     */
+    function _ensureServerForActiveEditor() {
+        if (!canRun() || !_isServedLanguageActive()) {
+            return;
+        }
+
+        // Not running yet: lazily start it (a fresh start already points at the current project root).
+        if (!registered) {
+            if (starting) {
+                return; // a start kicked off by a previous activeEditorChange is still in flight
+            }
+            starting = true;
+            pendingRepoint = false;
+            start().catch(function (err) {
+                if (!initErrorReported) {
+                    initErrorReported = true;
+                    window.logger && window.logger.reportError(err, "[TypeScriptSupport] LSP init failed");
+                }
+            }).finally(function () {
+                starting = false;
+            });
+            return;
+        }
+
+        // Running: repoint at the current project, but only when a project switch armed it - never on
+        // ordinary file switches.
+        if (pendingRepoint) {
+            pendingRepoint = false;
+            loadLSPClient().then(function (LSPClient) {
+                LSPClient.changeWorkspaceRoot(SERVER_ID);
+            });
+        }
+    }
+
     AppInit.appReady(function () {
         if (!canRun()) {
             return;
         }
         _refreshCheckJs();
-        start().catch(function (err) {
-            console.error("[TypeScriptSupport] init failed", err && (err.message || err));
-        }).finally(function () {
-            // Signal for integration tests that the server start has been attempted/settled.
-            window._TypeScriptSupportReadyToIntegTest = true;
-        });
 
         // Offer project-wide code intelligence (creates a default ts/jsconfig) when a JS/TS file is
         // opened in a project that has no config yet. Projects that already carry one are silent.
@@ -283,17 +331,20 @@ define(function (require, exports, module) {
             }
         });
 
-        // Re-point the server at the new workspace root when the project changes, and re-evaluate
-        // whether the new project type-checks its JS. This uses workspace/didChangeWorkspaceFolders
-        // (no process restart, so no tsserver cold start) and only falls back to a full restart for
-        // servers that don't support live workspace-folder changes.
+        // Lazily start / repoint the server from the active editor's language (VS Code's onLanguage
+        // model). Evaluate the editor already open at startup (session restore), then track switches.
+        EditorManager.on("activeEditorChange", _ensureServerForActiveEditor);
+        _ensureServerForActiveEditor();
+
+        // On project switch: re-evaluate checkJs and arm a one-shot repoint. The actual repoint
+        // (workspace/didChangeWorkspaceFolders, no restart) happens the next time a served-language
+        // file is active - here if one already is, otherwise on the activeEditorChange as the new
+        // project's file opens. Plain file switches within a project never set this, so they don't
+        // repoint.
         ProjectManager.on(ProjectManager.EVENT_PROJECT_OPEN, function () {
             _refreshCheckJs();
-            if (registered) {
-                loadLSPClient().then(function (LSPClient) {
-                    LSPClient.changeWorkspaceRoot(SERVER_ID);
-                });
-            }
+            pendingRepoint = true;
+            _ensureServerForActiveEditor();
         });
 
         // Pick up a tsconfig/jsconfig being added, edited, or removed at the project root.
diff --git a/src/extensions/default/TypeScriptSupport/unittests.js b/src/extensions/default/TypeScriptSupport/unittests.js
index 551edd9381..f140175173 100644
--- a/src/extensions/default/TypeScriptSupport/unittests.js
+++ b/src/extensions/default/TypeScriptSupport/unittests.js
@@ -55,10 +55,10 @@ define(function (require, exports, module) {
             CodeInspection = testWindow.brackets.test.CodeInspection;
             QuickViewManager = testWindow.brackets.getModule("features/QuickViewManager");
             CodeInspection.toggleEnabled(true);
-            // Wait until the extension has attempted to start the language server.
-            await awaitsFor(function () {
-                return testWindow._TypeScriptSupportReadyToIntegTest;
-            }, "TypeScript LSP server to start", 30000);
+            // createTestWindowAndRun already waited for the app (and so the extension's appReady, which
+            // wires the lazy-start hooks) to finish loading. The server itself starts lazily on the
+            // first served-language file - the warm-up below opens a .ts, which starts it; waiting for
+            // its diagnostics ("not assignable") is the real readiness signal.
 
             // Warm up tsserver. Its very first request pays a large one-time cost - spawning node,
             // launching vtsls, and loading the TypeScript library + project - which on a slow/loaded
diff --git a/src/languageTools/LSPClient.js b/src/languageTools/LSPClient.js
index 4478fdf117..5d814056e4 100644
--- a/src/languageTools/LSPClient.js
+++ b/src/languageTools/LSPClient.js
@@ -742,6 +742,16 @@ define(function (require, exports, module) {
         if (!client) {
             return;
         }
+        // Resolve the target root FIRST: a redundant call for the same root must be a cheap no-op and
+        // must never restart (this can be called often - e.g. once per editor switch). This check has
+        // to precede the restart fallbacks below, or a same-root call to a server that lacks live
+        // workspace-folder support would pointlessly recycle the process.
+        const newVfsPath = (client.config.rootUriProvider && client.config.rootUriProvider()) || _projectRootPath();
+        const newUri = newVfsPath ? pathToServerUri(newVfsPath) : null;
+        const oldUri = client.rootUri || null;
+        if (newUri === oldUri) {
+            return; // same workspace - nothing to do
+        }
         // Not up yet (e.g. the project switched before init finished) - a (re)start picks up the
         // current root on its own.
         if (!client.capabilities) {
@@ -754,12 +764,6 @@ define(function (require, exports, module) {
         if (!supportsLiveChange) {
             return restartLanguageServer(serverId);
         }
-        const newVfsPath = (client.config.rootUriProvider && client.config.rootUriProvider()) || _projectRootPath();
-        const newUri = newVfsPath ? pathToServerUri(newVfsPath) : null;
-        const oldUri = client.rootUri || null;
-        if (newUri === oldUri) {
-            return; // same workspace - nothing to do
-        }
         const conn = await getConnector();
         const added = newUri ? [{ uri: newUri, name: FileUtils.getBaseName(newVfsPath) }] : [];
         const removed = oldUri ? [{ uri: oldUri, name: client.rootName || FileUtils.getBaseName(oldUri) }] : [];

From bd1806fc63f8522a0f70739ad3c07f020955c2aa Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 13:35:16 +0530
Subject: [PATCH 3/9] fix(lsp): show the source module on a highlighted
 auto-import, not the clipped detail
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The highlighted auto-import row rendered token.detail inline - a long
"Add import from <module> …" string that clipped to a useless "Add import from
"fs" names…", while non-highlighted rows showed the short module. Skip the inline
signature for auto-imports (their detail is that import line; the doc popup still
shows it in full) and keep the short source-module tag visible on the highlighted
row. In-scope items are unchanged - they still show their type signature inline.
---
 src/languageTools/DefaultProviders.js |  6 ++++--
 src/styles/brackets.less              | 10 ++++------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/languageTools/DefaultProviders.js b/src/languageTools/DefaultProviders.js
index ab0e4d9a66..4d1a9dd255 100644
--- a/src/languageTools/DefaultProviders.js
+++ b/src/languageTools/DefaultProviders.js
@@ -494,8 +494,10 @@ define(function (require, exports, module) {
             // Inline: the signature for the highlighted row. Re-inject every time (it is
             // idempotent) because the list DOM is rebuilt on each keystroke, which drops a
             // previously-injected signature. resolveCompletion is cached separately (_lspResolved),
-            // so this does not cause extra LSP requests.
-            if (token.detail) {
+            // so this does not cause extra LSP requests. Skip it for auto-imports - their detail is a
+            // long "Add import from <module>" string that just clips uselessly; the short source-module
+            // tag stays visible there instead (see CSS), and the doc popup carries the full import.
+            if (token.detail && !_isAutoImport(token)) {
                 _injectInlineSignature($span, token.detail);
             }
             // Beside the list: the signature header + the (possibly long) documentation.
diff --git a/src/styles/brackets.less b/src/styles/brackets.less
index 88f15a97e5..33706d66f9 100644
--- a/src/styles/brackets.less
+++ b/src/styles/brackets.less
@@ -2663,12 +2663,10 @@ span.brackets-hints-with-type-details {
     opacity: 0.55;
 }
 
-// On the highlighted row the side doc popup already names the import source, and the inline
-// signature takes the right slot, so hide the source tag there to keep the row uncluttered.
-// The clubbed "N imports…" tag is the row's whole purpose, so keep it visible when highlighted.
-.codehint-menu.lsp-hints .highlight .lsp-hint-source:not(.lsp-hint-import-group) {
-    display: none;
-}
+// The source-module tag stays visible on the highlighted row too. Auto-imports get no inline
+// signature (their detail is a long "Add import from <module>" that would just clip), so the short
+// module tag is the most useful thing to keep there; in-scope items have no source tag and show
+// their signature instead.
 
 // The clubbed "N imports…" affordance reads as an action, not a source path: not italic, a touch
 // more present than a plain source tag.

From ebbe987c130601d97923d13577e319892d1736df Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 14:07:20 +0530
Subject: [PATCH 4/9] feat(lsp): unify code-hint doc & parameter popups, make
 doc text selectable

Restyle the LSP documentation popup and the parameter-hint popup so all
three code-hint surfaces (completion list, doc popup, parameter hints)
share one visual identity: same menu background, border radius and
shadow, in both light and dark themes.

Redesign the fenced code blocks inside the doc popup as elevated panels
and add a per-block copy button (with copied feedback).

Make the doc popup text selectable: add user-select and an I-beam
cursor, and stop the popup's own mousedown/click from bubbling to
Bootstrap's outside-click handler (which was tearing the popup down
before a drag-select could start). Native selection is preserved
because the handler does not preventDefault.
---
 src/languageTools/DefaultProviders.js | 62 +++++++++++++++++
 src/styles/brackets.less              | 97 +++++++++++++++++++++------
 2 files changed, 140 insertions(+), 19 deletions(-)

diff --git a/src/languageTools/DefaultProviders.js b/src/languageTools/DefaultProviders.js
index 4d1a9dd255..063c043fd0 100644
--- a/src/languageTools/DefaultProviders.js
+++ b/src/languageTools/DefaultProviders.js
@@ -201,6 +201,47 @@ define(function (require, exports, module) {
         return parts.join("");
     }
 
+    // Minimal copy glyph (stroked, inherits currentColor) for the per-code-block copy button.
+    const COPY_ICON = '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" ' +
+        'stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+        '<rect x="9" y="9" width="13" height="13" rx="2"/>' +
+        '<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
+
+    function _copyText(text) {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+            return navigator.clipboard.writeText(text);
+        }
+        return new Promise(function (resolve, reject) {
+            try {
+                const ta = document.createElement("textarea");
+                ta.value = text;
+                ta.style.cssText = "position:fixed;opacity:0;pointer-events:none;";
+                document.body.appendChild(ta);
+                ta.select();
+                document.execCommand("copy");
+                document.body.removeChild(ta);
+                resolve();
+            } catch (e) {
+                reject(e);
+            }
+        });
+    }
+
+    // Give every code block in the doc popup a hover-revealed copy button.
+    function _addCopyButtons($popup) {
+        $popup.find("pre").each(function () {
+            const $pre = $(this);
+            if ($pre.children(".lsp-copy-btn").length) {
+                return;
+            }
+            $("<button>")
+                .addClass("lsp-copy-btn")
+                .attr({ type: "button", title: Strings.CMD_COPY, "aria-label": Strings.CMD_COPY })
+                .html(COPY_ICON)
+                .appendTo($pre);
+        });
+    }
+
     function _showDocPopup($hint, docHtml) {
         var $menu = $hint.closest(".codehint-menu");
         if (!docHtml || !$menu.length) {
@@ -213,8 +254,29 @@ define(function (require, exports, module) {
         // position:fixed, so it is still placed in viewport coordinates and is never clipped.
         if (!$lspDocPopup || !$lspDocPopup.parent().is($menu)) {
             $lspDocPopup = $("<div>").addClass("lsp-hint-doc-popup").appendTo($menu);
+            // Keep mouse interaction inside the popup from reaching the document-level handlers that
+            // dismiss the completion (Bootstrap's "close dropdown on outside click"), so the user can
+            // select and copy text/code without the popup vanishing. Crucially we do NOT preventDefault
+            // here - the browser's native text selection must keep working.
+            $lspDocPopup
+                .on("mousedown click", function (e) {
+                    e.stopPropagation();
+                })
+                .on("click", ".lsp-copy-btn", function (e) {
+                    e.preventDefault();
+                    const $btn = $(this);
+                    const text = $btn.closest("pre").find("code").text();
+                    if (!text) {
+                        return;
+                    }
+                    _copyText(text).then(function () {
+                        $btn.addClass("copied");
+                        setTimeout(function () { $btn.removeClass("copied"); }, 1200);
+                    }).catch(function () { /* clipboard unavailable - ignore */ });
+                });
         }
         $lspDocPopup.empty().html(docHtml);
+        _addCopyButtons($lspDocPopup);
 
         // Anchor to the actual visible list (ul.dropdown-menu), not the zero-width .codehint-menu
         // positioning element, so the popup sits flush beside the list without overlapping it.
diff --git a/src/styles/brackets.less b/src/styles/brackets.less
index 33706d66f9..5464a237cb 100644
--- a/src/styles/brackets.less
+++ b/src/styles/brackets.less
@@ -2452,44 +2452,101 @@ a, img {
     line-height: 1.5;
     word-wrap: break-word;
 
-    background: @bc-panel-bg;
+    // Share the completion list's surface so the two popups read as one widget (the list is
+    // @bc-menu-bg with @bc-border-radius and a 0 3px 9px @bc-shadow). Matching bg, radius and shadow
+    // is what stops the doc popup from looking like a separate, mismatched card.
+    background: @bc-menu-bg;
     color: @bc-text;
     border: 1px solid rgba(0, 0, 0, 0.12);
-    border-radius: 6px;
-    box-shadow: 0 4px 15px @bc-shadow-large;
+    border-radius: @bc-border-radius;
+    box-shadow: 0 3px 9px @bc-shadow;
+    // Let users select and copy the docs/signature (the popup otherwise inherits user-select:none),
+    // and show the text/I-beam cursor so it reads as selectable.
+    user-select: text;
+    -webkit-user-select: text;
+    cursor: text;
 
     .dark & {
-        background: @dark-bc-panel-bg;
+        background: @dark-bc-menu-bg;
         color: @dark-bc-text;
-        border-color: rgba(255, 255, 255, 0.10);
-        box-shadow: 0 4px 15px @dark-bc-shadow-large;
+        border-color: rgba(255, 255, 255, 0.09);
+        box-shadow: 0 3px 9px @dark-bc-shadow;
     }
 
     p { margin: 6px 0; }
     p:first-child { margin-top: 0; }
     p:last-child { margin-bottom: 0; }
 
+    // The signature is the popup's focal point: present it as one elevated code panel - a cool inset
+    // lifted off the surface by a hairline border and a 1px top inner-highlight, with comfortable
+    // padding so the syntax tokens have room to breathe. The copy button is anchored to it.
     pre {
-        margin: 6px 0;
-        padding: 8px 10px;
-        background: @bc-panel-bg-alt;
-        border: 1px solid rgba(0, 0, 0, 0.10);
-        border-radius: 5px;
+        position: relative;
+        margin: 1px 0 11px 0;
+        padding: 9px 12px;
+        background: #f2f4f7;
+        border: 1px solid rgba(0, 0, 0, 0.07);
+        border-radius: 6px;
+        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.7);
         overflow-x: auto;
         white-space: pre;
         .dark & {
-            background: #1c1c1c;
-            border-color: rgba(255, 255, 255, 0.09);
+            background: #1a1b1f;
+            border-color: rgba(255, 255, 255, 0.08);
+            box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.045);
         }
     }
     pre code {
         font-family: 'SourceCodePro', 'SF Mono', Menlo, Consolas, monospace;
         font-size: 12px;
+        line-height: 1.55;
         color: @bc-text-emphasized;
         background: none;
         padding: 0;
         .dark & { color: @dark-bc-text-emphasized; }
     }
+
+    // Hover-revealed copy button, sitting on the code panel.
+    .lsp-copy-btn {
+        position: absolute;
+        top: 5px;
+        right: 5px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 22px;
+        height: 22px;
+        padding: 0;
+        border: 1px solid rgba(0, 0, 0, 0.10);
+        border-radius: 5px;
+        background: #ffffff;
+        color: #57606a;
+        cursor: pointer;
+        opacity: 0;
+        transition: opacity 0.12s ease, background 0.12s ease, color 0.12s ease, border-color 0.12s ease;
+        .dark & {
+            border-color: rgba(255, 255, 255, 0.12);
+            background: #25272e;
+            color: #b9bfc7;
+        }
+    }
+    pre:hover .lsp-copy-btn { opacity: 0.85; }
+    .lsp-copy-btn:hover {
+        opacity: 1;
+        background: #f3f5f8;
+        color: @bc-text-emphasized;
+        .dark & { background: #2f323a; color: @dark-bc-text-emphasized; }
+    }
+    .lsp-copy-btn:focus-visible { opacity: 1; outline: 1px solid @bc-text-link; outline-offset: 1px; }
+    // Copied: swap the glyph for a check in the success accent.
+    .lsp-copy-btn.copied { opacity: 1; }
+    .lsp-copy-btn.copied svg { display: none; }
+    .lsp-copy-btn.copied::after {
+        content: "✓";
+        font-size: 13px;
+        font-weight: 700;
+        color: @accent-success;
+    }
     code {
         font-family: 'SourceCodePro', 'SF Mono', Menlo, Consolas, monospace;
         font-size: 11.5px;
@@ -2708,17 +2765,19 @@ span.brackets-hints-with-type-details {
     overflow: hidden;
     padding: 5px 11px;
     text-align: left;
-    border-radius: 6px;
+    // Share the completion list / doc popup surface so all three code-hint popups read as one
+    // family (menu bg, @bc-border-radius, 0 3px 9px @bc-shadow).
+    border-radius: @bc-border-radius;
     color: @bc-text;
-    background: @bc-panel-bg;
+    background: @bc-menu-bg;
     border: 1px solid rgba(0, 0, 0, 0.12);
-    box-shadow: 0 4px 15px @bc-shadow-large;
+    box-shadow: 0 3px 9px @bc-shadow;
 
     .dark & {
         color: @dark-bc-text;
-        background: @dark-bc-panel-bg;
-        border-color: rgba(255, 255, 255, 0.12);
-        box-shadow: 0 4px 15px @dark-bc-shadow-large;
+        background: @dark-bc-menu-bg;
+        border-color: rgba(255, 255, 255, 0.09);
+        box-shadow: 0 3px 9px @dark-bc-shadow;
     }
 }
 

From 68fa5a6b2260ca24ff5424563fc245092b5d3427 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 14:08:47 +0530
Subject: [PATCH 5/9] docs(claude): clarify var is legacy; new code must use
 const/let

---
 CLAUDE.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 011f189c80..7c96cb1e69 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,6 +7,7 @@
 - Never include `Co-Authored-By` lines in commit messages.
 
 ## Code Style
+- This is a long-lived, partly legacy codebase — you will see older patterns like `var` in existing files. Leave surrounding legacy style alone unless you're deliberately refactoring it, but **any new code you write must use `const`/`let`, never `var`** (see below). Match the file's other conventions where they don't conflict with these rules.
 - 4-space indentation, never tabs.
 - Always use semicolons.
 - Brace style: (`if (x) {`), single-line blocks allowed.

From 2654af91f1b5a9bbc69dc50c6ea12266a9422ac4 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 16:40:43 +0530
Subject: [PATCH 6/9] style(lsp): give doc-popup code blocks a subtle
 surface-derived tint

Replace the separate-coloured signature/code panel with a faint wash
derived from the popup surface (low-opacity black/white), a hairline
border and soft corners. Distinct enough to register as a code region,
quiet enough not to look like a pasted-in card, and consistent across
light and dark themes.
---
 src/styles/brackets.less | 47 +++++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 22 deletions(-)

diff --git a/src/styles/brackets.less b/src/styles/brackets.less
index 5464a237cb..a40fd989e5 100644
--- a/src/styles/brackets.less
+++ b/src/styles/brackets.less
@@ -2477,25 +2477,28 @@ a, img {
     p:first-child { margin-top: 0; }
     p:last-child { margin-bottom: 0; }
 
-    // The signature is the popup's focal point: present it as one elevated code panel - a cool inset
-    // lifted off the surface by a hairline border and a 1px top inner-highlight, with comfortable
-    // padding so the syntax tokens have room to breathe. The copy button is anchored to it.
+    // Code blocks - the top signature and any fenced blocks inside the docs - stay cohesive with the
+    // popup surface rather than being a separate-coloured panel: the fill is a faint tint *derived
+    // from* the surface (a low-opacity black/white wash, so it reads the same in both themes) with a
+    // hairline border and soft corners. Distinct enough to register as a code region, quiet enough
+    // not to look like a pasted-in card. Copy button floats at its top-right.
     pre {
         position: relative;
-        margin: 1px 0 11px 0;
-        padding: 9px 12px;
-        background: #f2f4f7;
-        border: 1px solid rgba(0, 0, 0, 0.07);
+        margin: 6px 0 10px 0;
+        padding: 7px 10px;
+        background: rgba(0, 0, 0, 0.08);
+        border: 1px solid rgba(0, 0, 0, 0.10);
         border-radius: 6px;
-        box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.7);
+        box-shadow: none;
         overflow-x: auto;
         white-space: pre;
         .dark & {
-            background: #1a1b1f;
-            border-color: rgba(255, 255, 255, 0.08);
-            box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.045);
+            background: rgba(255, 255, 255, 0.09);
+            border-color: rgba(255, 255, 255, 0.10);
         }
     }
+    // The signature is the very first block; no top margin so it sits snug under the popup's top edge.
+    pre:first-child { margin-top: 0; }
     pre code {
         font-family: 'SourceCodePro', 'SF Mono', Menlo, Consolas, monospace;
         font-size: 12px;
@@ -2506,36 +2509,36 @@ a, img {
         .dark & { color: @dark-bc-text-emphasized; }
     }
 
-    // Hover-revealed copy button, sitting on the code panel.
+    // Hover-revealed copy button, floating over the flush code block. Borderless and transparent at
+    // rest so it doesn't read as a chip on the bare surface; it grows a faint pill only on its own
+    // hover.
     .lsp-copy-btn {
         position: absolute;
-        top: 5px;
-        right: 5px;
+        top: 3px;
+        right: 3px;
         display: inline-flex;
         align-items: center;
         justify-content: center;
         width: 22px;
         height: 22px;
         padding: 0;
-        border: 1px solid rgba(0, 0, 0, 0.10);
+        border: 0;
         border-radius: 5px;
-        background: #ffffff;
+        background: none;
         color: #57606a;
         cursor: pointer;
         opacity: 0;
-        transition: opacity 0.12s ease, background 0.12s ease, color 0.12s ease, border-color 0.12s ease;
+        transition: opacity 0.12s ease, background 0.12s ease, color 0.12s ease;
         .dark & {
-            border-color: rgba(255, 255, 255, 0.12);
-            background: #25272e;
             color: #b9bfc7;
         }
     }
-    pre:hover .lsp-copy-btn { opacity: 0.85; }
+    pre:hover .lsp-copy-btn { opacity: 0.7; }
     .lsp-copy-btn:hover {
         opacity: 1;
-        background: #f3f5f8;
+        background: rgba(0, 0, 0, 0.06);
         color: @bc-text-emphasized;
-        .dark & { background: #2f323a; color: @dark-bc-text-emphasized; }
+        .dark & { background: rgba(255, 255, 255, 0.14); color: @dark-bc-text-emphasized; }
     }
     .lsp-copy-btn:focus-visible { opacity: 1; outline: 1px solid @bc-text-link; outline-offset: 1px; }
     // Copied: swap the glyph for a check in the success accent.

From 751e5c85101d73abf242f42c55d816f29d30c879 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 17:46:37 +0530
Subject: [PATCH 7/9] perf(lsp): stop Tern from double-indexing JS when the TS
 server is active

The legacy Tern engine and vtsls both ran for JS files on desktop: the
priority system meant the LSP's hints always won, but Tern still spun up
its worker and indexed the whole project in parallel - pure waste.

Gate it: JavaScriptCodeHints now skips creating a Tern session (so
ScopeManager never indexes) whenever the language server serves the
file's language, mirroring JSHint's lazy desktop-only LSPClient handle so
the browser build is untouched. The server starts lazily and can come up
after Tern already indexed the first file, so we also reset Tern on
EVENT_LANGUAGE_SERVER_STARTED and let it resume on _STOPPED.
---
 .../default/JavaScriptCodeHints/main.js       | 59 ++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/src/extensions/default/JavaScriptCodeHints/main.js b/src/extensions/default/JavaScriptCodeHints/main.js
index e69df616ae..37990a9ab3 100644
--- a/src/extensions/default/JavaScriptCodeHints/main.js
+++ b/src/extensions/default/JavaScriptCodeHints/main.js
@@ -59,6 +59,44 @@ define(function (require, exports, module) {
     var _inlineScriptLanguages = ["html", "php"],
         phProvider = new JSParameterHintsProvider();
 
+    // --- Defer to the TypeScript language server (vtsls) when it is active ------------------------
+    // When vtsls serves a JS/TS file, Tern is redundant: its hints lose to the server's higher-
+    // priority ones (see the provider registrations at priority 0 below) and its background project
+    // indexing only duplicates work the server already does. So on desktop we resolve a handle to
+    // LSPClient (intentionally kept out of the browser build) and, for any language the server serves,
+    // skip creating a Tern session - ScopeManager then never indexes the project in parallel with the
+    // server. The server starts lazily and can come up *after* Tern already indexed the first file, so
+    // we also listen for its start event to drop that data and re-evaluate the active editor; on stop
+    // we let Tern take over again. In the browser _lspClient stays null and Tern behaves as before.
+    // (We piggy-back on isLintingProviderActive as the "server is up and serving this language"
+    // signal - the same one JSHint uses to defer its linting.)
+    let _lspClient = null;
+    let _reinstallActiveEditorListeners = null;  // assigned at appReady, once the listeners exist
+
+    function _lspServesLanguage(languageId) {
+        return !!(_lspClient && languageId && _lspClient.isLintingProviderActive(languageId));
+    }
+
+    if (Phoenix.isNativeApp) {
+        brackets.getModule(["languageTools/LSPClient"], function (LSPClient) {
+            _lspClient = LSPClient;
+            LSPClient.on(LSPClient.EVENT_LANGUAGE_SERVER_STARTED, function () {
+                // The server may have started after Tern already indexed the first file - drop that
+                // analysis to reclaim the memory, then re-gate the active editor so it defers now.
+                ScopeManager.handleProjectClose();
+                if (_reinstallActiveEditorListeners) {
+                    _reinstallActiveEditorListeners();
+                }
+            });
+            LSPClient.on(LSPClient.EVENT_LANGUAGE_SERVER_STOPPED, function () {
+                // Server gone - let Tern resume handling the active editor.
+                if (_reinstallActiveEditorListeners) {
+                    _reinstallActiveEditorListeners();
+                }
+            });
+        });
+    }
+
     // Define the detectedExclusions which are files that have been detected to cause Tern to run out of control.
     PreferencesManager.definePreference("jscodehints.detectedExclusions", "array", [], {
         description: Strings.DESCRIPTION_DETECTED_EXCLUSIONS
@@ -663,7 +701,18 @@ define(function (require, exports, module) {
                 return;
             }
 
-            if (editor && HintUtils.isSupportedLanguage(LanguageManager.getLanguageForPath(editor.document.file.fullPath).getId())) {
+            const languageId = editor
+                ? LanguageManager.getLanguageForPath(editor.document.file.fullPath).getId()
+                : null;
+
+            // When the TypeScript language server serves this language, defer to it entirely: don't
+            // create a Tern session, so ScopeManager never indexes the project alongside the server.
+            if (_lspServesLanguage(languageId)) {
+                session = null;
+                return;
+            }
+
+            if (editor && HintUtils.isSupportedLanguage(languageId)) {
                 initializeSession(editor, previousEditor);
                 editor
                     .on(HintUtils.eventName("change"), function (event, editor, changeList) {
@@ -845,6 +894,14 @@ define(function (require, exports, module) {
             ScopeManager.handleProjectOpen();
         });
 
+        // Lets the LSP start/stop handlers re-evaluate the active editor (gate Tern off when the
+        // server comes up, back on when it goes away) - defined here, where the listeners exist.
+        _reinstallActiveEditorListeners = function () {
+            const activeEditor = EditorManager.getActiveEditor();
+            uninstallEditorListeners(activeEditor);
+            installEditorListeners(activeEditor);
+        };
+
         // immediately install the current editor
         installEditorListeners(EditorManager.getActiveEditor());
 

From 05b4c2f51d8b43765e27b67a3c21b6e281c53826 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 17:46:46 +0530
Subject: [PATCH 8/9] perf(lsp): incremental textDocument/didChange sync

Previously every keystroke (debounced) shipped the entire file to the
language server, ignoring the server's advertised incremental capability -
costly on large files under sustained typing (vtsls re-reads the whole
buffer each time).

Now DocumentSync reads the server's textDocumentSync kind and, when it is
Incremental, accumulates the CodeMirror change records during the debounce
window and sends them as ordered LSP range edits; it falls back to full
text when the server wants full sync, when a change record can't be mapped,
or on a refresh-from-disk. notifyDidChange takes the contentChanges array
so the caller decides the shape.

Adds two integration tests that drive many real edits (sequential inserts,
mid-document replacement, deletion, and a same-line multi-cursor batch) and
use the server's own diagnostics as the sync oracle.
---
 .../default/TypeScriptSupport/unittests.js    | 84 +++++++++++++++++++
 src/languageTools/DocumentSync.js             | 82 ++++++++++++++++--
 src/languageTools/LSPClient.js                |  7 +-
 .../ts/incremental.ts                         |  3 +
 4 files changed, 168 insertions(+), 8 deletions(-)
 create mode 100644 test/spec/TypeScriptSupport-test-files/ts/incremental.ts

diff --git a/src/extensions/default/TypeScriptSupport/unittests.js b/src/extensions/default/TypeScriptSupport/unittests.js
index f140175173..f4a39d3806 100644
--- a/src/extensions/default/TypeScriptSupport/unittests.js
+++ b/src/extensions/default/TypeScriptSupport/unittests.js
@@ -152,6 +152,90 @@ define(function (require, exports, module) {
             expect(panelText().toLowerCase().includes("jshint")).toBe(false);
         }, 45000);
 
+        // ----- incremental document sync ----------------------------------------------------------
+
+        // DocumentSync sends incremental range edits (not the whole file) when the server advertises
+        // incremental sync. These two tests use the server's OWN diagnostics as the sync oracle: a
+        // type error can only appear or clear exactly on cue if the server's copy of the document
+        // matches the editor after every edit. If incremental replay ever drifted, the error would
+        // land on the wrong text (or not at all), failing the assertion. incremental.ts is mutated in
+        // memory only and force-closed without saving, so the on-disk fixture stays clean.
+
+        function inspectionClean() {
+            return $("#status-inspection").hasClass("inspection-valid");
+        }
+
+        it("keeps the server in sync across many incremental edits", async function () {
+            await _openInProject("ts/", "incremental.ts");
+            const editor = EditorManager.getCurrentFullEditor();
+            const doc = editor.document;
+            await awaitsFor(inspectionClean, "incremental.ts to start clean", 30000);
+
+            // 1) Many single-character inserts - each a separate change record - appending a valid
+            // statement. Fed only these incremental edits, the server must still parse it as clean.
+            const insert = "\nlet d: number = 4;";
+            for (let i = 0; i < insert.length; i++) {
+                const line = editor.lineCount() - 1;
+                doc.replaceRange(insert[i], { line: line, ch: editor.getLine(line).length });
+            }
+            await awaitsFor(inspectionClean, "still clean after many single-char inserts", 30000);
+
+            // 2) A whole-line replacement (non-empty range) that introduces a type error on line 0.
+            doc.replaceRange('let a: number = "oops";',
+                { line: 0, ch: 0 }, { line: 0, ch: editor.getLine(0).length });
+            await awaitsFor(function () {
+                return panelText().includes("not assignable");
+            }, "type error after a mid-document line replacement", 30000);
+
+            // 3) Fix it with another replacement -> the error must clear.
+            doc.replaceRange("let a: number = 0;",
+                { line: 0, ch: 0 }, { line: 0, ch: editor.getLine(0).length });
+            await awaitsFor(inspectionClean, "error clears after the fix", 30000);
+
+            // 4) A multi-line deletion (non-empty range, empty text): drop line 1 entirely. Still valid.
+            doc.replaceRange("", { line: 1, ch: 0 }, { line: 2, ch: 0 });
+            await awaitsFor(inspectionClean, "still clean after a deletion", 30000);
+
+            // Discard the in-memory edits so the fixture is pristine for re-runs / other tests.
+            await awaitsForDone(CommandManager.execute(Commands.FILE_CLOSE, { _forceClose: true }),
+                "close incremental.ts");
+        }, 90000);
+
+        it("keeps the server in sync for a batched multi-cursor edit", async function () {
+            await _openInProject("ts/", "incremental.ts");
+            const editor = EditorManager.getCurrentFullEditor();
+            await awaitsFor(inspectionClean, "incremental.ts to start clean", 30000);
+
+            // Two cursors on the SAME line, edited in one operation - the order-sensitive case, since
+            // the first replacement shifts the columns of the second. CodeMirror applies and reports
+            // the batch so that replaying the records in array order reproduces the result; this
+            // confirms our 1:1 change-record -> LSP-range map honours that ordering.
+            // "let a: number = 0;" -> "let abc: number = \"hello\";"
+            editor.setSelections([
+                { start: { line: 0, ch: 4 }, end: { line: 0, ch: 5 } },     // the identifier `a`
+                { start: { line: 0, ch: 16 }, end: { line: 0, ch: 17 } }    // the literal `0`
+            ]);
+            editor._codeMirror.replaceSelections(["abc", '"hello"']);
+            // Editor side is correct by construction; the assertion that matters is the server agreeing
+            // - it can only report the error if it received the same text.
+            expect(editor.getLine(0)).toBe('let abc: number = "hello";');
+            await awaitsFor(function () {
+                return panelText().includes("not assignable");
+            }, "type error after the multi-cursor edit", 30000);
+
+            // Revert both cursors in one operation -> the error must clear (sync holds the other way).
+            editor.setSelections([
+                { start: { line: 0, ch: 4 }, end: { line: 0, ch: 7 } },     // `abc`
+                { start: { line: 0, ch: 18 }, end: { line: 0, ch: 25 } }    // `"hello"`
+            ]);
+            editor._codeMirror.replaceSelections(["a", "0"]);
+            expect(editor.getLine(0)).toBe("let a: number = 0;");
+            await awaitsFor(inspectionClean, "error clears after reverting the multi-cursor edit", 30000);
+
+            await awaitsForDone(CommandManager.execute(Commands.FILE_CLOSE, { _forceClose: true }),
+                "close incremental.ts");
+        }, 90000);
+
         // ----- hover quick-actions (Go to Definition / Find Usages) -------------------------------
 
         // Query the hover popover at a position the same way QuickViewManager does internally.
diff --git a/src/languageTools/DocumentSync.js b/src/languageTools/DocumentSync.js
index ae400716ea..1c56399f8b 100644
--- a/src/languageTools/DocumentSync.js
+++ b/src/languageTools/DocumentSync.js
@@ -26,9 +26,12 @@
  * disposes it (firing `beforeDocumentDelete`) only when the last editor/working-set reference
  * is gone, so a file open in multiple panes is opened once and closed once.
  *
- * `didChange` is debounced and sends the full document text (simple and correct; incremental
- * sync can be added later). Before any feature request, `flush()` sends the latest pending
- * change synchronously so the server's view matches the cursor.
+ * `didChange` is debounced. When the server advertises incremental sync, the edits made during
+ * the debounce window are accumulated and sent as ordered LSP range edits (so a keystroke ships a
+ * tiny payload instead of the whole file); otherwise it falls back to sending the full document
+ * text. Any change record that can't be mapped to a range forces a one-off full resync for safety.
+ * Before any feature request, `flush()` sends the latest pending change synchronously so the
+ * server's view matches the cursor.
  *
  * @module languageTools/DocumentSync
  */
@@ -40,6 +43,47 @@ define(function (require, exports, module) {
 
     const CHANGE_DEBOUNCE_MS = 400;
 
+    // LSP TextDocumentSyncKind values we care about.
+    const SYNC_FULL = 1,
+        SYNC_INCREMENTAL = 2;
+
+    // The sync mode the server asked for. `textDocumentSync` is either a number or an object with a
+    // `change` field; anything that isn't explicitly Incremental is treated as full sync (the safe,
+    // always-correct default - e.g. a server that omits the capability).
+    function _syncKind(client) {
+        const tds = client && client.capabilities && client.capabilities.textDocumentSync;
+        if (tds === undefined || tds === null) {
+            return SYNC_FULL;
+        }
+        const kind = (typeof tds === "object") ? tds.change : tds;
+        return (kind === SYNC_INCREMENTAL) ? SYNC_INCREMENTAL : SYNC_FULL;
+    }
+
+    // Map a Phoenix/CodeMirror change list to LSP incremental contentChanges. CodeMirror delivers the
+    // batch in order, each record's {from,to} already relative to the text after the previous records
+    // applied - which is exactly how LSP replays contentChanges - so a straight 1:1 map is correct.
+    // Returns null if any record can't be mapped, signalling the caller to fall back to a full resync.
+    function _toIncrementalChanges(changeList) {
+        if (!changeList || !changeList.length) {
+            return null;
+        }
+        const changes = [];
+        for (let i = 0; i < changeList.length; i++) {
+            const c = changeList[i];
+            if (!c || !c.from || !c.to || !c.text) {
+                return null;
+            }
+            changes.push({
+                range: {
+                    start: { line: c.from.line, character: c.from.ch },
+                    end: { line: c.to.line, character: c.to.ch }
+                },
+                text: c.text.join("\n")
+            });
+        }
+        return changes;
+    }
+
     let initialized = false;
     const registeredClients = [];     // LanguageClient[]
     const tracked = new Map();        // vfsPath -> { client, version, open, pendingTimer }
@@ -72,7 +116,11 @@ define(function (require, exports, module) {
     function _open(client, doc) {
         const vfsPath = doc.file.fullPath;
         const text = doc.getText();
-        const state = { client: client, version: 1, open: true, pendingTimer: null, lastSentText: text };
+        const state = {
+            client: client, version: 1, open: true, pendingTimer: null, lastSentText: text,
+            pendingChanges: [],  // accumulated LSP incremental edits since the last send
+            fullResync: false    // set when an unmappable change forces a full-text send
+        };
         tracked.set(vfsPath, state);
         client.notifyDidOpen(client.uriForPath(vfsPath), _lspLanguageId(client, doc), state.version, text);
     }
@@ -85,9 +133,17 @@ define(function (require, exports, module) {
             return;
         }
         const text = doc.getText();
+        let contentChanges;
+        if (!state.fullResync && _syncKind(client) === SYNC_INCREMENTAL && state.pendingChanges.length) {
+            contentChanges = state.pendingChanges; // tiny per-edit payloads
+        } else {
+            contentChanges = [{ text: text }];     // full-document sync (default, or safety fallback)
+        }
         state.version += 1;
         state.lastSentText = text;
-        client.notifyDidChange(client.uriForPath(vfsPath), state.version, text);
+        state.pendingChanges = [];
+        state.fullResync = false;
+        client.notifyDidChange(client.uriForPath(vfsPath), state.version, contentChanges);
     }
 
     function _close(doc) {
@@ -103,7 +159,7 @@ define(function (require, exports, module) {
         tracked.delete(vfsPath);
     }
 
-    function _onDocumentChange(event, doc) {
+    function _onDocumentChange(event, doc, changeList) {
         const client = _clientForDoc(doc);
         if (!client) {
             return;
@@ -113,6 +169,20 @@ define(function (require, exports, module) {
             _open(client, doc);
             return;
         }
+        // Accumulate the edits so the debounced send (or a flush() before a feature request) can
+        // replay them as incremental ranges. If the server wants full sync, or a record can't be
+        // mapped, fall back to a full-text resync for this cycle.
+        if (!state.fullResync && _syncKind(client) === SYNC_INCREMENTAL) {
+            const mapped = _toIncrementalChanges(changeList);
+            if (mapped) {
+                for (let i = 0; i < mapped.length; i++) {
+                    state.pendingChanges.push(mapped[i]);
+                }
+            } else {
+                state.fullResync = true;
+                state.pendingChanges = [];
+            }
+        }
         if (state.pendingTimer) {
             clearTimeout(state.pendingTimer);
         }
diff --git a/src/languageTools/LSPClient.js b/src/languageTools/LSPClient.js
index 5d814056e4..084bc318bc 100644
--- a/src/languageTools/LSPClient.js
+++ b/src/languageTools/LSPClient.js
@@ -303,10 +303,13 @@ define(function (require, exports, module) {
             textDocument: { uri: uri, languageId: languageId, version: version, text: text }
         });
     };
-    LanguageClient.prototype.notifyDidChange = function (uri, version, text) {
+    // `contentChanges` is the LSP array the caller (DocumentSync) builds: either a single full-text
+    // entry [{ text }] for full sync, or an ordered list of incremental edits [{ range, text }, ...]
+    // when the server advertises incremental sync.
+    LanguageClient.prototype.notifyDidChange = function (uri, version, contentChanges) {
         return this._notify("textDocument/didChange", {
             textDocument: { uri: uri, version: version },
-            contentChanges: [{ text: text }]
+            contentChanges: contentChanges
         });
     };
     LanguageClient.prototype.notifyDidClose = function (uri) {
diff --git a/test/spec/TypeScriptSupport-test-files/ts/incremental.ts b/test/spec/TypeScriptSupport-test-files/ts/incremental.ts
new file mode 100644
index 0000000000..7cc88e58f4
--- /dev/null
+++ b/test/spec/TypeScriptSupport-test-files/ts/incremental.ts
@@ -0,0 +1,3 @@
+let a: number = 0;
+let b: number = 0;
+let c: number = 0;

From a1fd11ff57b6c14c11b20fa04cd12604097f02f4 Mon Sep 17 00:00:00 2001
From: abose <arun@core.ai>
Date: Sat, 27 Jun 2026 18:20:42 +0530
Subject: [PATCH 9/9] fix(lsp): prevent incremental-sync divergence from a
 double-applied edit

A feature-request flush() can race the document-change listener: it ships
a full update that already includes a keystroke which is also still queued
in pendingChanges, so the debounced incremental send replays that edit and
the server applies it twice - leaving a phantom stray token (e.g. a "}"
reported as "Declaration or statement expected") that no restart cleared.

Fix: before trusting the accumulated incremental edits, replay them on the
last-sent text and require they reproduce the current document exactly;
otherwise send a full resync. This makes divergence impossible regardless
of flush/keystroke ordering. The decision and replay are factored into
pure helpers (_contentChangesFor / _applyIncremental) and covered by a new
unit:DocumentSync suite (14 specs), including the double-apply case.
---
 src/languageTools/DocumentSync.js |  60 ++++++++++++--
 test/UnitTestSuite.js             |   1 +
 test/spec/DocumentSync-test.js    | 130 ++++++++++++++++++++++++++++++
 3 files changed, 184 insertions(+), 7 deletions(-)
 create mode 100644 test/spec/DocumentSync-test.js

diff --git a/src/languageTools/DocumentSync.js b/src/languageTools/DocumentSync.js
index 1c56399f8b..ac97172264 100644
--- a/src/languageTools/DocumentSync.js
+++ b/src/languageTools/DocumentSync.js
@@ -29,7 +29,9 @@
  * `didChange` is debounced. When the server advertises incremental sync, the edits made during
  * the debounce window are accumulated and sent as ordered LSP range edits (so a keystroke ships a
  * tiny payload instead of the whole file); otherwise it falls back to sending the full document
- * text. Any change record that can't be mapped to a range forces a one-off full resync for safety.
+ * text. Before sending, the accumulated edits are replayed on the last-sent text and must reproduce
+ * the current document exactly - if they don't (an unmappable record, or a flush/keystroke ordering
+ * race that already shipped an edit), it sends full text instead, so the server can never diverge.
  * Before any feature request, `flush()` sends the latest pending change synchronously so the
  * server's view matches the cursor.
  *
@@ -84,6 +86,48 @@ define(function (require, exports, module) {
         return changes;
     }
 
+    // Offset (UTF-16 code units) of an LSP position within text. Lines split on "\n", matching what
+    // doc.getText() and the change records use.
+    function _offsetAt(text, pos) {
+        let line = 0, i = 0;
+        while (line < pos.line) {
+            const nl = text.indexOf("\n", i);
+            if (nl === -1) {
+                return text.length;
+            }
+            i = nl + 1;
+            line++;
+        }
+        return i + pos.character;
+    }
+
+    // Replay LSP incremental contentChanges onto a string, in order. Used to verify the accumulated
+    // edits reproduce the current document before we trust them (see _contentChangesFor).
+    function _applyIncremental(text, changes) {
+        for (let i = 0; i < changes.length; i++) {
+            const ch = changes[i];
+            const s = _offsetAt(text, ch.range.start);
+            const e = _offsetAt(text, ch.range.end);
+            text = text.slice(0, s) + ch.text + text.slice(e);
+        }
+        return text;
+    }
+
+    // Choose the contentChanges payload for a didChange: the accumulated incremental edits when the
+    // server wants incremental sync AND replaying them on the last-sent text exactly reproduces the
+    // current document; otherwise a full-text resync. The replay check is the safety net: a
+    // feature-request flush() can race the change listener and send a full update that already
+    // includes a keystroke still sitting in pendingChanges, so replaying it would apply that edit to
+    // the server twice (the classic phantom stray "}"). Any such drift falls back to full text, so the
+    // server can never diverge. Exposed for unit tests.
+    function _contentChangesFor(syncKind, lastSentText, pendingChanges, fullResync, text) {
+        if (!fullResync && syncKind === SYNC_INCREMENTAL && pendingChanges.length &&
+                _applyIncremental(lastSentText, pendingChanges) === text) {
+            return pendingChanges;
+        }
+        return [{ text: text }];
+    }
+
     let initialized = false;
     const registeredClients = [];     // LanguageClient[]
     const tracked = new Map();        // vfsPath -> { client, version, open, pendingTimer }
@@ -133,12 +177,8 @@ define(function (require, exports, module) {
             return;
         }
         const text = doc.getText();
-        let contentChanges;
-        if (!state.fullResync && _syncKind(client) === SYNC_INCREMENTAL && state.pendingChanges.length) {
-            contentChanges = state.pendingChanges; // tiny per-edit payloads
-        } else {
-            contentChanges = [{ text: text }];     // full-document sync (default, or safety fallback)
-        }
+        const contentChanges = _contentChangesFor(
+            _syncKind(client), state.lastSentText, state.pendingChanges, state.fullResync, text);
         state.version += 1;
         state.lastSentText = text;
         state.pendingChanges = [];
@@ -339,4 +379,10 @@ define(function (require, exports, module) {
     exports.openSupportedDocuments = openSupportedDocuments;
     exports.flush = flush;
     exports.clearServer = clearServer;
+
+    // Exposed for unit tests only.
+    exports._toIncrementalChanges = _toIncrementalChanges;
+    exports._applyIncremental = _applyIncremental;
+    exports._contentChangesFor = _contentChangesFor;
+    exports._SYNC_INCREMENTAL = SYNC_INCREMENTAL;
 });
diff --git a/test/UnitTestSuite.js b/test/UnitTestSuite.js
index 7a50deccb5..9a1a88b27c 100644
--- a/test/UnitTestSuite.js
+++ b/test/UnitTestSuite.js
@@ -31,6 +31,7 @@ define(function (require, exports, module) {
     require("spec/CSSUtils-integ-test");
     require("spec/Document-test");
     require("spec/Document-integ-test");
+    require("spec/DocumentSync-test");
     require("spec/Editor-test");
     require("spec/EditorRedraw-test");
     require("spec/EditorCommandHandlers-test");
diff --git a/test/spec/DocumentSync-test.js b/test/spec/DocumentSync-test.js
new file mode 100644
index 0000000000..f8cbb18562
--- /dev/null
+++ b/test/spec/DocumentSync-test.js
@@ -0,0 +1,130 @@
+/*
+ * GNU AGPL-3.0 License
+ *
+ * Copyright (c) 2021 - present core.ai . All rights reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
+ *
+ */
+
+/*global describe, it, expect*/
+
+define(function (require, exports, module) {
+    const DocumentSync = require("languageTools/DocumentSync");
+
+    const INCREMENTAL = DocumentSync._SYNC_INCREMENTAL;
+    const FULL = 1;
+
+    // A CodeMirror-style change record (positions use {line, ch}).
+    function cm(fromLine, fromCh, toLine, toCh, textLines, removedLines) {
+        return {
+            from: { line: fromLine, ch: fromCh },
+            to: { line: toLine, ch: toCh },
+            text: textLines,
+            removed: removedLines || [""]
+        };
+    }
+
+    describe("unit:DocumentSync incremental sync", function () {
+
+        describe("_toIncrementalChanges - CodeMirror change list -> LSP range edits", function () {
+            it("maps a single-char insertion", function () {
+                const out = DocumentSync._toIncrementalChanges([cm(2, 0, 2, 0, ["x"])]);
+                expect(out).toEqual([
+                    { range: { start: { line: 2, character: 0 }, end: { line: 2, character: 0 } }, text: "x" }
+                ]);
+            });
+
+            it("joins multi-line inserted text with \\n", function () {
+                const out = DocumentSync._toIncrementalChanges([cm(1, 4, 1, 4, ["a", "b", "c"])]);
+                expect(out[0].text).toBe("a\nb\nc");
+            });
+
+            it("maps a deletion (non-empty range, empty text)", function () {
+                const out = DocumentSync._toIncrementalChanges([cm(3, 0, 5, 0, [""], ["foo", "bar", ""])]);
+                expect(out).toEqual([
+                    { range: { start: { line: 3, character: 0 }, end: { line: 5, character: 0 } }, text: "" }
+                ]);
+            });
+
+            it("maps a multi-record batch in order", function () {
+                const out = DocumentSync._toIncrementalChanges([cm(0, 4, 0, 5, ["abc"]), cm(0, 16, 0, 17, ["\"hi\""])]);
+                expect(out.length).toBe(2);
+                expect(out[0].range.start).toEqual({ line: 0, character: 4 });
+                expect(out[1].range.start).toEqual({ line: 0, character: 16 });
+            });
+
+            it("returns null for an empty or unmappable list (caller then full-resyncs)", function () {
+                expect(DocumentSync._toIncrementalChanges([])).toBe(null);
+                expect(DocumentSync._toIncrementalChanges([{ text: ["x"] }])).toBe(null); // missing from/to
+            });
+        });
+
+        describe("_applyIncremental - replay LSP edits onto a string", function () {
+            const edit = (sl, sc, el, ec, text) => ({
+                range: { start: { line: sl, character: sc }, end: { line: el, character: ec } }, text: text
+            });
+
+            it("applies an insertion", function () {
+                expect(DocumentSync._applyIncremental("ab", [edit(0, 1, 0, 1, "X")])).toBe("aXb");
+            });
+
+            it("applies a deletion", function () {
+                expect(DocumentSync._applyIncremental("abc", [edit(0, 1, 0, 2, "")])).toBe("ac");
+            });
+
+            it("applies a replacement spanning lines", function () {
+                expect(DocumentSync._applyIncremental("a\nb\nc", [edit(0, 1, 2, 0, "X")])).toBe("aXc");
+            });
+
+            it("applies a batch in order (each edit relative to the prior result)", function () {
+                // "let a = 0;" -> replace `a` then `0`. CodeMirror reports same-line edits so that
+                // replaying them in order reproduces the result.
+                const batch = [edit(0, 8, 0, 9, "9"), edit(0, 4, 0, 5, "abc")];
+                expect(DocumentSync._applyIncremental("let a = 0;", batch)).toBe("let abc = 9;");
+            });
+        });
+
+        describe("_contentChangesFor - the divergence safety net", function () {
+            const okEdit = [{ range: { start: { line: 0, character: 1 }, end: { line: 0, character: 1 } }, text: "X" }];
+
+            it("sends the incremental edits when replaying them reproduces the document", function () {
+                const out = DocumentSync._contentChangesFor(INCREMENTAL, "ab", okEdit, false, "aXb");
+                expect(out).toBe(okEdit); // the same accumulated array, trusted as-is
+            });
+
+            it("falls back to full text on drift (a double-applied edit)", function () {
+                // The base text already contains the edit (a flush shipped it), but it is still pending.
+                // Replaying it would duplicate the char -> not equal to the document -> full resync.
+                const out = DocumentSync._contentChangesFor(INCREMENTAL, "aXb", okEdit, false, "aXb");
+                expect(out).toEqual([{ text: "aXb" }]);
+            });
+
+            it("sends full text when the server wants full sync", function () {
+                const out = DocumentSync._contentChangesFor(FULL, "ab", okEdit, false, "aXb");
+                expect(out).toEqual([{ text: "aXb" }]);
+            });
+
+            it("sends full text when a fullResync was flagged", function () {
+                const out = DocumentSync._contentChangesFor(INCREMENTAL, "ab", okEdit, true, "aXb");
+                expect(out).toEqual([{ text: "aXb" }]);
+            });
+
+            it("sends full text when there are no pending edits", function () {
+                const out = DocumentSync._contentChangesFor(INCREMENTAL, "ab", [], false, "abc");
+                expect(out).toEqual([{ text: "abc" }]);
+            });
+        });
+    });
+});