[juliusmarminge]

Problem

An open Word, PowerPoint or other document/binary preview in the Files panel reloads and jumps back to its first page after every agent command and checkpoint, even when that file did not change. The document branch of FilePreviewPanel keyed AttachmentFilePreview on the thread-wide workspaceMutationId, which moves after every completed command, file change and checkpoint.

Reproduced on main @ 25bf84a in the web app (fresh database, synthetic files): a 21-page report.docx scrolled to 2500px was torn down and reloaded at page 1 three times while the agent ran sleep 5; echo one and sleep 5; echo two (two commands plus the checkpoint), with the file untouched. A 400-row data.sqlite preview did the same on a single git status turn (scroll 966 → 0, twice).

Change

The document branch now goes through a small WorkspaceDocumentPreview that reads the server's fileRevision for the media-file asset with useAssetUrlState, the same way the video, audio, PDF and large-text previews already do, and remounts AttachmentFilePreview only when that revision (or the explicit refresh) changes.

• An unchanged file stays mounted, keeping its page and scroll position.
• A real edit gives a new revision, so the new bytes load.
• While the revision is re-checked (including a reconnect, which reports Loading), the last revision is kept; the first open shows the loading state until the revision arrives, so the preview mounts once.
• A failed mint (the file was deleted or moved) remounts so the preview shows its error.
• Servers that report no fileRevision keep following workspaceMutationId as before. In a draft, recognized documents (served as draft-workspace-file) also keep following workspaceMutationId; draft unknown binaries are media-file assets and follow their file revision like any other.

Scope and approval

Fixes #32669

Triaged bug report; one-branch fix in apps/web/src/components/files/FilePreviewPanel.tsx plus its browser test. HTML, image and PDF previews are not touched.

Verification

Focused tests, apps/web/src/components/files/FilePreviewPanel.browser.test.tsx (workspace document previews):

• keeps an unchanged document loaded when another workspace change lands: fails on main (an unchanged document re-minted its URL: expected "vi.fn()" to be called once, but got 2 times), passes here.
• keeps an unchanged document mounted while its revision check reloads: guards the loading path.
• reloads the document when its URL can no longer be minted: guards the deleted-file path.
• loads the new bytes when the document itself changes: guards against never reloading.

At 359bba3 (main merged at d313b2a): vp run check:changed passes format, lint, knip, typecheck, tests and React Compiler. The server-without-fileRevision fallback and the draft transitions are checked by reading the code only; no test or capture drives them.

Evidence

Linux Chromium157; CSS1440×900,DPR2,font16px/100%,dark; Files maximized,explorer256px,preview1184px. R24:CSS900×900,light/dark,preview644px/900px. Synthetic fixtures,local isolated dev servers,free Replay invalidations; T3CODE_DEV_SEED=0. Before d313b2aff3; after 359bba3d25.

25/26 matrix rows have recordings; partial/unverified claims below prevent full-matrix sign-off. Logs sample every250ms. Log-clock times below are seconds after instrumentation; original video clocks differ. DiffT means channel delta>16, without normalization.

Row	Before d313b2aff3	After 359bba3d25	Diff0	DiffT
R02 ·1440×900 dark	R02-before.mp4 R02-before-log.json	R02-after.mp4 R02-after-log.json
Word section20 → two unchanged-byte Replay turns/checkpoints. Video before0s→32.8s resets to section01; after0–36.2s stays20. Log before0.25→22.25s: identity1→6,scrollTop20368→0,checkpoints1→3; after0.26→30.75s: identity1→1,20368→20368,checkpoints1→3 (completions10.59/17.50s).

Row	Before d313b2aff3	After 359bba3d25	Diff0	DiffT
R03 ·1440×900 dark	R03-before.mp4 R03-before-log.json	R03-after.mp4 R03-after-log.json
Slide2 → unchanged-byte Replay/checkpoint. Video before0s→9.1s resets to1; after0–45.8s stays2. Log before0.25→14.25s: identity1→5,scrollTop736→0,checkpoints5→6; after0.25→13.75s: identity1→1,736→736,checkpoints4→5. Supplemental R03-controls-after.mp4 / R03-controls-after-log.json: checkpoint then log47.6s Next3,49.8s Previous2; identity1 retained.

