fix(desktop): stabilize packaged webview startup

Author: anthhub

apps/desktop/preload/index.ts

@@ -14,6 +14,7 @@ import {
   updaterEvents,
 } from "../shared/host";
 import { getDesktopRuntimeConfig } from "../shared/runtime-config";
+import { resolveWebviewPreloadUrl } from "./webview-preload-url";
 
 const validChannels = new Set<string>(hostInvokeChannels);
 
@@ -66,10 +67,7 @@ const hostBridge: HostBridge = {
     posthogHost: runtimeConfig.posthogHost,
     isPackaged: !process.defaultApp,
     needsSetupAnimation: process.env.NEXU_NEEDS_SETUP_ANIMATION === "1",
-    webviewPreloadUrl: new URL(
-      "./webview-preload.js",
-      import.meta.url,
-    ).toString(),
+    webviewPreloadUrl: resolveWebviewPreloadUrl(import.meta.dirname),
   },
 
   invoke<TChannel extends HostInvokeChannel>(

apps/desktop/preload/webview-preload-url.ts

@@ -0,0 +1,6 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function resolveWebviewPreloadUrl(preloadDir: string): string {
+  return pathToFileURL(join(preloadDir, "webview-preload.js")).toString();
+}

apps/desktop/preload/webview-preload.ts

@@ -10,6 +10,7 @@ import {
   hostInvokeChannels,
 } from "../shared/host";
 import { getDesktopRuntimeConfig } from "../shared/runtime-config";
+import { resolveWebviewPreloadUrl } from "./webview-preload-url";
 
 const validChannels = new Set<string>(hostInvokeChannels);
 
@@ -34,10 +35,7 @@ const hostBridge: HostBridge = {
     posthogHost: runtimeConfig.posthogHost,
     isPackaged: !process.defaultApp,
     needsSetupAnimation: false,
-    webviewPreloadUrl: new URL(
-      "./webview-preload.js",
-      import.meta.url,
-    ).toString(),
+    webviewPreloadUrl: resolveWebviewPreloadUrl(import.meta.dirname),
   },
 
   invoke<TChannel extends HostInvokeChannel>(

apps/desktop/src/components/desktop-shell.tsx

@@ -16,10 +16,7 @@ import { SurfaceFrame } from "./surface-frame";
 import { UpdateBanner } from "./update-banner";
 
 function getWebviewPreloadUrl(): string {
-  return new URL(
-    "../dist-electron/preload/webview-preload.js",
-    document.location.href,
-  ).href;
+  return window.nexuHost.bootstrap.webviewPreloadUrl;
 }
 
 export function DesktopShell() {

apps/desktop/src/lib/openclaw-surface.ts

@@ -0,0 +1,25 @@
+import type { DesktopRuntimeConfig, RuntimeState } from "../../shared/host";
+
+export function isOpenClawSurfaceReady(
+  runtimeState: RuntimeState | null,
+): boolean {
+  return (
+    runtimeState?.units.some(
+      (unit) => unit.id === "openclaw" && unit.phase === "running",
+    ) ?? false
+  );
+}
+
+export function getDesktopOpenClawUrl(input: {
+  runtimeConfig: Pick<DesktopRuntimeConfig, "urls" | "tokens"> | null;
+  runtimeState: RuntimeState | null;
+}): string | null {
+  if (!input.runtimeConfig || !isOpenClawSurfaceReady(input.runtimeState)) {
+    return null;
+  }
+
+  return new URL(
+    `/#token=${input.runtimeConfig.tokens.gateway}`,
+    input.runtimeConfig.urls.openclawBase,
+  ).toString();
+}

apps/desktop/src/main.tsx

@@ -50,6 +50,7 @@ import {
   triggerMainProcessCrash,
   triggerRendererProcessCrash,
 } from "./lib/host-api";
+import { getDesktopOpenClawUrl } from "./lib/openclaw-surface";
 import { CloudProfilePage } from "./pages/cloud-profile-page";
 import "./runtime-page.css";
 
@@ -1093,6 +1094,7 @@ function DesktopShell() {
   const webSurfaceVersion = 0;
   const [runtimeConfig, setRuntimeConfig] =
     useState<DesktopRuntimeConfig | null>(null);
+  const [runtimeState, setRuntimeState] = useState<RuntimeState | null>(null);
   const update = useAutoUpdate();
 
   // Setup animation phases:
@@ -1124,6 +1126,24 @@ function DesktopShell() {
         setSetupPhase((prev) => (prev === "looping" ? "fading" : prev));
       })
       .catch(() => null);
+
+    void getRuntimeState()
+      .then(setRuntimeState)
+      .catch(() => null);
+  }, []);
+
+  useEffect(() => {
+    const unsubscribe = onRuntimeEvent((event) => {
+      setRuntimeState((current) => {
+        if (!current) {
+          return current;
+        }
+
+        return applyRuntimeEvent(current, event);
+      });
+    });
+
+    return unsubscribe;
   }, []);
 
   useEffect(() => {
@@ -1210,12 +1230,10 @@ function DesktopShell() {
     runtimeConfig && controllerReady
       ? new URL("/workspace", runtimeConfig.urls.web).toString()
       : null;
-  const desktopOpenClawUrl = runtimeConfig
-    ? new URL(
-        `/#token=${runtimeConfig.tokens.gateway}`,
-        runtimeConfig.urls.openclawBase,
-      ).toString()
-    : null;
+  const desktopOpenClawUrl = getDesktopOpenClawUrl({
+    runtimeConfig,
+    runtimeState,
+  });
   return (
     <div
       className={

tests/desktop/openclaw-surface.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import type {
+  RuntimeState,
+  RuntimeUnitState,
+} from "../../apps/desktop/shared/host";
+import {
+  getDesktopOpenClawUrl,
+  isOpenClawSurfaceReady,
+} from "../../apps/desktop/src/lib/openclaw-surface";
+
+function createUnit(overrides: Partial<RuntimeUnitState>): RuntimeUnitState {
+  return {
+    id: "openclaw",
+    label: "OpenClaw",
+    kind: "service",
+    launchStrategy: "launchd",
+    phase: "starting",
+    autoStart: true,
+    pid: null,
+    port: 18789,
+    startedAt: null,
+    exitedAt: null,
+    exitCode: null,
+    lastError: null,
+    lastReasonCode: null,
+    lastProbeAt: null,
+    restartCount: 0,
+    commandSummary: null,
+    binaryPath: null,
+    logFilePath: null,
+    logTail: [],
+    ...overrides,
+  };
+}
+
+function createRuntimeState(units: RuntimeUnitState[]): RuntimeState {
+  return {
+    startedAt: new Date(0).toISOString(),
+    units,
+  };
+}
+
+describe("openclaw surface gating", () => {
+  it("keeps the surface unavailable until the openclaw runtime unit is running", () => {
+    const runtimeState = createRuntimeState([
+      createUnit({ phase: "starting" }),
+    ]);
+
+    expect(isOpenClawSurfaceReady(runtimeState)).toBe(false);
+  });
+
+  it("builds the gateway URL only after the openclaw runtime unit is running", () => {
+    const startingState = createRuntimeState([
+      createUnit({ phase: "starting" }),
+    ]);
+    const runningState = createRuntimeState([createUnit({ phase: "running" })]);
+
+    expect(
+      getDesktopOpenClawUrl({
+        runtimeConfig: {
+          urls: { openclawBase: "http://127.0.0.1:18789" },
+          tokens: { gateway: "gw-secret-token" },
+        },
+        runtimeState: startingState,
+      }),
+    ).toBeNull();
+
+    expect(
+      getDesktopOpenClawUrl({
+        runtimeConfig: {
+          urls: { openclawBase: "http://127.0.0.1:18789" },
+          tokens: { gateway: "gw-secret-token" },
+        },
+        runtimeState: runningState,
+      }),
+    ).toBe("http://127.0.0.1:18789/#token=gw-secret-token");
+  });
+});

tests/desktop/webview-preload-url.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { resolveWebviewPreloadUrl } from "../../apps/desktop/preload/webview-preload-url";
+
+describe("resolveWebviewPreloadUrl", () => {
+  it("returns a file URL for the packaged webview preload script", () => {
+    const url = resolveWebviewPreloadUrl("/tmp/nexu/dist-electron/preload");
+
+    expect(url).toBe(
+      "file:///tmp/nexu/dist-electron/preload/webview-preload.js",
+    );
+  });
+});