@oxyhq/bloom 1.2.0 → 1.2.2

package/src/media-flight/MediaSurface.tsx

@@ -93,6 +93,19 @@ export interface MediaSurfaceProps {
    * surface that handed off to itself would release on its own first frame.
    */
   flightId?: string;
+  /**
+   * Render the video arm with NO player, unbinding this element from it while
+   * the element is still in the DOM.
+   *
+   * expo-video's web player mirrors pause across every element bound to it, and
+   * a `<video>` removed from the DOM is auto-paused by the browser — but
+   * `unmountVideoView` only runs in a PASSIVE effect cleanup, so it happens
+   * after removal and after that auto-pause. A dying element therefore pauses
+   * the one the viewer is watching. Setting this for one commit before unmount
+   * runs expo-video's own `[props.player]` effect early, whose cleanup unbinds,
+   * so the later pause reaches nobody.
+   */
+  detached?: boolean;
 }
 
 /**
@@ -112,6 +125,7 @@ export const MediaSurface = memo(function MediaSurface({
   accessibilityLabel,
   pointerEvents,
   flightId,
+  detached = false,
 }: MediaSurfaceProps) {
   // Captured once — see `surfaceType` above. A consumer changing it later gets
   // the value the view was mounted with, which is the only value expo-video
@@ -162,11 +176,21 @@ export const MediaSurface = memo(function MediaSurface({
       )}
       {content.kind === 'video' && expoVideo !== null ? (
         <expoVideo.VideoView
-          player={content.player}
+          player={detached ? null : content.player}
           contentFit={contentFit}
           surfaceType={mountedSurfaceType}
           nativeControls={nativeControls}
-          style={StyleSheet.absoluteFill}
+          // `absoluteFill` ALONE does not size this, and the reason is a CSS
+          // rule rather than a bug: expo-video renders a DOM `<video>`, which is
+          // a REPLACED element, and `position:absolute; inset:0` with
+          // `width/height:auto` resolves a replaced element to its INTRINSIC
+          // size — 300x150, the `<video>` default — instead of stretching it.
+          // Measured: inside a 320x200 box the element computed
+          // `left/right/top/bottom: 0px` and `width: 300px; height: 150px`, so
+          // it sat at the default while the box animated around it and then
+          // jumped when metadata arrived. The poster escapes this only because
+          // expo-image sizes its own element.
+          style={[StyleSheet.absoluteFill, styles.fillReplaced]}
           accessibilityLabel={accessibilityLabel}
           onFirstFrameRender={reportLive}
         />
@@ -222,6 +246,14 @@ export function EmptyMediaSurface({ style }: { style?: MediaPosterStyle }) {
 }
 
 const styles = StyleSheet.create({
+  /**
+   * Explicit size for a REPLACED element. Redundant for a `<div>` and
+   * load-bearing for a `<video>` — see the note at the call site.
+   */
+  fillReplaced: {
+    width: '100%',
+    height: '100%',
+  },
   box: {
     // What makes the box's corner radius actually clip a video, and the other
     // half of why the Android surface has to be a `textureView`.

package/src/media-flight/expo-video-module.ts

@@ -104,12 +104,42 @@ export interface ExpoVideoLike {
 
 /** `undefined` until the first load attempt, then the module or `null`. */
 let videoModule: ExpoVideoLike | null | undefined;
+/** Set by {@link provideExpoVideo}; wins over the `require` below. */
+let providedModule: ExpoVideoLike | null | undefined;
 /** Why the load failed, quoted verbatim in the dev warning. */
 let unavailableReason = '';
 let hasWarned = false;
 
+/**
+ * Hand Bloom the expo-video module explicitly.
+ *
+ * REQUIRED ON ANY ESM WEB BUNDLER, and measured rather than assumed: in a Vite
+ * bundle `typeof require` is `undefined`, so the optional-peer `require` below
+ * cannot run and video silently degrades to its poster **even when expo-video
+ * is installed**. Metro has a real `require` and is unaffected, which is why
+ * this went unnoticed — the app that uses this is Metro-built.
+ *
+ * There is no bundler-agnostic sync alternative: `import()` is async and this is
+ * called during render, so making it async would mean the surface renders
+ * without video for a frame and then upgrades. Handing the module over is
+ * explicit, synchronous, and costs the consumer one line at startup:
+ *
+ * ```ts
+ * import * as ExpoVideo from 'expo-video';
+ * provideExpoVideo(ExpoVideo);
+ * ```
+ *
+ * Pass `null` to clear it.
+ */
+export function provideExpoVideo(module: ExpoVideoLike | null): void {
+  providedModule = module;
+  // Drop any cached `require` result so the next load reflects this decision.
+  videoModule = undefined;
+}
+
 /** The expo-video module, or `null` when the optional peer is not installed. */
 export function loadExpoVideo(): ExpoVideoLike | null {
+  if (providedModule !== undefined && providedModule !== null) return providedModule;
   if (videoModule !== undefined) return videoModule;
   videoModule = null;
 
@@ -176,6 +206,7 @@ export function warnExpoVideoUnavailable(): void {
 /** Test seam — drops the cached module handle so a suite can load it again. */
 export function resetExpoVideoModule(): void {
   videoModule = undefined;
+  providedModule = undefined;
   unavailableReason = '';
   hasWarned = false;
 }

package/src/media-flight/index.ts

@@ -13,6 +13,7 @@ export { SURFACE_MOUNT_TIMEOUT_MS } from './constants';
 export {
   loadExpoVideo,
   warnExpoVideoUnavailable,
+  provideExpoVideo,
   resetExpoVideoModule,
   type ExpoVideoLike,
   type VideoPlayerLike,

package/src/media-flight/store.ts

@@ -77,6 +77,8 @@ interface FlightStatus {
   /** Waiters on `flyTo`'s promise, resolved once `mounted` turns true. */
   mountWaiters: Array<() => void>;
   mountTimer: ReturnType<typeof setTimeout> | null;
+  /** Pending final removal while the surface unbinds from its player. */
+  unbindTimer: ReturnType<typeof setTimeout> | null;
 }
 
 interface Registry {
@@ -119,6 +121,7 @@ function statusFor(id: string): FlightStatus {
       handedOff: false,
       mountWaiters: [],
       mountTimer: null,
+      unbindTimer: null,
     };
     reg.status.set(id, status);
   }
@@ -127,7 +130,9 @@ function statusFor(id: string): FlightStatus {
 
 function clearTimers(status: FlightStatus): void {
   if (status.mountTimer !== null) clearTimeout(status.mountTimer);
+  if (status.unbindTimer !== null) clearTimeout(status.unbindTimer);
   status.mountTimer = null;
+  status.unbindTimer = null;
 }
 
 function resolveMountWaiters(status: FlightStatus): void {
@@ -263,6 +268,7 @@ export function flyTo(
       // silently ignored by the view it is meant to configure.
       surfaceType: existing.surfaceType,
       landing: false,
+      unbinding: false,
       generation: existing.generation + 1,
     };
     reg.flights.set(id, next);
@@ -285,6 +291,7 @@ export function flyTo(
     surfaceType: options?.surfaceType ?? 'textureView',
     progress: makeMutable(0),
     landing: false,
+    unbinding: false,
     generation: 0,
   };
   reg.flights.set(id, flight);
@@ -394,9 +401,47 @@ export function flyBack(id: string): void {
   });
 }
 
-/** Drop the surface for `id`. Called when a landing leg settles, and on teardown. */
+/**
+ * Drop the surface for `id`. Called when a landing leg settles, and on teardown.
+ *
+ * A VIDEO surface does not go straight out. It renders for one more commit with
+ * NO player first, because expo-video's web player mirrors pause across every
+ * element bound to it and a `<video>` removed from the DOM is auto-paused by the
+ * browser — while `unmountVideoView` only runs in a PASSIVE effect cleanup,
+ * i.e. after removal and after that auto-pause. So the dying element pauses the
+ * one the viewer is now watching. Measured: the reel's video paused 1 ms after
+ * the flying surface left the DOM, with `currentTime` still advancing and
+ * nobody having called `pause()`.
+ *
+ * Rendering `player={null}` for one commit runs expo-video's own `[props.player]`
+ * effect while the node is STILL in the DOM: its cleanup calls
+ * `unmountVideoView`, the element leaves `_mountedVideos`, and its later pause
+ * reaches nobody. That is the documented mount/unmount pair, not a patch of
+ * somebody else's module.
+ *
+ * The cost is one frame in which the outgoing surface shows its poster instead
+ * of video. It is already on its way out and the destination is live by then —
+ * `handOff` is what got us here — so that frame is covered.
+ */
 export function releaseFlight(id: string): void {
   const reg = registry();
+  const flight = reg.flights.get(id);
+
+  if (flight !== undefined && flight.content.kind === 'video' && !flight.unbinding) {
+    reg.flights.set(id, { ...flight, unbinding: true });
+    const unbinding = statusFor(id);
+    if (unbinding.unbindTimer === null) {
+      // After the commit AND expo-video's passive effect, which is the whole
+      // point — a microtask would run before either.
+      unbinding.unbindTimer = setTimeout(() => {
+        unbinding.unbindTimer = null;
+        releaseFlight(id);
+      }, 0);
+    }
+    publish(reg);
+    return;
+  }
+
   const status = reg.status.get(id);
   if (status) {
     // A waiter still parked on `flyTo`'s promise would otherwise hang until its

package/src/media-flight/types.ts

@@ -94,6 +94,19 @@ export interface MediaFlight {
    * settles, the surface is released instead of parked.
    */
   landing: boolean;
+  /**
+   * True for the ONE commit between "release requested" and the surface
+   * actually going away, during which a video surface renders with no player.
+   *
+   * expo-video's web player MIRRORS pause across every element bound to it
+   * (`VideoPlayer.web.js`: `video.onpause` pauses all the others), and a
+   * `<video>` removed from the DOM is auto-paused by the browser. Its
+   * `unmountVideoView` runs in a PASSIVE effect cleanup — after removal, after
+   * the auto-pause — so a dying element pauses the one the viewer is watching.
+   * Unbinding first takes this element out of `_mountedVideos` while it is
+   * still in the DOM, so its later pause reaches nobody.
+   */
+  unbinding: boolean;
   /** Bumped on every retarget, so React remounts nothing but the layer re-reads. */
   generation: number;
 }