fix(ui): don't strand the viewer under the progress overlay, for images or videos

[lstein]

Summary

During a render, the viewer is effectively locked. The progress-preview overlay is opaque and
sits on top of the selected media; gallery clicks change the selection underneath, but nothing
visibly happens until a tab switch remounts the viewer panel. Found while chaining Wan i2v renders
with a gallery full of videos: every click during a multi-minute render is silently swallowed.

Note

This PR now also contains #9434 (viewer progress-image handoff), which is closed in favour of
this one. The two had converged into a single change maintained in two branches — three commits
existed in both with identical subjects, this branch's auto-switch marker and completion dedupe
were ported byte-identical from #9434, and #9434 had since adopted this branch's extracted reveal
controller. They conflicted in four files in either merge order, so the split was costing a
resolution per review round with a standing risk of the two copies drifting. Sections 5–7 below
are #9434's; its review history is on that PR.

1. Videos never got the temporary reveal

CurrentImagePreview lifts the overlay for 2 s when the user clicks a thumbnail mid-render
(#9217). CurrentVideoPreview showed the overlay unconditionally whenever a progress image
existed. The reveal is now ported: the clicked video appears (first frame + play button) for 2 s,
then the live preview returns. An actively-playing video is never re-covered — an explicit play is
a stronger signal than the click that revealed it, and re-covering would leave audio running under
an opaque overlay with unreachable controls. The overlay returns when the player is closed.

2. Media-type switches reset the reveal's memory

The reveal fires on a change of rendered item. That previous-item tracking was a per-component
ref, but image↔video clicks swap the mounted preview component, so the ref reset and the first
reveal after every type switch was swallowed. The ref now lives in the shared ImageViewerContext.

3. An auto-switch to a finished item read as a user click

The reveal fires on any change of the selected item, so an auto-switch to a just-finished render
hid the next render's live preview for 2 s. The auto-switch selection is dispatched only after
onInvocationComplete's DTO fetch, so a quickly-started next render's first progress event can
land ahead of it and reset $isProgressImageResolving — timing cannot distinguish the handoff from
a click. Fixed by identity: the gallery records the name it is auto-switching to and the reveal
consumes it on that item's first render. The marker is scoped to the selection it was recorded
for, settled by a redux listener matching on state change rather than action type, so an
auto-switch that never renders is dropped the moment the selection moves on and can never swallow
a genuine later click on the same item.

4. Multi-GPU: concurrent sessions overwrote each other's video preview

CurrentImagePreview tiles per-session previews when more than one render runs concurrently; the
video overlay only ever rendered the single shared latest preview, so parallel sessions overwrote
each other's frames in place. The tiles branch is now ported, mirroring the image viewer.

5. The reveal was slow (from #9434)

CurrentImagePreview gated rendering behind an off-DOM preload of the full-resolution PNG (often
several MB), and only that onLoad cleared the overlay — so the stale latent preview stayed on
screen for the entire download. A 256px WEBP thumbnail already exists for every image and is
typically higher resolution than the latent preview it replaces; the reveal is now gated on it,
and DndImage swaps the full image in, in place, once it finishes.

The preload also used the raw imageDTO.image_url while DndImage requests
useMediaUrl(imageDTO.image_url), which appends a media-cookie version — a different key, so the
same bytes were fetched twice (measured: 2 requests when the URLs differ, 1 when they match). The
reuse here is the document's list of available images, keyed by URL and not the HTTP cache, so it
still holds in multiuser mode where images are served Cache-Control: private, no-store.

6. A failed preload wedged the overlay (from #9434)

The preload now settles on success or error and reports through the lifecycle's identity-gated
onLoadImage(sessionId), so a failed load cannot wedge the overlay and a late-settling thumbnail
from an earlier session cannot cut a different session's resolve illusion short.

7. Duplicate invocation_complete deliveries re-ran the gallery work (from #9434)

A duplicate completion double-counted the optimistic board totals and re-dispatched the auto-switch.
The handler now tracks processed invocations itself and returns before any gallery work on a
duplicate, marking the key before the DTO-fetch await so a duplicate landing mid-flight is rejected
too. The shared completedInvocationKeysByItemId map could not be used: the workflow coordinator
pre-marks first-delivery events for non-active workflow items, so keying the early return off it
would have skipped gallery work for legitimate queued workflow completions.

How the merge was resolved

Four files conflicted; all four resolved toward this branch's reveal controller.

#9434 carried a stateless getSelectedItemRevealDecision() whose caller managed the previous-item
ref, the auto-switch marker and the timer by hand. createSelectedItemRevealController owns all of
that and adds sequencing the decision function had no way to express: the resolve-window deferral
(a click landing inside the window keeps its identity until the window ends, so it can still be
revealed), the SELECTION_CLEARED sentinel (re-selecting the item that was just cleared is a
click, and must reveal), and the StrictMode re-arm. Those are the two "inherited holes" an earlier
revision of this PR listed as open — they are fixed here, not deferred.

Everything else #9434 contributed to the conflicted files is kept: the thumbnail-gated preload, the
error-path overlay clear, and its onInvocationComplete coverage. CurrentImagePreview's wiring
test is rewritten against the controller; of its four assertions, one is now covered by a real unit
test on the controller (the marker is consumed on every rendered-item change even with no progress
showing) and one became the routing check CurrentVideoPreview already carries. The only test
dropped without a counterpart asserted that the decision function returned nothing but 'reveal'
or 'hide' — a statement about an API that no longer exists.

Every behavior that had a test on either branch still has one: the merged tree's test inventory is a
superset of both sides apart from those ten titles, nine of which were checked individually against
their counterparts.

One rule did not survive, deliberately. The controller's resolve-window deferral preserves a
single deferred identity, so two changes of the rendered item entirely inside one resolve window
that end back on the item showing when the window opened read as "nothing changed" and do not
reveal; #9434's function would have revealed. Its answer was right for the wrong reason — the ref
had advanced only because that version overwrote it unconditionally, which is the bug that lost the
first click in the far more common single-change case. The window is bounded by
RESOLVE_TIMEOUT_MS (3 s) and the sequence needs an intervening null render, so the controller's
behavior is kept.

One coverage hole the merge opened, now closed. The rewritten wiring test dropped #9434's only
assertion that the component writes $isTemporarilyShowingSelectedImage, and nothing else covers
it: the controller's tests substitute their own setRevealed, CurrentVideoPreview's assertions
are all on the read side, and neither component is ever mounted. Replacing setRevealed with a
no-op in both previews left all 26 wiring assertions — and the full suite — green with the reveal
completely dead. Both wiring tests now fail against that mutation.

Review

Fresh-context adversarial reviews attacked the atom lifecycle (unmount-order interleavings on
preview-component swaps, cross-component stale timers, stuck-ON reveal), the shared ref (preload
lag, rapid A→B→A clicks, deselect paths), the auto-switch registry (unconsumed entries,
wrong-render consumption, TTL/bound edges), the error-handler clear, and — separately — the merge
resolution itself, hunting for a fix that vanished with the side it came from.

Stacked on this

#9520 refactors the reveal into an item-owned state machine on top of this branch. It is
review-ready but should land after this one; its diff is this PR plus ~660 lines of restructuring.

Testing

pnpm lint (tsc, eslint, prettier, dpdm) and the full vitest suite are clean on the merged tree.

[JPPhoto]

A few things to fix:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/CurrentVideoPreview.tsx:115 treats any video-name change as a user reveal. An asynchronously auto-selected completed video can therefore hide a newer render's progress preview for 2 seconds. #9434 fixes this for images with autoSwitchedImages, but PR 9475 defers the video equivalent. Test: enable auto-switch, finish video B, start video C, let C emit progress, then let B's selection arrive; the progress overlay must remain visible.

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/context.tsx:187 and :216 clear global progress state without checking active sessions. If session A finishes while session B remains active, A's preview is removed from $progressData, but the global image/event can be cleared by the failsafe, metadata load, error path, or cancellation. B's tile then disappears until another B progress event. Test: emit progress for A and B, finish A, leave B active without another event, then trigger the 10-second failsafe or A's clear path; B's preview must remain visible.

Some alternative paths worth considering:

• Instead of the current shared lastRenderedItemNameRef, isTemporarilyShowingSelectedImage, and global resolve timer: use an item-owned reducer/state machine. Track each item as running, resolving, canceled, or failed, with item-specific media readiness, reveal source, and timeout.

• Instead of the current implicit combination of progress state, completion handoff, and selection reveal: use three explicit state machines. Keep queue progress, completed-item handoff, and selected-media reveal separate, with events carrying item_id and source.

• Instead of patching only the shared clear path: add progressOwnerItemId and resolveItemId, make onLoadImage item-specific, and derive the displayed fallback from $activeProgressData when the current global owner finishes. Also extend the #9434 auto-switch registry to videos.

[lstein]

Consolidated: this PR now contains #9434, which is closed in favour of it. The description is
rewritten to cover both — sections 5–7 are #9434's fixes, and there is a short account of how the
four conflicting files were resolved.

The short version: the reveal resolves to this branch's controller throughout. #9434 carried a
stateless decision function whose caller managed the previous-item ref, the auto-switch marker and
the timer by hand; the controller owns all of it and adds the resolve-window deferral and the
cleared-selection sentinel — which are the two inherited holes an earlier revision of this PR
listed as open, so they are fixed here rather than deferred. Everything else #9434 contributed
survives: the thumbnail-gated preload, the overlay clear on preload error, the duplicate-completion
dedupe.

An adversarial review of the resolution found one thing, and it was mine: the rewritten wiring test
dropped #9434's only assertion that the component writes $isTemporarilyShowingSelectedImage, and
nothing else covered it — the controller's tests substitute their own setRevealed, the video
tests only assert the read side, and neither component is ever mounted. Replacing that wiring with
a no-op in both previews left all 26 wiring assertions and the full suite green with the reveal
completely dead. Restored in f44c07a, with both tests now failing against that mutation.

One rule from #9434 deliberately did not survive, documented in the description: two changes of the
rendered item inside a single resolve window that end back where they started no longer reveal. Its
answer there was right for the wrong reason — the ref had advanced only because that version
overwrote it unconditionally, which is the bug that lost the first click in the much more common
single-change case.

#9520 is rebased on this and stays stacked; it is ~690 lines of restructuring on top.

[JPPhoto]

Merge blockers:

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:92-94,567-587: retry timers survive socket/auth teardown; setEventListeners.tsx:77-82 and useSocketIO.ts:96-107 provide no disposal. A stale callback can fetch old output through the current store and mutate the new session's gallery/board caches. Effect: cross-session or foreign-content contamination. Likelihood: plausible during logout, account switch, or reconnect within 13 s. Recovery: reload or refetch caches. Test: fail the first DTO lookup, replace auth/socket, advance timers, assert no old fetch or dispatch.

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/selectedItemReveal.ts:151-155: first rendered item is always suppressed when lastRenderedItemNameRef is null. With progress visible, a normal first click selecting a video from an empty viewer therefore leaves the video behind the overlay. Effect: core video reveal path fails on first use. Likelihood: normal when generation is active before any item was rendered. Recovery: select another item or reopen the viewer. Test: mount with null prior render, select a video during progress, assert the temporary overlay is cleared.

Other findings/issues:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/CurrentVideoPreview.tsx:125-150,393-435: reveal timing starts from videoName, before loadeddata or canplay; preload="metadata" and near-zero seeking do not prove a decoded frame exists. Effect: slow videos can reveal as black/blank, then re-cover after the timer. Likelihood: plausible on slow storage/network or large videos. Recovery: wait for load, then reselect. Test: delay media readiness beyond the reveal timeout and assert the overlay remains cleared only after a frame is ready.

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:123-155,180-201: retry success unconditionally increments cached board totals, even if another refresh or delivery already inserted the output during the retry window. Name-list insertion dedupes, but board counts do not. Effect: stale or doubled board image counts until refetch. Likelihood: plausible during the 1-13 s retry window. Recovery: board refetch or reload. Test: prepopulate the output in board caches, run a failed lookup followed by retry success, assert totals remain unchanged.

Corner/impossible cases to note:

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:81-88,567-585: the 1000-entry LRU can evict a retry state before its timer fires; the callback then silently returns. Effect: bounded retry recovery is skipped and output remains absent. Likelihood: rare high-throughput/replay burst. Recovery: manual refetch or duplicate completion. Test: schedule a retry, process over 1000 distinct completions, advance the timer, assert the retry still runs.

Suggestions:

• Instead of shared lastRenderedItemNameRef plus timing guards: use per-session idle, resolving(item_id), and live(item_id) states with an explicit selection-generation token. Add media-readiness state to distinguish initial render, user selection, auto-switch, rapid A/B/A, and decoded-frame availability.

• Instead of leaving retry timers attached to an obsolete socket handler: return a disposer from setEventListeners, cancel timers during socket/auth teardown, and attach retries to an auth/session generation.

• Instead of unconditional retry count updates: make board-total updates idempotent against current cached membership or perform one authoritative invalidation after delivery.

• Instead of starting video reveal from videoName: gate reveal on loadeddata or canplay, with a bounded fallback for media that never becomes ready.

[lstein]

All four addressed at b874b90a4b.

Blocker — retry timers survive socket/auth teardown

Confirmed, and worse than "stale fetch": the timer closes over an event from the session that scheduled it, but dispatch resolves to whatever store is current when it fires. A logout or account switch inside the 13 s window would fetch the old session's output and insert it into the new session's gallery and board caches.

setEventListeners now returns a disposer, and useSocketIO calls it before socket.disconnect() — so the teardown that replaces the socket also drops anything that socket's handler scheduled. There is a behavioral test that a cancelled handler fires nothing afterwards, and a wiring test that the cleanup actually calls the disposer (deleting either fails).

Blocker — the first rendered item is always suppressed

Confirmed. The rule existed for the render that happens when the viewer opens onto an existing selection, which is not a click — but a viewer sitting empty while a generation runs is a state the user has already been shown, so their first click there is a click like any other, and it was landing behind the overlay.

An empty selection now records the cleared-selection sentinel whether or not anything rendered before it. That distinguishes the two: "nothing has ever rendered" still suppresses, "the viewer showed you nothing, and now you picked something" reveals. Both directions are tests.

Video reveal starting before a frame exists

You've raised this three times and I kept pointing at the follow-up branch; that was the wrong call, so it's fixed here. The controller now holds the claim instead of spending the two seconds: a reveal is owed when the selection lands and shown when the item reports a decoded frame (loadeddata), bounded by a 1 s grace so media that never becomes ready still makes the click land rather than swallowing it.

Readiness is reported as which item has painted, not a boolean — a boolean is reset from a different effect than the one that reads it, and a passive effect's setState does not reach the next effect's closure in the same commit, so a video→video click would have read the new name with the previous video's readiness.

Retry success double-counting board totals

Confirmed. Seconds after the fact another refresh or delivery may already have inserted the output; the name-list insert dedupes, the board totals are blind increments and do not. A retry now asks the server for the affected boards instead of bumping the cache — retries are rare enough that one authoritative refresh beats making every optimistic update idempotent.

Corner case: LRU eviction before the timer fires

Fixed too, since it was cheap: the missing names are captured in the timer's closure rather than read back from the LRU, so an eviction can no longer turn the refetch into a silent give-up. If the entry survives and says the work is done, the timer still stands down.

Suite is 1947 tests with tsc, eslint, prettier, knip and dpdm clean; every fix above mutation-checked rather than trusted green. #9434 carries the shared handler and socket-teardown changes as of e407aa6771.

[JPPhoto]

Merge blockers:

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:563-581,660-665: teardown clears queued timers only; pending DTO deliveries continue and can schedule new retries after disposal. setEventListeners.tsx:1049-1051 has no closed/session guard. Effect: old-session DTOs can mutate the new user's gallery and board caches. Likelihood: plausible logout/account switch during a DTO request. Recovery: reload/refetch. Test: hold DTO lookup pending, call disposer, resolve failure, advance timers; current code performs a second lookup.

Other findings/issues:

• invokeai/frontend/web/src/services/events/setEventListeners.test.ts:1-24: replaces the prior 644-line executable socket integration suite with two source-text checks. Workflow invalidation, queue cancellation, own/foreign routing, and node/progress isolation now have no runtime coverage. Effect: listener regressions can pass CI. Likelihood: every future edit to this shared listener, including this PR's lifecycle changes. Recovery: restore behavior-level socket tests. Test: retain a mock socket and trigger representative workflow, queue, foreign-event, and teardown paths.

Another corner/impossible case that can probably be left alone:

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:648-650: every retryable duplicate calls runTrackedDelivery(..., 0), resetting backoff. A persistent duplicate stream during DTO outage can start 1 s retry chains indefinitely. Effect: unbounded request/cache-invalidation load while output remains missing. Likelihood: rare replay/duplicate stream. Recovery: stops only when duplicates stop or page reloads. Test: repeatedly emit the same failed completion before each retry and assert globally bounded attempts.

Suggestions:

• Instead of clearing only timer handles: mark the handler disposed with a session generation, check it before and after every await and before scheduleRetry, and abort in-flight RTKQ requests where possible.

• Instead of source-string teardown checks: restore executable socket fixtures and test pending-lookup disposal, event routing, queue invalidation, and cross-user isolation.

• Instead of resetting retry attempt to zero for every duplicate: preserve per-invocation attempt state while allowing one duplicate to supersede its queued timer.

[lstein]

All three addressed at 042350c334.

The deleted socket suite — my mistake, and thank you for catching it

You're right, and it was worse than a trade-off: I wrote setEventListeners.test.ts with a redirect without checking whether the file existed, and 644 lines of executable socket coverage — workflow invalidation, queue cancellation, own/foreign routing, cross-user isolation — were destroyed by the write. That was careless, and the two source-string checks that replaced them were not an argument for doing it; I did not know I had done it.

The suite is restored intact, and the teardown coverage that motivated the file is now inside it as an executable test rather than a grep: the mocked completion handler carries a dispose(), and the disposer setEventListeners returns is asserted to call it. Deleting the return value fails that test.

Blocker — disposal only stopped queued timers

Confirmed, exactly as you described: the timer handles were cleared, but a DTO request already in flight came back afterwards, dispatched into whatever store had replaced the old one, and scheduled fresh retries against it.

The handler now knows it has been disposed and checks that after every await, not just before starting: an output fetched for the ended session is not dispatched, no retry is scheduled for it, and an event delivered after teardown does nothing at all. Your test recipe is one of the three new cases — hold the lookup pending, dispose, resolve the failure, advance: no second lookup, and nothing left armed. That last assertion is checked before advancing the clock, since a timer armed and then fired reads as "no timer" afterwards.

I did not go as far as aborting in-flight RTKQ requests. The guard makes their results inert, which covers the effect you named; cancelling the requests themselves would be a change to getImageDTOSafe's contract and I would rather do that deliberately than fold it in here.

Backoff reset by duplicates

Fixed rather than left alone — you were right that it makes the bound meaningless, and the fix is small. The attempt count lives on the retry state now, so a duplicate resumes the chain where it had got to instead of starting a fresh one at one second. A stream of duplicates through an outage gets one shared chain of three attempts, not three per duplicate.

Worth noting my first attempt at this did not work: I stored the attempt count from the pass doing the delivering, which for a duplicate is zero, so it overwrote the very thing it was meant to preserve. The mutation check caught it — the test passed against both the fix and its absence until I made the duplicates arrive after each retry fired, which is the shape you described.

Suite is 1972 tests with tsc, eslint, prettier, knip and dpdm clean. #9434 carries the same changes as of c5005b0e52.

[JPPhoto]

To fix:

• invokeai/frontend/web/src/features/gallery/components/ImageViewer/CurrentImagePreview.test.ts:8-10 and invokeai/frontend/web/src/features/gallery/components/ImageViewer/CurrentVideoPreview.test.ts:6-12,15-86: tests inspect source text, not mounted components or real media/effect lifecycles. Effect: wiring/order regressions can leave the overlay or reveal broken while tests pass. Likelihood: normal future refactor. Recovery: manual browser repro. Test: add DOM/browser integration coverage for preload, media events, context swaps, and unmount.

Corner/impossible cases that can likely be ignored:

• invokeai/frontend/web/src/services/events/onInvocationComplete.tsx:103,664-698: after 1000 distinct completion keys, an older dedupe entry can be evicted; a delayed duplicate then repeats gallery work, board-count increments, and auto-switch. Effect: duplicate UI/state. Likelihood: rare long-lived session or replay burst. Recovery: refetch gallery and board data. Test: process 1001 unique completions, replay the first, assert no second delivery.

Suggestions:

• Instead of source-string preview checks, use a mounted DOM/browser harness or a tested component adapter.

• Instead of a fixed 1000-entry LRU as the sole duplicate guard, retain completion identity through the replay window or make gallery and board updates idempotent.

[lstein]

Addressed at f2853a635a (CI green).

Source-text tests → mounted DOM coverage

You're right, and this was the standing debt I'd been flagging each round: the package had no DOM test environment at all, so the component tests could only grep. Fixed via the adapter route you suggested:

• The wiring both preview components share — one controller per mount, run on every input change with a cleanup that cancels only the timer, the flag lowered on unmount — is now useSelectedItemReveal, and the video's painted-name readiness is usePaintedItemName beside it. Each component becomes a hook call.
• The hooks are mounted under happy-dom (new dev dependency) with real effect lifecycles. The suite covers exactly what source text cannot see: the image→video component swap over the shared ref — including the outgoing component's timer being cancelled before it can cut the incoming reveal short; unmount lowering the flag with no timer left to re-raise it; StrictMode's double-invoked effects; and readiness driven by a real <video> element's loadeddata event, reset when the element is swapped for another video.
• Every one of those is mutation-verified: deleting the cleanup, the unmount lower, or the by-name readiness each fails a mounted test.

The remaining source-text assertions shrink to the one thing they're good for — pinning that the components actually call the tested hook, with the right readiness expression per path (preload-settled for images, loadeddata for videos).

What this does not cover, stated plainly: the full components still aren't mounted — their dnd/hotkeys/toast dependencies make that a project-infrastructure decision rather than a PR-sized one. The hook boundary means a component-level regression is now limited to "stopped calling the hook / fed it the wrong expression", which the residual text checks pin.

The LRU eviction corner

Agreed it can wait, and one note for the record: the retry path no longer depends on the entry surviving (the scheduled refetch captures its missing names at schedule time), and retry-path board totals are already server-authoritative rather than incremented. What remains exposed to a post-eviction replay is a first-delivery re-run — your "retain completion identity through the replay window" is the right shape for that, and I'd fold it into the same follow-up as making the optimistic inserts idempotent, rather than grow this PR further.

Suite is 1984 tests with tsc, eslint, prettier, knip and dpdm clean.

[JPPhoto]

There is a very low probability issue of a delayed duplicate completion replaying after its 1000-entry dedupe record is evicted, causing duplicate gallery or board updates, but I'm approving this PR.