feat(desktop): Windows x64 build and runtime support (#273)

.github/workflows/build-desktop.yml

@@ -27,6 +27,39 @@ on:
         required: false
         type: number
         default: 30
+  workflow_dispatch:
+    # Manual build trigger so the fork can produce installers without the
+    # upstream release tooling (the fork uses v*-fork.* tags that
+    # release-desktop.yml does not react to).
+    inputs:
+      channel:
+        description: "Release channel (stable or canary)"
+        required: true
+        type: choice
+        options:
+          - stable
+          - canary
+        default: stable
+      version_suffix:
+        description: "Version suffix to append (e.g., -canary). Empty for stable."
+        required: false
+        type: string
+        default: ""
+      electron_builder_config:
+        description: "Electron builder config file"
+        required: false
+        type: string
+        default: "electron-builder.ts"
+      artifact_prefix:
+        description: "Prefix for artifact names"
+        required: false
+        type: string
+        default: "desktop"
+      artifact_retention_days:
+        description: "Number of days to retain artifacts"
+        required: false
+        type: number
+        default: 14
 
 jobs:
   build-macos:
@@ -263,3 +296,129 @@ jobs:
           path: apps/desktop/release/*-linux.yml
           retention-days: ${{ inputs.artifact_retention_days }}
           if-no-files-found: error
+
+  build-windows:
+    name: Build - Windows (x64)
+    runs-on: windows-latest
+    environment: production
+
+    defaults:
+      run:
+        # bash (Git Bash) is bundled on windows-latest runners and is used so
+        # the cross-platform scripts behave like they do on macOS/Linux.
+        shell: bash
+
+    steps:
+      - name: Enable git long paths
+        shell: pwsh
+        run: git config --global core.longpaths true
+
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - name: Setup Bun
+        id: setup-bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version-file: .bun-version
+
+      - name: Cache dependencies
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ steps.setup-bun.outputs.bun-revision }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-bun-${{ steps.setup-bun.outputs.bun-revision }}-
+
+      - name: Install dependencies
+        run: bun install --frozen --ignore-scripts
+
+      - name: Install desktop native dependencies
+        working-directory: apps/desktop
+        run: bun run install:deps
+
+      - name: Set version suffix
+        if: inputs.version_suffix != ''
+        working-directory: apps/desktop
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          NEW_VERSION="${CURRENT_VERSION}${{ inputs.version_suffix }}"
+          echo "Setting version to: $NEW_VERSION"
+          node -e "
+            const fs = require('fs');
+            const pkg = require('./package.json');
+            pkg.version = '$NEW_VERSION';
+            fs.writeFileSync('./package.json', JSON.stringify(pkg, null, '\t') + '\n');
+          "
+          echo "Updated package.json version to $NEW_VERSION"
+
+      - name: Clean dev folder
+        working-directory: apps/desktop
+        run: bun run clean:dev
+
+      - name: Generate file icons
+        working-directory: apps/desktop
+        run: bun run generate:icons
+
+      - name: Compile app with electron-vite
+        working-directory: apps/desktop
+        env:
+          NEXT_PUBLIC_POSTHOG_KEY: ${{ secrets.NEXT_PUBLIC_POSTHOG_KEY }}
+          NEXT_PUBLIC_POSTHOG_HOST: ${{ secrets.NEXT_PUBLIC_POSTHOG_HOST }}
+          GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
+          GH_CLIENT_ID: ${{ secrets.GH_CLIENT_ID }}
+          NEXT_PUBLIC_WEB_URL: ${{ secrets.NEXT_PUBLIC_WEB_URL }}
+          NEXT_PUBLIC_API_URL: ${{ secrets.NEXT_PUBLIC_API_URL }}
+          NEXT_PUBLIC_DOCS_URL: ${{ secrets.NEXT_PUBLIC_DOCS_URL }}
+          NEXT_PUBLIC_STREAMS_URL: ${{ secrets.NEXT_PUBLIC_STREAMS_URL }}
+          NEXT_PUBLIC_ELECTRIC_URL: ${{ secrets.NEXT_PUBLIC_ELECTRIC_URL }}
+          SENTRY_DSN_DESKTOP: ${{ secrets.SENTRY_DSN_DESKTOP }}
+          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
+          RELAY_URL: ${{ secrets.RELAY_URL }}
+          SUPERSET_WORKSPACE_NAME: superset
+        run: bun run compile:app
+
+      - name: Build superset-browser-mcp binary
+        # Bun doesn't auto-run lifecycle hooks, so the prebuild step that emits
+        # Resources/resources/superset-browser-mcp/superset-browser-mcp.exe
+        # has to be invoked explicitly.
+        working-directory: apps/desktop
+        run: bun run build:browser-mcp
+
+      - name: Build Electron app (NSIS)
+        working-directory: apps/desktop
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+        run: bun run package -- --publish never --config ${{ inputs.electron_builder_config }} --win
+
+      - name: Verify Windows installer + update manifest exist
+        working-directory: apps/desktop
+        run: |
+          ls -la release
+          test -n "$(ls -1 release/*.exe 2>/dev/null)" || {
+            echo "::error::No NSIS .exe generated in apps/desktop/release"
+            exit 1
+          }
+          test -f release/latest.yml || {
+            echo "::error::latest.yml (auto-update manifest) missing"
+            exit 1
+          }
+
+      - name: Upload NSIS installer artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ${{ inputs.artifact_prefix }}-win-x64-nsis
+          path: |
+            apps/desktop/release/*.exe
+            apps/desktop/release/*.exe.blockmap
+          retention-days: ${{ inputs.artifact_retention_days }}
+          if-no-files-found: error
+
+      - name: Upload Windows auto-update manifest
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: ${{ inputs.artifact_prefix }}-win-x64-update-manifest
+          path: apps/desktop/release/latest.yml
+          retention-days: ${{ inputs.artifact_retention_days }}
+          if-no-files-found: error

README.md

@@ -184,7 +184,7 @@ If it runs in a terminal, it runs on Superset
 
 | Requirement | Details |
 |:------------|:--------|
-| **OS** | macOS (Windows/Linux untested) |
+| **OS** | macOS / Windows x64 (preview, this fork) / Linux (untested) |
 | **Runtime** | [Bun](https://bun.sh/) v1.0+ |
 | **Version Control** | Git 2.20+ |
 | **GitHub CLI** | [gh](https://cli.github.com/) |
@@ -194,7 +194,41 @@ If it runs in a terminal, it runs on Superset
 
 ### Quick Start (Pre-built)
 
-**[Download Superset for macOS](https://github.com/superset-sh/superset/releases/latest)**
+- **macOS**: [Download Superset for macOS](https://github.com/superset-sh/superset/releases/latest) (upstream)
+- **Windows x64** *(preview, this fork)*: [Latest MocA-Love/superset release](https://github.com/MocA-Love/superset/releases/latest) — pick the `Superset-*-x64.exe` NSIS installer. Windows support is a rolling preview; see the [Windows known limitations](#windows-preview-known-limitations) below.
+
+### Windows preview: known limitations
+
+Windows builds are a rolling preview tracked in issue [#273](https://github.com/MocA-Love/superset/issues/273). The app launches and the core workspace / terminal / chat flow works, but the following fork features are not yet on par with macOS:
+
+- **Agent wrapper (`~/.superset/bin` PATH injection)** — not yet generated on Windows. Agents (Claude Code / Codex / Gemini / cursor-agent / Copilot) still work via their global hook configs (`~/.claude/settings.json`, `~/.codex/hooks.json`, `~/.gemini/settings.json`, `~/.cursor/hooks.json`) but Superset-side PATH overrides for managed binaries are skipped.
+- **GitHub Copilot CLI project hooks** — `.github/hooks/superset-notify.json` is auto-synced by the bash wrapper on Unix only. On Windows, place the hook file manually until the wrapper is ported to PowerShell.
+- **Mica / Acrylic** — applied via `BrowserWindow.setBackgroundMaterial('mica')`; Windows 10 and pre-22H2 Windows 11 show the opaque fallback.
+- **Auto-install on quit** — the fork checks GitHub API for updates on Windows like on macOS, but there's no NSIS auto-install-on-quit flow yet; clicking "Install" opens the release page for manual download.
+- **Dev-mode deep-link** — `superset://` protocol is registered at install time via NSIS + `app.setAsDefaultProtocolClient`. Dev-mode (running `bun run dev` from source) does not register the protocol on Windows.
+
+### Building Windows locally
+
+```powershell
+# Enable long paths (run once per machine; opens a UAC prompt).
+git config --global core.longpaths true
+
+git clone https://github.com/MocA-Love/superset.git
+cd superset
+
+# Skip lifecycle scripts; native modules are materialized by the postinstall .mjs.
+bun install --frozen --ignore-scripts
+
+cd apps/desktop
+$env:SUPERSET_WORKSPACE_NAME = 'superset'
+bun run install:deps
+bun run compile:app
+bun run build:browser-mcp
+bun run package -- --publish never --win
+# Output: apps/desktop/release/*.exe + *.exe.blockmap + latest.yml
+```
+
+The Windows NSIS build is also available via GitHub Actions → **Build Desktop App** → *Run workflow* on `MocA-Love/superset`, which produces the same artifacts without needing a Windows machine.
 
 ### Build from Source
 

apps/desktop/electron-builder.ts

@@ -96,8 +96,10 @@ const config: Configuration = {
 		"!**/.DS_Store",
 	],
 
