@camstack/system 1.2.93 → 1.2.94

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { Lt as nodePin, St as DeviceFeature, Wt as EventCategory, _t as errMsg, i as BatteryStatusSchema, j as deriveBatteryPresence, lt as snapshotCapability, pt as streamQualityLabel, vt as BaseAddon, w as bareAddonId, wt as DeviceType } from "../../dist-F1XDQDE1.mjs";
+import { Ct as DeviceFeature, Gt as EventCategory, M as deriveBatteryPresence, Rt as nodePin, T as batteryCapability, Tt as DeviceType, i as BatteryStatusSchema, mt as streamQualityLabel, ut as snapshotCapability, vt as errMsg, w as bareAddonId, yt as BaseAddon } from "../../dist-COd223t-.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { signExpiringUrl, verifyExpiringUrl } from "@camstack/types/node";
@@ -249,7 +249,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
@@ -260,9 +260,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`
@@ -294,6 +294,7 @@ function courtesyLabel(reason) {
 		case "offline": return "Offline";
 		case "sleeping": return "Sleeping";
 		case "unreachable": return "Unreachable";
+		case "waking": return "Waking";
 	}
 }
 /**
@@ -305,6 +306,7 @@ function courtesyBackground(reason) {
 		case "disabled": return "#2b2b31";
 		case "offline": return "#3a2b2b";
 		case "sleeping": return "#232b3a";
+		case "waking": return "#243247";
 		case "unreachable": return "#3a2b2b";
 	}
 }
@@ -320,15 +322,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>`
@@ -350,6 +364,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 sharp(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 sharp(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
 /**
@@ -543,7 +575,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
@@ -554,6 +587,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("-")}"`;
 }
 /**
@@ -584,7 +618,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, {
@@ -615,7 +650,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) {
@@ -718,8 +754,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
@@ -730,17 +766,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
@@ -781,6 +817,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". */
@@ -825,9 +864,14 @@ var SnapshotAddon = class SnapshotAddon extends 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
@@ -899,6 +943,12 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			const deviceId = event.data.deviceId;
 			if (typeof deviceId === "number") this.evictRemovedDevice(deviceId, "device-unregistered");
 		});
+		this.subscribe({ category: EventCategory.BatteryOnWakeStarted }, (event) => {
+			this.wakingDevices.set(event.data.deviceId, Date.now());
+		});
+		this.subscribe({ category: EventCategory.BatteryOnStatusChanged }, (event) => {
+			this.wakingDevices.delete(event.data.deviceId);
+		});
 		await this.serveMediaDataPlane();
 		await this.ensureLinkDataPlane();
 		return [{
@@ -1160,13 +1210,12 @@ var SnapshotAddon = class SnapshotAddon extends 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;
 		}
@@ -1180,28 +1229,31 @@ var SnapshotAddon = class SnapshotAddon extends 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
 		};
 	}
@@ -1217,24 +1269,28 @@ var SnapshotAddon = class SnapshotAddon extends 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
@@ -1242,7 +1298,7 @@ var SnapshotAddon = class SnapshotAddon extends 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: {
@@ -1281,6 +1337,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}
 		this.cache.clear();
 		this.variants.clear();
+		this.stateFrames.clear();
+		this.wakingDevices.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -1313,18 +1371,16 @@ var SnapshotAddon = class SnapshotAddon extends 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);
@@ -1333,6 +1389,24 @@ var SnapshotAddon = class SnapshotAddon extends 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,
@@ -1351,19 +1425,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			});
 			return hit ? hit.data : null;
 		}
