@camstack/system 1.2.62 → 1.2.64

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { Mt as nodePin, _t as DeviceFeature, ft as errMsg, i as BatteryStatusSchema, ot as streamQualityLabel, pt as BaseAddon, rt as snapshotCapability, x as bareAddonId, yt as DeviceType } from "../../dist-DnKpFaP1.mjs";
+import { At as nodePin, _t as DeviceType, dt as BaseAddon, ht as DeviceFeature, i as BatteryStatusSchema, ot as streamQualityLabel, rt as snapshotCapability, ut as errMsg, x as bareAddonId } from "../../dist-CMb7aKS0.mjs";
 import { execFile, spawn } from "node:child_process";
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
@@ -261,10 +261,10 @@ function parseSnapshotMediaRequest(url) {
 * `snapshot.getSnapshotOverview` advertises still matches the frame nobody
 * asked to resize.
 */
-function snapshotEtag(request, capturedAt) {
-	const parts = [`${String(request.deviceId)}-${String(capturedAt)}`];
-	if (request.streamId !== void 0) parts.push(`s${request.streamId}`);
-	if (request.width !== void 0) parts.push(`w${String(request.width)}`);
+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)}`);
 	return `"${parts.join("-")}"`;
 }
 /**
@@ -283,6 +283,29 @@ function createSnapshotMediaHandler(deps) {
 			res.writeHead(404).end();
 			return;
 		}
+		const inm = req.headers["if-none-match"];
+		if (typeof inm === "string" && !parsed.force && deps.peekFresh !== void 0) {
+			let peeked = null;
+			try {
+				peeked = await deps.peekFresh(parsed.deviceId, parsed.streamId);
+			} catch {
+				peeked = null;
+			}
+			if (peeked !== null) {
+				const peekedEtag = snapshotEtag({
+					deviceId: parsed.deviceId,
+					streamId: parsed.streamId,
+					width: parsed.width
+				}, peeked.capturedAt);
+				if (inm === peekedEtag) {
+					res.writeHead(304, {
+						etag: peekedEtag,
+						"cache-control": `private, max-age=${Math.max(0, Math.floor(peeked.maxAgeS))}`
+					}).end();
+					return;
+				}
+			}
+		}
 		let media;
 		try {
 			media = await deps.getMedia(parsed.deviceId, parsed.streamId, parsed.force, parsed.width);
@@ -300,9 +323,13 @@ function createSnapshotMediaHandler(deps) {
 			res.writeHead(404).end();
 			return;
 		}
-		const etag = snapshotEtag(parsed, media.capturedAt);
+		const etag = snapshotEtag({
+			deviceId: parsed.deviceId,
+			streamId: parsed.streamId,
+			width: "servedWidth" in media ? media.servedWidth : parsed.width
+		}, media.capturedAt);
 		const cacheControl = `private, max-age=${Math.max(0, Math.floor(media.maxAgeS))}`;
-		if (req.headers["if-none-match"] === etag) {
+		if (inm === etag) {
 			res.writeHead(304, {
 				etag,
 				"cache-control": cacheControl
@@ -325,7 +352,7 @@ function createSnapshotMediaHandler(deps) {
 *  per-device preference decides what it captures, and conflating it with an
 *  explicit request is how the original bug read. */
 var AUTO = "auto";
-function keyOf(deviceId, streamId) {
+function keyOf$1(deviceId, streamId) {
 	return `${deviceId}:${streamId ?? AUTO}`;
 }
 var SnapshotCache = class {
@@ -333,10 +360,10 @@ var SnapshotCache = class {
 	/** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
 	keysByDevice = /* @__PURE__ */ new Map();
 	get(deviceId, streamId) {
-		return this.byKey.get(keyOf(deviceId, streamId));
+		return this.byKey.get(keyOf$1(deviceId, streamId));
 	}
 	set(deviceId, streamId, entry) {
-		const key = keyOf(deviceId, streamId);
+		const key = keyOf$1(deviceId, streamId);
 		this.byKey.set(key, entry);
 		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
 		keys.add(key);
@@ -496,6 +523,123 @@ var SnapshotVariantCache = class SnapshotVariantCache {
 	}
 };
 //#endregion
+//#region src/builtins/snapshot/snapshot-keep-warm.ts
+/**
+* Subscription bookkeeping for the snapshot keep-warm loop.
+*
+* The snapshot cache has exactly one writer — a successful capture — and every
+* capture is triggered by somebody asking. Nothing refreshes a frame on its own,
+* so with no viewer open every thumbnail in the system is as old as the last
+* time somebody looked. Measured on the live hub: 15 of 16 cameras cached, all
+* captured in one 55 ms burst, all 10 minutes old and not moving.
+*
+* The fix is a warm loop — but a blind one would dial 16 cameras forever for
+* nobody. This module holds the thing that makes it bounded: a warm tick only
+* touches cameras SOMEBODY IS LOOKING AT, and "looking at" is inferred from the
+* requests themselves. One data-plane request for a device makes it an observer
+* for {@link WARM_WINDOW_MS}; when the last viewer closes, the loop goes quiet
+* on its own after that window and costs exactly nothing.
+*
+* Pure and side-effect-free (no timer, no I/O, `now` injected) — the addon owns
+* the timer, this owns the decision. Unit-tested in
+* `__tests__/snapshot-keep-warm.spec.ts`.
+*/
+/**
+* How often the warm loop runs. Chosen so a tile is perceptibly fresh while
+* watched; it is also the single biggest cost lever in the design (16 cameras ×
+* 12 ticks/min against a pool of 3 ffmpeg). A chained timer, not `setInterval` —
+* the next tick is scheduled only after the previous one settles, so a slow
+* fleet cannot stack ticks on top of each other.
+*/
+var WARM_INTERVAL_MS = 5e3;
+/**
+* How long one request keeps a device warm. Two minutes of inertia after the
+* last observer goes away: long enough that flipping between screens (or a
+* phone locking briefly) does not go cold, short enough that a closed app stops
+* costing captures well before anyone notices.
+*/
+var WARM_WINDOW_MS = 12e4;
+function keyOf(deviceId, streamId) {
+	return `${deviceId}:${streamId ?? "auto"}`;
+}
+/**
+* Who is being watched right now, and at what sizes.
+*
+* `note` on every data-plane request; `active` on every warm tick. `active`
+* PRUNES as it walks rather than merely filtering — the map is fed by request
+* traffic, so a filter-only read would leave every device ever requested in
+* memory for the life of the process.
+*/
+var SnapshotSubscriptions = class {
+	entries = /* @__PURE__ */ new Map();
+	/** Record that somebody asked for this (device, stream) — at `width`, when the
+	*  request carried one. */
+	note(deviceId, streamId, width, nowMs) {
+		const key = keyOf(deviceId, streamId);
+		const existing = this.entries.get(key);
+		if (existing) {
+			existing.lastRequestedAt = nowMs;
+			if (width !== void 0) existing.widths.set(width, nowMs);
+			this.entries.delete(key);
+			this.entries.set(key, existing);
+			return;
+		}
+		this.entries.set(key, {
+			deviceId,
+			streamId,
+			lastRequestedAt: nowMs,
+			widths: width === void 0 ? /* @__PURE__ */ new Map() : new Map([[width, nowMs]])
+		});
+		while (this.entries.size > 64) {
+			const oldest = this.entries.keys().next();
+			if (oldest.done === true) break;
+			this.entries.delete(oldest.value);
+		}
+	}
+	/**
+	* Refresh the window on subscriptions that ALREADY exist. Never creates one.
+	*
+	* This is what stops the design deadlocking, and the deadlock was measured on
+	* the live hub before it existed. The client re-requests an image only when
+	* the frame identity changes, and the identity changes only because the warm
+	* loop captured — so 120 s after the last image request the subscription
+	* expired, warming stopped, the identity froze, the client never asked again,
+	* and the tile was stuck. Ages went 13 s → 49.7 s at exactly t+120 s.
+	*
+	* The client's `getSnapshotOverview` poll is the heartbeat: asking "what is
+	* the state of these cameras" IS the statement that somebody is looking. It
+	* deliberately cannot CREATE a subscription, because that poll is app-wide —
+	* if it did, opening the app would warm every camera on the install, which is
+	* the blind poll this whole design avoids. Only a rendered surface subscribes.
+	*/
+	renew(deviceIds, nowMs) {
+		for (const deviceId of deviceIds) for (const entry of this.entries.values()) if (entry.deviceId === deviceId) entry.lastRequestedAt = nowMs;
+	}
+	/** The (device, stream) pairs still inside the warm window, dropping the rest. */
+	active(nowMs, windowMs = WARM_WINDOW_MS) {
+		const targets = [];
+		for (const [key, entry] of this.entries) {
+			if (nowMs - entry.lastRequestedAt >= windowMs) {
+				this.entries.delete(key);
+				continue;
+			}
+			for (const [width, at] of entry.widths) if (nowMs - at >= windowMs) entry.widths.delete(width);
+			targets.push({
+				deviceId: entry.deviceId,
+				streamId: entry.streamId,
+				widths: [...entry.widths.keys()].sort((a, b) => a - b)
+			});
+		}
+		return targets;
+	}
+	get size() {
+		return this.entries.size;
+	}
+	clear() {
+		this.entries.clear();
+	}
+};
+//#endregion
 //#region src/builtins/snapshot/snapshot.addon.ts
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
@@ -562,8 +706,28 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* strictly-additive delivery path). Disposed on shutdown.
 	*/
 	mediaDataPlane = null;
-	constructor() {
+	/**
+	* Who is being looked at, inferred from data-plane traffic. The keep-warm
+	* loop's entire bound — see `snapshot-keep-warm.ts`.
+	*/
+	subscriptions = new SnapshotSubscriptions();
+	/** Chained warm-tick timer (never `setInterval` — see `scheduleWarmTick`). */
+	warmTimer = null;
+	/** Set while a warm tick is running so ticks can never stack. */
+	warmTickRunning = false;
+	/** Flipped on shutdown so an in-flight tick does not reschedule itself. */
+	stopped = false;
+	/**
+	* How a full frame becomes a card-sized one. Defaults to the real ffmpeg
+	* resize; injectable so the wrapper's own logic is testable without spawning a
+	* process for every fixture. `JpegResizer` was declared for exactly this and
+	* had no injector — which is why the resize-failure path had never been
+	* exercised anywhere but production.
+	*/
+	resize;
+	constructor(resize = resizeJpeg) {
 		super({ staleTtlMs: 6e4 });
+		this.resize = resize;
 	}
 	async onInitialize() {
 		this.ctx.logger.info("Snapshot wrapper initialized");
@@ -577,6 +741,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			getSnapshotOverview: (input) => this.getSnapshotOverview(input)
 		};
 		await this.serveMediaDataPlane();
+		this.scheduleWarmTick();
 		return [{
 			capability: snapshotCapability,
 			provider
@@ -592,7 +757,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* base64 path.
 	*/
 	async serveMediaDataPlane() {
-		const handler = createSnapshotMediaHandler({ getMedia: (deviceId, streamId, force, width) => this.resolveSnapshotMedia(deviceId, streamId, force, width) });
+		const handler = createSnapshotMediaHandler({
+			getMedia: (deviceId, streamId, force, width) => this.resolveSnapshotMedia(deviceId, streamId, force, width),
+			peekFresh: (deviceId, streamId) => this.peekFreshFrame(deviceId, streamId)
+		});
 		try {
 			this.mediaDataPlane = await this.ctx.dataPlane?.serve({
 				prefix: "media",
@@ -614,6 +782,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
 	*/
 	async resolveSnapshotMedia(deviceId, streamId, force, width) {
+		this.subscriptions.note(deviceId, streamId, width, Date.now());
 		const image = await this.getSnapshot({
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
@@ -623,14 +792,128 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		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;
+		if (width === void 0) return {
+			bytes: Buffer.from(image.base64, "base64"),
+			contentType: image.contentType,
+			capturedAt,
+			maxAgeS: effectiveMaxAgeS(prefs, isBattery),
+			servedWidth: void 0
+		};
+		const thumb = await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs);
 		return {
-			bytes: width === void 0 ? Buffer.from(image.base64, "base64") : await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs),
+			bytes: thumb.bytes,
 			contentType: image.contentType,
 			capturedAt,
-			maxAgeS: effectiveMaxAgeS(prefs, isBattery)
+			maxAgeS: effectiveMaxAgeS(prefs, isBattery),
+			servedWidth: thumb.width
+		};
+	}
+	/**
+	* Cache-only freshness peek for the data-plane's conditional-GET fast path.
+	* Never captures, never resizes, never dials anything: a cached frame that is
+	* still inside its per-device max-age, or null.
+	*
+	* Returning null for a STALE entry is the important half. A 304 there would
+	* pin the tile to the old frame for as long as the client kept revalidating,
+	* which is the exact staleness this change exists to remove.
+	*/
+	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);
+		if (Date.now() - hit.ts >= maxAgeS * 1e3) return null;
+		return {
+			capturedAt: hit.ts,
+			maxAgeS
 		};
 	}
 	/**
+	* Schedule the next warm tick. A CHAINED timer, not `setInterval`: the next
+	* tick is armed only after the previous one settles, so a fleet that is slower
+	* than the interval degrades to "as fast as it can" instead of stacking ticks
+	* on top of each other and exhausting the ffmpeg pool.
+	*
+	* `unref` so the loop never holds the process open.
+	*/
+	scheduleWarmTick() {
+		if (this.stopped) return;
+		this.warmTimer = setTimeout(() => {
+			this.runWarmTick().finally(() => {
+				this.scheduleWarmTick();
+			});
+		}, WARM_INTERVAL_MS);
+		this.warmTimer.unref?.();
+	}
+	/**
+	* Refresh the cache for every camera somebody is currently looking at.
+	*
+	* Deliberately NOT a blind poll of the whole fleet: with nobody watching this
+	* walks an empty list and costs nothing, which is the entire difference
+	* between this and a background poller.
+	*
+	* Battery cameras need no special case here and must not get one. A warm tick
+	* is a plain non-forced `getSnapshot`, so it meets the two gates that already
+	* exist — the 3600 s battery max-age (which makes the tick a cache hit) and
+	* the sleeping-battery gate (which refuses to capture without `force`). A
+	* second battery check here would be a rule that disagrees with the authority
+	* that already owns it.
+	*/
+	async runWarmTick() {
+		if (this.warmTickRunning || this.stopped) return;
+		this.warmTickRunning = true;
+		const logger = this.ctx.logger;
+		try {
+			const targets = this.subscriptions.active(Date.now());
+			if (targets.length === 0) return;
+			const failed = (await Promise.allSettled(targets.map((t) => this.warmOne(t, logger)))).filter((r) => r.status === "rejected").length;
+			logger.debug("snapshot: keep-warm tick", { meta: {
+				watched: targets.length,
+				failed
+			} });
+		} catch (err) {
+			logger.warn("snapshot: keep-warm tick failed", { meta: { error: errMsg(err) } });
+		} finally {
+			this.warmTickRunning = false;
+		}
+	}
+	/**
+	* Warm one (device, stream): refresh the frame, then pre-derive the widths
+	* that were actually requested.
+	*
+	* Deriving the variants matters as much as the capture. Warming only the full
+	* frame would leave every grid tile still paying an ffmpeg resize on the
+	* request path — the cache would be fresh and the tile would still be slow.
+	*/
+	async warmOne(target, logger) {
+		const work = this.warmOneUnbounded(target, logger);
+		work.catch(() => void 0);
+		if (!(await raceForResult(work, 5e3)).settled) logger.debug("snapshot: keep-warm still in flight past the tick — leaving it to land", { tags: { deviceId: target.deviceId } });
+	}
+	async warmOneUnbounded(target, logger) {
+		const { deviceId, streamId, widths } = target;
+		try {
+			if (this.stopped) return;
+			const image = await this.getSnapshot({
+				deviceId,
+				...streamId !== void 0 ? { streamId } : {},
+				force: false
+			}, WARM_INTERVAL_MS);
+			if (!image) return;
+			const capturedAt = this.cache.get(deviceId, streamId)?.ts;
+			if (capturedAt === void 0) return;
+			const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
+			for (const width of widths) {
+				if (this.stopped) return;
+				await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs);
+			}
+		} catch (err) {
+			logger.debug("snapshot: keep-warm failed for device", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+		}
+	}
+	/**
 	* The frame at a card-sized width, derived once per (device, stream, width)
 	* per capture.
 	*
@@ -641,10 +924,13 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	async thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs) {
 		const cached = this.variants.get(deviceId, streamId, width, capturedAt);
-		if (cached !== void 0) return cached;
+		if (cached !== void 0) return {
+			bytes: cached,
+			width
+		};
 		const full = Buffer.from(image.base64, "base64");
 		try {
-			const resized = await resizeJpeg(full, width);
+			const resized = await this.resize(full, width);
 			this.variants.set(deviceId, streamId, width, capturedAt, resized);
 			if (prefs.snapshotDebug) this.ctx.logger.info("snapshot: thumbnail derived", {
 				tags: { deviceId },
@@ -654,7 +940,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					thumbBytes: resized.length
 				}
 			});
-			return resized;
+			return {
+				bytes: resized,
+				width
+			};
 		} catch (err) {
 			this.ctx.logger.warn("snapshot: resize failed — serving the full frame", {
 				tags: { deviceId },
@@ -664,10 +953,19 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					error: errMsg(err)
 				}
 			});
-			return full;
+			return {
+				bytes: full,
+				width: void 0
+			};
 		}
 	}
 	async onShutdown() {
+		this.stopped = true;
+		if (this.warmTimer !== null) {
+			clearTimeout(this.warmTimer);
+			this.warmTimer = null;
+		}
+		this.subscriptions.clear();
 		if (this.mediaDataPlane) {
 			await this.mediaDataPlane.dispose().catch(() => void 0);
 			this.mediaDataPlane = null;
@@ -706,7 +1004,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input) {
+	async getSnapshot(input, warmAheadMs = 0) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -725,7 +1023,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
 		const hit = this.cache.get(deviceId, effectiveStreamId);
-		const effectiveMaxAgeMs = effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3;
+		const effectiveMaxAgeMs = Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs);
 		const decision = decideSnapshotServe({
 			now,
 			cachedAt: hit?.ts ?? null,
@@ -1087,6 +1385,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	getSnapshotOverview(input) {
 		const now = Date.now();
+		this.subscriptions.renew(input.deviceIds, now);
 		const rows = input.deviceIds.map((deviceId) => {
 			const hit = this.cache.latest(deviceId);
 			if (!hit) return {

package/dist/builtins/snapshot/snapshot-keep-warm.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Subscription bookkeeping for the snapshot keep-warm loop.
+ *
+ * The snapshot cache has exactly one writer — a successful capture — and every
+ * capture is triggered by somebody asking. Nothing refreshes a frame on its own,
+ * so with no viewer open every thumbnail in the system is as old as the last
+ * time somebody looked. Measured on the live hub: 15 of 16 cameras cached, all
+ * captured in one 55 ms burst, all 10 minutes old and not moving.
+ *
+ * The fix is a warm loop — but a blind one would dial 16 cameras forever for
+ * nobody. This module holds the thing that makes it bounded: a warm tick only
+ * touches cameras SOMEBODY IS LOOKING AT, and "looking at" is inferred from the
+ * requests themselves. One data-plane request for a device makes it an observer
+ * for {@link WARM_WINDOW_MS}; when the last viewer closes, the loop goes quiet
+ * on its own after that window and costs exactly nothing.
+ *
+ * Pure and side-effect-free (no timer, no I/O, `now` injected) — the addon owns
+ * the timer, this owns the decision. Unit-tested in
+ * `__tests__/snapshot-keep-warm.spec.ts`.
+ */
+/**
+ * How often the warm loop runs. Chosen so a tile is perceptibly fresh while
+ * watched; it is also the single biggest cost lever in the design (16 cameras ×
+ * 12 ticks/min against a pool of 3 ffmpeg). A chained timer, not `setInterval` —
+ * the next tick is scheduled only after the previous one settles, so a slow
+ * fleet cannot stack ticks on top of each other.
+ */
+export declare const WARM_INTERVAL_MS = 5000;
+/**
+ * How long one request keeps a device warm. Two minutes of inertia after the
+ * last observer goes away: long enough that flipping between screens (or a
+ * phone locking briefly) does not go cold, short enough that a closed app stops
+ * costing captures well before anyone notices.
+ */
+export declare const WARM_WINDOW_MS = 120000;
+/**
+ * Hard bound on tracked subscriptions. The map is keyed by whatever device ids
+ * arrive over HTTP, so it is attacker-influenced: a sweep over ids must not be
+ * able to grow it without limit, nor make a warm tick dial an unbounded fleet.
+ * Well above any real install's simultaneously-watched camera count.
+ */
+export declare const MAX_WARM_TARGETS = 64;
+/** One (device, stream) the warm loop should refresh, plus the widths a client
+ *  actually asked for — so the tick can pre-derive exactly those variants and
+ *  leave the next real request a hit at BOTH cache levels. */
+export interface SnapshotWarmTarget {
+    readonly deviceId: number;
+    readonly streamId: string | undefined;
+    /** Requested widths still inside the window, ascending. Empty = full frame only. */
+    readonly widths: readonly number[];
+}
+/**
+ * Who is being watched right now, and at what sizes.
+ *
+ * `note` on every data-plane request; `active` on every warm tick. `active`
+ * PRUNES as it walks rather than merely filtering — the map is fed by request
+ * traffic, so a filter-only read would leave every device ever requested in
+ * memory for the life of the process.
+ */
+export declare class SnapshotSubscriptions {
+    private readonly entries;
+    /** Record that somebody asked for this (device, stream) — at `width`, when the
+     *  request carried one. */
+    note(deviceId: number, streamId: string | undefined, width: number | undefined, nowMs: number): void;
+    /**
+     * Refresh the window on subscriptions that ALREADY exist. Never creates one.
+     *
+     * This is what stops the design deadlocking, and the deadlock was measured on
+     * the live hub before it existed. The client re-requests an image only when
+     * the frame identity changes, and the identity changes only because the warm
+     * loop captured — so 120 s after the last image request the subscription
+     * expired, warming stopped, the identity froze, the client never asked again,
+     * and the tile was stuck. Ages went 13 s → 49.7 s at exactly t+120 s.
+     *
+     * The client's `getSnapshotOverview` poll is the heartbeat: asking "what is
+     * the state of these cameras" IS the statement that somebody is looking. It
+     * deliberately cannot CREATE a subscription, because that poll is app-wide —
+     * if it did, opening the app would warm every camera on the install, which is
+     * the blind poll this whole design avoids. Only a rendered surface subscribes.
+     */
+    renew(deviceIds: readonly number[], nowMs: number): void;
+    /** The (device, stream) pairs still inside the warm window, dropping the rest. */
+    active(nowMs: number, windowMs?: number): readonly SnapshotWarmTarget[];
+    get size(): number;
+    clear(): void;
+}

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

@@ -9,6 +9,24 @@ export interface SnapshotMedia {
     readonly capturedAt: number;
     /** Effective per-device max cache age (seconds) → `Cache-Control: max-age`. */
     readonly maxAgeS: number;
+    /**
+     * The width the returned BYTES are actually at, or undefined when they are the
+     * frame as captured.
+     *
+     * Deliberately not the same thing as the requested width. A failed resize
+     * serves the full frame, and stamping the requested `-w320` on it poisons the
+     * ETag: a later SUCCESSFUL resize of the same capture mints the identical tag
+     * with completely different bytes, so a client holding the megabyte revalidates,
+     * gets a 304, and keeps it. The tag has to describe what went out.
+     */
+    readonly servedWidth?: number | undefined;
+}
+/** What the cache can answer about a device WITHOUT capturing anything. */
+export interface SnapshotPeek {
+    /** Epoch ms of the cached capture. */
+    readonly capturedAt: number;
+    /** Effective per-device max cache age (seconds). */
+    readonly maxAgeS: number;
 }
 export interface SnapshotMediaHandlerDeps {
     /**
@@ -17,6 +35,27 @@ export interface SnapshotMediaHandlerDeps {
      * produced (→ 404). Throwing produces an opaque 500 (caller logs).
      */
     readonly getMedia: (deviceId: number, streamId: string | undefined, force: boolean, width: number | undefined) => Promise<SnapshotMedia | null>;
+    /**
+     * Cache-only lookup: what frame is cached for this (device, stream) right now,
+     * and is it still FRESH? Returns null when nothing is cached or the entry is
+     * past its max-age.
+     *
+     * This exists so a conditional GET can be answered before `getMedia` runs.
+     * Without it a 304 is only cheap in bytes — the ladder and the resize have
+     * both already happened by the time the ETags are compared, which on a camera
+     * whose live paths are failing is two 15 s ffmpeg timeouts to send zero bytes.
+     *
+     * Width is deliberately absent: the ETag the client presents already names the
+     * width it holds, and it can only hold a tag this server minted, so matching
+     * the frame identity is sufficient. A client holding the FULL frame after a
+     * failed resize presents `"<id>-<ts>"`, which cannot collide with the
+     * `"<id>-<ts>-w320"` a `?w=320` request computes — it falls through and
+     * re-derives, which is exactly right.
+     *
+     * Optional: a host that does not supply it keeps the previous behaviour
+     * exactly (run the ladder, then compare).
+     */
+    readonly peekFresh?: (deviceId: number, streamId: string | undefined) => Promise<SnapshotPeek | null>;
 }
 /** Parsed `/<deviceId>[.jpg][?streamId=…&force=1&w=320]` request. */
 export interface SnapshotMediaRequest {
@@ -59,7 +98,15 @@ export declare function parseSnapshotMediaRequest(url: string): SnapshotMediaReq
  * `snapshot.getSnapshotOverview` advertises still matches the frame nobody
  * asked to resize.
  */
-export declare function snapshotEtag(request: SnapshotMediaRequest, capturedAt: number): string;
+export declare function snapshotEtag(variant: SnapshotVariantIdentity, capturedAt: number): string;
+/** The (device, stream, width) triple an ETag names. Structurally a
+ *  {@link SnapshotMediaRequest}, but the width is the width SERVED — see
+ *  {@link SnapshotMedia.servedWidth}. */
+export interface SnapshotVariantIdentity {
+    readonly deviceId: number;
+    readonly streamId: string | undefined;
+    readonly width: number | undefined;
+}
 /**
  * Create a data-plane handler that serves per-device snapshots as JPEG images.
  * `deps.getMedia` is called once per request; null → 404, throw → 500. A