@xorgate/react-native 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 0.2.0
+
+Replay: the recorded-media player, over `expo-video`.
+
+- **Needs `@xorgate/react` 0.2.1 or later**, which is where `useReplayTelemetry`
+  takes the player CORE rather than the browser wrapper — the change that lets a
+  React Native player drive replay telemetry at all. The declared range stays
+  `^0.2.0-next.1` because it already admits 0.2.1 and a tighter one cannot be
+  installed until 0.2.1 is on npm; the only way to get the wrong types is a
+  lockfile pinned at the pre-release, where `useReplayTelemetry(deviceId,
+  player)` will not typecheck. Publish `@xorgate/react` 0.2.1 first.
+- **`expo-video` is a new required peer.** It is the native player; there is no
+  way to play a recorded segment without it, and an optional peer whose absence
+  fails deep inside a lane is worse than one line of install (the same call
+  `expo-crypto` got in 0.1.0). Installing it moves the native fingerprint.
+- `useReplayPlayer(manifest, options)` — `@xorgate/react`'s
+  `useReplayPlayerCore` with native media bound to every lane. The transport,
+  the clock, the lanes and `laneState` are the web package's; what is added is
+  `lanePlayer(streamKey)` and `laneMedia(streamKey)`, and the pool of players
+  behind them. `createVideoPlayer` is manual memory, so the hook creates a
+  pair per lane lazily and releases it when the lane goes or the hook unmounts.
+- `<ReplayVideo player streamKey />` — both of a lane's views, the hidden one
+  at zero opacity, `nativeControls` off.
+- `ExpoVideoReplayEngine` — one lane over two players, implementing
+  `@xorgate/react`'s `ReplayEngine`. A phone has no Media Source Extensions:
+  `AVPlayer` and `ExoPlayer` play a FILE, and a recorded segment is a
+  self-contained fMP4 that cannot be concatenated at runtime. So a lane is two
+  players and a boundary is an opacity flip. Four decisions the real segments
+  forced, all measured before the code was written:
+  - **The boundary is the manifest's** `effectiveDurationMs`, not the file's
+    end — a segment's file runs past the next one's start and playing that tail
+    would show the same wall clock twice. `playToEnd` is the fallback for the
+    opposite case, a file shorter than the manifest claims.
+  - **Readiness is the `statusChange` event, never the `replaceAsync`
+    promise**, which resolves with `status` still `loading`; `bufferedPosition`
+    can answer for the previous item until then.
+  - **Prepare early, promote on time.** The next segment is loaded and parked
+    on its first frame half a second out, and played only when the outgoing
+    player actually reaches the boundary — swapping at the lead would silently
+    drop it, once per segment.
+  - **A cross-segment seek always loads onto the hidden player**, so the
+    outgoing picture stays up for the 1.3-5.3 s the download takes instead of
+    going black.
+- A failed segment load is probed with a one-byte ranged GET on the same
+  presigned URL, because a native player never reports the HTTP status: 403
+  becomes `onAuthError` (the manifest refresh, as in the browser engine) and
+  404/410 becomes a media error. Anything else retries.
+- `useReplayPlayer(manifest, { debug })` — every decision a lane makes, as one
+  line, off by default. A seam is tens of milliseconds wide and the native
+  player is the half you cannot step through, so a boundary that did NOT
+  happen has to be able to leave evidence. It is what found the four defects
+  below, none of which any test had caught.
+
+**Four things the device corrected, all at the same place: a segment boundary.**
+On the first real 3-segment session a whole 60 s segment vanished — 57.7 s of a
+145.6 s replay, silently — and it took all four lining up:
+
+1. **A preloaded player is not parked at 0.** One was caught at 15.68 s, and
+   promoting it would have started that segment a quarter of the way in. On
+   iOS a playback RATE is the transport, so setting the rate on a paused
+   preload starts it playing. The rate now goes only on the player that is
+   about to play, and the incoming player is seeked unconditionally rather
+   than only for a non-zero offset.
+2. **Promoting does not move the playhead.** The clock is paced BY the lane
+   and only learns the new position on its next tick, so the very next
+   `ensureAt` arrives with a timestamp a few milliseconds BEFORE the boundary
+   — which dragged the lane back into the segment it had just left, which the
+   next tick undid, and so on. A move back into a just-crossed segment is now
+   ignored for a second.
+3. **The boundary must be released whether or not the player says so.** The
+   last `timeUpdate` of a segment lands 60-80 ms short of the file's end, and
+   `playToEnd` / `playingChange` follow a beat later. A timer armed when the
+   lead-in is prepared — for the expected end plus 120 ms — closes that, and
+   deliberately fires LATE: early skips real video, late only holds a frame.
+   A segment's end is `min(manifest, file)`, because a file can fall short of
+   what the manifest claims (60.000 s claimed, 59.987 s of media).
+4. **A lane waiting on a prepared lead-in must not report itself stalled.**
+   It did, so the player core's stall recovery ran — and with the playhead
+   already inside the NEXT segment, that recovery seeks to the END of it.
+   That is the line that actually ate the 57.7 s.
+
+Two more it showed, away from the boundary:
+
+- **A seek holds the outgoing picture STILL**, not merely on screen. The
+  outgoing player used to keep playing for the seconds a cross-segment
+  download takes — six of them, on one measured seek — while the transport bar
+  already read the seek target, so the picture and the clock were describing
+  different moments. A boundary lead-in is deliberately exempt: there the
+  outgoing segment is still the right one, right up to its last frame.
+- **A torn-down lane dies quietly.** The players belong to the hook, and one
+  that has been released throws `NotFoundException` on every access; the hook
+  now destroys engines before releasing players rather than trusting React's
+  cleanup order, and an engine handed a dead pair goes inert instead of
+  throwing into the tree.
+
 ## 0.1.0
 
 First release: live telemetry and live video on React Native, over

