fix(01-15): hand the video off to a custodial PiP session (UIFIX-05)

Entering picture-in-picture read as the lightbox being dismissed, and the
session died with it: both Teleport and KeepAlive move their subtree on
deactivation, which the PiP spec treats as removal.

MediaLightbox now listens for the video's own enterpictureinpicture event —
so PiP entered by the browser's native control behaves identically to the
toolbar button — and follows a fixed order: adopt, animate, then emit close.
Adopting first is what makes the element survive the unmount the emit
triggers; the invariant is documented in place so a refactor cannot reorder
it innocently.

The backdrop animates a handoff on the PiP path only, closing on transitionend
with a bounded 350ms fallback for browsers that skip the transition and for
the reduced-motion path where the duration is zero and the event never fires.

Verified: 5 new tests plus the full frontend suite green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

neode-ui/src/components/cloud/MediaLightbox.vue

@@ -4,6 +4,7 @@
       <div
         v-if="show"
         class="lightbox-backdrop"
+        :class="{ 'lightbox-pip-handoff': pipHandoff }"
         @click.self="close"
         @keydown="onKeydown"
         tabindex="0"
@@ -19,7 +20,7 @@
           </div>
           <div class="flex items-center gap-1">
             <button
-              v-if="pipSupported && currentItem && isVideoFile(currentItem)"
+              v-if="pipAvailable && currentItem && isVideoFile(currentItem)"
               class="lightbox-btn"
               title="Picture-in-picture"
               @click.stop="togglePip(videoEl)"
@@ -84,6 +85,8 @@
             autoplay
             @dblclick="toggleFullscreen"
             @error="onMediaError"
+            @enterpictureinpicture="onEnterPip"
+            @leavepictureinpicture="onLeavePip"
           />
 
           <!-- Audio -->
@@ -124,7 +127,8 @@
 import { ref, computed, watch, onUnmounted, nextTick } from 'vue'
 import type { FileBrowserItem } from '@/api/filebrowser-client'
 import { getFileCategory } from '@/composables/useFileType'
-import { pipSupported, togglePip } from '@/utils/pip'
+import { isPipSupported, togglePip } from '@/utils/pip'
+import { usePipSession } from '@/composables/usePipSession'
 
 const props = defineProps<{
   items: FileBrowserItem[]
@@ -145,6 +149,16 @@ const currentUrl = ref<string | null>(null)
 const backdropEl = ref<HTMLElement | null>(null)
 const videoEl = ref<HTMLVideoElement | null>(null)
 
+const pipAvailable = isPipSupported()
+const pipSession = usePipSession()
+const pipHandoff = ref(false)
+// Bounded fallback for the transitionend-driven close below — covers a
+// browser that skips the transition entirely (including the reduced-motion
+// path, where the CSS transition duration is zero and transitionend never
+// fires).
+const PIP_HANDOFF_FALLBACK_MS = 350
+let handoffTimer: ReturnType<typeof setTimeout> | null = null
+
 const urlCache = new Map<string, string>()
 
 const mediaItems = computed(() =>
@@ -234,6 +248,38 @@ function close() {
   emit('close')
 }
 
+function finishPipHandoff() {
+  backdropEl.value?.removeEventListener('transitionend', finishPipHandoff)
+  if (handoffTimer) {
+    clearTimeout(handoffTimer)
+    handoffTimer = null
+  }
+  emit('close')
+}
+
+// Listens for the enterpictureinpicture event itself, rather than inferring
+// from the button click, so PiP entered by any route (the browser's own
+// control, a keyboard shortcut) behaves the same. Order matters here and
+// must stay exactly this: adopt first, animate second, emit last — adopting
+// first is what makes the element survive the unmount the emit triggers.
+function onEnterPip() {
+  const video = videoEl.value
+  if (!video) return
+  pipSession.adopt(video)
+  pipHandoff.value = true
+  backdropEl.value?.addEventListener('transitionend', finishPipHandoff, { once: true })
+  handoffTimer = setTimeout(finishPipHandoff, PIP_HANDOFF_FALLBACK_MS)
+}
+
+// The session's own leavepictureinpicture listener (attached in
+// usePipSession at adopt time) is the primary release path, since the
+// lightbox has normally already unmounted by the time PiP is exited. This
+// handler only covers the case where the lightbox is somehow still
+// mounted; release() is idempotent so calling it twice is harmless.
+function onLeavePip() {
+  pipSession.release()
+}
+
 function toggleFullscreen() {
   const el = videoEl.value
   if (!el) return
@@ -264,6 +310,7 @@ watch(currentItem, (item) => {
 
 watch(() => props.show, async (visible) => {
   if (visible) {
+    pipHandoff.value = false
     currentIndex.value = props.startIndex
     const item = mediaItems.value[props.startIndex]
     if (item) {
@@ -422,6 +469,38 @@ onUnmounted(() => {
   opacity: 0;
 }
 
+/* Picture-in-picture handoff (UIFIX-05): reads as the video moving into the
+   PiP window rather than a dismissal. The backdrop's blur/opacity fall away
+   while the content scales down and drifts toward the bottom-right corner
+   most browsers default the PiP window to — a best-effort convention, since
+   the actual corner is browser- and user-controlled. Applied only on the
+   PiP path; a normal close (button or Escape) never gets this class. */
+.lightbox-pip-handoff {
+  transition: opacity 0.3s ease, backdrop-filter 0.3s ease;
+  opacity: 0;
+  backdrop-filter: blur(0px);
+  -webkit-backdrop-filter: blur(0px);
+}
+.lightbox-pip-handoff .lightbox-topbar,
+.lightbox-pip-handoff .lightbox-nav {
+  transition: opacity 0.3s ease;
+  opacity: 0;
+}
+.lightbox-pip-handoff .lightbox-content {
+  transition: transform 0.3s cubic-bezier(0.22, 1, 0.36, 1), opacity 0.3s ease;
+  transform: scale(0.4) translate(40vw, 40vh);
+  opacity: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .lightbox-pip-handoff,
+  .lightbox-pip-handoff .lightbox-topbar,
+  .lightbox-pip-handoff .lightbox-nav,
+  .lightbox-pip-handoff .lightbox-content {
+    transition: none;
+  }
+}
+
 /* Mobile */
 @media (max-width: 768px) {
   .lightbox-content { padding: 3rem 0; }