Row	Before d313b2aff3	After 359bba3d25	Diff0	DiffT
R04 ·1440×900 dark	R04-recapture-before.mp4 R04-recapture-before-log.json	R04-recapture-after.mp4 R04-recapture-after-log.json
records400 rows101–150,scroll270/150 → unchanged-byte Replay/checkpoint. Before resets to categories by video~10s (remaining movie is a settled hold); after0–20.6s retains records. Log before0.25→229.25s: identity1→null,scroll270/150→null (one-row table has no sampled scroller),checkpoints6→7; after0.25→20.75s: identity1→1,270/150→270/150,checkpoints9→10. Original R04-before-log.json corroborates identity1→5 and270/150→0/0. Diff0 remains qualified by one unrelated chrome pixel.

Row	What was shown	Recording(s)	Result
R01	Uncached Word opens21pages,0–3.4s	R01-after.mp4	Partial: initial null-mutation boundary absent.
R05	XLSX sheet2,F68,scroll1000/500,checkpoint18→19	R05-readable-after.mp4	Retained; action label O68 is incorrect; visible F68.
R06a	RTF page2,125%,scrolled,checkpoint26→27	R06a-scrolled-after.mp4	Retained visually,iframeid1; numeric frame scroll unmeasured; rushed navigation unverified.
R06b	One-body ODT125%,scrolled,checkpoints11→13	R06b-after.mp4	Retained visually,iframeid1; numeric frame scroll unmeasured.
R07	ODP slide2/focused frame,checkpoint13→14	R07-after.mp4	Retained,iframeid1.
R08	EPUB chapter2/scroll,checkpoint14→15	R08-after.mp4	Retained visually,iframeid1.
R09	ODS sheet2/vertical1000,checkpoint17→18	R09-scrolled-after.mp4	Retained; actual horizontal0 despite action label500.
R10	Notebook25cells,cell24/scroll6310,saved text/image/HTML	R10-expanded-after.mp4	Expanded state retained,checkpoint23→24,id1.
R11	Archive nested text+image; log19–25.4s/26.6–32.7s	R11-after.mp4	Visual retention; Back/Parent usable; identity not sampled for image/root.
R12	Scrolled font specimen,checkpoint22→23	R12-after.mp4	Retained,iframeid1; clipped first line excluded as typography proof.
R13	Unknown binary,no-op then Save at log8.2s	R13-after.mp4	id1 retained; download360bytes matches synthetic SHA256(d7a0f51b…be7a9d).
R14	Word A→B(~5s)→A(~57s); SQLite400→401(~32s)	R14-word-after.mp4 R14-sqlite-after.mp4	New/reverted bytes visible; Wordid1→2→3,SQLite1→3; Word still decoded from video.
R15	Explicit Refresh: Word20→1; SQLite records/page101→categories; binary fallback	R15-word-after.mp4 R15-sqlite-after.mp4 R15-binary-after.mp4	Recaptured with settled holds; Wordid1→2,scroll20368→0; binaryid1→2; original rushed clip rejected.
R16	Local transport outage→reconnect; later editB→A	R16-reconnect-after.mp4 R16-post-reconnect-edit-after.mp4	Partial: starts/ends scroll0,id1→3; no remote/Loading/waiting retention proof.
R17	Move open Word→unavailable error→restore/Try again(log24.6s)	R17-after.mp4	Real failure and recovery shown.
R18a	Cold missing file→mint error→recreate/Try again	R18a-after.mp4	Error/recovery shown; transient bands excluded from settled proof.
R18b	Authorized corrupt Office→renderer error→valid bytes/Refresh	R18b-after.mp4	Distinct error/recovery shown; transient bands excluded.
R19	Legacy missing revision,null→m1→m2	None	Unverified: no compatibility harness/recording.
R20	Real draft Word opens and Refresh resets	R20-real-draft-after.mp4	Partial: same-draft mutations/first submission absent.
R21	Real draft binary opens and Refresh remounts	R21-real-draft-after.mp4	Partial: exact mutations/edit/disposition not instrumented.
R22	Draft same-basename A→B→A in different directories	R22-file-identity-after.mp4	Partial: second environment/thread/workspace/draft↔persisted absent.
R23	NUL bad.txt remains honest text-fetch error through no-op/Refresh	R23-after.mp4	Partial: bad.csv and render/source controls absent.
R24	900×900 light long-path error/ready; explorer toggle; dark→light Word; light font	R24-after.mp4 R24-theme-after.mp4	Partial: theme retains Word20; resize visibly changes20→15; no font theme transition/splitter drag.

