@oxyhq/bloom 1.2.2 → 1.4.0

package/lib/typescript/module/media-flight/types.d.ts

@@ -1,3 +1,5 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
 import type { VideoPlayerLike, VideoSurfaceType } from './expo-video-module';
 /**
@@ -205,4 +207,95 @@ export interface MediaFlightController {
      */
     progress: SharedValue<number>;
 }
+/**
+ * What Bloom hands a video slot: the three things it must decide, and nothing
+ * else.
+ *
+ * `style` is not advisory. A DOM `<video>` is a REPLACED element, and
+ * `position:absolute; inset:0` with `width/height:auto` resolves it to its
+ * INTRINSIC size (300x150) instead of stretching — so a slot that drops this
+ * style paints a 300x150 video inside whatever box it was given. Spread it.
+ */
+export interface MediaVideoSlotProps {
+    /**
+     * The player Bloom was given — never one Bloom created.
+     *
+     * `null` means UNBIND THIS ELEMENT NOW, and it must be passed straight
+     * through. expo-video answers a null player by emptying the source, which
+     * pauses the element without an event; that silence is what stops a surface
+     * on its way out from pausing the one the viewer just landed on. Substituting
+     * anything else here — keeping the old player, unmounting instead — brings
+     * that defect back. See `releaseFlight`.
+     */
+    player: VideoPlayerLike | null;
+    /** Fills the box. Spread it — see above. */
+    style: StyleProp<ViewStyle>;
+    contentFit: 'contain' | 'cover';
+}
+/**
+ * Paint the video yourself.
+ *
+ * Bloom mounts a `VideoView` with the handful of props it knows about, which is
+ * enough until a consumer needs something only its OWN element can give it: a
+ * `ref` for `startPictureInPicture()` or `enterFullscreen()`, expo-video's
+ * picture-in-picture callbacks, `onFirstFrameRender`, anything expo-video adds
+ * later. Widening Bloom's props to cover those would drag expo-video's surface
+ * into Bloom's API, and it would be behind again on the next release.
+ *
+ * So the consumer may build the element instead, with Bloom deciding only what
+ * it has to: which player, and a style that fills the box.
+ *
+ * MEMOISE IT (`useCallback`). The slot is part of what a host publishes to the
+ * layer, compared by identity — a new function every render republishes every
+ * render. Correct either way, wasteful if you skip it.
+ */
+export type MediaVideoSlot = (props: MediaVideoSlotProps) => ReactNode;
+/**
+ * A place a media surface may live: the feed row it starts in, the fullscreen
+ * player it lands in, and every other end of a flight.
+ *
+ * A host DECLARES a box; it does not own the media. On web that distinction is
+ * the whole feature — the media is ONE DOM node the layer paints once and moves
+ * between hosts, so it survives the origin route unmounting mid-flight without
+ * ever leaving the document. On native a host renders its media inline, which
+ * is what it has always done and what the platform makes correct there.
+ */
+export interface MediaFlightHostProps {
+    /** The id this host shares with the flight and with the other end. */
+    id: string;
+    /** What to paint: a still image, or a consumer-owned expo-video player. */
+    content: MediaSurfaceContent;
+    /** Style of the host BOX. Give it the radius and `overflow: 'hidden'` you want. */
+    style?: StyleProp<ViewStyle>;
+    /** How the media fills the box. Defaults to `'cover'`. */
+    contentFit?: 'contain' | 'cover';
+    /**
+     * Paint the video yourself, keeping your own `ref` and expo-video props. See
+     * {@link MediaVideoSlot}; memoise it.
+     */
+    renderVideo?: MediaVideoSlot;
+    /** Whether the video arm shows expo-video's own controls. Defaults to `false`. */
+    nativeControls?: boolean;
+    accessibilityLabel?: string;
+    /**
+     * Android's rendering surface for the video arm. See `MediaSurfaceProps`.
+     * Ignored on web, where there is no such choice.
+     */
+    surfaceType?: VideoSurfaceType;
+    /**
+     * Passed through as a PROP, never as a style key — react-native-web resolves
+     * `box-none`/`box-only` from the prop path only.
+     */
+    pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+    /**
+     * Set on a DESTINATION host, to the id its flight was started with, when the
+     * destination paints its media ITSELF rather than through the shared node —
+     * which on native is always. The web host does not need it: a flight there
+     * ends when the destination host claims the node, because by then the node it
+     * is claiming has been showing the media all along.
+     *
+     * Leave it unset on an origin host, which would otherwise hand off to itself.
+     */
+    flightId?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/media-flight/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/media-flight/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/media-flight/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,eAAe,CACb,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACtE,IAAI,CAAC;CACT;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,mBAAmB,CAAC;IAC7B,wCAAwC;IACxC,IAAI,EAAE,YAAY,CAAC;IACnB,oCAAoC;IACpC,EAAE,EAAE,YAAY,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC;IAChC,gFAAgF;IAChF,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI,KAAK,IAAI,CAAC;IACzE;;;;OAIG;IACH,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5D;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,CACL,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,kBAAkB,KACzB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;OAIG;IACH,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;;;;;;;OASG;IACH,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;OASG;IACH,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,4CAA4C;IAC5C,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC5B,UAAU,EAAE,SAAS,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,SAAS,CAAC;AAEvE;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,OAAO,EAAE,mBAAmB,CAAC;IAC7B,mFAAmF;IACnF,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,kFAAkF;IAClF,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC1D;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.2.2",
+  "version": "1.4.0",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
@@ -610,6 +610,11 @@
         "types": "./lib/typescript/module/media-flight/index.d.ts",
         "default": "./src/media-flight/index.ts"
       },
