@oxyhq/bloom 1.0.6 → 1.2.0

package/docs/level-picker.mdx

@@ -0,0 +1,105 @@
+---
+title: LevelPicker
+description: A stepped level over a disclosure — the surface, not what the levels mean.
+order: 35
+---
+
+# LevelPicker
+
+A short, ordered scale picked on a rail, with a disclosure underneath that
+reveals the detail rows for whatever the scale is a summary of. It is the body
+of a menu panel: put it inside a `DropdownMenuContent` and give it rows.
+
+```tsx
+import { LevelPicker } from '@oxyhq/bloom/level-picker';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from '@oxyhq/bloom/dropdown-menu';
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild label="Quality">
+    <Button variant="ghost">{QUALITY[level]}</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end" className="w-[224px]">
+    <LevelPicker
+      accessibilityLabel="Quality"
+      levels={QUALITY}
+      value={level}
+      onValueChange={setLevel}
+      minLabel="Faster"
+      maxLabel="Sharper"
+      detailsLabel="Advanced">
+      <DropdownMenuSub>
+        <DropdownMenuSubTrigger>Format</DropdownMenuSubTrigger>
+        <DropdownMenuSubContent side="right" align="start">
+          …
+        </DropdownMenuSubContent>
+      </DropdownMenuSub>
+    </LevelPicker>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Which prop decides what
+
+| prop                                             | decides                                                        |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| `levels`                                         | how many stops there are, and what each is called               |
+| `value` / `onValueChange`                        | the selected stop, as an index — fully controlled               |
+| `accessibilityLabel`                             | what the level applies to. **Required**                         |
+| `minLabel` / `maxLabel`                          | the ends of the scale, shown while the rail is being worked     |
+| `detailsLabel`                                   | the disclosure row's text. Defaults to `Details`                |
+| `expanded` / `defaultExpanded` / `onExpandedChange` | whether the details are showing                              |
+| `children`                                       | the rows the disclosure reveals                                 |
+
+## `levels` is the whole scale
+
+The array's LENGTH is the number of stops — two, five, nine — and each entry is
+that stop's own name, announced as the slider's value. So a level is never a
+bare number to a screen reader:
+
+```tsx
+levels={['Draft', 'Standard', 'Fine', 'Very fine', 'Maximum']}
+value={1}   // "Standard"
+```
+
+There is no `min`, `max` or `step`: a level picker is for a scale short enough
+to name every position on. If yours is not, you want a
+[`Slider`](/docs/bloom/main/slider).
+
+## It owns the surface, not the meaning
+
+The picker knows the number of stops, their names, and that a disclosure reveals
+some rows. It knows nothing about what a stop selects or what the rows do —
+those are `children`, and they are ordinary menu rows. Keeping that line is what
+lets one component serve a quality scale, a privacy scale and a compression
+scale without learning about any of them.
+
+## Label it, and do not rely on the captions
+
+`minLabel` and `maxLabel` are captions on the SCALE ("Faster" → "Sharper"), and
+they are visible only while the rail is hovered, focused or being dragged.
+Neither is a name for the control: ARIA computes no name from a `slider`'s
+contents, and a caption beside one is a sibling. `accessibilityLabel` is
+required in the type for that reason.
+
+## Keyboard and pointer
+
+On web the rail is a focusable `role="slider"`: <kbd>←</kbd>/<kbd>→</kbd> (and
+<kbd>↑</kbd>/<kbd>↓</kbd>) step one level, <kbd>Home</kbd> and <kbd>End</kbd> go
+to the ends, and a drag holds pointer capture so it keeps steering past the end
+of the track. On native the same control is an `adjustable` with `increment` and
+`decrement` actions, driven by a `PanResponder`.
+
+## Both platforms, two layouts
+
+The picker is web-forked, and the reason is the details region: a sub-menu is a
+flyout on web and an INLINE disclosure on native, so the native fork measures
+the region on every layout instead of animating to a height it computed. Both
+forks read one set of stops, insets and colour roles, so the control is the same
+control — see `src/level-picker/constants.ts`.

package/docs/media-flight.mdx

@@ -0,0 +1,272 @@
+---
+title: MediaFlight
+description: A shared-element media transition that survives the route change — on web and on native.
+order: 75
+---
+
+# MediaFlight
+
+A picture — or a **playing video** — moves from where it is to where it is
+going, across a navigation, without restarting and without being re-downloaded.
+
+```tsx
+// app/_layout.tsx — mounted ONCE, at the root, above the router.
+import { MediaFlightLayer } from '@oxyhq/bloom/media-flight';
+
+<MediaFlightLayer />
+```
+
+```tsx
+// the origin: a feed thumbnail
+import { useMediaFlight } from '@oxyhq/bloom/media-flight';
+
+const flight = useMediaFlight();
+
+<Pressable
+  ref={(node) => flight.registerAnchor(mediaId, node)}
+  onPress={async () => {
+    const from = await flight.measureAnchor(mediaId);
+    // AWAIT, then navigate. Never the other way round — see below.
+    await flight.flyTo(mediaId, targetRect, { kind: 'video', player, poster }, { from: from ?? undefined });
+    router.push(`/videos?id=${mediaId}`);
+  }}
+>
+  {/* while it is in flight, render a HOLE here — never a second copy */}
+</Pressable>
+```
+
+```tsx
+// the destination: it says where it wants the surface, and takes it over by
+// reporting its own first frame. `flightId` is the entire wiring.
+<MediaSurface content={{ kind: 'video', player, poster }} flightId={mediaId} />
+```
+
+## The one rule: await `flyTo` before tearing the origin down
+
+expo-video's **web** player keeps a `Set` of mounted `<video>` elements and, on
+each new mount, copies `currentTime`, play state, volume, muted and rate from
+`[...set][0]`. If that set is EMPTY when the new element mounts it returns early
+and the element starts **at zero**.
+
+So the layer's surface has to enter the set while the origin's is still in it.
+On web, navigating unmounts the origin route — so navigating before the layer
+has committed is exactly the restart, and it is intermittent, because whether
+you win the race depends on a commit you do not control.
+
+`flyTo` returns a promise that resolves on that commit. Awaiting it is the whole
+contract, and it is the only ordering fact a consumer has to know — everything
+else is the layer's problem. It resolves on a short timeout when no
+`<MediaFlightLayer>` is mounted, so a missing root component degrades to "no
+transition" and warns once in dev, rather than leaving a feed whose videos
+cannot be opened.
+
+It does **not** wait for a decode. `MediaSurface` renders the poster BEHIND the
+video on both platforms, and neither an unpainted `<video>` (expo-video sets no
+`poster` attribute) nor an Android `TextureView` with the ExoPlayer shutter off
+draws anything opaque — so the still shows through until the first frame lands.
+Waiting for paint would trade an invisible problem for a laggy tap.
+
+## The poster must already be in the image cache
+
+`flyTo` resolves on the layer's COMMIT, not on its first painted pixel. That
+trade is only sound if committing is *effectively* painting — and whether it is
+depends entirely on one thing. Measured in Chrome, milliseconds from `flyTo`
+resolving to the flying surface having visible pixels:
+
+| the poster URI | ms |
+| --- | --- |
+| already rendered by the page (in the image cache) | **1–5** |
+| never requested before (same file, cache-busted) | **510–900** |
+
+So a **warm** poster makes the commit a frame, and a **cold** one opens a
+half-second hole exactly where the origin has just disappeared. Measured in a
+consuming app the hole was ~350 ms, framed by "the feed row stopped painting"
+and "the flight had not started".
+
+**The fix is not to make `flyTo` wait.** Waiting would move that half second in
+front of the user's tap, which is worse in the place people actually feel it.
+The fix is to make sure the origin has already painted the exact URI the flight
+will carry.
+
+<Callout variant="warning" title="expo-video does not fetch your poster">
+On web, expo-video's `VideoView` renders `<video src=…>` with **no `poster`
+attribute**. So a feed that shows video and passes a poster to the video view
+never actually requests that URL — and the flight is then the first thing that
+asks for it, at the worst possible moment. Render the still yourself under the
+video (`MediaPoster` is exported for exactly this), or prefetch it.
+</Callout>
+
+One-minute check: in the Network panel, does the poster request appear **when
+you tap**? If so, this is what you are looking at.
+
+`scripts/verify-media-flight.mjs` gates Bloom's half — that a warm surface
+presents within a frame or two, with no re-fetch and no fade. Its control flies
+a cold poster over a latency-throttled link, so "warm is fast" cannot be
+reported by a harness that always says zero.
+
+## The layer leaves when the DESTINATION is live, not when the animation ends
+
+Measured against production: opening a full-screen video route takes **~996 ms**
+(median, n=10) from tap to first presented frame — ~545 ms to mount the route,
+~380 ms to `loadedmetadata`, ~40 ms to the frame. A flight animation lasts about
+300 ms. Releasing the surface when the animation ends would therefore uncover a
+~700 ms hole *exactly* where the transition was supposed to hide one.
+
+So the release condition is an observable fact, not a clock: the destination's
+own first frame. Give the destination's `<MediaSurface>` a `flightId` and it
+reports that itself (expo-video's `onFirstFrameRender`, expo-image's `onLoad`).
+`flight.handOff(id)` is there for a destination that renders something else.
+
+Called mid-flight, a hand-off is remembered rather than obeyed — the surface
+finishes travelling first, or it would vanish between the two rects.
+
+**The success criterion is continuity, not speed.** With a shared player the
+frame is already on screen before the tap; the flight does not make the video
+appear sooner, it makes it never disappear. Measure "was there ever no frame?"
+and "did `currentTime` advance monotonically?", not time-to-first-frame.
+
+## Why this exists rather than `react-native-teleport`
+
+A shared-element transition normally assumes the origin screen is still mounted
+while the element travels. That is why `react-native-teleport` requires
+`presentation: 'transparentModal'`, and why it has no web story at all.
+
+Under expo-router on web the origin route is **unmounted** the moment the URL
+changes. Anything the origin was rendering — a `VideoView`, a decoded image —
+is gone before the first frame of the transition.
+
+So the surface is moved 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. The surface it
+paints belongs to neither route, so neither route can take it down. Origin and
+destination only **declare** where they want it; the layer is what paints it.
+
+## Why the layer does not own the surface at rest
+
+A tempting design is for the feed cell to render only an anchor and let the
+layer paint every video, so there is never a swap at all. It does not work, and
+the reason is not performance.
+
+The layer paints through the `Portal`, which is outside every `overflow: hidden`
+and every z-index in the app. A feed video painted there would render **over** a
+sticky header, over a sidebar, over any open sheet, and it would not be clipped
+by the feed column's own rounded corners. That is not a risk to be measured away
+— the layer would have to know the app's clip regions, which is exactly what it
+cannot know. It holds on web and on native alike.
+
+Covering the whole screen is correct for the ~300 ms of a transition and wrong
+for the rest of the time. So: the cell owns its surface at rest, the layer owns
+it during the flight, and the handshake above is what makes the two swaps
+invisible.
+
+## One live 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.
+
+Concretely:
+
+- `flyTo` on an id that is already flying **retargets** the same surface. It
+  never adds a second one, and the surface resumes from where it currently is
+  rather than snapping back to the original origin.
+- The origin and the destination must render a **hole** (or the poster still —
+  `MediaPoster` is exported for exactly that) while the surface is in the layer.
+  Two copies is what this exists to prevent.
+- `flyBack` measures the current anchor, lands there, and releases. With no
+  measurable anchor it releases immediately, because a flying copy held over a
+  destination that has already drawn its own media is the duplicate again.
+
+## The API
+
+| member                          | does                                                          |
+| ------------------------------- | ------------------------------------------------------------- |
+| `registerAnchor(id, node)`      | declares the host view that anchors `id`; `null` clears it     |
+| `measureAnchor(id)`             | that node's window rect, or `null` when it has none            |
+| `flyTo(id, rect, content, opts)`| takes the surface live and moves it to `rect`                  |
+| `flyBack(id)`                   | flies it to its anchor and releases it on landing              |
+| `progress`                      | `SharedValue<number>`, 0 → 1 for the most recent leg           |
+
+The most recently registered node for an id **is** the anchor, which is what
+makes a destination mounting over an origin take over as the fly-back target
+without either of them coordinating.
+
+## It never takes a click
+
+Every node the layer renders is `pointerEvents="none"`, inside an `OverlayRoot`
+that is `box-none`. A flying surface is a picture of something the app is
+already showing; the controls underneath it stay the ones the user is pressing.
+
+The layer also renders **nothing at all** while no flight is live — which is
+what keeps it out of the overlay stack's live set, so the rank counter can
+still reset (see `overlay/stack.ts`). It takes a rank only while it is
+actually painting, and therefore stacks by open order like every other Bloom
+surface.
+
+## Why the size is animated rather than scaled
+
+`ZoomableMediaGallery` flies its media with a uniform `scale`, which is right
+there: it opens from a thumbnail into a box of the same aspect ratio. 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 replacing. `width`/`height` are
+interpolated instead; the position still rides a transform, so the only layout
+work per frame is one absolutely-positioned node resizing.
+
+## Android: a flight crosses a surface-type boundary
+
+expo-video renders Android video into a `SurfaceView` by default. A flight
+cannot: a `SurfaceView` is composited by the system OUTSIDE the view hierarchy,
+so it ignores its parent's clip, corner radius and transform — every property a
+flying box depends on. The layer therefore flies as a `textureView`.
+
+**So unless one side changes, the hand-off swaps surface types.** Whether that
+is visible is a device question and nothing here answers it. Measured on a real
+device it may not flicker at all, in which case the right action is none.
+
+The knob exists so both arrangements can be measured:
+
+```tsx
+// fly as a surfaceView, matching a destination that has not changed
+flight.flyTo(id, rect, content, { surfaceType: 'surfaceView' });
+```
+
+```tsx
+// …or leave the flight alone and give the DESTINATION a textureView
+<MediaSurface content={content} flightId={id} surfaceType="textureView" />
+```
+
+Flying as a `surfaceView` will not transform correctly on Android — that is the
+trade the first option makes. `surfaceType` is captured on first render on both
+sides (expo-video forbids changing it at runtime), so a retarget deliberately
+does not accept a new one.
+
+## Peers
+
+`expo-image` is required (hence the subpath — the family is deliberately not on
+the root barrel, because Metro does not tree-shake). `expo-video` is
+**optional**: an app that flies only images never installs it, and one that
+flies video without it gets the poster plus a single dev warning naming the
+package.
+
+## What a jest run can and cannot see
+
+The registry: that a flight is created, that a second `flyTo` retargets rather
+than duplicating, that `flyBack` releases, that the layer renders nothing while
+idle and a surface when one is live, and that `flyTo` really waits for the
+layer's commit.
+
+What it can never see is the MOTION. Every reanimated animation resolves
+synchronously under the test mock, so a mapper that runs once and freezes at the
+opening frame — the documented web failure mode of this package — produces the
+same tree as one that animates. Two browser gates cover it, both headful against
+real Chrome:
+
+- `node scripts/verify-media-flight.mjs` samples the flying surface's
+  `getBoundingClientRect` during and after the flight, and distinguishes frozen
+  (never leaves the origin) from snapped (already at the destination) from
+  animating, then asserts it lands on the destination rect and is released.
+- `node scripts/verify-overlay-stacking.mjs` parks a surface over a button and
+  clicks the button with trusted input, which is the only way to tell a layer
+  that is `pointer-events: none` from one that merely looks like it.

package/docs/migrating-the-media-gallery.mdx

@@ -0,0 +1,103 @@
+---
+title: Migrating the media gallery
+description: ZoomableImageGallery became ZoomableMediaGallery when the family learned to page video. Two symbols, seven files, two repos — and the subpath you already import still resolves.
+order: 3
+---
+
+# Migrating the media gallery
+
+The full-screen viewer now pages **video as well as images**, so the family is
+`zoomable-media-gallery` and the component is `ZoomableMediaGallery`. Bloom
+follows the clean-cut rule: there is no `@deprecated` alias and no old-name
+shim. This page is the whole bridge.
+
+## What actually changed
+
+Two exported names, and nothing else:
+
+| Old | New |
+| --- | --- |
+| `ZoomableImageGallery` | `ZoomableMediaGallery` |
+| `ZoomableImageGalleryHandle` | `ZoomableMediaGalleryHandle` |
+| `ZoomableImageGalleryProps` | `ZoomableMediaGalleryProps` |
+
+Everything else you import from this family keeps its name: `GalleryImage`,
+`MeasureThumb`, `MeasuredRect`, and every constant.
+
+<Callout variant="info" title="The subpath still resolves">
+`@oxyhq/bloom/zoomable-image-gallery` and
+`@oxyhq/bloom/zoomable-media-gallery` are two specifiers for the SAME module.
+The old one is not a shim being tolerated — an image gallery is exactly what
+this serves when every item is an image, so it stays a first-class entry point.
+You only have to change the *names you import*, not the path you import them
+from. Changing the path too is tidier, and optional.
+</Callout>
+
+## An image item is unchanged
+
+`kind` is optional on the image arm precisely so this stays true:
+
+```tsx
+const images: GalleryImage[] = [
+  { uri: 'https://…/a.jpg', alt: 'A photo', aspectRatio: 1.5 },
+];
+```
+
+If your call site only ever passes images, the rename is the entire migration.
+
+## Every affected file in the ecosystem
+
+Measured across `~/Oxy` (agent worktrees excluded). **Two repos, seven files,
+and in every one of them the fix is the two symbol renames above.**
+
+| Repo | File |
+| --- | --- |
+| Homiio | `packages/frontend/hooks/usePropertyPhotoGallery.ts` |
+| Homiio | `packages/frontend/components/property/PhotoGallery.tsx` |
+| Homiio | `packages/frontend/components/property/PhotoGrid.tsx` |
+| Homiio | `packages/frontend/utils/propertyUtils.ts` |
+| Mention | `packages/frontend/components/ZoomableAvatar.tsx` |
+| Mention | `packages/frontend/components/Post/PostAttachmentsRow.tsx` |
+| Mention | `packages/frontend/components/Post/Attachments/PostAttachmentMedia.tsx` |
+
+`propertyUtils.ts` and `PostAttachmentMedia.tsx` import only `GalleryImage` /
+`MeasuredRect`, which did not change — they appear here because they name the
+subpath, and they need no edit at all.
+
+<Callout variant="info" title="Noted is not affected">
+`Noted/packages/frontend/components/notes/attachments/ZoomableImageGallery.tsx`
+is an app-local component (a port of Mention's original), reached through
+`@/components/...`. It imports nothing from Bloom, so this rename does not touch
+it. It is listed here because a `grep` for the old name finds it and it looks
+like a call site.
+</Callout>
+
+## Why the failure is safe
+
+A symbol that no longer exists fails at RESOLUTION — a TypeScript error and a
+bundler error, at build time, naming the identifier. There is no version of this
+that renders wrong or misbehaves at runtime, and nothing sees it until the app
+deliberately bumps Bloom.
+
+## While you are here: video
+
+Adding a video page needs a `VideoPlayer` **you** create and own — Bloom never
+creates or destroys one:
+
+```tsx
+import { useVideoPlayer } from 'expo-video';
+import type { GalleryMedia } from '@oxyhq/bloom/zoomable-media-gallery';
+
+const player = useVideoPlayer(videoUrl);
+
+const items: GalleryMedia[] = [
+  { uri: 'https://…/a.jpg', alt: 'A photo', aspectRatio: 1.5 },
+  { kind: 'video', id: 'clip-1', player, poster: 'https://…/still.jpg', aspectRatio: 1.777 },
+];
+```
+
+`expo-video` is an optional peer. An app that pages only images never installs
+it; one that pages video without it gets posters and a single dev warning.
+
+See [MediaFlight](./media-flight) for moving that same player between a feed
+thumbnail and a full-screen route without restarting playback.

package/docs/migrating-to-1.0.mdx

@@ -185,7 +185,7 @@ failure, not a type error.
 | `@oxyhq/bloom/menu` | `@oxyhq/bloom/dropdown-menu` | The family was ported to shadcn/react-native-reusables' public API. Every `Menu*` export is `DropdownMenu*`. |
 | `@oxyhq/bloom/collapsible` | `@oxyhq/bloom/accordion` | `Collapsible` called `UIManager.setLayoutAnimationEnabledExperimental(true)` at module scope and reached the root barrel through `export *`, so that side effect ran for every barrel consumer on Android old-arch whether or not the component was used. |
 | `@oxyhq/bloom/grouped-buttons` | `@oxyhq/bloom/settings-list` + `@oxyhq/bloom/item` | The only one of the three row renderers with no `accessibilityRole`, no `accessibilityLabel` and no `aria-disabled`, built on `TouchableOpacity`/`activeOpacity` instead of `useInteractionState`. |
-| `@oxyhq/bloom/pressable-with-hover` | none — inline it | One internal user. It now lives inside `zoomable-image-gallery` as `NavArrow`, the package's only hover-styled control. |
+| `@oxyhq/bloom/pressable-with-hover` | none — inline it | One internal user. It now lives inside `zoomable-media-gallery` as `NavArrow`, the package's only hover-styled control. |
 
 ### Subpaths added
 

package/docs/slider.mdx

@@ -68,6 +68,8 @@ throwing; an empty or whitespace-only string counts as missing, because
   into and is hard to land on a specific value.
 - **There are fewer than about five positions.** Use a
   [`SegmentedControl`](/docs/bloom/main/segmented-control) or a
-  [`Radio`](/docs/bloom/main/radio) group — they name the options.
+  [`Radio`](/docs/bloom/main/radio) group — they name the options. A
+  [`LevelPicker`](/docs/bloom/main/level-picker) is the third answer: a rail
+  with named stops, for a short scale that still reads as a continuum.
 - **The range is huge and non-linear.** A slider over 1–1,000,000 gives most of
   its travel to values nobody wants.

package/docs/zoomable-media-gallery.mdx

@@ -0,0 +1,116 @@
+---
+title: ZoomableMediaGallery
+description: The full-screen media viewer — images and video, mounted once, opened imperatively.
+order: 71
+---
+
+# ZoomableMediaGallery
+
+Full-screen images **and video** with pinch-zoom, swipe between, and
+drag-to-dismiss. Mount it once near the app root and open it from anywhere.
+
+```tsx
+import { ZoomableMediaGallery, type ZoomableMediaGalleryHandle } from '@oxyhq/bloom/zoomable-media-gallery';
+
+const gallery = useRef<ZoomableMediaGalleryHandle>(null);
+
+<ZoomableMediaGallery ref={gallery} measureThumb={measureThumb} />
+
+// from a thumbnail
+gallery.current?.open(items, index);
+```
+
+## Two specifiers, one module
+
+`@oxyhq/bloom/zoomable-image-gallery` resolves the same module and keeps
+working: an image gallery is exactly what this serves when every item is an
+image. The COMPONENT was renamed, so update the identifier —
+`ZoomableImageGallery` no longer exists, and there is no alias.
+
+## A page is an image or a video
+
+```tsx
+import { useVideoPlayer } from 'expo-video';
+import type { GalleryMedia } from '@oxyhq/bloom/zoomable-media-gallery';
+
+// YOU create the player and YOU own it. Bloom never creates or releases one.
+const player = useVideoPlayer(videoUrl);
+
+const items: GalleryMedia[] = [
+  { uri: 'https://…/photo.jpg', alt: 'A photo', aspectRatio: 1.5 },
+  { kind: 'video', id: 'clip-1', player, poster: 'https://…/still.jpg', aspectRatio: 1.777 },
+];
+```
+
+An image item is unchanged — `{ uri }` — because `kind` is optional on that
+arm. A video item carries the `VideoPlayer` object itself, and that is the
+whole mechanism behind "the video does not restart when it opens": expo-video
+keeps the player separate from the `VideoView` that shows it, and one player
+can feed several views. Handing the same player to this gallery moves a playing
+video into full screen without re-opening the stream.
+
+Give a video an `aspectRatio`. Unlike an image there is nothing to probe, so
+without one the page opens at the default ratio and resizes when the first
+frame arrives.
+
+## Exactly one video view is mounted
+
+The ACTIVE page. Every other page, and every thumbnail-strip tile, renders the
+poster still. A second `VideoView` on the same player would be a duplicate
+surface — the thing this family and `media-flight` are both built to avoid —
+and on a strip it would be one decoder per tile.
+
+One surface swap happens per opening: the pre-pager open surface hands over to
+the pager's active page once the open animation settles.
+
+## Which prop decides what
+
+| prop               | decides                                                  |
+| ------------------ | --------------------------------------------------------- |
+| `measureThumb`     | the rect the opening animation grows FROM                 |
+| `cornerRadius`     | the thumbnail's corner, so the transition matches it       |
+| `indicatorVariant` | `dots` or `thumbnails` for the page indicator              |
+| `videoControls`    | whether video pages show expo-video's transport controls   |
+
+`open(items, index, rect?)` takes the whole set and which one to show.
+
+## Why it is imperative
+
+One gallery serves every thumbnail on a screen. Making it declarative would
+mean a piece of state per grid, or one shared "which item is open" flag
+threaded through everything that can show media. The ref is what lets a
+thumbnail deep in a list open it without the list knowing the gallery exists.
+
+## `measureThumb` is what makes the transition read
+
+Without it the gallery fades in from nowhere. With it, the image grows out of
+the thumbnail the user pressed, which tells them *which* image they opened —
+useful precisely in the case where a grid has several similar photos.
+
+It returns a promise because measuring is asynchronous on native. Returning
+`null` is fine and degrades to the fade.
+
+## `alt` is the caption and the accessible text
+
+Set `alt` on each item. It is shown as the caption for the active page, and it
+is the only description a screen reader has — a media viewer with no alt text
+is a screen with nothing on it.
+
+## Peers
+
+It requires `expo-image`, which is why the family is **not** on the root
+barrel: Metro does not tree-shake, so importing the barrel would drag that peer
+into every consumer's build whether or not they use a gallery. Import it from
+its subpath.
+
+`expo-video` is an **optional** peer, loaded through
+`media-flight/expo-video-module` with the one dynamic-require shape Metro marks
+optional. An app that ships no video never has to install it; one that does and
+forgets gets its video pages degraded to their posters, with a single dev
+warning naming the package.
+
+## What a jest run can and cannot see
+
+That it renders nothing until `open()` is called, and that it opens at the
+index it was given. The gestures — pinch, pan-to-dismiss, the shared-element
+transition — belong to a device build.

package/lib/commonjs/floating/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_constants","require","_context","_FloatingPanel","_menuRows","_menuSubInline","_TriggerSlot","_useAnchorRect","_useSheetOpenBridge"],"sourceRoot":"../../../src","sources":["floating/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAWA,IAAAA,UAAA,GAAAC,OAAA;AAMA,IAAAC,QAAA,GAAAD,OAAA;AAaA,IAAAE,cAAA,GAAAF,OAAA;AACA,IAAAG,SAAA,GAAAH,OAAA;AAKA,IAAAI,cAAA,GAAAJ,OAAA;AACA,IAAAK,YAAA,GAAAL,OAAA;AAEA,IAAAM,cAAA,GAAAN,OAAA;AACA,IAAAO,mBAAA,GAAAP,OAAA","ignoreList":[]}
+{"version":3,"names":["_constants","require","_context","_FloatingPanel","_menuRows","_menuSubInline","_TriggerSlot","_useAnchorRect","_useSheetOpenBridge"],"sourceRoot":"../../../src","sources":["floating/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgBA,IAAAA,UAAA,GAAAC,OAAA;AAMA,IAAAC,QAAA,GAAAD,OAAA;AAaA,IAAAE,cAAA,GAAAF,OAAA;AACA,IAAAG,SAAA,GAAAH,OAAA;AAKA,IAAAI,cAAA,GAAAJ,OAAA;AACA,IAAAK,YAAA,GAAAL,OAAA;AAEA,IAAAM,cAAA,GAAAN,OAAA;AACA,IAAAO,mBAAA,GAAAP,OAAA","ignoreList":[]}

package/lib/commonjs/image-aspect-ratio-cache/aspect-ratio-cache.js

@@ -10,7 +10,7 @@ var _reactNative = require("react-native");
  * 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/lib/commonjs/index.js

@@ -93,6 +93,7 @@ var _exportNames = {
   InputGroup: true,
   InputGroupAddon: true,
   Slider: true,
+  LevelPicker: true,
   Combobox: true,
   BottomSheet: true,
   LinkPreviewCard: true,
@@ -329,6 +330,12 @@ Object.defineProperty(exports, "Label", {
     return _index26.Label;
   }
 });
+Object.defineProperty(exports, "LevelPicker", {
+  enumerable: true,
+  get: function () {
+    return _levelPicker.LevelPicker;
+  }
+});
 Object.defineProperty(exports, "LinkPreviewCard", {
   enumerable: true,
   get: function () {
@@ -881,6 +888,7 @@ var _index26 = require("./label/index.js");
 var _index27 = require("./field/index.js");
 var _index28 = require("./input-group/index.js");
 var _index29 = require("./slider/index.js");
+var _levelPicker = require("./level-picker");
 var _combobox = require("./combobox");
 var _bottomSheet = require("./bottom-sheet");
 var _index30 = require("./card/index.js");