@camstack/addon-pipeline 1.2.249 → 1.2.250

package/dist/stream-broker/index.js

@@ -12484,6 +12484,8 @@ var StreamBroker = class StreamBroker {
 	* behaviour, unchanged.
 	*/
 	prestreamPump;
+	/** The manager's hook for "real media started" — see `PrestreamProvider`. */
+	onRealMediaStarted;
 	/**
 	* Latched once real media has been seen on this session.
 	*
@@ -12760,6 +12762,31 @@ var StreamBroker = class StreamBroker {
 	/** True while the stream is suspended (ffmpeg killed, no RTSP connection). */
 	_suspended = false;
 	/**
+	* The LAZY url this broker was started from, remembered for as long as it
+	* lives.
+	*
+	* It exists because the published url and the broker's state disagree for
+	* about sixteen seconds after a suspend. The catalog still carries the real
+	* `tcp://…` socket — the publisher only republishes the sentinel when its
+	* sleep poll notices the camera has gone — while the broker has already torn
+	* that socket down. In that window `resolveCurrentSource()` truthfully
+	* answers with a socket nobody can dial.
+	*
+	* That cost device 640 its prestream on 2026-09-16: the window re-opened
+	* (which `suspend()` does deliberately, for a consumer that never left) with
+	* the real url, `planPrestream` refused it `not-lazy`, and the refusal is
+	* terminal — the operator's client sat dark for ten seconds and gave up six
+	* before the sentinel came back.
+	*
+	* NOT cleared when `start()` is later called with a materialized url: that
+	* happens on every wake, and clearing it there is the bug again. A broker
+	* genuinely reconfigured onto a permanent mains source keeps a stale value,
+	* which costs nothing — `prestreamEligible` (battery + declared signals) is
+	* the authority on whether a camera gets a prestream at all, and it is asked
+	* first, in the manager.
+	*/
+	lazySourceUrl;
+	/**
 	* Optional demand-transition observer. Fires `true` the instant demand first
 	* appears (a consumer attaches) and `false` when the broker actually suspends
 	* after the idle grace — aligned with the broker's own reader spawn/teardown
@@ -13031,6 +13058,7 @@ var StreamBroker = class StreamBroker {
 	* sees black, which is the outcome every refusal falls back to.
 	*/
 	setPrestreamProvider(provider) {
+		this.onRealMediaStarted = provider.onRealMediaStarted;
 		this.prestreamPump = new PrestreamPump({
 			prepare: provider.prepare,
 			emit: (frame) => {
@@ -13140,13 +13168,26 @@ var StreamBroker = class StreamBroker {
 			const fresh = this.sourceProvider();
 			if (fresh) {
 				this.source = fresh;
+				this.noteLazyUrl(fresh.url);
 				return fresh;
 			}
 		}
 		return this.source ?? null;
 	}
+	/**
+	* Remember a lazy url ANY time one is seen — see {@link lazySourceUrl}.
+	*
+	* Here and not only in `start()` because a broker that has never dialled is a
+	* real and common state: a battery camera nobody has asked for yet, with a
+	* prestream consumer attached, has a recipe and no socket. Learning it from
+	* the dial alone would leave exactly that broker unable to describe itself.
+	*/
+	noteLazyUrl(url) {
+		if (typeof url === "string" && url.startsWith("lazy:rfc4571:")) this.lazySourceUrl = url;
+	}
 	async start(source) {
 		this.source = source;
+		this.noteLazyUrl(source.url);
 		this.manualStop = false;
 		this.stopping = false;
 		if (source.videoCodec) this.detectedCodec = source.videoCodec;
@@ -13660,7 +13701,7 @@ var StreamBroker = class StreamBroker {
 	reconcilePrestreamWindow() {
 		if (!this.prestreamPump) return;
 		if (this.prestreamWanted && !this.prestreamWindowClosed) {
-			const url = this.resolveCurrentSource()?.url ?? this.source?.url;
+			const url = this.lazySourceUrl ?? this.resolveCurrentSource()?.url ?? this.source?.url;
 			if (url !== void 0) this.prestreamPump.start(url);
 			return;
 		}
@@ -13787,6 +13828,14 @@ var StreamBroker = class StreamBroker {
 		if (packet.isPlaceholder !== true && !this.prestreamWindowClosed) {
 			this.prestreamWindowClosed = true;
 			this.prestreamPump?.stop("first real packet");
+			try {
+				this.onRealMediaStarted?.();
+			} catch (err) {
+				this.logger?.debug("prestream: real-media hook threw", {
+					tags: { deviceId: this.numericDeviceId ?? 0 },
+					meta: { error: String(err) }
+				});
+			}
 		}
 		if (this.source?.type === "push") {
 			this.stopErrorPlaceholder();
@@ -17382,44 +17431,89 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* 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 {
+			prepare: async ({ sourceUrl }) => {
+				const gate = prestreamEligible({
+					batteryOperated: await this.isBatteryOperated(deviceId),
+					declaresSignals: (await this.declaredSignalCodes(deviceId)).length > 0
 				});
-				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
-					}
+				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);
+			},
+			/**
+			* REFRESH THE PICTURE WHILE THE CAMERA IS UP.
+			*
+			* The window shows the camera's last snapshot, and nothing was
+			* refreshing it: a battery camera refuses a capture while it believes
+			* itself asleep, and that belief lags the wake by seconds — so the only
+			* attempts ever made were the prestream's own, while composing, which is
+			* BEFORE any media exists. Measured on device 640 (2026-09-16): four
+			* wakes in forty minutes, the encoded picture `bytes=23912` every time,
+			* and between first packet and suspend not one capture was even
+			* attempted. The operator read the result as a placeholder rather than
+			* as their own room, which is exactly what it had become.
+			*
+			* Here the camera is provably awake and its media is flowing, so a
+			* capture costs it nothing it is not already paying — and what lands is
+			* a scene from the event that just happened.
+			*
+			* NEVER `force`: it is an operator signal, and the rule holds even where
+			* it would be harmless. If the native path still refuses, the addon's
+			* own stream-broker fallback pulls a frame from the restream that is, by
+			* construction, running right now.
+			*
+			* Fire and forget, and a failure is DEBUG: the window already has a
+			* picture to show, and this only decides how recent the NEXT one is.
+			*/
+			onRealMediaStarted: () => {
+				const api = this.api;
+				if (!api) return;
+				api.snapshot.getSnapshot.query({ deviceId }).then(() => {
+					logger.debug("prestream: picture refreshed from the live window", {
+						tags: { deviceId },
+						meta: { brokerId }
+					});
+				}).catch((err) => {
+					logger.debug("prestream: live-window refresh failed — keeping the older picture", {
+						tags: { deviceId },
+						meta: {
+							brokerId,
+							error: require_dist.errMsg(err)
+						}
+					});
 				});
-				return null;
 			}
-			return await this.preparePrestreamFrame(deviceId, brokerId, planned.plan, logger);
-		} };
+		};
 	}
 	/**
 	* Fetch the picture, compose the treatment, encode ONCE and cache the bytes.

package/dist/stream-broker/index.mjs

@@ -12480,6 +12480,8 @@ var StreamBroker = class StreamBroker {
 	* behaviour, unchanged.
 	*/
 	prestreamPump;
+	/** The manager's hook for "real media started" — see `PrestreamProvider`. */
+	onRealMediaStarted;
 	/**
 	* Latched once real media has been seen on this session.
 	*
@@ -12756,6 +12758,31 @@ var StreamBroker = class StreamBroker {
 	/** True while the stream is suspended (ffmpeg killed, no RTSP connection). */
 	_suspended = false;
 	/**
+	* The LAZY url this broker was started from, remembered for as long as it
+	* lives.
+	*
+	* It exists because the published url and the broker's state disagree for
+	* about sixteen seconds after a suspend. The catalog still carries the real
+	* `tcp://…` socket — the publisher only republishes the sentinel when its
+	* sleep poll notices the camera has gone — while the broker has already torn
+	* that socket down. In that window `resolveCurrentSource()` truthfully
+	* answers with a socket nobody can dial.
+	*
+	* That cost device 640 its prestream on 2026-09-16: the window re-opened
+	* (which `suspend()` does deliberately, for a consumer that never left) with
+	* the real url, `planPrestream` refused it `not-lazy`, and the refusal is
+	* terminal — the operator's client sat dark for ten seconds and gave up six
+	* before the sentinel came back.
+	*
+	* NOT cleared when `start()` is later called with a materialized url: that
+	* happens on every wake, and clearing it there is the bug again. A broker
+	* genuinely reconfigured onto a permanent mains source keeps a stale value,
+	* which costs nothing — `prestreamEligible` (battery + declared signals) is
+	* the authority on whether a camera gets a prestream at all, and it is asked
+	* first, in the manager.
+	*/
+	lazySourceUrl;
+	/**
 	* Optional demand-transition observer. Fires `true` the instant demand first
 	* appears (a consumer attaches) and `false` when the broker actually suspends
 	* after the idle grace — aligned with the broker's own reader spawn/teardown
@@ -13027,6 +13054,7 @@ var StreamBroker = class StreamBroker {
 	* sees black, which is the outcome every refusal falls back to.
 	*/
 	setPrestreamProvider(provider) {
+		this.onRealMediaStarted = provider.onRealMediaStarted;
 		this.prestreamPump = new PrestreamPump({
 			prepare: provider.prepare,
 			emit: (frame) => {
@@ -13136,13 +13164,26 @@ var StreamBroker = class StreamBroker {
 			const fresh = this.sourceProvider();
 			if (fresh) {
 				this.source = fresh;
+				this.noteLazyUrl(fresh.url);
 				return fresh;
 			}
 		}
 		return this.source ?? null;
 	}
+	/**
+	* Remember a lazy url ANY time one is seen — see {@link lazySourceUrl}.
+	*
+	* Here and not only in `start()` because a broker that has never dialled is a
+	* real and common state: a battery camera nobody has asked for yet, with a
+	* prestream consumer attached, has a recipe and no socket. Learning it from
+	* the dial alone would leave exactly that broker unable to describe itself.
+	*/
+	noteLazyUrl(url) {
+		if (typeof url === "string" && url.startsWith("lazy:rfc4571:")) this.lazySourceUrl = url;
+	}
 	async start(source) {
 		this.source = source;
+		this.noteLazyUrl(source.url);
 		this.manualStop = false;
 		this.stopping = false;
 		if (source.videoCodec) this.detectedCodec = source.videoCodec;
@@ -13656,7 +13697,7 @@ var StreamBroker = class StreamBroker {
 	reconcilePrestreamWindow() {
 		if (!this.prestreamPump) return;
 		if (this.prestreamWanted && !this.prestreamWindowClosed) {
-			const url = this.resolveCurrentSource()?.url ?? this.source?.url;
+			const url = this.lazySourceUrl ?? this.resolveCurrentSource()?.url ?? this.source?.url;
 			if (url !== void 0) this.prestreamPump.start(url);
 			return;
 		}
@@ -13783,6 +13824,14 @@ var StreamBroker = class StreamBroker {
 		if (packet.isPlaceholder !== true && !this.prestreamWindowClosed) {
 			this.prestreamWindowClosed = true;
 			this.prestreamPump?.stop("first real packet");
+			try {
+				this.onRealMediaStarted?.();
+			} catch (err) {
+				this.logger?.debug("prestream: real-media hook threw", {
+					tags: { deviceId: this.numericDeviceId ?? 0 },
+					meta: { error: String(err) }
+				});
+			}
 		}
 		if (this.source?.type === "push") {
 			this.stopErrorPlaceholder();
@@ -17378,44 +17427,89 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* 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 {
+			prepare: async ({ sourceUrl }) => {
+				const gate = prestreamEligible({
+					batteryOperated: await this.isBatteryOperated(deviceId),
+					declaresSignals: (await this.declaredSignalCodes(deviceId)).length > 0
 				});
-				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
-					}
+				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);
+			},
+			/**
+			* REFRESH THE PICTURE WHILE THE CAMERA IS UP.
+			*
+			* The window shows the camera's last snapshot, and nothing was
+			* refreshing it: a battery camera refuses a capture while it believes
+			* itself asleep, and that belief lags the wake by seconds — so the only
+			* attempts ever made were the prestream's own, while composing, which is
+			* BEFORE any media exists. Measured on device 640 (2026-09-16): four
+			* wakes in forty minutes, the encoded picture `bytes=23912` every time,
+			* and between first packet and suspend not one capture was even
+			* attempted. The operator read the result as a placeholder rather than
+			* as their own room, which is exactly what it had become.
+			*
+			* Here the camera is provably awake and its media is flowing, so a
+			* capture costs it nothing it is not already paying — and what lands is
+			* a scene from the event that just happened.
+			*
+			* NEVER `force`: it is an operator signal, and the rule holds even where
+			* it would be harmless. If the native path still refuses, the addon's
+			* own stream-broker fallback pulls a frame from the restream that is, by
+			* construction, running right now.
+			*
+			* Fire and forget, and a failure is DEBUG: the window already has a
+			* picture to show, and this only decides how recent the NEXT one is.
+			*/
+			onRealMediaStarted: () => {
+				const api = this.api;
+				if (!api) return;
+				api.snapshot.getSnapshot.query({ deviceId }).then(() => {
+					logger.debug("prestream: picture refreshed from the live window", {
+						tags: { deviceId },
+						meta: { brokerId }
+					});
+				}).catch((err) => {
+					logger.debug("prestream: live-window refresh failed — keeping the older picture", {
+						tags: { deviceId },
+						meta: {
+							brokerId,
+							error: errMsg(err)
+						}
+					});
 				});
-				return null;
 			}
-			return await this.preparePrestreamFrame(deviceId, brokerId, planned.plan, logger);
-		} };
+		};
 	}
 	/**
 	* Fetch the picture, compose the treatment, encode ONCE and cache the bytes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-pipeline",
-  "version": "1.2.249",
+  "version": "1.2.250",
   "description": "Pipeline bundle — runner, detection, motion, audio + stream broker. Multi-entry npm package shipping pipeline addons under a single bundle.",
   "keywords": [
     "camstack",