fix(desktop): prevent artifact version flicker

[puemos]

Problem

People switching artifact versions see the preview pane flash to a spinner the first time each version loads.

Changes

• Keep the current preview visible until the selected version is ready.
• Keep comments bound to the displayed version, and disable navigation and editing during the transition.
• Reuse cached data only for versions with the same identity, task, and artifact name.
• No screenshot: this changes a transient loading state. The steady state is unchanged.

How did you test this code?

• Extended ArtifactPreview.test.tsx to cover the loading state, its completion, guarded editing, stable comments, and unrelated artifacts.
• Ran the focused Vitest suite, the @posthog/ui type check, desktop Biome, host boundaries, and ci:preflight.

👉 Stay up-to-date with PostHog coding conventions for a smoother review.

Automatic notifications

• Publish to changelog?

Docs update

None. This change does not affect a documented workflow.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

An OpenAI coding agent worked through pi. It used /writing-tests, /writing-pr-descriptions, /writing-simplified-technical-english, and /working-with-task-comments. The session link is unavailable.

[trunk-io]

😎 Merged directly without going through the merge queue, as the queue was empty and the PR was up to date with the target branch - details.

[github-actions]

React Doctor found no issues in the changed files. 🎉

_{Reviewed by React Doctor for commit 3539c7f.}

[puemos]

Merge Confidence: 4.0/5 - Confident

"Looks good - minor concerns only"

Assessment

• ✓ Well-scoped single-concern change: replace the loading spinner on artifact version navigation with the previously-loaded document, across exactly 2 source files and 1 test
• ✓ The correctness argument is handled — every write/navigate affordance that could act on stale content is gated (canEdit via versionsLoading, both version-nav buttons, commentsEnabled)
• ✓ Additive API change only: useArtifactPreviewData gains isPlaceholderData; repo search confirms ArtifactPreview.tsx is the sole consumer
• ✓ Error path verified safe: TanStack v5 only applies placeholderData while status is pending, so a failed fetch drops the placeholder, releases the guards, and still renders ArtifactPreviewError (ArtifactPreview.tsx:294)
• ⚠ commentsEnabled={commentsEnabled && !isPlaceholderData} feeds document generation, not just UI — AnnotatedArtifactHtml.tsx:75-82 memoises previewDocument on it and artifactHtmlFrame.tsx:33-39 rebuilds the iframe blob URL, so HTML artifacts now take two full iframe reloads per version switch, partly undoing the flicker fix this PR is for
• ⚠ placeholderData: (previousData) => previousData is unscoped: because each version is a distinct artifactId in the query key, selecting an unrelated artifact from the sidebar also renders the prior artifact's body under the new header
• ⚠ The test's useQuery mock keeps artifact-0 in the placeholder state permanently, so it proves the guards engage but never that they release — a stuck-disabled state would pass
• ⚠ commentTarget/commentsQuery (ArtifactPreview.tsx:135-139) and the derived comments/commentLoadError (lines 190-193) still key on the newly-selected version and are gated on the ungated commentsEnabled; worth confirming nothing renders them against the stale body

---

Review: Keep previous artifact content visible during version navigation via React Query placeholderData

This PR replaces the loading spinner shown while navigating between artifact versions with the previously-loaded document, by adding placeholderData: (previousData) => previousData to the artifactPreview query and surfacing isPlaceholderData up into ArtifactPreview. Because the pane now renders content that doesn't match the selected version, the change also gates the affordances that would act on it: editing (versionsLoading: runsLoading || isPlaceholderData), both version-nav buttons, and the comment surface.

The core approach is sound and the guard set covers the write paths. Three things are worth attention before merge.

First, commentsEnabled is load-bearing for document generation, not just presentation — AnnotatedArtifactHtml.tsx:75-82 memoises previewDocument on it and artifactHtmlFrame.tsx:33-39 converts that into the iframe's blob src. Deriving it from isPlaceholderData therefore causes two full iframe reloads per version switch for HTML artifacts, which works against the flicker reduction this PR is chasing.

Second, the placeholder isn't scoped to version steps: each version is its own artifactId in the query key, so selecting an unrelated artifact from the sidebar also renders the prior artifact's body under the new header.

Third, the new test's useQuery mock keeps the fixture in the placeholder state permanently, so it verifies the guards engaging but never releasing — the stuck-disabled failure mode would pass unnoticed.

The error path checks out: TanStack v5 applies placeholderData only while status is pending, so a failed fetch drops the placeholder, re-enables the arrows, and falls through to ArtifactPreviewError. No security, breaking-change, or hooks issues found.

[trunk-io]

   

View Full Report ↗︎ ⋅ Docs

[stamphog]

Contained frontend UX fix to a loading-state flicker in the desktop artifact preview; not risky territory, and all four substantive inline review concerns (stale-placeholder test gap, missing edit/comment guard coverage, extra iframe reloads, cross-artifact cache bleed) were fixed in a follow-up commit and verified present in the diff.

• Author wrote 96% of the modified lines and has 7 merged PRs in these paths (familiarity STRONG).
• 👍 on the PR from hex-security-app[bot].

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	75L, 2F substantive, 169L/3F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (169L, 3F, single-area, fix)
stamphog 2.0.0b4		.stamphog/policy.yml @ e081a98 · reviewed head 3539c7f

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-08-09 15:48 UTC	Run
prod-us	✅ Deployed	2026-08-09 16:02 UTC	Run
prod-eu	✅ Deployed	2026-08-09 16:03 UTC	Run