@tiledev/sdk-apptile-live-selling 0.1.0

package/README.md

@@ -0,0 +1,322 @@
+# @tiledev/sdk-apptile-live-selling
+
+Live selling, auctions and giveaways for React Native — the Apptile live-selling gateway as a typed
+singleton, a Zego room engine, an assembled session state machine, and system picture-in-picture with
+its own config plugin.
+
+**Headless.** It ships one component (`LiveVideoTarget`, because a render target is unavoidably
+native). Your header, comments list, bid bar and sheets stay yours.
+
+**Storefront-agnostic.** Products, cart writes and the auction checkout come from an adapter you
+supply, so there is no Shopify dependency.
+
+```bash
+npm i @tiledev/sdk-apptile-live-selling
+```
+
+Peers, all optional: `expo`, `react`, `react-native`, `zego-express-engine-reactnative`. Off-device the
+engine and PIP resolve to no-ops, so a web or Node bundle needs none of them.
+
+Three entry points: `.` (client, session machine, types), `./react` (providers, hooks, the one
+component), `./types` (types alone, for a package that only needs the shapes).
+
+## 1. Add the config plugin
+
+Every native entry live selling needs lives in a file `expo prebuild` regenerates, so it has to be a
+plugin — an edit by hand works on the machine that made it and silently stops working in CI.
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["@tiledev/sdk-apptile-live-selling", {
+        "cameraPermission": "Used to appear on camera when you co-host a live show."
+      }]
+    ]
+  }
+}
+```
+
+| Prop | Default | What it writes |
+|---|---|---|
+| `pip` | `true` | `android:supportsPictureInPicture`, the `configChanges` a PIP resize needs, `UIBackgroundModes: ["audio"]` |
+| `cameraPermission` / `microphonePermission` | generic copy | `NSCameraUsageDescription` / `NSMicrophoneUsageDescription` — never overwrites strings your app already sets |
+| `capturePermissions` | `true` | Android `CAMERA` + `RECORD_AUDIO` |
+
+Zego's own Maven repo is added unconditionally: `im.zego:express-video` lives only there, and a clean
+Android checkout fails at configuration time without it.
+
+Then `npx expo prebuild` and run the app. The `LivePip` Expo module autolinks itself.
+
+> If your app already vendors a `live-pip` module, **delete it** — identical module and pod names
+> collide at link time.
+
+## 2. Configure
+
+Every viewer endpoint is **anonymous**: the brand `companyId` is the only credential, sent as
+`x-company-id`. It is not the Shopify store id and not the Tile app id.
+
+```ts
+import { liveSelling } from '@tiledev/sdk-apptile-live-selling';
+
+liveSelling.configure({
+  apiUrl: 'https://live-selling.apptile.io',
+  companyId: '<brand-id>',
+  zegoAppId: 361108744,   // platform-level: the gateway signs room tokens with one Zego app
+  commerce,               // see §4
+  identity,
+});
+```
+
+| Field | Required | Purpose |
+|---|---|---|
+| `apiUrl` | yes | Gateway base URL, no trailing slash |
+| `companyId` | yes | Apptile "brand id" — the only credential |
+| `zegoAppId` | for video | Matches the gateway, not the brand. Native engine only |
+| `commerce` | for shopping | Resolves lots to products and sells them |
+| `identity` | for bidding | The customer a win is attributed to |
+| `storage` | no | AsyncStorage-shaped. Defaults to `localStorage`, else in-memory |
+| `videoCollectionId` | no | The clip reel. **Not** scoped by the company header, so a stale id serves another tenant's clips — unset ⇒ `clips.list()` is `[]` |
+| `requestSource` | no | `X-Request-Source`. Defaults to `"APPTILE"` |
+| `logger` | no | `{ error }`. Defaults to silent |
+| `customerAccountRequest` | no | The customer's bearer transport. Only the unpaid-wins read uses it |
+
+Pass real `storage` in anything you ship. Three things are lost on relaunch without it: the name a
+signed-out shopper gave, the accepted auction terms, and which polls this install voted in. The last one
+does damage — **the gateway does not dedupe votes**, so a forgotten vote lets the same device vote again.
+
+## 3. Mount and render
+
+`LiveSellingProvider` configures the client. `LiveSessionProvider` folds the engine's events and the
+polled record into one renderable state — mount it **above your navigator**, because the Zego engine
+holds exactly one room and two places usually render the same stream (a home card and the full-screen
+player). Own it per screen and whichever unmounts first kills the other's video.
+
+```tsx
+import {
+  LiveSellingProvider, LiveSessionProvider, useLiveSession, LiveVideoTarget,
+} from '@tiledev/sdk-apptile-live-selling/react';
+
+<LiveSellingProvider config={config}>
+  <LiveSessionProvider onPipRestore={() => navigate('Live')}>
+    <Navigator />
+  </LiveSessionProvider>
+</LiveSellingProvider>
+```
+
+Surfaces don't own the video, they *bind* to it:
+
+```tsx
+function LiveScreen() {
+  const session = useLiveSession();
+  const isFocused = useIsFocused();
+
+  return (
+    <LiveVideoTarget active={isFocused && session.pipMode === 'none'}>
+      {session.status !== 'playing' && <YourPoster status={session.status} />}
+    </LiveVideoTarget>
+  );
+}
+```
+
+`active` is a prop rather than read from navigation focus, so the package needs no navigator
+dependency — and a PIP surface drawn outside the navigator has no route to read focus from anyway.
+Exactly one mounted target should have it set.
+
+### What `useLiveSession()` gives you
+
+| | |
+|---|---|
+| `status` | `loading` · `connecting` · `waitingForHost` · `playing` · `ended` · `error` |
+| `stream` | the record: title, host, products, giveaways, `bidCap`, `reactionStyle` |
+| `activeProduct` `products` | resolved through your commerce adapter |
+| `comments` `reactions` `sold` `poll` | the live feed; reactions and sold cards expire on their own |
+| `auction` | `biddingOpen`, `highestBid`, `nextBid`, `timeLeftMs`, `isLeading`, `leaderName`, `extended`, `lastWin` |
+| `giveaway` | `active`, `entryCount`, `registered`, `result` |
+| `guest` | co-host: `mode`, `status`, `slot`, `mutedByHost`, `mixerLayout` |
+| `viewerCount` `elapsedMs` `muted` `pipMode` `viewerName` | header material |
+| `actions` | `sendComment`, `sendReaction`, `addToCart`, `voteInPoll`, `placeBid`, `enterGiveaway`, `enterPip`, `joinAsGuest`, … |
+
+`actions` is identity-stable — safe in a dependency array, and deliberately so: one of the effects that
+depends on it rebinds the video, which is a real `startPlayingStream`.
+
+`viewerName` is `null` when nobody has said who they are. Ask before the first comment goes out rather
+than publishing "Anonymous" to a room; `actions.chooseViewerName(raw)` remembers the answer.
+
+`capabilitiesFor(stream)` returns the flag set a stream calls for (`canBid`, `canEnterGiveaway`,
+`showLiveBadge`, …), so one screen serves an ordinary live show and an auction. An auction is a live show
+plus bidding — the flags are derived, not spelled out twice.
+
+## 4. Adapters
+
+The gateway only ever speaks in bare numeric product ids, because that is what the host dashboard
+records. Turning one into something with a price, an image and variants is your job — and so is selling.
+
+```ts
+const commerce = {
+  productsByIds: async (ids) => {
+    const products = await shopify.products.byIds(ids.map((id) => `gid://shopify/Product/${id}`));
+    return products.map((p) => ({
+      id: p.id,
+      storeProductId: p.id.split('/').pop(),
+      title: p.title,
+      price: p.priceRange.min.amount,
+      currencyCode: p.priceRange.min.currencyCode,
+      imageUrl: p.images?.[0]?.url ?? null,
+      variants: p.variants.map((v) => ({
+        id: v.id, title: v.title, price: v.price.amount, available: v.availableForSale,
+      })),
+      raw: p,                       // carried through untouched, for your own call sites
+    }));
+  },
+  // FALSE for a *refused* line rather than throwing. A refused add must not be announced to the
+  // room — that card is what everyone else reads as "it is going".
+  addLine: (variantId, quantity) => shopify.cart.addLine({ merchandiseId: variantId, quantity }),
+};
+
+const identity = {
+  bidderId: () => customerId,                  // bare id; what the host echoes back on a bid
+  customerRef: () => `gid://shopify/Customer/${customerId}`,
+  customerName: () => customer.firstName,
+};
+```
+
+Only `productsByIds` is required. An unimplemented method disables the feature that needs it rather than
+throwing: no `addLine` ⇒ no add-to-cart, no `createAuctionCheckout` ⇒ wins are reported but not payable.
+
+`raw` keeps its type. Name it once and your own product comes back off the session with no cast:
+
+```ts
+const session = useLiveSession<ShopifyProduct>();
+session.activeProduct?.raw?.onlineStoreUrl;   // ShopifyProduct | undefined, not unknown
+```
+
+`bidderId` must be the **same id the host's broadcast echoes back**, or `isLeading` compares two
+different things and nobody is ever leading. Keep it distinct from the per-install viewer id, which is
+what the host mutes by.
+
+<details>
+<summary><b>The auction checkout contract</b> — read before implementing <code>createAuctionCheckout</code></summary>
+
+Build a **disposable** cart, not the shopping cart: an auction win is already a commitment at a settled
+price, and mixing those lines into a browsing cart lets a quantity stepper change it.
+
+On Shopify each line carries a hidden `_winningBid` (or `_giveawayItem`) attribute that a **cart
+transform** function on the store reads to reprice the line server-side. Each line also needs something
+unique in its attributes — Shopify merges lines sharing the same merchandise *and* attributes, so two
+identical wins collapse into one quantity-2 line priced as a single lot, and the second win is free.
+</details>
+
+## 5. Auctions — the two rules that matter
+
+**Nothing is optimistic.** A viewer *offers* a bid to the round's moderator and waits; only the host's
+broadcast sets the high bid, the leader and the deadline. That is what makes two phones agree.
+
+**Deadlines are on the host's clock**, carried as `serverNowMs` on every event that moves them. A phone
+minutes out of sync would otherwise close a round that is still open. `auction.timeLeftMs` is already
+corrected for the offset.
+
+`useAuctionBidGate` owns the four ordered conditions in front of a bid and reports which one is current;
+you render the panels. The order is the whole point:
+
+```ts
+const gate = useAuctionBidGate({
+  streamingId: session.stream?.streamingId ?? null,
+  isLoggedIn, biddingOpen: auction.biddingOpen,
+  variantCount: biddingProduct?.variants.length ?? 0,
+  placeBid: actions.placeBid,
+});
+
+// gate.blocker: 'signIn' | 'unpaidWins' | 'terms' | 'variant' | null
+gate.requestBid();        // the round's minimum — the slide gesture
+gate.requestBid(250);     // a custom bid
+```
+
+Signed in → nothing outstanding on another stream → rules accepted once per install → a variant chosen
+(once per round, not per bid). The requested bid is held while you clear the blockers and then placed, so
+finishing the last panel completes the bid they originally asked for. Call `gate.refreshUnpaidWins()`
+from your own focus effect, so a customer who leaves to settle a tab is unblocked on return.
+
+If you render the panels as React Native `Modal`s, honour `SHEET_HANDOFF_MS` between them — presenting
+one while another dismisses is a native iOS exception, not a catchable error.
+
+## 6. Platform boundaries
+
+Two pairs of files, and Metro picks by platform. TypeScript resolves the non-native one, which is why
+`tsc` needs neither Zego nor Expo installed.
+
+| Native (iOS/Android) | Everywhere else |
+|---|---|
+| `engine.native.ts` — the real Zego engine; owns the room, plays into a rebindable view, publishes a guest's camera, translates every Zego channel into a `LiveEvent` | `engine.ts` — no-op, `isNoop: true` |
+| `pip.native.ts` — the `LivePip` Expo module | `pip.ts` — no-op, `isLivePipSupported: false` |
+
+So the session never arms a handover that cannot happen, and a web bundle never evaluates the Zego
+entry module.
+
+**Picture-in-picture** is two stages. `actions.enterPip()` shrinks to a surface *you* draw; the session
+arms the OS handover in advance, so minimising the app opens a real system window with no JavaScript
+involved at that moment. Coming back raises `onPipRestore` — navigate to your live screen, which the SDK
+can't do itself from above the navigator.
+
+## 7. Imperative client
+
+For anything the session doesn't cover. `liveSelling.configure()` first; `isReady()` and `companyId()`
+report state.
+
+| Namespace | Methods |
+|---|---|
+| `streams` | `list` `ongoing` `byId` `zegoToken` |
+| `auctions` | `recordBid` `enterGiveaway` `hasAcceptedTerms` `acceptTerms` `unpaidStreamIds` `wins` `isBiddingBlocked` |
+| `polls` | `vote` `loadVotedOption` `rememberVote` `forgetVote` |
+| `replays` | `list` `segments` `comments` `incrementViews` |
+| `clips` | `list` |
+| `guest` | `acceptInvite` `leaveSlot` `userId` |
+| `flags` | `fetch` — per-company feature switches |
+| `viewer` | `id` `loadName` `cachedName` `saveName` `normaliseName` |
+| `engine` | the Zego engine (above) |
+
+Read hooks for screens that only need data: `useOngoingLive`, `useLiveStreams`, `useStreamInfo`,
+`useReplays`, `useClips`, `useAuction`.
+
+`LiveEvent` is the union the engine emits — `comment`, `reaction`, `sold`, `viewers`, `productChange`,
+`poll*`, `biddingStarted`/`bidInfo`/`biddingClosed`/`auctionWon`, `giveaway*`, the `guest*` co-host
+signals, and an `unknown` fallthrough so a new host-side message is visible rather than dropped.
+Subscribe via `LiveSellingProvider`'s `onEvent` or `liveSelling.engine.subscribe`.
+
+## Scripts
+
+| Command | What it does |
+|---|---|
+| `npm run build` | Cleans, compiles `src` → `dist` and `plugin/src` → `plugin/build`. Both are needed: `app.plugin.js` loads the compiled plugin so consumers never need TypeScript at prebuild |
+| `npm run lint` | Typechecks both projects, emitting nothing |
+| `npm run clean` | Removes `dist` and `plugin/build` |
+| `npm pack` | The publish tarball — use it to verify `dist`, `ios/`, `android/`, `expo-module.config.json`, `app.plugin.js` and `plugin/build` all ship |
+
+The reducer is exported on its own (`sessionReducer`, `deriveStatus`, `timeLeftMs`) and is pure, so it
+can be driven with no room, socket or React.
+
+## Gotchas
+
+- **A camera left off is invisible to Zego.** No media event and no camera-state event fires; only
+  zero-FPS quality samples reveal it, which is why `status` becomes `waitingForHost` about 5s in rather
+  than instantly.
+- **A dropped socket is not the end of a stream.** Backgrounding disconnects the room and Zego recovers
+  by itself, so only the host's explicit signal or the record ends it.
+- **Broadcasts are never replayed.** A shadow-mute is seeded from the stream record for exactly this
+  reason — otherwise a muted viewer gets a free message per relaunch, and an *unmute* is invisible until
+  the app restarts.
+- **A guest and a viewer cannot both hold the room.** One Zego session per engine, and publishing rights
+  live in the token, so co-hosting logs the viewer out and `leaveGuest` takes the room back.
+- **Consuming via `file:` or a workspace link?** Hoist `@types/react`. The `.d.ts` otherwise resolves
+  against the SDK's own nested copy, and React 18's `ReactNode` isn't assignable to React 19's.
+
+## Not included
+
+UI · a storefront · navigation · a static clip fallback (`clips.list()` reads only the configured
+collection).
+
+## Verified against
+
+React 19.1.0 · React Native 0.81.5 · Expo 54 — typechecked from the packed tarball, plus a Node load of
+the pure data layer. The native path (autolinking, the podspec, the plugin's prebuild output) has not
+been exercised on a device yet.

package/android/build.gradle

@@ -0,0 +1,33 @@
+apply plugin: 'com.android.library'
+apply plugin: 'expo-module-gradle-plugin'
+
+group = 'expo.modules.livepip'
+version = '1.0.0'
+
+android {
+  namespace "expo.modules.livepip"
+  defaultConfig {
+    versionCode 1
+    versionName "1.0.0"
+  }
+}
+
+dependencies {
+  // `ComponentActivity.addOnPictureInPictureModeChangedListener`, which is the only way to observe
+  // the PIP transitions without editing MainActivity — and MainActivity is prebuild output, so an
+  // edit there would be wiped by the next `expo prebuild`. Declared rather than leant on
+  // transitively through react-android: this module does not compile without it.
+  //
+  // The version matches the `strictly 1.9.3` constraint the app's own graph already carries; a
+  // different one here would be a resolution conflict rather than an upgrade.
+  //
+  // The listener's two argument types (`Consumer`, `PictureInPictureModeChangedInfo`) come from
+  // androidx.core, which expo-modules-core re-exports as an `api` dependency — hence not repeated.
+  implementation 'androidx.activity:activity:1.9.3'
+
+  // `ReactContext`, to contradict the host pause that would otherwise freeze the PIP window — see
+  // `keepRenderingWhileInPip`. expo-modules-core depends on this too, but as `implementation`, so
+  // none of it reaches here. Unversioned on purpose: the React Native Gradle plugin resolves it to
+  // the one React the app is built against.
+  implementation 'com.facebook.react:react-android'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest>
+  <!--
+    Deliberately empty. `android:supportsPictureInPicture` belongs on MainActivity, which is
+    generated by prebuild — see `plugins/withLivePipAndroid.js`, which sets it there. A library
+    manifest cannot add an attribute to an activity the app declares.
+  -->
+</manifest>

package/android/src/main/java/expo/modules/livepip/LivePipModule.kt

@@ -0,0 +1,310 @@
+package expo.modules.livepip
+
+import android.app.PictureInPictureParams
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
+import android.util.Rational
+import androidx.activity.ComponentActivity
+import androidx.annotation.RequiresApi
+import androidx.core.app.PictureInPictureModeChangedInfo
+import androidx.core.os.bundleOf
+import androidx.core.util.Consumer
+import androidx.lifecycle.Lifecycle
+import com.facebook.react.bridge.ReactContext
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * System picture-in-picture for the live stream, Android side.
+ *
+ * The API is the one iOS already speaks — `configure` / `setStream` / `setArmed` / `start` / `stop`
+ * and four events — so `modules/live-pip/index.ts` and every caller stay platform-agnostic. What
+ * happens underneath is not the same shape at all, and it is worth saying why.
+ *
+ * On iOS a PIP window is a piece of *content*: AVKit wants a sample-buffer layer, the engine's own
+ * texture view is not one, and so `LivePipController` intercepts Zego's frames and re-enqueues them.
+ * On Android a PIP window is the *activity itself*, scaled down. There is nothing to intercept — the
+ * `ZegoTextureView` already on screen keeps drawing, because an activity in PIP is paused but still
+ * visible and never reaches `onStop`. So this file is only ever asking the OS to shrink the window,
+ * and the "show video, hide everything else" half of the job is React's: see `LivePipBubble`, which
+ * fills the window with the stream while `pipMode` is `system`.
+ *
+ * That is also why `configure` and `setStream` are no-ops here rather than missing. They exist on
+ * iOS to build and steer a frame pipeline this platform does not have, and the shared JS calls them
+ * unconditionally.
+ */
+class LivePipModule : Module() {
+  /** Whether backgrounding the app should hand over to a PIP window. Mirrors iOS's meaning exactly. */
+  private var armed = false
+
+  /**
+   * Our view of `Activity.isInPictureInPictureMode`, so a listener firing twice for one transition
+   * cannot emit `onPipStart` twice.
+   */
+  private var inPip = false
+
+  /**
+   * The activity the listener below is attached to, so it can be detached from the same one. An
+   * activity is recreated on a process restart or a config change we do not handle, and leaving the
+   * listener on a dead one means emitting events for a window nobody can see.
+   */
+  private var listeningTo: ComponentActivity? = null
+
+  private val pipListener = Consumer<PictureInPictureModeChangedInfo> { info ->
+    handleModeChange(info.isInPictureInPictureMode)
+  }
+
+  private val activity: ComponentActivity?
+    get() = appContext.currentActivity as? ComponentActivity
+
+  override fun definition() = ModuleDefinition {
+    Name("LivePip")
+
+    Events("onPipStart", "onPipStop", "onPipRestore", "onPipError")
+
+    /** No-op: nothing to configure without a frame pipeline. See the note at the top of the file. */
+    AsyncFunction("configure") {}
+
+    /** No-op: the window renders whatever the activity renders, so it needs no stream id. */
+    AsyncFunction("setStream") { _: String? -> }
+
+    AsyncFunction("setArmed") { next: Boolean -> setArmed(next) }
+
+    AsyncFunction("start") { start() }
+
+    AsyncFunction("stop") { stop() }
+
+    /**
+     * The pre-Android-12 half of auto-enter.
+     *
+     * From API 31 the OS does this itself off `setAutoEnterEnabled`, which is the only version that
+     * gets a genuinely seamless handoff — the transition happens with no app code in the loop, the
+     * same property iOS's `canStartPictureInPictureAutomaticallyFromInline` has. Below that, the last
+     * callback before the app leaves is this one, so it is where the request has to go. Not
+     * `onPause`: that also fires when the screen turns off, and a PIP window opened because someone
+     * pocketed their phone is not what "keep watching" means.
+     */
+    OnUserLeavesActivity {
+      if (armed && Build.VERSION.SDK_INT < Build.VERSION_CODES.S) start()
+    }
+
+    /**
+     * Fires when React Native pauses the host — which, entering PIP, happens either just before or
+     * just after the mode change, depending on the OS version and on whether auto-enter or an
+     * explicit call opened the window. Whichever order it lands in, the pause must not be the last
+     * word while a window is up, so the un-pause is re-applied from both sides.
+     */
+    OnActivityEntersBackground {
+      if (inPip) keepRenderingWhileInPip()
+    }
+
+    OnDestroy { detach() }
+  }
+
+  // MARK: - Entry points
+  //
+  // Each one re-tests the version rather than trusting the guard in the last one. The whole file
+  // below API 26 is unreachable — `enterPictureInPictureMode(params)` does not exist there — and a
+  // helper that establishes the version is invisible to lint's `NewApi` check, so the test has to
+  // sit where the call is or the release build fails on it.
+
+  private fun setArmed(next: Boolean) {
+    armed = next
+    if (!available()) {
+      // Only worth saying when something was actually asked for. A device without the feature is a
+      // live stream without picture-in-picture, which is still a working live stream — the in-app
+      // bubble carries on regardless.
+      if (next) fail("Picture-in-picture is not available on this device")
+      return
+    }
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    applyArmed(next)
+  }
+
+  private fun start() {
+    if (!available() || Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    enterPip()
+  }
+
+  private fun stop() {
+    val activity = this.activity ?: return
+    activity.runOnUiThread {
+      if (!activity.isInPictureInPictureMode) return@runOnUiThread
+      leavePip(activity)
+    }
+  }
+
+  // MARK: - The window
+
+  @RequiresApi(Build.VERSION_CODES.O)
+  private fun applyArmed(next: Boolean) {
+    val activity = this.activity ?: return
+    activity.runOnUiThread {
+      attach(activity)
+      // Below API 31 there are no params to keep current — `enterPictureInPictureMode` carries them
+      // at the moment it is called, from `OnUserLeavesActivity` above.
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        runCatching { activity.setPictureInPictureParams(params(autoEnter = next)) }
+          .onFailure { fail(it.message ?: "Could not arm picture-in-picture") }
+      }
+      // Deliberately *not* leaving an open window when disarmed. Disarming happens when the session
+      // ends — the host hangs up, or the viewer closes the window — and the two cases that reach
+      // here mid-window both end with the OS taking the window down anyway. The one that does not is
+      // a stream ending while the user watches in PIP, and yanking the whole app to the foreground
+      // for that is worse than leaving a window they can dismiss themselves: Android has no
+      // counterpart to `stopPictureInPicture()`, so foregrounding is the only "close" available.
+    }
+  }
+
+  @RequiresApi(Build.VERSION_CODES.O)
+  private fun enterPip() {
+    val activity = this.activity ?: return
+    activity.runOnUiThread {
+      if (activity.isInPictureInPictureMode) return@runOnUiThread
+      attach(activity)
+      // Not merely a failed transition: the OS also throws here when the user has revoked the app's
+      // picture-in-picture access in settings, which is a state nothing else reports.
+      runCatching { activity.enterPictureInPictureMode(params(autoEnter = armed)) }
+        .onFailure { fail(it.message ?: "Could not start picture-in-picture") }
+    }
+  }
+
+  /**
+   * Comes back out of the window and into the app.
+   *
+   * Android has no counterpart to `stopPictureInPicture()` — the only way out is to bring the task
+   * forward, which is exactly what the window's own expand button does. So this takes the expand
+   * path, and the listener below reports it as a restore rather than as a dismissal. iOS's `stop()`
+   * means the other thing (dismiss, and stop playing); nothing in the app calls either, and the JS
+   * wrapper documents the split.
+   */
+  private fun leavePip(activity: ComponentActivity) {
+    val intent = Intent(activity, activity.javaClass)
+      .addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+    runCatching { activity.startActivity(intent) }
+  }
+
+  /**
+   * Portrait 9:16 — the shape the hosts publish in, and the same one the in-app bubble uses. Without
+   * it the window inherits the activity's aspect ratio, which is the phone's, and the stream sits in
+   * a tall window with black down both sides.
+   */
+  @RequiresApi(Build.VERSION_CODES.O)
+  private fun params(autoEnter: Boolean): PictureInPictureParams {
+    val builder = PictureInPictureParams.Builder().setAspectRatio(Rational(9, 16))
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      builder.setAutoEnterEnabled(autoEnter)
+      // Seamless resize is for content that can be re-laid-out mid-transition; a video surface
+      // cross-fades instead, which is what turning it off asks for — and the cross-fade is also what
+      // covers React swapping the app's UI for the full-bleed stream on the way in.
+      builder.setSeamlessResizeEnabled(false)
+    }
+    return builder.build()
+  }
+
+  /**
+   * API 26, not the manifest's own 24: picture-in-picture existed at 24 for Android TV only, and the
+   * params overload does not exist before O. The feature check covers the rest — a handset can ship
+   * without it, and low-memory devices routinely do.
+   */
+  private fun available(): Boolean {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return false
+    val activity = this.activity ?: return false
+    return activity.packageManager.hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE)
+  }
+
+  // MARK: - Transitions
+
+  private fun attach(activity: ComponentActivity) {
+    if (listeningTo === activity) return
+    detach()
+    activity.addOnPictureInPictureModeChangedListener(pipListener)
+    listeningTo = activity
+    inPip = activity.isInPictureInPictureMode
+  }
+
+  private fun detach() {
+    listeningTo?.removeOnPictureInPictureModeChangedListener(pipListener)
+    listeningTo = null
+  }
+
+  private fun handleModeChange(isInPip: Boolean) {
+    if (isInPip == inPip) return
+    inPip = isInPip
+
+    if (isInPip) {
+      keepRenderingWhileInPip()
+      emit("onPipStart", Bundle())
+      return
+    }
+
+    /*
+     * Expanded, or closed? Both leave PIP and neither carries a flag saying which.
+     *
+     * The lifecycle answers it. Tapping the window's close button stops the activity *before* this
+     * callback runs, so the state has already fallen below STARTED; tapping expand brings it
+     * forward, so it is at least STARTED. This is the check Google's own PIP sample uses, and this
+     * callback is the last moment the two paths are still distinguishable.
+     */
+    val restored = listeningTo?.lifecycle?.currentState?.isAtLeast(Lifecycle.State.STARTED) ?: false
+    // Hand the lifecycle back. Restoring brings a real `onResume` along behind this, so only the
+    // close needs saying: there the activity stops without ever pausing again — it already paused on
+    // the way *into* the window — so nothing else would undo the un-pause below, and the app would
+    // go on rendering a screen no one is looking at.
+    if (!restored) resumeReactHostRendering(resumed = false)
+    // Same order as iOS: the restore first, then the stop it caused. The JS ignores a stop that
+    // carries `restored`, so the pair reads as one event on either platform.
+    if (restored) emit("onPipRestore", Bundle())
+    emit("onPipStop", bundleOf("restored" to restored))
+  }
+
+  /**
+   * Keeps React Native drawing while the app is in a picture-in-picture window.
+   *
+   * Without this the window is a still photograph. An activity in PIP is *paused* — visible, but
+   * paused — and React Native reads that pause as "nobody is looking": `FabricUIManager.onHostPause`
+   * stops `DispatchUIFrameCallback`, so mount items queue up and are never applied. React goes on
+   * computing perfectly correct layouts that never reach a native view.
+   *
+   * Measured, not inferred, and worth repeating if this ever regresses: an opaque full-window view
+   * rendered from JS reported the right layout through `onLayout` — the PIP window's own size, to the
+   * decimal — and did not draw a single pixel of itself. Layout was fine; mounting was frozen. (Do
+   * not reach for `dumpsys gfxinfo` to check this. Its frame counter sits still for a paused activity
+   * whether or not the window is updating, so it reads the same before and after this fix. Take a
+   * screenshot instead.)
+   *
+   * So the pause is contradicted for exactly as long as a window is up. That is not a trick — the
+   * app genuinely is on screen, and every native app in PIP keeps rendering. The cost is that JS
+   * sees `AppState: 'active'` while in PIP, which is also the truthful answer.
+   *
+   * Posted rather than called inline: this runs from inside React Native's own lifecycle dispatch,
+   * which is iterating its listener list at the time, and re-entering it there is how you get a
+   * concurrent modification out of a list nobody expected to change mid-loop.
+   */
+  private fun keepRenderingWhileInPip() = resumeReactHostRendering(resumed = true)
+
+  private fun resumeReactHostRendering(resumed: Boolean) {
+    val context = appContext.reactContext as? ReactContext ?: return
+    val activity = this.activity
+    Handler(Looper.getMainLooper()).post {
+      runCatching {
+        if (resumed) context.onHostResume(activity) else context.onHostPause()
+      }.onFailure { fail(it.message ?: "Could not keep rendering in picture-in-picture") }
+    }
+  }
+
+  private fun fail(message: String) = emit("onPipError", bundleOf("message" to message))
+
+  /**
+   * Best-effort by design. Closing the window finishes the activity and the React host goes with it,
+   * so the last event of a session is routinely sent into a runtime that is already tearing down.
+   * That throws, and it is not a failure worth reporting to anyone.
+   */
+  private fun emit(name: String, body: Bundle) {
+    runCatching { sendEvent(name, body) }
+  }
+}

package/app.plugin.js

@@ -0,0 +1,3 @@
+// Expo resolves a package's config plugin through this file. Points at the compiled plugin so a
+// consumer never needs TypeScript at prebuild time.
+module.exports = require('./plugin/build');