@camstack/addon-pipeline 1.2.228 → 1.2.231

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $t as isEvent, A as RingBuffer, Dt as resolveEgressDecodeHwAccel, E as RATE_CONTROL_TIGHT, Gt as BaseAddon, Ht as invocationFromEncodeProfile, I as batteryCapability, J as egressTranscodeSharingKey, Jt as DeviceType, Kt as CAM_PROFILE_ORDER, L as cameraStreamsCapability, Lt as webrtcSessionCapability, M as addonWidgetsSourceCapability, Pt as streamBrokerCapability, R as createHwAccelCache, Rt as errMsg, T as RATE_CONTROL_RELAXED, Ut as isSoftwareDecode, V as declareLogChannel, Vt as buildFfmpegArgs$1, W as deriveBatteryPresence, Wt as BOOT_RECOVERY_BACKOFF_MS, Xt as createEvent, Y as egressTransportFromRequest, Zt as expandAudioChunkToF32le, _n as string, cn as array, en as makeProfileBrokerId, fn as literal, gn as record, h as EncodeProfileSchema, i as BatteryStatusSchema, in as parseProfileBrokerId, ln as boolean, lt as maskUrlCredentials, mn as object, nn as nodePin, ot as loadContributionCapability, pn as number, qt as DeviceFeature, sn as _enum, st as logChannelsCapability, tn as makeSourceBrokerId, un as discriminatedUnion, v as G711_SCALE_CORRECTION_DB, vn as union, yn as EventCategory, z as createLogChannelsProvider, zt as AUDIO_PRESETS } from "../dist-Dcp-eVbN.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-ClxCG7kX.mjs";
-import { c as PREBUFFER_MAX_MS, d as resolvePrebuffer, i as parseRestreamPath, l as capPreRollRequestMs, n as NO_DECLARATION, u as prebufferRetentionMs } from "../restream-intent-DWe2kInY.mjs";
+import { A as RingBuffer, Bt as AUDIO_PRESETS, Ct as rankStreams, E as RATE_CONTROL_TIGHT, Ft as streamBrokerCapability, Gt as BOOT_RECOVERY_BACKOFF_MS, Ht as buildFfmpegArgs$1, I as batteryCapability, J as egressTranscodeSharingKey, Jt as DeviceFeature, Kt as BaseAddon, L as cameraStreamsCapability, M as addonWidgetsSourceCapability, Ot as resolveEgressDecodeHwAccel, Qt as expandAudioChunkToF32le, R as createHwAccelCache, Rt as webrtcSessionCapability, T as RATE_CONTROL_RELAXED, Ut as invocationFromEncodeProfile, V as declareLogChannel, W as deriveBatteryPresence, Wt as isSoftwareDecode, Y as egressTransportFromRequest, Yt as DeviceType, Zt as createEvent, _n as record, an as parseProfileBrokerId, bn as EventCategory, cn as _enum, dn as discriminatedUnion, en as isEvent, h as EncodeProfileSchema, hn as object, i as BatteryStatusSchema, ln as array, lt as maskUrlCredentials, mn as number, nn as makeSourceBrokerId, ot as loadContributionCapability, pn as literal, qt as CAM_PROFILE_ORDER, rn as nodePin, st as logChannelsCapability, tn as makeProfileBrokerId, un as boolean, v as G711_SCALE_CORRECTION_DB, vn as string, yn as union, z as createLogChannelsProvider, zt as errMsg } from "../dist-DTPYOq7J.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-Cz92fVGW.mjs";
+import { c as PREBUFFER_MAX_MS, d as resolvePrebuffer, i as parseRestreamPath, l as capPreRollRequestMs, n as NO_DECLARATION, u as prebufferRetentionMs } from "../restream-intent-MeJhGCK9.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-BWZQJ1AS.mjs";
+import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-CyaNDtrw.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -17,6 +17,7 @@ import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { renderCourtesyJpeg, renderCourtesyOverlayJpeg } from "@camstack/system/addon-utils";
 import * as net$1 from "node:net";
 import net from "node:net";
 import { createSocket } from "node:dgram";
@@ -556,6 +557,240 @@ function rankDecodeHwAccels(preferred, supportedMethods) {
 	return candidates.sort((a, b) => decodeHwAccelRankIndex(a) - decodeHwAccelRankIndex(b));
 }
 //#endregion
+//#region src/stream-broker/stream-broker/egress-source-readiness.ts
+/**
+* Whether waiting on this source can achieve anything — the three-way answer
+* `waitForSourceMedia` consumes.
+*
+* The subtlety that cost a measured 15 s per cold Alexa open on 2026-09-13: a
+* lazy publisher materialises because someone DIALS it. The source broker's own
+* `redial` / `kickReconnect` both refuse without demand, by design — a broker
+* with no consumer must not wake a camera. So for a cold, idle source the
+* ffmpeg child IS the demand, and withholding it waits for media that only
+* starts because of the thing being withheld. The live log of that mistake:
+*
+*   19:04:27  waited for the SOURCE  {outcome=timeout waitedMs=15005 ready=false}
+*   19:04:30  the child died before the decoder — retrying in SOFTWARE
+*   19:04:32  rfc4571: publisher materialized {materializeMs=5798}
+*
+* Fifteen seconds of nothing, then the spawn, then the wake it had triggered.
+*
+* So: wait only when a materialize is ALREADY in flight — a second consumer
+* arriving while the first is waking the camera, which is the case the wait was
+* really for. A cold idle source answers `null`: not "no media", but "waiting
+* here cannot help", and the caller spawns at once.
+*/
+function sourceWaitState(input) {
+	if (input.hasMedia) return true;
+	if (input.materializing) return false;
+	return null;
+}
+async function waitForSourceMedia(input) {
+	const started = input.now();
+	const first = input.hasMedia();
+	if (first === null) return {
+		ready: false,
+		waitedMs: 0,
+		outcome: "unknown"
+	};
+	if (first) return {
+		ready: true,
+		waitedMs: 0,
+		outcome: "live"
+	};
+	for (;;) {
+		const elapsed = input.now() - started;
+		if (elapsed >= input.timeoutMs) return {
+			ready: false,
+			waitedMs: elapsed,
+			outcome: "timeout"
+		};
+		await input.sleep(input.pollMs);
+		const state = input.hasMedia();
+		const waitedMs = input.now() - started;
+		if (state === null) return {
+			ready: false,
+			waitedMs,
+			outcome: "unknown"
+		};
+		if (state) return {
+			ready: true,
+			waitedMs,
+			outcome: "materialized"
+		};
+	}
+}
+//#endregion
+//#region src/stream-broker/stream-broker/stream-health-scope.ts
+/**
+* WHICH streams a health transition is worth telling the operator about.
+*
+* `stream.online` / `stream.offline` are operator-facing: they reach the
+* notification rules and land on a phone. So they must be facts about a
+* CAMERA, and an egress stream is not one — it is the private pipe an exporter
+* asks the broker to build for one consumer session and drops when that session
+* ends. Its whole life is an implementation detail of somebody watching.
+*
+* Measured on this hub 2026-09-13: every Alexa session on the baby monitor
+* produced a `stream.online` and a `stream.offline` pair against
+* `640/egress:8e96e97a…`, and the operator read them as the battery camera
+* flapping during its wake. Nothing was flapping — that is just what an egress
+* pipe does, once per session, by design.
+*
+* The doctrine already existed one layer down: an egress is published with
+* `autoEligible: false` so "a private egress can never become a camera's
+* published stream". It simply had not reached the event path.
+*
+* A DERIVED stream is different and stays in scope: the operator configured it,
+* it is meant to persist, and its going offline is news.
+*/
+/** Private, per-session egress pipes. See {@link healthEventIsOperatorFacing}. */
+var PRIVATE_STREAM_PREFIXES = ["egress:"];
+function healthEventIsOperatorFacing(camStreamId) {
+	return !PRIVATE_STREAM_PREFIXES.some((prefix) => camStreamId.startsWith(prefix));
+}
+//#endregion
+//#region src/stream-broker/stream-broker/prestream-eligibility.ts
+function prestreamEligible(input) {
+	if (input.batteryOperated === null || input.declaresSignals === null) return {
+		eligible: false,
+		reason: "unknown"
+	};
+	if (!input.batteryOperated) return {
+		eligible: false,
+		reason: "not-battery"
+	};
+	if (!input.declaresSignals) return {
+		eligible: false,
+		reason: "no-signals-cap"
+	};
+	return { eligible: true };
+}
+//#endregion
+//#region src/stream-broker/stream-broker/prestream-signal-selection.ts
+function nextEnabledSignals(input) {
+	const base = input.stored ?? input.declared;
+	const set = new Set(base);
+	if (input.enabled) set.add(input.code);
+	else set.delete(input.code);
+	const known = input.declared.filter((c) => set.has(c));
+	const extra = [...set].filter((c) => !input.declared.includes(c));
+	return [...known, ...extra];
+}
+//#endregion
+//#region src/stream-broker/stream-broker/wake-hold.ts
+/**
+* The HOLD a camera's own signal buys, and what it may not buy.
+*
+* A stream a consumer merely watches is not a reason to wake a battery camera —
+* a Frigate-style puller holds a session open for ever, and treating that as
+* demand keeps the camera awake for ever, which is the whole point of the
+* battery (D173). So a prestream consumer is FED without being INTENT, and the
+* only thing that dials is a signal the camera reported about itself.
+*
+* This module is the timing half of that, and it is pure so the arithmetic can
+* be argued with. Three rules:
+*
+*  - **A hold EXTENDS, it never stacks.** Continuous motion keeps a camera up
+*    and it sleeps `holdMs` after the LAST signal, not after the sum of them.
+*    A counter or a queue would turn a busy afternoon into an hour of wake.
+*  - **A run is bounded ABSOLUTELY, from its first signal.** A stuck PIR
+*    reporting every second would otherwise extend the hold indefinitely and
+*    drain the battery — the one failure this whole design exists to prevent.
+*    The same re-arm-under-a-ceiling shape D371 gives `recording-signal`.
+*  - **A deadline, not a chain of timers.** The state is one number; the timer
+*    only decides when to LOOK at it. A chain would drift and would have to be
+*    cancelled correctly on every path.
+*/
+/** How long a camera stays awake after the LAST signal. The operator's, per
+*  camera; this is the default the broker ships. */
+var DEFAULT_WAKE_HOLD_MS = 15e3;
+/**
+* Ceiling on ONE run, measured from its first signal.
+*
+* Five minutes. Long enough that a genuine sustained event — a person moving
+* around a garden — is covered end to end; short enough that a sensor stuck
+* ON costs one five-minute wake rather than a night.
+*/
+var WAKE_HOLD_MAX_RUN_MS = 5 * 6e4;
+/**
+* How long a camera is left alone after a run hit the ceiling.
+*
+* Without this the ceiling is cosmetic, and the test that found it says why: a
+* run ends exactly AT the ceiling, so the very next signal from a sensor that
+* never stops re-arms a fresh five minutes. Five minutes awake, an instant
+* asleep, five minutes awake — all night, which is the precise failure the
+* ceiling was written to prevent.
+*
+* So a capped run buys silence. Ten minutes: long enough that a stuck sensor
+* costs a third of its time rather than all of it, short enough that a genuine
+* long event — someone working in the garden — resumes within a few minutes
+* instead of being locked out for an hour.
+*
+* Signals during the quarantine are REFUSED and counted, not queued: a queue
+* would fire them all the moment it lifts, which is the same drain arriving
+* late.
+*/
+var WAKE_QUARANTINE_AFTER_CAP_MS = 10 * 6e4;
+var NO_HOLD = {
+	runStartedAt: 0,
+	until: 0,
+	signals: 0,
+	quarantinedUntil: 0
+};
+/**
+* Absorb one signal.
+*
+* A signal arriving with the run already at its ceiling does NOT extend it —
+* and does not start a new one either, because a new run measured from now
+* would be the same unbounded extension wearing a different name. It is
+* reported as `capped` so the operator can see a sensor that will not stop.
+*/
+function absorbSignal(input) {
+	const { current, now, holdMs } = input;
+	if (!(current.until > now && current.runStartedAt > 0)) {
+		if (current.quarantinedUntil > now) return {
+			hold: {
+				...current,
+				signals: current.signals + 1
+			},
+			outcome: "quarantined"
+		};
+		return {
+			hold: {
+				runStartedAt: now,
+				until: now + holdMs,
+				signals: 1,
+				quarantinedUntil: 0
+			},
+			outcome: "armed"
+		};
+	}
+	if (now - current.runStartedAt >= 3e5) return {
+		hold: {
+			...current,
+			signals: current.signals + 1,
+			quarantinedUntil: now + WAKE_QUARANTINE_AFTER_CAP_MS
+		},
+		outcome: "capped"
+	};
+	const ceiling = current.runStartedAt + WAKE_HOLD_MAX_RUN_MS;
+	const until = Math.min(now + holdMs, ceiling);
+	return {
+		hold: {
+			...current,
+			until,
+			signals: current.signals + 1,
+			...until === ceiling ? { quarantinedUntil: ceiling + WAKE_QUARANTINE_AFTER_CAP_MS } : {}
+		},
+		outcome: "extended"
+	};
+}
+/** Whether the hold still keeps the camera awake at `now`. */
+function holdIsLive(hold, now) {
+	return hold.until > now;
+}
+//#endregion
 //#region src/stream-broker/battery-wake-on-play.ts
 /**
 * Wake-on-play — pressing play on a sleeping battery camera wakes it, and the
@@ -1244,7 +1479,7 @@ var ADTS_SAMPLE_RATES = [
 /** AAC-LC AudioObjectType for the 2-byte AudioSpecificConfig. */
 var AAC_LC_OBJECT_TYPE = 2;
 /** Grace before escalating SIGTERM → SIGKILL on a lingering child. */
