From 4eddc591f227f3ad189865b1c4a22c81eb1f7be0 Mon Sep 17 00:00:00 2001
From: Makisuo <minetoaster12@gmail.com>
Date: Fri, 14 Aug 2026 02:24:27 +0200
Subject: [PATCH 1/3] feat(replays): play video-backed sessions behind a replay
 engine seam
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The player hardcoded `new Replayer(...)`, so rrweb was the only thing it
could ever play. Mobile sessions record H.264 segments wrapped in
rrweb-shaped events — the chunk pipeline carries them fine, but rrweb
finds no DOM to rebuild and renders nothing.

Engine construction, the clock, seeking and letterboxing now sit behind
`ReplayEngine`, with two implementations: the existing rrweb Replayer
(moved over unchanged, including its negative-baseline clock guard) and
a video engine that decodes each base64 segment to a Blob URL and drives
one `<video>` element. Because every segment opens on an IDR keyframe,
an offset resolves to (segment, offset-within-segment) exactly — a seek
into a gap between segments snaps forward to the next real footage.

Nothing below the context changed: the surface, transport, editor
timeline, events rail and chunk loader are untouched, and the existing
player tests pass as written.

Two correctness fixes fall out of supporting both formats:

- Idle derivation treated every event as an instant. A video session
  emits ~one event per 30s segment, so each quiet segment read as a 30s
  idle band and skip-idle (on by default) collapsed the recording to
  nothing. A segment now spans its duration, so only real gaps — the
  recorder stopping while the app is backgrounded — stay collapsible.
- Marker extraction only matched MouseInteractions.Click, so touch
  sessions produced no click markers. TouchStart now counts, which also
  fixes mobile-web rrweb sessions that never had markers either.

Format selection rides `maple.session.replay_format` in the existing
ResourceAttributes map, so there is no warehouse migration and no wire
change: the detail query already ships the whole map as JSON, and the
route prefetches it, so the engine is chosen before any chunk is
fetched. An absent key means rrweb — every session recorded before the
marker existed is a browser recording.

Also stop `normalizeEvents` from running JSON.stringify over both sides
of every adjacent pair; with a base64 MP4 inside each event that
serialized hundreds of KB per comparison on every range decode.
---
 .../replays/engine/replay-engine.ts           |  88 +++++
 .../components/replays/engine/rrweb-engine.ts | 107 ++++++
 .../replays/engine/video-engine.test.ts       | 155 +++++++++
 .../components/replays/engine/video-engine.ts | 310 ++++++++++++++++++
 .../src/components/replays/replay-events.ts   |  22 +-
 .../components/replays/replay-format.test.ts  |  37 ++-
 .../src/components/replays/replay-format.ts   |  26 ++
 .../replays/replay-player-context.test.ts     | 100 +++++-
 .../replays/replay-player-context.tsx         | 213 ++++++------
 .../src/components/replays/replay-studio.tsx  |   7 +-
 packages/browser-session/src/meta-row.test.ts |  34 ++
 packages/browser-session/src/meta-row.ts      |   7 +
 12 files changed, 1000 insertions(+), 106 deletions(-)
 create mode 100644 apps/web/src/components/replays/engine/replay-engine.ts
 create mode 100644 apps/web/src/components/replays/engine/rrweb-engine.ts
 create mode 100644 apps/web/src/components/replays/engine/video-engine.test.ts
 create mode 100644 apps/web/src/components/replays/engine/video-engine.ts