package/dist/index.d.ts

@@ -5,14 +5,17 @@
  * re-exported here, so an app imports from ONE package: the data hooks, live
  * telemetry, the live-block policy, the replay timeline and clock, the
  * telemetry math, the types. What this package adds is the runtime underneath
- * them (`nativePlatform`, `XorgateNativeProvider`) and the two pieces that
- * cannot be neutral because they are pixels: `useLiveVideo` / `LiveVideo` over
- * react-native-webrtc's `RTCView`.
+ * them (`nativePlatform`, `XorgateNativeProvider`) and the pieces that cannot
+ * be neutral because they are pixels: `useLiveVideo` / `LiveVideo` over
+ * react-native-webrtc's `RTCView`, and `useReplayPlayer` / `ReplayVideo` over
+ * expo-video.
  *
  * The browser-only exports of `@xorgate/react` — its `useLiveVideo`,
  * `LiveVideo`, `useReplayPlayer`, `ReplayVideo` and the `browser*` platform
  * helpers — are deliberately NOT re-exported: they need `HTMLVideoElement`,
- * `window` or Media Source Extensions, none of which exist here. Importing
+ * `window` or Media Source Extensions, none of which exist here. The four
+ * names are SHADOWED by the native implementations above, so an app that
+ * imports from this package gets the one that works on a phone; importing
  * `@xorgate/react` directly still works and is how you reach them on web.
  */
 export { nativePlatform, type NativePlatformOptions } from "./platform.js";
@@ -21,5 +24,8 @@ export { appStateWake, composeWake, type WakeSource } from "./wake.js";
 export { XorgateNativeProvider, type XorgateNativeProviderProps, } from "./provider.js";
 export { useLiveVideo, type UseLiveVideo, type UseLiveVideoOptions, } from "./use-live-video.js";
 export { LiveVideo, type LiveVideoProps } from "./live-video.js";
