Never paint a browser snapshot at stale geometry (the modal-open flash)

Opening a modal locks scroll, which removes the window scrollbar and reflows
the panel — so a capture taken before the lock describes a rect the panel no
longer occupies. The handshake painted that frame anyway and only then
retried, so the replacement landed visibly offset from the page it stands in
for: the flash. A capture is now checked against the host's live rect before
it is painted; a mismatched frame is skipped and re-captured at the settled
layout instead (modal retries go 2 -> 3 to absorb the extra settle).

Author: Sg312

apps/sim/app/workspace/[workspaceId]/home/components/mothership-view/components/resource-content/components/browser-session/browser-panel-occlusion.test.ts

@@ -30,6 +30,7 @@ import {
   createBrowserPanelGeometryOcclusionLease,
   hasNativeSurfaceOcclusion,
   NATIVE_SURFACE_OCCLUSION_SELECTOR,
+  snapshotMatchesHost,
   useBrowserPanelOcclusion,
 } from '@/app/workspace/[workspaceId]/home/components/mothership-view/components/resource-content/components/browser-session/browser-panel-occlusion'
 
@@ -582,3 +583,44 @@ describe('useBrowserPanelOcclusion modal lifecycle', () => {
     hook.unmount()
   })
 })
+
+describe('snapshotMatchesHost', () => {
+  const rect = (x: number, y: number, width: number, height: number) =>
+    ({ x, y, width, height }) as DOMRect
+
+  it('accepts a capture that still describes the host rect', () => {
+    expect(
+      snapshotMatchesHost(
+        { viewportBounds: { x: 10, y: 20, width: 800, height: 600 } },
+        rect(10, 20, 800, 600)
+      )
+    ).toBe(true)
+  })
+
+  it('tolerates sub-pixel drift from rounding', () => {
+    expect(
+      snapshotMatchesHost(
+        { viewportBounds: { x: 10, y: 20, width: 800, height: 600 } },
+        rect(10.4, 19.6, 800.5, 599.5)
+      )
+    ).toBe(true)
+  })
+
+  it('rejects a capture taken before a scroll lock reflowed the panel', () => {
+    // Modal scroll lock removes the scrollbar: the host widens by 15px, so the
+    // pre-lock capture would paint misaligned — the flash this guards.
+    expect(
+      snapshotMatchesHost(
+        { viewportBounds: { x: 10, y: 20, width: 800, height: 600 } },
+        rect(10, 20, 815, 600)
+      )
+    ).toBe(false)
+  })
+
+  it('accepts captures with no viewport bounds (host-tracking fallback style)', () => {
+    expect(snapshotMatchesHost({ viewportBounds: undefined }, rect(0, 0, 100, 100))).toBe(true)
+    expect(
+      snapshotMatchesHost({ viewportBounds: { x: 0, y: 0, width: 10, height: 10 } }, null)
+    ).toBe(true)
+  })
+})

apps/sim/app/workspace/[workspaceId]/home/components/mothership-view/components/resource-content/components/browser-session/browser-panel-occlusion.ts

