fix(desktop): keep browser page visible under floating content (#51240)

2026-10-16 10:30:01 +08:00 · 2026-09-25 10:35:17 +10:00
parent e23d89c9a9
commit b02cc35f13
15 changed files with 182 additions and 18 deletions
@@ -2,7 +2,7 @@ import { DialogProvider } from "@opencode/ui/context/dialog"
 import { Browser } from "@opencode/plugin-browser/rpc"
 import { For, Show } from "solid-js"
 import { createStore } from "solid-js/store"
-import { render } from "solid-js/web"
+import { Portal, render } from "solid-js/web"
 import { LanguageProvider, UiI18nBridge } from "../src/runtime/i18n/language"
 import type { BrowserPaneLayout, BrowserPaneRegistration } from "../src/runtime/platform/browser-pane"
 import type { createSessionBrowser } from "../src/session/browser/model"
@@ -27,7 +27,12 @@ export function mountBrowserPane() {
      loadErrors: {} as Record<string, string | undefined>,
      error: undefined as string | undefined,
      layouts: {} as Record<string, BrowserPaneLayout | undefined>,
+      covered: false,
+      captures: 0,
+      holdCapture: false,
    })
+    // Each capture waits until the fixture releases it, so a spec can observe the pending state.
+    const held: (() => void)[] = []
    const tabs = ["Alpha", "Beta"].map((name) => ({
      id: Browser.TabID.make(`tab_${name === "Alpha" ? "11111111" : "22222222"}-1111-1111-1111-111111111111`),
      title: name,
@@ -44,6 +49,17 @@ export function mountBrowserPane() {
        {
          setLayout: (layout) => setStore("layouts", tab.title, layout),
          command: async () => undefined,
+          capture: async () => {
+            setStore("captures", (count) => count + 1)
+            if (store.holdCapture) await new Promise<void>((resolve) => held.push(resolve))
+            const canvas = new OffscreenCanvas(4, 4)
+            const paint = canvas.getContext("2d")
+            if (paint) {
+              paint.fillStyle = "#3b82f6"
+              paint.fillRect(0, 0, 4, 4)
+            }
+            return canvas.convertToBlob()
+          },
          close: () => undefined,
        },
      ]),
@@ -118,12 +134,34 @@ export function mountBrowserPane() {
            Complete navigation
          </button>
          <button onClick={() => setStore("visible", (visible) => !visible)}>Toggle Review tab</button>
+          <button onClick={() => setStore("holdCapture", true)}>Hold capture</button>
+          <button onClick={() => held.splice(0).forEach((resolve) => resolve())}>Release capture</button>
+          <button onClick={() => setStore("covered", (covered) => !covered)}>Toggle popover</button>
        </nav>
-        <div style={{ width: "640px", height: "360px", border: "1px solid #555" }}>
+        <p>Captures: {store.captures}</p>
+        <div style={{ position: "relative", width: "640px", height: "360px", border: "1px solid #555" }}>
          <Show when={store.mounted}>
            <SessionBrowserPane browser={browser} visible={store.visible} />
          </Show>
        </div>
+        <Show when={store.covered}>
+          {/* Floating content portals into <body> like a menu or hover card over the page. */}
+          <Portal mount={document.body}>
+            <div
+              data-popper-positioner
+              data-testid="fixture-popover"
+              style={{
+                position: "fixed",
+                top: "0",
+                left: "0",
+                width: "320px",
+                height: "480px",
+                "z-index": "1001",
+                "pointer-events": "none",
+              }}
+            />
+          </Portal>
+        </Show>
        <h2 style={{ "font-size": "18px", margin: "20px 0 12px" }}>Native layout recorder</h2>
        <p>The desktop boundary keeps each session's page visible until its registration is hidden.</p>
        <For each={tabs}>
@@ -58,6 +58,27 @@ story("hides the native view immediately while the pane stays mounted", async ({
  await expect(root.getByTestId("native-Alpha")).toHaveAttribute("data-visible", "true")
 })

+story("keeps a still of the page under floating content that covers it", async ({ page }, testInfo) => {
+  const root = page.getByTestId("browser-pane-fixture")
+  const still = root.locator("#browser-panel img")
+  await root.getByRole("button", { name: "Hold capture", exact: true }).click()
+  await root.getByRole("button", { name: "Toggle popover", exact: true }).click()
+  await expect(root.getByText("Captures: 1", { exact: true })).toBeVisible()
+  // The native page stays up until its still is ready, so the pane never shows blank.
+  await expect(root.getByTestId("native-Alpha")).toHaveAttribute("data-visible", "true")
+  await expect(still).toHaveCount(0)
+
+  await root.getByRole("button", { name: "Release capture", exact: true }).click()
+  await expect(root.getByTestId("native-Alpha")).toHaveAttribute("data-visible", "false")
+  await expect(still).toBeVisible()
+  await page.screenshot({ path: testInfo.outputPath("covered.png") })
+
+  await root.getByRole("button", { name: "Toggle popover", exact: true }).click()
+  await expect(root.getByTestId("native-Alpha")).toHaveAttribute("data-visible", "true")
+  await expect(still).toHaveCount(0)
+  await expect(root.getByText("Captures: 1", { exact: true })).toBeVisible()
+})
+
 story("shows the empty state over a blank native page and restores navigation", async ({ page }) => {
  const root = page.getByTestId("browser-pane-fixture")
  await root.getByRole("button", { name: "Blank page", exact: true }).click()
@@ -25,6 +25,8 @@ export type BrowserPaneEvent =
 export type BrowserPaneRegistration = {
  setLayout(layout?: BrowserPaneLayout): void
  command(command: BrowserPaneCommand): Promise<void>
+  /** Captures the shown page, or resolves null when nothing is on screen. */
+  capture(tabID: Browser.TabID): Promise<Blob | null>
  close(): void
 }

@@ -43,6 +43,9 @@ function fixture() {
          async command(command) {
            call.commands.push(command)
          },
+          async capture() {
+            return null
+          },
          close() {
            call.closed = true
          },
@@ -11,6 +11,7 @@ import { createStore } from "solid-js/store"
 import { useLanguage } from "@/runtime/i18n/language"
 import { usePlatform } from "@/runtime/platform/platform"
 import { useCommand } from "@/shell/commands/command"
+import type { Browser } from "@opencode/plugin-browser/rpc"
 import type { createSessionBrowser } from "./model"

 export function SessionBrowserPane(props: { browser: ReturnType<typeof createSessionBrowser>; visible: boolean }) {
@@ -30,6 +31,8 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
    // A submitted navigation the browser has not reported yet; keeps the empty state hidden meanwhile.
    navigating: false,
    visible: typeof document === "undefined" || document.visibilityState === "visible",
+    // A still of the page shown in the DOM while floating content covers the hidden native view.
+    snapshot: undefined as { tabID: Browser.TabID; url: string } | undefined,
  })
  const empty = () => !address() && !state()?.loading && !store.navigating
  let surface: HTMLDivElement | undefined
@@ -37,6 +40,8 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
  let frame: number | undefined
  let layout: string | undefined
  let until = 0
+  let capturing: Browser.TabID | undefined
+  let release: ReturnType<typeof setTimeout> | undefined
  const canvas = document.createElement("canvas")
  canvas.width = canvas.height = 1
  const paint = canvas.getContext("2d", { willReadFrequently: true })
@@ -69,6 +74,45 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
      const r = el.getBoundingClientRect()
      return r.width > 0 && r.left < rect.right && r.right > rect.left && r.top < rect.bottom && r.bottom > rect.top
    })
+  const replaceSnapshot = (next?: { tabID: Browser.TabID; url: string }) => {
+    if (store.snapshot?.url) URL.revokeObjectURL(store.snapshot.url)
+    setStore("snapshot", next)
+  }
+  // Keep the page on screen as a still under the floating content. The native view
+  // stays visible until the still has decoded, so the pane never flashes blank.
+  const freeze = (tabID: Browser.TabID) => {
+    clearTimeout(release)
+    release = undefined
+    if (store.snapshot?.tabID === tabID || capturing === tabID) return
+    capturing = tabID
+    void (registration()?.capture(tabID) ?? Promise.resolve(null))
+      .catch(() => null)
+      .then(async (blob) => {
+        const url = blob ? URL.createObjectURL(blob) : ""
+        if (url) {
+          const image = new Image()
+          image.src = url
+          await image.decode().catch(() => undefined)
+        }
+        if (capturing !== tabID) {
+          if (url) URL.revokeObjectURL(url)
+          return
+        }
+        capturing = undefined
+        // A failed capture still hides the page; the pane shows its background as before.
+        replaceSnapshot({ tabID, url })
+        schedule()
+      })
+  }
+  const thaw = () => {
+    capturing = undefined
+    if (!store.snapshot || release !== undefined) return
+    // Keep the still under the native view until the view has painted again.
+    release = setTimeout(() => {
+      release = undefined
+      replaceSnapshot()
+    }, 150)
+  }
  const measure = () => {
    if (!surface) return
    const tab = state()
@@ -84,7 +128,11 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
    const bottom = Math.round(rect.bottom * zoom)
    // The desktop page hides blank and loading documents itself; only hide here
    // while the pane shows its own empty or failed state over the surface.
-    const visible = props.visible && store.visible && !empty() && !failed() && !dialog.active && !covered(rect)
+    const shown = props.visible && store.visible && !empty() && !failed() && !dialog.active
+    const cover = covered(rect)
+    if (shown && cover) freeze(tab.id)
+    if (!cover) thaw()
+    const visible = shown && !(cover && store.snapshot?.tabID === tab.id)
    // The cutout exposes the app backdrop outside the rounded Review card,
    // not the browser surface inside it.
    const color = getComputedStyle(
@@ -186,6 +234,9 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
  createEventListener(document, "visibilitychange", () => setStore("visible", document.visibilityState === "visible"))
  onCleanup(() => {
    if (frame !== undefined) cancelAnimationFrame(frame)
+    clearTimeout(release)
+    capturing = undefined
+    replaceSnapshot()
  })

  return (
@@ -296,7 +347,17 @@ export function SessionBrowserPane(props: { browser: ReturnType<typeof createSes
          {error()}
        </div>
      </Show>
-      <div ref={surface} class="min-h-0 flex-1 bg-v2-background-bg-base flex items-center justify-center">
+      <div ref={surface} class="relative min-h-0 flex-1 bg-v2-background-bg-base flex items-center justify-center">
+        <Show when={store.snapshot?.tabID === state()?.id && !empty() && !failed() && store.snapshot?.url}>
+          {(url) => (
+            <img
+              src={url()}
+              alt=""
+              draggable={false}
+              class="absolute inset-0 size-full pointer-events-none select-none"
+            />
+          )}
+        </Show>
        <Show when={(empty() || failed()) && !props.browser.suspended()}>
          {/* Add the 40px toolbar to the file empty state's 160px bottom padding to align their centers. */}
          <div
@@ -361,6 +361,12 @@ export function createBrowserPage(
      visible = value
      updateVisibility()
    },
+    // Freezes the shown page so the renderer can paint it under DOM overlays while the view hides.
+    async capture() {
+      if (closed || !visible || !content) return
+      const image = await contents.capturePage()
+      return image.isEmpty() ? undefined : new Uint8Array(image.toJPEG(90))
+    },
    async execute(command: Browser.Command, signal: AbortSignal): Promise<Browser.Result> {
      await ready
      abortError(signal)
@@ -288,6 +288,9 @@ export function createBrowserPane(storage: StateStore) {
      page.layout(bounds, value.background, value.radius)
      page.setVisible(true)
    },
+    async capture(win: BrowserWindow, bindingID: string, tabID: Browser.TabID) {
+      return (await owned(win, bindingID).pages.get(tabID)?.capture()) ?? null
+    },
    async command(win: BrowserWindow, bindingID: string, command: BrowserPaneCommand) {
      const entry = owned(win, bindingID)
      await execute(entry, { action: command, files: [] }, new AbortController().signal)
@@ -6,7 +6,7 @@ import { IpcPortHandoff } from "../ipc-transport"
 import { Shutdown } from "../lifecycle/shutdown"
 import { isRendererUrl } from "../windows/scheme"
 import { DesktopStorage } from "../storage"
-import { sender } from "./context"
+import { sender, type RpcContext } from "./context"

 export const eventHandlers = EventRpcs.toLayer(
  Effect.gen(function* () {
@@ -25,21 +25,29 @@ export const eventHandlers = EventRpcs.toLayer(
    })
    const remove = yield* shutdown.add(stop)
    yield* Effect.addFinalizer(() => Effect.sync(remove).pipe(Effect.andThen(stop)))
+    const owner = async (context: RpcContext) => {
+      const contents = sender(handoff, context)
+      const win = BrowserWindow.fromWebContents(contents)
+      if (!win || win.isDestroyed() || win.webContents !== contents || !isRendererUrl(contents.getURL())) {
+        throw new Error("browser.pane.owner.invalid")
+      }
+      browser ??= load()
+      return { win, pane: await browser }
+    }
    return EventRpcs.of({
      DesktopEvents: (_request, context) => ipcEventStream(sender(handoff, context).id),
      BrowserPane: ({ request }, context) =>
        Effect.tryPromise(async () => {
-          const contents = sender(handoff, context)
-          const win = BrowserWindow.fromWebContents(contents)
-          if (!win || win.isDestroyed() || win.webContents !== contents || !isRendererUrl(contents.getURL())) {
-            throw new Error("browser.pane.owner.invalid")
-          }
-          browser ??= load()
-          const pane = await browser
-          if (request.type === "register") return pane.register(win, request.bindingID, request.target)
-          if (request.type === "layout") return pane.layout(win, request.bindingID, request.layout)
-          if (request.type === "command") return pane.command(win, request.bindingID, request.command)
-          return pane.close(win, request.bindingID)
+          const target = await owner(context)
+          if (request.type === "register") return target.pane.register(target.win, request.bindingID, request.target)
+          if (request.type === "layout") return target.pane.layout(target.win, request.bindingID, request.layout)
+          if (request.type === "command") return target.pane.command(target.win, request.bindingID, request.command)
+          return target.pane.close(target.win, request.bindingID)
+        }).pipe(Effect.orDie),
+      BrowserPaneCapture: (request, context) =>
+        Effect.tryPromise(async () => {
+          const target = await owner(context)
+          return target.pane.capture(target.win, request.bindingID, request.tabID)
        }).pipe(Effect.orDie),
    })
  }),
@@ -4,6 +4,7 @@ import type { DesktopNativeBundle } from "@opencode/app/i18n/desktop-native"
 import type { UpdaterState } from "@opencode/app/updater"
 import type { WslServersPlatform } from "@opencode/app/wsl/types"
 import type { SshPlatform } from "@opencode/app/ssh"
+import type { Browser } from "@opencode/plugin-browser/rpc"
 import type { BrowserPaneRequest } from "../shared/ipc-rpc/browser"
 import type { WindowBootstrap } from "../shared/window-bootstrap"
 import type {
@@ -31,6 +32,7 @@ export type ElectronAPI = {
  browserPane: {
    request(request: BrowserPaneRequest): Promise<void>
    send(request: BrowserPaneRequest): void
+    capture(bindingID: string, tabID: Browser.TabID): Promise<ArrayBuffer | null>
    onEvent(callback: (value: { readonly bindingID: string; readonly event: BrowserPaneEvent }) => void): () => void
  }
  wslServers: WslServersAPI
@@ -50,6 +50,8 @@ export const api: ElectronAPI = {
  browserPane: {
    request: (request) => invoke("BrowserPane", { request }),
    send: (request) => send("BrowserPane", { request }),
+    capture: (bindingID, tabID) =>
+      invoke("BrowserPaneCapture", { bindingID, tabID }).then((data) => (data ? toArrayBuffer(data) : null)),
    onEvent: (callback) => listen("BrowserPaneEvent", (value) => callback(value)),
  },
  wslServers: {
@@ -46,6 +46,10 @@ export function createDesktopPlatform(
                .catch(() => undefined)
          },
          command: (command) => ready.then(() => api.browserPane.request({ type: "command", bindingID, command })),
+          capture: (tabID) =>
+            ready
+              .then(() => api.browserPane.capture(bindingID, tabID))
+              .then((data) => data && new Blob([data], { type: "image/jpeg" })),
          close() {
            if (closed) return
            closed = true
@@ -1,6 +1,7 @@
 import { Browser } from "@opencode/plugin-browser/rpc"
 import { Schema } from "effect"
 import { Rpc } from "effect/unstable/rpc"
+import { Transferable } from "effect/unstable/workers"

 const text = (maximum: number) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maximum))
 const bindingID = text(128)
@@ -42,3 +43,7 @@ export const BrowserPaneEventSchema = Schema.Union([
  }),
 ])
 export const BrowserPaneRpc = Rpc.make("BrowserPane", { payload: { request: BrowserPaneRequestSchema } })
+export const BrowserPaneCaptureRpc = Rpc.make("BrowserPaneCapture", {
+  payload: { bindingID, tabID: Browser.TabID },
+  success: Schema.NullOr(Transferable.Uint8Array),
+})
@@ -1,6 +1,6 @@
 import { Schema } from "effect"
 import { Rpc, RpcGroup } from "effect/unstable/rpc"
-import { BrowserPaneEventSchema, BrowserPaneRpc } from "./browser"
+import { BrowserPaneCaptureRpc, BrowserPaneEventSchema, BrowserPaneRpc } from "./browser"
 import { UpdaterStateSchema } from "./updater"
 import { WslServersEventSchema } from "./wsl"
 import { SshState } from "@opencode/app/ssh"
@@ -63,4 +63,4 @@ export const DesktopEvent = Schema.Union([
 export type DesktopEvent = Schema.Schema.Type<typeof DesktopEvent>

 export const DesktopEvents = Rpc.make("DesktopEvents", { success: DesktopEvent, stream: true })
-export const EventRpcs = RpcGroup.make(DesktopEvents, BrowserPaneRpc)
+export const EventRpcs = RpcGroup.make(DesktopEvents, BrowserPaneRpc, BrowserPaneCaptureRpc)
@@ -71,6 +71,10 @@ async function main() {
            void ready.then(() => pane.layout(win, bindingID, layout))
          },
          command: (command) => ready.then(() => pane.command(win, bindingID, command)),
+          capture: (tabID) =>
+            ready
+              .then(() => pane.capture(win, bindingID, tabID))
+              .then((data) => data && new Blob([data], { type: "image/jpeg" })),
          close: () => {
            listeners.delete(bindingID)
            void ready.then(() => pane.close(win, bindingID)).catch(() => {})
@@ -333,6 +333,11 @@ async function main() {
    await call("tabs.focus", { tabID: second.id })
    pane.layout(win, "suite", { tabID: second.id, visible: true, bounds: { x: 0, y: 0, width: 1000, height: 700 } })
    const snap = await call("snapshot", { tabID, boxes: true })
+    const still = await until(() => pane.capture(win, "suite", second.id))
+    assert(still)
+    assert.deepEqual(Array.from(still.subarray(0, 2)), [0xff, 0xd8], "The shown page captures as a JPEG still")
+    assert.equal(await pane.capture(win, "suite", tabID), null, "A hidden page has no still to show")
+    console.log("PASS browser pane still capture")
    const ref = (text: string) => {
      const match = snap.content
        .split("\n")