+export { ExpoVideoReplayEngine, type ExpoVideoReplayEngineOptions, } from "./replay-engine.js";
+export { useReplayPlayer, type UseReplayPlayer, type UseReplayPlayerNativeOptions, type ReplayLaneMedia, type ReplayLaneState, type ReplayLaneStatus, type UseReplayPlayerOptions, } from "./use-replay-player.js";
+export { ReplayVideo, type ReplayVideoProps } from "./replay-video.js";
 export { XorgateProvider, useXorgate, useXorgateTenancy, DEFAULT_BASE_URL, type XorgateProviderProps, type XorgateConfig, type XorgateAuth, type FirstPartyAuth, type SessionTokenAuth, type ApiKeyAuth, type LiveCredentialsAuth, type LiveCredentials, type LiveUnavailableReason, type Awaitable, type XorgatePlatform, XorgateError, isXorgateError, type Device, type DeviceModel, type LatestByMetric, type LatestReading, type MediaSession, type Me, type MetricName, type Organization, type PageMeta, type RecordingRun, type ReplayGap, type ReplayManifest, type ReplaySegment, type ReplaySession, type StreamKey, type TelemetryHistory, type TelemetryReading, type VideoChannel, type Workspace, type XorgateClient, useMe, useOrganizations, useWorkspaces, useDevices, useDevice, useDeviceModel, useTelemetryLatest, useTelemetryHistory, useVideoChannels, useRecordingRuns, useSessions, type QueryResult, type QueryOptions, type UseDevicesParams, type UseDevicesResult, type UseTelemetryHistoryParams, type UseSessionsParams, type UseRunsResult, type UseSessionsResult, useLiveTelemetry, useLivePlane, useLiveCredentials, parseTelemetryPayload, presignIotWssUrl, type UseLiveTelemetry, type UseLiveTelemetryOptions, type LiveStatus, type TelemetryPoint, type TelemetrySnapshot, type TelemetryFeedDeps, type MqttLikeClient, type MqttConnectionSpec, type ResolvedLiveCredentials, type ParsedTelemetryPayload, type TelemetryRecordingStatus, type TelemetryMediaStatus, type TelemetryStreamStatus, type LiveBlockPayload, useLiveBlock, resolveLiveBlock, liveBlockElapsedMs, LIVE_BLOCK_STALE_MS, type LiveBlockReason, type LiveBlockOpenReason, type LiveBlockState, type ResolveLiveBlockInput, useLiveVideoSession, type UseLiveVideoSession, type UseLiveVideoSessionOptions, type LiveVideoStatus, type LiveVideoStats, type WebRtcPlatform, type PeerConnectionLike, type SignalingLike, type TimerHost, useReplayManifest, useReplayPlayerCore, useReplayTelemetry, buildTimeline, segmentEnd, segmentAt, hasCoverageAt, gapAt, nextSegmentAfter, prevBoundary, nextBoundary, clampTs, buildLanes, buildClockTimeline, segmentUrlKey, ReplayClock, REPLAY_RATES, parseSegmentMediaInfo, seriesFromReadings, floorIndex, latestWithin, metricGroup, stalenessMs, overviewStalenessMs, chooseIntervalSeconds, windowBoundsFor, windowNeedsRefetch, buildTrace, traceLines, traveledLines, positionAt, GROUP_STALENESS_MS, DEFAULT_STALENESS_MS, WINDOW_SPAN_MS, WINDOW_MIN_SPAN_MS, type UseReplayManifestParams, type UseReplayManifestResult, type UseReplayPlayerCore, type UseReplayTelemetry, type UseReplayTelemetryOptions, type ReplayEngine, type ReplayEngineOptions, type ReplayEngineFactory, type ReplayTimeline, type ReplayLane, type LaneSegment, type ReplayClockState, type ReplayRate, type PacerCandidate, type GapSkipEvent, type SegmentMediaInfo, type MetricSeries, type GpsTrace, type WindowBounds, type PositionResolution, } from "@xorgate/react";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,eAAe,CAAC;AAMvB,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMjE,OAAO,EACL,qBAAqB,EACrB,KAAK,4BAA4B,GAClC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAMvE,OAAO,EAEL,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,eAAe,EAGpB,YAAY,EACZ,cAAc,EACd,KAAK,MAAM,EACX,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,EAAE,EACP,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,aAAa,EAGlB,KAAK,EACL,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EAGtB,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAGrB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAG1B,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,SAAS,EAGd,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,KAAK,EACL,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -5,14 +5,17 @@
  * re-exported here, so an app imports from ONE package: the data hooks, live
  * telemetry, the live-block policy, the replay timeline and clock, the
  * telemetry math, the types. What this package adds is the runtime underneath