+      "browser": {
+        "types": "./lib/typescript/module/media-flight/index.web.d.ts",
+        "import": "./lib/module/media-flight/index.web.js",
+        "require": "./lib/commonjs/media-flight/index.web.js"
+      },
       "import": {
         "types": "./lib/typescript/module/media-flight/index.d.ts",
         "default": "./lib/module/media-flight/index.js"

package/src/media-flight/MediaFlightHost.tsx

@@ -0,0 +1,56 @@
+/**
+ * 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',
+  renderVideo,
+  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}
+        renderVideo={renderVideo}
+        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,85 @@
+/**
+ * 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',
+  renderVideo,
+  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, renderVideo, nativeControls, accessibilityLabel, flightId }),
+    [content, contentFit, renderVideo, 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

@@ -129,8 +129,10 @@ function MediaFlightSurface({ flight }: { flight: MediaFlight }) {
       contentFit={contentFit}
       surfaceType={surfaceType}
       // One commit with no player before this node leaves the DOM — see
-      // `releaseFlight`. Without it the dying element's auto-pause mirrors
-      // through expo-video and stops the video the viewer just landed on.
+      // `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.

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

@@ -0,0 +1,191 @@
+/**
+ * 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,
+  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 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, renderVideo, nativeControls, accessibilityLabel, flightId } = node.render;
+  return createPortal(
+    <MediaSurface
+      content={content}
+      contentFit={contentFit}
+      renderVideo={renderVideo}
+      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];
+
+  // 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} />;
+
+  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 }: { id: string; style: MediaSurfaceStyle }) {
+  const [node, setNode] = useState<View | null>(null);
+  const setBox = useCallback((next: View | null) => setNode(next), []);
+
+  // A POSITION-ONLY claim: it says where the node lives for the length of the
+  // leg and nothing about what is painted in it. A flight that published a
+  // render of its own would replace the hosts' — and swap a consumer's own
+  // element out and back, which is two remounts in the middle of the one
+  // operation whose whole point is that the element is never rebuilt.
+  useLayoutEffect(() => {
+    const el = node as unknown as HTMLElement | null;
+    if (el === null) return undefined;
+    claimMediaNode(id, el, FLIGHT_RANK);
+    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

@@ -26,7 +26,7 @@ import { Image } from 'expo-image';
 import Animated from 'react-native-reanimated';
 
 import { handOffFlight } from './store';
-import type { MediaSurfaceContent } from './types';
+import type { MediaSurfaceContent, MediaVideoSlot } from './types';
 import {
   loadExpoVideo,
   warnExpoVideoUnavailable,
@@ -70,6 +70,14 @@ export interface MediaSurfaceProps {
    * is every property a flying box relies on.
    */
   surfaceType?: VideoSurfaceType;
+  /**
+   * Paint the video yourself, keeping your own `ref` and expo-video props.
+   *
+   * When this is given, Bloom builds no `VideoView` at all and the optional
+   * peer is never loaded on this path — the consumer already imported
+   * expo-video to write the slot. See {@link MediaVideoSlot}.
+   */
+  renderVideo?: MediaVideoSlot;
   /** Whether the video arm shows expo-video's own controls. Defaults to `false`. */
   nativeControls?: boolean;
   accessibilityLabel?: string;
@@ -98,12 +106,16 @@ export interface MediaSurfaceProps {
    * 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.
+   * 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;
 }
@@ -121,6 +133,7 @@ export const MediaSurface = memo(function MediaSurface({
   style,
   contentFit = 'contain',
   surfaceType = 'textureView',
+  renderVideo,
   nativeControls = false,
   accessibilityLabel,
   pointerEvents,
@@ -141,10 +154,12 @@ export const MediaSurface = memo(function MediaSurface({
   }, [flightId]);
 
   const still = content.kind === 'video' ? content.poster : content.uri;
-  // Loaded for the video arm only, and only when there is one — an image
-  // surface must never make an app resolve an optional native peer.
-  const expoVideo = content.kind === 'video' ? loadExpoVideo() : null;
-  if (content.kind === 'video' && expoVideo === null) {
+  // Loaded for the video arm only, and only when Bloom is the one building the
+  // element — an image surface must never make an app resolve an optional
+  // native peer, and neither must a consumer that brought its own view.
+  const expoVideo =
+    content.kind === 'video' && renderVideo === undefined ? loadExpoVideo() : null;
+  if (content.kind === 'video' && renderVideo === undefined && expoVideo === null) {
     // Degrade to the poster rather than to nothing: a black hole where a video
     // should be reads as a broken app, a still frame reads as a video that has
     // not started. The warning is what makes the difference visible to the
@@ -174,7 +189,16 @@ export const MediaSurface = memo(function MediaSurface({
           {...webDraggableProps}
         />
       )}
-      {content.kind === 'video' && expoVideo !== null ? (
+      {content.kind === 'video' && renderVideo !== undefined
+        ? renderVideo({
+            player: detached ? null : content.player,
+            // The same style Bloom's own view gets, for the same reason: a
+            // replaced element that is not told its size paints at 300x150.
+            style: [StyleSheet.absoluteFill, styles.fillReplaced],
+            contentFit,
+          })
+        : null}
+      {content.kind === 'video' && renderVideo === undefined && expoVideo !== null ? (
         <expoVideo.VideoView
           player={detached ? null : content.player}
           contentFit={contentFit}

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';