@camstack/system 1.2.61 → 1.2.63

package/dist/builtins/local-auth/oauth-grants.d.ts

@@ -7,7 +7,17 @@ interface IssueCodeInput {
     scopes: TokenScope[];
     redirectUri: string;
     hubUrl: string;
+    codeChallenge?: string;
 }
+/**
+ * PKCE S256 check (RFC 7636 §4.6): `BASE64URL(SHA256(verifier)) === challenge`.
+ *
+ * Keyed off the CLAIM, never off the descriptor: a code minted with a challenge
+ * stays unusable without the verifier even if the integration later stops
+ * requiring PKCE. Constant-time compare so a wrong verifier cannot be walked
+ * byte by byte inside the code's 60 s window.
+ */
+export declare function verifyPkceS256(challenge: string, verifier: string | undefined): boolean;
 interface TokenPair {
     accessToken: string;
     refreshToken: string;
@@ -34,6 +44,7 @@ export declare function createOauthGrants(ssoBridge: ISsoBridgeProvider, session
     oauthExchangeCode(input: {
         code: string;
         redirectUri: string;
+        codeVerifier?: string;
     }): Promise<TokenPair | null>;
     oauthRefresh(input: {
         refreshToken: string;

package/dist/builtins/local-auth/oauth-session-manager.d.ts

@@ -1,4 +1,4 @@
-import { TokenScope, SettingsStoreClient } from '@camstack/types';
+import { SettingsStoreClient, TokenScope } from '@camstack/types';
 export interface OauthSession {
     readonly id: string;
     readonly userId: string;

package/dist/builtins/local-network/local-network.addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 //#region src/builtins/local-network/local-network.addon.ts

package/dist/builtins/local-network/local-network.addon.mjs

@@ -1,4 +1,4 @@
-import { W as localNetworkCapability, pt as BaseAddon, zt as EventCategory } from "../../dist-L6QPJWsr.mjs";
+import { Lt as EventCategory, W as localNetworkCapability, dt as BaseAddon } from "../../dist-BJ2w3uoN.mjs";
 import * as os from "node:os";
 //#region src/builtins/local-network/local-network.addon.ts
 /**

package/dist/builtins/loki-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 //#region src/builtins/loki-logging/loki-payload.ts
 /**
 * Loki rejects a label name that is not a valid Prometheus label

package/dist/builtins/loki-logging/index.mjs

@@ -1,4 +1,4 @@
-import { G as logDestinationCapability, pt as BaseAddon } from "../../dist-L6QPJWsr.mjs";
+import { G as logDestinationCapability, dt as BaseAddon } from "../../dist-BJ2w3uoN.mjs";
 //#region src/builtins/loki-logging/loki-payload.ts
 /**
 * Loki rejects a label name that is not a valid Prometheus label

package/dist/builtins/native-metrics/native-metrics.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_child_process = require("node:child_process");

package/dist/builtins/native-metrics/native-metrics.addon.mjs

@@ -1,4 +1,4 @@
-import { Et as createEvent, J as metricsProviderCapability, pt as BaseAddon, zt as EventCategory } from "../../dist-L6QPJWsr.mjs";
+import { J as metricsProviderCapability, Lt as EventCategory, dt as BaseAddon, wt as createEvent } from "../../dist-BJ2w3uoN.mjs";
 import * as fs from "node:fs";
 import { execFile, execFileSync } from "node:child_process";
 import { promisify } from "node:util";

package/dist/builtins/platform-probe/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-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_child_process = require("node:child_process");

package/dist/builtins/platform-probe/index.mjs

@@ -1,5 +1,5 @@
 import { o as __toESM } from "../../chunk-CNf5ZN-e.mjs";
-import { A as enumerateInferenceDevices, Ot as emitReadiness, Q as platformProbeCapability, et as scoreRuntimes, ft as errMsg, pt as BaseAddon, zt as EventCategory } from "../../dist-L6QPJWsr.mjs";
+import { $ as platformProbeCapability, Et as emitReadiness, Lt as EventCategory, M as enumerateInferenceDevices, dt as BaseAddon, tt as scoreRuntimes, ut as errMsg } from "../../dist-BJ2w3uoN.mjs";
 import * as fs from "node:fs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 //#region src/builtins/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { pt as BaseAddon, zt as EventCategory } from "../../dist-L6QPJWsr.mjs";
+import { Lt as EventCategory, dt as BaseAddon } from "../../dist-BJ2w3uoN.mjs";
 //#region src/builtins/remote-access-orchestrator/enabled-providers-reconcile.ts
 /**
 * Reconcile the durable `enabledProviders` set against authoritative

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BN681PgO.js");
+const require_dist = require("../../dist-LDrOFrd-.js");
 let node_child_process = require("node:child_process");
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
@@ -266,10 +266,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("-")}"`;
 }
 /**
@@ -288,6 +288,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);
@@ -305,9 +328,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
@@ -330,7 +357,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 {
@@ -338,10 +365,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);
@@ -501,6 +528,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;
@@ -567,8 +711,28 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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");
@@ -582,6 +746,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			getSnapshotOverview: (input) => this.getSnapshotOverview(input)
 		};
 		await this.serveMediaDataPlane();
+		this.scheduleWarmTick();
 		return [{
 			capability: require_dist.snapshotCapability,
 			provider
@@ -597,7 +762,10 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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",
@@ -619,6 +787,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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 } : {},
@@ -628,14 +797,128 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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: require_dist.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: require_dist.errMsg(err) }
+			});
+		}
+	}
+	/**
 	* The frame at a card-sized width, derived once per (device, stream, width)
 	* per capture.
 	*
@@ -646,10 +929,13 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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 },
@@ -659,7 +945,10 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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 },
@@ -669,10 +958,19 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 					error: require_dist.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;
@@ -711,7 +1009,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input) {
+	async getSnapshot(input, warmAheadMs = 0) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -730,7 +1028,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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,
@@ -1092,6 +1390,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.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 {