- * them (`nativePlatform`, `XorgateNativeProvider`) and the two pieces that
- * cannot be neutral because they are pixels: `useLiveVideo` / `LiveVideo` over
- * react-native-webrtc's `RTCView`.
+ * them (`nativePlatform`, `XorgateNativeProvider`) and the pieces that cannot
+ * be neutral because they are pixels: `useLiveVideo` / `LiveVideo` over
+ * react-native-webrtc's `RTCView`, and `useReplayPlayer` / `ReplayVideo` over
+ * expo-video.
  *
  * The browser-only exports of `@xorgate/react` — its `useLiveVideo`,
  * `LiveVideo`, `useReplayPlayer`, `ReplayVideo` and the `browser*` platform
  * helpers — are deliberately NOT re-exported: they need `HTMLVideoElement`,
- * `window` or Media Source Extensions, none of which exist here. Importing
+ * `window` or Media Source Extensions, none of which exist here. The four
+ * names are SHADOWED by the native implementations above, so an app that
+ * imports from this package gets the one that works on a phone; importing
  * `@xorgate/react` directly still works and is how you reach them on web.
  */
 // ---------------------------------------------------------------------------
@@ -28,6 +31,12 @@ export { XorgateNativeProvider, } from "./provider.js";
 export { useLiveVideo, } from "./use-live-video.js";
 export { LiveVideo } from "./live-video.js";
 // ---------------------------------------------------------------------------
