@oxyhq/bloom 1.2.1 → 1.3.0

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

@@ -0,0 +1,335 @@
+/**
+ * ONE DOM node per media id, for its whole life.
+ *
+ * ## Why this exists
+ *
+ * expo-video's web player keeps a SET of mounted `<video>` elements and keeps
+ * them in step: `mountVideoView` adds an element and then copies play state and
+ * `currentTime` onto it from `[...set][0]`, and `_addListeners` gives every
+ * element an `onpause` that pauses all the OTHERS. `unmountVideoView` deletes
+ * the element from the set and nothing more — the handlers it installed are
+ * never removed by anything in the package.
+ *
+ * So an element on its way out still governs the player. The browser pauses a
+ * `<video>` the moment it leaves the document, that pause runs the dead
+ * element's handler, and the handler stops the element the viewer is watching.
+ *
+ * Measured against the real `VideoPlayerWeb` (expo-video 57.0.2), across every
+ * topology a consumer can produce on one shared player:
+ *
+ * ```
+ * origin dies BEFORE the destination mounts   ct=0      playing   (restarts)
+ * origin dies AFTER  the destination mounts   ct=4.28   paused    (freezes)
+ * one element, re-parented                    ct=4.28   playing
+ * ```
+ *
+ * TWO ELEMENTS GIVE THE POSITION OR THE PLAYBACK, NEVER BOTH. That is not a
+ * property of the flight layer — the first two rows have no Bloom surface in
+ * them at all — it is a property of two elements sharing one player. The only
+ * topology that gives both is one element that is never unmounted and never
+ * removed from the document.
+ *
+ * ## How a node survives its host
+ *
+ * A `<video>` React renders belongs to React: when the host unmounts, React
+ * removes it, and if anything has moved it in the meantime React's
+ * `parent.removeChild(node)` throws. So the node cannot be owned by either end.
+ *
+ * Instead Bloom creates a WRAPPER outside React (`document.createElement`) and
+ * the layer renders the media into it with `createPortal`. A portal's container
+ * is not part of React's tree — React reconciles the media against the wrapper
+ * and never against the document — so moving the wrapper between hosts with
+ * `appendChild` is invisible to React. The container's IDENTITY never changes,
+ * which is the whole trick: `createPortal` to a container that CHANGES unmounts
+ * and remounts, which is exactly what we are avoiding.
+ *
+ * And a synchronous move does not pause the video. HTML's removal steps for a
+ * media element await a stable state and then abort if the element is back in a
+ * document — so `appendChild` from one parent to another is not a removal as
+ * far as playback is concerned. (This is why re-parenting a `<video>` works and
+ * re-parenting an `<iframe>` does not: an iframe reloads.)
+ *
+ * ## Claims
+ *
+ * Hosts do not move the node themselves; they CLAIM the id and the registry
+ * decides. A flight outranks a host, so the layer keeps the node for the whole
+ * leg even though the destination has already mounted and claimed it — and the
+ * frame the flight lets go is the frame the destination takes it, with no gap
+ * and no second element. With no claim at all the node parks in a holder that
+ * is attached to the document but invisible, because a parked node that was
+ * DETACHED would pause.
+ */
+import { hasFlight } from './store';
+import type { MediaSurfaceContent } from './types';
+
+/** What the layer paints into a shared node, as its current holder wants it. */
+export interface MediaNodeRender {
+  content: MediaSurfaceContent;
+  contentFit: 'contain' | 'cover';
+  nativeControls: boolean;
+  accessibilityLabel: string | undefined;
+  /** Forwarded to the media, so a consumer keeps its own first-frame signal. */
+  flightId: string | undefined;
+}
+
+/** A flight outranks a host: the layer holds the node until the leg ends. */
+export const HOST_RANK = 0;
+export const FLIGHT_RANK = 1;
+
+interface MediaNodeClaim {
+  el: HTMLElement;
+  rank: number;
+  /** Registration order, so the most recent host wins among equals. */
+  seq: number;
+  render: MediaNodeRender;
+}
+
+interface MediaNodeRecord {
+  wrapper: HTMLDivElement;
+  claims: MediaNodeClaim[];
+  /**
+   * How the media is painted right now: the top claim's, or — while the node is
+   * PARKED between hosts — the last claim's.
+   *
+   * Parking has to keep painting. A node the layer stopped rendering would lose
+   * its element to React, which is the removal this whole module exists to
+   * avoid, and it would lose it exactly in the gap between the origin
+   * unmounting and the destination mounting: the moment of the flight.
+   */
+  render: MediaNodeRender;
+}
+
+/** What the layer needs in order to paint one shared node. */
+export interface MediaNodeView {
+  id: string;
+  wrapper: HTMLDivElement;
+  render: MediaNodeRender;
+}
+
+interface NodeRegistry {
+  nodes: Map<string, MediaNodeRecord>;
+  listeners: Set<() => void>;
+  /** Cached for `useSyncExternalStore`, which compares snapshots by identity. */
+  snapshot: readonly MediaNodeView[];
+  holder: HTMLElement | null;
+  seq: number;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __oxyhq_bloom_media_nodes__: NodeRegistry | undefined;
+}
+
+function registry(): NodeRegistry {
+  globalThis.__oxyhq_bloom_media_nodes__ ??= {
+    nodes: new Map(),
+    listeners: new Set(),
+    snapshot: [],
+    holder: null,
+    seq: 0,
+  };
+  return globalThis.__oxyhq_bloom_media_nodes__;
+}
+
+/** Where a node with no holder waits: in the document, and not on screen. */
+const HOLDER_ID = 'bloom-media-holder';
+
+function holder(reg: NodeRegistry): HTMLElement | null {
+  if (typeof document === 'undefined') return null;
+  if (reg.holder !== null && reg.holder.isConnected) return reg.holder;
+  const existing = document.getElementById(HOLDER_ID);
+  if (existing !== null) {
+    reg.holder = existing;
+    return existing;
+  }
+  const created = document.createElement('div');
+  created.id = HOLDER_ID;
+  // Attached, so nothing pauses; 1x1 and transparent, so nothing shows. NOT
+  // `display: none` — a video in a `display: none` subtree keeps playing in
+  // every browser that matters, but it also stops presenting frames, and the
+  // point of parking is that the media survives untouched.
+  created.style.cssText =
+    'position:fixed;top:0;left:0;width:1px;height:1px;overflow:hidden;opacity:0;pointer-events:none;';
+  created.setAttribute('aria-hidden', 'true');
+  document.body.appendChild(created);
+  reg.holder = created;
+  return created;
+}
+
+function makeWrapper(): HTMLDivElement {
+  const wrapper = document.createElement('div');
+  // Fills whichever box currently hosts it. `pointer-events: auto` is explicit
+  // and load-bearing: a host may sit inside a `pointer-events: none` layer (a
+  // poster overlay, a flying surface), and the media inside this wrapper is
+  // the one thing in there that a viewer may need to press.
+  wrapper.style.cssText =
+    'position:absolute;top:0;left:0;right:0;bottom:0;pointer-events:auto;';
+  wrapper.setAttribute('data-bloom-media-node', '');
+  return wrapper;
+}
+
+function recordFor(id: string, render: MediaNodeRender): MediaNodeRecord {
+  const reg = registry();
+  let record = reg.nodes.get(id);
+  if (!record) {
+    record = { wrapper: makeWrapper(), claims: [], render };
+    reg.nodes.set(id, record);
+  }
+  return record;
+}
+
+/** The claim that currently holds the node: highest rank, then most recent. */
+function topClaim(record: MediaNodeRecord): MediaNodeClaim | null {
+  let best: MediaNodeClaim | null = null;
+  for (const claim of record.claims) {
+    if (best === null || claim.rank > best.rank || (claim.rank === best.rank && claim.seq > best.seq)) {
+      best = claim;
+    }
+  }
+  return best;
+}
+
+/**
+ * Put the wrapper where its top claim says, in ONE synchronous move.
+ *
+ * The `parentElement` check is not an optimisation: re-appending to the same
+ * parent is a remove-then-insert, and doing that per render would put the media
+ * through the removal path it exists to avoid.
+ */
+function place(record: MediaNodeRecord): void {
+  const reg = registry();
+  const target = topClaim(record)?.el ?? holder(reg);
+  if (target === null) return;
+  if (record.wrapper.parentElement === target) return;
+  target.appendChild(record.wrapper);
+}
+
+function sameRender(a: MediaNodeRender, b: MediaNodeRender): boolean {
+  if (a.contentFit !== b.contentFit) return false;
+  if (a.nativeControls !== b.nativeControls) return false;
+  if (a.accessibilityLabel !== b.accessibilityLabel) return false;
+  if (a.flightId !== b.flightId) return false;
+  const x = a.content;
+  const y = b.content;
+  if (x.kind !== y.kind) return false;
+  if (x.kind === 'video' && y.kind === 'video') {
+    return x.player === y.player && x.poster === y.poster;
+  }
+  return x.kind !== 'video' && y.kind !== 'video' && x.uri === y.uri;
+}
+
+function publish(reg: NodeRegistry): void {
+  const next: MediaNodeView[] = [];
+  for (const [id, record] of reg.nodes) {
+    record.render = topClaim(record)?.render ?? record.render;
+    next.push({ id, wrapper: record.wrapper, render: record.render });
+  }
+  const previous = reg.snapshot;
+  const unchanged =
+    previous.length === next.length &&
+    previous.every((view, i) => {
+      const candidate = next[i];
+      return (
+        candidate !== undefined &&
+        candidate.id === view.id &&
+        candidate.wrapper === view.wrapper &&
+        sameRender(candidate.render, view.render)
+      );
+    });
+  // Identity is the signal `useSyncExternalStore` reads. Publishing a fresh
+  // array for an unchanged set renders the layer forever.
+  if (unchanged) {
+    for (const listener of reg.listeners) listener();
+    return;
+  }
+  reg.snapshot = next;
+  for (const listener of reg.listeners) listener();
+}
+
+/**
+ * Claim the shared node for `id` into `el`.
+ *
+ * Idempotent for an unchanged claim: called from a layout effect on every
+ * render, it moves the node once and publishes nothing afterwards.
+ */
+export function claimMediaNode(
+  id: string,
+  el: HTMLElement,
+  rank: number,
+  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;
+    }
+    existing.render = render;
+  } else {
+    reg.seq += 1;
+    record.claims.push({ el, rank, seq: reg.seq, render });
+  }
+  place(record);
+  publish(reg);
+}
+
+/**
+ * Drop a claim. The node goes to the next claim, or parks — or is DISPOSED, if
+ * nothing is going to want it back.
+ *
+ * "Nothing is going to want it back" is a fact the registry can read rather
+ * than a timeout it has to guess: no claim left AND no flight live for this id.
+ * During a navigation there IS a flight live — that is what a flight IS — so
+ * the node survives the gap between the origin unmounting and the destination
+ * mounting. Without a flight, an unmounted host is just a host that went away.
+ */
+export function releaseMediaNode(id: string, el: HTMLElement, rank: number): void {
+  const reg = registry();
+  const record = reg.nodes.get(id);
+  if (record === undefined) return;
+  const before = record.claims.length;
+  record.claims = record.claims.filter((claim) => !(claim.el === el && claim.rank === rank));
+  if (record.claims.length === before) return;
+  if (record.claims.length === 0 && !hasFlight(id)) {
+    reg.nodes.delete(id);
+    record.wrapper.remove();
+    publish(reg);
+    return;
+  }
+  place(record);
+  publish(reg);
+}
+
+/** Whether anything holds a shared node for this id. */
+export function hasMediaNode(id: string): boolean {
+  const record = registry().nodes.get(id);
+  return record !== undefined && record.claims.length > 0;
+}
+
+/** Subscribe to the shared-node set. The layer's `useSyncExternalStore` half. */
+export function subscribeToMediaNodes(listener: () => void): () => void {
+  const reg = registry();
+  reg.listeners.add(listener);
+  return () => {
+    reg.listeners.delete(listener);
+  };
+}
+
+/** Every shared node that something is currently holding. Stable identity. */
+export function getMediaNodes(): readonly MediaNodeView[] {
+  return registry().snapshot;
+}
+
+/** Test seam: drop every node and take its wrapper out of the document. */
+export function resetMediaNodes(): void {
+  const reg = registry();
+  for (const record of reg.nodes.values()) record.wrapper.remove();
+  reg.nodes.clear();
+  reg.snapshot = [];
+  if (reg.holder !== null) {
+    reg.holder.remove();
+    reg.holder = null;
+  }
+  for (const listener of reg.listeners) listener();
+}

