@oxyhq/bloom 1.2.1 → 1.3.0

package/src/media-flight/MediaFlightHost.tsx

@@ -0,0 +1,54 @@
+/**
+ * A place a media surface lives — NATIVE.
+ *
+ * Here a host is exactly what it looks like: a box that renders its own
+ * `MediaSurface`. Native has no equivalent of the web problem this component
+ * exists for (a DOM `<video>` that must survive its React owner), and expo-video
+ * on native hands a player between views without the pause mirroring that makes
+ * two web elements mutually destructive. So this is the plain implementation,
+ * and `MediaFlightHost.web.tsx` is the one that re-parents.
+ *
+ * ONE API, two implementations. A consumer writes the same JSX on both
+ * platforms and never learns which one it got.
+ */
+import { useCallback } from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { MediaSurface } from './MediaSurface';
+import { registerAnchor } from './store';
+import type { MediaFlightHostProps } from './types';
+
+export function MediaFlightHost({
+  id,
+  content,
+  style,
+  contentFit = 'cover',
+  nativeControls = false,
+  accessibilityLabel,
+  surfaceType,
+  pointerEvents,
+  flightId,
+}: MediaFlightHostProps) {
+  // A callback ref rather than an effect: the anchor must be measurable the
+  // moment the box is on screen, and a tap can come one frame later.
+  const setNode = useCallback(
+    (node: View | null) => registerAnchor(id, node),
+    [id],
+  );
+
+  return (
+    <View ref={setNode} style={style} pointerEvents={pointerEvents}>
+      <MediaSurface
+        content={content}
+        contentFit={contentFit}
+        nativeControls={nativeControls}
+        accessibilityLabel={accessibilityLabel}
+        surfaceType={surfaceType}
+        flightId={flightId}
+        style={StyleSheet.absoluteFill}
+      />
+    </View>
+  );
+}
+
+MediaFlightHost.displayName = 'MediaFlightHost';

package/src/media-flight/MediaFlightHost.web.tsx

@@ -0,0 +1,84 @@
+/**
+ * A place a media surface lives — WEB, where it does NOT render the media.
+ *
+ * This host renders an empty box and CLAIMS the shared node for its id. The
+ * media itself is one DOM node the layer paints once and moves between hosts
+ * with `appendChild`, so a video keeps its element, its decoder and its
+ * position when the origin route unmounts mid-flight. See `media-node.web.ts`
+ * for why one element is the only topology that keeps both the position and the
+ * playback.
+ *
+ * The consumer writes the same JSX as on native and never learns the
+ * difference — including that here, `flightId` is not needed: a flight ends
+ * when a destination host claims the node, and the node it claims has been
+ * showing the media all along.
+ */
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { View } from 'react-native';
+
+import {
+  HOST_RANK,
+  claimMediaNode,
+  releaseMediaNode,
+  type MediaNodeRender,
+} from './media-node.web';
+import { handOffFlight, hasFlight, registerAnchor } from './store';
+import type { MediaFlightHostProps } from './types';
+
+export function MediaFlightHost({
+  id,
+  content,
+  style,
+  contentFit = 'cover',
+  nativeControls = false,
+  accessibilityLabel,
+  pointerEvents,
+  flightId,
+}: MediaFlightHostProps) {
+  // State rather than a ref, because the claim runs in a layout effect and an
+  // effect cannot depend on a ref's mutation. One extra render at mount.
+  const [node, setNode] = useState<View | null>(null);
+
+  const setHost = useCallback(
+    (next: View | null) => {
+      registerAnchor(id, next);
+      setNode(next);
+    },
+    [id],
+  );
+
+  const render = useMemo<MediaNodeRender>(
+    () => ({ content, contentFit, nativeControls, accessibilityLabel, flightId }),
+    [content, contentFit, nativeControls, accessibilityLabel, flightId],
+  );
+  const renderRef = useRef(render);
+
+  // Declared FIRST so it runs first on mount: it seeds the ref the claim below
+  // reads, and afterwards it is what pushes prop changes into a live claim —
+  // in place, without releasing, because a release would move the node and a
+  // move away and back is a removal, which is what pauses a video.
+  useLayoutEffect(() => {
+    renderRef.current = render;
+    const el = node as unknown as HTMLElement | null;
+    if (el !== null) claimMediaNode(id, el, HOST_RANK, render);
+  }, [id, node, render]);
+
+  // Owns the claim's LIFETIME, and only that: its cleanup must run when the
+  // host really goes away, never on a prop change.
+  useLayoutEffect(() => {
+    const el = node as unknown as HTMLElement | null;
+    if (el === null) return undefined;
+    claimMediaNode(id, el, HOST_RANK, renderRef.current);
+    // A new host appearing mid-flight IS the hand-off. On native the
+    // destination has to decode a first frame before it can say this; here the
+    // node it just claimed is the one that has been playing since the origin,
+    // so mounting is the whole signal. An origin host does not reach this with
+    // a flight live — it claimed before the flight began.
+    if (hasFlight(id)) handOffFlight(id);
+    return () => releaseMediaNode(id, el, HOST_RANK);
+  }, [id, node]);
+
+  return <View ref={setHost} style={style} pointerEvents={pointerEvents} />;
+}
+
+MediaFlightHost.displayName = 'MediaFlightHost';

