@oxyhq/bloom 1.0.6 → 1.2.0

package/src/media-flight/MediaFlightLayer.tsx

@@ -0,0 +1,144 @@
+/**
+ * The layer that survives navigation.
+ *
+ * ## The problem it exists for
+ *
+ * A shared-element transition normally assumes the ORIGIN screen is still
+ * mounted while the element travels — which is why `react-native-teleport` needs
+ * `presentation: 'transparentModal'` and has no web story at all. Under
+ * expo-router on web the origin route is UNMOUNTED the moment the URL changes,
+ * so anything the origin was rendering (a `VideoView`, a decoded image) is gone
+ * before the first frame of the transition.
+ *
+ * The fix is to move the surface OUT of both screens for the duration of the
+ * flight. `<MediaFlightLayer>` is mounted ONCE at the app root and renders
+ * through Bloom's `Portal`, whose outlet lives above the router on both
+ * platforms — so the surface it paints belongs to neither route and neither
+ * route can take it down. Origin and destination only DECLARE where they want
+ * it (`registerAnchor` + `flyTo`); the layer is what actually paints it.
+ *
+ * ## One surface per id
+ *
+ * That is the contract, and for video it is the whole feature. expo-video keeps
+ * the `VideoPlayer` OBJECT separate from the `VideoView` that shows it, and one
+ * player may feed several views — so moving a video is a matter of mounting ONE
+ * view in the right place, never of creating a second player. A second surface
+ * for the same id would mean two views mounted over one another and a visible
+ * swap; the store enforces one by RETARGETING an existing flight rather than
+ * adding to it.
+ *
+ * ## It never takes a click
+ *
+ * Every node here is `pointerEvents="none"` (or `box-none` on the root, via
+ * `OverlayRoot`). A flying surface is a picture of something the app is already
+ * showing: the controls underneath it stay the ones the user is pressing, and a
+ * layer mounted for the whole life of the app that swallowed presses would be
+ * indistinguishable from a frozen UI.
+ */
+import { useEffect, useSyncExternalStore } from 'react';
+import { StyleSheet } from 'react-native';
+import { interpolate, useAnimatedStyle } from 'react-native-reanimated';
+
+import { OverlayRoot } from '../overlay';
+import { Portal } from '../portal';
+import { MediaSurface } from './MediaSurface';
+import { getFlights, notifySurfaceMounted, subscribeToFlights } from './store';
+import type { MediaFlight } from './types';
+
+/**
+ * Mount ONCE, at the app root, above the router. Renders nothing at all until a
+ * flight is live, so it costs a subscription and no view while idle — and takes
+ * an overlay rank only while it is actually painting, which is what keeps the
+ * overlay stack's counter able to reset (see `overlay/stack.ts`).
+ */
+export function MediaFlightLayer() {
+  const flights = useSyncExternalStore(subscribeToFlights, getFlights, getFlights);
+
+  if (flights.length === 0) return null;
+
+  return (
+    <Portal>
+      {/* `OverlayRoot` fills the viewport, is `box-none`, and takes this
+          surface's place in the open-order overlay stack — so a flight started
+          over an open dialog paints above it, and one started under a later
+          sheet goes behind. */}
+      <OverlayRoot>
+        {flights.map((flight) => (
+          <MediaFlightSurface key={flight.id} flight={flight} />
+        ))}
+      </OverlayRoot>
+    </Portal>
+  );
+}
+
+MediaFlightLayer.displayName = 'MediaFlightLayer';
+
+/**
+ * One flying surface.
+ *
+ * ## Why the size is animated rather than scaled
+ *
+ * The media gallery flies its images with a uniform `scale`, which is right
+ * there: it opens from a thumbnail into a box of the SAME aspect ratio, so one
+ * factor describes the whole move. A flight does not have that luxury — it
+ * routinely goes from a cropped square tile to a 16:9 player — and a uniform
+ * scale would leave the first frame the wrong height, i.e. visibly not the
+ * thumbnail it is supposed to be replacing. Interpolating `width`/`height` is
+ * exact at both ends; the position still rides a transform, so the only layout
+ * work per frame is one absolutely-positioned node resizing.
+ */
+function MediaFlightSurface({ flight }: { flight: MediaFlight }) {
+  const { id, from, to, progress, content, cornerRadius, contentFit, surfaceType } = 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
+  // has actually put this surface in the tree, and an effect is the only thing
+  // in React that means exactly that. On web it is also the moment the
+  // `<video>` element joined expo-video's mounted set — which is what carries
+  // `currentTime` across from the origin, and what stops working the instant
+  // the caller navigates first.
+  useEffect(() => {
+    notifySurfaceMounted(id);
+  }, [id]);
+
+  // Deltas rather than absolute rects, so the worklet closes over four numbers.
+  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 cannot
+  // auto-detect the reads and drives the mapper off the deps array instead:
+  // with none, it runs ONCE and freezes at the opening frame while `progress`
+  // animates underneath it. Same rule as `ZoomableMediaGallery` and
+  // `BottomSheetBase`. Do NOT strip these.
+  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],
+  );
+
+  return (
+    <MediaSurface
+      content={content}
+      contentFit={contentFit}
+      surfaceType={surfaceType}
+      // 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"
+      style={[styles.box, { left: to.x, top: to.y, borderRadius: cornerRadius }, boxStyle]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    position: 'absolute',
+    overflow: 'hidden',
+  },
+});