diff --git a/apps/web/src/components/replays/engine/replay-engine.ts b/apps/web/src/components/replays/engine/replay-engine.ts
new file mode 100644
index 000000000..26b483606
--- /dev/null
+++ b/apps/web/src/components/replays/engine/replay-engine.ts
@@ -0,0 +1,88 @@
+// The replay engine seam
+//
+// The player used to construct `new Replayer(...)` inline, which made rrweb the
+// only thing it could ever play. The iOS SDK records H.264 segments and wraps
+// each one in rrweb-*shaped* events so the chunk pipeline carries them
+// untouched — but there is no DOM to rebuild, so rrweb renders nothing.
+//
+// Everything above this interface (the provider's transport state, the trimmed
+// timeline, markers, idle bands, the chunk loader) is format-agnostic and stays
+// exactly as it was. Everything rrweb-specific lives in `rrweb-engine.ts`;
+// everything video-specific in `video-engine.ts`.
+//
+// The contract is deliberately shaped like the rrweb surface the provider
+// already depended on, so the refactor is behaviour-preserving:
+//
+//   new Replayer(events, {root})   -> ReplayEngineFactory.create({mount, events})
+//   getMetaData().totalTime        -> totalTimeMs
+//   getCurrentTime()               -> getCurrentTimeMs()
+//   play(o) / pause(o?)            -> play(o) / pause(o?)
+//   setConfig({speed})             -> setSpeed(speed)
+//   addEvent(e)                    -> addEvent(e)
+//   destroy()                      -> destroy()
+//   on(Finish) / on(Resize)        -> onFinish / onResize callbacks
+//   .iframe + .wrapper.style       -> fit(container)
+
+/** The recorded viewport, used to letterbox the recording inside the surface. */
+export interface Viewport {
+	readonly width: number
+	readonly height: number
+}
+
+export interface ReplayEngineCreateInput {
+	/** The surface's inner div. The engine owns its contents entirely. */
+	readonly mount: HTMLElement
+	/** The seed events. Later events arrive through `addEvent`, forward-only. */
+	readonly events: ReadonlyArray<unknown>
+	/**
+	 * Viewport to fall back to when the engine can't report its own — derived
+	 * from the stream's `meta` events by `deriveMeta`.
+	 */
+	readonly fallbackViewport: Viewport
+	/** Playback reached the end of the recording. */
+	onFinish(): void
+	/** The recorded viewport changed mid-session; the surface must re-fit. */
+	onResize(): void
+}
+
+export interface ReplayEngine {
+	/** Length of the loaded recording, in real ms. */
+	readonly totalTimeMs: number
+	/**
+	 * Playhead as a real-ms offset from session start, matching the clock the
+	 * trimmed `Timeline` and backend span alignment are built against.
+	 *
+	 * Implementations must never return a negative or non-finite value — the
+	 * provider feeds this straight back into `play()`.
+	 */
+	getCurrentTimeMs(): number
+	play(offsetMs: number): void
+	/** With no offset, hold at the current position. */
+	pause(offsetMs?: number): void
+	setSpeed(speed: number): void
+	/**
+	 * Append an event that arrived after construction.
+	 *
+	 * Forward-only by contract: every trailing event postdates the seed. A
+	 * backward seek rebuilds the engine from the nearest checkpoint instead
+	 * (see `requestSeek` in `use-replay-chunk-loader.ts`).
+	 */
+	addEvent(event: unknown): void
+	/** Fit the recording inside `container`, letterboxed and centred. */
+	fit(container: HTMLElement): void
+	destroy(): void
+}
+
+export interface ReplayEngineFactory {
+	create(input: ReplayEngineCreateInput): ReplayEngine
+}
+
+/**
+ * Which engine plays a session's chunks.
+ *
+ * Carried by the `maple.session.replay_format` resource attribute so the player
+ * can pick an engine from session metadata alone, without downloading a chunk
+ * to find out. An absent attribute means `rrweb` — every session recorded
+ * before the marker existed is a browser recording.
+ */
+export type ReplayFormat = "rrweb" | "video"
diff --git a/apps/web/src/components/replays/engine/rrweb-engine.ts b/apps/web/src/components/replays/engine/rrweb-engine.ts
new file mode 100644
index 000000000..ac8a0cee8
--- /dev/null
+++ b/apps/web/src/components/replays/engine/rrweb-engine.ts
@@ -0,0 +1,107 @@
+import { Replayer } from "@rrweb/replay"
+import { ReplayerEvents } from "@rrweb/types"
+import type { ReplayEngine, ReplayEngineCreateInput, ReplayEngineFactory } from "./replay-engine"
+
+// The rrweb engine — browser recordings.
+//
+// This is the behaviour the player has always had, moved behind the engine
+// interface unchanged. Every quirk documented here was a shipped bug once.
+
+class RrwebEngine implements ReplayEngine {
+	private readonly replayer: Replayer
+	private readonly fallbackViewport: ReplayEngineCreateInput["fallbackViewport"]
+
+	constructor(input: ReplayEngineCreateInput) {
+		const accent =
+			getComputedStyle(document.documentElement).getPropertyValue("--primary").trim() || "#6366f1"
+
+		this.fallbackViewport = input.fallbackViewport
+		this.replayer = new Replayer(input.events as never, {
+			root: input.mount,
+			speed: 1,
+			// We skip idle ourselves by jumping (see the provider's rAF loop) —
+			// rrweb's own skipInactive only fast-forwards, which is slow. Keep it off.
+			skipInactive: false,
+			mouseTail: { duration: 600, lineCap: "round", lineWidth: 3, strokeStyle: accent },
+			showWarning: false,
+			showDebug: false,
+			liveMode: false,
+		})
+
+		// rrweb's own transport events are unreliable in @rrweb/replay (Start/Resume
+		// often don't fire); play/pause state is driven from the provider's handlers.
+		// We still honour Finish to flip back to the replay affordance at the end.
+		this.replayer.on(ReplayerEvents.Finish, () => input.onFinish())
+		// The recorded viewport can change mid-session (responsive / window resize);
+		// rrweb resizes its iframe and emits Resize. Also fires for the initial snapshot.
+		this.replayer.on(ReplayerEvents.Resize, () => input.onResize())
+	}
+
+	get totalTimeMs(): number {
+		return this.replayer.getMetaData().totalTime
+	}
+
+	/**
+	 * Read the playhead, treating "not started yet" as 0.
+	 *
+	 * rrweb builds its player context with `baselineTime: 0`, and
+	 * `getCurrentTime()` is `timer.timeOffset + (baselineTime - events[0].timestamp)`
+	 * — so until the engine has been driven by a `play()` / `pause(offset)` (the only
+	 * things that assign `baselineTime`), it reports `-events[0].timestamp`: a
+	 * negative epoch, ~55 years. Feeding that back into `play()` re-bases the whole
+	 * stream decades into the future and nothing ever casts, which is what left the
+	 * player frozen at 0:00 until the first scrub re-based it for us.
+	 */
+	getCurrentTimeMs(): number {
+		const ms = this.replayer.getCurrentTime()
+		return Number.isFinite(ms) && ms > 0 ? ms : 0
+	}
+
+	play(offsetMs: number): void {
+		this.replayer.play(offsetMs)
+	}
+
+	pause(offsetMs?: number): void {
+		this.replayer.pause(offsetMs)
+	}
+
+	setSpeed(speed: number): void {
+		this.replayer.setConfig({ speed })
+	}
+
+	addEvent(event: unknown): void {
+		this.replayer.addEvent(event as never)
+	}
+
+	/**
+	 * Fit the recorded page *inside* the surface (contain + letterbox), centered on
+	 * both axes. The surface keeps a constant box (CSS aspect-ratio / fullscreen
+	 * flex), so the player height never jumps between recordings.
+	 *
+	 * Scale against the iframe rrweb actually built, not the statically-derived
+	 * fallback — a session can carry several Meta events (viewport resizes), and
+	 * `deriveMeta` keeps the last one, which may not match the current frame. The
+	 * iframe's width/height *attributes* always reflect the current viewport, and
+	 * the `Resize` listener re-runs this when they change mid-playback.
+	 */
+	fit(container: HTMLElement): void {
+		const vw = Number(this.replayer.iframe?.getAttribute("width")) || this.fallbackViewport.width
+		const vh = Number(this.replayer.iframe?.getAttribute("height")) || this.fallbackViewport.height
+		const availW = container.clientWidth
+		const availH = container.clientHeight
+		if (!availW || !availH || !vw || !vh) return
+		const scale = Math.min(availW / vw, availH / vh)
+		const offsetX = Math.max(0, (availW - vw * scale) / 2)
+		const offsetY = Math.max(0, (availH - vh * scale) / 2)
+		this.replayer.wrapper.style.transformOrigin = "top left"
+		this.replayer.wrapper.style.transform = `translate(${offsetX}px, ${offsetY}px) scale(${scale})`
+	}
+
+	destroy(): void {
+		this.replayer.destroy()
+	}
+}
+
+export const rrwebEngineFactory: ReplayEngineFactory = {
+	create: (input) => new RrwebEngine(input),
+}
diff --git a/apps/web/src/components/replays/engine/video-engine.test.ts b/apps/web/src/components/replays/engine/video-engine.test.ts
new file mode 100644
index 000000000..d3f91cbfc
--- /dev/null
+++ b/apps/web/src/components/replays/engine/video-engine.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest"
+import {
+	extractVideoSegments,
+	resolveSegment,
+	segmentsTotalMs,
+	videoSegmentPayload,
+	type VideoSegment,
+} from "./video-engine"
+
+// A mobile recording is a sequence of independent MP4s, each opening on an IDR
+// keyframe. The segment math below is what turns a playhead offset into
+// (which file, how far into it) — the whole reason seeking is exact here.
+//
+// The DOM side (<video>, Blob URLs) is deliberately not tested: jsdom implements
+// neither URL.createObjectURL nor HTMLMediaElement.play/pause, so a test of it
+// would only exercise its own stubs.
+
+const T0 = 1_700_000_000_000
+
+/** An rrweb-shaped custom event carrying one H.264 segment, as the iOS SDK emits. */
+const videoEvent = (offsetMs: number, durationMs: number, overrides: Record<string, unknown> = {}) => ({
+	type: 5,
+	timestamp: T0 + offsetMs,
+	data: {
+		tag: "video",
+		payload: {
+			segmentId: `seg-${offsetMs}`,
+			size: 12_800,
+			duration: durationMs,
+			encoding: "h264",
+			container: "mp4",
+			width: 390,
+			height: 844,
+			frameCount: 60,
+			frameRateType: "constant",
+			frameRate: 2,
+			left: 0,
+			top: 0,
+			base64: "AAAAIGZ0eXA=",
+			...overrides,
+		},
+	},
+})
+
+const metaEvent = (offsetMs: number) => ({
+	type: 4,
+	timestamp: T0 + offsetMs,
+	data: { href: "app://main", width: 390, height: 844 },
+})
+
+const touchEvent = (offsetMs: number) => ({
+	type: 3,
+	timestamp: T0 + offsetMs,
+	data: { source: 2, type: 7, pointerType: 2 },
+})
+
+describe("videoSegmentPayload", () => {
+	it("recognises the SDK's video custom event", () => {
+		expect(videoSegmentPayload(videoEvent(0, 30_000))).toMatchObject({ encoding: "h264" })
+	})
+
+	it("rejects everything that is not one", () => {
+		// Type 5 but a different tag, right type/tag but wrong event type, and the
+		// ordinary rrweb events a browser session is made of.
+		expect(videoSegmentPayload({ type: 5, timestamp: T0, data: { tag: "breadcrumb" } })).toBeUndefined()
+		expect(videoSegmentPayload(metaEvent(0))).toBeUndefined()
+		expect(videoSegmentPayload(touchEvent(0))).toBeUndefined()
+		expect(videoSegmentPayload(null)).toBeUndefined()
+		expect(videoSegmentPayload(undefined)).toBeUndefined()
+	})
+})
+
+describe("extractVideoSegments", () => {
+	it("positions segments against the stream's first event, not the epoch", () => {
+		// The meta event opens the chunk, so time-zero is it — the first video
+		// segment lands 5ms later, not 1.7 trillion ms later.
+		const events = [metaEvent(0), videoEvent(5, 30_000), touchEvent(1_200), videoEvent(30_005, 30_000)]
+		const segments = extractVideoSegments(events, T0)
+		expect(segments).toHaveLength(2)
+		expect(segments[0]).toMatchObject({ startMs: 5, durationMs: 30_000, width: 390, height: 844 })
+		expect(segments[1]).toMatchObject({ startMs: 30_005, durationMs: 30_000 })
+	})
+
+	it("orders segments by start time regardless of arrival order", () => {
+		const segments = extractVideoSegments([videoEvent(60_000, 30_000), videoEvent(0, 30_000)], T0)
+		expect(segments.map((s) => s.startMs)).toEqual([0, 60_000])
+	})
+
+	it("skips unusable segments rather than failing the recording", () => {
+		// A chunk missing its payload must not take the surrounding footage down
+		// with it — same posture as `decodeRange` skipping a malformed chunk.
+		const events = [
+			videoEvent(0, 30_000),
+			videoEvent(30_000, 30_000, { base64: "" }),
+			{ type: 5, timestamp: T0 + 60_000, data: { tag: "video" } },
+			videoEvent(90_000, 30_000),
+		]
+		expect(extractVideoSegments(events, T0).map((s) => s.startMs)).toEqual([0, 90_000])
+	})
+
+	it("returns nothing for a browser recording", () => {
+		expect(extractVideoSegments([metaEvent(0), touchEvent(10)], T0)).toEqual([])
+	})
+})
+
+describe("segmentsTotalMs", () => {
+	it("measures to the end of the last segment, not its start", () => {
+		expect(segmentsTotalMs(extractVideoSegments([videoEvent(0, 30_000)], T0))).toBe(30_000)
+	})
+
+	it("is zero for an empty recording", () => {
+		expect(segmentsTotalMs([])).toBe(0)
+	})
+})
+
+describe("resolveSegment", () => {
+	// Two 30s segments with a 10s hole between them — the recorder stopped while
+	// the app was backgrounded.
+	const segments: ReadonlyArray<VideoSegment> = extractVideoSegments(
+		[videoEvent(0, 30_000), videoEvent(40_000, 30_000)],
+		T0,
+	)
+
+	it("maps an offset inside a segment to that segment's own clock", () => {
+		expect(resolveSegment(segments, 0)).toEqual({ index: 0, offsetSec: 0 })
+		expect(resolveSegment(segments, 12_500)).toEqual({ index: 0, offsetSec: 12.5 })
+		// Second segment starts at 40s, so 45s is 5s into its own media clock —
+		// not 45s, which is what a naive global-timeline seek would use.
+		expect(resolveSegment(segments, 45_000)).toEqual({ index: 1, offsetSec: 5 })
+	})
+
+	it("snaps a seek landing in a gap forward to the next segment", () => {
+		// 35s is dead air. Stalling there would look like frozen playback, so the
+		// playhead moves to the start of the next real footage.
+		expect(resolveSegment(segments, 35_000)).toEqual({ index: 1, offsetSec: 0 })
+	})
+
+	it("treats a segment boundary as the start of the next segment", () => {
+		expect(resolveSegment(segments, 30_000)).toEqual({ index: 1, offsetSec: 0 })
+	})
+
+	it("holds at the tail of the last segment past the end", () => {
+		// Reporting the end (rather than wrapping to 0) is what lets the engine
+		// fire `onFinish` instead of silently restarting the recording.
+		expect(resolveSegment(segments, 999_999)).toEqual({ index: 1, offsetSec: 30 })
+	})
+
+	it("clamps a negative offset to the first segment", () => {
+		expect(resolveSegment(segments, -5_000)).toEqual({ index: 0, offsetSec: 0 })
+	})
+
+	it("has nothing to resolve on an empty recording", () => {
+		expect(resolveSegment([], 1_000)).toBeUndefined()
+	})
+})
diff --git a/apps/web/src/components/replays/engine/video-engine.ts b/apps/web/src/components/replays/engine/video-engine.ts
new file mode 100644
index 000000000..dafda927c
--- /dev/null
+++ b/apps/web/src/components/replays/engine/video-engine.ts
@@ -0,0 +1,310 @@
+import type { ReplayEngine, ReplayEngineCreateInput, ReplayEngineFactory } from "./replay-engine"
+
+// The video engine — mobile recordings.
+//
+// The iOS SDK captures masked screenshots, encodes them to H.264, and wraps each
+// segment in rrweb-*shaped* events so the existing chunk pipeline carries them
+// with no gateway or storage changes. The MP4 itself rides inside the JSON as
+// base64 (gzipped, that costs 0.6-1.0x the raw MP4).
+//
+// So a "recording" here is a sequence of independent MP4s, each opening with an
+// IDR keyframe. That is what makes seeking cheap: every segment is its own
+// checkpoint, so any offset resolves to (segment, offset-within-segment) with no
+// decode from an earlier point. It also means playback is a src swap at each
+// boundary rather than one continuous stream.
+
+/** One H.264 segment, positioned on the session clock. */
+export interface VideoSegment {
+	readonly segmentId: string
+	/** Offset from session start, ms — the same clock `getCurrentTimeMs` reports. */
+	readonly startMs: number
+	readonly durationMs: number
+	/** The MP4, base64-encoded. Decoded to a Blob URL lazily. */
+	readonly base64: string
+	readonly width: number
+	readonly height: number
+}
+
+/** Where an offset on the session clock lands within the segment list. */
+export interface SegmentPosition {
+	readonly index: number
+	/** Seconds into that segment's own media clock. */
+	readonly offsetSec: number
+}
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+	typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
+
+const numberOr = (value: unknown, fallback: number): number =>
+	typeof value === "number" && Number.isFinite(value) ? value : fallback
+
+/**
+ * True for the rrweb `custom` event (type 5) that carries an H.264 segment.
+ *
+ * Exported because idle-band derivation needs the same test: a video event
+ * *spans* its duration, and treating it as an instant makes every quiet segment
+ * look like a 30s idle gap.
+ */
+export function videoSegmentPayload(event: unknown): Record<string, unknown> | undefined {
+	const ev = asRecord(event)
+	if (ev?.type !== 5) return undefined
+	const data = asRecord(ev.data)
+	if (data?.tag !== "video") return undefined
+	return asRecord(data.payload)
+}
+
+/**
+ * Pull the ordered segment list out of a raw event stream.
+ *
+ * `startTime` is the stream's first event timestamp — the playhead's time-zero,
+ * matching `DerivedMeta.startTime`. Segments without a usable payload are
+ * skipped rather than failing the whole recording, the same way `decodeRange`
+ * skips a malformed chunk.
+ */
+export function extractVideoSegments(events: ReadonlyArray<unknown>, startTime: number): VideoSegment[] {
+	const segments: VideoSegment[] = []
+	for (const raw of events) {
+		const payload = videoSegmentPayload(raw)
+		if (!payload) continue
+		const base64 = payload.base64
+		if (typeof base64 !== "string" || base64.length === 0) continue
+		const timestamp = numberOr(asRecord(raw)?.timestamp, Number.NaN)
+		if (!Number.isFinite(timestamp)) continue
+		segments.push({
+			segmentId: typeof payload.segmentId === "string" ? payload.segmentId : String(segments.length),
+			startMs: Math.max(0, timestamp - startTime),
+			durationMs: Math.max(0, numberOr(payload.duration, 0)),
+			base64,
+			width: numberOr(payload.width, 0),
+			height: numberOr(payload.height, 0),
+		})
+	}
+	segments.sort((a, b) => a.startMs - b.startMs)
+	return segments
+}
+
+/** End of the last segment — the recording's length on the session clock. */
+export function segmentsTotalMs(segments: ReadonlyArray<VideoSegment>): number {
+	let end = 0
+	for (const segment of segments) end = Math.max(end, segment.startMs + segment.durationMs)
+	return end
+}
+
+/**
+ * Map a session-clock offset onto (segment, offset-within-segment).
+ *
+ * The recorder pauses when the app is backgrounded, so segments are not
+ * necessarily contiguous. An offset landing in a gap snaps *forward* to the next
+ * segment — the same thing the provider's skip-idle jump does, and the only
+ * choice that keeps playback moving instead of stalling on dead air.
+ */
+export function resolveSegment(
+	segments: ReadonlyArray<VideoSegment>,
+	offsetMs: number,
+): SegmentPosition | undefined {
+	if (segments.length === 0) return undefined
+	for (let index = 0; index < segments.length; index++) {
+		const segment = segments[index]!
+		if (offsetMs < segment.startMs) return { index, offsetSec: 0 }
+		if (offsetMs < segment.startMs + segment.durationMs) {
+			return { index, offsetSec: (offsetMs - segment.startMs) / 1000 }
+		}
+	}
+	// Past the end of the recording — hold at the tail of the last segment so the
+	// engine reports "finished" rather than silently restarting.
+	const index = segments.length - 1
+	return { index, offsetSec: segments[index]!.durationMs / 1000 }
+}
+
+/** Decode base64 to an MP4 object URL. Mirrors the idiom in `lib/log-key.ts`. */
+function toObjectUrl(base64: string): string {
+	const binary = atob(base64)
+	const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0))
+	return URL.createObjectURL(new Blob([bytes], { type: "video/mp4" }))
+}
+
+class VideoEngine implements ReplayEngine {
+	private readonly video: HTMLVideoElement
+	private readonly onFinish: () => void
+	private readonly onResize: () => void
+	private segments: VideoSegment[]
+	private index = -1
+	/** Object URLs by segment index. Only the current and next are kept alive. */
+	private readonly urls = new Map<number, string>()
+	/** True while the engine should advance across segment boundaries on its own. */
+	private playing = false
+	private speed = 1
+	private destroyed = false
+	/** Applied once the swapped-in segment reports its metadata. */
+	private pendingSeekSec: number | null = null
+	/** Session-clock zero, kept so late segments rebase against the same origin. */
+	private readonly streamStart: number
+
+	constructor(input: ReplayEngineCreateInput) {
+		this.onFinish = input.onFinish
+		this.onResize = input.onResize
+		this.streamStart = streamStartMs(input.events)
+		this.segments = extractVideoSegments(input.events, this.streamStart)
+
+		const video = document.createElement("video")
+		// `object-fit: contain` *is* the letterbox-and-centre that the rrweb engine
+		// has to compute by hand, so `fit()` has nothing left to do.
+		video.style.width = "100%"
+		video.style.height = "100%"
+		video.style.objectFit = "contain"
+		// Screen recordings carry no audio track; muted also keeps `play()` clear of
+		// autoplay policy, which would otherwise reject the promise on first press.
+		video.muted = true
+		video.playsInline = true
+		video.preload = "auto"
+		input.mount.replaceChildren(video)
+		this.video = video
+
+		video.addEventListener("loadedmetadata", this.handleLoadedMetadata)
+		video.addEventListener("ended", this.handleEnded)
+
+		// Show the opening frame immediately, the way rrweb paints its first
+		// snapshot on construction rather than waiting for play.
+		if (this.segments.length > 0) this.select(0, 0)
+	}
+
+	private handleLoadedMetadata = (): void => {
+		this.onResize()
+		if (this.pendingSeekSec !== null) {
+			this.video.currentTime = this.pendingSeekSec
+			this.pendingSeekSec = null
+		}
+		if (this.playing) void this.video.play().catch(() => {})
+	}
+
+	private handleEnded = (): void => {
+		if (!this.playing) return
+		const next = this.index + 1
+		if (next >= this.segments.length) {
+			this.playing = false
+			this.onFinish()
+			return
+		}
+		this.select(next, 0)
+	}
+
+	/** Point the element at `index`, seeking to `offsetSec` once it is loadable. */
+	private select(index: number, offsetSec: number): void {
+		if (this.destroyed) return
+		const segment = this.segments[index]
+		if (!segment) return
+		if (index === this.index) {
+			// Same media — seek directly; no metadata round-trip needed.
+			if (this.video.readyState >= 1) this.video.currentTime = offsetSec
+			else this.pendingSeekSec = offsetSec
+			return
+		}
+		this.index = index
+		this.pendingSeekSec = offsetSec
+		this.video.src = this.urlFor(index)
+		this.video.playbackRate = this.speed
+		this.retainAround(index)
+		this.video.load()
+	}
+
+	private urlFor(index: number): string {
+		const existing = this.urls.get(index)
+		if (existing !== undefined) return existing
+		const url = toObjectUrl(this.segments[index]!.base64)
+		this.urls.set(index, url)
+		return url
+	}
+
+	/**
+	 * Hold object URLs for the current and next segment only.
+	 *
+	 * The base64 already sits in the loader's event array; a decoded Blob is a
+	 * second copy. A 30-minute session is ~60 segments, so keeping them all alive
+	 * would pin tens of MB to play two.
+	 */
+	private retainAround(index: number): void {
+		// Warm the next segment so the boundary swap doesn't stall on a decode.
+		if (index + 1 < this.segments.length) this.urlFor(index + 1)
+		for (const [held, url] of this.urls) {
+			if (held === index || held === index + 1) continue
+			URL.revokeObjectURL(url)
+			this.urls.delete(held)
+		}
+	}
+
+	get totalTimeMs(): number {
+		return segmentsTotalMs(this.segments)
+	}
+
+	getCurrentTimeMs(): number {
+		const segment = this.segments[this.index]
+		if (!segment) return 0
+		const ms = segment.startMs + this.video.currentTime * 1000
+		return Number.isFinite(ms) && ms > 0 ? ms : 0
+	}
+
+	play(offsetMs: number): void {
+		const position = resolveSegment(this.segments, offsetMs)
+		if (!position) return
+		this.playing = true
+		this.select(position.index, position.offsetSec)
+		if (this.video.readyState >= 1 && this.pendingSeekSec === null) {
+			void this.video.play().catch(() => {})
+		}
+	}
+
+	pause(offsetMs?: number): void {
+		this.playing = false
+		this.video.pause()
+		if (offsetMs === undefined) return
+		const position = resolveSegment(this.segments, offsetMs)
+		if (position) this.select(position.index, position.offsetSec)
+	}
+
+	setSpeed(speed: number): void {
+		this.speed = speed
+		this.video.playbackRate = speed
+	}
+
+	addEvent(event: unknown): void {
+		const payload = videoSegmentPayload(event)
+		if (!payload) return
+		// Re-extract through the same path so a late segment is validated
+		// identically to a seed one. `startMs` is already session-relative on the
+		// existing list, so rebase the newcomer against the same zero.
+		const appended = extractVideoSegments([event], this.streamStart)
+		if (appended.length === 0) return
+		for (const segment of appended) {
+			if (this.segments.some((existing) => existing.segmentId === segment.segmentId)) continue
+			this.segments.push(segment)
+		}
+		this.segments.sort((a, b) => a.startMs - b.startMs)
+	}
+
+	fit(): void {
+		// `object-fit: contain` on a 100%/100% element already letterboxes and
+		// centres against whatever box the surface gives us.
+	}
+
+	destroy(): void {
+		this.destroyed = true
+		this.video.removeEventListener("loadedmetadata", this.handleLoadedMetadata)
+		this.video.removeEventListener("ended", this.handleEnded)
+		this.video.pause()
+		this.video.removeAttribute("src")
+		this.video.load()
+		for (const url of this.urls.values()) URL.revokeObjectURL(url)
+		this.urls.clear()
+		this.video.remove()
+	}
+}
+
+/** First event timestamp — the playhead's time-zero, matching `deriveMeta`. */
+function streamStartMs(events: ReadonlyArray<unknown>): number {
+	const first = asRecord(events[0])
+	return numberOr(first?.timestamp, 0)
+}
+
+export const videoEngineFactory: ReplayEngineFactory = {
+	create: (input) => new VideoEngine(input),
+}
diff --git a/apps/web/src/components/replays/replay-events.ts b/apps/web/src/components/replays/replay-events.ts
index 811b4e8a5..3417a34fc 100644
--- a/apps/web/src/components/replays/replay-events.ts
+++ b/apps/web/src/components/replays/replay-events.ts
@@ -21,7 +21,27 @@ const timestampOf = (event: unknown): number => (hasTimestamp(event) ? event.tim
 /** Order events by timestamp; ties keep input order (Arr.sort is a stable native sort). */
 const byTimestamp = Order.mapInput(Order.Number, timestampOf)
 
-const isSameEvent = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b)
+/** The `type` field, when the event has a numeric one. */
+const typeOf = (event: unknown): number | undefined =>
+	typeof event === "object" && event !== null && "type" in event && typeof event.type === "number"
+		? event.type
+		: undefined
+
+/**
+ * Exact-duplicate test for two adjacent events.
+ *
+ * `JSON.stringify` is the ground truth, but it is not free: a mobile video event
+ * carries a whole base64-encoded MP4, so stringifying both sides of every
+ * adjacent pair would serialize hundreds of KB per comparison, on every range
+ * decode. Since duplicates must agree on timestamp and type anyway, checking
+ * those first rejects nearly every pair for two field reads — and only genuine
+ * candidates pay for the full comparison.
+ */
+const isSameEvent = (a: unknown, b: unknown): boolean => {
+	if (timestampOf(a) !== timestampOf(b)) return false
+	if (typeOf(a) !== typeOf(b)) return false
+	return JSON.stringify(a) === JSON.stringify(b)
+}
 
 /**
  * Stable-sort the concatenated event stream by timestamp and drop exact adjacent
diff --git a/apps/web/src/components/replays/replay-format.test.ts b/apps/web/src/components/replays/replay-format.test.ts
index fb5319d4e..8fdf29b81 100644
--- a/apps/web/src/components/replays/replay-format.test.ts
+++ b/apps/web/src/components/replays/replay-format.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { recordedMarker, replayPartitionWindow } from "./replay-format"
+import { recordedMarker, replayFormat, replayPartitionWindow } from "./replay-format"
 
 // The session-detail warehouse queries are PARTITION BY toDate(...) over a 30-day
 // TTL; `replayPartitionWindow` turns a session's start (and optional end) into the
@@ -64,3 +64,38 @@ describe("recordedMarker", () => {
 		expect(recordedMarker(JSON.stringify({ "maple.session.recorded": "1" }))).toBeUndefined()
 	})
 })
+
+// `replayFormat` decides which engine plays a session, from session metadata
+// alone — so the player never has to download a chunk to find out what it is
+// looking at. Every fallback here resolves to "rrweb" on purpose: a session with
+// no marker was recorded before the marker existed, and those are all browser
+// recordings.
+describe("replayFormat", () => {
+	it("reads a mobile session's marker", () => {
+		expect(replayFormat(JSON.stringify({ "maple.session.replay_format": "video" }))).toBe("video")
+	})
+
+	it("reads an explicit browser marker", () => {
+		expect(replayFormat(JSON.stringify({ "maple.session.replay_format": "rrweb" }))).toBe("rrweb")
+	})
+
+	it("treats a session recorded before the marker existed as rrweb", () => {
+		expect(replayFormat(JSON.stringify({ "maple.session.recorded": "true" }))).toBe("rrweb")
+		expect(replayFormat("{}")).toBe("rrweb")
+		expect(replayFormat(undefined)).toBe("rrweb")
+		expect(replayFormat(null)).toBe("rrweb")
+		expect(replayFormat("")).toBe("rrweb")
+	})
+
+	it("falls back to rrweb rather than throwing on unusable attributes", () => {
+		// A player that crashes on a malformed row is worse than one that tries the
+		// engine every existing session uses.
+		expect(replayFormat("not json")).toBe("rrweb")
+		expect(replayFormat("null")).toBe("rrweb")
+		expect(replayFormat("[]")).toBe("rrweb")
+	})
+
+	it("falls back to rrweb for a format a newer SDK invented", () => {
+		expect(replayFormat(JSON.stringify({ "maple.session.replay_format": "av1" }))).toBe("rrweb")
+	})
+})
diff --git a/apps/web/src/components/replays/replay-format.ts b/apps/web/src/components/replays/replay-format.ts
index d715f5fe9..4582932e8 100644
--- a/apps/web/src/components/replays/replay-format.ts
+++ b/apps/web/src/components/replays/replay-format.ts
@@ -1,4 +1,5 @@
 import { warehouseDateTimeToIso, formatWarehouseDateTime } from "@maple/query-engine"
+import type { ReplayFormat } from "./engine/replay-engine"
 import type { ActionKind } from "./replay-player-context"
 
 // Presentation helpers for the session-replay surfaces (list, detail, player,
@@ -61,6 +62,31 @@ export function recordedMarker(resourceAttributes: string | null | undefined): b
 	return undefined
 }
 
+/**
+ * Read the SDK's `maple.session.replay_format` marker, which decides *which
+ * engine* plays a session.
+ *
+ * Browser sessions carry rrweb DOM snapshots; mobile sessions carry H.264
+ * segments wrapped in rrweb-shaped events. Reading this from session metadata is
+ * what lets the player pick an engine without downloading a chunk first.
+ *
+ * Everything unrecognised — absent key, unparseable attributes, a value from a
+ * newer SDK than this build knows — falls back to `"rrweb"`. Every session
+ * recorded before the marker existed is a browser recording, so that default is
+ * correct rather than merely safe.
+ */
+export function replayFormat(resourceAttributes: string | null | undefined): ReplayFormat {
+	if (!resourceAttributes) return "rrweb"
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(resourceAttributes)
+	} catch {
+		return "rrweb"
+	}
+	if (typeof parsed !== "object" || parsed === null) return "rrweb"
+	return (parsed as Record<string, unknown>)["maple.session.replay_format"] === "video" ? "video" : "rrweb"
+}
+
 /** A warehouse partition-pruning window, shared by the session-detail atom callers. */
 export interface ReplayPartitionWindow {
 	readonly windowStart: string
diff --git a/apps/web/src/components/replays/replay-player-context.test.ts b/apps/web/src/components/replays/replay-player-context.test.ts
index 701764b46..2b3807d99 100644
--- a/apps/web/src/components/replays/replay-player-context.test.ts
+++ b/apps/web/src/components/replays/replay-player-context.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest"
-import { classifyUnplayable } from "./replay-player-context"
+import { classifyUnplayable, deriveMeta } from "./replay-player-context"
 
 // When a session has no playable frames, the player must say *why*. Getting
 // this wrong is user-visible in both directions: calling a live upload
@@ -50,3 +50,101 @@ describe("classifyUnplayable", () => {
 		})
 	})
 })
