[codex] Preview workspace image files

[StiensWout]

Summary

• route workspace image files into the existing integrated preview flow
• expose image preview actions from file links and file surfaces
• keep non-image file opening behavior unchanged

Root cause

The asset server already supports signed workspace image preview URLs, but the web client only treated HTML and PDF paths as previewable entry files.

Impact

Screenshots and other workspace image files can be viewed in-app from file explorer, markdown links, and diff file headers. If preview opening fails, the UI falls back to the existing file surface behavior.

Validation

• vp test packages/shared/src/filePreview.test.ts apps/web/src/diffFileActions.test.ts
• vp check
• vp run typecheck
• python3 /home/t3code/.codex/skills/.system/skill-creator/scripts/quick_validate.py /home/t3code/.codex/skills/t3-contribute

vp check reports the repository's existing unrelated warnings and no errors.

Closes #3140

Note

Add image file preview in the integrated browser panel for workspace files

• Image files clicked in the files panel, diff panel, and chat markdown links now open in the integrated browser preview when runtime support is available, falling back to the file/editor surface with a warning toast on failure or interruption.
• Introduces request scoping via beginPreviewRequest so that newer preview requests supersede older in-flight ones, preventing stale results from being applied.
• Adds typed errors (BrowserPreviewUnavailableError, BrowserPreviewAssetUrlInvalidError, BrowserPreviewEnvironmentDisconnectedError, BrowserPreviewThreadContextUnavailableError) with structured context fields replacing ad-hoc message strings.
• Replaces the local regex file-type check with shared helpers (isWorkspaceImagePreviewPath, isWorkspacePreviewEntryPath) from @t3tools/shared/filePreview.
• Behavioral Change: FilePreviewPanel eligibility and UI labels now use the shared workspace preview rule and say "Open file in preview" instead of "Open file in browser".

^{Macroscope summarized 66c94ff.}

---

Note

Medium Risk
Touches signed asset URL assembly and preview state; changes are bounded to preview UI with fallbacks, but concurrent preview requests and URL error handling warrant careful review.

Overview
Workspace image files (png, jpeg, gif, svg, webp, avif, etc.) now use the same integrated preview flow as HTML/PDF, instead of only opening in the file editor.

Preview pipeline (openFileInPreview) delegates file-type checks to shared @t3tools/shared/filePreview helpers, adds per-thread request coalescing so a newer open wins over an older in-flight preview, and accepts an optional AbortSignal. Preview failures are modeled with Schema.TaggedErrorClass errors (thread/environment context, separate tags for disconnected env, missing thread, invalid asset URL). Invalid asset URLs record lengths and metadata only—not signed paths or base URLs.

UI entry points: ChatView file surfaces and DiffPanel diff file opens try image preview when the runtime supports it, then fall back to the existing file/editor path with a warning toast. Chat markdown file links use the broader preview eligibility, pass abort signals, and on preview failure or interruption open the file surface instead of only showing an error. FilePreviewPanel labels and eligibility align with “preview” wording and shared rules.

New unit tests cover unavailable runtime, safe invalid-URL errors, and stale preview responses.

^{Reviewed by Cursor Bugbot for commit 66c94ff. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7b871c68-1f28-46f4-a05a-84021b3e678b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new image preview feature with new error types, async request tracking, and integration across multiple UI components. The scope of new runtime behavior plus an unresolved bug comment about thread handling warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Preview abort omits thread change

Medium Severity

MarkdownFileLink aborts in-flight integrated preview only on unmount, not when threadRef changes. After switching threads while a plan or message link preview is still pending, completion or the new interrupt fallback can still run with the previous thread’s callbacks and open the browser or file panel on the wrong thread.

 

^{Reviewed by Cursor Bugbot for commit 0078748. Configure here.}