fix(server): preview click timeouts identify the target#23489

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Preview click timeouts now include the selector and bounded information about whether the target still matches. The broker forwards server-browser timeout reasons, truncated to 500 characters.

Changes: Preview click timeout diagnostics

Layer / File(s)	Summary
Target timeout details packages/contracts/src/previewAutomation.ts, apps/server/src/preview/ServerBrowserPage.ts, apps/server/src/preview/ServerBrowserPage.test.ts	The timeout error supports an optional reason. After a locator click times out, the page checks the target count for up to 250 ms and reports whether the target is absent, still present, or unknown. The error retains the original cause. Tests cover absent and still-matching targets.
Broker timeout reasons apps/server/src/mcp/PreviewAutomationBroker.ts, apps/server/src/mcp/PreviewAutomationBroker.test.ts	The broker reads string reasons from remote error details and includes server-browser reasons, truncated to 500 characters, in timeout errors. A test checks that the broker message includes the selector and timeout.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Low

Possibly related issues

• pingdotgg/t3code#25557: This change forwards bounded server-browser diagnostics but does not add a shared remaining-time budget or preserve Playwright’s actionability reason.
• pingdotgg/t3code#28138: This change adds target details to click timeout errors, but does not establish or resolve the underlying responsiveness problem.
• pingdotgg/t3code#3714: This change adds the failed selector and bounded target-match details to timed-out click errors.

Suggested reviewers: maria-rcks

The diagnostics are mergeable; adding coverage for stalled or failed target counts would improve regression protection.

Check name	Status	Explanation
Title check	Passed	The title is concise, follows the conventional format, and clearly identifies the main change: making preview click timeouts identify their target.
Description check	Passed	The description includes all required sections. It explains the problem, the implementation, scope and approval, focused verification, limitations, and test results.
Linked Issues check	Passed	Issue #3714 requires an actionable preview_click error for a missing target. The error must include the failed selector or locator. The whole-PR summary shows these changes: - `ServerBrowserPage.ts…
Out of Scope Changes check	Passed	Every listed change supports the #3714 objective of an actionable timeout error for a missing target: - ServerBrowserPage.ts: adds the bounded target count and the timeout diagnostic. This is the c…

Full details: Linked Issues check

Explanation

Issue #3714 requires an actionable preview_click error for a missing target. The error must include the failed selector or locator. The whole-PR summary shows these changes:

• ServerBrowserPage.ts: After a click timeout with a locator, a bounded count check runs (at most 250 ms). A zero count yields a reason that names the selector and says no element matches. A one-or-more count yields a reason that says the element still matches. A count of unknown size yields an unknown-match reason. The message warns that the click may already have happened. Selector text is capped at 200 characters.
• ServerBrowserPage.ts: ServerBrowserOperationError accepts ErrorOptions. The original timeout is kept as cause. It is not serialized into the agent-facing message.
• PreviewAutomationBroker.ts: For the server browser client, the broker carries the reason into PreviewAutomationTimeoutError. The reason is truncated to 500 characters. Other clients do not receive it. Timeout clamping is unchanged.
• packages/contracts/src/previewAutomation.ts: PreviewAutomationTimeoutError takes an optional reason. The message is unchanged when no reason exists.
• Tests: ServerBrowserPage.test.ts and PreviewAutomationBroker.test.ts cover a zero-match timeout. They check the selector, the 15,000 ms timeout, the 'may have occurred' warning, and the retained TimeoutError cause. A hidden-target case checks the matching message.

Together these changes meet the issue requirement for the zero-match case. The changed code is in the server and contracts packages. The issue lists apps/desktop as its area. The error path for preview_click runs through these server files, so this area mismatch does not create an unmet coding requirement. Direct Electron attachment was not verified. That check is a runtime check, not a coding requirement. Inspection of the repository was not needed to reach this result. The verdict relies on the supplied whole-PR summary.

Full details: Out of Scope Changes check

Explanation

Every listed change supports the #3714 objective of an actionable timeout error for a missing target:

• ServerBrowserPage.ts: adds the bounded target count and the timeout diagnostic. This is the core fix.
• ServerBrowserPage.ts (ErrorOptions): keeps the original timeout as cause without exposing it to the agent. This supports the error-reporting design.
• PreviewAutomationBroker.ts: passes the bounded reason through the existing timeout error. It does not change other clients.
• packages/contracts/src/previewAutomation.ts: adds an optional reason field. This is the transport for the diagnostic and keeps the message unchanged when no reason exists.
• PreviewAutomationBroker.test.ts and ServerBrowserPage.test.ts: test the new behavior. Tests are expected supporting changes.

No listed change adds unrelated behavior. The summary shows no changes to unrelated features, public APIs beyond the optional field and constructor option, or other packages. The summary is the only evidence used for this check.

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR