fix(Image): close Image.Swap contract gaps from code review

- Broaden ImageSwap's transitionend handler to finalize done() on any
  property, not just opacity. Previously the previous layer leaked
  permanently if a consumer wrote a non-opacity transition on
  previous-class. Docs now call out that previous-class must include
  at least one transition for the exit to resolve.
- Clarify in the docs that data-[has-previous]:opacity-100 on
  current-class is not optional — without it, the crossfade shows a
  background bleed-through during the 0→1 fade-in. Updated the Class
  routing bullet and added a dedicated bullet spelling out the pin
  as required.
- Add a code comment in ImageSwap's currentSrc watcher explaining the
  cleared-then-restored-src edge case so a future reader sees the
  intentional trade-off.
- Rename test describe block 'sSR' → 'SSR' (auto-capitalization tripped
  the Vitest reporter output).

Author: johnleider

apps/docs/src/pages/components/semantic/image.md

@@ -167,8 +167,10 @@ Reach for this pattern whenever the user can navigate between preloaded sources
 A few details worth knowing:
 
 - **Initial mount behaves like `Image.Img`** — there's no previous source on first load, so the component renders a single `<img>` and the placeholder shows while it loads. Only *subsequent* src changes engage the crossfade.
-- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` to fade opacity 1 → 0, and the `transitionend` event triggers `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
+- **Built on the Presence primitive** — the previous layer's mount lifecycle (mounted → leaving → unmounted) is managed by v0's `Presence` composable. CSS targets `data-state='leaving'` on the previous layer during its exit, and `transitionend` on the previous element calls `done()` to finalize the unmount. No `setTimeout`, no manual cleanup.
 - **Class routing** — `class` goes on the wrapper `<div>` (layout, border-radius). `img-class` applies to both inner `<img>` elements (object-fit, sizing). `current-class` and `previous-class` target the individual layers — this is where transition/opacity rules live. The component ships no opinionated styling: you write the fade behavior against `data-state`, `data-has-previous` (on current while a swap is in flight), and Presence's `data-[state=leaving]` (on previous during exit).
+- **`data-has-previous` pin is required** — during the hold window the current layer is still `data-state='loading'`; once the load fires, both layers transition simultaneously (new fades 0→1, previous fades 1→0). Without `data-[has-previous]:opacity-100` on `current-class` to pin the current layer opaque through the swap, the two simultaneous fades show background bleed-through (a dim flash) in the middle of the crossfade. Treat it as a required rule, not informational state.
+- **`previous-class` must include at least one CSS transition** — `done()` is driven by `transitionend` on the previous element. If `previous-class` has no CSS transition at all, the event never fires and the previous layer leaks in the DOM. Opacity is the usual choice; transform, filter, or any other transitioned property works equivalently.
 - **Error state** — if the new image errors, the old one stays visible underneath and `Image.Fallback` overlays as usual. Call `retry()` from the Root slot props or the Fallback slot props to re-attempt the same source.
 
 Not a replacement for `Image.Img` in every case — if you don't need cross-src transitions (single content image, hero banner, avatars), stick with `Image.Img` for the simpler DOM.

packages/0/src/components/Image/ImageSwap.vue

@@ -132,7 +132,10 @@
     // Only capture the previous source when no transition is in flight —
     // navigating through several sources before any have loaded should
     // keep the original previous visible rather than flashing through
-    // each intermediate URL.
+    // each intermediate URL. Also skips when newSrc is falsy: clearing
+    // src to undefined/empty and restoring it degrades to a hard swap,
+    // which is the correct trade-off since a cleared src means the
+    // consumer has intentionally unmounted the logical image.
     if (oldSrc && newSrc && newSrc !== oldSrc && !showPrevious.value) {
       previousSrc.value = oldSrc
       showPrevious.value = true
@@ -169,8 +172,11 @@
     emit('error', e)
   }
 
-  function onPresenceLeave (e: Event, done: () => void) {
-    if ((e as TransitionEvent).propertyName === 'opacity') done()
+  function onPresenceLeave (_e: Event, done: () => void) {
+    // Accept any transitionend, not just opacity — consumers are free to
+    // build exits from transform, filter, etc. Requires that previous-class
+    // include at least one CSS transition so the event fires at all.
+    done()
   }
 
   const slotProps = toRef((): ImageSwapSlotProps => ({