package/src/media-flight/store.ts

@@ -77,6 +77,8 @@ interface FlightStatus {
   /** Waiters on `flyTo`'s promise, resolved once `mounted` turns true. */
   mountWaiters: Array<() => void>;
   mountTimer: ReturnType<typeof setTimeout> | null;
+  /** Pending final removal while the surface unbinds from its player. */
+  unbindTimer: ReturnType<typeof setTimeout> | null;
 }
 
 interface Registry {
@@ -119,6 +121,7 @@ function statusFor(id: string): FlightStatus {
       handedOff: false,
       mountWaiters: [],
       mountTimer: null,
+      unbindTimer: null,
     };
     reg.status.set(id, status);
   }
@@ -127,7 +130,9 @@ function statusFor(id: string): FlightStatus {
 
 function clearTimers(status: FlightStatus): void {
   if (status.mountTimer !== null) clearTimeout(status.mountTimer);
+  if (status.unbindTimer !== null) clearTimeout(status.unbindTimer);
   status.mountTimer = null;
+  status.unbindTimer = null;
 }
 
 function resolveMountWaiters(status: FlightStatus): void {
@@ -263,6 +268,7 @@ export function flyTo(
       // silently ignored by the view it is meant to configure.
       surfaceType: existing.surfaceType,
       landing: false,
+      unbinding: false,
       generation: existing.generation + 1,
     };
     reg.flights.set(id, next);
@@ -285,6 +291,7 @@ export function flyTo(
     surfaceType: options?.surfaceType ?? 'textureView',
     progress: makeMutable(0),
     landing: false,
+    unbinding: false,
     generation: 0,
   };
   reg.flights.set(id, flight);
@@ -394,9 +401,62 @@ export function flyBack(id: string): void {
   });
 }
 
