@tiledev/sdk-apptile-live-selling 0.8.1 → 0.9.1

package/README.md

@@ -8,7 +8,9 @@ its own config plugin.
 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.
+supply. An app on `@tiledev/sdk-shopify` can take that adapter ready-made (§4, "On Shopify"), along
+with the cart's giveaway-prize helpers. They are built on the app's own sdk-shopify client, so this
+package loads none of sdk-shopify.
 
 ```bash
 npm i @tiledev/sdk-apptile-live-selling @tiledev/sdk-apptile-live-selling-native
@@ -69,13 +71,16 @@ mistake here regardless of how the ranges are written.
 
 Peers: `react` and `react-native` are needed by the main entry, which re-exports the React layer;
 `zego-express-engine-reactnative` stays optional — off-device the engine resolves to a no-op, as does
-picture-in-picture in the native package.
+picture-in-picture in the native package. `@tiledev/sdk-shopify` (`>=0.10.0`) is required since 0.9.0:
+the Shopify adapter and prize helpers (§4) are built for it, though the app passes its own client in
+and nothing of sdk-shopify is loaded from here.
 
-**Everything ships from the package root**, including the providers, the hooks and `LiveVideoTarget`.
-There is no `./react` subpath — a subpath is reachable only through the `exports` map, which a
-resolver that ignores it (node10, some test runners and bundlers) cannot see at all. What remains
-beside the root is `./types` (types alone) and a wildcard for any module in `dist` — `/session`,
-`/streams`, `/polls` — the escape hatch below.
+**Everything ships from the package root**, including the providers, the hooks, `LiveVideoTarget` and
+the Shopify helpers. There is no `./react` or `./shopify` subpath — a subpath is reachable only through
+the `exports` map, which a resolver that ignores it (node10, some test runners and bundlers) cannot see
+at all, and an app testing a local build would need its Metro and Jest redirects changed for one
+(decided 2026-10-06, Head of Engineering). What remains beside the root is `./types` (types alone) and
+a wildcard for any module in `dist` — `/session`, `/streams`, `/polls` — the escape hatch below.
 
 > The root entry pulls in `react-native`, so it no longer loads in a plain Node runtime. Driving the
 > pure data layer from Node — `sessionReducer`, the wire mappers — goes through the module subpaths
@@ -121,11 +126,13 @@ Every viewer endpoint is **anonymous**: the brand `companyId` is the only creden
 `x-company-id`. It is not the Shopify store id and not the Tile app id.
 
 ```ts