+// Replay (expo-video)
+// ---------------------------------------------------------------------------
+export { ExpoVideoReplayEngine, } from "./replay-engine.js";
+export { useReplayPlayer, } from "./use-replay-player.js";
+export { ReplayVideo } from "./replay-video.js";
+// ---------------------------------------------------------------------------
 // Re-exported unchanged from `@xorgate/react`
 // ---------------------------------------------------------------------------
 export { 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,OAAO,EAAE,cAAc,EAA8B,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAmB,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,qBAAqB,GAEtB,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,OAAO,EACL,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAuB,MAAM,iBAAiB,CAAC;AAEjE,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E,OAAO;AACL,uBAAuB;AACvB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,gBAAgB;AAahB,oCAAoC;AACpC,YAAY,EACZ,cAAc;AAsBd,aAAa;AACb,KAAK,EACL,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW;AAUX,oCAAoC;AACpC,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB;AAgBhB,oBAAoB;AACpB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB;AAMnB,mDAAmD;AACnD,mBAAmB;AAUnB,4EAA4E;AAC5E,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,KAAK,EACL,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GAqBnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,OAAO,EAAE,cAAc,EAA8B,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAmB,MAAM,WAAW,CAAC;AACvE,OAAO,EACL,qBAAqB,GAEtB,MAAM,eAAe,CAAC;AAEvB,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,OAAO,EACL,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAuB,MAAM,iBAAiB,CAAC;AAEjE,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,OAAO,EACL,qBAAqB,GAEtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,GAOhB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAyB,MAAM,mBAAmB,CAAC;AAEvE,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E,OAAO;AACL,uBAAuB;AACvB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,gBAAgB;AAahB,oCAAoC;AACpC,YAAY,EACZ,cAAc;AAsBd,aAAa;AACb,KAAK,EACL,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW;AAUX,oCAAoC;AACpC,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB;AAgBhB,oBAAoB;AACpB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB;AAMnB,mDAAmD;AACnD,mBAAmB;AAUnB,4EAA4E;AAC5E,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,KAAK,EACL,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GAqBnB,MAAM,gBAAgB,CAAC"}

package/dist/replay-engine.d.ts

@@ -0,0 +1,193 @@
+import { type ReplayEngine, type ReplayEngineOptions } from "@xorgate/react";
+import type { VideoPlayer } from "expo-video";
+export interface ExpoVideoReplayEngineOptions extends ReplayEngineOptions {
+    /**
+     * The lane's two players. The engine drives them but does not own them:
+     * `useReplayPlayer` creates and releases the pair, the same way the browser
+     * engine is handed a `<video>` it did not create.
+     */
+    players: readonly [VideoPlayer, VideoPlayer];
+    /** The player on screen changed. The hook re-renders so the views swap. */
+    onActivePlayerChange?: () => void;
+    /**
+     * Every decision this lane makes, as one line. Off by default and costing
+     * nothing when unset. A replay seam is tens of milliseconds wide and the
+     * native player is the half you cannot step through, so the only way to
+     * find out why a boundary did or did not happen is to have the engine say
+     * so at the time.
+     */
+    onDebug?: (message: string) => void;
+}
+/**
+ * One replay lane over two `expo-video` players (replay option A).
+ *
+ * The browser plays a lane as ONE `<video>` fed by Media Source Extensions:
+ * segments are appended into a single continuous buffer and there is no seam
+ * to manage. A phone has no MSE. `AVPlayer` and `ExoPlayer` play a FILE, and
+ * every recorded segment is a self-contained fMP4 (own `ftyp`+`moov`, `tfdt`
+ * from 0) — an ordinary playable MP4, and nothing that can be concatenated at
+ * runtime. So a lane is two players: one showing segment N while the other
+ * already holds N+1, and a boundary is an opacity swap between two views that
+ * are both mounted.
+ *
+ * Four things shape the code, all measured on real segments before it was
+ * written (SPIKES.md §4):
+ *
+ * - **The boundary is the MANIFEST's** (`effectiveDurationMs`), not the file's
+ *   end: a segment's file routinely runs past the next segment's start
+ *   (`fstat` anchors), and playing that tail would show the same wall clock
+ *   twice. `playToEnd` is the fallback for the opposite case, a file SHORTER
+ *   than the manifest claims.
+ * - **Readiness is an event, not a promise.** `replaceAsync` resolves with
+ *   `status` still `loading`, and `bufferedPosition` can report the previous
+ *   item's value for a beat afterwards. Nothing here trusts a player until
+ *   `statusChange → readyToPlay`.
+ * - **Prepare early, promote on time.** The incoming player is loaded and
+ *   parked on its first frame half a second before the boundary, but it is
+ *   not played until the outgoing one actually reaches the boundary. That is
+ *   what makes the seam a picture change with no playhead jump — swapping
+ *   early would silently skip the lead, once per segment.
+ * - **A cross-segment seek is download-bound** (1.3-5.3 s for a 6-13 MB
+ *   segment), so it always loads onto the HIDDEN player and the outgoing
+ *   picture stays up until the new one has a frame. Replacing the visible
+ *   player's source instead is seconds of black.
+ *
+ * Positions are lane-local seconds, as `ReplayEngine` requires; the wall clock
+ * stays the player core's business.
+ */
+export declare class ExpoVideoReplayEngine implements ReplayEngine {
+    private readonly timeline;
+    private readonly getUrl;
+    private readonly onError;
+    private readonly onUpdate;
+    private readonly onAuthError;
+    private readonly onActivePlayerChange;
+    private readonly onDebug;
+    private readonly slots;
+    private activeIdx;
+    private activation;
+    private boundaryTimer;
+    private wantPlay;
+    private rate;
+    private destroyed;
+    private firstFrameFired;
+    /** Lane-local seconds, kept so `position` is honest while nothing is ready. */
+    private lastPos;
+    /** The last position the active player was seen at, and when — see `watchStall`. */
+    private stalledAt;
+    private stalledSince;
+    /** The segment most recently left at a boundary, and when. See `activate`. */
+    private crossed;
+    private readonly failedAt;
+    private readonly probing;
+    private readonly abort;
+    private readonly waitingCbs;
+    private readonly firstFrameCbs;
+    constructor(opts: ExpoVideoReplayEngineOptions);
+    private makeSlot;
+    get position(): number;
+    get paused(): boolean;
+    /** The player whose picture belongs on screen. */
+    get activePlayer(): VideoPlayer;
+    /** Which of the two players `activePlayer` is. */
+    get activeIndex(): 0 | 1;
+    buffered(): Array<{
+        start: number;
+        end: number;
+    }>;
+    isBufferedAt(posSec: number): boolean;
+    isStalled(): boolean;
+    seek(posSec: number): void;
+    play(): void;
+    pause(): void;
+    setRate(rate: number): void;
+    /**
+     * Keep the media around `ts` — and the segment after it — loaded. Called at
+     * clock-notify rate and from the core's 500 ms pump, so every path is
+     * guarded: steady state does no work.
+     */
+    ensureAt(ts: number): void;
+    on(event: "waiting" | "firstFrame", cb: () => void): () => void;
+    destroy(): void;
+    private debug;
+    /** One line of state, for a debug message that has to explain a decision. */
+    private snapshot;
+    private segPos;
+    private slotHolding;
+    /**
+     * Only the player on screen ever plays; the other one is preload.
+     *
+     * Every write below goes through JSI to a native object the hook owns, and
+     * a call on one that has been released throws `NotFoundException` rather
+     * than returning — so nothing here may run after `destroy()`.
+     */
+    private applyTransport;
+    /**
+     * Bring `seg` to the front at `offsetSec`, always through the HIDDEN player
+     * so the picture on screen survives the load.
+     */
+    private activate;
+    private cancelActivation;
+    /** Park the incoming player on the frame it will be promoted with. */
+    private prepare;
+    private maybePromote;
+    /** One segment of look-ahead on the hidden player — what makes a boundary free. */
+    /**
+     * Cross the boundary on time even if the outgoing player never says it is
+     * finished. Armed when the lead-in is prepared, for the moment the segment
+     * is expected to run out plus a short grace, and re-armed rather than fired
+     * if the player is somehow still behind that (a pause, a slower rate). An
+     * event almost always beats it; what it buys is that none of them has to,
+     * and that the swap lands AFTER the end rather than before it — a timer
+     * that fires early skips real video, one that fires late holds a frame.
+     */
+    private armBoundaryTimer;
+    private onBoundaryTimer;
+    private clearBoundaryTimer;
+    private prefetchAfter;
+    private load;
+    /**
+     * The player on screen has stopped advancing while the transport says play.
+     * That is a segment that has run out of file without saying so — and it is
+     * the state that must never be left alone, because the player core's stall
+     * recovery reads the playhead (already inside the NEXT segment) rather than
+     * the media, and jumps to the end of a segment that was never shown.
+     */
+    private watchStall;
+    private markReady;
+    /**
+     * The one case `statusChange` cannot report: a player that was already
+     * `readyToPlay` and whose new item loaded without the status ever leaving
+     * that value. Runs off the core's pump, so it costs nothing in steady state.
+     */
+    private reconcileReady;
+    private onTimeUpdate;
+    private onPlayToEnd;
+    /**
+     * The outgoing segment is finished, however we found out. With a lead-in
+     * already prepared this swaps; without one — the file ran out well before
+     * the manifest said it would, which `fstat`-anchored rows do — it starts
+     * the next segment now rather than leave the clock on a player that will
+     * never advance again.
+     */
+    private releaseBoundary;
+    /**
+     * Where this player's segment really ends, in its own seconds: the manifest
+     * duration, or the file's if the file is shorter. A file that outruns the
+     * manifest must be cut at the manifest (its tail is the next segment's wall
+     * clock); a file that falls short can only be played to its own end, and
+     * waiting for a boundary it can never reach is what freezes a lane.
+     */
+    private endOf;
+    private contiguousNext;
+    private onStatusChange;
+    /**
+     * A native player reports that a source would not load, and never why: the
+     * HTTP status is not on the error. A one-byte ranged GET against the same
+     * presigned URL is the cheapest way to tell an expired signature (403 —
+     * refresh the manifest, exactly as the browser engine does) from a network
+     * blip (retry), and it only ever runs on a failure.
+     */
+    private onLoadFailure;
+}
+//# sourceMappingURL=replay-engine.d.ts.map

package/dist/replay-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-engine.d.ts","sourceRoot":"","sources":["../src/replay-engine.ts"],"names":[],"mappings":"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"}