fix(desktop): prevent browser screenshot filename collisions

[saphid]

Problem

If you take two desktop Browser screenshots of the same site in the same millisecond, both get the same filename. The second save silently overwrites the first image.

Why this qualifies

This is a small, obvious data-loss bug fix under CONTRIBUTING: every successful capture should keep its own file. There is no linked issue or prior maintainer discussion. The change is one expression in the desktop screenshot ID, plus one regression test. Capture, save, reveal, copy-path and copy-image behaviour are all unchanged.

Fix

PreviewManager.captureScreenshot now adds an eight-character UUID suffix to the screenshot ID, and so to the filename. Agent MCP screenshots already use exactly this format, in apps/server/src/mcp/McpHttpServer.ts.

Evidence

Environment: macOS 26.5.2 (arm64), a locally built Electron 44.4.2 desktop client and a disposable local page with isolated state. The window is 1280 × 850 CSS px, the Browser page is 539 × 758 CSS px, and DPR is 2.

Versions verified:

• Focused tests and builds were re-run on upstream main f870c419fc.
• The desktop media below was captured on main 43bd667739 and on the previous head of this PR (53488e872b). The images carry those labels.
• The capture is still valid for the rebased head:
  • The production change is byte-identical.
  • Main changed none of the files on the capture path between those commits: preview/Manager.ts, preload.ts, the desktop IPC channel and method, PreviewView.tsx and the contracts IPC type.

Reproduction. Both runs use the same Browser panel, page and viewport, and start with an empty screenshot directory:

1. Capture the page in state A with the Browser panel's Capture screenshot button. This goes through the real desktop:preview-capture-screenshot IPC handler.
2. Change the page to state B and capture again.
3. Compare the returned IDs and paths with the files on disk and their SHA-256 hashes.

How the collision is forced. A hook at the capture boundary pins only the artifact naming timestamp, to 2026-10-03T00:00:00.000Z. Everything else is real: Electron capturePage, PNG conversion, file writes and rendering. The two requests started 62 ms apart on main and 72 ms apart with the fix. This reproduces the equal-timestamp collision deterministically. It does not claim the captures were naturally simultaneous.

Before (main).

• Both requests return browser-screenshot-127-0-0-1-murml1c0 and the same path.
• Only one file is left on disk. Its hash matches capture B, so capture A was overwritten.

browser-screenshot-127-0-0-1-murml1c0.png  77592 bytes
SHA-256 67c367e55d1d592da40fb8b3ea154bf752c2bef8c87ee30b5ff7c7f28111f0d3

After (this PR).

• The timestamps still match.
• The two IDs and paths differ.
• Both files are on disk, and each matches its own captured image.

browser-screenshot-127-0-0-1-murml1c0-9a74238e.png  75187 bytes (A)
SHA-256 49041333cbd4269294c6c75b2fb31b7b99387271231a22014f7273e08fa18d2d
browser-screenshot-127-0-0-1-murml1c0-42b8ba4f.png  77592 bytes (B)
SHA-256 910818ea9939730fd350ce7aaabbec3082dbf9fcc3e6cfa46ecf529256c7d2dc

Recordings: before, after.

• They are timestamped real page screenshots sampled at about 10 fps. The 62–72 ms gap between the two requests is shorter than that sampling interval. So the recordings show the state change and the final result, and the request receipts establish that two requests were made. They say nothing about frame-rate performance.
• The "Harness disk check" text on the page is a test-harness annotation filled in from the actual directory listing. It is not product UI.
• The directory images are labelled transcripts of the actual disk listings, with the full hashes split across lines for readability.

Focused commands run at this head, on main f870c41:

Command	Result
vp test run src/preview/Manager.test.ts (from apps/desktop), with main's Manager.ts	1 failed, 95 passed. The new test fails with expected 'browser-screenshot-example-com-0' not to be 'browser-screenshot-example-com-0'
Same command with this PR	96 passed
vp run --filter @t3tools/desktop typecheck	pass
vp lint --report-unused-disable-directives and vp fmt --check on both changed files	pass
vp run build:desktop	pass
node scripts/release-smoke.ts	pass
node apps/desktop/scripts/verify-preload-bundle.mjs	pass when run with process.platform set to linux, which is how CI's Linux host runs it

