@oxyhq/bloom 1.5.0 → 1.7.0

package/src/media-flight/index.ts

@@ -27,6 +27,9 @@ export type {
   MediaFlightAnchorNode,
   MediaFlightController,
   MediaFlightHostProps,
+  MediaSurfaceVideoOf,
+  MediaVideoSlot,
+  MediaVideoSlotProps,
   MediaFlightOptions,
   MediaSurfaceContent,
   MediaSurfaceImage,

package/src/media-flight/index.web.ts

@@ -36,6 +36,9 @@ export type {
   MediaFlightAnchorNode,
   MediaFlightController,
   MediaFlightHostProps,
+  MediaSurfaceVideoOf,
+  MediaVideoSlot,
+  MediaVideoSlotProps,
   MediaFlightOptions,
   MediaSurfaceContent,
   MediaSurfaceImage,

package/src/media-flight/media-node.web.ts

@@ -225,6 +225,47 @@ function pick(claims: readonly MediaNodeClaim[]): MediaNodeClaim | null {
   return best;
 }
 
+/**
+ * An element that can be MOVED rather than removed and re-inserted.
+ *
+ * `moveBefore` is newer than TypeScript's DOM library, so the capability is
+ * named here and checked at runtime rather than assumed.
+ */
+interface MovingParent {
+  moveBefore(node: Node, child: Node | null): void;
+}
+
+/**
+ * DERIVED FROM react-native-teleport 1.2.0 — `src/views/Portal/index.tsx`,
+ * its `moveElementTo`. MIT, Copyright (c) 2025 Kiryl Ziusko; see `NOTICE`.
+ *
+ * Changed: typed for TypeScript's DOM library, which does not know `moveBefore`
+ * yet, and reduced to the append case Bloom needs (no `before` sibling).
+ *
+ * Why it is worth taking rather than keeping `appendChild`: `appendChild` of an
+ * ATTACHED node is a remove followed by an insert, and the only reason media
+ * survives it is that HTML's removal steps await a stable state and abort if
+ * the node is back in a document by then. `moveBefore` does not run the removal
+ * steps at all — it is the state-preserving primitive, which matters for
+ * anything the abort does not cover: focus, `<iframe>`s, CSS animations.
+ *
+ * Measured for a playing `<video>` in Chrome 151: indistinguishable from
+ * `appendChild` (ct 0.60 -> 1.00, never paused, 6 frames, worst frame gap
+ * 100 ms — the clip's own cadence — under both), while a real removal pauses
+ * and freezes. So this is not a fix for a defect Bloom has; it is the correct
+ * primitive for the ones it does not have yet.
+ */
+function moveInto(parent: HTMLElement, child: HTMLElement): void {
+  if (supportsMoveBefore && child.parentNode !== null) {
+    (parent as unknown as MovingParent).moveBefore(child, null);
+    return;
+  }
+  parent.appendChild(child);
+}
+
+const supportsMoveBefore =
+  typeof Element !== 'undefined' && 'moveBefore' in Element.prototype;
+
 /**
  * Put the wrapper where its top claim says, in ONE synchronous move.
  *
@@ -237,7 +278,7 @@ function place(record: MediaNodeRecord): void {
   const target = topClaim(record)?.el ?? holder(reg);
   if (target === null) return;
   if (record.wrapper.parentElement === target) return;
-  target.appendChild(record.wrapper);
+  moveInto(target, record.wrapper);
 }
 
 function sameRender(a: MediaNodeRender, b: MediaNodeRender): boolean {

package/src/media-flight/types.ts

@@ -66,6 +66,19 @@ export interface MediaSurfaceVideo {
 /** What a media surface paints: a still image, or a consumer-owned video. */
 export type MediaSurfaceContent = MediaSurfaceImage | MediaSurfaceVideo;
 
+/**
+ * `MediaSurfaceVideo` carrying the consumer's OWN player type.
+ *
+ * Bloom transports that object; it never reads it. Narrowing it to
+ * `VideoPlayerLike` on the way through would be Bloom asserting something about
+ * cargo — and it would land on the consumer, who then has to cast the player
+ * back before handing it to expo-video's `VideoView`. A contract that pushes a
+ * consumer towards `as` ends up as an `as any` in someone's repo.
+ */
+export interface MediaSurfaceVideoOf<P extends VideoPlayerLike> extends MediaSurfaceVideo {
+  player: P;
+}
+
 /**
  * A media surface currently owned by the flight layer.
  *
@@ -233,7 +246,7 @@ export interface MediaFlightController {
  * 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 {
+export interface MediaVideoSlotProps<P extends VideoPlayerLike = VideoPlayerLike> {
   /**
    * The player Bloom was given — never one Bloom created.
    *
@@ -244,7 +257,7 @@ export interface MediaVideoSlotProps {
    * anything else here — keeping the old player, unmounting instead — brings
    * that defect back. See `releaseFlight`.
    */
-  player: VideoPlayerLike | null;
+  player: P | null;
   /** Fills the box. Spread it — see above. */
   style: StyleProp<ViewStyle>;
   contentFit: 'contain' | 'cover';
@@ -267,7 +280,9 @@ export interface MediaVideoSlotProps {
  * 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;
+export type MediaVideoSlot<P extends VideoPlayerLike = VideoPlayerLike> = (
+  props: MediaVideoSlotProps<P>,
+) => ReactNode;
 
 /**
  * A place a media surface may live: the feed row it starts in, the fullscreen
@@ -279,11 +294,16 @@ export type MediaVideoSlot = (props: MediaVideoSlotProps) => ReactNode;
  * ever leaving the document. On native a host renders its media inline, which
  * is what it has always done and what the platform makes correct there.
  */
-export interface MediaFlightHostProps {
+export interface MediaFlightHostProps<P extends VideoPlayerLike = VideoPlayerLike> {
   /** The id this host shares with the flight and with the other end. */
   id: string;
-  /** What to paint: a still image, or a consumer-owned expo-video player. */
-  content: MediaSurfaceContent;
+  /**
+   * What to paint: a still image, or a consumer-owned expo-video player.
+   *
+   * The player's own type flows from here into {@link renderVideo}, so a slot
+   * gets back exactly what it put in and hands it to `VideoView` with no cast.
+   */
+  content: MediaSurfaceImage | MediaSurfaceVideoOf<P>;
   /** Style of the host BOX. Give it the radius and `overflow: 'hidden'` you want. */
   style?: StyleProp<ViewStyle>;
   /** How the media fills the box. Defaults to `'cover'`. */
@@ -292,7 +312,7 @@ export interface MediaFlightHostProps {
    * Paint the video yourself, keeping your own `ref` and expo-video props. See
    * {@link MediaVideoSlot}; memoise it.
    */
-  renderVideo?: MediaVideoSlot;
+  renderVideo?: MediaVideoSlot<P>;
   /** Whether the video arm shows expo-video's own controls. Defaults to `false`. */
   nativeControls?: boolean;
   accessibilityLabel?: string;