@oxyhq/bloom 1.1.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
@@ -577,18 +577,46 @@
         "default": "./lib/commonjs/media-inset-border/index.js"
       }
     },
+    "./zoomable-media-gallery": {
+      "react-native": {
+        "types": "./lib/typescript/module/zoomable-media-gallery/index.d.ts",
+        "default": "./src/zoomable-media-gallery/index.ts"
+      },
+      "import": {
+        "types": "./lib/typescript/module/zoomable-media-gallery/index.d.ts",
+        "default": "./lib/module/zoomable-media-gallery/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/zoomable-media-gallery/index.d.ts",
+        "default": "./lib/commonjs/zoomable-media-gallery/index.js"
+      }
+    },
     "./zoomable-image-gallery": {
       "react-native": {
-        "types": "./lib/typescript/module/zoomable-image-gallery/index.d.ts",
-        "default": "./src/zoomable-image-gallery/index.ts"
+        "types": "./lib/typescript/module/zoomable-media-gallery/index.d.ts",
+        "default": "./src/zoomable-media-gallery/index.ts"
+      },
+      "import": {
+        "types": "./lib/typescript/module/zoomable-media-gallery/index.d.ts",
+        "default": "./lib/module/zoomable-media-gallery/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/zoomable-media-gallery/index.d.ts",
+        "default": "./lib/commonjs/zoomable-media-gallery/index.js"
+      }
+    },
+    "./media-flight": {
+      "react-native": {
+        "types": "./lib/typescript/module/media-flight/index.d.ts",
+        "default": "./src/media-flight/index.ts"
       },
       "import": {
-        "types": "./lib/typescript/module/zoomable-image-gallery/index.d.ts",
-        "default": "./lib/module/zoomable-image-gallery/index.js"
+        "types": "./lib/typescript/module/media-flight/index.d.ts",
+        "default": "./lib/module/media-flight/index.js"
       },
       "require": {
-        "types": "./lib/typescript/commonjs/zoomable-image-gallery/index.d.ts",
-        "default": "./lib/commonjs/zoomable-image-gallery/index.js"
+        "types": "./lib/typescript/commonjs/media-flight/index.d.ts",
+        "default": "./lib/commonjs/media-flight/index.js"
       }
     },
     "./pressable-scale": {
@@ -1498,8 +1526,9 @@
     "generate:tokens-json": "bun scripts/generate-design-tokens-json.ts",
     "prebuild": "node scripts/generate-platform-exports.mjs && bun scripts/generate-theme-css.ts && bun scripts/generate-design-tokens-json.ts",
     "build": "bob build",
-    "postbuild": "node scripts/verify-package.mjs",
+    "postbuild": "node scripts/verify-package.mjs && node scripts/verify-build-freshness.mjs --worktree",
     "verify:package": "node scripts/verify-package.mjs",
+    "verify:build-freshness": "node scripts/verify-build-freshness.mjs --worktree",
     "verify:consumer-types": "node scripts/verify-consumer-typecheck.mjs",
     "test": "jest",
     "typescript": "tsc --noEmit && node scripts/verify-consumer-typecheck.mjs",
@@ -1544,6 +1573,7 @@
     "expo-image": "~56.0.11",
     "expo-router": "^56.0.0",
     "expo-symbols": "~56.0.6",
+    "expo-video": "~57.0.2",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.4.1",
     "react": "19.2.0",
@@ -1576,6 +1606,7 @@
     "expo-image": "*",
     "expo-router": ">=3.0.0",
     "expo-symbols": ">=0.4.5",
+    "expo-video": "*",
     "nativewind": ">=5.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
@@ -1603,6 +1634,9 @@
     "expo-router": {
       "optional": true
     },
+    "expo-video": {
+      "optional": true
+    },
     "nativewind": {
       "optional": true
     },

package/src/image-aspect-ratio-cache/aspect-ratio-cache.ts

@@ -3,7 +3,7 @@
  * the image source URI.
  *
  * Intended for a thumbnail renderer and a fullscreen viewer (e.g.
- * `@oxyhq/bloom/zoomable-image-gallery`) sharing the SAME image URI to read
+ * `@oxyhq/bloom/zoomable-media-gallery`) sharing the SAME image URI to read
  * from and write to this one map, so an image already resolved as a thumbnail
  * has its ratio on hand when it opens "big" — no second cache, no duplicate
  * `Image.getSize` round-trip on the hot path. If the two surfaces render

package/src/index.ts

@@ -17,7 +17,8 @@
 //         `ScrollRestorationProvider` itself. `theme/adaptive-colors.ts` also
 //         names expo-router, but through the optional-`require` boundary, which
 //         links nothing.
-//       · `./zoomable-image-gallery` — statically imports `expo-image`.
+//       · `./zoomable-media-gallery` and `./media-flight` — both reach
+//         `expo-image` through the shared `media-flight/MediaSurface`.
 //     Gate: `src/__tests__/root-barrel-graph.test.ts`.
 //
 //  2. Its exports are generic, collision-prone names. Those come in as a

package/src/index.web.ts

@@ -22,7 +22,8 @@
 //         `ScrollRestorationProvider` itself. `theme/adaptive-colors.ts` also
 //         names expo-router, but through the optional-`require` boundary, which
 //         links nothing.
-//       · `./zoomable-image-gallery` — statically imports `expo-image`.
+//       · `./zoomable-media-gallery` and `./media-flight` — both reach
+//         `expo-image` through the shared `media-flight/MediaSurface`.
 //     Gate: `src/__tests__/root-barrel-graph.test.ts`.
 //
 //  2. Its exports are generic, collision-prone names. Those come in as a

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,251 @@
+/**
+ * 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}
+          // `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}
+        />
+      ) : 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({
+  /**
+   * 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`.
+    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.
+ */