@oxyhq/bloom 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.3.0",
+  "version": "1.5.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';
@@ -39,6 +37,7 @@ import { StyleSheet, type View } from 'react-native';
 import { createPortal } from 'react-dom';
 import Animated, { interpolate, useAnimatedStyle } from 'react-native-reanimated';
 
+import { SLOT_FILL_TOLERANCE_PX } from './constants';
 import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { MediaSurface, type MediaSurfaceStyle } from './MediaSurface';
@@ -48,7 +47,6 @@ import {
   getMediaNodes,
   releaseMediaNode,
   subscribeToMediaNodes,
-  type MediaNodeRender,
   type MediaNodeView,
 } from './media-node.web';
 import { getFlights, notifySurfaceMounted, subscribeToFlights } from './store';
@@ -91,11 +89,28 @@ 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;
+
+  // DOES THE MEDIA ACTUALLY FILL ITS BOX?
+  //
+  // Bloom hands a `renderVideo` slot a style that sizes a replaced element, and
+  // a slot that forgets to spread it paints a 300x150 `<video>` inside whatever
+  // box it was given — correct in every other respect, wrong on screen, and
+  // reported by nothing. That defect shipped once from Bloom's own view and
+  // cost a day to find; a consumer writing the slot can reproduce it in a line.
+  //
+  // Measured one frame after the commit, because layout has to have happened.
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production' || renderVideo === undefined) return undefined;
+    const frame = requestAnimationFrame(() => warnIfNotFilling(node.wrapper));
+    return () => cancelAnimationFrame(frame);
+  }, [node.wrapper, renderVideo]);
+
   return createPortal(
     <MediaSurface
       content={content}
       contentFit={contentFit}
+      renderVideo={renderVideo}
       nativeControls={nativeControls}
       accessibilityLabel={accessibilityLabel}
       flightId={flightId}
@@ -105,6 +120,37 @@ function SharedMediaNode({ node }: { node: MediaNodeView }) {
   );
 }
 
+let hasWarnedAboutFill = false;
+
+/**
+ * One warning per module lifetime, and none in production — same mechanism as
+ * `warnExpoVideoUnavailable`.
+ *
+ * It compares the media element with the WRAPPER, not with a fixed size: the
+ * invariant is "the media fills the box it was given", and a box that happens
+ * to be 300x150 is not a defect.
+ */
+function warnIfNotFilling(wrapper: HTMLElement): void {
+  if (hasWarnedAboutFill || !wrapper.isConnected) return;
+  const media = wrapper.querySelector('video');
+  if (media === null) return;
+  const box = wrapper.getBoundingClientRect();
+  const painted = media.getBoundingClientRect();
+  if (box.width === 0 || box.height === 0) return;
+  const off =
+    Math.abs(painted.width - box.width) > SLOT_FILL_TOLERANCE_PX ||
+    Math.abs(painted.height - box.height) > SLOT_FILL_TOLERANCE_PX;
+  if (!off) return;
+  hasWarnedAboutFill = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[Bloom] A \`renderVideo\` element is ${Math.round(painted.width)}x${Math.round(painted.height)} ` +
+      `inside a ${Math.round(box.width)}x${Math.round(box.height)} box. A DOM \`<video>\` is a ` +
+      'REPLACED element: without an explicit size it paints at its intrinsic 300x150 whatever ' +
+      'its inset says. Spread the `style` Bloom passes the slot.',
+  );
+}
+
 /**
  * One flying surface. See `MediaFlightLayer.tsx` for why the size is animated
  * rather than scaled.
@@ -137,21 +183,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 +212,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

@@ -13,7 +13,7 @@
  * 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 { memo, useCallback, useEffect, useRef, useState, type ComponentProps } from 'react';
 import {
   Platform,
   StyleSheet,
@@ -25,8 +25,9 @@ import {
 import { Image } from 'expo-image';
 import Animated from 'react-native-reanimated';
 
+import { SLOT_IDENTITY_CHURN_LIMIT } from './constants';
 import { handOffFlight } from './store';
-import type { MediaSurfaceContent } from './types';
+import type { MediaSurfaceContent, MediaVideoSlot } from './types';
 import {
   loadExpoVideo,
   warnExpoVideoUnavailable,
@@ -70,6 +71,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;
@@ -107,7 +116,10 @@ export interface MediaSurfaceProps {
    * 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`.
+   * it installed. See `releaseFlight`, and
+   * `scripts/probe-expo-video-listener-leak.mjs`, which measures that in real
+   * Chrome against expo-video's real class — including that grafting the
+   * missing `_removeListeners` into it makes the leak go away.
    */
   detached?: boolean;
 }