On macOS, the preload verifier fails with window is not defined at a darwin-only listener. That failure is not caused by this PR:

• main fails the same way.
• The built preload.cjs has the same SHA-256 on main and on this branch.
• This PR changes no preload source, verifier or bundler config.

Surfaces

• Desktop: fixed. PreviewManager.captureScreenshot is the only place Browser panel screenshots get their name. Its only caller is the Browser panel's Capture screenshot control, through the desktop:preview-capture-screenshot IPC handler.
• Web (app.t3.codes and npx t3): not affected. Only the desktop Browser panel writes these files. The server's MCP screenshot path already uses this suffix.
• Mobile: not affected. Mobile has no desktop Browser panel capture.
• Local / remote-relay / tunnel: not affected. Screenshots are captured and written on the desktop machine, whatever environment it is connected to. The ID format is not part of any wire contract, and the artifact type is unchanged.
• Providers (Codex, Claude, Cursor, Grok, OpenCode, Antigravity): not affected. This is not provider-shaped behaviour.

Not checked

• Naturally occurring same-millisecond collisions. The demo pins the naming timestamp instead.
• Windows and Linux desktop runtimes.
• Remote/relay/tunnel sessions, and multi-environment sessions.
• The desktop media was not recaptured after the rebase. It is reused because the capture path and the production change are byte-identical, as explained above.

GPT-6.1 Sol, GPT-6 Astra and Claude Opus 5.5 via T3 Code
🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at fa56909

Macroscope's review found this PR approvable — This is a small, self-contained desktop bug fix that adds a UUID suffix to screenshot filenames to prevent overwrites. Capture behavior, artifact structure, and the IPC contract remain unchanged, with focused regression coverage added.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate 47a86a7

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 56292b60-f017-4987-ac32-ebf3d9f23e98

📥 Commits

Reviewing files that changed from the base of the PR and between 53488e8 and fa56909.

📒 Files selected for processing (1)

• apps/desktop/src/preview/Manager.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Screenshot artifact IDs now include an eight-character UUID suffix. A regression test checks that same-site captures with the same timestamp receive distinct IDs and paths.

Changes

Screenshot artifact ID uniqueness

Layer / File(s)	Summary
Generate and verify unique screenshot IDs apps/desktop/src/preview/Manager.ts, apps/desktop/src/preview/Manager.test.ts	The ID generator appends an eight-character UUID suffix. The test checks distinct IDs and paths, matching timestamps, and PNG data written to each path.

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Bug fix

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to fa569

The UUID suffix distinguishes same-time screenshot filenames, and inspected desktop consumers do not depend on the old ID format. No known workflow issue remains before merge.

Security Architecture Review

Security architecture risk: ⚪ Minimal · up to fa569

The change reduces accidental screenshot overwrites without expanding access or changing the storage destination. No material security risk was identified in the reviewed change.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The change affects filenames within the existing screenshot directory. The inspected comparison shows no additional caller, storage destination, tenant scope or privilege introduced by the suffix.

Trust Boundaries and Controls

• observed — The URL-derived filename component is restricted to a sanitized hostname slug. The suffix is generated by Node crypto rather than page content. Existing capture retries check that the web contents still belong to the tab before capture and before accepting the image; these checks are unchanged.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the fix for desktop Browser screenshot filename collisions.
Description check	✅ Passed	The description explains the problem, the fix, why the focused change qualifies without prior approval, and the verification performed. It also reports limitations and untested cases.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[saphid]

Rebased onto current main with no production change. On CodeRabbit's note that distinct filenames are probabilistic: a collision now needs the same site, the same millisecond and the same 32-bit UUID prefix, about 1 in 4 billion for each same-millisecond pair. The server's MCP screenshot path already uses this exact format (apps/server/src/mcp/McpHttpServer.ts), so both screenshot writers now behave the same. A counter or exclusive-create write would add more machinery than this flow needs.

Dismissing prior approval to re-evaluate fa56909

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-10-03	Julius	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}