@oxyhq/bloom 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.3.0",
+  "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",

package/src/media-flight/MediaFlightHost.tsx

@@ -23,6 +23,7 @@ export function MediaFlightHost({
   content,
   style,
   contentFit = 'cover',
+  renderVideo,
   nativeControls = false,
   accessibilityLabel,
   surfaceType,
@@ -41,6 +42,7 @@ export function MediaFlightHost({
       <MediaSurface
         content={content}
         contentFit={contentFit}
+        renderVideo={renderVideo}
         nativeControls={nativeControls}
         accessibilityLabel={accessibilityLabel}
         surfaceType={surfaceType}

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

@@ -30,6 +30,7 @@ export function MediaFlightHost({
   content,
   style,
   contentFit = 'cover',
+  renderVideo,
   nativeControls = false,
   accessibilityLabel,
   pointerEvents,
@@ -48,8 +49,8 @@ export function MediaFlightHost({
   );
 
   const render = useMemo<MediaNodeRender>(
-    () => ({ content, contentFit, nativeControls, accessibilityLabel, flightId }),
-    [content, contentFit, nativeControls, accessibilityLabel, flightId],
+    () => ({ content, contentFit, renderVideo, nativeControls, accessibilityLabel, flightId }),
+    [content, contentFit, renderVideo, nativeControls, accessibilityLabel, flightId],
   );
   const renderRef = useRef(render);
 

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

@@ -30,8 +30,6 @@ import {
   useCallback,
   useEffect,
   useLayoutEffect,
-  useMemo,
-  useRef,
   useState,
   useSyncExternalStore,
 } from 'react';
@@ -48,7 +46,6 @@ import {
   getMediaNodes,
   releaseMediaNode,
   subscribeToMediaNodes,
-  type MediaNodeRender,
   type MediaNodeView,
 } from './media-node.web';
 import { getFlights, notifySurfaceMounted, subscribeToFlights } from './store';
@@ -91,11 +88,12 @@ 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;
+  const { content, contentFit, renderVideo, nativeControls, accessibilityLabel, flightId } = node.render;
   return createPortal(
     <MediaSurface
       content={content}
       contentFit={contentFit}
+      renderVideo={renderVideo}
       nativeControls={nativeControls}
       accessibilityLabel={accessibilityLabel}
       flightId={flightId}
@@ -137,21 +135,9 @@ function MediaFlightSurface({ flight, shared }: { flight: MediaFlight; shared: b
 
   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} />;
+  if (shared) return <FlyingSharedNode id={id} style={box} />;
 
   return (
     <MediaSurface
@@ -178,33 +164,19 @@ function MediaFlightSurface({ flight, shared }: { flight: MediaFlight; shared: b
  * 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;
-}) {
+function FlyingSharedNode({ id, style }: { id: string; style: MediaSurfaceStyle }) {
   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.
+  // 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, renderRef.current);
+    claimMediaNode(id, el, FLIGHT_RANK);
     return () => releaseMediaNode(id, el, FLIGHT_RANK);
   }, [id, node]);
 

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;
@@ -125,6 +133,7 @@ export const MediaSurface = memo(function MediaSurface({
   style,
   contentFit = 'contain',
   surfaceType = 'textureView',
+  renderVideo,
   nativeControls = false,
   accessibilityLabel,
   pointerEvents,
@@ -145,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
@@ -178,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/media-node.web.ts

@@ -60,12 +60,14 @@
  * DETACHED would pause.
  */
 import { hasFlight } from './store';
-import type { MediaSurfaceContent } from './types';
+import type { MediaSurfaceContent, MediaVideoSlot } from './types';
 
 /** What the layer paints into a shared node, as its current holder wants it. */
 export interface MediaNodeRender {
   content: MediaSurfaceContent;
   contentFit: 'contain' | 'cover';
+  /** The consumer's own video element, if it brought one. Compared by identity. */
+  renderVideo: MediaVideoSlot | undefined;
   nativeControls: boolean;
   accessibilityLabel: string | undefined;
   /** Forwarded to the media, so a consumer keeps its own first-frame signal. */
@@ -81,7 +83,19 @@ interface MediaNodeClaim {
   rank: number;
   /** Registration order, so the most recent host wins among equals. */
   seq: number;
-  render: MediaNodeRender;
+  /**
+   * What this claimant wants painted — or `undefined` for a claim that decides
+   * only WHERE the node lives.
+   *
+   * The flight is the second kind, and that distinction is load-bearing. A
+   * flight that published a render of its own would replace whatever the hosts
+   * were painting for the length of the leg, and if a consumer brought its own
+   * element (`renderVideo`) the flight would swap it out and back — two
+   * remounts, in the middle of the one operation whose entire purpose is that
+   * the element is never rebuilt. Measured: the consumer's `<video>` ended the
+   * flight as a different node, with the original left disconnected.
+   */
+  render: MediaNodeRender | undefined;
 }
 
 interface MediaNodeRecord {
@@ -168,20 +182,42 @@ function makeWrapper(): HTMLDivElement {
   return wrapper;
 }
 
-function recordFor(id: string, render: MediaNodeRender): MediaNodeRecord {
+function recordFor(id: string, render: MediaNodeRender | undefined): MediaNodeRecord {
   const reg = registry();
   let record = reg.nodes.get(id);
   if (!record) {
-    record = { wrapper: makeWrapper(), claims: [], render };
+    // A position-only claim can be the first one in: a flight can take off
+    // before the host it flies from has committed. `EMPTY_RENDER` paints
+    // nothing until a host says what, which is the honest state.
+    record = { wrapper: makeWrapper(), claims: [], render: render ?? EMPTY_RENDER };
     reg.nodes.set(id, record);
   }
   return record;
 }
 
+/** Nothing to paint yet. Replaced by the first host claim that arrives. */
+const EMPTY_RENDER: MediaNodeRender = {
+  content: { uri: '' },
+  contentFit: 'cover',
+  renderVideo: undefined,
+  nativeControls: false,
+  accessibilityLabel: undefined,
+  flightId: undefined,
+};
+
 /** The claim that currently holds the node: highest rank, then most recent. */
 function topClaim(record: MediaNodeRecord): MediaNodeClaim | null {
+  return pick(record.claims);
+}
+
+/** The highest-ranked claim that says what to PAINT. See `MediaNodeClaim.render`. */
+function topRender(record: MediaNodeRecord): MediaNodeClaim | null {
+  return pick(record.claims.filter((claim) => claim.render !== undefined));
+}
+
+function pick(claims: readonly MediaNodeClaim[]): MediaNodeClaim | null {
   let best: MediaNodeClaim | null = null;
-  for (const claim of record.claims) {
+  for (const claim of claims) {
     if (best === null || claim.rank > best.rank || (claim.rank === best.rank && claim.seq > best.seq)) {
       best = claim;
     }
@@ -206,6 +242,7 @@ function place(record: MediaNodeRecord): void {
 
 function sameRender(a: MediaNodeRender, b: MediaNodeRender): boolean {
   if (a.contentFit !== b.contentFit) return false;
+  if (a.renderVideo !== b.renderVideo) return false;
   if (a.nativeControls !== b.nativeControls) return false;
   if (a.accessibilityLabel !== b.accessibilityLabel) return false;
   if (a.flightId !== b.flightId) return false;
@@ -221,7 +258,7 @@ function sameRender(a: MediaNodeRender, b: MediaNodeRender): boolean {
 function publish(reg: NodeRegistry): void {
   const next: MediaNodeView[] = [];
   for (const [id, record] of reg.nodes) {
-    record.render = topClaim(record)?.render ?? record.render;
+    record.render = topRender(record)?.render ?? record.render;
     next.push({ id, wrapper: record.wrapper, render: record.render });
   }
   const previous = reg.snapshot;
@@ -256,15 +293,16 @@ export function claimMediaNode(
   id: string,
   el: HTMLElement,
   rank: number,
-  render: MediaNodeRender,
+  render?: MediaNodeRender,
 ): void {
   const reg = registry();
   const record = recordFor(id, render);
   const existing = record.claims.find((claim) => claim.el === el && claim.rank === rank);
   if (existing !== undefined) {
-    if (sameRender(existing.render, render) && record.wrapper.parentElement === topClaim(record)?.el) {
-      return;
-    }
+    const unchanged =
+      existing.render === render ||
+      (existing.render !== undefined && render !== undefined && sameRender(existing.render, render));
+    if (unchanged && record.wrapper.parentElement === topClaim(record)?.el) return;
     existing.render = render;
   } else {
     reg.seq += 1;

package/src/media-flight/types.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
 
@@ -223,6 +224,51 @@ 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.
@@ -242,6 +288,11 @@ export interface MediaFlightHostProps {
   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;