@@ -125,6 +137,7 @@ export const MediaSurface = memo(function MediaSurface({
   style,
   contentFit = 'contain',
   surfaceType = 'textureView',
+  renderVideo,
   nativeControls = false,
   accessibilityLabel,
   pointerEvents,
@@ -136,6 +149,18 @@ export const MediaSurface = memo(function MediaSurface({
   // supports.
   const [mountedSurfaceType] = useState(surfaceType);
 
+  // A slot rebuilt on every render republishes this surface to the layer on
+  // every render, which nothing at runtime reports — the picture is correct and
+  // the app is doing work in proportion to how often its rows re-render. The
+  // counter lives in an effect rather than in render: a render-phase ref write
+  // makes the React Compiler bail on the whole component.
+  const slotChurn = useRef(0);
+  useEffect(() => {
+    if (renderVideo === undefined) return;
+    slotChurn.current += 1;
+    if (slotChurn.current === SLOT_IDENTITY_CHURN_LIMIT) warnSlotNotMemoised();
+  }, [renderVideo]);
+
   // 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`
@@ -145,10 +170,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 +205,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}
@@ -205,6 +241,24 @@ export const MediaSurface = memo(function MediaSurface({
 
 MediaSurface.displayName = 'MediaSurface';
 
+let hasWarnedAboutSlotChurn = false;
+
+/**
+ * One warning per module lifetime, and none in production — same mechanism as
+ * `warnExpoVideoUnavailable`.
+ */
+function warnSlotNotMemoised(): void {
+  if (process.env.NODE_ENV === 'production' || hasWarnedAboutSlotChurn) return;
+  hasWarnedAboutSlotChurn = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[Bloom] A \`renderVideo\` slot changed identity ${SLOT_IDENTITY_CHURN_LIMIT} times. ` +
+      'It is part of what a media host publishes to the flight layer and is compared by ' +
+      'identity, so a slot rebuilt on every render republishes the surface on every render. ' +
+      'Wrap it in `useCallback` with the props it actually reads.',
+  );
+}
+
 /**
  * The STILL of a media item — a video's poster, or the image itself — and never
  * a video view.

package/src/media-flight/constants.ts

@@ -30,3 +30,25 @@ export const SURFACE_MOUNT_TIMEOUT_MS = 250;
  * `flyBack(id)` and `releaseFlight(id)` are the escape hatches, and they are
  * the caller's to use.
  */
+
+/**
+ * How many times a video slot may change identity before Bloom says so.
+ *
+ * `renderVideo` is part of what a host publishes to the layer and is compared
+ * by identity, so an unmemoised slot republishes on every render of the row it
+ * lives in — silently, and only under load. Five is well past any legitimate
+ * cause (a mute toggle, a fit change) and far below the churn of a slot rebuilt
+ * per render in a scrolling feed.
+ */
+export const SLOT_IDENTITY_CHURN_LIMIT = 5;
+
+/**
+ * How far a media element may sit from the box it is supposed to fill, in px,
+ * before Bloom says so.
+ *
+ * Two, not zero: subpixel layout and a box mid-animation both land within a
+ * pixel, and the defect this catches is not subtle — a `<video>` that never
+ * received Bloom's sizing style paints at its intrinsic 300x150 inside whatever
+ * box it was given.
+ */
+export const SLOT_FILL_TOLERANCE_PX = 2;

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/store.ts

@@ -432,7 +432,10 @@ export function flyBack(id: string): void {
  *
  * DO NOT replace this with a direct `unmountVideoView` call. It looks
  * equivalent, it is the half that does not matter, and the fix would disappear
- * silently. `MediaFlight.test.tsx` makes that substitution its control.
+ * silently. `MediaFlight.test.tsx` makes that substitution its control, and
+ * `scripts/probe-expo-video-listener-leak.mjs` measures the upstream defect
+ * this steps around — run it before touching any of this. The day it prints
+ * LEAK GONE, this commit and the tests that pin it can go.
  *
  * The cost is one frame in which the outgoing surface shows its poster instead
  * of video. It is already on its way out and the destination is live by then —

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;