Repository Turn Document

Fix Electron Codex Bridge Regression

Repaired the Electron desktop ChatGPT/Codex bridge after the Settings screen fell back to the browser-only “Desktop Required” state. The desktop shell now loads its preload bridge from a CommonJS file, exposes an explicit desktop runtime marker, and stamps the renderer with an Islandflow desktop user-agent marker.

Issueislandflow-sc6

ScopeElectron desktop bridge loading

ValidationDesktop build and focused tests passed; web build hit tracked shared-types blocker

Summary

The Electron app was presenting the same fallback shown in a regular browser, which blocked managed ChatGPT login, Codex model loading, and native Copilot controls. The fix makes the preload file unambiguously runnable by Electron and gives the web runtime reliable desktop shell signals while the bridge is coming online.

Changes Made

Added apps/desktop/src/preload.cjs, a CommonJS preload that exposes window.islandflowDesktop.ai.
Exposed window.islandflowDesktopRuntime from preload as a minimal Electron shell marker.
Updated the desktop build script to copy src/preload.cjs into dist/preload.cjs.
Pointed the Electron BrowserWindow preload path at preload.cjs instead of preload.js.
Added an explicit IslandflowDesktop/<version> Electron/<version> user-agent token before loading the app URL.
Updated the web runtime detector to accept the preload runtime marker and the Islandflow desktop user-agent token.

Context

The visible failure mode was the Settings page labeling the session as browser-only even though it was running inside Islandflow Desktop. That meant the renderer saw neither the native preload bridge nor a desktop-shell signal it trusted. The previous bridge code was emitted as preload.js inside an ESM package, which is fragile for Electron preload loading because the script is intended to run as classic CommonJS. The follow-up patch also protects against Electron user-agent stripping by using a dedicated preload marker.

Important Implementation Details

The preload bridge still exposes the same IPC methods, so the native AI control contract did not change.
The runtime marker is intentionally tiny: it says only that this renderer is Islandflow running in Electron.
The user-agent marker is a secondary fallback signal. When the preload bridge is healthy, window.islandflowDesktop remains the source of truth for native controls.
The app and Electron versions are read at runtime with app.getVersion() and process.versions.electron.
The older TypeScript preload source remains in place for now, but Electron no longer depends on its emitted .js file.

Relevant Diff Snippets

Snippets are formatted as unified patch text for Diffs-style review. Reference: https://diffs.com/docs.

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
@@
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && cp src/preload.cjs dist/preload.cjs",

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
@@
-const PRELOAD_PATH = fileURLToPath(new URL("./preload.js", import.meta.url));
+const PRELOAD_PATH = fileURLToPath(new URL("./preload.cjs", import.meta.url));
@@
   installNavigationGuards(window);
+  window.webContents.setUserAgent(
+    `${window.webContents.getUserAgent()} IslandflowDesktop/${app.getVersion()} Electron/${process.versions.electron}`
+  );

diff --git a/apps/desktop/src/preload.cjs b/apps/desktop/src/preload.cjs
+const { contextBridge, ipcRenderer } = require("electron");
+...
+contextBridge.exposeInMainWorld("islandflowDesktopRuntime", {
+  shell: "electron",
+  app: "islandflow"
+});
+contextBridge.exposeInMainWorld("islandflowDesktop", bridge);

Expected Impact for End-Users

Opening Settings inside Islandflow Desktop should no longer show the browser-only fallback. If the native bridge itself is unavailable, users should see bridge recovery guidance instead of being told they are not in the desktop app. When the bridge is available, users should be able to connect ChatGPT or Codex, load managed models, and use native Copilot controls from the desktop app again.

Validation

Buildbun --cwd=apps/desktop run build passed.

Desktop Testsbun --cwd=apps/desktop run test passed, 12 tests.

Web Bridge Testsbun test apps/web/app/desktop-ai.test.ts passed, 19 tests.

Web Buildbun --cwd=apps/web run build compiled, then failed on tracked issue islandflow-c8f: shared packages/types imports still use explicit .ts extensions.

Issues, Limitations, and Mitigations

The live GUI screenshot after the first patch still showed the browser-only fallback, which prompted the explicit preload runtime marker added here.
The old src/preload.ts still exists. A later cleanup can remove or consolidate it after confirming no packaging path still references it.
The web production build remains blocked by islandflow-c8f, unrelated to the desktop runtime marker change.

Follow-up Work

Close islandflow-sc6 after the follow-up commit lands.
Consider adding a lightweight Electron smoke test that asserts window.islandflowDesktop exists after launch.
Remove the unused TypeScript preload path once the CommonJS preload has been verified in packaged and dev runs.