+
+// Marker and idle-band derivation runs over the raw event stream, which is now
+// two different shapes: rrweb DOM events from a browser, and H.264 segments from
+// a phone. Both have to land on the same timeline.
+
+const T0 = 1_700_000_000_000
+
+const videoEvent = (offsetMs: number, durationMs: number) => ({
+	type: 5,
+	timestamp: T0 + offsetMs,
+	data: {
+		tag: "video",
+		payload: {
+			segmentId: `seg-${offsetMs}`,
+			duration: durationMs,
+			width: 390,
+			height: 844,
+			base64: "AA==",
+		},
+	},
+})
+
+const metaEvent = (offsetMs: number, href = "app://main") => ({
+	type: 4,
+	timestamp: T0 + offsetMs,
+	data: { href, width: 390, height: 844 },
+})
+
+/** rrweb mouseInteraction; `type` 2 is Click, 7 is TouchStart. */
+const interaction = (offsetMs: number, type: number) => ({
+	type: 3,
+	timestamp: T0 + offsetMs,
+	data: { source: 2, type },
+})
+
+describe("deriveMeta idle bands", () => {
+	it("does not call continuous video segments idle", () => {
+		// THE trap for video sessions. Segments are ~30s apart and a quiet one
+		// emits a single event, so measuring idle from timestamps alone marks every
+		// segment as a 30s gap — and skip-idle (on by default) then collapses the
+		// entire recording to nothing. A segment stays active for its duration.
+		const events = [
+			metaEvent(0),
+			videoEvent(0, 30_000),
+			videoEvent(30_000, 30_000),
+			videoEvent(60_000, 30_000),
+		]
+		expect(deriveMeta(events).inactiveIntervals).toEqual([])
+	})
+
+	it("still reports a real gap between segments", () => {
+		// The recorder stops while the app is backgrounded. That hole is genuine
+		// idle and must stay collapsible, or skip-idle stops being useful.
+		const events = [metaEvent(0), videoEvent(0, 30_000), videoEvent(90_000, 30_000)]
+		expect(deriveMeta(events).inactiveIntervals).toEqual([{ start: 30_000, end: 90_000 }])
+	})
+
+	it("keeps treating ordinary rrweb events as instants", () => {
+		const events = [metaEvent(0), interaction(1_000, 2), interaction(20_000, 2)]
+		expect(deriveMeta(events).inactiveIntervals).toEqual([{ start: 1_000, end: 20_000 }])
+	})
+})
+
+describe("deriveMeta markers", () => {
+	it("marks a touch as a click", () => {
+		// Mobile sessions only ever emit TouchStart (7). rrweb records touch on
+		// mobile *web* too, so before this a phone session of either kind produced
+		// no click markers at all.
+		const markers = deriveMeta([metaEvent(0), interaction(5_000, 7)]).actionMarkers
+		expect(markers).toEqual([{ ms: 5_000, kind: "click" }])
+	})
+
+	it("still marks a mouse click", () => {
+		const markers = deriveMeta([metaEvent(0), interaction(5_000, 2)]).actionMarkers
+		expect(markers).toEqual([{ ms: 5_000, kind: "click" }])
+	})
+
+	it("ignores touch-move and touch-end", () => {
+		// 8 is TouchMove_Departed, 9 is TouchEnd — a drag is one interaction, not
+		// three markers stacked on the scrubber.
+		const markers = deriveMeta([metaEvent(0), interaction(5_000, 8), interaction(5_100, 9)]).actionMarkers
+		expect(markers).toEqual([])
+	})
+
+	it("takes the recorded viewport from a mobile meta event", () => {
+		const meta = deriveMeta([metaEvent(0), videoEvent(0, 30_000)])
+		expect(meta).toMatchObject({ recordedWidth: 390, recordedHeight: 844, startTime: T0 })
+	})
+
+	it("marks navigation on a genuine screen change", () => {
+		const markers = deriveMeta([
+			metaEvent(0, "app://main"),
+			metaEvent(4_000, "app://main"),
+			metaEvent(8_000, "app://settings"),
+		]).actionMarkers
+		expect(markers).toEqual([{ ms: 8_000, kind: "nav" }])
+	})
+})
diff --git a/apps/web/src/components/replays/replay-player-context.tsx b/apps/web/src/components/replays/replay-player-context.tsx
index f745a0515..9c9e247aa 100644
--- a/apps/web/src/components/replays/replay-player-context.tsx
+++ b/apps/web/src/components/replays/replay-player-context.tsx
@@ -1,8 +1,10 @@
 import * as React from "react"