package/src/media-flight/MediaFlightLayer.tsx

@@ -88,7 +88,7 @@ MediaFlightLayer.displayName = 'MediaFlightLayer';
  * work per frame is one absolutely-positioned node resizing.
  */
 function MediaFlightSurface({ flight }: { flight: MediaFlight }) {
-  const { id, from, to, progress, content, cornerRadius, contentFit, surfaceType } = flight;
+  const { id, from, to, progress, content, cornerRadius, contentFit, surfaceType, unbinding } = flight;
 
   // The COMMIT signal `flyTo`'s promise waits on, and the reason it is an effect
   // rather than anything derived: what the caller needs to know is that React
@@ -128,6 +128,12 @@ function MediaFlightSurface({ flight }: { flight: MediaFlight }) {
       content={content}
       contentFit={contentFit}
       surfaceType={surfaceType}
+      // One commit with no player before this node leaves the DOM — see
+      // `releaseFlight`, and note there that what it buys is expo-video
+      // emptying the source, not the unbind. Without it the dying element's
+      // auto-pause mirrors through expo-video and stops the video the viewer
+      // just landed on.
+      detached={unbinding}
       // A flying surface is a picture, never a control: it must not intercept
       // the press that is already travelling to whatever is underneath it.
       pointerEvents="none"

package/src/media-flight/MediaFlightLayer.web.tsx

@@ -0,0 +1,219 @@
+/**
+ * The layer that survives navigation — WEB, where it also OWNS the media.
+ *
+ * Everything in `MediaFlightLayer.tsx` still holds: mounted once at the app
+ * root, painting through `Portal` so a flying surface belongs to neither route.
+ * What this fork adds is the other half of the web story.
+ *
+ * ## It paints each shared node exactly once, forever
+ *
+ * `createPortal(<MediaSurface …/>, wrapper)` for every id a host has claimed.
+ * The wrapper is a plain `<div>` created OUTSIDE React by `media-node.web.ts`,
+ * so React reconciles the media against a container whose identity never
+ * changes while the registry moves that container between hosts with
+ * `appendChild`. React never sees the move; the browser never sees a removal;
+ * the video never loses its element, its decoder or its position.
+ *
+ * That is why the layer, and not the host, renders the media on web: the media
+ * has to be rendered by a tree that outlives every host, and the app root is
+ * the only such tree.
+ *
+ * ## A flying surface with a shared node paints nothing itself
+ *
+ * It becomes a positioned, animated BOX that claims the node — one more host,
+ * outranking the others for the length of the leg. A flight for an id with no
+ * shared node (an image gallery, any consumer that has not adopted a host)
+ * falls back to painting its own `MediaSurface`, which is what every flight did
+ * before hosts existed.
+ */
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { StyleSheet, type View } from 'react-native';
+import { createPortal } from 'react-dom';
+import Animated, { interpolate, useAnimatedStyle } from 'react-native-reanimated';
+
+import { OverlayRoot } from '../overlay';
+import { Portal } from '../portal/index.web';
+import { MediaSurface, type MediaSurfaceStyle } from './MediaSurface';
+import {
+  FLIGHT_RANK,
+  claimMediaNode,
+  getMediaNodes,
+  releaseMediaNode,
+  subscribeToMediaNodes,
+  type MediaNodeRender,
+  type MediaNodeView,
+} from './media-node.web';
+import { getFlights, notifySurfaceMounted, subscribeToFlights } from './store';
+import type { MediaFlight } from './types';
+
+export function MediaFlightLayer() {
+  const flights = useSyncExternalStore(subscribeToFlights, getFlights, getFlights);
+  const nodes = useSyncExternalStore(subscribeToMediaNodes, getMediaNodes, getMediaNodes);
+
+  if (flights.length === 0 && nodes.length === 0) return null;
+
+  return (
+    <>
+      {nodes.map((node) => (
+        <SharedMediaNode key={node.id} node={node} />
+      ))}
+      {flights.length === 0 ? null : (
+        <Portal>
+          {/* `OverlayRoot` fills the viewport, is `box-none`, and takes this
+              surface's place in the open-order overlay stack. */}
+          <OverlayRoot>
+            {flights.map((flight) => (
+              <MediaFlightSurface
+                key={flight.id}
+                flight={flight}
+                // Read from the SNAPSHOT, never from the registry: a lookup
+                // during render is external mutable state in a memoized
+                // position, which the React Compiler is allowed to freeze.
+                shared={nodes.some((node) => node.id === flight.id)}
+              />
+            ))}
+          </OverlayRoot>
+        </Portal>
+      )}
+    </>
+  );
+}
+
+MediaFlightLayer.displayName = 'MediaFlightLayer';
+
+/** One media element, painted into the wrapper its id owns, and never again. */
+function SharedMediaNode({ node }: { node: MediaNodeView }) {
+  const { content, contentFit, nativeControls, accessibilityLabel, flightId } = node.render;
+  return createPortal(
+    <MediaSurface
+      content={content}
+      contentFit={contentFit}
+      nativeControls={nativeControls}
+      accessibilityLabel={accessibilityLabel}
+      flightId={flightId}
+      style={StyleSheet.absoluteFill}
+    />,
+    node.wrapper,
+  );
+}
+
+/**
+ * One flying surface. See `MediaFlightLayer.tsx` for why the size is animated
+ * rather than scaled.
+ */
+function MediaFlightSurface({ flight, shared }: { flight: MediaFlight; shared: boolean }) {
+  const { id, from, to, progress, content, cornerRadius, contentFit, surfaceType, unbinding } = flight;
+
+  useEffect(() => {
+    notifySurfaceMounted(id);
+  }, [id]);
+
+  const originX = from.x - to.x;
+  const originY = from.y - to.y;
+
+  // CRITICAL — every shared value a mapper READS must be listed in its deps.
+  // On web WITHOUT the react-native-worklets babel plugin, reanimated drives a
+  // mapper off its deps array rather than off the reads it detects: with none,
+  // it runs ONCE and freezes at the opening frame. See `MediaFlightLayer.tsx`.
+  const boxStyle = useAnimatedStyle(
+    () => ({
+      transform: [
+        { translateX: interpolate(progress.value, [0, 1], [originX, 0]) },
+        { translateY: interpolate(progress.value, [0, 1], [originY, 0]) },
+      ],
+      width: interpolate(progress.value, [0, 1], [from.width, to.width]),
+      height: interpolate(progress.value, [0, 1], [from.height, to.height]),
+    }),
+    [progress, originX, originY, from.width, from.height, to.width, to.height],
+  );
+
+  const box = [styles.box, { left: to.x, top: to.y, borderRadius: cornerRadius }, boxStyle];
+
+  const render = useMemo<MediaNodeRender>(
+    () => ({
+      content,
+      contentFit,
+      nativeControls: false,
+      accessibilityLabel: undefined,
+      // A flying surface never hands off to itself.
+      flightId: undefined,
+    }),
+    [content, contentFit],
+  );
+
+  // The shared node is already painting this media. The flight is then a BOX
+  // that borrows it for the length of the leg, never a second copy.
+  if (shared) return <FlyingSharedNode id={id} style={box} render={render} />;
+
+  return (
+    <MediaSurface
+      content={content}
+      contentFit={contentFit}
+      surfaceType={surfaceType}
+      // One commit with no player before this node leaves the DOM — see
+      // `releaseFlight`. Only the no-shared-node path can need it: a shared
+      // node is never removed, which is the point of the whole mechanism.
+      detached={unbinding}
+      // A flying surface is a picture, never a control.
+      pointerEvents="none"
+      style={box}
+    />
+  );
+}
+
+/**
+ * The flight's own claim on a shared node.
+ *
+ * `pointerEvents` stays `none` on the BOX: a flying surface must not take the
+ * press travelling to whatever is underneath it. The wrapper inside sets
+ * `pointer-events: auto` for the media's sake, which is what a host needs and
+ * is inert here — a descendant asking for `auto` does not override a `none`
+ * ancestor.
+ */
+function FlyingSharedNode({
+  id,
+  style,
+  render,
+}: {
+  id: string;
+  style: MediaSurfaceStyle;
+  render: MediaNodeRender;
+}) {
+  const [node, setNode] = useState<View | null>(null);
+  const setBox = useCallback((next: View | null) => setNode(next), []);
+  const renderRef = useRef(render);
+
+  // Declared first so it runs first on mount, and afterwards is what pushes
+  // prop changes into a live claim IN PLACE — releasing and re-claiming would
+  // move the node away and back, and a move away is a removal.
+  useLayoutEffect(() => {
+    renderRef.current = render;
+    const el = node as unknown as HTMLElement | null;
+    if (el !== null) claimMediaNode(id, el, FLIGHT_RANK, render);
+  }, [id, node, render]);
+
+  // Owns the claim's LIFETIME, and only that.
+  useLayoutEffect(() => {
+    const el = node as unknown as HTMLElement | null;
+    if (el === null) return undefined;
+    claimMediaNode(id, el, FLIGHT_RANK, renderRef.current);
+    return () => releaseMediaNode(id, el, FLIGHT_RANK);
+  }, [id, node]);
+
+  return <Animated.View ref={setBox} style={style} pointerEvents="none" />;
+}
+
+const styles = StyleSheet.create({
+  box: {
+    position: 'absolute',
+    overflow: 'hidden',
+  },
+});

package/src/media-flight/MediaSurface.tsx

@@ -93,6 +93,23 @@ 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, so a dying
+   * element pauses the one the viewer is watching.
+   *
+   * Setting this for one commit runs expo-video's own `[props.player]` effect
+   * early — and the half that matters is `removeAttribute('src'); load()`
+   * (`VideoView.web.js:206`), not the unbind beside it. The media element load
+   * algorithm pauses WITHOUT firing `pause` (measured in real Chrome, with
+   * controls), so the element goes quiet and its later removal fires nothing.
+   * Unbinding alone does not help: `unmountVideoView` never clears the handler
+   * it installed. See `releaseFlight`.
+   */
+  detached?: boolean;
 }
 
 /**
@@ -112,6 +129,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,7 +180,7 @@ 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}

package/src/media-flight/index.ts

@@ -1,4 +1,5 @@
 export { MediaFlightLayer } from './MediaFlightLayer';
+export { MediaFlightHost } from './MediaFlightHost';
 export { MediaSurface, MediaPoster, EmptyMediaSurface } from './MediaSurface';
 export { useMediaFlight } from './use-media-flight';
 export {
@@ -25,6 +26,7 @@ export type {
   MediaFlight,
   MediaFlightAnchorNode,
   MediaFlightController,
+  MediaFlightHostProps,
   MediaFlightOptions,
   MediaSurfaceContent,
   MediaSurfaceImage,

package/src/media-flight/index.web.ts

@@ -0,0 +1,45 @@
+/**
+ * The web barrel, which exists to NAME the `.web` siblings.
+ *
+ * Export conditions do not apply to relative specifiers, so a bundler that is
+ * not Metro reaches `MediaFlightLayer.web.tsx` and `MediaFlightHost.web.tsx`
+ * only because this file spells them out. Those two are the whole web fork of
+ * this family: the layer that paints each shared media node once, and the host
+ * that claims it. Everything else below is the same module on both platforms.
+ */
+export { MediaFlightLayer } from './MediaFlightLayer.web';
+export { MediaFlightHost } from './MediaFlightHost.web';
+export { MediaSurface, MediaPoster, EmptyMediaSurface } from './MediaSurface';
+export { useMediaFlight } from './use-media-flight';
+export {
+  DEFAULT_FLIGHT_CORNER_RADIUS,
+  flightProgress,
+  handOffFlight,
+  hasFlight,
+  releaseFlight,
+  resetMediaFlight,
+} from './store';
+export { SURFACE_MOUNT_TIMEOUT_MS } from './constants';
+export {
+  loadExpoVideo,
+  warnExpoVideoUnavailable,
+  provideExpoVideo,
+  resetExpoVideoModule,
+  type ExpoVideoLike,
+  type VideoPlayerLike,
+  type VideoSurfaceContentFit,
+  type VideoSurfaceType,
+  type VideoViewLikeProps,
+} from './expo-video-module';
+export type {
+  MediaFlight,
+  MediaFlightAnchorNode,
+  MediaFlightController,
+  MediaFlightHostProps,
+  MediaFlightOptions,
+  MediaSurfaceContent,
+  MediaSurfaceImage,
+  MediaSurfaceVideo,
+  MeasuredRect,
+} from './types';
+export type { MediaSurfaceProps } from './MediaSurface';