+import AsyncStorage from '@react-native-async-storage/async-storage';
 import { liveSelling } from '@tiledev/sdk-apptile-live-selling';
 
 liveSelling.configure({
   apiUrl: 'https://live-selling.apptile.io',
   companyId: '<brand-id>',
+  storage: AsyncStorage,  // required since 0.9.0; `window.localStorage` on the web
   zegoAppId: 361108744,   // platform-level: the gateway signs room tokens with one Zego app
   commerce,               // see §4
   identity,
@@ -136,18 +143,48 @@ liveSelling.configure({
 |---|---|---|
 | `apiUrl` | yes | Gateway base URL, no trailing slash |
 | `companyId` | yes | Apptile "brand id" — the only credential |
+| `storage` | yes | Since 0.9.0. AsyncStorage-shaped: `AsyncStorage` on a phone, `window.localStorage` on the web. `configure` throws without it |
 | `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 |
+| `logger` | no | `{ error, warn? }`. Defaults to silent. `warn` gets handled-data reports; without it they go to `error` |
 | `customerAccountRequest` | no | The customer's bearer transport. Only the unpaid-wins read uses it |
+| `requestTimeoutMs` | no | Since 0.9.0. How long any gateway (or replay-comment CDN) request may take before it fails with a `LiveSellingTimeoutError`. Defaults to `10000`; zero, negative or non-numbers mean the default |
+| `offAirGraceMs` | no | Since 0.9.0. How long the session waits, with no live record and not reconnecting, before `status` becomes `ended`. Defaults to `4000` |
+| `hiddenShows` | no | Since 0.9.0. `{ titleIncludes, visibleToEmailDomains }`: shows to keep from shoppers, such as a team's rehearsals. Below |
 
-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
+**Timeouts (0.9.0).** Every request is time-boxed — the fetch and reading its body — and a request
+that runs out fails with `LiveSellingTimeoutError` (`url`, `timeoutMs`), never a bare `AbortError`.
+An HTTP failure is still a `LiveSellingError` with its `status`. Before 0.9.0 a request on a dead
+connection never settled, so a join waiting on its room token hung for as long as the OS kept the
+socket open.
+
+**Hidden shows (0.9.0).** A team rehearses on the store's real gateway, which has no "draft" setting.
+Name the rehearsals and who may see them, and pass the signed-in viewer's email to the provider:
+
+```tsx
+hiddenShows: { titleIncludes: ['apptiletest'], visibleToEmailDomains: ['apptile.io'] },
+
+<LiveSellingProvider config={config} viewerEmail={customer?.email ?? null}>
+```
+
+A title containing any word, in any case, is hidden from everyone but an email ending `@` + a domain
+(`host@apptile.io.example.com` is not `apptile.io`). For a viewer who may not see it, the show doesn't
+exist: `useReplays`, `useOngoingLive`, `useLiveStreams` and `useStreamInfo` leave it out, the session
+never holds its record **or joins its room**, and `streams.destinationFor` sends its link to the list
+of shows. The imperative reads (`streams.list`, `ongoing`, `byId`, `replays.list`) stay the gateway's.
+`viewerEmail` is a prop so a sign-in reaches every hook at once; `useHiddenShows()` gives the rule for
+an app's own lists, and the pure `isHiddenFrom` / `withoutHiddenShows` take it as arguments. It hides
+shows in the app only: anyone with the company id can still ask the gateway for them.
+
+**`storage` is required (0.9.0).** It keeps three things across relaunches: the name a signed-out
+shopper gave, the accepted auction terms, and which polls this install voted in. Losing the last one
 does damage — **the gateway does not dedupe votes**, so a forgotten vote lets the same device vote again.
+Until 0.9.0 it was optional, with an in-memory store on a phone, and two of the three apps on this
+package shipped without it (each found on a phone, not in review), so it is now a compile error to
+leave it out. A test that wants nothing kept passes an in-memory store of its own.
 
 ## 3. Mount and render
 
@@ -194,23 +231,168 @@ Exactly one mounted target should have it set.
 | `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` |
+| `comments` `reactions` `sold` `cartAnnouncements` `poll` | the live feed; reactions, sold cards and cart cards expire on their own (each at its lifetime, by one timeout) |
+| `auction` | `biddingOpen`, `highestBid`, `nextBid`, `closesAt`, `isLeading`, `leaderName`, `extended`, `lastWin` (with `isYou`), `wonLotIds` |
+| `giveaway` | `active`, `entryCount`, `registered`, `result` (`winnerName`, `entrantNames`, `entrantNamesReady`, `youEntered`, `isYou`) |
+| `pinnedComment` | `{ id, text }` the host pinned, or null; always null once `status` is `ended` |
 | `guest` | co-host: `mode`, `status`, `slot`, `mutedByHost`, `mixerLayout` |
-| `viewerCount` `elapsedMs` `muted` `pipMode` `viewerName` | header material |
-| `actions` | `sendComment`, `sendReaction`, `addToCart`, `voteInPoll`, `placeBid`, `enterGiveaway`, `enterPip`, `joinAsGuest`, … |
+| `viewerCount` `muted` `pipMode` `viewerName` | header material |
+| `actions` | `sendComment`, `sendReaction`, `addToCart`, `voteInPoll`, `placeBid`, `enterGiveaway`, `enterPip`, `joinAsGuest`, … `placeBid` resolves `{ sent }` and `enterGiveaway` `{ entered }`, with a `reason` when not (0.9.0) |
 
 `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`.
 
+### The session never ticks; the clocks are hooks (0.9.0)
+
+The session changes only when something happens (a room event, a record read, an action's answer) and
+is the same object until one of its fields does. It holds **no clock**: a session that ticks draws every
+component that reads it on every tick, and the session is app-wide (before 0.9.0 that was every reader,
+5 times a second during an auction round). It holds the moments instead:
+
+- `auction.closesAt`: when the round closes, **on this phone's clock** (ms, like `Date.now()`); null
+  with no round open. It moves only when the host moves the deadline.
+- `stream.startedAtMs`: when the show started.
+
+A component that shows a clock counts to one of them itself, and only that component is drawn as it
+ticks:
+
+```tsx
+function RoundClock({ closesAt }: { closesAt: number | null }) {
+  const timeLeftMs = useAuctionCountdown(closesAt);            // ms left, ≥ 0
+  return <Text>{Math.ceil(timeLeftMs / 1000)}s</Text>;
+}
+
+function ShowClock({ startedAt }: { startedAt: number | null }) {
+  const elapsedMs = useShowClock(startedAt);                   // ms since the start, ≥ 0
+  return <Text>{Math.floor(elapsedMs / 60_000)} min</Text>;
+}
+
+// The screen passes the moments down and is never drawn on a clock:
+<RoundClock closesAt={session.auction.closesAt} />
+<ShowClock startedAt={session.stream?.startedAtMs ?? null} />
+```
+
+Both wake once a second, a few milliseconds after the second they show changes, so every second is
+shown once (a free-running 1 s timer shows one twice and skips another). Both stop with nothing to
+count: the countdown at zero or with no round, the show's clock with no start time. They take a number
+rather than reading the session, so a tile can call them with its props, and they work outside the
+provider and on the web.
+
 `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.
 
+### The show a screen is about (0.9.0)
+
+The session is app-wide and follows one show. A screen opened for a named show pins it
+(`holdStream(id)`), and for a moment after that the session still holds the last show's record. Ask
+`useLiveShow` rather than reading `session.stream`:
+
+```ts
+const { show, status, onAir, capabilities } = useLiveShow(route.params.streamId);
+// show:   the session's record once it is this show's, else null
+// status: 'connecting' until then, then the session's ('loading' reads as 'connecting');
+//         'ended' at once when the session has settled on nothing
+// onAir:  playing, or waiting for the host: when the room's controls show
+```
+
+`liveShowFor(session, streamingId)` is the same, pure. On the web it is always `ended`, with no show.
+
+**A card that plays the show** (a muted preview on a home rail or a list of shows) claims the picture
+only when `canPlayInCard({ session, show, screenOnShow: useIsFocused() })`: the session is in that
+show's room and playing, no bubble or window has the picture, and the card's screen is on show.
+
+**Where a link goes:** `await liveSelling.streams.destinationFor(streamingId, { viewerEmail })` reads the
+record once and answers `{ destination, show, readError }`. `destination` is `{ to: 'livePlayer' }` (on
+air), `{ to: 'replay', feedId }` (ended with a recording) or `{ to: 'showList' }` (anything else, a
+hidden show included); map them to your screens. Most pushes about a show are opened after it, so this
+is how one lands on the recording. A recording is remembered for the app's run; never throws; a failed
+read comes back in `readError`, for you to report.
+
+**The lots:** `product.sellId` (the lot number) and `product.baseBidPrice` (an auction's opening bid)
+are joined on from the record; `featuredFirst(products, featuredId)` lifts the featured one to the front
+of a list, the rest in the host's order.
+
+### Names are never emails (0.9.0)
+
+The room shows each viewer's name to everyone, so an email must never reach a screen. Every name the
+SDK hands out has been through `publicName`: comments and the room's history, cart cards, reactions,
+the auction's leader and winner, the giveaway's winner and entrants, a replay's chat, and the events
+themselves. An email keeps its part before the @, an "@handle" stays whole, a real name is unchanged.
+So does the name it publishes for this viewer.
+
+- `viewerNameFor(customer)` is the name to pass as `viewerName`: first and last name, else the first
+  name, else the email's handle; null when signed out. `createShopifyLiveIdentity`'s `customerName`
+  uses it.
+- `firstNameOf(name)` is the first word, for a card with no room for more.
+
+### What the session does on its own (0.9.0)
+
+These used to be workarounds in each app's live screen (Freckled Poppy's, mostly). They are the
+session's job now; delete the app-side copies when you upgrade.
+
+- **Comment history on join.** The last 40 lines the room said before this device arrived
+  (`/live-streaming/comments?streaming_id=`) are put in front of `comments`, once per show. The
+  gateway's duplicate rows are collapsed; anything the room has already delivered is not repeated;
+  the host's stored `"You"` is shown as the host (`stream.hostName`); this device's earlier lines are
+  marked `isOwn` by the name it comments under. Muted lines are left out.
+- **The first comment carries the right name (L6).** `chooseViewerName` gives the name to the engine
+  at once, so the comment that prompted for it goes out under it, not as "Anonymous". A comment a
+  signed-in shopper sends before their name has loaded is **held** and sent the moment it lands —
+  `sendComment` resolves then — or after 10 s at the latest. Don't hold it yourself.
+- **Pinned comment.** `session.pinnedComment` joins the record's `pinned_comment` (arrival), every
+  `PINNED_COMMENT_CHANGED` broadcast (now the typed `pinnedCommentChanged` event, not `unknown`), and
+  a fresh record read on every reconnect. Hidden once the show has ended.
+- **Lot numbers.** When the host features a lot (`PRODUCT_CHANGE`) the record is read again, so a
+  `sellId` the gateway issues at show time reaches `product.sellId` without an app-side
+  `refreshStreamRecords()`. Skipped when the record already has the lot's number.
+- **Nothing on air.** With a read finished, nothing live in it, and the room not reconnecting,
+  `status` becomes `ended` after `offAirGraceMs` (4 s). It used to stay `loading` for ever. A forced
+  read (`refreshStreamRecords()`, e.g. on screen focus) restarts the wait, so a stale record cannot end
+  a show that has just started.
+- **The giveaway reveal's roster (ENG-705).** `giveaway_end` arrives before the gateway writes the
+  entrants onto the record, so the session asks the record again every 700 ms for up to 5 s and keeps
+  the first list with names. Wait for `giveaway.result.entrantNamesReady` before rolling the reveal;
+  the list never changes after it turns true.
+- **A giveaway or poll that has ended stays ended (0.9.0).** A giveaway this phone watched end isn't
+  opened again by a record read taken before the gateway wrote the end (known by its lot and its start,
+  so the same product given away again later still shows). A poll on the record is raised only while
+  its `status` is `"active"` (or absent). A giveaway's `variantPrice` and `variantImageUrl` are the
+  record's `variant_price` and `variant_image`; before 0.9.0 the price was never read.
+- **Android picture-in-picture.** A window the session armed becomes `pipMode: 'system'` even when the
+  player let go of the handover in the same instant, so the window's close button stops playback and
+  its expand button raises `onPipRestore`. A device with no picture-in-picture is reported once, as a
+  warning, and never armed again (L21).
+- **The system window gives the picture back where it took it from.** A window opened from your
+  in-app bubble goes back to the bubble (`pipMode` `'inapp'`, no `onPipRestore`); one opened from a
+  full-screen player goes back to `'none'` and raises `onPipRestore`. Either way in one render, so a
+  surface that claims on `'none'` never grabs the picture on the way back to the bubble. On iOS, coming
+  back to the app with the window still up (by the app's icon rather than the window's expand) does the
+  same and takes the window down. A window is offered only while the show is `playing`, and once up it
+  stays armed whatever the status does. **Closing** it stops the show, which then stays stopped until
+  the app is back in the foreground: a surface that claims in between (the full-screen player still
+  focused behind the window) no longer starts it again behind the app. The same holds after the
+  `PIP_GRANT_MS` stop when no window came.
+- **`LiveVideoTarget`** restates its mute on every status change (a card mounted before the engine
+  existed used to leave the host audible) and takes the picture again when the app returns to the
+  foreground (ENG-580, a blank surface after a comment link) — no app-side "reclaim" toggle needed.
+- **`holdStream(streamingId)`** pins the session to a named show at once, replacing any earlier hold.
+  Pass the id your route carries (a push, a deep link): one call replaces the release-then-hold pair
+  that re-pinned the old show when both ran in one commit (DEL-2882). `holdStream()` with no id still
+  pins whatever is on screen.
+
 `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.
 
+### Taps on the phone (0.9.1)
+
+`liveHaptics.tick()` as each name rolls past in a giveaway draw, `liveHaptics.knock()` as a bidding war
+starts, `liveHaptics.success()` when the shopper wins the draw or the auction. Pass expo-haptics to
+`configure` (`haptics: Haptics`, from `import * as Haptics from 'expo-haptics'`, a native module) and call
+them where your tiles draw those moments. Without it, and always on the web, they do nothing; a failed tap
+is dropped; ticks are capped at 20 a second. The package doesn't depend on expo-haptics (an optional
+`require` wouldn't bundle in an app without it).
+
 ## 4. Adapters
 
 The gateway only ever speaks in bare numeric product ids, because that is what the host dashboard
@@ -265,20 +447,133 @@ what the host mutes by.
 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.
+On Shopify each line carries a hidden `_winningBid` attribute (a prize: the store's prize key, such as
+`_isGiveawayItem` or `_giveawayItem`) that a **cart transform** function on the store reads to reprice
+the line server-side. Each line also needs something unique in its attributes (`_winIndex`) — 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. The cart itself carries
+`source_name`, `source_type: "auction"` and `auction_id`, which the order webhook matches;
+`createShopifyLiveCommerce` (below) builds exactly this.
+
+**The wins can come from more than one show.** The bid gate stops a customer bidding on a second stream
+while the first is unpaid, but nothing gates a giveaway, so a shopper can win one on a later show. Since
+0.9.0 `auctions.wins()` and `useAuctionWins` return every unpaid stream's lots, and each item names its
+own `streamingId`. `auctionId` is still one stream, the first with something payable: put it on the cart
+as `auction_id`, as before, and build one cart for every item, because a checkout opens one cart. The
+host's order webhook matches that one `auction_id`, so lots from another stream may stay listed as
+unpaid until the host clears them too.
 </details>
 
+### On Shopify (0.9.0)
+
+For an app whose storefront is `@tiledev/sdk-shopify` (`>=0.10.0`, a required peer). These build the
+adapters above from the app's own sdk-shopify client and customer, and give the cart its
+giveaway-prize helpers. They are plain functions that load nothing of sdk-shopify: the app passes its
+own `shopify` client and customer in, so the copy of sdk-shopify the app configured is the one used.
+(The Tile preview, or an app testing an unpublished build, can hold two copies, and the other one has
+no store and no customer.) The few fields they read are declared here (`ShopifyProductsAndCart`,
+`ShopifyProductForLive`, `ShopifyCustomerSession`, …), and the app's compiler checks sdk-shopify's real
+objects against them where it passes them in.
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  LiveSellingProvider, createShopifyLiveCommerce, createShopifyLiveIdentity,
+} from '@tiledev/sdk-apptile-live-selling';
+import { shopify, useCustomer } from '@tiledev/sdk-shopify';
+
+function AppLiveSellingProvider({ children }) {
+  const customer = useCustomer();
+  const latestCustomer = useRef(customer);
+  latestCustomer.current = customer;
+
+  const config = useMemo(() => {
+    const signedIn = createShopifyLiveIdentity(() => latestCustomer.current);
+    return {
+      apiUrl, companyId, zegoAppId,
+      storage: AsyncStorage,
+      identity: signedIn.identity,
+      customerAccountRequest: signedIn.customerAccountRequest,
+      commerce: createShopifyLiveCommerce({
+        shopify,
+        cartSourceName: 'apptile-mobile-app-builder',
+        prizeWriteKey: '_isGiveawayItem',   // the key YOUR store's cart transform reads; no default
+        buyer: signedIn.buyer,
+        imageTransform: { maxWidth: 600 },
+      }),
+    };
+  }, []);
+  return <LiveSellingProvider config={config}>{children}</LiveSellingProvider>;
+}
+```
+
+**`createShopifyLiveCommerce(options)`** returns `{ productsByIds, createAuctionCheckout }`. Add your
+own `addLine` beside them. Each product's `raw` is the sdk-shopify `Product` it was read as; read it
+typed with `useAuctionWins<Product>()` / `useLiveSession<Product>()`.
+
+| Option | Required | What it is |
+|---|---|---|
+| `shopify` | yes | The app's sdk-shopify client (`shopify`): its `products.byIds` and `cart.create` |
+| `cartSourceName` | yes | `source_name` on the wins cart |
+| `prizeWriteKey` | yes | The line attribute this store's cart transform reads for a prize. No default: a wrong one charges a winner full price |
+| `buyer` | yes | Who pays: `{ customerAccessToken, email? }`, or null for a guest cart. `createShopifyLiveIdentity(...).buyer` |
+| `imageTransform` | no | The products' photo size, passed to `products.byIds` |
+| `extraLineAttributes` | no | `(win) => ShopifyAttribute[]`: more attributes on each win's line, after the adapter's own (a final-sale stamp, say) |
+| `extraCartAttributes` | no | `(lines) => ShopifyAttribute[]`: more attributes on the cart, after the adapter's own (an attribution record, say) |
+
+- `productsByIds(ids)`: one `products.byIds` read. A bare id becomes a product GID, a missing product is
+  left out, and each `LiveProduct` keeps the Shopify `Product` on `raw`. Each variant carries its own
+  photo, when it has one (`imageUrl`, 0.9.0).
+- `createAuctionCheckout(wins, auctionId)`: the contract above. A cart of its own; each win a line of
+  one stamped `_winningBid` (or `prizeWriteKey: "true"`) and `_winIndex`; the giveaway discount codes;
+  `source_name`, `source_type: "auction"`, `auction_id`; the buyer when there is one (a guest cart when
+  there isn't, or reading it fails). Each win is charged on the variant `useAuctionWins` shows: the
+  recorded one when it belongs to the product, else the first that can be sold, else the first. Throws
+  when there is nothing to check out or none of the wins can be sold.
+
+**`createShopifyLiveIdentity(readCustomer)`** takes a function that returns sdk-shopify's
+`useCustomer()` result as it is now (keep it in a ref, as above), and calls it each time the SDK asks.
+It returns:
+
+- `identity`: `bidderId`, the customer's bare numeric id, and `customerRef`, their GID, both only for a
+  Shopify sign-in (the winner's record is on the Customer Account API, so an email-and-password
+  session can't bid); `customerName`, first and last name; `customerEmail`.
+- `customerAccountRequest`: the customer's own `request`.
+- `buyer`: their access token and email, for `createShopifyLiveCommerce`; null when signed out.
+
+**The cart's giveaway prizes.** The live-selling service adds a won prize to the winner's shopping cart,
+stamped, and the store's cart transform makes it free.
+
+```ts
+import { isGiveawayPrizeLine, prizeLinePrice, useAuctionWins } from '@tiledev/sdk-apptile-live-selling';
+
+const { giveawayVariantIds } = useAuctionWins();          // prizes the host put in with no stamp
+const prize = isGiveawayPrizeLine(line, { keys: ['_isGiveawayItem'] }) ||
+  giveawayVariantIds.has(line.merchandise.id);
+const { nowPerUnit, costsNothing, repriced } = prizeLinePrice(line);
+```
+
+- `isGiveawayPrizeLine(line, { keys? })`: stamped with any of `keys`, with any value but `"false"`.
+  `keys` defaults to `GIVEAWAY_PRIZE_KEYS`, both spellings in use (`_isGiveawayItem`, which the service
+  writes, and `_giveawayItem`, which some auction carts write). A store that reads one passes it.
+  Reading a line as a prize takes its stepper away, so a prize line can't be removed or changed.
+- **The stamp proves a prize, never a price.** The store's repricing may not have run (lines charged
+  in full have been seen), so show what the line costs. `prizeLinePrice(line)`: the line's total
+  shared over its quantity (`nowPerUnit`), because Shopify zeroes the total and leaves
+  `amountPerQuantity` at the full price; `costsNothing` when the total is 0; `repriced` when it is less
+  than the unit price, for the unit price struck through.
+- `useAuctionWins().giveawayVariantIds`: the variants this customer won as prizes (empty on the web).
+
 ## 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.
+minutes out of sync would otherwise close a round that is still open. `auction.closesAt` is already
+moved onto the phone's clock (`endsAtMs − serverOffsetMs`), so `useAuctionCountdown(auction.closesAt)`
+counts the host's time. If the host goes quiet, the session closes the round itself 1 s past the
+deadline: a slow last-instant bid, which also extends the clock, still lands first.
 
 `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:
@@ -289,21 +584,89 @@ const gate = useAuctionBidGate({
   isLoggedIn, biddingOpen: auction.biddingOpen,
   variantCount: biddingProduct?.variants.length ?? 0,
   placeBid: actions.placeBid,
+  // 0.9.0, all optional:
+  atAmountShown: true, round: auction,   // a bid goes out at the amount shown, or not at all
+  startSignIn,                           // the gate signs the shopper in, then comes back to the bid
+  signInLoading,                         // signed in, the bidder still loading: hold, start no sign-in
+  screenOnShow: isFocused,               // back on show still signed out: the held bid is dropped
 });
 
 // gate.blocker: 'signIn' | 'unpaidWins' | 'terms' | 'variant' | null
 gate.requestBid();        // the round's minimum — the slide gesture
 gate.requestBid(250);     // a custom bid
+gate.refusal;             // { id, reason: 'outbid' | 'overCap', amount } | null   (atAmountShown)
+gate.bidOnItsWay;         // true for BID_ON_ITS_WAY_MS (1.2 s) after a bid goes
 ```
 
 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.
+finishing the last panel completes the bid they originally asked for. A held bid belongs to its round:
+when bidding closes it is dropped and its panel closed. Call `gate.refreshUnpaidWins()` from your own
+focus effect, so a customer who leaves to settle a tab is unblocked on return.
+
+- **`atAmountShown`** (with `round: session.auction`): `requestBid()` holds the next bid as it is at the
+  tap, not as it will be once the panels close, and the bid gets a last look at the round as it goes
+  (`bidRefusal`: open with time left, at most the ceiling, at least the next bid). A closed round sends
+  nothing; outbid or over the ceiling sends nothing and sets `refusal` (`amount`: the next bid to beat,
+  or the ceiling) for you to show.
+- **`startSignIn`**: the gate never stops at `signIn`. It holds the bid and starts your sign-in; once
+  `isLoggedIn`, if bidding on that lot is still open, it reads the unpaid wins fresh and goes through the
+  gate again from there. Dropped when the lot closes, when another bid is asked for, or when
+  `screenOnShow` turns true again with the shopper signed out (your Sign In page closed). A sign-in that
+  never leaves the screen keeps it until the lot closes. Without `startSignIn` the gate stops at `signIn`.
+- **`actions.placeBid`** says whether the bid went: `{ sent: true }`, or `{ sent: false, reason }`
+  (`noModerator` is L3, below).
 
 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.
 
+**The round's other rules (0.9.0), pure:**
+
+- `auction.lastWin.isYou`: the shopper led the round as it closed and the winning bid is theirs
+  (`isYourWin`). The room names the winner only by name; this is the best a phone can tell.
+- `lotStateFor(storeProductId, auction, show)`: `'open'` while a round is open on the lot, `'closed'` once
+  won (the record's `winnerCount`, or `auction.wonLotIds`, the lots this phone saw won this show), else
+  `'upcoming'`.
+- The custom bid sheet: `quickBids(nextBid, bidCap)` (the next bid rounded up, plus 5, 20, 60 and 100,
+  none over the ceiling) and `winChance(amount, nextBid)` (`'veryHigh'`: 50 over or double; `'good'`: 20
+  over or half again; `'medium'`: anything over; else `'tooLow'`).
+- The chat: `classifyComment(text)` → `{ kind: 'winner' }` | `{ kind: 'bid', label: 'Bid ', amount:
+  '$64.00' }` | `{ kind: 'plain' }`, for the room's bid and winner lines, which arrive as plain text.
+
+### Giveaways (0.9.0)
+
+```ts
+const entry = useGiveawayEntry({
+  session,                                   // useLiveSession()
+  canEnter: onAir && capabilities.canEnterGiveaway,   // useLiveShow(streamId)
+  isLoggedIn, startSignIn,
+  screenOnShow: isFocused && !signInSheetUp,
+  cartId,
+});
+// entry.open, entry.sheetOpen, entry.openSheet(), entry.closeSheet()
+// entry.enter(typedName?), entry.entering, entry.entryFailed
+// entry.signInToEnter()                     back here signed in, the sheet opens again
+// entry.draw, entry.youWon, entry.drawDone() the draw once its roster is ready; never one from before
+//                                           this screen opened
+
+const { product, variant, readError } = useGiveawayPrize<Product>(entry.open);
+```
+
+- **Signing in to enter:** `signInToEnter()` starts your sign-in (close the sheet first: it is a
+  `Modal`). Once `isLoggedIn` and `screenOnShow`, the sheet opens again if the giveaway is still open and
+  not drawn; the shopper taps Enter themselves. Back on show still signed out, nothing reopens.
+- **The entry:** `actions.enterGiveaway` resolves `{ entered: true }` once the host took it, else
+  `{ entered: false, reason }`; `entryFailed` says so. With a typed name (`enter(name)`), the name is
+  saved first and the entry goes once the session holds it.
+- **"You won":** `giveaway.result.isYou`, by the customer id the record names on this draw's giveaway
+  (`LiveGiveaway.winnerId`) when a read has it, else among those who entered by name, spaces and capitals
+  aside (`sameRoomName`). `youEntered` keeps the entry past the draw.
+- **The prize:** one `productsByIds` read through your adapter when the prize changes, cleared first;
+  `variant` is the one given away. The record's name, variant, price and photo stand in until it
+  answers. `readError` is yours to report.
+- Both hooks take values rather than reading the session, so they run on a stand-in session in your
+  tests, and on the web, where the session is idle.
+
 ## 6. Platform boundaries
 
 Two pairs of files here, and Metro picks by platform. TypeScript resolves the non-native one, which
@@ -312,7 +675,7 @@ lives in the native package.)
 
 | 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` |
+| `engine.native.ts` — hands the real Zego module, `Platform.OS`, picture-in-picture and the token call to `ZegoLiveEngine` (`zegoEngine.ts`), which owns the room, plays into a rebindable view, publishes a guest's camera, and translates every Zego channel into a `LiveEvent` | `engine.ts` — no-op, `isNoop: true` |
 | `react/index.ts` — the real providers, hooks and video target | `react/index.web.ts` — real client and read hooks, idle session, `View` in place of the texture view |
 
 The web file is not only about behaviour. `LiveVideoTarget` requires `zego-express-engine-reactnative`
@@ -328,8 +691,14 @@ 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.
+involved at that moment. Coming back puts the picture where the window took it from: your bubble again
+(`'inapp'`), or, for a window your full-screen player opened (`autoPip`), `'none'` and `onPipRestore` —
+navigate to your live screen, which the SDK can't do itself from above the navigator.
+
+To come back to the same picture with no black frame, keep the bubble's `LiveVideoTarget` mounted and
+active while an iOS window that came from it is up (`pipMode` `'system'`): the engine goes on drawing
+into that view, so the bubble needs no new binding when the window hands it back. Keep the full-screen
+player's view mounted too (its `active` off), as the README's usual `active` expression already does.
 
 ## 7. Imperative client
 
@@ -338,7 +707,7 @@ report state.
 
 | Namespace | Methods |
 |---|---|
-| `streams` | `list` `ongoing` `byId` `zegoToken` |
+| `streams` | `list` `ongoing` `byId` `zegoToken` `commentHistory` `destinationFor` |
 | `auctions` | `recordBid` `enterGiveaway` `hasAcceptedTerms` `acceptTerms` `unpaidStreamIds` `wins` `isBiddingBlocked` |
 | `polls` | `vote` `loadVotedOption` `rememberVote` `forgetVote` |
 | `replays` | `list` `segments` `comments` `incrementViews` |
@@ -349,7 +718,7 @@ report state.
 | `engine` | the Zego engine (above) |
 
 Read hooks for screens that only need data: `useOngoingLive`, `useLiveStreams`, `useStreamInfo`,
-`useReplays`, `useClips`, `useAuction`.
+`useReplays`, `useClips`, `useAuction`; and `useLiveShow`, the session's record for one show (§3).
 
 **`useOngoingLive` is the one hook that polls, on purpose, to make the app experience better.** A
 show that starts while the shopper already has the app open is worth catching, and no event reaches
@@ -368,12 +737,60 @@ turn it off in the config: `ongoingLivePolling: { whenIdleMs, whileLiveMs }` or
 interval. 10,000 apps open at 2 minutes is about 83 requests a second; 100,000 is about 830. Raise
 `whenIdleMs` for a large audience, or send a "show started" push and call `refreshOngoingLive()`.
 
-`useReplays({ playableOnly: true })` keeps only replays with a playable video.
+`useReplays({ playableOnly: true })` keeps only replays with a playable video. `hasRead` (0.9.0) turns
+true when its first read has finished, successfully or not, and stays true: before it, an empty list
+is still loading, not "no shows". Shows hidden from the viewer are left out, so a page can show nothing
+while the archive goes on; read on while the list is empty, `hasRead` and `hasMore`.
+
+**Replays, since 0.9.0:**
+- `useReplays` pages by what the gateway **sent** (`ReplayFeed.receivedCount`), not by what it kept
+  after dropping entries without a playlist. Until 0.9.0 a page with an unplayable entry made the next
+  page overlap it, and a page with nothing playable on it was asked for again forever. An empty page
+  is the end (`hasMore: false`), whatever the gateway's flag says. One read at a time: `loadMore`
+  does nothing while another read or a `refresh` is running.
+- `replays.comments(streamingId)` reads the show's chat file,
+  `https://cdn.apptile.io/assets/live-replay-comments/<streamingId>.json` (no company header). The
+  gateway's `/live-streaming/comments/{id}`, which it read until 0.9.0, answers 404 for every
+  recording. No file (403) means nobody talked: an empty list. The host's own rows keep the name the
+  file gives them, `"You"`; show your brand's name there instead.
 
 `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`.
+`poll*`, `biddingStarted`/`bidInfo`/`biddingClosed`/`auctionWon`, `giveaway*`, `pinnedCommentChanged`,
+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`.
+
+**The engine, since 0.9.0:**
+- Zego hands messages over in **batches**; every entry of a barrage, broadcast or stream-extra-info
+  batch is read. Until 0.9.0 only the first was, and the rest vanished.
+- A room counts as joined only once `loginRoom` succeeds. A refused login is tried 3 times (waiting
+  1 s, then 2 s), and a join that failed can simply be asked for again — before, a failed login left
+  the engine believing it was in the room, and every later join for that show returned early.
+- `roomTokenWillExpire` fetches a fresh token (`streams.zegoToken`) and calls `renewToken`, so a long
+  watch is no longer dropped when the token runs out.
+- A subscriber that throws is logged and skipped; leaving never throws; and only this package's own
+  Zego handlers are ever detached (L16 — `playerQualityUpdate` was attached twice).
+- `bidInfo` carries `moderatorId` when the gateway sends one, and the session remembers the last
+  moderator of the show, so a viewer who missed a round's opening can still bid when one is known.
+  When none is, `placeBid` logs a warning and sends nothing — not even the REST ledger record — and
+  resolves `{ sent: false, reason: 'noModerator' }`, so an app can tell the shopper.
+
+### Needs the backend
+
+The SDK reads these the moment they exist; until then the gaps above remain.
+
+- **The moderator on bid info (L3).** Add `moderatorInCharge` (the same `{ userID, userName }` that
+  `START_BIDDING` carries) to every `BROADCAST_BID_INFO` `data`, and to the stream record while a round
+  is open. Without it, a viewer who joined after the round opened — and has not heard any earlier
+  round's opening this show — has nobody to address `BID_PLACED` to.
+- **A winner id.** The SDK reads only a display name from `BID_WINNER_ANNOUNCEMENT`
+  (`bidWinner.meta.user.userName`) and from `giveaway_end` (`winner.displayName`). So an auction's
+  "you won" is inferred (the shopper led as the round closed, at the winning amount), and a giveaway's
+  is matched by name unless a record read after the draw carries the drawn giveaway's `winner` (a
+  customer GID, read since 0.9.0). Send the winner's customer id on both events — the same bare id
+  `BROADCAST_BID_INFO.user.userId` uses — and the SDK can compare it with `identity.bidderId()`.
+- **Entrant names on `giveaway_end`.** The reveal's roster is read back off the record because the end
+  event names only the winner, and the record lags it (ENG-705). Send the entrant display names (or a
+  sample) on the event and the 5-second wait goes away.
 
 ## Releasing
 
@@ -419,9 +836,10 @@ two copies of the same Expo module, and identical pod and module names collide a
 | `npm run build` | Cleans and compiles `src` → `dist` |
 | `npm run lint` | Typechecks, emitting nothing |
 | `npm run clean` | Removes `dist` |
+| `npm test` | Compiles `src` + `test` to `.test-dist` and runs `node --test` — the reducer, the engine (against a stand-in Zego), the transport and the mappers |
 | `npm pack` | The publish tarball — `dist`, `types`, `session` and nothing native |
 
-The reducer is exported on its own (`sessionReducer`, `deriveStatus`, `timeLeftMs`) and is pure, so it
+The reducer is exported on its own (`sessionReducer`, `deriveStatus`, `roundClosesAt`, `nextExpiryAt`) and is pure, so it
 can be driven with no room, socket or React — from Node, import it as
 `@tiledev/sdk-apptile-live-selling/session` rather than off the root.