-import { Replayer } from "@rrweb/replay"
-import { EventType, IncrementalSource, MouseInteractions, ReplayerEvents } from "@rrweb/types"
+import { EventType, IncrementalSource, MouseInteractions } from "@rrweb/types"
 import { Result, useAtomValue } from "@/lib/effect-atom"
 import { getReplayManifestResultAtom } from "@/lib/services/atoms/warehouse-query-atoms"
+import type { ReplayEngine, ReplayEngineFactory, ReplayFormat } from "./engine/replay-engine"
+import { rrwebEngineFactory } from "./engine/rrweb-engine"
+import { videoEngineFactory, videoSegmentPayload } from "./engine/video-engine"
 import { normalizeEvents } from "./replay-events"
 import type { ReplayPartitionWindow } from "./replay-format"
 import { manifestDurationMs, type ReplayChunkMeta } from "./replay-range"
@@ -11,11 +13,15 @@ import { buildTimeline, type InactiveInterval, type Timeline } from "./replay-ti
 
 // Replay player context
 //
-// The rrweb engine + transport state used to live inside the player surface.
+// The replay engine + transport state used to live inside the player surface.
 // The video-editor layout renders the surface and the timeline strip in
 // separate parts of the page, so both need to read `currentMs` and drive
 // `seek`. This provider owns the engine and exposes that state via context;
 // `<ReplaySurface>` and `<ReplayEditorTimeline>` are both consumers.