package/src/media-flight/MediaSurface.tsx

@@ -0,0 +1,233 @@
+/**
+ * ONE renderer for "an image or a video, painted into a box".
+ *
+ * Both the flight layer and the media gallery need exactly this, and they need
+ * it to be the same code: a flight that lands inside the gallery hands its
+ * surface over frame-for-frame, so two renderers that disagree by a pixel of
+ * `contentFit` or a corner radius show the swap.
+ *
+ * BOTH ARMS RENDER THE SAME BOX — an `Animated.View` with the media filling it —
+ * rather than the image arm rendering an animated `Image` directly. That is the
+ * property that makes an image and a video interchangeable at a call site: the
+ * caller's style means the same thing either way, the corner radius clips a
+ * platform video surface the way it rounds an image, and the transform lands on
+ * a node reanimated is allowed to drive (expo-video's own host is not one).
+ */
+import { memo, useCallback, useState, type ComponentProps } from 'react';
+import {
+  Platform,
+  StyleSheet,
+  View,
+  type ImageStyle,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { Image } from 'expo-image';
+import Animated from 'react-native-reanimated';
+
+import { handOffFlight } from './store';
+import type { MediaSurfaceContent } from './types';
+import {
+  loadExpoVideo,
+  warnExpoVideoUnavailable,
+  type VideoSurfaceType,
+} from './expo-video-module';
+
+/**
+ * Exactly what `Animated.View` accepts, taken from the component rather than
+ * restated: a caller hands this component the output of `useAnimatedStyle` and a
+ * hand-written `StyleProp<ViewStyle>` would reject it.
+ */
+export type MediaSurfaceStyle = ComponentProps<typeof Animated.View>['style'];
+
+/**
+ * The style a STILL accepts. The intersection is what lets one value reach both
+ * an `Image` and a `View`: `ViewStyle` and `ImageStyle` disagree on exactly one
+ * key (`overflow`, which `ViewStyle` also allows to be `'scroll'`), and the
+ * intersection narrows it to the two values both accept.
+ */
+export type MediaPosterStyle = StyleProp<ViewStyle & ImageStyle>;
+
+// Web-only: a media surface is never a drag source. Written as an inline
+// conditional SPREAD rather than a `Platform.select` returning `undefined` —
+// spreading a `T | undefined` into JSX crashes tsc 5.9 outright
+// (`getIntersectionTypeFacts: type.types is not iterable`), and the gallery
+// already wrote it this way for the same reason.
+const webDraggableProps = Platform.OS === 'web' ? { draggable: false } : {};
+
+export interface MediaSurfaceProps {
+  /** What to paint: a still image, or a consumer-owned expo-video player. */
+  content: MediaSurfaceContent;
+  /** Size, radius and transform of the box. May carry an animated style. */
+  style?: MediaSurfaceStyle;
+  /** How the media fills the box. Defaults to `'contain'`. */
+  contentFit?: 'contain' | 'cover';
+  /**
+   * Android's rendering surface for the video arm. Defaults to `'textureView'`
+   * and is CAPTURED ON FIRST RENDER: expo-video documents that this prop must
+   * not change at runtime, and a `surfaceView` is composited outside the app's
+   * view hierarchy — it ignores its parent's clip, radius and transform, which
+   * is every property a flying box relies on.
+   */
+  surfaceType?: VideoSurfaceType;
+  /** Whether the video arm shows expo-video's own controls. Defaults to `false`. */
+  nativeControls?: boolean;
+  accessibilityLabel?: string;
+  /**
+   * Passed through as a PROP, never as a style key: react-native-web resolves
+   * the RN-only `box-none`/`box-only` values from the prop path only.
+   */
+  pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+  /**
+   * Set this on the DESTINATION surface of a media flight, to the same id the
+   * flight was started with. When this surface presents its first frame it tells
+   * the layer to let the flying copy go.
+   *
+   * It exists so the ordering knowledge stays in Bloom. The alternative is a
+   * consumer releasing the flight on a timer — and the timer is always wrong,
+   * because a fullscreen video route measured ~1 s from tap to first frame
+   * against production while a flight animation lasts ~300 ms. Whoever guessed
+   * would be choosing between a hole and a surface that overstays.
+   *
+   * Leave it unset on an origin surface, and on the flight layer's own: a
+   * surface that handed off to itself would release on its own first frame.
+   */
+  flightId?: string;
+}
+
+/**
+ * A still image, or a video fed by a player the CONSUMER owns.
+ *
+ * The video arm mounts a `VideoView` around the caller's `player`. Bloom never
+ * creates, replaces or releases that player — handing one player to a new view
+ * is what moves a playing video between surfaces without restarting it, and it
+ * is the reason this component takes a player object rather than a source URL.
+ */
+export const MediaSurface = memo(function MediaSurface({
+  content,
+  style,
+  contentFit = 'contain',
+  surfaceType = 'textureView',
+  nativeControls = false,
+  accessibilityLabel,
+  pointerEvents,
+  flightId,
+}: 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
+  // supports.
+  const [mountedSurfaceType] = useState(surfaceType);
+
+  // Both arms report the same fact — "there is a picture here now" — because the
+  // destination of a flight can be either, and a caller should not have to know
+  // which one it wired. expo-video raises `onFirstFrameRender` from `loadeddata`
+  // on web; expo-image raises `onLoad` once the source is decoded and displayed.
+  const reportLive = useCallback(() => {
+    if (flightId !== undefined) handOffFlight(flightId);
+  }, [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) {
+    // 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
+    // developer, once, in dev.
+    warnExpoVideoUnavailable();
+  }
+
+  return (
+    <Animated.View style={[styles.box, style]} pointerEvents={pointerEvents}>
+      {still === undefined ? null : (
+        // Behind the video (and the whole picture on the image arm), so the box
+        // is never empty while a first frame decodes and a flight that starts
+        // before playback still carries a picture. This is also why a flight
+        // never has to wait for a decode: an unpainted `<video>` sets no
+        // `poster` attribute and an Android TextureView runs with the ExoPlayer
+        // shutter off, so neither draws anything opaque over this.
+        <Image
+          source={{ uri: still }}
+          contentFit={contentFit}
+          style={StyleSheet.absoluteFill}
+          transition={0}
+          accessibilityLabel={accessibilityLabel}
+          // Only the arm that IS the picture reports being live. On the video
+          // arm the poster is scenery: handing off on it would release the
+          // flying surface while the destination still had no video.
+          onLoad={content.kind === 'video' ? undefined : reportLive}
+          {...webDraggableProps}
+        />
+      )}
+      {content.kind === 'video' && expoVideo !== null ? (
+        <expoVideo.VideoView
+          player={content.player}
+          contentFit={contentFit}
+          surfaceType={mountedSurfaceType}
+          nativeControls={nativeControls}
+          style={StyleSheet.absoluteFill}
+          accessibilityLabel={accessibilityLabel}
+          onFirstFrameRender={reportLive}
+        />
+      ) : null}
+    </Animated.View>
+  );
+});
+
+MediaSurface.displayName = 'MediaSurface';
+
+/**
+ * The STILL of a media item — a video's poster, or the image itself — and never
+ * a video view.
+ *
+ * This is what every surface that is not the live one renders: an off-screen
+ * gallery page, a thumbnail-strip tile, an origin placeholder while its media is
+ * in flight. Mounting a `MediaSurface` there instead would put a second
+ * `VideoView` on the same player, which is precisely what the "one live surface
+ * per id" contract forbids — and on a thumbnail strip it would mean one decoder
+ * per tile.
+ */
+export function MediaPoster({
+  content,
+  style,
+  contentFit = 'cover',
+  accessibilityLabel,
+}: {
+  content: MediaSurfaceContent;
+  style?: MediaPosterStyle;
+  contentFit?: 'contain' | 'cover';
+  accessibilityLabel?: string;
+}) {
+  const uri = content.kind === 'video' ? content.poster : content.uri;
+  if (uri === undefined) return <EmptyMediaSurface style={style} />;
+  return (
+    <Image
+      source={{ uri }}
+      contentFit={contentFit}
+      style={style}
+      transition={0}
+      accessibilityLabel={accessibilityLabel}
+      {...webDraggableProps}
+    />
+  );
+}
+
+/**
+ * A box with no media at all — what a gallery page renders for a video item
+ * whose poster is unknown, so the layout never collapses.
+ */
+export function EmptyMediaSurface({ style }: { style?: MediaPosterStyle }) {
+  return <View style={[styles.empty, style]} pointerEvents="none" />;
+}
+
+const styles = StyleSheet.create({
+  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`.
+    overflow: 'hidden',
+  },
+  empty: {
+    backgroundColor: 'rgba(255,255,255,0.08)',
+  },
+});

package/src/media-flight/constants.ts

@@ -0,0 +1,32 @@
+/**
+ * How long `flyTo` will wait for `<MediaFlightLayer>` to commit the surface
+ * before letting the caller carry on regardless (ms).
+ *
+ * The wait is a COMMIT, not a network round-trip: the surface only has to be
+ * mounted, because that is what puts it in expo-video's `_mountedVideos` set
+ * while the origin is still there — which is the whole mechanism that carries
+ * `currentTime` across. One React commit is a frame or two. Painting is a
+ * separate, slower thing that the poster covers (see `MediaSurface`), so it is
+ * deliberately NOT waited on here: blocking a tap on a decode would trade a
+ * problem nobody can see for one everybody can feel.
+ *
+ * The timeout exists for the case where no layer is mounted at all. Without it
+ * the promise never settles and the consumer never navigates — an app that
+ * forgot one line at its root would appear to have a dead feed.
+ */
+export const SURFACE_MOUNT_TIMEOUT_MS = 250;
+
+/*
+ * There is deliberately NO hand-off timeout.
+ *
+ * The obvious one — release the flying surface after N seconds if no destination
+ * ever claims it — would have to be wrong in one direction or the other, because
+ * the layer cannot tell "the destination failed" from "the caller meant the
+ * layer to keep painting this". And the failure it would guard against is not
+ * actually bad: a destination that never loads leaves the flying surface
+ * showing the video, playing, at exactly the rect the destination wanted, over a
+ * destination showing its poster. Going back calls `flyBack`, which releases it.
+ *
+ * `flyBack(id)` and `releaseFlight(id)` are the escape hatches, and they are
+ * the caller's to use.
+ */

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

@@ -0,0 +1,181 @@
+/**
+ * The optional-peer boundary for `expo-video`.
+ *
+ * Bloom ships no native code and never will, so `expo-video` cannot be a hard
+ * dependency: an app that renders no video must not be made to install a native
+ * module. It is therefore an OPTIONAL peer, and a static `import` contradicts
+ * that — Metro resolves every static import in the eager graph, so an omitted
+ * "optional" peer does not degrade, it aborts the whole bundle with `Unable to
+ * resolve module expo-video`, naming a package the app never mentions.
+ *
+ * The load has to be dynamic in the ONE shape Metro understands: a `require()`
+ * of a STRING LITERAL as a DIRECT STATEMENT of a `try` block, which Metro
+ * collects as an optional dependency (resolving the real module when installed,
+ * writing `null` into the dependency map when it is not, so the failure lands in
+ * the `catch` below at evaluation time instead of at build time). One `if` of
+ * nesting loses that — `isOptionalDependency` returns at the FIRST BlockStatement
+ * it meets — hence the `typeof require` guard sits OUTSIDE the try.
+ *
+ * `require` may also not exist at all (this file backs the `import` condition
+ * too, i.e. an ESM build under Node), hence that guard.
+ *
+ * A missing video module is invisible — a poster where a video should be looks
+ * exactly like a video that has not started — so {@link warnExpoVideoUnavailable}
+ * names the package once, in dev.
+ *
+ * @see connection-status/netinfo.ts — the same boundary for netinfo.
+ * @see hooks/haptics-module.ts — the same boundary for expo-haptics.
+ */
+import type { ComponentType } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * Declared locally rather than taken from the ambient `NodeRequire`, which
+ * returns `any`: `unknown` forces the module handle to be narrowed below instead
+ * of leaking an untyped value into the caller.
+ */
+declare const require: (moduleName: string) => unknown;
+
+/**
+ * The slice of `expo-video`'s `VideoPlayer` Bloom depends on.
+ *
+ * Hand-written rather than `typeof import('expo-video')` so no expo-video type
+ * reaches Bloom's emitted declarations — a consumer that skips the optional peer
+ * must not inherit a TS7016 from Bloom's own `.d.ts`. The two are kept in step by
+ * the assignability check in `__tests__/MediaFlight.test.tsx`, which is excluded
+ * from the build and so may name the real package.
+ *
+ * Bloom never CALLS any of this. **The consumer creates the player, owns it and
+ * destroys it**; Bloom only hands the object back to a `VideoView`, which is the
+ * whole mechanism that lets a video move between surfaces without restarting
+ * (expo-video's own docs: "when the same player is playing in multiple video
+ * views"). The three members below exist so the type is not `object` — a
+ * structural minimum the real `VideoPlayer` satisfies, and that an arbitrary
+ * object does not.
+ *
+ * `play`/`pause` are declared in METHOD syntax deliberately: `strictFunctionTypes`
+ * exempts method parameters from contravariance, which keeps a real
+ * `VideoPlayer` assignable here across `@types/react` copies.
+ */
+export interface VideoPlayerLike {
+  readonly playing: boolean;
+  play(): void;
+  pause(): void;
+}
+
+/** How a video is scaled inside its box. Mirrors expo-video's `VideoContentFit`. */
+export type VideoSurfaceContentFit = 'contain' | 'cover' | 'fill';
+
+/**
+ * Android's rendering surface for a video view.
+ *
+ * `textureView` is what Bloom asks for everywhere, because a `SurfaceView` is
+ * composited by the system OUTSIDE the app's view hierarchy: it ignores the
+ * parent's clip, corner radius and transform, so a video flying between two
+ * rects would paint as an un-rounded rectangle at the wrong place. It also
+ * cannot be changed at runtime (expo-video: "This prop should not be changed at
+ * runtime"), which is why {@link MediaSurfaceProps.surfaceType} is captured on
+ * first render.
+ */
+export type VideoSurfaceType = 'textureView' | 'surfaceView';
+
+/** The slice of `VideoViewProps` Bloom passes. */
+export interface VideoViewLikeProps {
+  player?: VideoPlayerLike | null;
+  contentFit?: VideoSurfaceContentFit;
+  surfaceType?: VideoSurfaceType;
+  nativeControls?: boolean;
+  style?: StyleProp<ViewStyle>;
+  pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+  accessibilityLabel?: string;
+  /**
+   * Raised once the mounted player has rendered its first frame into this view.
+   * On web expo-video raises it from the element's `loadeddata` event; it is the
+   * only OBSERVABLE "this surface is live now" the package offers, and the media
+   * flight layer's hand-off depends on it rather than on a timer.
+   */
+  onFirstFrameRender?: () => void;
+}
+
+/** The slice of expo-video's module surface Bloom renders. */
+export interface ExpoVideoLike {
+  VideoView: ComponentType<VideoViewLikeProps>;
+}
+
+/** `undefined` until the first load attempt, then the module or `null`. */
+let videoModule: ExpoVideoLike | null | undefined;
+/** Why the load failed, quoted verbatim in the dev warning. */
+let unavailableReason = '';
+let hasWarned = false;
+
+/** The expo-video module, or `null` when the optional peer is not installed. */
+export function loadExpoVideo(): ExpoVideoLike | null {
+  if (videoModule !== undefined) return videoModule;
+  videoModule = null;
+
+  // The `typeof require` guard sits OUTSIDE the try on purpose — see the header.
+  // Nested one `if`/`else` deeper, the require below is no longer a direct
+  // statement of the try block, Metro stops marking it optional, and an app
+  // without expo-video fails to BUILD instead of losing the video surface.
+  if (typeof require === 'undefined') {
+    unavailableReason = 'this bundle has no CommonJS `require`';
+    return videoModule;
+  }
+
+  try {
+    const loaded = require('expo-video') as
+      | (Partial<ExpoVideoLike> & { default?: Partial<ExpoVideoLike> })
+      | null
+      | undefined;
+    // `VideoView` is a class component upstream, so `typeof` is `'function'`
+    // either way; a memo/forwardRef build would be an object carrying
+    // `$$typeof`. Both are accepted, nothing else is.
+    const resolved = isComponentBearing(loaded) ? loaded : loaded?.default;
+
+    if (isComponentBearing(resolved)) {
+      videoModule = { VideoView: resolved.VideoView as ComponentType<VideoViewLikeProps> };
+    } else {
+      unavailableReason = 'the module resolved without a `VideoView` export';
+    }
+  } catch (error) {
+    unavailableReason = error instanceof Error ? error.message : String(error);
+  }
+
+  return videoModule;
+}
+
+function isComponentBearing(
+  candidate: (Partial<ExpoVideoLike> & { default?: unknown }) | null | undefined,
+): candidate is Partial<ExpoVideoLike> & { VideoView: ComponentType<VideoViewLikeProps> } {
+  const view = candidate?.VideoView;
+  if (typeof view === 'function') return true;
+  return typeof view === 'object' && view !== null && '$$typeof' in view;
+}
+
+/**
+ * One warning per module lifetime, and none in production — the same mechanism
+ * as `connection-status/netinfo.ts` and `hooks/haptics-module.ts`. Metro and
+ * Vite/Rolldown both fold the `NODE_ENV` check statically, so a production
+ * bundle keeps neither the branch nor the message.
+ */
+export function warnExpoVideoUnavailable(): void {
+  if (process.env.NODE_ENV === 'production' || hasWarned) return;
+  hasWarned = true;
+  // Internal Bloom diagnostic: only the consumer's package.json can fix this,
+  // so it names the package, the install command and what is lost.
+  // eslint-disable-next-line no-console
+  console.warn(
+    '[Bloom] A video media surface fell back to its poster: the optional peer ' +
+      '`expo-video` could not be loaded, so no video is rendered and the shared ' +
+      'media transition carries a still frame instead. Install it ' +
+      '(`npx expo install expo-video`) or pass image content only. ' +
+      `Reason: ${unavailableReason}`,
+  );
+}
+
+/** Test seam — drops the cached module handle so a suite can load it again. */
+export function resetExpoVideoModule(): void {
+  videoModule = undefined;
+  unavailableReason = '';
+  hasWarned = false;
+}

package/src/media-flight/index.ts

@@ -0,0 +1,33 @@
+export { MediaFlightLayer } from './MediaFlightLayer';
+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,
+  resetExpoVideoModule,
+  type ExpoVideoLike,
+  type VideoPlayerLike,
+  type VideoSurfaceContentFit,
+  type VideoSurfaceType,
+  type VideoViewLikeProps,
+} from './expo-video-module';
+export type {
+  MediaFlight,
+  MediaFlightAnchorNode,
+  MediaFlightController,
+  MediaFlightOptions,
+  MediaSurfaceContent,
+  MediaSurfaceImage,
+  MediaSurfaceVideo,
+  MeasuredRect,
+} from './types';
+export type { MediaSurfaceProps } from './MediaSurface';