@@ -184,10 +184,34 @@ async function decodeSnapshot(dataUrl: string): Promise<boolean> {
  * changing layers never reveals or recaptures the native view, and the view is
  * revealed only after the final reason disappears.
  */
+
+/** Largest tolerated drift, in CSS px, between a capture and the live host rect. */
+const SNAPSHOT_GEOMETRY_TOLERANCE_PX = 1
+
+/**
+ * Whether a captured frame still describes the rectangle the panel occupies.
+ * A capture with no viewport bounds is positioned by the fallback
+ * `absolute inset-0` style, which tracks the host by construction.
+ */
+export function snapshotMatchesHost(
+  frame: Pick<BrowserPanelSnapshot, 'viewportBounds'>,
+  hostRect: DOMRect | null
+): boolean {
+  const bounds = frame.viewportBounds
+  if (!bounds || !hostRect) return true
+  return (
+    Math.abs(bounds.x - hostRect.x) <= SNAPSHOT_GEOMETRY_TOLERANCE_PX &&
+    Math.abs(bounds.y - hostRect.y) <= SNAPSHOT_GEOMETRY_TOLERANCE_PX &&
+    Math.abs(bounds.width - hostRect.width) <= SNAPSHOT_GEOMETRY_TOLERANCE_PX &&
+    Math.abs(bounds.height - hostRect.height) <= SNAPSHOT_GEOMETRY_TOLERANCE_PX
+  )
+}
+
 export function useBrowserPanelOcclusion(
   scopeId: string,
   activeTabId: string | null,
-  panelVisible = true
+  panelVisible = true,
+  getHostRect?: () => DOMRect | null
 ): BrowserPanelOcclusion {
   const [snapshotRender, setSnapshotRender] = useState<SnapshotRender | null>(null)
   const [activeOverlay, setActiveOverlay] = useState<BrowserPanelOverlay | null>(null)
@@ -204,8 +228,10 @@ export function useBrowserPanelOcclusion(
   const paintFramesRef = useRef<number[]>([])
   const reconcileChainRef = useRef<Promise<boolean>>(Promise.resolve(true))
   const mountedRef = useRef(true)
+  const getHostRectRef = useRef(getHostRect)
   activeTabIdRef.current = activeTabId
   panelVisibleRef.current = panelVisible
+  getHostRectRef.current = getHostRect
 
   const updateSnapshotRender = useCallback((render: SnapshotRender | null) => {
     snapshotRenderRef.current = render
@@ -303,7 +329,7 @@ export function useBrowserPanelOcclusion(
 
       // Modal scroll locking can alter panel geometry between capture and the
       // final native hide. One fresh capture retries that now-settled layout.
-      const maxAttempts = desired === 'modal' ? 2 : 1
+      const maxAttempts = desired === 'modal' ? 3 : 1
       for (let attempt = 0; attempt < maxAttempts; attempt++) {
         const frame = await captureBrowserPanelSnapshot(scopeId).catch(() => null)
         if (!mountedRef.current || version !== transitionVersionRef.current) return false
@@ -318,6 +344,13 @@ export function useBrowserPanelOcclusion(
         desired = desiredLayer()
         if (!desired || !decoded) continue
 
+        // Painting a capture whose geometry no longer matches the host is the
+        // flash: a modal's scroll lock changes the window's content width
+        // between capture and paint, so the replacement lands offset from the
+        // page it is standing in for. Skip that frame and re-capture at the
+        // settled layout instead of showing a misaligned one.
+        if (!snapshotMatchesHost(frame, getHostRectRef.current?.() ?? null)) continue
+
         const paintId = ++paintIdRef.current
         const painted = new Promise<boolean>((resolve) => {
           pendingPaintRef.current = { paintId, resolve }

apps/sim/app/workspace/[workspaceId]/home/components/mothership-view/components/resource-content/components/browser-session/browser-session.tsx

@@ -372,6 +372,9 @@ export function BrowserSession({
   const suspended = useBrowserSessionStore((state) => state.sessions[scopeId]?.suspended ?? false)
   const panelRef = useRef<HTMLDivElement>(null)
   const hostRef = useRef<HTMLDivElement>(null)
+  // Lets the occlusion handshake reject a capture taken before a modal's
+  // scroll lock reflowed the panel — painting that stale rect is the flash.
+  const getHostRect = useCallback(() => hostRef.current?.getBoundingClientRect() ?? null, [])
   const urlInputRef = useRef<HTMLInputElement>(null)
   const findInputRef = useRef<HTMLInputElement>(null)
   const fillButtonRef = useRef<HTMLButtonElement>(null)
@@ -450,7 +453,7 @@ export function BrowserSession({
     requestOverlay,
     closeOverlay,
     onSnapshotError,
-  } = useBrowserPanelOcclusion(scopeId, activeTabId, panelVisible)
+  } = useBrowserPanelOcclusion(scopeId, activeTabId, panelVisible, getHostRect)
 
   // The resource picker lives above this component in the panel tab bar. Give
   // that one external browser overlay access to the same capture/hide handshake