-/** Drop the surface for `id`. Called when a landing leg settles, and on teardown. */
+/**
+ * Drop the surface for `id`. Called when a landing leg settles, and on teardown.
+ *
+ * A VIDEO surface does not go straight out. It renders for one more commit with
+ * NO player first, because expo-video's web player mirrors pause across every
+ * element bound to it and a `<video>` removed from the DOM is auto-paused by the
+ * browser — while `unmountVideoView` only runs in a PASSIVE effect cleanup,
+ * i.e. after removal and after that auto-pause. So the dying element pauses the
+ * one the viewer is now watching. Measured: the reel's video paused 1 ms after
+ * the flying surface left the DOM, with `currentTime` still advancing and
+ * nobody having called `pause()`.
+ *
+ * Rendering `player={null}` for one commit runs expo-video's own `[props.player]`
+ * effect while the node is STILL in the DOM, and the operative part of that is
+ * NOT the unbind. `unmountVideoView` takes the element out of `_mountedVideos`
+ * and leaves the `onpause` handler `_addListeners` installed, so unbinding
+ * alone would still mirror. What saves it is the other half of the same
+ * branch: `removeAttribute('src'); load()` (`VideoView.web.js:206`). The media
+ * element load algorithm sets `paused` to true WITHOUT firing `pause`, so the
+ * element goes quiet, and its later removal fires nothing either because it is
+ * already paused.
+ *
+ * Measured in real Chrome, with controls: a playing element put through
+ * `removeAttribute('src') + load()` reports events `["play"]` and nothing more,
+ * while the same element paused by hand, or removed from the DOM while
+ * playing, reports `["play","pause"]`. Against real builds: without this commit
+ * the destination ends STOPPED (5/5), with it PLAYING (6/6) and the position
+ * carried.
+ *
+ * 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.
+ *
+ * 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 —
+ * `handOff` is what got us here — so that frame is covered.
+ */
 export function releaseFlight(id: string): void {
   const reg = registry();
+  const flight = reg.flights.get(id);
+
+  if (flight !== undefined && flight.content.kind === 'video' && !flight.unbinding) {
+    reg.flights.set(id, { ...flight, unbinding: true });
+    const unbinding = statusFor(id);
+    if (unbinding.unbindTimer === null) {
+      // After the commit AND expo-video's passive effect, which is the whole
+      // point — a microtask would run before either.
+      unbinding.unbindTimer = setTimeout(() => {
+        unbinding.unbindTimer = null;
+        releaseFlight(id);
+      }, 0);
+    }
+    publish(reg);
+    return;
+  }
+
   const status = reg.status.get(id);
   if (status) {
     // A waiter still parked on `flyTo`'s promise would otherwise hang until its

package/src/media-flight/types.ts

@@ -1,3 +1,4 @@
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
 
 import type { VideoPlayerLike, VideoSurfaceType } from './expo-video-module';
@@ -94,6 +95,19 @@ export interface MediaFlight {
    * settles, the surface is released instead of parked.
    */
   landing: boolean;
+  /**
+   * True for the ONE commit between "release requested" and the surface
+   * actually going away, during which a video surface renders with no player.
+   *
+   * expo-video's web player MIRRORS pause across every element bound to it
+   * (`VideoPlayer.web.js`: `video.onpause` pauses all the others), and a
+   * `<video>` removed from the DOM is auto-paused by the browser. Its
+   * `unmountVideoView` runs in a PASSIVE effect cleanup — after removal, after
+   * the auto-pause — so a dying element pauses the one the viewer is watching.
+   * Unbinding first takes this element out of `_mountedVideos` while it is
+   * still in the DOM, so its later pause reaches nobody.
+   */
+  unbinding: boolean;
   /** Bumped on every retarget, so React remounts nothing but the layer re-reads. */
   generation: number;
 }
@@ -208,3 +222,47 @@ export interface MediaFlightController {
    */
   progress: SharedValue<number>;
 }
+
+/**
+ * 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.
+ *
+ * A host DECLARES a box; it does not own the media. On web that distinction is
+ * the whole feature — the media is ONE DOM node the layer paints once and moves
+ * between hosts, so it survives the origin route unmounting mid-flight without
+ * 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 {
+  /** 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;
+  /** 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'`. */
+  contentFit?: 'contain' | 'cover';
+  /** Whether the video arm shows expo-video's own controls. Defaults to `false`. */
+  nativeControls?: boolean;
+  accessibilityLabel?: string;
+  /**
+   * Android's rendering surface for the video arm. See `MediaSurfaceProps`.
+   * Ignored on web, where there is no such choice.
+   */
+  surfaceType?: VideoSurfaceType;
+  /**
+   * Passed through as a PROP, never as a style key — react-native-web resolves
+   * `box-none`/`box-only` from the prop path only.
+   */
+  pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+  /**
+   * Set on a DESTINATION host, to the id its flight was started with, when the
+   * destination paints its media ITSELF rather than through the shared node —
+   * which on native is always. The web host does not need it: a flight there
+   * ends when the destination host claims the node, because by then the node it
+   * is claiming has been showing the media all along.
+   *
+   * Leave it unset on an origin host, which would otherwise hand off to itself.
+   */
+  flightId?: string;
+}