-	// Rebuild native modules for Electron's Node.js version
-	npmRebuild: true,
+	// Rebuild native modules for Electron's Node.js version.
+	// Disabled on Windows — native modules are materialized by install:deps +
+	// copy:native-modules, and node-gyp fails without Visual Studio Build Tools.
+	npmRebuild: process.platform !== "win32",
 
 	// macOS DMG
 	// NOTE: dmgbuild 1.2.0 は size = (sum(app files) + 128MB) を割り当てるが、
@@ -212,6 +214,9 @@ const config: Configuration = {
 	nsis: {
 		oneClick: false,
 		allowToChangeInstallationDirectory: true,
+		createDesktopShortcut: true,
+		createStartMenuShortcut: true,
+		shortcutName: productName,
 	},
 };
 

apps/desktop/electron.vite.config.ts

@@ -15,6 +15,7 @@ import {
 	defineEnv,
 	devPath,
 	htmlEnvTransformPlugin,
+	stripCrossOriginPlugin,
 } from "./vite/helpers";
 
 // override: true ensures .env values take precedence over inherited env vars
@@ -124,6 +125,11 @@ export default defineConfig({
 				},
 				output: {
 					dir: resolve(devPath, "main"),
+					// VS Code and other Electron hosts set ELECTRON_RUN_AS_NODE=1 on
+					// their child process env; leaving it set puts Electron into plain
+					// Node mode and the app never opens a window. Clear it before any
+					// require("electron") call — must be the very first statement.
+					banner: "delete process.env.ELECTRON_RUN_AS_NODE;",
 				},
 				external: ["electron", ...mainExternalizedDependencies],
 				plugins: [sentryPlugin].filter(Boolean),
@@ -253,6 +259,7 @@ export default defineConfig({
 			}),
 			reactPlugin(),
 			htmlEnvTransformPlugin(),
+			stripCrossOriginPlugin(),
 		],
 
 		worker: {

apps/desktop/scripts/copy-native-modules.ts

@@ -122,8 +122,13 @@ function copyModuleIfSymlink(
 		console.log(`  ${moduleName}: symlink -> replacing with real files`);
 		console.log(`    Real path: ${realPath}`);
 
-		// Remove the symlink
-		rmSync(modulePath);
+		// Windows: Bun materializes direct deps as directory junctions instead of
+		// file symlinks; rmSync needs { recursive: true } to remove them.
+		if (process.platform === "win32") {
+			rmSync(modulePath, { recursive: true, force: true });
+		} else {
+			rmSync(modulePath);
+		}
 
 		// Copy the actual files
 		cpSync(realPath, modulePath, { recursive: true });
@@ -275,7 +280,13 @@ function copyDependencyForPackage(
 			const nestedStats = lstatSync(nestedDependencyPath);
 			if (nestedStats.isSymbolicLink()) {
 				const realPath = realpathSync(nestedDependencyPath);
-				rmSync(nestedDependencyPath);
+				// Windows: bun materializes these as directory junctions, not
+				// file symlinks; rmSync needs { recursive: true } to remove them.
+				if (process.platform === "win32") {
+					rmSync(nestedDependencyPath, { recursive: true, force: true });
+				} else {
+					rmSync(nestedDependencyPath);
+				}
 				cpSync(realPath, nestedDependencyPath, {
 					recursive: true,
 				});

apps/desktop/src/lib/electron-app/factories/app/setup.ts

@@ -59,7 +59,9 @@ export async function makeAppSetup(
 	return window;
 }
 
-PLATFORM.IS_LINUX && app.disableHardwareAcceleration();
+// Disable GPU hardware acceleration on Linux and Windows to prevent black/blank
+// screens caused by driver incompatibilities with Chromium's compositor.
+(PLATFORM.IS_LINUX || PLATFORM.IS_WINDOWS) && app.disableHardwareAcceleration();
 
 // macOS Sequoia+: occluded window throttling can corrupt GPU compositor layers
 if (PLATFORM.IS_MAC) {

apps/desktop/src/lib/window-loader.ts

@@ -24,9 +24,17 @@ export function registerRoute(props: {
 		const url = `http://localhost:${env.DESKTOP_VITE_PORT}/#/`;
 		console.log("[window-loader] Loading development URL:", url);
 		props.browserWindow.loadURL(url);
+	} else if (process.platform === "win32") {
+		// Production (Windows): file:// breaks ES module dynamic imports
+		// (code-split route chunks) in Electron on Windows. The custom
+		// superset-app:// protocol — registered in main/index.ts — serves the
+		// same renderer files with proper module support so lazy routes load.
+		const url = "superset-app://app/index.html#/";
+		console.log("[window-loader] Loading custom protocol URL:", url);
+		props.browserWindow.loadURL(url);
 	} else {
-		// Production: load from file with hash routing
-		// TanStack Router uses hash-based routing, so we always start at #/
+		// Production (macOS / Linux): load from file with hash routing.
+		// TanStack Router uses hash-based routing, so we always start at #/.
 		console.log("[window-loader] Loading file:", props.htmlFile);
 		props.browserWindow.loadFile(props.htmlFile, { hash: "/" });
 	}