+//
+// The engine sits behind `ReplayEngine` (see `engine/replay-engine.ts`), so
+// browser (rrweb) and mobile (H.264 segment) recordings both play here. Nothing
+// below this provider knows or cares which one is mounted.
 
 const EMPTY_CHUNKS: ReadonlyArray<ReplayChunkMeta> = []
 
@@ -80,7 +86,22 @@ function isMovementNoise(source: number | undefined): boolean {
 	)
 }
 
-function deriveMeta(events: unknown[]): DerivedMeta {
+/**
+ * How long an event occupies the timeline.
+ *
+ * Almost everything rrweb records is instantaneous, but a mobile video segment
+ * *spans* its duration: one event covers 30s of footage. Measuring idle from its
+ * timestamp alone would mark every quiet segment as a 30s gap, and skip-idle
+ * (on by default) would then collapse the whole recording to nothing.
+ */
+function eventSpanMs(event: unknown): number {
+	const payload = videoSegmentPayload(event)
+	if (!payload) return 0
+	const duration = payload.duration
+	return typeof duration === "number" && Number.isFinite(duration) ? Math.max(0, duration) : 0
+}
+
+export function deriveMeta(events: unknown[]): DerivedMeta {
 	let recordedWidth = 1280
 	let recordedHeight = 720
 	const actionMarkers: ActionMarker[] = []
@@ -121,7 +142,9 @@ function deriveMeta(events: unknown[]): DerivedMeta {
 					end: ev.timestamp - startTime,
 				})
 			}