-		const presence = isBatteryDevice ? await this.readBatteryPresence(deviceId) : "awake";
-		if (!force && presence !== "awake") {
-			log.debug("snapshot: battery cam not awake and no force — serving cache, not capturing", {
-				tags: { deviceId },
-				meta: {
-					presence,
-					hasCache: hit !== void 0,
-					ageMs: hit ? now - hit.ts : null
-				}
-			});
-			if (hit) return hit.data;
-			return await this.courtesyImage(deviceId, presence, deviceName);
-		}
 		const flightKey = `${deviceId}:${effectiveStreamId ?? "auto"}`;
 		const flight = this.captureFlight.run(flightKey, () => this.captureFresh({
 			deviceId,
@@ -1482,6 +1543,7 @@ var SnapshotAddon = class SnapshotAddon extends 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,
@@ -1516,6 +1578,7 @@ var SnapshotAddon = class SnapshotAddon extends 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,
@@ -1669,6 +1732,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	dropDeviceCaches(deviceId) {
 		this.cache.deleteDevice(deviceId);
 		this.variants.deleteDevice(deviceId);
+		this.stateFrames.delete(deviceId);
+		this.wakingDevices.delete(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 	}
 	/**
@@ -1706,55 +1771,64 @@ var SnapshotAddon = class SnapshotAddon extends 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) {
-		return await this.readBatteryPresence(deviceId) !== "awake";
-	}
-	/**
-	* The device's three-valued battery presence (D173) — `awake`, `sleeping`,
-	* or `unreachable`. Same mirror read as the sleep gate, one derivation
-	* (`deriveBatteryPresence`) so this layer cannot disagree with the badge or
-	* the stream error about what a camera is doing.
-	*
-	* A failed read answers `awake`: unknown must never become a fault badge,
-	* and "assume awake" is the pre-existing, deliberately conservative failure
-	* direction of the gate this replaces.
-	*/
-	async readBatteryPresence(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 parsed = BatteryStatusSchema.safeParse(raw);
-			if (!parsed.success) return "awake";
-			return deriveBatteryPresence({
-				status: parsed.data,
-				nowMs: Date.now()
+			const raw = await this.ctx.api.deviceState.getCapSlice.query({
+				deviceId,
+				capName: batteryCapability.name
 			});
+			const parsed = BatteryStatusSchema.safeParse(raw);
+			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: errMsg(err) }
 			});
-			return "awake";
 		}
+		if (!(meta?.isBattery === true || batteryStatus !== null || waking)) return { isBattery: false };
+		if (waking) return {
+			isBattery: true,
+			reason: "waking"
+		};
+		const presence = 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
@@ -1930,12 +2004,48 @@ var SnapshotAddon = class SnapshotAddon extends 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: 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, …),
@@ -1967,7 +2077,8 @@ var SnapshotAddon = class SnapshotAddon extends 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

package/dist/builtins/snapshot/snapshot-courtesy.d.ts

@@ -9,7 +9,7 @@
  * first is how a dead camera stayed green for 30 hours. The two are separated
  * by `deriveBatteryPresence`, never by a caller's own guess.
  */
-export type CourtesyReason = 'disabled' | 'offline' | 'sleeping' | 'unreachable';
+export type CourtesyReason = 'disabled' | 'offline' | 'sleeping' | 'unreachable' | 'waking';
 /** Default tile size when the caller asks for no particular width. */
 export declare const COURTESY_DEFAULT_WIDTH = 640;
 /** The word the frame carries. Deliberately the operator's vocabulary. */
@@ -35,6 +35,11 @@ export interface CourtesyFrameSpec {
  * frame read the same, with a floor so a thumbnail stays legible.
  */
 export declare function buildCourtesySvg(spec: CourtesyFrameSpec): string;
+/**
+ * The same state treatment as a courtesy frame, but translucent so the last
+ * real camera frame remains visible underneath it.
+ */
+export declare function buildCourtesyOverlaySvg(spec: CourtesyFrameSpec): string;
 /** Cache key — a courtesy frame is a pure function of these four. */
 export declare function courtesyCacheKey(spec: CourtesyFrameSpec): string;
 /**
@@ -44,3 +49,10 @@ export declare function courtesyCacheKey(spec: CourtesyFrameSpec): string;
  * does, so a broken courtesy path is never mistaken for a broken camera.
  */
 export declare function renderCourtesyJpeg(spec: CourtesyFrameSpec): Promise<Buffer>;
+/**
+ * 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.
+ */
+export declare function renderCourtesyOverlayJpeg(background: Buffer, spec: Pick<CourtesyFrameSpec, 'deviceName' | 'reason'>): Promise<Buffer>;

package/dist/builtins/snapshot/snapshot-media-handler.d.ts

@@ -9,6 +9,8 @@ export interface SnapshotMedia {
     readonly capturedAt: number;
     /** Effective per-device max cache age (seconds) → `Cache-Control: max-age`. */
     readonly maxAgeS: number;
+    /** State treatment painted over the capture (sleeping, waking, …). */
+    readonly variantKey?: string | undefined;
     /**
      * The width the returned BYTES are actually at, or undefined when they are the
      * frame as captured.
@@ -27,6 +29,8 @@ export interface SnapshotPeek {
     readonly capturedAt: number;
     /** Effective per-device max cache age (seconds). */
     readonly maxAgeS: number;
+    /** State treatment that would be painted over this capture. */
+    readonly variantKey?: string | undefined;
 }
 export interface SnapshotMediaHandlerDeps {
     /**
@@ -91,7 +95,8 @@ export declare function parseSnapshotMediaRequest(url: string): SnapshotMediaReq
  * 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
@@ -106,6 +111,7 @@ export interface SnapshotVariantIdentity {
     readonly deviceId: number;
     readonly streamId: string | undefined;
     readonly width: number | undefined;
+    readonly variantKey?: string | undefined;
 }
 /**
  * Create a data-plane handler that serves per-device snapshots as JPEG images.

package/dist/builtins/snapshot/snapshot-resize.d.ts

@@ -60,8 +60,8 @@ export declare const RESIZE_TIMEOUT_MS = 10000;
  */
 export declare function resizeJpeg(bytes: Buffer, width: number, timeoutMs?: number): Promise<Buffer>;
 /**
- * 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
@@ -75,8 +75,8 @@ export declare class SnapshotVariantCache {
     private static key;
     /** The variant for this exact frame, or undefined when it is missing or was
      *  derived from an older capture. */
-    get(deviceId: number, streamId: string | undefined, width: number, sourceTs: number): Buffer | undefined;
-    set(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, bytes: Buffer): void;
+    get(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, variantKey?: string): Buffer | undefined;
+    set(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, bytes: Buffer, variantKey?: string): void;
     deleteDevice(deviceId: number): void;
     clear(): void;
 }