Enable running the VS Code extension host on the workspace (Node.js) by default

[joao-boechat]

Summary

This PR makes the Q# VS Code extension run its extension host primarily on the workspace side (Node.js) rather than on the UI side (browser). This is important for remote development scenarios — WSL, SSH, Codespaces, Dev Containers — where keeping the extension host close to the workspace avoids bugs and simplifies the architecture. The extension still supports running on the UI side for VS Code for Web.

To make this work, the Node.js entry point of the qsharp-lang npm package needed to function correctly. Rather than fixing the separate Node.js codepath, we unified both entry points into a single platform-agnostic module, using the web-worker package to abstract away Worker API differences between browsers and Node.js.

Motivation

The Q# extension was originally built as a web-first extension, meaning the extension host always ran on the UI side (browser), even in desktop VS Code. This caused issues in remote development scenarios (WSL, SSH, Codespaces, Dev Containers) where the extension host needs to run close to the workspace for correct behavior. By making the Node.js entry point the default, the extension host runs on the workspace side, avoiding these issues.

Additionally, the npm package previously maintained two parallel codepaths — browser.ts and main.ts — each with its own wasm loading strategy, worker proxy implementation, and per-service worker scripts. The build system also produced two separate wasm-bindgen targets (web and nodejs) and used npm conditional exports to route consumers to the right entry point. The Node.js path was incomplete and buggy, and the duplication made changes error-prone. Unifying these into a single platform-agnostic entry point simplifies the codebase and eliminates this class of bugs.

Architecture (of qsharp-lang)

Before

graph TD
    subgraph "npm package entry points"
        B["browser.ts (browser entry)"]
        M["main.ts (Node.js entry)"]
    end

    B --> WB["workers/browser.ts"]
    M --> WN["workers/node.ts"]

    WB --> CWB["compiler/worker-browser.ts"]
    WB --> LSWB["language-service/worker-browser.ts"]
    WB --> DSWB["debug-service/worker-browser.ts"]

    WN --> CWN["compiler/worker-node.ts"]
    WN --> LSWN["language-service/worker-node.ts"]
    WN --> DSWN["debug-service/worker-node.ts"]

    CWB --> WASMW["lib/web/qsc_wasm.js"]
    CWN --> WASMN["lib/nodejs/qsc_wasm.cjs"]

Loading

After

graph TD
    subgraph "npm package entry point"
        M["main.ts (single entry)"]
    end

    M --> WM["workers/main.ts (proxy, uses web-worker pkg)"]

    WW["workers/worker.ts (runs inside worker)"]

    WW --> CW["compiler/worker.ts"]
    WW --> LSW["language-service/worker.ts"]
    WW --> DSW["debug-service/worker.ts"]

    CW --> WASM["lib/web/qsc_wasm.js"]
    LSW --> WASM
    DSW --> WASM

    WM -.->|spawns| CW
    WM -.->|spawns| LSW
    WM -.->|spawns| DSW

Loading

Changes

qsharp-lang npm package (source/npm/qsharp/)

• Deleted browser.ts and merged all functionality into main.ts — a single platform-agnostic entry point.
• Consolidated per-service worker pairs (worker-browser.ts / worker-node.ts) into a single worker.ts each.
• Replaced workers/browser.ts and workers/node.ts with workers/worker.ts (worker-side) and workers/main.ts (main-thread proxy using the web-worker package).
• Added common-exports.ts for shared re-exports.
• Only the web wasm-bindgen target is used; the nodejs target is no longer needed.
• Simplified package.json exports — removed conditional browser/node/default routing.
• Added web-worker (^1.5.0) as a dependency.
• Some APIs are now async (getCompiler(), getDebugService(), getLanguageService(), getProjectLoader()), and worker factory functions now require an explicit worker path argument.

VS Code extension (source/vscode/)

• Introduced a __PLATFORM__ build-time constant ("browser" or "node") to resolve the correct worker script paths at runtime.
• The extension builds two platform bundles — one for browser and one for Node.js — each covering the extension host entry point (extension.ts) and the worker entry points (compilerWorker.ts, debug-service-worker.ts).
• A single wasm file is now shared across both platforms (copied to wasm/), which is the main reason the overall VSIX size only grew from 3.9 MB to 4.09 MB despite adding a full Node.js bundle.
• The web-worker package must be marked as an external dependency in the Node.js esbuild bundle. This is because web-worker performs an internal runtime check that breaks if its code is inlined into the bundle. As a result, it is copied into the extension's node_modules/ so it can be resolved at runtime (e.g. when installed from a VSIX).
• Desktop entry point changed to ./out/node/extension.js.
• Logs Platform, UI Kind, and Remote name during activation for diagnostics.

Build system (build.py)

• Only the web wasm-bindgen target is built. Removed the nodejs target and its .js → .cjs renaming logic.

Tests (source/npm/qsharp/test/)

• Updated to use the unified API (loadWasmModule, async service getters, explicit worker paths).

Extra

• Fixes issue 2966

[joao-boechat]

now that we're just using the web target, should I simplify the code to account for that, or do I leave the structure as is in case we want to add the nodejs target back?

[minestarks]

I would simplify.

[ScottCarda-MS]

Since web workers was touched, I just wanted to double-check that the worker logic responsible for state-viz calculation on the circuit editor was still functional. I tested it and it seems to be working fine, but is there any reason to be concerned about that?

[joao-boechat]

@ScottCarda-MS I don't see any of the worker code I touched being referenced there. I think that the worker code in state-viz is named that way because it is supposed to be agnostic (browser and worker), so it avoids using API that's only available in browser. But my modifications shouldn't affect that part!