[BUG] preview_screenshot MCP tool always times out — preview pane visibilityState permanently "hidden" when chat pane is focused

[0zlw]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

The preview_screenshot MCP tool reliably times out (30-second timeout) whenever the Claude Code Desktop preview pane is not the foreground window. This makes autonomous visual verification essentially broken — agents call preview_screenshot during their work, at which point the user is reading the chat response and the preview pane is in the background.

This is a Claude Code Desktop issue, not a user app issue. The preview pane BrowserWindow/WebContentsView is created and managed entirely by Claude Code Desktop. Users have no access to how it is instantiated and cannot fix it themselves.

Investigation via preview_eval confirmed the root cause:

• document.visibilityState === "hidden" throughout all testing while chat pane is focused
• performance.getEntriesByType('paint').length === 0 — compositor has never painted
• requestAnimationFrame callbacks never fire while hidden

We exhaustively confirmed that no JavaScript running inside the preview page can work around this — the following were all tried and failed to trigger a compositor paint:

• Object.defineProperty(document, 'visibilityState', { get: () => 'visible' })
• Overriding requestAnimationFrame to use setTimeout
• window.focus(), document.documentElement.focus()
• Element.requestFullscreen()
• Continuous DOM mutations, forced scrolls, injecting large elements

The fix must be made in Claude Code Desktop's Electron layer — specifically in how the preview BrowserWindow/WebContentsView is created. Users cannot work around this.

What Should Happen?

preview_screenshot should capture the current rendered state of the preview pane regardless of which panel is focused in Claude Code Desktop. The pane is visually rendering content on screen — only the MCP screenshot capture fails.

Error Messages/Logs

Steps to Reproduce

1. Start a dev server with preview_start
2. Read Claude's response in the chat pane (preview pane moves to background)
3. Claude calls preview_screenshot autonomously
4. Tool times out after 30 seconds — every time, with no useful error

Alternatively, verify the root cause directly:

1. Start a dev server with preview_start
2. Run preview_eval with expression document.visibilityState while reading chat
3. Returns "hidden" — confirms compositor is not painting the preview pane

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

Claude Code Desktop: Claude/1.4758.0

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Other

Additional Information

Environment:

• Claude Code Desktop: Claude/1.4758.0
• Electron: 41.3.0
• Chromium: 146.0.7680.188
• OS: Windows 11

Why users cannot fix this themselves:
The preview pane is a BrowserWindow or WebContentsView created internally by Claude Code Desktop. Users have no access to the Electron layer, no ability to pass window creation options, and no way to inject Chrome flags into that specific window. Every JS-level workaround was tested and failed — the compositor simply does not paint hidden windows regardless of what the page JavaScript does.

Suggested fix (one of the following, applied in Claude Code Desktop's Electron code):

• Set paintWhenInitiallyHidden: true on the preview BrowserWindow/WebContentsView
• Add --disable-renderer-backgrounding Chrome flag to the preview window
• Add --disable-backgrounding-occluded-windows Chrome flag
• Add --disable-features=CalculateNativeWinOcclusion Chrome flag

Note: When the preview pane IS the foreground window, visibilityState is "visible" and preview_screenshot works correctly. This confirms the pane renders fine — only the backgrounding behaviour needs to be disabled.

Impact:

• Every preview_screenshot call during autonomous agent work times out (30 seconds each)
• Agents typically retry multiple times, wasting minutes per session
• Visual verification of UI changes is effectively unavailable during agentic workflows
• Workaround (Claude in Chrome MCP) requires the user to have Chrome extension installed and adds unnecessary complexity to what should be a simple screenshot

[0xbrainkid]

This is a strong root-cause report because it shows the failure is not “the page is hard to screenshot,” it is that Claude Code Desktop is asking an occluded Electron preview surface to behave like an actively painted one.

The important distinction is that the tool failure is tied to window/background state, not page content:

• when the preview pane is foregrounded, screenshots work
• when chat has focus, visibilityState stays hidden, no paint entries appear, and rAF never fires

That means autonomous screenshotting is structurally broken in the exact workflow where agents need it most: while the user is reading chat and the agent is trying to verify UI changes in the background.

I also think the “users cannot fix this themselves” point matters. Once the issue lives at BrowserWindow/WebContentsView creation time, JS workarounds inside the page are the wrong layer entirely.

So I’d treat this as a Desktop/Electron configuration bug with major workflow impact. A 30-second timeout on every autonomous preview_screenshot attempt effectively turns visual verification into dead time unless the user manually babysits pane focus, which defeats the purpose of the tool.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.