What else changed (every visible difference in the paired zero-threshold comparisons):

• R02: section/page numbers01↔20 in heading and paragraphs; vertical content offset and preceding-page white strip. Header/explorer pixels match;165,135 changed pixels.
• R03: counter1↔2,Previous disabled/enabled,title/bullet1↔2,and preceding-slide white strip/content position. Header/explorer match;66,638 changed pixels.
• R04: table selector/categories↔records,page range/navigation state,1row/2columns↔400rows/16columns,headers/widths/cell text/borders/scroll positions/scrollbars,clipped edge cells,and populated↔empty viewport area. Original pair also changes Search caret/focus versus selector outline: not comparable. Recapture removes these rings but has one unrelated chrome pixel(2779,149),RGB31→30; Diff0 is still not a perfectly controlled comparison,2,004,614 changed pixels. Nothing was erased; DiffT suppresses that1-level pixel.

Unverified: R19; exact harness portions of R16/R20/R21; initial null boundaryR01; R06a navigation; remote/waiting/scroll retentionR16; full environment/thread/draft identityR22; CSV/controlsR23; resize reading-position retention and font theme transitionR24. R04 behavior is shown, but its strict zero-threshold comparison remains qualified. Scroll-boundary clipping, ellipsized paths, transient spinner/blank/stale frames and rejected originals are enumerated in capture-review.md.
vp test run apps/web/src/components/files/FilePreviewPanel.browser.test.tsx:6/6 pass. The four revision tests cover unchanged/Loading/Failure/changed bytes; two cover Markdown tasks. These tests do not drive R19 legacy fallback or exact R16 waiting/R20–R21 draft transitions.

Drivers: instrument.js · preview-driver.js · export-log.js · capture-helpers.js · compare.py.
Seeds: seed.py · extra-seed.py · mutate-fixture.py · identity-seed.py · long-odp.py · long-path.py · notebook-html.py · widen-sqlite.py · widen-xlsx.py.
Method/fixtures: capture-protocol.md · catalog.json · synthetic-fixtures.zip. All recording logs/stills and verbatim ghdrop outputs: artifact-index.md.
Both continuation servers stopped,own tab closed,before worktree removed,synthetic SQLite restored; after worktree clean. AI-assisted; verified with the tests and tools listed above.

Verification log

• Review round 1 at 359bba3, two independent reviewers: no code defects found. One verdict MERGE; the other FIX_FIRST only for the then-missing recordings, now attached above.
• Proof audit pass 2: retention, reload-on-edit, Refresh, error/recovery and first-open behaviour confirmed in the recordings, with every diff image recomputed. Open capture-quality notes: one rebuilt R02 frame differs from the delivered one inside the explorer-toggle icon (max 7/255); the R04 Diff0 retains one 1-level chrome pixel; several scrolled document stills clip text at the viewport edges.
• Not checked: desktop (Electron) and mobile clients, a remote reconnect, a server without fileRevision.
• CI green on 359bba3.

AI-assisted; verified with the tests and tools listed above.

🤖 Generated with Claude Code

[macroscopeapp]

Approvability

Verdict: Approved at 4c5427b

Macroscope's review found this PR approvable — Document previews retain their reading position when unrelated agent commands leave the file unchanged, while edits and explicit refresh still reload them. The change is limited to preview lifecycle, with no changes to stored files or access permissions.

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

[coderabbitai]

No actionable comments were generated in the recent review.

Walkthrough

Document and binary-file previews now use asset revisions to determine when the preview remounts. Draft documents continue to use workspace mutation IDs. Browser tests cover preview retention, URL minting failures, and changed revisions.

Changes: Document preview revision handling

Layer / File(s)	Summary
Revision-keyed document previews apps/web/src/components/files/FilePreviewPanel.tsx, apps/web/src/components/files/FilePreviewPanel.browser.test.tsx	WorkspaceDocumentPreview selects an asset resource and keys the attachment preview by revision and refresh counter. It retains the last resolved revision while loading and uses a failure-specific key after URL errors. Tests cover unchanged revisions, failed URL minting, and changed revisions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related issues