-			prevMeaningfulTs = ev.timestamp
+			// A video segment stays "active" for its whole duration, so the next
+			// segment starting right after it is continuous playback, not a gap.
+			prevMeaningfulTs = ev.timestamp + eventSpanMs(raw)
 		}
 
 		if (ev.type === EventType.Meta && ev.data) {
@@ -137,7 +160,13 @@ function deriveMeta(events: unknown[]): DerivedMeta {
 			}
 		} else if (isIncremental && typeof ev.timestamp === "number") {
 			const ms = ev.timestamp - startTime
-			if (source === IncrementalSource.MouseInteraction && ev.data?.type === MouseInteractions.Click) {
+			// Touch counts as a click. Mobile sessions only ever emit TouchStart, and
+			// rrweb records touch on mobile *web* too — so before this, a phone
+			// session of either kind produced no click markers at all.
+			if (
+				source === IncrementalSource.MouseInteraction &&
+				(ev.data?.type === MouseInteractions.Click || ev.data?.type === MouseInteractions.TouchStart)
+			) {
 				pushMarker("click", ms)
 			} else if (source === IncrementalSource.Input) {
 				pushMarker("input", ms)
@@ -226,20 +255,14 @@ export function useReplayPlayer(): ReplayPlayerContextValue {
 
 const EMPTY_EVENTS: unknown[] = []
 
-/**
- * Read the engine's playhead, treating "not started yet" as 0.
- *
- * rrweb builds its player context with `baselineTime: 0`, and
- * `getCurrentTime()` is `timer.timeOffset + (baselineTime - events[0].timestamp)`
- * — so until the engine has been driven by a `play()` / `pause(offset)` (the only
- * things that assign `baselineTime`), it reports `-events[0].timestamp`: a
- * negative epoch, ~55 years. Feeding that back into `play()` re-bases the whole
- * stream decades into the future and nothing ever casts, which is what left the
- * player frozen at 0:00 until the first scrub re-based it for us.
- */
-function engineTimeMs(replayer: Replayer | null): number {
-	const ms = replayer?.getCurrentTime() ?? 0
-	return Number.isFinite(ms) && ms > 0 ? ms : 0
+/** Read the engine's playhead, treating "no engine yet" as 0. */
+function engineTimeMs(engine: ReplayEngine | null): number {
+	return engine?.getCurrentTimeMs() ?? 0
+}
+
+const ENGINE_FACTORIES: Record<ReplayFormat, ReplayEngineFactory> = {
+	rrweb: rrwebEngineFactory,
+	video: videoEngineFactory,
 }
 
 export function errorMessage(error: unknown): string {
@@ -256,6 +279,7 @@ export function ReplayPlayerProvider({
 	eventsOverride,
 	window,
 	recorded,
+	format = "rrweb",
 	sessionActive = false,
 }: {
 	sessionId: string
@@ -270,6 +294,12 @@ export function ReplayPlayerProvider({
 	 * `sessionActive` + chunk count instead.
 	 */
 	recorded?: boolean
+	/**
+	 * Which engine plays this session, from the SDK's
+	 * `maple.session.replay_format` marker. Defaults to `rrweb`: every session
+	 * recorded before the marker existed is a browser recording.
+	 */
+	format?: ReplayFormat
 	/** Whether the session is still open (`status === "active"`), i.e. chunks may still arrive. */
 	sessionActive?: boolean
 }) {
@@ -355,7 +385,7 @@ export function ReplayPlayerProvider({
 	const figureRef = React.useRef<HTMLElement | null>(null)
 	const surfaceRef = React.useRef<HTMLDivElement | null>(null)
 	const mountRef = React.useRef<HTMLDivElement | null>(null)
-	const replayerRef = React.useRef<Replayer | null>(null)
+	const engineRef = React.useRef<ReplayEngine | null>(null)
 
 	const { recordedWidth, recordedHeight, startTime, actionMarkers, inactiveIntervals } = React.useMemo(
 		() => deriveMeta(events),
@@ -391,30 +421,18 @@ export function ReplayPlayerProvider({
 		[inactiveIntervals, timeline],
 	)
 
-	// Fit the recorded page *inside* the fixed-size surface (contain + letterbox),
-	// centered on both axes. The surface keeps a constant box (CSS aspect-ratio /
-	// fullscreen flex), so the player height never jumps between recordings.
+	// Re-fit the recording inside the fixed-size surface. How that is done is the
+	// engine's business (rrweb transforms its wrapper; the video element just uses
+	// `object-fit: contain`) — the provider only says *when*.
 	//
-	// Scale against the iframe rrweb actually built, not the statically-derived
-	// `recordedWidth` — a session can carry several Meta events (viewport resizes),
-	// and deriveMeta keeps the last one, which may not match the current frame.
-	// The iframe's width/height attributes always reflect the current viewport,
-	// and the `Resize` listener re-runs this when they change mid-playback.
+	// Deliberately dep-free and referentially stable: the recorded viewport is
+	// handed to the engine at construction instead, which keeps `recordedWidth`
+	// and `recordedHeight` out of the mount effect's dependency list below.
 	const applyScale = React.useCallback(() => {
-		const replayer = replayerRef.current
 		const container = surfaceRef.current
-		if (!replayer || !container) return
-		const vw = Number(replayer.iframe?.getAttribute("width")) || recordedWidth || 1280
-		const vh = Number(replayer.iframe?.getAttribute("height")) || recordedHeight || 720
-		const availW = container.clientWidth
-		const availH = container.clientHeight
-		if (!availW || !availH || !vw || !vh) return
-		const scale = Math.min(availW / vw, availH / vh)
-		const offsetX = Math.max(0, (availW - vw * scale) / 2)
-		const offsetY = Math.max(0, (availH - vh * scale) / 2)
-		replayer.wrapper.style.transformOrigin = "top left"
-		replayer.wrapper.style.transform = `translate(${offsetX}px, ${offsetY}px) scale(${scale})`
-	}, [recordedWidth, recordedHeight])
+		if (!container) return
+		engineRef.current?.fit(container)
+	}, [])
 
 	// Mirror document fullscreen state so the surface rescales + the button swaps.
 	React.useEffect(() => {
@@ -430,8 +448,8 @@ export function ReplayPlayerProvider({
 
 	// Mount the engine once events are ready. Keyed on `events` — a fresh session
 	// rebuilds. The surface's mount div is committed before this parent effect runs.
-	// The returned cleanup calls observer.disconnect() + replayer.destroy(), which
-	// tears down every replayer.on(...) subscription registered below.
+	// The returned cleanup calls observer.disconnect() + engine.destroy(), which
+	// tears down whatever listeners the engine registered.
 	// oxlint-disable-next-line react-doctor/effect-needs-cleanup
 	React.useEffect(() => {
 		if (status !== "ready") return
@@ -439,48 +457,36 @@ export function ReplayPlayerProvider({
 		if (!mount) return
 		mount.innerHTML = ""
 
-		const accent =
-			getComputedStyle(document.documentElement).getPropertyValue("--primary").trim() || "#6366f1"
-
-		const replayer = new Replayer(events as never, {
-			root: mount,
-			speed: 1,
-			// We skip idle ourselves by jumping (see the rAF loop) — rrweb's own
-			// skipInactive only fast-forwards, which is slow. Keep it off.
-			skipInactive: false,
-			mouseTail: { duration: 600, lineCap: "round", lineWidth: 3, strokeStyle: accent },
-			showWarning: false,
-			showDebug: false,
-			liveMode: false,
+		const engine = ENGINE_FACTORIES[format].create({
+			mount,
+			events,
+			// The engine prefers its own live viewport when it has one; this is the
+			// statically-derived fallback from the stream's Meta events.
+			fallbackViewport: { width: recordedWidth || 1280, height: recordedHeight || 720 },
+			onFinish: () => {
+				setIsPlaying(false)
+				setFinished(true)
+			},
+			// The recorded viewport can change mid-session (responsive / window
+			// resize / device rotation). Re-fit so the recording stays centered in
+			// the fixed surface. Also fires for the initial frame.
+			onResize: () => applyScale(),
 		})
-		replayerRef.current = replayer
-		setTotalMs(replayer.getMetaData().totalTime)
+		engineRef.current = engine
+		setTotalMs(engine.totalTimeMs)
 		setCurrentMs(0)
 		setFinished(false)
 		setIsPlaying(false)
 		fedCountRef.current = 0
 
-		// rrweb's own transport events are unreliable in @rrweb/replay (Start/Resume
-		// often don't fire); play/pause state is driven from our handlers. We still
-		// honour Finish to flip back to the replay affordance at the end.
-		replayer.on(ReplayerEvents.Finish, () => {
-			setIsPlaying(false)
-			setFinished(true)
-		})
-
-		// The recorded viewport can change mid-session (responsive / window resize);
-		// rrweb resizes its iframe and emits Resize. Re-fit so the recording stays
-		// centered in the fixed surface. Also fires for the initial snapshot.
-		replayer.on(ReplayerEvents.Resize, () => applyScale())
-
 		const observer = new ResizeObserver(() => applyScale())
 		if (surfaceRef.current) observer.observe(surfaceRef.current)
 		applyScale()
 
 		return () => {
 			observer.disconnect()
-			replayer.destroy()
-			replayerRef.current = null
+			engine.destroy()
+			engineRef.current = null
 			mount.innerHTML = ""
 		}
 		// Keyed on the SEED, and on nothing else that moves.
@@ -491,7 +497,10 @@ export function ReplayPlayerProvider({
 		// live session the manifest moves constantly: the iframe flashes and the
 		// playhead snaps back to 0 every few seconds, which reads as "playback is
 		// frozen". Trailing events and the total are applied by the effects below.
-	}, [events, status, applyScale])
+		//
+		// `recordedWidth`/`recordedHeight` are derived from `events` and `format`
+		// is a per-session prop, so neither adds churn beyond the seed itself.
+	}, [events, status, applyScale, format, recordedWidth, recordedHeight])
 
 	// The manifest knows the full length before the payload is loaded, so the
 	// scrubber shows the real duration from the first frame. `getMetaData()` would
@@ -504,9 +513,9 @@ export function ReplayPlayerProvider({
 	// Resume where the user asked after a seek-driven rebuild. Separate from the
 	// mount effect so that a new seek target never reconstructs the engine.
 	React.useEffect(() => {
-		const replayer = replayerRef.current
-		if (!replayer || status !== "ready" || seekTargetMs === null) return
-		replayer.pause(seekTargetMs)
+		const engine = engineRef.current
+		if (!engine || status !== "ready" || seekTargetMs === null) return
+		engine.pause(seekTargetMs)
 		setCurrentMs(seekTargetMs)
 	}, [seekTargetMs, status])
 
@@ -518,11 +527,11 @@ export function ReplayPlayerProvider({
 	// which is why a backward seek rebuilds (see `requestSeek`) rather than
 	// arriving here.
 	React.useEffect(() => {
-		const replayer = replayerRef.current
-		if (!replayer || status !== "ready") return
+		const engine = engineRef.current
+		if (!engine || status !== "ready") return
 		const pending = loader.trailingEvents.slice(fedCountRef.current)
 		if (pending.length === 0) return
-		for (const event of pending) replayer.addEvent(event as never)
+		for (const event of pending) engine.addEvent(event)
 		fedCountRef.current = loader.trailingEvents.length
 	}, [loader.trailingEvents, status])
 
@@ -540,16 +549,16 @@ export function ReplayPlayerProvider({
 		// frame before the engine clock catches up (which would thrash pause/play).
 		let lastJumpedEnd = -1
 		const tick = () => {
-			const replayer = replayerRef.current
-			if (replayer) {
-				const cur = replayer.getCurrentTime()
+			const engine = engineRef.current
+			if (engine) {
+				const cur = engine.getCurrentTimeMs()
 				const gap = skipInactive && inactiveIntervals.find((iv) => cur >= iv.start && cur < iv.end)
 				if (gap && gap.end !== lastJumpedEnd) {
 					lastJumpedEnd = gap.end
 					// Explicit pause→play forces the engine to seek; play(offset) alone
 					// can no-op while already playing in @rrweb/replay.
-					replayer.pause(gap.end)
-					replayer.play(gap.end)
+					engine.pause(gap.end)
+					engine.play(gap.end)
 					setCurrentMs(gap.end)
 				} else if (!gap) {
 					lastJumpedEnd = -1
@@ -573,32 +582,32 @@ export function ReplayPlayerProvider({
 	// the transport controls' own play calls.
 	const stalledRef = React.useRef(false)
 	React.useEffect(() => {
-		const replayer = replayerRef.current
-		if (!replayer || !isPlaying) return
+		const engine = engineRef.current
+		if (!engine || !isPlaying) return
 		if (loader.bufferState === "buffering") {
 			stalledRef.current = true
-			replayer.pause()
+			engine.pause()
 		} else if (loader.bufferState === "idle" && stalledRef.current) {
 			stalledRef.current = false
-			replayer.play(engineTimeMs(replayer))
+			engine.play(engineTimeMs(engine))
 		}
 	}, [loader.bufferState, isPlaying])
 
 	const togglePlay = React.useCallback(() => {
-		const replayer = replayerRef.current
-		if (!replayer) return
+		const engine = engineRef.current
+		if (!engine) return
 		if (finished) {
-			replayer.play(0)
+			engine.play(0)
 			setCurrentMs(0)
 			setFinished(false)
 			setIsPlaying(true)
 		} else if (isPlaying) {
-			replayer.pause()
+			engine.pause()
 			setIsPlaying(false)
 		} else {
-			const engineCurrentMs = engineTimeMs(replayer)
+			const engineCurrentMs = engineTimeMs(engine)
 			const from = engineCurrentMs >= totalMs ? 0 : engineCurrentMs
-			replayer.play(from)
+			engine.play(from)
 			setIsPlaying(true)
 		}
 	}, [finished, isPlaying, totalMs])
@@ -620,8 +629,8 @@ export function ReplayPlayerProvider({
 		const pending = pendingSeekRef.current
 		pendingSeekRef.current = null
 		if (pending === null) return
-		const replayer = replayerRef.current
-		if (!replayer) return
+		const engine = engineRef.current
+		if (!engine) return
 		// `displayMs` arrives in trimmed-timeline space; map back to rrweb's real
 		// clock before driving the engine. The pending request snapshots the latest
 		// playback state at the call site and is overwritten by newer pointer moves.
@@ -632,8 +641,8 @@ export function ReplayPlayerProvider({
 		// preceding checkpoint (the only thing rrweb can start from). The rebuild
 		// resumes at this offset, so don't also drive the doomed current engine.
 		if (requestSeek(clamped)) return
-		if (pending.isPlaying && clamped < pending.totalMs) replayer.play(clamped)
-		else replayer.pause(clamped)
+		if (pending.isPlaying && clamped < pending.totalMs) engine.play(clamped)
+		else engine.pause(clamped)
 	}, [requestSeek])
 
 	const seekDisplay = React.useCallback(
@@ -648,7 +657,7 @@ export function ReplayPlayerProvider({
 
 	const seekRelativeDisplay = React.useCallback(
 		(deltaMs: number) => {
-			const currentRealMs = engineTimeMs(replayerRef.current)
+			const currentRealMs = engineTimeMs(engineRef.current)
 			seekDisplay(timeline.toDisplay(currentRealMs) + deltaMs)
 		},
 		[seekDisplay, timeline],
@@ -663,7 +672,7 @@ export function ReplayPlayerProvider({
 
 	const changeSpeed = React.useCallback((next: number) => {
 		setSpeed(next)
-		replayerRef.current?.setConfig({ speed: next })
+		engineRef.current?.setSpeed(next)
 	}, [])
 
 	const toggleSkipInactive = React.useCallback(() => {
diff --git a/apps/web/src/components/replays/replay-studio.tsx b/apps/web/src/components/replays/replay-studio.tsx
index 40effb39d..b837d5005 100644
--- a/apps/web/src/components/replays/replay-studio.tsx
+++ b/apps/web/src/components/replays/replay-studio.tsx
@@ -2,7 +2,7 @@ import { ReplaySurface, ReplayTransport } from "@/components/replays/replay-play
 import { ReplayPlayerProvider } from "@/components/replays/replay-player-context"
 import { ReplayEditorTimeline } from "@/components/replays/replay-editor-timeline"
 import { SessionRail } from "@/components/replays/session-events-panel"
-import { recordedMarker, type ReplayPartitionWindow } from "@/components/replays/replay-format"
+import { recordedMarker, replayFormat, type ReplayPartitionWindow } from "@/components/replays/replay-format"
 import { Reveal, SessionIdentityBar } from "@/components/replays/session-detail-parts"
 
 // Replay studio
@@ -70,12 +70,17 @@ export function ReplayStudio({
 	const isActive = session.status === "active"
 	const label = session.userId || "Anonymous session"
 	const recorded = recordedMarker(session.resourceAttributes)
+	// Which engine plays this session (browser rrweb vs mobile H.264 segments).
+	// Read from the already-loaded session metadata, so the player never has to
+	// download a chunk to find out what it is looking at.
+	const format = replayFormat(session.resourceAttributes)
 
 	return (
 		<ReplayPlayerProvider
 			sessionId={sessionId}
 			window={window}
 			recorded={recorded}
+			format={format}
 			sessionActive={isActive}
 		>
 			<div className="flex min-h-0 flex-1 flex-col lg:flex-row">
diff --git a/packages/browser-session/src/meta-row.test.ts b/packages/browser-session/src/meta-row.test.ts
index c0a042251..19f060bfc 100644
--- a/packages/browser-session/src/meta-row.test.ts
+++ b/packages/browser-session/src/meta-row.test.ts
@@ -206,3 +206,37 @@ describe("buildSessionMetaRow analytics fields", () => {
 		expect(row.group_id).toBe("")
 	})
 })
+
+// `maple.session.replay_format` tells the web player which engine to mount
+// before it downloads a chunk. The browser SDK can only ever produce rrweb; the
+// mobile SDKs stamp "video". It must be on BOTH the active and ended rows:
+// session_replays is a ReplacingMergeTree that replaces the whole row at the
+// latest Version, so a marker emitted only on the active row would be destroyed
+// by the ended row and the player would silently fall back to rrweb.
+describe("buildSessionMetaRow replay format marker", () => {
+	it("stamps rrweb on the active row", () => {
+		const row = buildSessionMetaRow({ ...base, status: "active", recorded: true })
+		const attrs = row.resource_attributes as Record<string, string>
+		expect(attrs["maple.session.replay_format"]).toBe("rrweb")
+	})
+
+	it("stamps rrweb on the ended row too, so the merge cannot drop it", () => {
+		const row = buildSessionMetaRow({
+			...base,
+			status: "ended",
+			recorded: true,
+			environment: "production",
+			traceIds: ["trace-1"],
+		})
+		const attrs = row.resource_attributes as Record<string, string>
+		expect(attrs["maple.session.replay_format"]).toBe("rrweb")
+	})
+
+	it("stamps it even when no replay was recorded", () => {
+		// A metadata-only session still describes what it *would* have recorded, so
+		// the attribute stays uniform across every row this builder emits.
+		const row = buildSessionMetaRow({ ...base, status: "active", recorded: false })
+		const attrs = row.resource_attributes as Record<string, string>
+		expect(attrs["maple.session.replay_format"]).toBe("rrweb")
+	})
+})
diff --git a/packages/browser-session/src/meta-row.ts b/packages/browser-session/src/meta-row.ts
index f5c65fe7e..4e682292f 100644
--- a/packages/browser-session/src/meta-row.ts
+++ b/packages/browser-session/src/meta-row.ts
@@ -93,6 +93,13 @@ export function buildSessionMetaRow(input: SessionMetaRowInput): Record<string,
 			// to distinguish a metadata-only session from one still uploading chunks.
 			// `maple.*` vendor namespace, per the telemetry conventions.
 			"maple.session.recorded": input.recorded ? "true" : "false",
+			// Which engine plays this session's chunks. Hardcoded because the browser
+			// SDK can only ever produce rrweb; the mobile SDKs stamp "video" (H.264
+			// segments wrapped in rrweb-shaped events). The web player reads this from
+			// session metadata so it can pick an engine without downloading a chunk
+			// first, and treats an absent key as "rrweb" — every session recorded
+			// before this marker existed is a browser recording.
+			"maple.session.replay_format": "rrweb",
 			// Storage-blocked visitors get an in-memory id, so their sessions each
 			// look like a distinct visitor. Flag it rather than inflate silently.
 			...(input.visitorId && input.visitorIdPersisted === false

From eafc441c671cc476455a6485a415cf43c6fd012b Mon Sep 17 00:00:00 2001
From: Makisuo <minetoaster12@gmail.com>
Date: Fri, 14 Aug 2026 12:11:49 +0200
Subject: [PATCH 2/3] fix(replays): keep the idle watermark monotonic across a
 segment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Validated the parser against the first real video-backed session in the
warehouse and the idle fix did not actually work.

The SDK stamps `meta`, `video` and `breadcrumb` with the SAME timestamp,
breadcrumb last. Advancing the watermark by plain assignment meant the
breadcrumb rewound it from (ts + duration) back to ts, so the next
segment 5001ms later still measured as a 5001ms gap — every segment
became an idle band again, which is the exact failure the span fix was
meant to prevent.

Take the max instead, and cover it with a test built from the real chunk
layout rather than synthetic events that happened to omit the sibling.
---
 .../replays/replay-player-context.test.ts         | 15 +++++++++++++++
 .../components/replays/replay-player-context.tsx  |  8 +++++++-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/apps/web/src/components/replays/replay-player-context.test.ts b/apps/web/src/components/replays/replay-player-context.test.ts
index 2b3807d99..f6d2f75c5 100644
--- a/apps/web/src/components/replays/replay-player-context.test.ts
+++ b/apps/web/src/components/replays/replay-player-context.test.ts
@@ -100,6 +100,21 @@ describe("deriveMeta idle bands", () => {
 		expect(deriveMeta(events).inactiveIntervals).toEqual([])
 	})
 
+	it("survives the sibling events the SDK emits on the same timestamp", () => {
+		// Modelled on a real recording (9 chunks, 5-6s segments): each chunk is
+		// `meta`, `video` and `breadcrumb` all stamped with the SAME ms, breadcrumb
+		// last. A plain assignment would rewind the watermark from (ts + duration)
+		// back to ts when the breadcrumb lands, and every segment would register as
+		// a gap again — so the watermark has to be monotonic.
+		const chunk = (atMs: number, durationMs: number) => [
+			metaEvent(atMs),
+			videoEvent(atMs, durationMs),
+			{ type: 5, timestamp: T0 + atMs, data: { tag: "breadcrumb", payload: { name: "tap" } } },
+		]
+		const events = [...chunk(0, 5_000), ...chunk(5_001, 6_000), ...chunk(11_007, 6_000)]
+		expect(deriveMeta(events).inactiveIntervals).toEqual([])
+	})
+
 	it("still reports a real gap between segments", () => {
 		// The recorder stops while the app is backgrounded. That hole is genuine
 		// idle and must stay collapsible, or skip-idle stops being useful.
diff --git a/apps/web/src/components/replays/replay-player-context.tsx b/apps/web/src/components/replays/replay-player-context.tsx
index 9c9e247aa..abd093644 100644
--- a/apps/web/src/components/replays/replay-player-context.tsx
+++ b/apps/web/src/components/replays/replay-player-context.tsx
@@ -144,7 +144,13 @@ export function deriveMeta(events: unknown[]): DerivedMeta {
 			}
 			// A video segment stays "active" for its whole duration, so the next
 			// segment starting right after it is continuous playback, not a gap.
-			prevMeaningfulTs = ev.timestamp + eventSpanMs(raw)
+			//
+			// Monotonic on purpose. The iOS SDK emits `meta`, `video` and
+			// `breadcrumb` all on the *same* timestamp, and the breadcrumb is
+			// processed after the segment — a plain assignment would rewind the
+			// watermark from (ts + duration) back to ts, and every segment would
+			// register as a gap again. Verified against a real recording.
+			prevMeaningfulTs = Math.max(prevMeaningfulTs, ev.timestamp + eventSpanMs(raw))
 		}
 
 		if (ev.type === EventType.Meta && ev.data) {

From 38bd233eac1a7e72d9134c686db7ea53ef58ca95 Mon Sep 17 00:00:00 2001
From: Makisuo <minetoaster12@gmail.com>
Date: Fri, 14 Aug 2026 12:28:51 +0200
Subject: [PATCH 3/3] fix(replays): stop the seed array identity from
 rebuilding the engine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Playing the fixture in a real browser showed the engine being destroyed
about 1.3s into playback and never resuming.

The mount effect is keyed on the seed `events` array, so that array's
identity is load-bearing — but it was being built inside the status memo,
which depends on the manifest result. Every manifest change therefore
minted a new array (`normalizeEvents(...)` on the injected path, a
`[...loader.seedEvents]` spread on the loaded one) and tore the engine
down.

This is the failure the mount effect's own comment says it fixed by
keying on the seed and "nothing else that moves" — the effect was keyed
correctly, the seed just wasn't stable. On rrweb it surfaced as an
iframe flash and the playhead snapping to 0 every few seconds on a live
session; the video engine loses playback entirely, which is how it
finally became obvious.

Both paths now hand back an already-stable array. Covered by a test that
recomputes the memo without changing its outcome: two engine instances
before the fix, one after.
---
 .../replays/replay-engine-stability.test.tsx  | 118 ++++++++++++++++++
 .../replays/replay-player-context.tsx         |  34 ++++-
 2 files changed, 146 insertions(+), 6 deletions(-)
 create mode 100644 apps/web/src/components/replays/replay-engine-stability.test.tsx

diff --git a/apps/web/src/components/replays/replay-engine-stability.test.tsx b/apps/web/src/components/replays/replay-engine-stability.test.tsx
new file mode 100644
index 000000000..bc61aeb22
--- /dev/null
+++ b/apps/web/src/components/replays/replay-engine-stability.test.tsx
@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+
+import { Registry, RegistryContext } from "@/lib/effect-atom"
+import { cleanup, render } from "@testing-library/react"
+import type { ReactNode } from "react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { ReplayPlayerProvider } from "./replay-player-context"
+import { ReplaySurface } from "./replay-player"
+
+// The engine is mounted in an effect keyed on the seed `events` array, so that
+// array's IDENTITY is load-bearing, not just its contents: a fresh array tears
+// the engine down and builds a new one.
+//
+// The status memo that produces `events` depends on the manifest result, which
+// changes on every refetch. Building the array inside that memo — a
+// `normalizeEvents(...)` call, or a `[...loader.seedEvents]` spread — therefore
+// rebuilds the engine every few seconds on a live session. On rrweb that showed
+// up as an iframe flash and the playhead snapping to 0; on the video engine it
+// killed playback outright (verified in a real browser: `VideoEngine.destroy`
+// fired ~1.3s into playback and the recording never resumed).
+//
+// `sessionActive` stands in for that churn here: it is a dependency of the same
+// memo but cannot change the outcome, so a rebuild triggered by flipping it is
+// unambiguously an identity bug rather than a real seed change.
+
+const REPLAY_EVENTS = [{ timestamp: 1_000 }, { timestamp: 31_000 }]
+
+const { FakeReplayer } = vi.hoisted(() => {
+	class FakeReplayer {
+		static instances: FakeReplayer[] = []
+		readonly iframe: null = null
+		readonly wrapper = { style: {} as Record<string, string> }
+		constructor() {
+			FakeReplayer.instances.push(this)
+		}
+		getMetaData() {
+			return { startTime: 0, endTime: 30_000, totalTime: 30_000 }
+		}
+		getCurrentTime() {
+			return 0
+		}
+		play() {}
+		pause() {}
+		addEvent() {}
+		on() {
+			return this
+		}
+		setConfig() {}
+		destroy() {}
+	}
+	return { FakeReplayer }
+})
+
+vi.mock("@rrweb/replay", () => ({ Replayer: FakeReplayer }))
+vi.mock("@rrweb/replay/dist/style.css", () => ({}))
+vi.mock("@/hooks/use-replay-keyboard-shortcuts", () => ({ useReplayKeyboardShortcuts: () => {} }))
+
+function Harness({ sessionActive }: { sessionActive: boolean }) {
+	return (
+		<ReplayPlayerProvider
+			sessionId="sess-1"
+			eventsOverride={REPLAY_EVENTS}
+			recorded
+			sessionActive={sessionActive}
+		>
+			<ReplaySurface url="https://app.acme.dev/dashboard" />
+		</ReplayPlayerProvider>
+	)
+}
+
+describe("replay engine mount stability", () => {
+	beforeEach(() => {
+		FakeReplayer.instances.length = 0
+		globalThis.ResizeObserver = class {
+			observe() {}
+			unobserve() {}
+			disconnect() {}
+		}
+		vi.stubGlobal("requestAnimationFrame", () => 0)
+		vi.stubGlobal("cancelAnimationFrame", () => {})
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+		cleanup()
+	})
+
+	it("builds the engine once and keeps it across unrelated re-renders", () => {
+		const registry = Registry.make()
+		const Wrapper = ({ children }: { children: ReactNode }) => (
+			<RegistryContext.Provider value={registry}>{children}</RegistryContext.Provider>
+		)
+
+		const view = render(
+			<Wrapper>
+				<Harness sessionActive={false} />
+			</Wrapper>,
+		)
+		expect(FakeReplayer.instances).toHaveLength(1)
+
+		// Recompute the status memo without changing what it resolves to. The seed
+		// is the same events array, so the engine must survive.
+		view.rerender(
+			<Wrapper>
+				<Harness sessionActive />
+			</Wrapper>,
+		)
+		expect(FakeReplayer.instances).toHaveLength(1)
+
+		view.rerender(
+			<Wrapper>
+				<Harness sessionActive={false} />
+			</Wrapper>,
+		)
+		expect(FakeReplayer.instances).toHaveLength(1)
+	})
+})
diff --git a/apps/web/src/components/replays/replay-player-context.tsx b/apps/web/src/components/replays/replay-player-context.tsx
index abd093644..374d526a4 100644
--- a/apps/web/src/components/replays/replay-player-context.tsx
+++ b/apps/web/src/components/replays/replay-player-context.tsx
@@ -101,7 +101,7 @@ function eventSpanMs(event: unknown): number {
 	return typeof duration === "number" && Number.isFinite(duration) ? Math.max(0, duration) : 0
 }
 
-export function deriveMeta(events: unknown[]): DerivedMeta {
+export function deriveMeta(events: ReadonlyArray<unknown>): DerivedMeta {
 	let recordedWidth = 1280
 	let recordedHeight = 720
 	const actionMarkers: ActionMarker[] = []
@@ -259,7 +259,7 @@ export function useReplayPlayer(): ReplayPlayerContextValue {
 	return ctx
 }
 
-const EMPTY_EVENTS: unknown[] = []
+const EMPTY_EVENTS: ReadonlyArray<unknown> = []
 
 /** Read the engine's playhead, treating "no engine yet" as 0. */
 function engineTimeMs(engine: ReplayEngine | null): number {
@@ -329,13 +329,27 @@ export function ReplayPlayerProvider({
 		enabled: eventsOverride === undefined,
 	})
 
+	// Normalized separately from the status derivation below, and keyed only on
+	// the injected array. Doing it inline would mint a fresh array on every
+	// recompute of that memo — see the identity note on `events`.
+	const overrideEvents = React.useMemo(
+		() => (eventsOverride ? normalizeEvents(eventsOverride) : undefined),
+		[eventsOverride],
+	)
+
+	// `events` is the engine's mount key, so its IDENTITY is load-bearing, not
+	// just its contents. This memo depends on `manifestResult`, which changes on
+	// every manifest refetch — so building a new array in here (a `normalizeEvents`
+	// call, or a `[...loader.seedEvents]` spread) tears the engine down and
+	// rebuilds it every few seconds on a live session. Both branches now hand back
+	// an already-stable array instead.
 	const { status, error, events } = React.useMemo<{
 		status: ReplayLoadStatus
 		error: unknown
-		events: unknown[]
+		events: ReadonlyArray<unknown>
 	}>(() => {
 		if (eventsOverride) {
-			const decoded = normalizeEvents(eventsOverride)
+			const decoded = overrideEvents ?? EMPTY_EVENTS
 			if (decoded.length >= 2) return { status: "ready" as const, error: null, events: decoded }
 			// Keep injected tests on the same status path as warehouse-loaded sessions.
 			return {
@@ -366,7 +380,7 @@ export function ReplayPlayerProvider({
 					}
 				}
 				if (loader.seedEvents.length >= 2) {
-					return { status: "ready" as const, error: null, events: [...loader.seedEvents] }
+					return { status: "ready" as const, error: null, events: loader.seedEvents }
 				}
 				// Manifest says there are chunks; the opening window is still in
 				// flight, or every chunk in it was unparseable.
@@ -379,7 +393,15 @@ export function ReplayPlayerProvider({
 					: { status: "loading" as const, error: null, events: EMPTY_EVENTS }
 			})
 			.orElse(() => ({ status: "loading" as const, error: null, events: EMPTY_EVENTS }))
-	}, [manifestResult, eventsOverride, recorded, sessionActive, loader.seedEvents, loader.loadError])
+	}, [
+		manifestResult,
+		eventsOverride,
+		overrideEvents,
+		recorded,
+		sessionActive,
+		loader.seedEvents,
+		loader.loadError,
+	])
 
 	// Playable length from the manifest — known before any payload is fetched.
 	const manifestTotalMs = React.useMemo(() => manifestDurationMs(manifestChunks), [manifestChunks])