@camstack/addon-pipeline 1.2.6 → 1.2.8

package/dist/stream-broker/index.mjs

@@ -1,7 +1,7 @@
-import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { $ as parseProfileBrokerId, G as DeviceFeature, H as errMsg, K as DeviceType, O as maskUrlCredentials, U as BaseAddon, V as webrtcSessionCapability, W as CAM_PROFILE_ORDER, X as makeProfileBrokerId, Y as isEvent, Z as makeSourceBrokerId, at as discriminatedUnion, ct as number, dt as string, ft as union, g as addonWidgetsSourceCapability, it as boolean, j as nodePin, l as EncodeProfileSchema, lt as object, m as RingBuffer, nt as _enum, pt as EventCategory, q as createEvent, rt as array, st as literal, ut as record, y as cameraStreamsCapability, z as streamBrokerCapability } from "../dist-Bw_V5L0r.mjs";
+import { l as __require, n as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-WO-foD7W.mjs";
+import { B as webrtcSessionCapability, G as DeviceType, H as BaseAddon, J as isEvent, K as createEvent, O as maskUrlCredentials, Q as parseProfileBrokerId, R as streamBrokerCapability, U as CAM_PROFILE_ORDER, V as errMsg, W as DeviceFeature, X as makeSourceBrokerId, Y as makeProfileBrokerId, ct as object, dt as union, ft as EventCategory, g as addonWidgetsSourceCapability, it as discriminatedUnion, j as nodePin, l as EncodeProfileSchema, lt as record, m as RingBuffer, nt as array, ot as literal, rt as boolean, st as number, tt as _enum, ut as string, y as cameraStreamsCapability } from "../dist-owmpaeIY.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
-import { n as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-CwUb5v3Y.mjs";
+import { t as extractKeyframes } from "../fmp4-keyframes-qOgJBjMO.mjs";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
@@ -10406,6 +10406,17 @@ var StreamBroker = class StreamBroker {
 	placeholderTimer;
 	reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
 	/**
+	* Dial rate-limiter (2026-07-23 storm fix): the earliest wall-clock at
+	* which ANY caller may dial the source again. Armed on every dial ATTEMPT
+	* with the current backoff window. The 30s reconnect timer was honored on
+	* ITS path, but parallel dial channels (demand resume, broker recreation)
+	* re-dialed instantly — an unreachable camera (614 EHOSTUNREACH) looped
+	* hundreds of dials/sec, the relayed log flood ballooned hub-main to
+	* 1.9 GB in 4 h and starved the HTTPS API. This gate makes the backoff a
+	* BROKER-level invariant instead of a per-path courtesy.
+	*/
+	nextDialAllowedAt = 0;
+	/**
 	* "First video" watchdog. Battery-cam rfc4571 sources sometimes
 	* complete TCP handshake on the loopback but the lib's dedicated
 	* session never delivers video bytes (camera fails to start the
@@ -10718,6 +10729,7 @@ var StreamBroker = class StreamBroker {
 		clearTimeout(this.reconnectTimer);
 		this.reconnectTimer = void 0;
 		this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+		this.nextDialAllowedAt = 0;
 		this.lastRefreshRequestAt = 0;
 		this.logger?.info("reconnect kicked — publisher refreshed source");
 		this.scheduleReconnect();
@@ -10757,6 +10769,21 @@ var StreamBroker = class StreamBroker {
 			this.logger?.info("Broker registered idle — no demand, source dial deferred");
 			return;
 		}
+		const dialWaitMs = this.nextDialAllowedAt - Date.now();
+		if (dialWaitMs > 0) {
+			this._status = "connecting";
+			if (!this.reconnectTimer) {
+				this.logger?.info("dial rate-limited — deferring to backoff window", { meta: { waitMs: dialWaitMs } });
+				this.reconnectTimer = setTimeout(() => {
+					this.reconnectTimer = void 0;
+					if (this.manualStop) return;
+					const src = this.resolveCurrentSource();
+					if (src) this.start(src);
+				}, dialWaitMs);
+			}
+			return;
+		}
+		this.nextDialAllowedAt = Date.now() + this.reconnectDelayMs;
 		this._status = "connecting";
 		if (source.ffmpegParser) {
 			this._status = "connecting";
@@ -11703,6 +11730,7 @@ var StreamBroker = class StreamBroker {
 				this.logger?.info("rtmp: streaming");
 				this._status = "streaming";
 				this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+				this.nextDialAllowedAt = 0;
 				this.stopErrorPlaceholder();
 			},
 			onError: (error) => {
@@ -11777,6 +11805,7 @@ var StreamBroker = class StreamBroker {
 				this.logger?.info("ffmpeg source: streaming");
 				this._status = "streaming";
 				this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+				this.nextDialAllowedAt = 0;
 				this.stopErrorPlaceholder();
 			},
 			onError: (error) => {
@@ -11846,6 +11875,7 @@ var StreamBroker = class StreamBroker {
 				if (this.stopping) return;
 				this._status = "streaming";
 				this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+				this.nextDialAllowedAt = 0;
 				this.stopErrorPlaceholder();
 				this.cancelFirstVideoWatchdog();
 				this.kickRtpActivityWatchdog();
@@ -12155,6 +12185,7 @@ var StreamBroker = class StreamBroker {
 			this.destroyRfc4571Reader();
 			this._status = "error";
 			this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+			this.nextDialAllowedAt = 0;
 			this.lastRefreshRequestAt = 0;
 			this.notifySourceRefresh();
 			this.scheduleReconnect();
@@ -12216,6 +12247,7 @@ var StreamBroker = class StreamBroker {
 			this.destroyNativeClient();
 			this._status = "error";
 			this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+			this.nextDialAllowedAt = 0;
 			this.scheduleReconnect();
 			return;
 		}
@@ -12224,6 +12256,7 @@ var StreamBroker = class StreamBroker {
 			this.destroyRfc4571Reader();
 			this._status = "error";
 			this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+			this.nextDialAllowedAt = 0;
 			this.notifySourceRefresh();
 			this.scheduleReconnect();
 			return;
@@ -12283,11 +12316,7 @@ var StreamBroker = class StreamBroker {
 			if (this.manualStop) return;
 			const src = this.resolveCurrentSource();
 			if (!src) return;
-			this._status = "connecting";
-			if (src.ffmpegParser) this.startFfmpegSourceReader(src);
-			else if (src.type === "rtmp") this.startRtmpReader(src);
-			else if (src.type === "rfc4571") this.startRfc4571Reader(src);
-			else this.startRtspReader(src);
+			this.start(src);
 		}, this.reconnectDelayMs);
 		this.reconnectDelayMs = Math.min(this.reconnectDelayMs * 2, MAX_RECONNECT_DELAY_MS);
 	}
@@ -13543,6 +13572,15 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* time without an activation handshake.
 	*/
 	brokers = /* @__PURE__ */ new Map();
+	/**
+	* Devices whose `deviceManager` meta says `disabled:true` — mirrored by the
+	* SAME `reconcileAllCatalogs` poll that already reads `listAll` (the D8
+	* reconcile backstop; no event plumbing). While a device is in this set,
+	* `ensureBroker` refuses (re)creation so a retrying audio/frame subscriber
+	* cannot resurrect a released broker, and the reconcile releases any broker
+	* that still exists. Cleared by the same poll on re-enable.
+	*/
+	disabledDevices = /* @__PURE__ */ new Set();
 	/** profileBrokerId (`${deviceId}/${profile}`) → sourceBrokerId currently aliased. */
 	profileRestreamerBindings = /* @__PURE__ */ new Map();
 	/** Per-device published cam-stream registry. */
@@ -14157,6 +14195,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* unchanged behavior.
 	*/
 	async ensureBrokerForWebrtcSession(deviceId, brokerId, camStreamId, tier) {
+		if (this.disabledDevices.has(deviceId)) return;
 		if (this.brokers.has(brokerId)) return;
 		if (this.remoteBrokerAdapters.has(brokerId)) return;
 		if (camStreamId === void 0) return;
@@ -14581,7 +14620,33 @@ var StreamBrokerManager = class StreamBrokerManager {
 			return;
 		}
 		const cameras = devices.filter((d) => d.isCamera || d.type === DeviceType.Camera);
-		await Promise.allSettled(cameras.map((d) => this.reconcileDeviceCatalog(d.id)));
+		for (const d of cameras) if (d.disabled) {
+			const firstSeen = !this.disabledDevices.has(d.id);
+			this.disabledDevices.add(d.id);
+			await this.releaseDisabledDeviceBrokers(d.id, firstSeen);
+		} else this.disabledDevices.delete(d.id);
+		await Promise.allSettled(cameras.filter((d) => !d.disabled).map((d) => this.reconcileDeviceCatalog(d.id)));
+	}
+	/** Release every live broker of a disabled device (idempotent — later poll
+	*  ticks find none and no-op). `logTransition` marks the disable EDGE. */
+	async releaseDisabledDeviceBrokers(deviceId, logTransition) {
+		const streams = this.cameraStreams.get(deviceId);
+		if (!streams) return;
+		const live = Array.from(streams.keys()).filter((camStreamId) => this.brokers.has(brokerIdFor(deviceId, camStreamId)));
+		if (live.length === 0) return;
+		if (logTransition || live.length > 0) this.logger.info("device disabled — releasing its brokers (no dial while disabled)", {
+			tags: { deviceId },
+			meta: { camStreamIds: live }
+		});
+		for (const camStreamId of live) await this.releaseBroker(deviceId, camStreamId).catch((err) => {
+			this.logger.warn("disabled-device broker release failed", {
+				tags: {
+					deviceId,
+					camStreamId
+				},
+				meta: { error: errMsg(err) }
+			});
+		});
 	}
 	/**
 	* Startup catalog pull: run a full reconcile, then a bounded number of extra
@@ -16325,6 +16390,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		}
 	}
 	async ensureBroker(deviceId, camStreamId) {
+		if (this.disabledDevices.has(deviceId)) return;
 		const cam = this.cameraStreams.get(deviceId)?.get(camStreamId);
 		if (!cam) return;
 		const brokerId = brokerIdFor(deviceId, camStreamId);
@@ -16875,6 +16941,11 @@ var ControlMessageSchema = discriminatedUnion("t", [
 		t: literal("scrubCommit"),
 		epoch: number()
 	}),
+	object({ t: literal("scrubStart") }),
+	object({
+		t: literal("scrubTo"),
+		epoch: number()
+	}),
 	object({
 		t: literal("setRate"),
 		rate: number().min(0).max(4)
@@ -17023,6 +17094,31 @@ var WAIT_TICK_MS = 250;
 * instead of merging the two feeds.
 */
 var SEEK_DISCONTINUITY_MS = 250;
+/**
+* Coalescing window for feeder-scrub `scrubTo` (experimental). Pointer-move
+* targets arrive far faster than a segment demux completes; the feeder collapses
+* them to at most one keyframe push per this window (≈ 16 pushes/s), always
+* pushing only the LATEST pending target (latest-wins). The FIRST move fires a
+* leading-edge tick immediately; subsequent moves ride the pending timer.
+*
+* Tightened 100 → 60 ms: same-fragment moves are memo/cache hits (zero demux) so
+* the window is now the dominant per-push cost inside a fragment, and 60 ms is
+* sustainable there — cross-fragment moves remain paced by the demux + the
+* one-in-flight guard, so this cannot spawn parallel demuxes.
+*/
+var SCRUB_COALESCE_MS = 60;
+/**
+* Upper bound on the per-scrub-session fragment cache (LRU by segment `startMs`).
+* A demuxed keyframe set is one AU per fragment, so 8 fragments is a few KB;
+* back-and-forth drags over this window push instantly with zero re-demux.
+*/
+var SCRUB_CACHE_MAX = 8;
+/**
+* Consecutive same-direction `scrubTo` deltas required before a direction-aware
+* prefetch commits its (single) background slot. Two deltas ⇒ the drag shows a
+* sustained direction, so a jittery/reversing drag never wastes the slot.
+*/
+var SCRUB_PREFETCH_DIR_THRESHOLD = 2;
 var RecordedFeeder = class {
 	deps;
 	clock = new MonotonicClock();
@@ -17053,6 +17149,61 @@ var RecordedFeeder = class {
 	* the pre-seek position when the client changes rate right after a seek.
 	*/
 	inFlightSeekEpochMs = null;
+	/**
+	* EXPERIMENTAL feeder-scrub sub-mode. While true the normal advance/feed loop
+	* is suspended and each coalesced `scrubTick` pushes the covering fragment's
+	* nearest keyframe ≤ the drag target. `scrubToken` is the MODE-EXIT guard (not
+	* a per-move token): it is bumped on `beginScrub`, on the commit `seek`, and on
+	* `dispose`, so an in-flight tick whose captured generation no longer matches
+	* drops itself. Latest-wins across rapid moves is handled by COALESCING —
+	* `scrubPendingEpochMs` always holds the newest target, and one tick per
+	* `SCRUB_COALESCE_MS` window processes it.
+	*/
+	scrubbing = false;
+	scrubToken = 0;
+	/** The newest un-processed drag target (null when the tick cycle has drained). */
+	scrubPendingEpochMs = null;
+	/**
+	* The active coalescing timer. Non-null means a tick cycle is live (scheduled
+	* OR running its async load) — it is the single re-entrancy guard, so a burst
+	* of `scrubTo` calls coalesce onto `scrubPendingEpochMs` instead of spawning
+	* parallel demuxes.
+	*/
+	scrubTimer = null;
+	/**
+	* The fragment demuxed by the last tick (same-fragment memo): consecutive drag
+	* targets inside ONE fragment reuse these access units instead of re-running
+	* readBytes/demux (ffmpeg) per pointer move. Reset on fragment change + exit.
+	*/
+	scrubSegment = null;
+	/**
+	* Per-scrub-session LRU of demuxed keyframe sets, keyed by segment `startMs`
+	* (Map insertion order IS the LRU order; a hit re-inserts to mark it most
+	* recent). Held ACROSS re-entrant drags in the same session — recorded footage
+	* is immutable, so a revisited fragment (back-and-forth drag) pushes instantly
+	* with zero re-demux. Bounded to {@link SCRUB_CACHE_MAX}; cleared only on the
+	* commit `seek`, `dispose`, and goLive teardown (all of which dispose/reset the
+	* feeder), never on `beginScrub`.
+	*/
+	scrubCache = /* @__PURE__ */ new Map();
+	/**
+	* The last drag target a `scrubTick` PROCESSED (null before the first). The
+	* sign of `(newTarget − this)` is the drag direction that steers prefetch.
+	*/
+	scrubPrevTarget = null;
+	/**
+	* Signed run-length of consecutive same-direction `scrubTo` deltas (+ forward,
+	* − backward). A prefetch commits only once `|run| ≥ SCRUB_PREFETCH_DIR_THRESHOLD`;
+	* a reversal or an in-fragment no-move resets it.
+	*/
+	scrubDirRun = 0;
+	/**
+	* The SECOND bounded concurrency slot: `true` while a direction-aware prefetch
+	* demux is in flight. At most one prefetch runs at a time and it only fills
+	* `scrubCache` — it never pushes, never touches the pending/timer/latest-wins
+	* state, and never blocks the live coalesced tick.
+	*/
+	scrubPrefetchInFlight = false;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -17064,6 +17215,18 @@ var RecordedFeeder = class {
 	*/
 	async seek(epochMs) {
 		const token = ++this.seekToken;
+		if (this.scrubbing) {
+			this.scrubbing = false;
+			this.scrubToken++;
+			this.scrubSegment = null;
+			this.scrubCache.clear();
+			this.scrubPrevTarget = null;
+			this.scrubDirRun = 0;
+			if (this.scrubTimer) {
+				clearTimeout(this.scrubTimer);
+				this.scrubTimer = null;
+			}
+		}
 		this.advanceToken++;
 		this.inFlightSeekEpochMs = epochMs;
 		try {
@@ -17142,6 +17305,200 @@ var RecordedFeeder = class {
 		this.seek(this.inFlightSeekEpochMs ?? this.cursorMs);
 	}
 	/**
+	* EXPERIMENTAL feeder-scrub: enter the scrub sub-mode. Aborts any in-flight
+	* seek/advance loop (latest-wins, exactly like `seek()` does up-front) and
+	* suspends the ~1 Hz position timer — during a drag position is reported per
+	* pushed keyframe instead. `this.rate` is preserved for the post-commit resume
+	* (the commit `seek` re-enters at the same rate).
+	*
+	* Idempotent WITHIN a drag: a second `beginScrub` while already scrubbing is a
+	* NO-OP. The app may re-send `scrubStart` mid-gesture (the observed repeated
+	* `scrubStart` storm), and resetting the token/coalescing state on each re-send
+	* would abort in-flight keyframe work and restart the drag — the exact stutter
+	* this guards against. The ONLY exit from scrub mode is the commit `seek()`
+	* (which flips `scrubbing` false and clears the session cache) or `dispose()`;
+	* a genuinely NEW drag is therefore always preceded by that exit, so its
+	* `beginScrub` runs the full reset below. (D-scrub-ux)
+	*/
+	beginScrub() {
+		if (this.disposed || this.scrubbing) return;
+		this.seekToken++;
+		this.advanceToken++;
+		this.scrubbing = true;
+		this.scrubToken++;
+		this.scrubPendingEpochMs = null;
+		this.scrubSegment = null;
+		this.scrubPrevTarget = null;
+		this.scrubDirRun = 0;
+		if (this.scrubTimer) {
+			clearTimeout(this.scrubTimer);
+			this.scrubTimer = null;
+		}
+		this.stopPositionReports();
+	}
+	/**
+	* EXPERIMENTAL feeder-scrub: register a drag target. Records the newest target
+	* and, if no tick cycle is live, starts a leading-edge tick. A burst of moves
+	* within the coalescing window collapses onto `scrubPendingEpochMs` (latest-
+	* wins) so only one keyframe is demuxed+pushed per `SCRUB_COALESCE_MS`. A
+	* `scrubTo` without a prior `beginScrub` (or after commit/dispose) is a no-op.
+	*/
+	scrubTo(epochMs) {
+		if (this.disposed || !this.scrubbing) return;
+		this.scrubPendingEpochMs = epochMs;
+		if (this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
+	}
+	/**
+	* One coalesced feeder-scrub push. Captures the newest pending target + the
+	* current mode generation, resolves the covering fragment (reusing the memo'd
+	* one when the target stays inside it), picks the nearest keyframe ≤ the
+	* target, stamps a discontinuity, and pushes that single access unit. Re-arms
+	* itself after `SCRUB_COALESCE_MS` while more moves are pending; otherwise
+	* ends the cycle. Video only — no audio during scrub. A gap target holds the
+	* last pushed frame (no push, no error).
+	*/
+	async scrubTick() {
+		const gen = this.scrubToken;
+		const target = this.scrubPendingEpochMs;
+		this.scrubPendingEpochMs = null;
+		if (this.disposed || !this.scrubbing || gen !== this.scrubToken || target === null) {
+			this.scrubTimer = null;
+			return;
+		}
+		try {
+			const loc = await this.withTimeout(this.deps.locate({
+				deviceId: this.deps.deviceId,
+				profile: this.deps.profile,
+				epochMs: target
+			}));
+			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
+			if (loc.kind === "gap") return;
+			let seg = this.scrubSegment;
+			if (!seg || seg.startMs !== loc.startMs) {
+				seg = this.scrubCacheGet(loc.startMs);
+				if (!seg) {
+					const loaded = await this.loadAus(loc.startMs, false, true);
+					if (this.disposed || !this.scrubbing || gen !== this.scrubToken || loaded === null) return;
+					seg = {
+						startMs: loc.startMs,
+						durMs: loc.durMs,
+						aus: loaded.video
+					};
+					this.scrubCachePut(seg);
+				}
+				this.scrubSegment = seg;
+			}
+			const au = seg.aus[this.pickScrubKeyframe(seg, target)];
+			if (!au) return;
+			if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+			this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+			this.clockHasAdvanced = true;
+			this.deps.onPosition(this.clampIntoSegment(seg, target));
+			this.maybeScrubPrefetch(seg, target, gen);
+		} catch {} finally {
+			if (gen !== this.scrubToken) {} else if (!this.disposed && this.scrubbing && this.scrubPendingEpochMs !== null) this.scrubTimer = setTimeout(() => void this.scrubTick(), SCRUB_COALESCE_MS);
+			else this.scrubTimer = null;
+		}
+	}
+	/**
+	* Index of the nearest keyframe at-or-before the drag target within `seg`
+	* (default 0 — the fragment's params-fused IDR, which the demux contract
+	* guarantees). Scans the access units whose PTS offset is ≤ the target offset
+	* and returns the LAST keyframe among them, so the pushed frame is standalone-
+	* decodable yet as close to the target as the GOP structure allows.
+	*/
+	pickScrubKeyframe(seg, target) {
+		const first = seg.aus[0];
+		if (!first) return 0;
+		const offsetMs = target - seg.startMs;
+		let idx = 0;
+		for (let i = 0; i < seg.aus.length; i++) {
+			const au = seg.aus[i];
+			if (!au) continue;
+			if (au.ptsMs - first.ptsMs > offsetMs) break;
+			if (au.keyframe) idx = i;
+		}
+		return idx;
+	}
+	/**
+	* Scrub fragment cache lookup with LRU touch: a hit is re-inserted so it moves
+	* to the most-recent end of the Map's insertion order (the eviction cursor is
+	* the oldest key).
+	*/
+	scrubCacheGet(startMs) {
+		const seg = this.scrubCache.get(startMs);
+		if (!seg) return null;
+		this.scrubCache.delete(startMs);
+		this.scrubCache.set(startMs, seg);
+		return seg;
+	}
+	/** Insert (or refresh) a demuxed fragment, evicting the oldest over the cap. */
+	scrubCachePut(seg) {
+		this.scrubCache.delete(seg.startMs);
+		this.scrubCache.set(seg.startMs, seg);
+		while (this.scrubCache.size > SCRUB_CACHE_MAX) {
+			const oldest = this.scrubCache.keys().next().value;
+			if (oldest === void 0) break;
+			this.scrubCache.delete(oldest);
+		}
+	}
+	/**
+	* Update the drag-direction run from the just-served target and, once the drag
+	* shows a sustained direction, kick off a single background prefetch of the
+	* NEXT fragment in that direction. Prefetch fills the cache only — it never
+	* pushes, so crossing into the neighbour later is an instant cache hit.
+	*/
+	maybeScrubPrefetch(seg, target, gen) {
+		const prev = this.scrubPrevTarget;
+		this.scrubPrevTarget = target;
+		if (prev === null) {
+			this.scrubDirRun = 0;
+			return;
+		}
+		const dir = target > prev ? 1 : target < prev ? -1 : 0;
+		if (dir === 0) {
+			this.scrubDirRun = 0;
+			return;
+		}
+		this.scrubDirRun = Math.sign(this.scrubDirRun) === dir ? this.scrubDirRun + dir : dir;
+		if (Math.abs(this.scrubDirRun) < SCRUB_PREFETCH_DIR_THRESHOLD) return;
+		if (this.scrubPrefetchInFlight) return;
+		const probeMs = dir === 1 ? seg.startMs + seg.durMs + 1 : seg.startMs - 1;
+		if (probeMs < 0) return;
+		this.scrubPrefetch(probeMs, gen);
+	}
+	/**
+	* Background (second-slot) prefetch: locate + keyframe-only demux the fragment
+	* covering `probeMs` into `scrubCache`. Bounded to one in flight; aborts at any
+	* teardown (`disposed` / left scrub / a bumped `scrubToken`); a failure is
+	* swallowed (the neighbour just demuxes on demand). Never pushes and never
+	* mutates latest-wins state.
+	*/
+	async scrubPrefetch(probeMs, gen) {
+		if (this.scrubPrefetchInFlight) return;
+		this.scrubPrefetchInFlight = true;
+		try {
+			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
+			const loc = await this.withTimeout(this.deps.locate({
+				deviceId: this.deps.deviceId,
+				profile: this.deps.profile,
+				epochMs: probeMs
+			}));
+			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
+			if (loc.kind !== "segment") return;
+			if (this.scrubCache.has(loc.startMs)) return;
+			const loaded = await this.loadAus(loc.startMs, false, true);
+			if (this.disposed || !this.scrubbing || gen !== this.scrubToken || loaded === null) return;
+			this.scrubCachePut({
+				startMs: loc.startMs,
+				durMs: loc.durMs,
+				aus: loaded.video
+			});
+		} catch {} finally {
+			this.scrubPrefetchInFlight = false;
+		}
+	}
+	/**
 	* Feed exactly one frame forward (+1) or backward (-1). Only meaningful while
 	* paused over a segment (rate 0, recorded mode) — ignored otherwise. Forward
 	* at a segment end crosses into the next segment (gaps are skipped via the
@@ -17153,7 +17510,7 @@ var RecordedFeeder = class {
 	* step is still in flight.
 	*/
 	stepFrame(dir) {
-		if (this.disposed || this.rate !== 0 || this.stepInFlight) return;
+		if (this.disposed || this.rate !== 0 || this.stepInFlight || this.scrubbing) return;
 		this.stepInFlight = true;
 		this.doStep(dir).catch(() => {}).finally(() => {
 			this.stepInFlight = false;
@@ -17480,8 +17837,10 @@ var RecordedFeeder = class {
 	*  access units. Keyed on `seekToken` so a fresh seek aborts an in-flight load
 	*  (latest-wins). Returns null on abort. Audio demux failures yield [] (audio
 	*  never blocks video). `wantAudio: false` skips the audio transcode entirely
-	*  (paused scrubs would throw it away). */
-	async loadAus(startMs, wantAudio = true) {
+	*  (paused scrubs would throw it away). `useScrubDemux: true` selects the
+	*  keyframe-only scrub demux (`deps.demuxScrub`, falling back to `deps.demux`
+	*  when absent — flag-off byte-identity). */
+	async loadAus(startMs, wantAudio = true, useScrubDemux = false) {
 		const token = this.seekToken;
 		const bytes = await this.withTimeout(this.deps.readBytes({
 			deviceId: this.deps.deviceId,
@@ -17489,7 +17848,8 @@ var RecordedFeeder = class {
 			startMs
 		}));
 		if (this.disposed || token !== this.seekToken) return null;
-		const video = await this.withTimeout(this.deps.demux(bytes));
+		const demux = useScrubDemux && this.deps.demuxScrub ? this.deps.demuxScrub : this.deps.demux;
+		const video = await this.withTimeout(demux(bytes));
 		if (this.disposed || token !== this.seekToken) return null;
 		let audio = [];
 		if (wantAudio && this.deps.demuxAudio && this.deps.sink.pushAudioPcmu) {
@@ -17538,6 +17898,16 @@ var RecordedFeeder = class {
 		this.disposed = true;
 		this.seekToken++;
 		this.advanceToken++;
+		this.scrubbing = false;
+		this.scrubToken++;
+		this.scrubSegment = null;
+		this.scrubCache.clear();
+		this.scrubPrevTarget = null;
+		this.scrubDirRun = 0;
+		if (this.scrubTimer) {
+			clearTimeout(this.scrubTimer);
+			this.scrubTimer = null;
+		}
 		this.stopPositionReports();
 	}
 };
@@ -17571,6 +17941,12 @@ var TimelineSession = class {
 			case "scrubCommit":
 				await (this.mode === "recorded" && this.feeder ? this.feeder : this.enterRecorded()).seek(msg.epoch);
 				break;
+			case "scrubStart":
+				(this.mode === "recorded" && this.feeder ? this.feeder : this.enterRecorded()).beginScrub();
+				break;
+			case "scrubTo":
+				if (this.mode === "recorded") this.feeder?.scrubTo(msg.epoch);
+				break;
 			case "setRate":
 				this.feeder?.setRate(msg.rate);
 				break;
@@ -17890,7 +18266,7 @@ function demuxMpegTsToAnnexB(ts) {
 	let current = null;
 	const finalize = () => {
 		if (current === null) return;
-		const pes = current.length === 1 ? current[0] : concat(current);
+		const pes = current.length === 1 ? current[0] : concat$1(current);
 		current = null;
 		const split = splitPes(pes);
 		if (split === null || split.es.length === 0) return;
@@ -17921,7 +18297,7 @@ function demuxMpegTsToAnnexB(ts) {
 	};
 }
 /** Concatenate TS payload fragments into one contiguous PES buffer. */
-function concat(parts) {
+function concat$1(parts) {
 	let total = 0;
 	for (const p of parts) total += p.length;
 	const out = new Uint8Array(total);
@@ -17978,6 +18354,33 @@ var SEGMENT_DEMUX_FFMPEG_ARGS = [
 	"pipe:1"
 ];
 /**
+* ffmpeg arguments for the SCRUB keyframe-only demux: same crash-isolated
+* `-c:v copy` mpegts remux as {@link SEGMENT_DEMUX_FFMPEG_ARGS}, but `-frames:v 1`
+* stops after the FIRST output access unit — a recorded fragment is a single
+* IDR-led GOP, so frame 1 is the params-fused keyframe the scrub sub-mode needs
+* (it never renders a delta frame). This reliably yields exactly the IDR with
+* its VPS/SPS/PPS fused, whereas input-side `-discard nokey` is a no-op over the
+* `pipe:0` fragmented-mp4 demuxer (empirically kept 39/40 packets). Exported for
+* the spec.
+*/
+var SEGMENT_DEMUX_SCRUB_FFMPEG_ARGS = [
+	"-hide_banner",
+	"-loglevel",
+	"error",
+	"-i",
+	"pipe:0",
+	"-map",
+	"0:v:0",
+	"-frames:v",
+	"1",
+	"-c:v",
+	"copy",
+	"-an",
+	"-f",
+	"mpegts",
+	"pipe:1"
+];
+/**
 * Demux a self-contained H.264 or H.265 `.m4s` fragment into ordered Annex-B
 * access units.
 *
@@ -18003,6 +18406,253 @@ async function demuxSegmentToAnnexB(bytes, ffmpegPath = "ffmpeg") {
 		codec
 	}));
 }
+/**
+* Keyframe-only demux for the feeder-scrub sub-mode: remux with `-frames:v 1`
+* (single-GOP fragment ⇒ the one IDR) and return ONLY keyframe access units.
+* The scrub path never renders delta frames — it always pushes the nearest
+* keyframe ≤ the drag target — so extracting only the IDR keeps the per-session
+* scrub fragment cache tiny (one AU/fragment instead of the full ~40) with no
+* loss of scrub fidelity.
+*
+* Wall time per fragment is dominated by the ffmpeg subprocess spawn, so this is
+* NOT meaningfully faster per fragment than {@link demuxSegmentToAnnexB}; the
+* frequency win comes from the feeder's fragment cache + direction-aware
+* prefetch (which eliminate / overlap the demux), for which this compact
+* keyframe-only payload is the cache unit.
+*
+* Defensive parse-side filter: keeps `keyframe` AUs, falling back to the first
+* AU (the demux contract's params-fused IDR) if none were flagged, so the result
+* is keyframes-only yet never empty for a valid fragment.
+*
+* @param bytes - The full `.m4s` fragment (one moov + one IDR-led GOP).
+* @param ffmpegPath - ffmpeg binary path (defaults to PATH `ffmpeg`).
+*/
+async function demuxSegmentKeyframesToAnnexB(bytes, ffmpegPath = "ffmpeg") {
+	const { codec, accessUnits } = demuxMpegTsToAnnexB(await runFfmpegOnce({
+		ffmpegPath,
+		args: SEGMENT_DEMUX_SCRUB_FFMPEG_ARGS,
+		input: bytes
+	}));
+	const mapped = accessUnits.map((au) => ({
+		data: au.data,
+		ptsMs: au.ptsMs,
+		keyframe: au.keyframe,
+		codec
+	}));
+	const keyframes = mapped.filter((au) => au.keyframe);
+	return keyframes.length > 0 ? keyframes : mapped.slice(0, 1);
+}
+//#endregion
+//#region src/stream-broker/recorded/avcc-annexb.ts
+/**
+* avcc-annexb — pure byte helpers to turn an ISO-BMFF (mp4) length-prefixed
+* video sample plus its `avcC`/`hvcC` decoder config into an Annex-B access
+* unit with the parameter sets prepended (SPS/PPS for H.264, VPS/SPS/PPS for
+* H.265).
+*
+* mp4 stores VCL NALs length-prefixed (AVCC/HVCC: a 1–4 byte big-endian length
+* field, `lengthSizeMinusOne+1`, before each NAL) and keeps the parameter sets
+* OUT of the samples, inside the `avcC`/`hvcC` box. A raw decoder / RTP
+* packetizer needs Annex-B start codes (`00 00 00 01`) AND the parameter sets
+* fused onto every IDR. These helpers do exactly that in JS — no ffmpeg, no
+* decode, byte copies only — so the feeder-scrub keyframe path can skip the
+* per-fragment ffmpeg spawn.
+*
+* All functions are pure and total for well-formed input; malformed config /
+* sample bytes throw a `RangeError` (the caller treats a throw as "fall back to
+* ffmpeg"). The `description` bytes are the box payload WITH the 8-byte box
+* header already stripped (i.e. starting at `configurationVersion`), matching
+* `mp4box`'s `avcC`/`hvcC` DataStream output minus header — see
+* `recorder/scrub/fmp4-keyframes.ts` `extractDescription`.
+*/
+/** Annex-B 4-byte start code prepended before every emitted NAL. */
+var START_CODE = Uint8Array.of(0, 0, 0, 1);
+/** Big-endian unsigned read of `size` (1..4) bytes at `off`. */
+function readUint(bytes, off, size) {
+	if (off + size > bytes.length) throw new RangeError(`readUint out of range: off=${off} size=${size} len=${bytes.length}`);
+	let v = 0;
+	for (let i = 0; i < size; i++) v = v * 256 + bytes[off + i];
+	return v;
+}
+/**
+* NAL length-prefix size in bytes (`lengthSizeMinusOne + 1`, 1..4) read from the
+* decoder config. `avcC` carries it at byte 4 (low 2 bits); `hvcC` at byte 21
+* (low 2 bits).
+*/
+function parseNalLengthSize(description, isHevc) {
+	const idx = isHevc ? 21 : 4;
+	if (description.length <= idx) throw new RangeError(`config too short for lengthSizeMinusOne (len=${description.length})`);
+	return (description[idx] & 3) + 1;
+}
+/** Concatenate byte chunks into one Uint8Array. */
+function concat(chunks) {
+	let total = 0;
+	for (const c of chunks) total += c.length;
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const c of chunks) {
+		out.set(c, off);
+		off += c.length;
+	}
+	return out;
+}
+/** Push one Annex-B NAL (start code + payload) onto `chunks`. */
+function pushNal(chunks, payload) {
+	chunks.push(START_CODE, payload);
+}
+/**
+* Parse the `avcC` parameter sets (SPS then PPS), emitting each as an Annex-B
+* NAL. Layout after the 4-byte profile/level prefix: byte 4 low-2 = length
+* size; byte 5 low-5 = numSPS; then `[u16 len][SPS]…`; then `[u8 numPPS]`; then
+* `[u16 len][PPS]…`.
+*/
+function extractAvcParameterSets(desc) {
+	const chunks = [];
+	const numSps = desc[5] & 31;
+	let p = 6;
+	for (let i = 0; i < numSps; i++) {
+		const len = readUint(desc, p, 2);
+		p += 2;
+		if (p + len > desc.length) throw new RangeError("avcC SPS length overruns config");
+		pushNal(chunks, desc.subarray(p, p + len));
+		p += len;
+	}
+	const numPps = readUint(desc, p, 1);
+	p += 1;
+	for (let i = 0; i < numPps; i++) {
+		const len = readUint(desc, p, 2);
+		p += 2;
+		if (p + len > desc.length) throw new RangeError("avcC PPS length overruns config");
+		pushNal(chunks, desc.subarray(p, p + len));
+		p += len;
+	}
+	return chunks;
+}
+/**
+* Parse the `hvcC` parameter-set arrays (typically VPS, SPS, PPS in order),
+* emitting each contained NAL as Annex-B. Layout: byte 22 = numOfArrays; then
+* per array `[u8 flags+NALtype][u16 numNalus]` followed by `numNalus` ×
+* `[u16 len][NAL]`.
+*/
+function extractHevcParameterSets(desc) {
+	const chunks = [];
+	const numArrays = readUint(desc, 22, 1);
+	let p = 23;
+	for (let a = 0; a < numArrays; a++) {
+		p += 1;
+		const numNalus = readUint(desc, p, 2);
+		p += 2;
+		for (let n = 0; n < numNalus; n++) {
+			const len = readUint(desc, p, 2);
+			p += 2;
+			if (p + len > desc.length) throw new RangeError("hvcC NAL length overruns config");
+			pushNal(chunks, desc.subarray(p, p + len));
+			p += len;
+		}
+	}
+	return chunks;
+}
+/**
+* Parameter sets from the decoder config as one Annex-B blob (each NAL led by a
+* `00 00 00 01` start code): SPS+PPS for H.264, VPS+SPS+PPS (+ any hvcC arrays)
+* for H.265. Throws on a malformed config.
+*/
+function extractParameterSetsAnnexB(description, isHevc) {
+	return concat(isHevc ? extractHevcParameterSets(description) : extractAvcParameterSets(description));
+}
+/**
+* Convert one length-prefixed (AVCC/HVCC) sample into Annex-B: walk each
+* `nalLengthSize`-byte length field, replacing it with a `00 00 00 01` start
+* code. Handles multi-NAL samples (multiple slices / SEI + VCL). Throws if a
+* length field overruns the sample.
+*/
+function avccSampleToAnnexB(sample, nalLengthSize) {
+	const chunks = [];
+	let p = 0;
+	while (p + nalLengthSize <= sample.length) {
+		const len = readUint(sample, p, nalLengthSize);
+		p += nalLengthSize;
+		if (len === 0) continue;
+		if (p + len > sample.length) throw new RangeError("AVCC NAL length overruns sample");
+		pushNal(chunks, sample.subarray(p, p + len));
+		p += len;
+	}
+	if (chunks.length === 0) throw new RangeError("AVCC sample yielded no NALs");
+	return concat(chunks);
+}
+/**
+* Build a standalone-decodable Annex-B keyframe access unit: the config's
+* parameter sets, then the sample's NALs, all Annex-B framed. Throws on
+* malformed input (caller falls back to the ffmpeg demux).
+*/
+function buildKeyframeAnnexB(sample, description, isHevc) {
+	const nalLengthSize = parseNalLengthSize(description, isHevc);
+	return concat([extractParameterSetsAnnexB(description, isHevc), avccSampleToAnnexB(sample, nalLengthSize)]);
+}
+//#endregion
+//#region src/stream-broker/recorded/segment-demux-js.ts
+/**
+* segment-demux-js — PURE-JS keyframe demux for the feeder-scrub sub-mode.
+*
+* Replaces the per-fragment ffmpeg spawn ({@link demuxSegmentKeyframesToAnnexB},
+* a ~140 ms subprocess floor) with an in-process mp4box parse. A recorded `.m4s`
+* is a self-contained fragment (`+frag_keyframe+empty_moov+default_base_moof`)
+* carrying its own `moov`, so its `avcC`/`hvcC` parameter sets and its sync
+* sample(s) are all in the bytes we already hold — no init segment to fetch.
+*
+* Flow: reuse {@link extractKeyframes} (the proven mp4box sync-sample demux the
+* scrub-pack service already ships — box parsing is NOT duplicated here) to get
+* the codec `description` + length-prefixed sync samples, then
+* {@link buildKeyframeAnnexB} converts each to a standalone-decodable Annex-B
+* access unit with the parameter sets fused on. The result matches the
+* {@link AccessUnit} contract the ffmpeg path produces: `codec` H264|H265,
+* `keyframe:true`, and `ptsMs` segment-relative (offset from the first sync
+* sample — the only thing the feeder reads, via `au.ptsMs - first.ptsMs`).
+*
+* Anchoring `extractKeyframes(bytes, 0)` makes the first sync sample's `ts` = 0,
+* so `ptsMs` is a plain segment-relative offset in ms, exactly like the ffmpeg
+* demux's PES-derived deltas — `clampIntoSegment`/position reporting are
+* unaffected.
+*/
+/** True for a WebCodecs codec string that is HEVC (`hvc1.`/`hev1.`), else H.264. */
+function isHevcCodec(codec) {
+	return /^h[ev][vc]1\./i.test(codec);
+}
+/**
+* Pure-JS keyframe-only demux of one self-contained `.m4s` fragment. Returns the
+* fragment's sync-sample access unit(s) as params-fused Annex-B, or `null` if
+* mp4box found no video / no decodable keyframe (caller falls back to ffmpeg).
+* Throws only on a genuinely malformed decoder config / sample — the wrapper
+* ({@link demuxSegmentKeyframesPreferJs}) turns that into an ffmpeg fallback.
+*/
+async function demuxSegmentKeyframesJs(bytes) {
+	const extracted = await extractKeyframes(bytes, 0);
+	if (!extracted || extracted.keyframes.length === 0) return null;
+	const isHevc = isHevcCodec(extracted.codec);
+	const codec = isHevc ? "H265" : "H264";
+	return extracted.keyframes.slice(0, 1).map((k) => ({
+		data: buildKeyframeAnnexB(k.data, extracted.description, isHevc),
+		ptsMs: k.ts,
+		keyframe: true,
+		codec
+	}));
+}
+/**
+* Feeder-scrub demux: try the pure-JS keyframe extractor first, fall back to the
+* ffmpeg spawn ({@link demuxSegmentKeyframesToAnnexB}) if the JS parse yields no
+* keyframe or throws on malformed bytes. Preserves the exact {@link AccessUnit}
+* contract either way, so it is a drop-in for `RecordedFeederDeps.demuxScrub`.
+*/
+async function demuxSegmentKeyframesPreferJs(bytes, opts = {}) {
+	try {
+		const js = await demuxSegmentKeyframesJs(bytes);
+		if (js && js.length > 0) return js;
+		opts.onFfmpegFallback?.("mp4box parse found no keyframe");
+	} catch (err) {
+		opts.onFfmpegFallback?.(`mp4box parse threw: ${String(err)}`);
+	}
+	return demuxSegmentKeyframesToAnnexB(bytes, opts.ffmpegPath);
+}
 //#endregion
 //#region src/stream-broker/recorded/segment-audio.ts
 /**
@@ -18877,6 +19527,7 @@ var BrokerWebrtcServer = class {
 		const locateRecorded = this.locateRecordedSegment;
 		const readRecorded = this.readRecordedSegmentBytes;
 		const resolveFfmpeg = this.resolveFfmpegPath;
+		let scrubJsFallbackLogged = false;
 		if (locateRecorded && readRecorded) {
 			let timeline;
 			timeline = new TimelineSession({
@@ -18888,6 +19539,19 @@ var BrokerWebrtcServer = class {
 					locate: locateRecorded,
 					readBytes: readRecorded,
 					demux: (b) => demuxSegmentToAnnexB(b, resolveFfmpeg?.()),
+					demuxScrub: (b) => demuxSegmentKeyframesPreferJs(b, {
+						ffmpegPath: resolveFfmpeg?.(),
+						onFfmpegFallback: (reason) => {
+							if (scrubJsFallbackLogged) return;
+							scrubJsFallbackLogged = true;
+							sessionLogger.warn("recorded scrub: JS keyframe demux failed — ffmpeg fallback (once/session)", { meta: {
+								sessionId,
+								deviceId,
+								profile,
+								reason
+							} });
+						}
+					}),
 					demuxAudio: (b) => demuxSegmentToPcmu(b, resolveFfmpeg?.()),
 					sink: {
 						pushAccessUnit: (data, ts, codec) => session.pushRecordedAccessUnit(data, ts, codec),