• pingdotgg/t3code#25798: HTML previews still use workspace mutation IDs and can remount after unrelated commands.
• pingdotgg/t3code#27681: HTML, PDF, and image previews remain outside the revision-based changes in this PR.

Possibly related PRs

• pingdotgg/t3code#25791: Adds the server-reported file revision contract used by this PR.
• pingdotgg/t3code#31061: Applies revision-based key derivation to image previews.

Suggested reviewers: maria-rcks, only21mil, macroscopeapp

Merge Risk: Minimal · up to c4f34

The document-preview change is ready to merge after normal checks; no unresolved behavior has been established that requires a fix.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title "fix(web): open documents no longer reload after every agent command" follows conventional commit form and names the main change: open document previews stop reloading after unrelated agent …
Linked Issues check		Issue #32669 requires that an open Word or PowerPoint preview keep its position when commands change no file, and that real file changes load. The diff in apps/web/src/components/files/FilePreviewPane…
Out of Scope Changes check		The whole-PR diff against the merge base changes the document branch of FilePreviewPanel.tsx and adds WorkspaceDocumentPreview, plus the browser test file named in the PR. The HTML, image and PDF bran…
Description check		The description covers the problem and reproduction, explains the change and scope, links the triaged issue, and provides focused test results and detailed before/after UI evidence. It also identifies…

Full details: Title check

Explanation

The title "fix(web): open documents no longer reload after every agent command" follows conventional commit form and names the main change: open document previews stop reloading after unrelated agent commands. The diff changes the document branch of FilePreviewPanel to key the preview on the server-reported fileRevision, which matches the title. The title is specific and short (10 words, 67 characters).

Full details: Linked Issues check

Explanation

Issue #32669 requires that an open Word or PowerPoint preview keep its position when commands change no file, and that real file changes load. The diff in apps/web/src/components/files/FilePreviewPanel.tsx replaces the document-branch key, which used workspaceMutationId, with WorkspaceDocumentPreview. For non-draft media-file resources, the new component calls useAssetUrlState and keys AttachmentFilePreview on the returned fileRevision. An unrelated workspace change therefore keeps the same key and the preview stays mounted. A changed fileRevision produces a new key, so new bytes load. The refreshRevision counter still remounts the preview on an explicit refresh. The shown state keeps the last revision during Loading, which covers a reconnect. A Failure produces a failure-specific key, so a deleted file shows its error. A Success without fileRevision falls back to workspaceMutationId, which keeps the previous behavior for servers that do not report a revision. The approach matches the existing WorkspaceVideoPreview pattern that the issue cites. The author reports browser tests for each path, including a test that fails on main and passes at the reviewed head. I did not run those tests. I did not inspect useAssetUrlState internals, so its re-mint behavior rests on the existing video-preview precedent and the reported tests.

Full details: Out of Scope Changes check

Explanation

The whole-PR diff against the merge base changes the document branch of FilePreviewPanel.tsx and adds WorkspaceDocumentPreview, plus the browser test file named in the PR. The HTML, image and PDF branches are not changed in the diff. The change serves the requested behavior in #32669 directly. Office, binary and document files all use the document branch, so their handling is an intended part of the fix and not an unrelated change. One edge case needs a note and is not a scope failure. A draft non-document binary uses a media-file resource with revision-based keying. The PR text says drafts keep following workspaceMutationId. That holds only when the server reports no fileRevision for that draft resource. I did not verify server behavior for drafts.

Full details: Description check

Explanation

The description covers the problem and reproduction, explains the change and scope, links the triaged issue, and provides focused test results and detailed before/after UI evidence. It also identifies unverified cases and limitations.

Finishing Touches

Generate docstrings

• Commit to this branch
• Create a new PR

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

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

Recent review info

Run configuration

• Source mode: Auto
• Repository: pingdotgg/t3code
• Branch: fix/issue-32669
• File: .coderabbit.config.ts
• Commit: c4f3486
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Team
• Run ID: 15fda2a7-ab24-4746-ad7d-599c2ae2327b

Commits

Reviewing files that changed from the base of the PR and between a9e709f and c4f3486.

Files selected for processing: 2

• apps/web/src/components/files/FilePreviewPanel.browser.test.tsx
• apps/web/src/components/files/FilePreviewPanel.tsx

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

Dismissing prior approval to re-evaluate 4c5427b