@camstack/system 1.2.92 → 1.2.94

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BH2tZ9ZN.js");
+const require_dist = require("../../dist-BspfS8Q7.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
@@ -255,7 +255,7 @@ function raceForResult(promise, timeoutMs) {
 //#endregion
 //#region src/builtins/snapshot/snapshot-courtesy.ts
 /**
-* A courtesy frame for a camera that CANNOT produce one.
+* State treatment for a camera that cannot produce a current frame.
 *
 * ── Why this exists ───────────────────────────────────────────────────────
 * A disabled, offline or sleeping camera has no frame, and until 2026-08-11 the
@@ -266,9 +266,9 @@ function raceForResult(promise, timeoutMs) {
 * who deliberately switched a camera off saw the same thing as a fault ([D62]:
 * "an off switch is REPORTED off; disabled must never look like broken").
 *
-* So the service answers with a frame that SAYS what is going on, carrying the
-* camera's own name. The client gets a valid image, the tile paints, and the
-* state is legible instead of inferred from an error.
+* So the service answers with an image that SAYS what is going on, carrying
+* the camera's own name. When a real cached frame exists it remains visible
+* under the treatment; otherwise the generated courtesy background is used.
 *
 * ── Why sharp and not ffmpeg ──────────────────────────────────────────────
 * The first draft of this file shelled out to `ffmpeg` with a `drawtext`
@@ -299,6 +299,8 @@ function courtesyLabel(reason) {
 		case "disabled": return "Disabled";
 		case "offline": return "Offline";
 		case "sleeping": return "Sleeping";
+		case "unreachable": return "Unreachable";
+		case "waking": return "Waking";
 	}
 }
 /**
@@ -310,6 +312,8 @@ function courtesyBackground(reason) {
 		case "disabled": return "#2b2b31";
 		case "offline": return "#3a2b2b";
 		case "sleeping": return "#232b3a";
+		case "waking": return "#243247";
+		case "unreachable": return "#3a2b2b";
 	}
 }
 /** XML escaping for text placed inside an SVG `<text>` node. */
@@ -324,15 +328,27 @@ function escapeCourtesyText(value) {
 * frame read the same, with a floor so a thumbnail stays legible.
 */
 function buildCourtesySvg(spec) {
+	return buildStateSvg(spec, false);
+}
+/**
+* The same state treatment as a courtesy frame, but translucent so the last
+* real camera frame remains visible underneath it.
+*/
+function buildCourtesyOverlaySvg(spec) {
+	return buildStateSvg(spec, true);
+}
+function buildStateSvg(spec, overlay) {
 	const stateSize = Math.max(12, Math.round(spec.width / 12));
 	const nameSize = Math.max(9, Math.round(spec.width / 26));
 	const state = escapeCourtesyText(courtesyLabel(spec.reason));
 	const name = escapeCourtesyText(spec.deviceName);
 	const midY = spec.height / 2;
+	const washOpacity = overlay ? "0.62" : "1";
+	const textStroke = Math.max(1, Math.round(spec.width / 320));
 	return [
 		`<svg xmlns="http://www.w3.org/2000/svg" width="${String(spec.width)}" height="${String(spec.height)}">`,
-		`<rect width="100%" height="100%" fill="${courtesyBackground(spec.reason)}"/>`,
-		`<g font-family="${COURTESY_FONT_STACK}" text-anchor="middle">`,
+		`<rect width="100%" height="100%" fill="${courtesyBackground(spec.reason)}" fill-opacity="${washOpacity}"/>`,
+		`<g font-family="${COURTESY_FONT_STACK}" text-anchor="middle" paint-order="stroke" stroke="#111118" stroke-width="${String(textStroke)}">`,
 		`<text x="50%" y="${String(Math.round(midY))}" font-size="${String(stateSize)}" fill="#e8e8ee">${state}</text>`,
 		`<text x="50%" y="${String(Math.round(midY + stateSize))}" font-size="${String(nameSize)}" fill="#9a9aa8">${name}</text>`,
 		`</g></svg>`
@@ -354,6 +370,24 @@ function renderCourtesyJpeg(spec) {
 		return bytes;
 	});
 }
+/**
+* Paint the state treatment over a real cached frame.
+*
+* The source dimensions are authoritative: overlays preserve the original
+* frame rather than resizing it to the generated courtesy-frame default.
+*/
+async function renderCourtesyOverlayJpeg(background, spec) {
+	const metadata = await (0, sharp.default)(background).metadata();
+	if (!metadata.width || !metadata.height) throw new Error("cached snapshot has no renderable dimensions");
+	const overlay = Buffer.from(buildCourtesyOverlaySvg({
+		...spec,
+		width: metadata.width,
+		height: metadata.height
+	}));
+	const bytes = await (0, sharp.default)(background).composite([{ input: overlay }]).jpeg({ quality: 82 }).toBuffer();
+	if (bytes.length === 0) throw new Error("courtesy overlay produced no bytes");
+	return bytes;
+}
 //#endregion
 //#region src/builtins/snapshot/snapshot-link-url.ts
 /**
@@ -547,7 +581,8 @@ function parseSnapshotMediaRequest(url) {
 * The response's entity tag.
 *
 * It has to identify the VARIANT, not just the frame: the same capture can now
-* be served at several widths and from several streams, and a plain
+* be served at several widths, from several streams, and with a camera-state
+* treatment, and a plain
 * `"<device>-<capturedAt>"` would let a client that fetched `?w=320` receive a
 * 304 for `?w=960` and render the small image at full size. The base form is
 * unchanged for a plain request, so the identity
@@ -558,6 +593,7 @@ function snapshotEtag(variant, capturedAt) {
 	const parts = [`${String(variant.deviceId)}-${String(capturedAt)}`];
 	if (variant.streamId !== void 0) parts.push(`s${variant.streamId}`);
 	if (variant.width !== void 0) parts.push(`w${String(variant.width)}`);
+	if (variant.variantKey !== void 0) parts.push(`v${variant.variantKey}`);
 	return `"${parts.join("-")}"`;
 }
 /**
@@ -588,7 +624,8 @@ function createSnapshotMediaHandler(deps) {
 				const peekedEtag = snapshotEtag({
 					deviceId: parsed.deviceId,
 					streamId: parsed.streamId,
-					width: parsed.width
+					width: parsed.width,
+					variantKey: peeked.variantKey
 				}, peeked.capturedAt);
 				if (inm === peekedEtag) {
 					res.writeHead(304, {
@@ -619,7 +656,8 @@ function createSnapshotMediaHandler(deps) {
 		const etag = snapshotEtag({
 			deviceId: parsed.deviceId,
 			streamId: parsed.streamId,
-			width: "servedWidth" in media ? media.servedWidth : parsed.width
+			width: "servedWidth" in media ? media.servedWidth : parsed.width,
+			variantKey: media.variantKey
 		}, media.capturedAt);
 		const cacheControl = `private, max-age=${Math.max(0, Math.floor(media.maxAgeS))}`;
 		if (inm === etag) {
@@ -722,8 +760,8 @@ function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
 	});
 }
 /**
-* Resized frames, keyed by (device, stream, width) AND validated against the
-* source frame's timestamp.
+* Resized frames, keyed by (device, stream, width, state treatment) AND
+* validated against the source frame's timestamp.
 *
 * The timestamp is the whole correctness argument: a variant outlives nothing.
 * When the underlying frame is recaptured its `capturedAt` moves, every variant
@@ -734,17 +772,17 @@ function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
 var SnapshotVariantCache = class SnapshotVariantCache {
 	byKey = /* @__PURE__ */ new Map();
 	keysByDevice = /* @__PURE__ */ new Map();
-	static key(deviceId, streamId, width) {
-		return `${deviceId}:${streamId ?? "auto"}:${width}`;
+	static key(deviceId, streamId, width, variantKey) {
+		return `${deviceId}:${streamId ?? "auto"}:${width}:${variantKey ?? "raw"}`;
 	}
 	/** The variant for this exact frame, or undefined when it is missing or was
 	*  derived from an older capture. */
-	get(deviceId, streamId, width, sourceTs) {
-		const entry = this.byKey.get(SnapshotVariantCache.key(deviceId, streamId, width));
+	get(deviceId, streamId, width, sourceTs, variantKey) {
+		const entry = this.byKey.get(SnapshotVariantCache.key(deviceId, streamId, width, variantKey));
 		return entry !== void 0 && entry.sourceTs === sourceTs ? entry.bytes : void 0;
 	}
-	set(deviceId, streamId, width, sourceTs, bytes) {
-		const key = SnapshotVariantCache.key(deviceId, streamId, width);
+	set(deviceId, streamId, width, sourceTs, bytes, variantKey) {
+		const key = SnapshotVariantCache.key(deviceId, streamId, width, variantKey);
 		this.byKey.set(key, {
 			bytes,
 			sourceTs
@@ -785,6 +823,9 @@ var LINK_MINT_DEADLINE_MS = 2500;
 var LINK_BATCH_WAIT_MS = 750;
 /** Frames older than this are never represented as current by the Viewer. */
 var LINK_CURRENT_MAX_AGE_MS = 15e3;
+/** Wake-on-play's 8 s firmware wait + 20 s broker settle, with scheduling
+*  slack. A lost completion event must not leave a camera "Waking" forever. */
+var SNAPSHOT_WAKING_TTL_MS = 35e3;
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
@@ -829,9 +870,14 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	* A courtesy frame is a pure function of those three, so it is rendered once
 	* and reused for as long as the process lives — a disabled camera must not
 	* cost an ffmpeg run per poll. Unbounded on purpose: the key space is
-	* (3 reasons × this node's own cameras), not user input.
+	* (state reasons × this node's own cameras), not user input.
 	*/
 	courtesyFrames = /* @__PURE__ */ new Map();
+	/** State overlays over real cached frames, grouped by device so invalidation
+	*  can discard every generation in O(1). */
+	stateFrames = /* @__PURE__ */ new Map();
+	/** Devices inside the explicit battery wake-in-progress window. */
+	wakingDevices = /* @__PURE__ */ new Map();
 	/**
 	* De-dupes concurrent captures per `${deviceId}:${streamId}` and holds a
 	* settled SUCCESS for COALESCE_MS so a grid-mount burst (and a row of refresh
@@ -903,6 +949,12 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			const deviceId = event.data.deviceId;
 			if (typeof deviceId === "number") this.evictRemovedDevice(deviceId, "device-unregistered");
 		});
+		this.subscribe({ category: require_dist.EventCategory.BatteryOnWakeStarted }, (event) => {
+			this.wakingDevices.set(event.data.deviceId, Date.now());
+		});
+		this.subscribe({ category: require_dist.EventCategory.BatteryOnStatusChanged }, (event) => {
+			this.wakingDevices.delete(event.data.deviceId);
+		});
 		await this.serveMediaDataPlane();
 		await this.ensureLinkDataPlane();
 		return [{
@@ -1164,13 +1216,12 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			}
 		});
 	}
-	/** True only for a BATTERY device that is currently asleep. Kept as one
-	*  question so the link path cannot accidentally treat "battery" as "asleep"
-	*  and stop refreshing a camera that is awake and streaming. */
+	/** True only for a battery device that must not be snapshot-refreshed. */
 	async isSleepingBatteryDevice(deviceId) {
 		try {
-			if ((await this.lookupDeviceMeta(deviceId))?.isBattery !== true) return false;
-			return await this.isDeviceSleeping(deviceId);
+			const meta = await this.lookupDeviceMeta(deviceId);
+			const state = await this.resolveSnapshotState(deviceId, meta);
+			return state.reason === "sleeping" || state.reason === "unreachable" || state.reason === "waking";
 		} catch {
 			return false;
 		}
@@ -1184,28 +1235,31 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
 	*/
 	async resolveSnapshotMedia(deviceId, streamId, force, width) {
+		const resolutionMeta = {};
 		const image = await this.getSnapshot({
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
 			force
-		});
+		}, 0, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, resolutionMeta);
 		if (!image) return null;
 		const capturedAt = this.cache.get(deviceId, streamId)?.ts ?? Date.now();
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
-		const isBattery = (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false;
+		const isBattery = resolutionMeta.isBattery ?? false;
 		if (width === void 0) return {
 			bytes: Buffer.from(image.base64, "base64"),
 			contentType: image.contentType,
 			capturedAt,
 			maxAgeS: effectiveMaxAgeS(prefs, isBattery),
+			variantKey: resolutionMeta.stateReason,
 			servedWidth: void 0
 		};
-		const thumb = await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs);
+		const thumb = await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs, resolutionMeta.stateReason);
 		return {
 			bytes: thumb.bytes,
 			contentType: image.contentType,
 			capturedAt,
 			maxAgeS: effectiveMaxAgeS(prefs, isBattery),
+			variantKey: resolutionMeta.stateReason,
 			servedWidth: thumb.width
 		};
 	}
@@ -1221,24 +1275,28 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	async peekFreshFrame(deviceId, streamId) {
 		const hit = this.cache.get(deviceId, streamId);
 		if (!hit) return null;
-		const maxAgeS = effectiveMaxAgeS(await this.readDeviceSettings(deviceId).catch(() => ({})), (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false);
+		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
+		const meta = await this.lookupDeviceMeta(deviceId);
+		const state = await this.resolveSnapshotState(deviceId, meta);
+		const maxAgeS = effectiveMaxAgeS(prefs, state.isBattery);
 		if (Date.now() - hit.ts >= maxAgeS * 1e3) return null;
 		return {
 			capturedAt: hit.ts,
-			maxAgeS
+			maxAgeS,
+			variantKey: state.reason
 		};
 	}
 	/**
-	* The frame at a card-sized width, derived once per (device, stream, width)
-	* per capture.
+	* The frame at a card-sized width, derived once per
+	* (device, stream, width, state treatment) per capture.
 	*
 	* A failed resize falls back to the FULL frame — a visible card beats a
 	* broken one — but never silently: the card would otherwise keep costing a
 	* megabyte with nothing anywhere saying why, which is the shape of the bug
 	* this whole change came from.
 	*/
-	async thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs) {
-		const cached = this.variants.get(deviceId, streamId, width, capturedAt);
+	async thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs, variantKey) {
+		const cached = this.variants.get(deviceId, streamId, width, capturedAt, variantKey);
 		if (cached !== void 0) return {
 			bytes: cached,
 			width
@@ -1246,7 +1304,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		const full = Buffer.from(image.base64, "base64");
 		try {
 			const resized = await this.resize(full, width);
-			this.variants.set(deviceId, streamId, width, capturedAt, resized);
+			this.variants.set(deviceId, streamId, width, capturedAt, resized, variantKey);
 			if (prefs.snapshotDebug) this.ctx.logger.info("snapshot: thumbnail derived", {
 				tags: { deviceId },
 				meta: {
@@ -1285,6 +1343,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 		this.cache.clear();
 		this.variants.clear();
+		this.stateFrames.clear();
+		this.wakingDevices.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -1317,18 +1377,16 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY) {
+	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY, resolutionMeta) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
 		const deviceName = meta?.name;
-		const isBatteryDevice = meta?.isBattery ?? false;
 		const log = this.ctx.logger.withTags({
 			deviceId,
 			...deviceName ? { deviceName } : {}
 		});
 		const now = Date.now();
-		if (meta?.disabled === true) return await this.courtesyImage(deviceId, "disabled", deviceName);
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
 		const rawPref = prefs.snapshotStreamId;
 		const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
@@ -1337,6 +1395,24 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
 		const hit = this.cache.get(deviceId, effectiveStreamId);
+		const state = await this.resolveSnapshotState(deviceId, meta);
+		const isBatteryDevice = state.isBattery;
+		if (resolutionMeta) {
+			resolutionMeta.isBattery = isBatteryDevice;
+			delete resolutionMeta.stateReason;
+		}
+		if (state.reason !== void 0 && (!force || state.reason === "disabled" || state.reason === "unreachable" || state.reason === "waking")) {
+			if (resolutionMeta) resolutionMeta.stateReason = state.reason;
+			log.debug("snapshot: camera state overrides raw cache", {
+				tags: { deviceId },
+				meta: {
+					reason: state.reason,
+					hasCache: hit !== void 0,
+					ageMs: hit ? now - hit.ts : null
+				}
+			});
+			return await this.stateImage(deviceId, state.reason, deviceName, hit);
+		}
 		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3));
 		const decision = decideSnapshotServe({
 			now,
@@ -1355,17 +1431,6 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			});
 			return hit ? hit.data : null;
 		}
-		if (!force && isBatteryDevice && await this.isDeviceSleeping(deviceId)) {
-			log.debug("snapshot: sleeping battery cam and no force — serving cache, not capturing", {
-				tags: { deviceId },
-				meta: {
-					hasCache: hit !== void 0,
-					ageMs: hit ? now - hit.ts : null
-				}
-			});
-			if (hit) return hit.data;
-			return await this.courtesyImage(deviceId, "sleeping", deviceName);
-		}
 		const flightKey = `${deviceId}:${effectiveStreamId ?? "auto"}`;
 		const flight = this.captureFlight.run(flightKey, () => this.captureFresh({
 			deviceId,
@@ -1484,6 +1549,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			if (native) {
 				const result = await this.nativePool.run(() => native.getSnapshot(input));
 				if (result) {
+					this.stateFrames.delete(deviceId);
 					this.cache.set(deviceId, effectiveStreamId, {
 						data: result,
 						ts: now,
@@ -1518,6 +1584,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		if (!(isBatteryDevice && nativeAbsent && !await this.hasStreamingBrokerForDevice(deviceId))) try {
 			const fallback = await this.grabFrameFromBroker(deviceId, effectiveStreamId);
 			if (fallback) {
+				this.stateFrames.delete(deviceId);
 				this.cache.set(deviceId, effectiveStreamId, {
 					data: fallback,
 					ts: now,
@@ -1671,6 +1738,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	dropDeviceCaches(deviceId) {
 		this.cache.deleteDevice(deviceId);
 		this.variants.deleteDevice(deviceId);
+		this.stateFrames.delete(deviceId);
+		this.wakingDevices.delete(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 	}
 	/**
@@ -1708,38 +1777,64 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 	}
 	/**
-	* Sleep state from the device-state MIRROR, not from a cap round-trip.
+	* Resolve the state that must be visible on a snapshot.
 	*
-	* `fetchDevice(id).state.battery` is a `SliceHandle` over the hub's
-	* runtime-state mirror: a local read, no RPC, no failure branch to get
-	* wrong. It is the same mirror that feeds the battery badge elsewhere
-	* in the UI, so if the operator can see "sleeping" on screen, this
-	* sees it too. (Both spec harnesses already model exactly this wiring
-	* — like the orphaned doc comment above, it outlived the gate it was
-	* built for.)
+	* Uses the same two canonical sources as wake-on-play:
+	*  1. `deviceManager.getDevice` for the registry's BatteryOperated feature;
+	*  2. `deviceState.getCapSlice('battery')` for the durable runtime mirror.
 	*
-	* `undefined` slice → the device has no battery state we know of →
-	* treated as awake. The caller has already established the device is
-	* battery-operated from its feature flags, so this only decides
-	* WHETHER IT IS ASLEEP, never whether it has a battery.
+	* A valid battery slice is itself positive evidence that the device is
+	* battery-operated. That closes the field failure where "Baby monitor" had a
+	* sleeping battery slice but a stale persisted feature projection, so the
+	* snapshot wrapper classified it as mains and a Viewer thumbnail logged in
+	* to the sleeping camera. The reverse is deliberately not guessed: no
+	* feature + no valid slice remains a mains/unknown camera and follows the
+	* ordinary capture path.
 	*
-	* Only consulted on the path that would otherwise CAPTURE — a fresh
-	* cache hit returns before we get here.
+	* Once battery-operated is established, a missing slice fails safe toward
+	* `sleeping` through the shared `deriveBatteryPresence` function. This avoids
+	* a background wake without inventing an `unreachable` fault.
 	*/
-	async isDeviceSleeping(deviceId) {
+	async resolveSnapshotState(deviceId, meta) {
+		if (meta?.disabled === true) return {
+			isBattery: meta.isBattery,
+			reason: "disabled"
+		};
+		const waking = this.isDeviceWaking(deviceId);
+		let batteryStatus = null;
 		try {
-			const handle = (await this.ctx.fetchDevice(deviceId)).state.battery;
-			await handle.refresh();
-			const raw = handle.value;
+			const raw = await this.ctx.api.deviceState.getCapSlice.query({
+				deviceId,
+				capName: require_dist.batteryCapability.name
+			});
 			const parsed = require_dist.BatteryStatusSchema.safeParse(raw);
-			return parsed.success && parsed.data.sleeping;
+			if (parsed.success) batteryStatus = parsed.data;
 		} catch (err) {
-			this.ctx.logger.warn("snapshot: battery mirror read failed — assuming awake", {
+			this.ctx.logger.debug("snapshot: battery runtime-state read failed", {
 				tags: { deviceId },
 				meta: { error: require_dist.errMsg(err) }
 			});
-			return false;
 		}
+		if (!(meta?.isBattery === true || batteryStatus !== null || waking)) return { isBattery: false };
+		if (waking) return {
+			isBattery: true,
+			reason: "waking"
+		};
+		const presence = require_dist.deriveBatteryPresence({
+			status: batteryStatus,
+			nowMs: Date.now()
+		});
+		return presence === "awake" ? { isBattery: true } : {
+			isBattery: true,
+			reason: presence
+		};
+	}
+	isDeviceWaking(deviceId) {
+		const startedAt = this.wakingDevices.get(deviceId);
+		if (startedAt === void 0) return false;
+		if (Date.now() - startedAt <= SNAPSHOT_WAKING_TTL_MS) return true;
+		this.wakingDevices.delete(deviceId);
+		return false;
 	}
 	/**
 	* True when at least one of the device's brokers is actively
@@ -1915,12 +2010,48 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		};
 	}
 	/**
+	* Render a state-labelled answer. A cached real frame is the background, not
+	* the answer by itself; if it cannot be decoded, fall back to the generated
+	* courtesy background rather than leaking an unlabelled stale frame.
+	*/
+	async stateImage(deviceId, reason, deviceName, hit) {
+		const resolvedName = deviceName ?? `#${String(deviceId)}`;
+		if (!hit) return await this.courtesyImage(deviceId, reason, resolvedName);
+		const key = `${String(hit.ts)}:${hit.streamId ?? "auto"}:${reason}:${resolvedName}`;
+		const deviceFrames = this.stateFrames.get(deviceId) ?? /* @__PURE__ */ new Map();
+		this.stateFrames.set(deviceId, deviceFrames);
+		const cached = deviceFrames.get(key);
+		if (cached !== void 0) return {
+			base64: cached.toString("base64"),
+			contentType: "image/jpeg"
+		};
+		try {
+			const bytes = await renderCourtesyOverlayJpeg(Buffer.from(hit.data.base64, "base64"), {
+				deviceName: resolvedName,
+				reason
+			});
+			deviceFrames.set(key, bytes);
+			return {
+				base64: bytes.toString("base64"),
+				contentType: "image/jpeg"
+			};
+		} catch (err) {
+			this.ctx.logger.warn("snapshot: state overlay failed — using generated courtesy background", {
+				tags: { deviceId },
+				meta: {
+					reason,
+					error: require_dist.errMsg(err)
+				}
+			});
+			return await this.courtesyImage(deviceId, reason, resolvedName);
+		}
+	}
+	/**
 	* Single-trip device lookup against device-manager. Returns the
-	* fields the wrapper actually consults — name (logging) + battery
-	* flag (cache window + broker-fallback gate). Sourced from the
-	* device-manager registry rather than the battery cap so the answer
-	* survives a momentarily-unreachable provider (the very condition
-	* we're trying to be resilient to).
+	* stable registry fields the wrapper consults. Battery classification is
+	* completed by `resolveSnapshotState` from this feature flag PLUS the
+	* canonical runtime-state mirror, so a stale persisted feature projection
+	* cannot authorize a snapshot dial against a known sleeping battery camera.
 	*
 	* Logged at debug + null return on failure: every call site already
 	* has a sensible fallback path (cache hit, conservative default, …),
@@ -1952,7 +2083,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	}
 	/** Settings-UI helper — battery flag drives the default max-age in the field description. */
 	async isDeviceBattery(deviceId) {
-		return (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false;
+		const meta = await this.lookupDeviceMeta(deviceId);
+		return (await this.resolveSnapshotState(deviceId, meta)).isBattery;
 	}
 	/**
 	* Feeds the settings-UI stream picker. Pinned to the ingest owner via