-var KILL_GRACE_MS = 500;
+var KILL_GRACE_MS$1 = 500;
 /**
 * Parse the 7-byte ADTS header of an AAC frame into the audio-init params the
 * broker's push ingress needs. Returns `null` when the buffer is too short or
@@ -1438,7 +1673,7 @@ var FfmpegPushReader = class {
 			if (pid !== void 0 && child.exitCode === null && child.signalCode === null) try {
 				child.kill("SIGKILL");
 			} catch {}
-		}, KILL_GRACE_MS).unref?.();
+		}, KILL_GRACE_MS$1).unref?.();
 	}
 };
 //#endregion
@@ -2890,6 +3125,26 @@ var RtspRestreamer = class {
 	getSessionCount() {
 		return this.sessions.size;
 	}
+	/**
+	* Sessions that count as LIVE INTENT — everything except a prestream dial.
+	*
+	* The split exists so a Frigate-style puller can hold a session open for ever
+	* against a battery camera without keeping it awake (D173). For a broker with
+	* no prestream session this equals {@link getSessionCount} exactly, which is
+	* why nothing else changed behaviour.
+	*/
+	getLiveIntentSessionCount() {
+		let n = 0;
+		for (const session of this.sessions.values()) if (!session.isPrestreamIntent()) n += 1;
+		return n;
+	}
+	/** Sessions asking only for the picture. Drives the prestream pump, nothing
+	*  else — it must never reach a dial decision. */
+	getPrestreamSessionCount() {
+		let n = 0;
+		for (const session of this.sessions.values()) if (session.isPrestreamIntent()) n += 1;
+		return n;
+	}
 	/** Per-session diagnostic snapshots consumed by `StreamBroker.listClients`. */
 	listSessionInfos() {
 		return [...this.sessions.values()].map((s) => s.getInfo());
@@ -3642,6 +3897,16 @@ var RtspSession = class {
 		return this.declaration.intent === "detection";
 	}
 	/**
+	* Whether this dial asked for the STREAM without asking for the CAMERA.
+	*
+	* The one question the demand split turns on: a prestream session is FED but
+	* is not INTENT, so it never dials a sleeping camera. See
+	* `PRESTREAM_PATH_SUFFIX`.
+	*/
+	isPrestreamIntent() {
+		return this.declaration.intent === "prestream";
+	}
+	/**
 	* Ms of retained history this session ASKED for on its dial. `0` = none.
 	*
 	* Read by `RtspRestreamer.servePendingSessionsRtp`, which serves the smaller
@@ -5009,41 +5274,19 @@ function isDecodeBackendFailure(error) {
 	return true;
 }
 //#endregion
-//#region src/stream-broker/stream-broker/egress-source-readiness.ts
-async function waitForSourceMedia(input) {
-	const started = input.now();
-	const first = input.hasMedia();
-	if (first === null) return {
-		ready: false,
-		waitedMs: 0,
-		outcome: "unknown"
-	};
-	if (first) return {
-		ready: true,
-		waitedMs: 0,
-		outcome: "live"
+//#region src/stream-broker/stream-broker/egress-geometry.ts
+function capAxis(requested, source) {
+	if (requested === void 0) return void 0;
+	if (source === void 0 || source <= 0) return requested;
+	return Math.min(requested, source);
+}
+function deliveredGeometry(input) {
+	const width = capAxis(input.requestedWidth, input.sourceWidth);
+	const height = capAxis(input.requestedHeight, input.sourceHeight);
+	return {
+		...width === void 0 ? {} : { width },
+		...height === void 0 ? {} : { height }
 	};
-	for (;;) {
-		const elapsed = input.now() - started;
-		if (elapsed >= input.timeoutMs) return {
-			ready: false,
-			waitedMs: elapsed,
-			outcome: "timeout"
-		};
-		await input.sleep(input.pollMs);
-		const state = input.hasMedia();
-		const waitedMs = input.now() - started;
-		if (state === null) return {
-			ready: false,
-			waitedMs,
-			outcome: "unknown"
-		};
-		if (state) return {
-			ready: true,
-			waitedMs,
-			outcome: "materialized"
-		};
-	}
 }
 //#endregion
 //#region src/stream-broker/stream-broker/rtsp-host.ts
@@ -5429,6 +5672,17 @@ var SOURCE_MEDIA_WAIT_MS = 15e3;
 /** Poll cadence for that wait. Flat, for the reason a materialize poll is. */
 var SOURCE_MEDIA_POLL_MS = 250;
 /**
+* How long to wait before re-dialling a source whose input was not there.
+*
+* The first spawn is what WAKES a lazy publisher, and the measured wake on this
+* hub lands between 2.2 s and 7.8 s (`materializeMs`). Three seconds is inside
+* that band: long enough that a quick wake is already serving, short enough
+* that the second attempt still beats the consumer's own patience.
+*/
+var INPUT_RETRY_DELAY_MS = 3e3;
+/** After the first three, log one keyframe in this many. */
+var KEYFRAME_LOG_EVERY = 25;
+/**
 * How long a push child may produce nothing before it is declared dead. The
 * observed failure EXITS in ~2 s and is caught by the error path long before
 * this; the timeout only covers a child that hangs.
@@ -5594,12 +5848,18 @@ var EgressTranscodeManager = class {
 		const decodeHwAccel = await this.opts.resolveDecodeHwAccel(deviceId, request.decodeHwAccel);
 		const fragments = delivery.transport === "fragments";
 		const publishedCamStreamId = `egress:${key.replace(/^egress:/, "")}`;
+		const delivered = deliveredGeometry({
+			requestedWidth: request.encode.video.width,
+			requestedHeight: request.encode.video.height,
+			sourceWidth: source.facts.width,
+			sourceHeight: source.facts.height
+		});
 		const pushSink = fragments || request.publishLocally !== true || this.opts.publishPushStream === void 0 ? null : await this.opts.publishPushStream({
 			deviceId,
 			camStreamId: publishedCamStreamId,
 			codec: request.encode.video.codec,
-			width: request.encode.video.width ?? 0,
-			height: request.encode.video.height ?? 0
+			width: delivered.width ?? 0,
+			height: delivered.height ?? 0
 		});
 		if (request.publishLocally === true && pushSink === null && !fragments) this.opts.logger.warn("egress transcode: local publication REFUSED — the consumer must dial the url", {
 			tags: { deviceId },
@@ -5613,7 +5873,10 @@ var EgressTranscodeManager = class {
 		const fragmentSeconds = fragments ? (delivery.fragmentMs ?? 0) / 1e3 : void 0;
 		const { sink: _sink, audioSidecar: _audioSidecar, ...plan } = invocationFromEncodeProfile({
 			profile: {
-				video: request.encode.video,
+				video: {
+					...request.encode.video,
+					...delivered
+				},
 				audio: audio.profileAudio
 			},
 			sourceCodec: source.codec,
@@ -6045,6 +6308,18 @@ var EgressTranscodeManager = class {
 										dts: packet.dts
 									}
 								});
+							} else if (packet.keyframe === true) {
+								keyframesOut += 1;
+								if (keyframesOut <= 3 || keyframesOut % KEYFRAME_LOG_EVERY === 0) logger.info("egress push: keyframe out", {
+									tags: { deviceId },
+									meta: {
+										brokerId: spec.brokerId,
+										camStreamId: spec.publishedCamStreamId,
+										keyframesOut,
+										bytes: packet.data.length,
+										approxRtpPackets: Math.ceil(packet.data.length / 1200)
+									}
+								});
 							} else if (packetsOut % PUSH_PACKET_LOG_EVERY === 0) logger.info("egress push: packets still flowing out of the ffmpeg child", {
 								tags: { deviceId },
 								meta: {
@@ -6102,30 +6377,66 @@ var EgressTranscodeManager = class {
 				reader.connect();
 			});
 		};
+		let keyframesOut = 0;
 		let hwAccelAtFault = true;
 		return {
 			hwAccelAtFault: () => hwAccelAtFault,
 			start: async () => {
 				const requested = spec.invocation.decodeHwAccel;
+				/** Whether a same-decode retry already produced a live child. */
+				let recoveredOnRetry = false;
+				const inputRetryDelayMs = this.opts.inputRetryDelayMs ?? INPUT_RETRY_DELAY_MS;
 				try {
 					await spawnAttempt(requested);
 				} catch (err) {
 					if (requested === null || isSoftwareDecode(requested)) throw err;
 					const blameBackend = isDecodeBackendFailure(errMsg(err));
 					hwAccelAtFault = blameBackend;
-					logger.warn(blameBackend ? "egress push: hardware decode produced NO packets — retrying in SOFTWARE" : "egress push: the child died before the decoder — retrying in SOFTWARE, backend NOT blamed", {
-						tags: { deviceId },
-						meta: {
-							brokerId: spec.brokerId,
-							camStreamId: spec.publishedCamStreamId,
-							decodeHwAccel: requested,
-							blameBackend,
-							error: errMsg(err)
+					if (!blameBackend) {
+						logger.info("egress push: the input was not there — retrying the SAME decode", {
+							tags: { deviceId },
+							meta: {
+								brokerId: spec.brokerId,
+								camStreamId: spec.publishedCamStreamId,
+								decodeHwAccel: requested,
+								afterMs: inputRetryDelayMs,
+								error: errMsg(err)
+							}
+						});
+						reader?.destroy();
+						await new Promise((resolve) => {
+							setTimeout(resolve, inputRetryDelayMs).unref?.();
+						});
+						try {
+							await spawnAttempt(requested);
+							recoveredOnRetry = true;
+						} catch (retryErr) {
+							logger.warn("egress push: the input was STILL not there — falling to SOFTWARE", {
+								tags: { deviceId },
+								meta: {
+									brokerId: spec.brokerId,
+									camStreamId: spec.publishedCamStreamId,
+									decodeHwAccel: requested,
+									error: errMsg(retryErr)
+								}
+							});
 						}
-					});
-					reader?.destroy();
-					activeHwAccel = null;
-					await spawnAttempt(null);
+					}
+					if (!recoveredOnRetry) {
+						logger.warn(blameBackend ? "egress push: hardware decode produced NO packets — retrying in SOFTWARE" : "egress push: the child died before the decoder — retrying in SOFTWARE, backend NOT blamed", {
+							tags: { deviceId },
+							meta: {
+								brokerId: spec.brokerId,
+								camStreamId: spec.publishedCamStreamId,
+								decodeHwAccel: requested,
+								blameBackend,
+								error: errMsg(err)
+							}
+						});
+						reader?.destroy();
+						activeHwAccel = null;
+						await spawnAttempt(null);
+					}
 				}
 				logger.info("egress transcode: publishing LOCALLY — no rtsp round trip", {
 					tags: { deviceId },
@@ -6875,13 +7186,13 @@ var EVENT_CLIP_MAX_HEIGHT = 1080;
 * `pickClipProfile` and the answer reports which was used.
 */
 function pickBestClipProfile(candidates) {
-	const usable = candidates.filter((c) => normaliseCodec$1(c.codec) === "h264" && (c.height ?? 0) > 0 && (c.width ?? 0) > 0);
+	const usable = candidates.filter((c) => normaliseCodec$2(c.codec) === "h264" && (c.height ?? 0) > 0 && (c.width ?? 0) > 0);
 	if (usable.length === 0) return null;
 	const within = usable.filter((c) => (c.height ?? 0) <= EVENT_CLIP_MAX_HEIGHT);
 	return [...within.length > 0 ? within : usable].sort((a, b) => within.length > 0 ? (b.height ?? 0) - (a.height ?? 0) : (a.height ?? 0) - (b.height ?? 0))[0]?.profile ?? null;
 }
 /** Publishers spell H.265 four ways; the same normalisation the broker uses. */
-function normaliseCodec$1(codec) {
+function normaliseCodec$2(codec) {
 	return (codec ?? "").toLowerCase().replace(/[.\s-]/g, "");
 }
 /**
@@ -7327,6 +7638,249 @@ function runGif(input, args) {
 	});
 }
 //#endregion
+//#region src/stream-broker/stream-broker/prestream-encode.ts
+/**
+* ONE short-lived ffmpeg turns the prestream's picture into ONE Annex-B IDR.
+*
+* ── Why one encode and not a continuous child ─────────────────────────────
+* The obvious shape is `-loop 1 -framerate 1` and let ffmpeg emit the picture
+* for as long as the camera is waking. That is a resident child per sleeping
+* camera, for the whole wake, to redraw a picture that changes at most hourly.
+* So the child encodes exactly ONE frame (`-frames:v 1`) and exits, the caller
+* caches the bytes, and {@link PrestreamPump} re-emits them. A new encode
+* happens only when the picture changes.
+*
+* ── Why every frame carries its own parameter sets ────────────────────────
+* The pump re-emits ONE access unit at 1 fps, so a consumer that attaches on
+* tick 4 sees its first packet with nothing before it. `-g 1` plus
+* `repeat-headers=1` makes that packet a complete IDR with SPS/PPS (or
+* VPS/SPS/PPS) inline, so it decodes within a second of attaching instead of
+* waiting for a keyframe that will never come.
+*
+* ── Why the geometry comes from the plan and nowhere else ─────────────────
+* `planPrestream` refuses a camera whose geometry nobody has probed, precisely
+* so this file never has a default to fall back on. `stream-broker.ts` records
+* what a wrong one does: a fixed 1280x720 placeholder SPS in front of a
+* camera's real IDR froze Chrome's decoder on the last synthetic frame until
+* the viewer was recreated by hand. Hence `scale` mode `exact`, the plan's
+* numbers, and the plan's codec.
+*
+* ── Why no text is drawn here ─────────────────────────────────────────────
+* D118: the hub carries two ffmpeg builds and only one has libfreetype, so
+* `drawtext` is forbidden. The picture arrives already composed — sharp + an
+* inline SVG, the house pattern from `snapshot-courtesy.ts`.
+*/
+/**
+* Bound on the encode. A single 4 MP still on `ultrafast` is milliseconds; a
+* child that has not answered in this long is hung, and the prestream would
+* otherwise hold a promise open for the rest of the process's life.
+*/
+var PRESTREAM_ENCODE_TIMEOUT_MS = 1e4;
+/** Grace before escalating SIGTERM → SIGKILL on a child that will not go. */
+var KILL_GRACE_MS = 500;
+/** x264/x265 params shared by both codecs: one-frame GOP, headers on it. */
+var STILL_ENCODER_PARAMS = "keyint=1:repeat-headers=1";
+/**
+* The argv. PURE, so the two properties that matter — the geometry is the
+* plan's, and the frame is a self-contained IDR — are assertable without a
+* binary.
+*/
+function buildPrestreamEncodeArgs(plan) {
+	const h265 = plan.codec === "h265";
+	return buildFfmpegArgs$1({
+		logLevel: "error",
+		decodeHwAccel: null,
+		input: {
+			url: "pipe:0",
+			extraArgs: [
+				"-f",
+				"image2pipe",
+				"-framerate",
+				"1"
+			]
+		},
+		video: {
+			kind: "encode",
+			encoder: h265 ? "libx265" : "libx264",
+			scale: {
+				mode: "exact",
+				width: plan.width,
+				height: plan.height
+			},
+			preset: "ultrafast",
+			...h265 ? {} : { tune: "stillimage" },
+			pixelFormat: "yuv420p",
+			fps: 1,
+			gopFrames: 1,
+			bf: 0
+		},
+		audio: { kind: "none" },
+		threadCount: 1,
+		outputArgs: [
+			"-frames:v",
+			"1",
+			h265 ? "-x265-params" : "-x264-params",
+			STILL_ENCODER_PARAMS
+		],
+		sink: {
+			kind: "stdout",
+			container: h265 ? "hevc" : "h264"
+		}
+	});
+}
+/**
+* Run the encode. Resolves with the Annex-B bytes, rejects with a named reason
+* — the caller turns a rejection into a refusal log and no prestream, which is
+* the same outcome as a black screen and never worse than one.
+*/
+function encodePrestreamIdr(options) {
+	const args = buildPrestreamEncodeArgs(options.plan);
+	const spawnFn = options.spawnFn ?? spawn;
+	const tags = options.deviceId === void 0 ? {} : { tags: { deviceId: options.deviceId } };
+	return new Promise((resolve, reject) => {
+		let child;
+		try {
+			child = spawnFn(options.ffmpegPath, args);
+		} catch (err) {
+			reject(/* @__PURE__ */ new Error(`prestream encode could not spawn ffmpeg: ${errMsg(err)}`));
+			return;
+		}
+		const chunks = [];
+		let stderrTail = "";
+		let settled = false;
+		const finish = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if ("error" in outcome) reject(outcome.error);
+			else resolve(outcome.bytes);
+		};
+		const timer = setTimeout(() => {
+			killChild(child);
+			finish({ error: /* @__PURE__ */ new Error(`prestream encode timed out after ${String(PRESTREAM_ENCODE_TIMEOUT_MS)} ms`) });
+		}, PRESTREAM_ENCODE_TIMEOUT_MS);
+		timer.unref?.();
+		child.stdout?.on("data", (chunk) => chunks.push(chunk));
+		child.stderr?.on("data", (chunk) => {
+			stderrTail = `${stderrTail}${chunk.toString("utf8")}`.slice(-2048);
+		});
+		child.stdin?.on("error", () => {});
+		child.on("error", (err) => {
+			finish({ error: /* @__PURE__ */ new Error(`prestream encode failed: ${err.message}`) });
+		});
+		child.on("exit", (code, signal) => {
+			if (code !== 0) {
+				finish({ error: /* @__PURE__ */ new Error(`prestream encode exited ${String(code ?? signal)}: ${stderrTail.trim() || "no stderr"}`) });
+				return;
+			}
+			const bytes = Buffer.concat(chunks);
+			if (bytes.length === 0) {
+				finish({ error: /* @__PURE__ */ new Error("prestream encode produced no bytes") });
+				return;
+			}
+			options.logger?.debug("prestream: picture encoded", {
+				...tags,
+				meta: {
+					codec: options.plan.codec,
+					width: options.plan.width,
+					height: options.plan.height,
+					bytes: bytes.length
+				}
+			});
+			finish({ bytes });
+		});
+		child.stdin?.end(options.jpeg);
+	});
+}
+function killChild(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	child.kill("SIGTERM");
+	setTimeout(() => {
+		if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+	}, KILL_GRACE_MS).unref?.();
+}
+//#endregion
+//#region src/stream-broker/stream-broker/prestream-picture.ts
+/**
+* The PICTURE the prestream shows: the camera's own last frame under a "Waking"
+* treatment, or — when there is none — a generated card carrying its name.
+*
+* ── Why a fallback exists at all ──────────────────────────────────────────
+* The snapshot cache is RAM-only. After a hub restart a sleeping battery camera
+* has no cached frame, and `getSnapshot` without `force` will not wake it to
+* make one (`force` is an OPERATOR signal — a background caller that sets it
+* wakes the camera it was trying not to disturb). So on exactly the cameras
+* this feature is for, "no picture" is a normal state, not an error. A card
+* saying WAKING with the camera's name is worse than the real frame and much
+* better than black — and it is what makes the broker servable inside Amazon's
+* six-second SDP deadline on a cold hub.
+*
+* ── Why the source is reported ────────────────────────────────────────────
+* The two look identical to a consumer and are very different to an operator:
+* one means the cache is warm, the other means it is cold. The caller logs
+* which was used, per camera.
+*
+* Pure input → bytes. No snapshot fetch, no device lookup, no I/O of its own —
+* the caller does both and hands the results in.
+*/
+/**
+* Compose the picture.
+*
+* An overlay that cannot be rendered (a truncated or non-decodable cached
+* frame) falls through to the generated card rather than leaking an unlabelled
+* stale frame — the same call the snapshot wrapper's `stateImage` makes, for
+* the same reason.
+*/
+async function composePrestreamPicture(input) {
+	const tags = input.deviceId === void 0 ? {} : { tags: { deviceId: input.deviceId } };
+	if (input.cachedJpeg !== null && input.cachedJpeg.length > 0) try {
+		return {
+			jpeg: await renderCourtesyOverlayJpeg(input.cachedJpeg, {
+				deviceName: input.deviceName,
+				reason: "waking"
+			}),
+			source: "cached-snapshot"
+		};
+	} catch (err) {
+		input.logger?.warn("prestream: cached frame could not be treated — using the card", {
+			...tags,
+			meta: { error: errMsg(err) }
+		});
+	}
+	return {
+		jpeg: await renderCourtesyJpeg({
+			deviceName: input.deviceName,
+			reason: "waking",
+			width: input.width,
+			height: input.height
+		}),
+		source: "generated-card"
+	};
+}
+function planPrestream(input) {
+	if (input.sourceUrl === void 0 || !input.sourceUrl.startsWith("lazy:rfc4571:")) return { refusal: "not-lazy" };
+	if (input.width === void 0 || input.height === void 0 || input.width <= 0 || input.height <= 0) return { refusal: "unknown-geometry" };
+	const codec = normaliseCodec$1(input.codec);
+	if (codec === null) return { refusal: "unknown-codec" };
+	return { plan: {
+		width: input.width,
+		height: input.height,
+		codec
+	} };
+}
+/**
+* `null` for a codec nobody has read. NOT a default of h264: a prestream in the
+* wrong codec is a stream the consumer cannot decode at all, which is worse
+* than the black screen it replaces.
+*/
+function normaliseCodec$1(codec) {
+	if (codec === void 0) return null;
+	const c = codec.toLowerCase().replace(/[.\s-]/g, "");
+	if (c === "h264" || c === "avc" || c === "avc1") return "h264";
+	if (c === "h265" || c === "hevc" || c === "hvc1" || c === "hev1") return "h265";
+	return null;
+}
+//#endregion
 //#region src/stream-broker/stream-broker/profile-restreamers.ts
 /**
 * Diff the desired profile→source aliasing against the current
@@ -11460,6 +12014,124 @@ function getPlaceholderFrame(kind, codec) {
 	return buf;
 }
 //#endregion
+//#region src/stream-broker/stream-broker/prestream-pump.ts
+/**
+* The prestream pump: ONE encode, then a 1 fps re-emit until real media lands.
+*
+* ── What it is for ────────────────────────────────────────────────────────
+* A lazy source is BUILT on demand, and on this hub that build costs 2.2 to
+* 12.4 s. For all of it the consumer had black — and Amazon allows SIX SECONDS
+* for an Alexa SDP answer, so a cold battery camera could not answer an Echo at
+* all. The pump makes the broker servable before the camera is: the camera's
+* own last picture under a "Waking" treatment, at the camera's real geometry,
+* replaced by real media the instant the first real packet arrives.
+*
+* ── The three rules it exists to hold ─────────────────────────────────────
+*  1. **Prepare ONCE.** The picture is fetched and encoded a single time per
+*     wake and the bytes are cached here. Re-fetching per tick would put a
+*     snapshot round-trip and a fork+exec on every second of every waking
+*     camera, and would move frames across a process boundary at frame-rate —
+*     D9/D18.
+*  2. **A late preparation lands nowhere.** The encode is async. If the camera
+*     woke while it was running the pump has already been stopped, and starting
+*     the timer then would paint a still picture over live media.
+*  3. **It never dials.** The pump has no source, no socket and no demand. It
+*     is started alongside the publisher request, never instead of it.
+*
+* Emission is the caller's: {@link PrestreamPumpOptions.emit} is where the
+* `isPlaceholder: true` packet is built, because that flag belongs to the
+* broker's packet contract and the containment that reads it lives there.
+*/
+var DEFAULT_PRESTREAM_INTERVAL_MS = 1e3;
+var PrestreamPump = class {
+	options;
+	intervalMs;
+	tags;
+	timer;
+	/** True from `start()` until `stop()`, INCLUDING while the encode runs. */
+	active = false;
+	frame = null;
+	startedAt = 0;
+	emitted = 0;
+	constructor(options) {
+		this.options = options;
+		this.intervalMs = options.intervalMs ?? DEFAULT_PRESTREAM_INTERVAL_MS;
+		this.tags = options.deviceId === void 0 ? {} : { tags: { deviceId: options.deviceId } };
+	}
+	/** Whether the window is currently being filled (or about to be). */
+	get running() {
+		return this.active;
+	}
+	/**
+	* Open the window. Idempotent: a second call while the first preparation is
+	* still in flight is a no-op, so a reconnect tick that re-enters the lazy
+	* branch every second does not spawn an encode every second.
+	*/
+	start(sourceUrl) {
+		if (this.active) return;
+		this.active = true;
+		this.startedAt = Date.now();
+		this.emitted = 0;
+		this.options.prepare({ sourceUrl }).then((frame) => {
+			if (!this.active) {
+				this.options.logger?.debug("prestream: preparation landed after the window closed", { ...this.tags });
+				return;
+			}
+			if (frame === null) {
+				this.options.logger?.info("prestream: refused — the window goes unfilled", { ...this.tags });
+				this.active = false;
+				return;
+			}
+			this.frame = frame;
+			this.options.logger?.info("prestream: filling the wake window", {
+				...this.tags,
+				meta: {
+					codec: frame.codec,
+					bytes: frame.annexB.length,
+					intervalMs: this.intervalMs,
+					preparedInMs: Date.now() - this.startedAt
+				}
+			});
+			this.tick();
+			this.timer = setInterval(() => this.tick(), this.intervalMs);
+		}).catch((err) => {
+			this.options.logger?.warn("prestream: preparation failed — the window goes unfilled", {
+				...this.tags,
+				meta: { error: errMsg(err) }
+			});
+			this.active = false;
+		});
+	}
+	/**
+	* Close the window. Called on the first NON-placeholder packet — the one edge
+	* the prestream is defined by — and on the broker's own teardown paths so a
+	* stopped broker leaves no timer behind.
+	*/
+	stop(reason) {
+		if (!this.active) return;
+		this.active = false;
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = void 0;
+		}
+		this.options.logger?.info("prestream: window closed", {
+			...this.tags,
+			meta: {
+				reason,
+				framesEmitted: this.emitted,
+				heldMs: Date.now() - this.startedAt
+			}
+		});
+		this.frame = null;
+	}
+	tick() {
+		const frame = this.frame;
+		if (!this.active || frame === null) return;
+		this.emitted++;
+		this.options.emit(frame);
+	}
+};
+//#endregion
 //#region src/stream-broker/stream-broker/stream-pipe-server.ts
 /**
 * A lightweight TCP server that broadcasts raw encoded video bytes
@@ -11752,6 +12424,23 @@ var StreamBroker = class StreamBroker {
 	audioMutedDropLogged = false;
 	reconnectTimer;
 	placeholderTimer;
+	/**
+	* The prestream pump, armed by the manager via `setPrestreamProvider`.
+	* `undefined` on a broker whose manager supplied none — the pre-prestream
+	* behaviour, unchanged.
+	*/
+	prestreamPump;
+	/**
+	* Latched once real media has been seen on this session.
+	*
+	* The lazy branch is re-entered on every materialize poll tick, so stopping
+	* the pump is not enough on its own: the very next tick would re-open a
+	* window that real bytes have already closed, and the consumer would get a
+	* still picture painted over live video every second. Reset exactly where
+	* `firstKeyframeReceived` is — broker stop and suspend — so a battery camera
+	* that goes back to sleep gets its prestream again on the next wake.
+	*/
+	prestreamWindowClosed = false;
 	reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
 	/**
 	* Dial rate-limiter (2026-07-23 storm fix): the earliest wall-clock at
@@ -11846,6 +12535,15 @@ var StreamBroker = class StreamBroker {
 	*/
 	materializeRequestedAt = 0;
 	/**
+	* The hold a camera's own signal bought. See `wake-hold.ts` — a term of
+	* {@link hasLiveIntent}, so the predicate's owner owns the state: putting it
+	* in the manager would give two places a vote on whether to dial.
+	*/
+	wakeHold = NO_HOLD;
+	/** Fires when the hold lapses, so the suspend happens instead of waiting for
+	*  an unrelated edge. Re-armed on every extension. */
+	wakeHoldTimer;
+	/**
 	* Rolling source-RTP activity watchdog. Distinct from the first-video
 	* watchdog: this one ARMS at DIAL time (so a connection that opens the
 	* loopback TCP but never delivers media is still detected) and RESETS on
@@ -12145,6 +12843,18 @@ var StreamBroker = class StreamBroker {
 	getLastPacketAt() {
 		return this.lastPacketAt;
 	}
+	/**
+	* Whether a LAZY publisher is being built right now.
+	*
+	* A consumer deciding whether it is worth waiting for this source needs to
+	* tell "cold and idle" from "waking up": the first cannot be waited for at
+	* all (the dial is the demand that starts the wake), the second can.
+	* `getFirstVideoWatchdogStatus` carries the same number and is a TEST SEAM —
+	* this is the production read.
+	*/
+	isMaterializing() {
+		return this.materializeRequestedAt > 0;
+	}
 	/** Source type of the active stream (rtsp/push/rtmp/placeholder/error). */
 	getActiveSourceType() {
 		return this.source?.type ?? "unknown";
@@ -12233,6 +12943,38 @@ var StreamBroker = class StreamBroker {
 		this.requestSourceRefresh = notify;
 	}
 	/**
+	* Arm the PRESTREAM — the fill for the window between "someone asked for this
+	* camera" and "the camera is awake".
+	*
+	* Manager-owned, because everything the fill needs is the manager's: the
+	* camera's probed geometry and codec (`planPrestream`), its last cached
+	* snapshot, its name, and the ffmpeg binary. The broker contributes the one
+	* thing it owns — WHEN the window is open — and nothing else.
+	*
+	* A broker with no provider behaves exactly as it did before the prestream
+	* existed: the lazy branch asks the publisher to materialize and the consumer
+	* sees black, which is the outcome every refusal falls back to.
+	*/
+	setPrestreamProvider(provider) {
+		this.prestreamPump = new PrestreamPump({
+			prepare: provider.prepare,
+			emit: (frame) => {
+				const now = Date.now();
+				this.pushEncodedPacket({
+					type: "video",
+					data: frame.annexB,
+					pts: now,
+					dts: now,
+					keyframe: true,
+					codec: frame.codec,
+					isPlaceholder: true
+				});
+			},
+			...this.logger ? { logger: this.logger } : {},
+			...this.numericDeviceId === void 0 ? {} : { deviceId: this.numericDeviceId }
+		});
+	}
+	/**
 	* Fire `requestSourceRefresh` at most once per ~500 ms. The
 	* dial-failure path fans into onError + reader.connect().catch; we
 	* only want one round-trip to the publisher per real failure.
@@ -12282,7 +13024,7 @@ var StreamBroker = class StreamBroker {
 	*/
 	redial(reason) {
 		if (this.manualStop || this.stopping || !this.source) return;
-		if (!this.hasDemand()) return;
+		if (!this.hasLiveIntent()) return;
 		this.logger?.info("source redial — the camera changed under a live reader", { meta: {
 			reason,
 			status: this._status
@@ -12298,7 +13040,7 @@ var StreamBroker = class StreamBroker {
 	}
 	kickReconnect() {
 		if (this.manualStop || this.stopping || !this.source) return;
-		if (!this.hasDemand()) return;
+		if (!this.hasLiveIntent()) return;
 		if (!this.reconnectTimer) return;
 		const nowMs = Date.now();
 		if (nowMs - this.lastKickAt < INITIAL_RECONNECT_DELAY_MS) return;
@@ -12340,7 +13082,7 @@ var StreamBroker = class StreamBroker {
 		} });
 		await this.pipeServer.start();
 		this.logger?.debug("Pipe server started", { meta: { url: this.pipeServer.getUrl() } });
-		if (isLazyDialSource(source.type) && !this.hasDemand()) {
+		if (isLazyDialSource(source.type) && !this.hasLiveIntent()) {
 			this._suspended = true;
 			this._status = "idle";
 			this.logger?.info("Broker registered idle — no demand, source dial deferred");
@@ -12398,6 +13140,8 @@ var StreamBroker = class StreamBroker {
 			clearInterval(this.placeholderTimer);
 			this.placeholderTimer = void 0;
 		}
+		this.prestreamPump?.stop("broker stopped");
+		this.prestreamWindowClosed = false;
 		if (this.reconnectTimer) {
 			clearTimeout(this.reconnectTimer);
 			this.reconnectTimer = void 0;
@@ -12559,14 +13303,98 @@ var StreamBroker = class StreamBroker {
 		this.checkDemand();
 	}
 	/** True when at least one consumer needs the stream alive. */
-	hasDemand() {
+	/**
+	* A signal the CAMERA reported about itself.
+	*
+	* Two terms must hold before anything is dialled, and they are the whole
+	* safety of this feature:
+	*
+	*  - the caller has already checked the signal is ENABLED for this camera
+	*    (the broker manager owns that setting), and
+	*  - somebody is actually waiting on the prestream. Waking a camera nobody is
+	*    watching is the one thing a battery camera must never do, and a signal
+	*    arriving with no consumer is exactly that.
+	*
+	* Returns what it did, so the caller's log line can say it. A hold that is
+	* merely EXTENDED does not re-dial: the camera is already up.
+	*/
+	reportWakeSignal(code, holdMs, at) {
+		if (this.rtspRestreamer.getPrestreamSessionCount() === 0) return "no-consumer";
+		const wasLive = holdIsLive(this.wakeHold, at);
+		const { hold, outcome } = absorbSignal({
+			current: this.wakeHold,
+			now: at,
+			holdMs
+		});
+		this.wakeHold = hold;
+		this.logger?.info("wake signal from the camera", {
+			tags: { deviceId: this.numericDeviceId },
+			meta: {
+				brokerId: this.deviceId,
+				code,
+				outcome,
+				signals: hold.signals,
+				untilMs: Math.max(0, hold.until - at),
+				runMs: hold.runStartedAt > 0 ? at - hold.runStartedAt : 0
+			}
+		});
+		this.armWakeHoldTimer(at);
+		if (outcome === "quarantined") return "no-consumer";
+		if (wasLive) return "hold-extended";
+		this.checkDemand();
+		return "woke";
+	}
+	/**
+	* Look at the hold when it lapses, so the camera actually goes back to sleep
+	* instead of waiting for an unrelated edge to notice.
+	*/
+	armWakeHoldTimer(now) {
+		if (this.wakeHoldTimer) clearTimeout(this.wakeHoldTimer);
+		const delay = this.wakeHold.until - now;
+		if (delay <= 0) return;
+		this.wakeHoldTimer = setTimeout(() => {
+			this.wakeHoldTimer = void 0;
+			this.logger?.info("wake hold lapsed — back to the prestream picture", {
+				tags: { deviceId: this.numericDeviceId },
+				meta: {
+					brokerId: this.deviceId,
+					signals: this.wakeHold.signals,
+					runMs: this.wakeHold.runStartedAt > 0 ? Date.now() - this.wakeHold.runStartedAt : 0
+				}
+			});
+			this.checkDemand();
+		}, delay);
+		this.wakeHoldTimer.unref?.();
+	}
+	/**
+	* Anything that must be FED, prestream sessions included.
+	*
+	* The only consumer of this is the prestream pump: it says "somebody is
+	* watching, keep the picture going", and says nothing about whether the
+	* camera may be dialled. {@link hasLiveIntent} answers that, and it is the
+	* one every dial path asks.
+	*/
+	hasAnyConsumer() {
+		if (this.hasLiveIntent()) return true;
+		return this.rtspRestreamer.getPrestreamSessionCount() > 0;
+	}
+	/**
+	* Consumers that may DIAL. Every term of the former `hasDemand`, with the
+	* RTSP session count filtered to exclude prestream dials, plus the wake hold.
+	*
+	* For a broker with no prestream session attached this is term-for-term what
+	* `hasDemand` was, which is why every existing camera, consumer and test
+	* behaves identically.
+	*/
+	hasLiveIntent() {
 		if (this.encodedCallbacks.size > 0) return true;
 		if (this.rtpVideoCallbacks.size > 0) return true;
 		if ((this.frameHandlePlane?.subscriberCount ?? 0) > 0) return true;
 		if (this.audioChunkPlane.subscriberCount > 0) return true;
-		if (this.rtspRestreamer.getSessionCount() > 0) return true;
+		if (this.rtspRestreamer.getLiveIntentSessionCount() > 0) return true;
 		if (this.pipeServer.getClientCount() > 0) return true;
 		if (this.prebufferHold !== null) return true;
+		if (holdIsLive(this.wakeHold, Date.now())) return true;
 		return false;
 	}
 	/**
@@ -12682,7 +13510,7 @@ var StreamBroker = class StreamBroker {
 	checkDemand() {
 		if (this.manualStop || this.stopping) return;
 		this.reconcileAudioConsumer();
-		if (this.hasDemand()) {
+		if (this.hasLiveIntent()) {
 			if (!this.demandActive) {
 				this.demandActive = true;
 				this.demandObserver?.(true);
@@ -12706,9 +13534,19 @@ var StreamBroker = class StreamBroker {
 		} else if (!this._suspended) {
 			if (!this.suspendTimer) this.suspendTimer = setTimeout(() => {
 				this.suspendTimer = void 0;
-				if (!this.hasDemand() && !this.manualStop && !this.stopping) this.suspend();
+				if (!this.hasLiveIntent() && !this.manualStop && !this.stopping) this.suspend();
 			}, SUSPEND_GRACE_MS);
 		}
+		this.prestreamWanted = this.hasAnyConsumer() && !this.hasLiveIntent();
+	}
+	/**
+	* Whether a prestream picture should be flowing right now: somebody is
+	* watching and the camera is not up. Read by the pump.
+	*/
+	prestreamWanted = false;
+	/** Whether the picture should be flowing — the pump's one question. */
+	wantsPrestream() {
+		return this.prestreamWanted;
 	}
 	/** Suspend the stream: kill ffmpeg/native client, clear buffers, go idle. Source is preserved for resume. */
 	suspend() {
@@ -12733,6 +13571,8 @@ var StreamBroker = class StreamBroker {
 			clearInterval(this.placeholderTimer);
 			this.placeholderTimer = void 0;
 		}
+		this.prestreamPump?.stop("broker suspended");
+		this.prestreamWindowClosed = false;
 		this.preBuffer.clear();
 		this.decoderSeedBuffer.clear();
 		this.clipBuffer?.clear();
@@ -12816,6 +13656,10 @@ var StreamBroker = class StreamBroker {
 	}
 	pushEncodedPacket(packet) {
 		if (this.stopping) return;
+		if (packet.isPlaceholder !== true && !this.prestreamWindowClosed) {
+			this.prestreamWindowClosed = true;
+			this.prestreamPump?.stop("first real packet");
+		}
 		if (this.source?.type === "push") {
 			this.stopErrorPlaceholder();
 			if (this._status === "error") this._status = "streaming";
@@ -12857,17 +13701,17 @@ var StreamBroker = class StreamBroker {
 			}
 		}
 		if (packet.type === "video" && !this.isRtpSource()) this.preBuffer.push(packet);
-		if (packet.type === "video" && this.clipBuffer) this.clipBuffer.push(packet);
+		if (packet.type === "video" && this.clipBuffer && packet.isPlaceholder !== true) this.clipBuffer.push(packet);
 		this.fanOutEncoded(packet);
 		if (packet.type === "video") {
 			this.pipeServer.broadcast(packet.data);
 			if (!this.rtspRestreamer.rtpPassthroughMode) this.rtspRestreamer.pushPacket(packet);
-			if (!this.firstKeyframeReceived && packet.keyframe) {
+			if (!this.firstKeyframeReceived && packet.keyframe && packet.isPlaceholder !== true) {
 				this.firstKeyframeReceived = true;
 				this.logger?.info("First keyframe received — decoder can start");
 			}
 		}
-		if (packet.type === "video" && this.firstKeyframeReceived) {
+		if (packet.type === "video" && this.firstKeyframeReceived && packet.isPlaceholder !== true) {
 			const plane = this.frameHandlePlane;
 			if (plane) {
 				const decoderPacket = this.decoderPacketWithParamSets(packet);
@@ -14431,7 +15275,7 @@ var StreamBroker = class StreamBroker {
 	}
 	scheduleReconnect() {
 		if (this.manualStop || !this.source) return;
-		if (!this.hasDemand()) {
+		if (!this.hasLiveIntent()) {
 			this._suspended = true;
 			this._status = "idle";
 			this.stopErrorPlaceholder();
@@ -14543,6 +15387,7 @@ var StreamBroker = class StreamBroker {
 			});
 			this._status = "error";
 			this.notifySourceRefresh();
+			if (!this.prestreamWindowClosed) this.prestreamPump?.start(source.url);
 			this.scheduleReconnect();
 			return;
 		}
@@ -15272,7 +16117,23 @@ var DeviceOverrideSchema = object({
 	derivedStreams: record(string(), DerivedStreamSchema).optional(),
 	hwaccel: record(string(), FfmpegHwAccelSettingSchema).optional(),
 	sourceParser: record(string(), SourceParserSettingSchema).optional(),
-	sourceParserArgs: record(string(), SourceParserArgsEntrySchema).optional()
+	sourceParserArgs: record(string(), SourceParserArgsEntrySchema).optional(),
+	/**
+	* The on-demand PRESTREAM, per camera.
+	*
+	* Absent means the operator has never touched it, which is NOT the same as
+	* off: `enabledSignals` absent means "every signal this camera recommends",
+	* so a Reolink works the moment a prestream URL is dialled without an
+	* operator hunting for a checkbox. An empty ARRAY is a deliberate "none" and
+	* is honoured — the two are different answers and the shape keeps them
+	* apart.
+	*/
+	prestream: object({
+		/** Signal codes allowed to wake this camera. Absent ⇒ the recommended set. */
+		enabledSignals: array(string()).optional(),
+		/** How long the camera stays up after the LAST signal. Absent ⇒ default. */
+		holdMs: number().int().min(1e3).max(3e5).optional()
+	}).optional()
 });
 /**
 * Read `audioEnabled` off a `privacyMask.getStatus` payload (D83 reconcile).
@@ -15416,6 +16277,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 	profileRestreamerBindings = /* @__PURE__ */ new Map();
 	/** Per-device published cam-stream registry. */
 	cameraStreams = /* @__PURE__ */ new Map();
+	/**
+	* The encoded prestream frame per broker, with the digest of the picture it
+	* was made from. One entry is one still image — kilobytes — and it is
+	* dropped with the broker in `releaseBroker`.
+	*/
+	prestreamFrames = /* @__PURE__ */ new Map();
 	/** Monotonic insertion counter per device — feeds `CameraStreamInternal.order`. */
 	streamOrderSeq = /* @__PURE__ */ new Map();
 	/** Persisted operator intent: which cam stream serves which profile. */
@@ -15767,7 +16634,10 @@ var StreamBrokerManager = class StreamBrokerManager {
 				sourceHasMedia: (brokerId) => {
 					const broker = this.brokers.get(brokerId);
 					if (broker === void 0) return null;
-					return broker.getLastPacketAt() > 0;
+					return sourceWaitState({
+						hasMedia: broker.getLastPacketAt() > 0,
+						materializing: broker.isMaterializing()
+					});
 				},
 				ffmpegConfig: () => this.ffmpegConfig,
 				...this.costRegistry === null ? {} : { costRegistry: this.costRegistry },
@@ -16303,6 +17173,150 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* firehose so we don't filter the entire device-state stream
 	* client-side and we get a typed payload.
 	*/
+	/**
+	* Build the per-broker PRESTREAM provider — the fill for the window between
+	* "someone asked for this camera" and "the camera is awake".
+	*
+	* On this hub that window is 2.2-12.4 s for a lazy source, and it is not
+	* merely ugly: Amazon allows SIX SECONDS for an Alexa SDP answer, so a cold
+	* battery camera could not answer an Echo at all.
+	*
+	* Four facts are needed and all four are the manager's, which is why the
+	* provider is a closure here rather than anything the broker knows about:
+	* the probed geometry and codec ({@link planPrestream}), the camera's last
+	* cached snapshot, its name, and the ffmpeg binary path.
+	*
+	* `null` is a REFUSAL, named in the log. Refusing is cheap — the consumer
+	* gets the black screen it got before the prestream existed — and the
+	* alternative for an unknown geometry is the decoder freeze the whole
+	* synthetic-frame path is shaped around.
+	*/
+	buildPrestreamProvider(deviceId, camStreamId, brokerId, logger) {
+		return { prepare: async ({ sourceUrl }) => {
+			const gate = prestreamEligible({
+				batteryOperated: await this.isBatteryOperated(deviceId),
+				declaresSignals: (await this.declaredSignalCodes(deviceId)).length > 0
+			});
+			if (!gate.eligible) {
+				logger.info("prestream: not offered for this camera", {
+					tags: { deviceId },
+					meta: {
+						brokerId,
+						reason: gate.reason
+					}
+				});
+				return null;
+			}
+			const stream = this.cameraStreams.get(deviceId)?.get(camStreamId);
+			const codec = this.lastProbedByBroker.get(brokerId)?.codec ?? stream?.codec;
+			const planned = planPrestream({
+				sourceUrl,
+				width: stream?.resolution?.width,
+				height: stream?.resolution?.height,
+				codec
+			});
+			if ("refusal" in planned) {
+				logger.info("prestream: no fill for this camera", {
+					tags: { deviceId },
+					meta: {
+						refusal: planned.refusal,
+						camStreamId,
+						width: stream?.resolution?.width ?? null,
+						height: stream?.resolution?.height ?? null,
+						codec: codec ?? null
+					}
+				});
+				return null;
+			}
+			return await this.preparePrestreamFrame(deviceId, brokerId, planned.plan, logger);
+		} };
+	}
+	/**
+	* Fetch the picture, compose the treatment, encode ONCE and cache the bytes.
+	*
+	* The cache is keyed on the picture's own digest plus the geometry, so a
+	* second wake of the same camera re-uses the frame and spawns nothing: the
+	* picture changes at most hourly, and a fork+exec per wake per sleeping
+	* camera is the cost this shape exists to avoid.
+	*/
+	async preparePrestreamFrame(deviceId, brokerId, plan, logger) {
+		if (!this.api) {
+			logger.info("prestream: no api access — the window goes unfilled", { tags: { deviceId } });
+			return null;
+		}
+		const api = this.api;
+		let cachedJpeg = null;
+		try {
+			const image = await api.snapshot.getSnapshot.query({ deviceId });
+			if (image) cachedJpeg = Buffer.from(image.base64, "base64");
+		} catch (err) {
+			logger.debug("prestream: cached snapshot read failed — falling back to the card", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		let deviceName = `#${String(deviceId)}`;
+		try {
+			const device = await api.deviceManager.getDevice.query({ deviceId });
+			if (device?.name) deviceName = device.name;
+		} catch (err) {
+			logger.debug("prestream: device name read failed — using the numeric id", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		const key = `${createHash("sha1").update(cachedJpeg ?? Buffer.alloc(0)).update(deviceName).digest("hex")}:${String(plan.width)}x${String(plan.height)}:${plan.codec}`;
+		const cached = this.prestreamFrames.get(brokerId);
+		if (cached && cached.key === key) {
+			logger.debug("prestream: re-using the encoded frame", {
+				tags: { deviceId },
+				meta: { bytes: cached.frame.annexB.length }
+			});
+			return cached.frame;
+		}
+		const picture = await composePrestreamPicture({
+			cachedJpeg,
+			deviceName,
+			width: plan.width,
+			height: plan.height,
+			logger,
+			deviceId
+		});
+		logger.info("prestream: picture composed", {
+			tags: { deviceId },
+			meta: {
+				source: picture.source,
+				width: plan.width,
+				height: plan.height,
+				codec: plan.codec
+			}
+		});
+		let annexB;
+		try {
+			annexB = await encodePrestreamIdr({
+				ffmpegPath: this.ffmpegConfig.binaryPath,
+				plan,
+				jpeg: picture.jpeg,
+				logger,
+				deviceId
+			});
+		} catch (err) {
+			logger.warn("prestream: encode failed — the window goes unfilled", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return null;
+		}
+		const frame = {
+			annexB,
+			codec: plan.codec
+		};
+		this.prestreamFrames.set(brokerId, {
+			key,
+			frame
+		});
+		return frame;
+	}
 	subscribePlaceholderStateSources(bus) {
 		bus.subscribe({ category: EventCategory.BatteryOnStatusChanged }, (event) => {
 			const data = event.data;
@@ -16457,11 +17471,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (!api) return;
 		await this.batteryWakeOnPlay.run(deviceId, {
 			logger: this.logger,
-			isBatteryDevice: async (id) => {
-				const dev = await api.deviceManager.getDevice.query({ deviceId: id }).catch(() => null);
-				if (!dev) return null;
-				return dev.features.includes(DeviceFeature.BatteryOperated);
-			},
+			isBatteryDevice: (id) => this.isBatteryOperated(id),
 			readBatteryFacts: async (id) => {
 				const slice = await api.deviceState.getCapSlice.query({
 					deviceId: id,
@@ -17994,6 +19004,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			const parsed = this.parseBrokerId(brokerId);
 			if (!parsed) continue;
 			const { deviceId, camStreamId } = parsed;
+			if (!healthEventIsOperatorFacing(camStreamId)) continue;
 			const lastPacketAt = broker.getLastPacketAt();
 			const wasHealthy = this.streamHealthByBroker.get(brokerId);
 			const isHealthy = lastPacketAt > 0 && now - lastPacketAt <= STREAM_STALE_TIMEOUT_MS;
@@ -18284,6 +19295,113 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* falls back to the global `ffmpeg.hwAccel`). Read by the transcode pipeline
 	* per spawn; affects ONLY the transcode paths.
 	*/
+	/**
+	* A device reporting one of its own signals — the cap method the provider
+	* calls. See `streamBroker.reportStreamSignal` for the contract.
+	*
+	* Everything that could refuse says WHY, because this is the path that
+	* decides whether a battery camera wakes, and a silent refusal here is
+	* indistinguishable from a signal that never arrived.
+	*/
+	async reportStreamSignal(input) {
+		const at = input.at ?? Date.now();
+		const declared = await this.declaredSignalCodes(input.deviceId);
+		if (!declared.includes(input.code)) {
+			this.logger.warn("wake signal REFUSED — this camera never declared that code", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					code: input.code,
+					declared
+				}
+			});
+			return {
+				accepted: false,
+				reason: "unknown-code"
+			};
+		}
+		const settings = this.deviceOverrides.get(input.deviceId)?.prestream;
+		if (!(settings?.enabledSignals ?? declared).includes(input.code)) return {
+			accepted: false,
+			reason: "not-enabled"
+		};
+		const holdMs = settings?.holdMs ?? 15e3;
+		let outcome = "no-consumer";
+		for (const [brokerId, broker] of this.brokers) {
+			if (this.parseBrokerId(brokerId)?.deviceId !== input.deviceId) continue;
+			const result = broker.reportWakeSignal(input.code, holdMs, at);
+			if (result === "woke") outcome = "woke";
+			else if (result === "hold-extended" && outcome !== "woke") outcome = "hold-extended";
+		}
+		return {
+			accepted: outcome !== "no-consumer",
+			reason: outcome
+		};
+	}
+	/**
+	* What this camera says it can emit. `[]` when it declares the cap and lists
+	* nothing, and `[]` when it does not declare the cap at all — both mean no
+	* signal of that name is acceptable, which is the same refusal.
+	*/
+	/**
+	* The signals a camera declares, with their labels — what the form renders.
+	* `[]` on any failure, which the caller reads as "not eligible": a form built
+	* from a list we could not read would offer wakes nobody confirmed.
+	*/
+	async declaredSignalList(deviceId) {
+		const read = this.deviceSignalDetailReader;
+		if (read === null) return [];
+		try {
+			return await read(deviceId);
+		} catch {
+			return [];
+		}
+	}
+	async declaredSignalCodes(deviceId) {
+		const read = this.deviceSignalReader;
+		if (read === null) return [];
+		try {
+			return await read(deviceId);
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* How the manager asks a DEVICE what signals it declares. Injected by the
+	* host addon, which owns the device proxy. `null` until it is.
+	*/
+	deviceSignalReader = null;
+	setDeviceSignalReader(read) {
+		this.deviceSignalReader = read;
+	}
+	/** The same read, with labels — the form needs them, the wake decision does
+	*  not. Injected by the host addon for the same reason. */
+	deviceSignalDetailReader = null;
+	setDeviceSignalDetailReader(read) {
+		this.deviceSignalDetailReader = read;
+	}
+	/**
+	* Whether this device runs on a battery.
+	*
+	* The DEVICE REGISTRY, never the published cam-streams: a sleeping camera has
+	* none — which is precisely when this question gets asked — and
+	* `deviceHasFeature` reads the stream map, so it answers `false` for every
+	* sleeping battery camera. That reasoning was written for the wake-on-play
+	* path and belongs to the question, not to one caller of it.
+	*
+	* `null` when nobody could say, and unknown is refused by every caller rather
+	* than guessed: guessing yes puts a mains camera in a wake-hold loop, and
+	* guessing no silently disables the feature on the cameras it exists for.
+	*/
+	async isBatteryOperated(deviceId) {
+		if (!this.api) return null;
+		try {
+			const features = (await this.api.deviceManager.getDevice.query({ deviceId }))?.features;
+			if (!Array.isArray(features)) return null;
+			return features.includes(DeviceFeature.BatteryOperated);
+		} catch {
+			return null;
+		}
+	}
 	getStreamHwAccelOverride(deviceId, camStreamId) {
 		return this.deviceOverrides.get(deviceId)?.hwaccel?.[camStreamId] ?? null;
 	}
@@ -18382,6 +19500,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 			value: setting,
 			label: hwAccelOptionLabel(setting)
 		}));
+		const declaredSignals = await this.declaredSignalList(deviceId);
+		const prestreamGate = prestreamEligible({
+			batteryOperated: await this.isBatteryOperated(deviceId),
+			declaresSignals: declaredSignals.length > 0
+		});
+		const prestreamOffered = prestreamGate.eligible;
 		const streamTabs = streams.filter((s) => !s.camStreamId.startsWith("derived:")).map((stream) => {
 			const camStreamId = stream.camStreamId;
 			const brokerId = brokerIdFor(deviceId, camStreamId);
@@ -18481,6 +19605,20 @@ var StreamBrokerManager = class StreamBrokerManager {
 						tooltip: "Copy muted URL to clipboard"
 					}]
 				},
+				...prestreamOffered ? [{
+					type: "text",
+					key: `rtspPrestreamUrl:${camStreamId}`,
+					label: "RTSP URL (prestream)",
+					description: "Video-only. Shows this camera’s last picture while it sleeps and cuts to live video when one of its wake signals fires — without a consumer on this URL ever keeping the camera awake.",
+					readonlyField: true,
+					span: 2,
+					value: rtspEntry?.url ? `${rtspEntry.url}/prestream` : "inactive",
+					actions: [{
+						action: "copy-value",
+						icon: "copy",
+						tooltip: "Copy prestream URL to clipboard"
+					}]
+				}] : [],
 				{
 					type: "boolean",
 					style: "switch",
@@ -18648,7 +19786,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				}
 			]
 		}));
-		return { sections: [{
+		const streamBrokerSection = {
 			id: "stream-broker-streams",
 			title: "",
 			tab: "stream-broker",
@@ -18665,7 +19803,37 @@ var StreamBrokerManager = class StreamBrokerManager {
 					...derivedTabs
 				]
 			}]
-		}, {
+		};
+		const prestreamCfg = override?.prestream;
+		const prestreamSections = prestreamGate.eligible ? [{
+			id: "stream-broker-prestream",
+			title: "Wake signals",
+			tab: "stream-broker",
+			location: "top-tab",
+			order: 50,
+			description: "A consumer can dial this camera’s prestream URL (the profile URL with /prestream) and be shown the last picture while the camera sleeps. It is fed without keeping the camera awake: only the signals below wake it, and it goes back to sleep once they stop.",
+			fields: [...declaredSignals.map((signal) => ({
+				type: "boolean",
+				style: "switch",
+				key: `prestreamSignal:${signal.code}`,
+				label: signal.label,
+				description: signal.recommended ? "Recommended by this camera’s driver." : "Offered by this camera’s driver.",
+				default: signal.recommended,
+				value: prestreamCfg?.enabledSignals === void 0 ? true : prestreamCfg.enabledSignals.includes(signal.code)
+			})), {
+				type: "number",
+				key: "prestreamHoldMs",
+				label: "Stay awake after the last signal",
+				description: "How long the camera keeps streaming once its signals stop. Extended by each new signal, never stacked — continuous motion keeps it up and it sleeps this long after the last one. One run is capped at five minutes whatever this says, and a camera whose sensor never stops is left alone for ten minutes after that.",
+				min: 1e3,
+				max: 3e5,
+				step: 1e3,
+				unit: "ms",
+				default: DEFAULT_WAKE_HOLD_MS,
+				value: prestreamCfg?.holdMs ?? 15e3
+			}]
+		}] : [];
+		const diagnosticsSection = {
 			id: "stream-broker-diagnostics",
 			title: "Diagnostics",
 			tab: "stream-broker",
@@ -18688,7 +19856,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 				default: false,
 				value: override?.webrtcDebug === true
 			}]
-		}] };
+		};
+		return { sections: [
+			streamBrokerSection,
+			...prestreamSections,
+			diagnosticsSection
+		] };
 	}
 	async getDeviceLiveContribution(_input) {
 		return null;
@@ -18800,6 +19973,31 @@ var StreamBrokerManager = class StreamBrokerManager {
 				nextOverride.sourceParserArgs = spa;
 				continue;
 			}
+			if (fieldKey.startsWith("prestreamSignal:")) {
+				overrideDirty = true;
+				const next = nextEnabledSignals({
+					declared: await this.declaredSignalCodes(deviceId),
+					stored: nextOverride.prestream?.enabledSignals,
+					code: fieldKey.slice(16),
+					enabled: value === null || value === void 0 ? true : Boolean(value)
+				});
+				nextOverride.prestream = {
+					...nextOverride.prestream,
+					enabledSignals: [...next]
+				};
+				continue;
+			}
+			if (fieldKey === "prestreamHoldMs") {
+				overrideDirty = true;
+				const raw = typeof value === "number" ? value : Number(value);
+				if (!Number.isFinite(raw)) continue;
+				const clamped = Math.min(3e5, Math.max(1e3, Math.round(raw)));
+				nextOverride.prestream = {
+					...nextOverride.prestream,
+					holdMs: clamped
+				};
+				continue;
+			}
 			if (fieldKey === "streamingDebug") {
 				overrideDirty = true;
 				const next = value === null || value === void 0 ? void 0 : Boolean(value);
@@ -19451,6 +20649,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		broker.setRequestSourceRefresh(() => {
 			this.emitRequestStreamSourceRefresh(deviceId, camStreamId, brokerId);
 		});
+		broker.setPrestreamProvider(this.buildPrestreamProvider(deviceId, camStreamId, brokerId, brokerLogger));
 		try {
 			await broker.start(source);
 		} catch (err) {
@@ -19498,6 +20697,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		this.streamOfflineReasonByBroker.delete(brokerId);
 		await broker.stop();
 		this.brokers.delete(brokerId);
+		this.prestreamFrames.delete(brokerId);
 		this.sweepFrameSubscriptions(brokerId);
 		this.rtspProvider.persistTokens();
 		this.syncProfileRestreamers(deviceId);
@@ -19964,6 +21164,28 @@ var WEBRTC_FALLBACK_PROFILE = {
 	},
 	audio: "passthrough"
 };
+function shouldWriteLossLine(input) {
+	if (input.lastWritten === null) return {
+		write: true,
+		reason: "first"
+	};
+	if (input.sample.hasReceiverReport !== input.lastWritten.hasReceiverReport) return {
+		write: true,
+		reason: "reporting-changed"
+	};
+	if (Math.abs(input.sample.lossPct - input.lastWritten.lossPct) >= 2) return {
+		write: true,
+		reason: "loss-moved"
+	};
+	if (input.ticksSinceWrite >= 10) return {
+		write: true,
+		reason: "heartbeat"
+	};
+	return {
+		write: false,
+		reason: "quiet"
+	};
+}
 //#endregion
 //#region src/stream-broker/webrtc/mdns-resolve.ts
 /**
@@ -20939,6 +22161,14 @@ function selectAudioClock(mimeType) {
 }
 //#endregion
 //#region src/stream-broker/webrtc/session.ts
+/**
+* Adaptive WebRTC session — extends the base session pattern with:
+* - RTCP Receiver Report monitoring (packet loss, jitter, RTT)
+* - Source replacement (replaceTrack for seamless quality switching)
+* - Stats emission for the AdaptiveController
+*
+* Uses werift (optional peer dependency) for server-side WebRTC.
+*/
 var _werift;
 async function loadWerift() {
 	if (_werift) return _werift;
@@ -21245,6 +22475,10 @@ var AdaptiveSession = class AdaptiveSession {
 	/** Log the camera's actual H.264 profile-level-id once per session. */
 	profileLogged = false;
 	onStats;
+	consumerKind;
+	/** The last loss sample actually WRITTEN, and how many ticks ago. */
+	lastLossWritten = null;
+	lossTicksSinceWrite = 0;
 	debug;
 	sourceCodec;
 	/**
@@ -21554,6 +22788,7 @@ var AdaptiveSession = class AdaptiveSession {
 		this.intercom = options.intercom;
 		this.iceConfig = options.iceConfig;
 		this.onStats = options.onStats;
+		this.consumerKind = options.consumerKind ?? "unknown";
 		this.debug = options.debug ?? false;
 		this.sourceCodec = options.sourceCodec ?? "H264";
 		this.transcodeToBaseline = options.transcodeToBaseline ?? false;
@@ -23556,6 +24791,37 @@ var AdaptiveSession = class AdaptiveSession {
 			selectedRemoteType: nominated?.remoteType ?? "none",
 			selectedRemoteAddr: nominated?.remoteAddr ?? "none"
 		} });
+		const rembRaw = this.videoSender?.receiverEstimatedMaxBitrate;
+		const rembBps = typeof rembRaw === "bigint" && rembRaw > 0n ? Number(rembRaw) : -1;
+		const sample = {
+			hasReceiverReport: report !== void 0,
+			lossPct: report ? Math.round(fractionLost / 256 * 100) : -1
+		};
+		this.lossTicksSinceWrite += 1;
+		const verdict = shouldWriteLossLine({
+			sample,
+			lastWritten: this.lastLossWritten,
+			ticksSinceWrite: this.lossTicksSinceWrite
+		});
+		if (verdict.write) {
+			this.lastLossWritten = sample;
+			this.lossTicksSinceWrite = 0;
+			this.logger.info("webrtc loss", {
+				tags: { deviceId: this.deviceId },
+				meta: {
+					sessionId: this.sessionId,
+					consumerKind: this.consumerKind,
+					why: verdict.reason,
+					hasReceiverReport: sample.hasReceiverReport,
+					rembBps,
+					lossPct: sample.lossPct,
+					packetsLost,
+					jitterMs: report ? Math.round(jitter / 90) : -1,
+					rttMs: report ? Math.round(rtt * 1e3) : -1,
+					rtpPacketsSent: this.rtpPacketsSent
+				}
+			});
+		}
 		if (report && this.onStats) this.onStats({
 			sessionId: this.sessionId,
 			packetLoss: fractionLost / 256,
@@ -28784,7 +30050,8 @@ var BrokerWebrtcServer = class {
 			logger: sessionLogger,
 			deviceId,
 			rtpBootstrap: useRtpRepacketizer ? () => broker.getRtpPreBuffer() : void 0,
-			debug: opts.streamingDebug === true
+			debug: opts.streamingDebug === true,
+			consumerKind: baseAttribution.kind
 		});
 		const seedFromSdp = (ps) => {
 			if (sessionCodec === "H265") session.seedH265CodecInfoFromSdp(ps);
@@ -29167,7 +30434,11 @@ var BrokerWebrtcServer = class {
 	/** Live signaling state for a session — used by the webrtc-session
 	*  provider's getSessionState. Returns a null pending when unknown. */
 	getSessionRenegotiationState(sessionId) {
-		return { pendingRenegotiation: this.sessions.get(sessionId)?.session.pendingRenegotiation ?? null };
+		const entry = this.sessions.get(sessionId);
+		return {
+			pendingRenegotiation: entry?.session.pendingRenegotiation ?? null,
+			alive: entry !== void 0
+		};
 	}
 	/**
 	* Wire an {@link AdaptiveController} to a freshly-created adaptive session.
@@ -29577,12 +30848,15 @@ var CameraStreamsProvider = class {
 		const accept = requirements.acceptCodecs ?? [];
 		const minHeight = requirements.minHeight ?? 0;
 		const minWidth = requirements.minWidth ?? 0;
+		const maxHeight = requirements.maxHeight ?? Number.POSITIVE_INFINITY;
+		const allowTranscode = requirements.allowTranscode === true;
 		const candidates = streams.filter((s) => {
 			if (!isSelectable(s)) return false;
 			if (excludeDerived && s.camStreamId.startsWith("derived:")) return false;
-			if (accept.length > 0 && !codecMatches(s.codec, accept)) return false;
+			if (!allowTranscode && accept.length > 0 && !codecMatches(s.codec, accept)) return false;
 			if ((s.resolution?.height ?? 0) < minHeight) return false;
 			if ((s.resolution?.width ?? 0) < minWidth) return false;
+			if ((s.resolution?.height ?? 0) > maxHeight) return false;
 			return true;
 		});
 		if (candidates.length === 0) {
@@ -29627,24 +30901,35 @@ var CameraStreamsProvider = class {
 			for (let i = 0; i < preferredProviders.length; i += 1) if (camStreamId.startsWith(preferredProviders[i])) return i;
 			return preferredProviders.length;
 		};
-		candidates.sort((a, b) => {
-			const ra = providerRank(a.camStreamId);
-			const rb = providerRank(b.camStreamId);
-			if (ra !== rb) return ra - rb;
-			const ha = a.resolution?.height ?? 0;
-			const hb = b.resolution?.height ?? 0;
-			return resolutionPreference === "highest" ? hb - ha : ha - hb;
-		});
-		const winner = candidates[0];
+		const ranked = rankStreams(candidates.map((s) => ({
+			camStreamId: s.camStreamId,
+			...s.codec === void 0 ? {} : { codec: s.codec },
+			...s.resolution ? {
+				height: s.resolution.height,
+				width: s.resolution.width
+			} : {}
+		})), {
+			acceptCodecs: accept,
+			allowTranscode,
+			preferredProviders,
+			resolutionPreference,
+			...preferences?.targetHeight === void 0 ? {} : { targetHeight: preferences.targetHeight }
+		});
+		if (ranked === null) return null;
+		const winner = candidates.find((s) => s.camStreamId === ranked.candidate.camStreamId);
+		if (winner === void 0) return null;
 		const reasonParts = [];
 		reasonParts.push(`codec=${winner.codec ?? "unknown"}`);
 		if (winner.resolution) reasonParts.push(`res=${winner.resolution.width}x${winner.resolution.height}`);
 		reasonParts.push(`provider=${providerRank(winner.camStreamId)}`);
+		reasonParts.push(ranked.transcodes ? "transcode" : "passthrough");
+		if (preferences?.targetHeight !== void 0) reasonParts.push(`target=${preferences.targetHeight}`);
 		if (requireSibling.length > 0) reasonParts.push(`bypassed=${requireSibling.join("|")}`);
 		return {
 			camStreamId: winner.camStreamId,
 			codec: winner.codec,
 			resolution: winner.resolution,
+			transcodes: ranked.transcodes,
 			reason: reasonParts.join(" ")
 		};
 	}
@@ -30116,6 +31401,11 @@ var StreamBrokerAddon = class extends BaseAddon {
 		const localNode = this.ctx.kernel.localNodeId;
 		const localNodeId = localNode ? localNode.includes("/") ? localNode.split("/")[0] : localNode : void 0;
 		this.brokerManager.setApiAccess(this.ctx.api, localNodeId, this.ctx.kernel.hwaccel);
+		const readSignals = async (deviceId) => {
+			return await (await this.ctx.fetchDevice(deviceId)).streamSignals?.listSignals({}) ?? [];
+		};
+		this.brokerManager.setDeviceSignalReader(async (deviceId) => (await readSignals(deviceId)).map((s) => s.code));
+		this.brokerManager.setDeviceSignalDetailReader(readSignals);
 		await this.loadFfmpegConfig();
 		await this.declareRowCollections();
 		await this.purgeFlattenedSettingsKeys();