@camstack/system 1.2.39 → 1.2.41

package/dist/builtins/snapshot/index.mjs

@@ -1,5 +1,5 @@
-import { Dt as nodePin, ct as BaseAddon, et as snapshotCapability, ft as DeviceFeature, i as BatteryStatusSchema, mt as DeviceType, rt as streamQualityLabel, st as errMsg } from "../../dist-DO76YVO2.mjs";
-import { execFile } from "node:child_process";
+import { Dt as nodePin, ct as BaseAddon, et as snapshotCapability, ft as DeviceFeature, i as BatteryStatusSchema, mt as DeviceType, rt as streamQualityLabel, st as errMsg } from "../../dist-rjk6L9_P.mjs";
+import { execFile, spawn } from "node:child_process";
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
 * Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
@@ -197,6 +197,32 @@ function raceForResult(promise, timeoutMs) {
 //#endregion
 //#region src/builtins/snapshot/snapshot-media-handler.ts
 /**
+* The widths a thumbnail may be served at.
+*
+* A ladder, not a free integer: the width is a cache key AND an ffmpeg run, so
+* honouring `?w=` verbatim would let any caller mint unbounded work and
+* unbounded memory. Twelve tiles measured at 181–240 px collapse onto one
+* variant instead of twelve.
+*
+* Rungs are chosen for the card sizes the viewer actually renders (180–390 px)
+* with headroom for a 2× device pixel ratio.
+*/
+var SNAPSHOT_WIDTH_LADDER = [
+	160,
+	240,
+	320,
+	480,
+	640,
+	960
+];
+/** Snap UP to the next rung — never below what was asked, so the client is not
+*  handed an image it has to upscale. Above the ladder, the largest rung: the
+*  point is to stop serving the 4K original. */
+function snapSnapshotWidth(requested) {
+	for (const rung of SNAPSHOT_WIDTH_LADDER) if (requested <= rung) return rung;
+	return SNAPSHOT_WIDTH_LADDER[SNAPSHOT_WIDTH_LADDER.length - 1] ?? requested;
+}
+/**
 * Parse the handler-relative path (`/<deviceId>.jpg?query`) into a request.
 * Returns null for a malformed / nested / non-numeric id so the handler answers
 * 404 without ever reaching `getMedia`.
@@ -215,13 +241,33 @@ function parseSnapshotMediaRequest(url) {
 	const rawStream = params.get("streamId");
 	const streamId = rawStream !== null && rawStream.length > 0 ? rawStream : void 0;
 	const rawForce = params.get("force");
+	const force = rawForce === "1" || rawForce === "true";
+	const rawWidth = params.get("w");
 	return {
 		deviceId,
 		streamId,
-		force: rawForce === "1" || rawForce === "true"
+		force,
+		width: rawWidth !== null && /^\d+$/.test(rawWidth) && Number.parseInt(rawWidth, 10) > 0 ? snapSnapshotWidth(Number.parseInt(rawWidth, 10)) : void 0
 	};
 }
 /**
+* 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
+* `"<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
+* `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)}`);
+	return `"${parts.join("-")}"`;
+}
+/**
 * 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
 * conditional GET with a matching `If-None-Match` produces a 304.
@@ -239,7 +285,7 @@ function createSnapshotMediaHandler(deps) {
 		}
 		let media;
 		try {
-			media = await deps.getMedia(parsed.deviceId, parsed.streamId, parsed.force);
+			media = await deps.getMedia(parsed.deviceId, parsed.streamId, parsed.force, parsed.width);
 		} catch {
 			const body = "Internal server error";
 			res.writeHead(500, {
@@ -254,7 +300,7 @@ function createSnapshotMediaHandler(deps) {
 			res.writeHead(404).end();
 			return;
 		}
-		const etag = `"${parsed.deviceId}-${media.capturedAt}"`;
+		const etag = snapshotEtag(parsed, media.capturedAt);
 		const cacheControl = `private, max-age=${Math.max(0, Math.floor(media.maxAgeS))}`;
 		if (req.headers["if-none-match"] === etag) {
 			res.writeHead(304, {
@@ -274,6 +320,182 @@ function createSnapshotMediaHandler(deps) {
 	};
 }
 //#endregion
+//#region src/builtins/snapshot/snapshot-cache.ts
+/** A request with no explicit stream is its OWN entry, not a wildcard: the
+*  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) {
+	return `${deviceId}:${streamId ?? AUTO}`;
+}
+var SnapshotCache = class {
+	byKey = /* @__PURE__ */ new Map();
+	/** 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));
+	}
+	set(deviceId, streamId, entry) {
+		const key = keyOf(deviceId, streamId);
+		this.byKey.set(key, entry);
+		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
+		keys.add(key);
+		this.keysByDevice.set(deviceId, keys);
+	}
+	/** The newest entry for a device, whichever stream produced it. */
+	latest(deviceId) {
+		let newest;
+		for (const key of this.keysByDevice.get(deviceId) ?? []) {
+			const entry = this.byKey.get(key);
+			if (entry !== void 0 && (newest === void 0 || entry.ts > newest.ts)) newest = entry;
+		}
+		return newest;
+	}
+	/**
+	* Drop every stream of one device.
+	*
+	* Device-wide on purpose: a settings change or an operator refresh
+	* invalidates the CAMERA, and leaving a sibling entry behind would keep
+	* serving the pre-change frame from the other key.
+	*/
+	deleteDevice(deviceId) {
+		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		this.keysByDevice.delete(deviceId);
+	}
+	clear() {
+		this.byKey.clear();
+		this.keysByDevice.clear();
+	}
+};
+//#endregion
+//#region src/builtins/snapshot/snapshot-resize.ts
+/**
+* Downscaling a captured frame to a card-sized thumbnail.
+*
+* Applied AFTER capture rather than during it, and that is deliberate: the two
+* capture paths (the vendor's native HTTP snapshot and the ffmpeg keyframe
+* grab) produce a JPEG by different routes, and only one of them has an
+* ffmpeg filter chain to hook into. Resizing the finished bytes gives both the
+* same behaviour with one implementation.
+*
+* The cost is one ffmpeg run per (device, stream, width) per cache window — not
+* one per request. A camera whose card is on screen pays it once every
+* `snapshotMaxAgeS`.
+*
+* `ffmpeg` is already this addon's dependency (the keyframe grab shells out to
+* it), so this adds no new one.
+*/
+var RESIZE_TIMEOUT_MS = 1e4;
+/**
+* Scale to `width`, preserving aspect ratio (`-2` keeps the height even, which
+* mjpeg requires).
+*
+* Rejects on a non-zero exit or a timeout. It NEVER falls back to the original
+* silently — a caller that quietly served the 4K frame when the resize failed
+* would reproduce exactly the bug this whole change exists to fix, and nobody
+* would see it. The caller decides, and logs.
+*/
+function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("ffmpeg", [
+			"-loglevel",
+			"error",
+			"-f",
+			"image2pipe",
+			"-i",
+			"pipe:0",
+			"-vf",
+			`scale=${String(width)}:-2:flags=bilinear`,
+			"-frames:v",
+			"1",
+			"-q:v",
+			"5",
+			"-f",
+			"image2pipe",
+			"-vcodec",
+			"mjpeg",
+			"pipe:1"
+		], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		const out = [];
+		let err = "";
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			child.kill("SIGKILL");
+			reject(/* @__PURE__ */ new Error(`snapshot resize timed out after ${String(timeoutMs)}ms`));
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => out.push(chunk));
+		child.stderr.on("data", (chunk) => {
+			err += chunk.toString();
+		});
+		child.on("error", (e) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(e);
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			const buf = Buffer.concat(out);
+			if (code !== 0 || buf.length === 0) {
+				reject(/* @__PURE__ */ new Error(`snapshot resize failed (code ${String(code)}): ${err.trim() || "no output"}`));
+				return;
+			}
+			resolve(buf);
+		});
+		child.stdin.on("error", () => {});
+		child.stdin.end(bytes);
+	});
+}
+/**
+* Resized frames, keyed by (device, stream, width) 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
+* derived from the old one stops matching, and the next request re-derives.
+* Without that check a card would keep showing a thumbnail of a frame the
+* full-size view had already replaced.
+*/
+var SnapshotVariantCache = class SnapshotVariantCache {
+	byKey = /* @__PURE__ */ new Map();
+	keysByDevice = /* @__PURE__ */ new Map();
+	static key(deviceId, streamId, width) {
+		return `${deviceId}:${streamId ?? "auto"}:${width}`;
+	}
+	/** 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));
+		return entry !== void 0 && entry.sourceTs === sourceTs ? entry.bytes : void 0;
+	}
+	set(deviceId, streamId, width, sourceTs, bytes) {
+		const key = SnapshotVariantCache.key(deviceId, streamId, width);
+		this.byKey.set(key, {
+			bytes,
+			sourceTs
+		});
+		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
+		keys.add(key);
+		this.keysByDevice.set(deviceId, keys);
+	}
+	deleteDevice(deviceId) {
+		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		this.keysByDevice.delete(deviceId);
+	}
+	clear() {
+		this.byKey.clear();
+		this.keysByDevice.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;
@@ -309,7 +531,10 @@ function effectiveMaxAgeS(prefs, isBattery) {
 * publishes stream endpoints.
 */
 var SnapshotAddon = class SnapshotAddon extends BaseAddon {
-	cache = /* @__PURE__ */ new Map();
+	cache = new SnapshotCache();
+	/** Card-sized derivatives of the frames above, keyed by width and validated
+	*  against the source frame's timestamp. */
+	variants = new SnapshotVariantCache();
 	/**
 	* 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
@@ -367,7 +592,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* base64 path.
 	*/
 	async serveMediaDataPlane() {
-		const handler = createSnapshotMediaHandler({ getMedia: (deviceId, streamId, force) => this.resolveSnapshotMedia(deviceId, streamId, force) });
+		const handler = createSnapshotMediaHandler({ getMedia: (deviceId, streamId, force, width) => this.resolveSnapshotMedia(deviceId, streamId, force, width) });
 		try {
 			this.mediaDataPlane = await this.ctx.dataPlane?.serve({
 				prefix: "media",
@@ -388,29 +613,67 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* the cache entry (matching the ETag `getSnapshotOverview` advertises) and the
 	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
 	*/
-	async resolveSnapshotMedia(deviceId, streamId, force) {
+	async resolveSnapshotMedia(deviceId, streamId, force, width) {
 		const image = await this.getSnapshot({
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
 			force
 		});
 		if (!image) return null;
-		const capturedAt = this.cache.get(deviceId)?.ts ?? Date.now();
+		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;
 		return {
-			bytes: Buffer.from(image.base64, "base64"),
+			bytes: width === void 0 ? Buffer.from(image.base64, "base64") : await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs),
 			contentType: image.contentType,
 			capturedAt,
 			maxAgeS: effectiveMaxAgeS(prefs, isBattery)
 		};
 	}
+	/**
+	* The frame at a card-sized width, derived once per (device, stream, width)
+	* 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);
+		if (cached !== void 0) return cached;
+		const full = Buffer.from(image.base64, "base64");
+		try {
+			const resized = await resizeJpeg(full, width);
+			this.variants.set(deviceId, streamId, width, capturedAt, resized);
+			if (prefs.snapshotDebug) this.ctx.logger.info("snapshot: thumbnail derived", {
+				tags: { deviceId },
+				meta: {
+					width,
+					fullBytes: full.length,
+					thumbBytes: resized.length
+				}
+			});
+			return resized;
+		} catch (err) {
+			this.ctx.logger.warn("snapshot: resize failed — serving the full frame", {
+				tags: { deviceId },
+				meta: {
+					width,
+					bytes: full.length,
+					error: errMsg(err)
+				}
+			});
+			return full;
+		}
+	}
 	async onShutdown() {
 		if (this.mediaDataPlane) {
 			await this.mediaDataPlane.dispose().catch(() => void 0);
 			this.mediaDataPlane = null;
 		}
 		this.cache.clear();
+		this.variants.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -454,7 +717,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			...deviceName ? { deviceName } : {}
 		});
 		const now = Date.now();
-		const hit = this.cache.get(deviceId);
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
 		const rawPref = prefs.snapshotStreamId;
 		const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
@@ -462,6 +724,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			tags: { deviceId },
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
+		const hit = this.cache.get(deviceId, effectiveStreamId);
 		const effectiveMaxAgeMs = effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3;
 		const decision = decideSnapshotServe({
 			now,
@@ -570,7 +833,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			if (native) {
 				const result = await this.nativePool.run(() => native.getSnapshot(input));
 				if (result) {
-					this.cache.set(deviceId, {
+					this.cache.set(deviceId, effectiveStreamId, {
 						data: result,
 						ts: now,
 						streamId: effectiveStreamId ?? null
@@ -604,7 +867,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.cache.set(deviceId, {
+				this.cache.set(deviceId, effectiveStreamId, {
 					data: fallback,
 					ts: now,
 					streamId: effectiveStreamId ?? null
@@ -750,7 +1013,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		};
 	}
 	async invalidateCache(input) {
-		this.cache.delete(input.deviceId);
+		this.cache.deleteDevice(input.deviceId);
+		this.variants.deleteDevice(input.deviceId);
 		this.captureFlight.invalidatePrefix(`${input.deviceId}:`);
 	}
 	/**
@@ -824,7 +1088,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	getSnapshotOverview(input) {
 		const now = Date.now();
 		const rows = input.deviceIds.map((deviceId) => {
-			const hit = this.cache.get(deviceId);
+			const hit = this.cache.latest(deviceId);
 			if (!hit) return {
 				deviceId,
 				lastCapturedAt: null,
@@ -848,7 +1112,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* (cache miss) since the addon started.
 	*/
 	async getStatus(deviceId) {
-		const hit = this.cache.get(deviceId);
+		const hit = this.cache.latest(deviceId);
 		if (!hit) return null;
 		return {
 			lastCapturedAt: hit.ts,
@@ -996,7 +1260,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			else delete next["snapshotMaxAgeS"];
 		}
 		await this.ctx.settings.writeDeviceStore(deviceId, next);
-		this.cache.delete(deviceId);
+		this.cache.deleteDevice(deviceId);
+		this.variants.deleteDevice(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 		return { success: true };
 	}

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

@@ -0,0 +1,45 @@
+/**
+ * The per-device snapshot cache, keyed by (device, STREAM).
+ *
+ * It used to be keyed by device alone, and `getSnapshot` served the hit before
+ * it had resolved which stream the caller asked for — so `?streamId=low`
+ * silently returned whatever was already cached. In production that meant the
+ * 4K main frame: probing a live camera with `low`, `sub` and `high` returned
+ * three byte-identical 1.2 MB responses. The parameter existed, was documented,
+ * and did nothing.
+ *
+ * Two views still need to ask a device-wide question — "when did this camera
+ * last produce a frame" (`getSnapshotOverview`, `getStatus`) — so
+ * {@link SnapshotCache.latest} answers it across streams rather than making
+ * every caller guess a key.
+ */
+/** The cached frame. Structurally the addon's `SnapshotImage` — declared here
+ *  rather than imported so the cache does not depend on the 1,100-line addon. */
+export interface SnapshotCacheImage {
+    readonly base64: string;
+    readonly contentType: string;
+}
+export interface SnapshotCacheEntry {
+    readonly data: SnapshotCacheImage;
+    readonly ts: number;
+    /** Stream id resolved at capture time — 'high' | 'mid' | 'low' | custom | null. */
+    readonly streamId: string | null;
+}
+export declare class SnapshotCache {
+    private readonly byKey;
+    /** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
+    private readonly keysByDevice;
+    get(deviceId: number, streamId: string | undefined): SnapshotCacheEntry | undefined;
+    set(deviceId: number, streamId: string | undefined, entry: SnapshotCacheEntry): void;
+    /** The newest entry for a device, whichever stream produced it. */
+    latest(deviceId: number): SnapshotCacheEntry | undefined;
+    /**
+     * Drop every stream of one device.
+     *
+     * Device-wide on purpose: a settings change or an operator refresh
+     * invalidates the CAMERA, and leaving a sibling entry behind would keep
+     * serving the pre-change frame from the other key.
+     */
+    deleteDevice(deviceId: number): void;
+    clear(): void;
+}

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

@@ -16,20 +16,50 @@ export interface SnapshotMediaHandlerDeps {
      * the wrapper's coalesced capture ladder; returns null when no frame can be
      * produced (→ 404). Throwing produces an opaque 500 (caller logs).
      */
-    readonly getMedia: (deviceId: number, streamId: string | undefined, force: boolean) => Promise<SnapshotMedia | null>;
+    readonly getMedia: (deviceId: number, streamId: string | undefined, force: boolean, width: number | undefined) => Promise<SnapshotMedia | null>;
 }
-/** Parsed `/<deviceId>[.jpg][?streamId=…&force=1]` request. */
+/** Parsed `/<deviceId>[.jpg][?streamId=…&force=1&w=320]` request. */
 export interface SnapshotMediaRequest {
     readonly deviceId: number;
     readonly streamId: string | undefined;
     readonly force: boolean;
+    /** Snapped target width in px, or undefined for the frame as captured. */
+    readonly width: number | undefined;
 }
+/**
+ * The widths a thumbnail may be served at.
+ *
+ * A ladder, not a free integer: the width is a cache key AND an ffmpeg run, so
+ * honouring `?w=` verbatim would let any caller mint unbounded work and
+ * unbounded memory. Twelve tiles measured at 181–240 px collapse onto one
+ * variant instead of twelve.
+ *
+ * Rungs are chosen for the card sizes the viewer actually renders (180–390 px)
+ * with headroom for a 2× device pixel ratio.
+ */
+export declare const SNAPSHOT_WIDTH_LADDER: readonly number[];
+/** Snap UP to the next rung — never below what was asked, so the client is not
+ *  handed an image it has to upscale. Above the ladder, the largest rung: the
+ *  point is to stop serving the 4K original. */
+export declare function snapSnapshotWidth(requested: number): number;
 /**
  * Parse the handler-relative path (`/<deviceId>.jpg?query`) into a request.
  * Returns null for a malformed / nested / non-numeric id so the handler answers
  * 404 without ever reaching `getMedia`.
  */
 export declare function parseSnapshotMediaRequest(url: string): SnapshotMediaRequest | null;
+/**
+ * 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
+ * `"<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
+ * `snapshot.getSnapshotOverview` advertises still matches the frame nobody
+ * asked to resize.
+ */
+export declare function snapshotEtag(request: SnapshotMediaRequest, capturedAt: number): string;
 /**
  * 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

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

@@ -0,0 +1,50 @@
+/**
+ * Downscaling a captured frame to a card-sized thumbnail.
+ *
+ * Applied AFTER capture rather than during it, and that is deliberate: the two
+ * capture paths (the vendor's native HTTP snapshot and the ffmpeg keyframe
+ * grab) produce a JPEG by different routes, and only one of them has an
+ * ffmpeg filter chain to hook into. Resizing the finished bytes gives both the
+ * same behaviour with one implementation.
+ *
+ * The cost is one ffmpeg run per (device, stream, width) per cache window — not
+ * one per request. A camera whose card is on screen pays it once every
+ * `snapshotMaxAgeS`.
+ *
+ * `ffmpeg` is already this addon's dependency (the keyframe grab shells out to
+ * it), so this adds no new one.
+ */
+/** Runs the resize. Injected so the caller is testable without a real ffmpeg. */
+export type JpegResizer = (bytes: Buffer, width: number) => Promise<Buffer>;
+export declare const RESIZE_TIMEOUT_MS = 10000;
+/**
+ * Scale to `width`, preserving aspect ratio (`-2` keeps the height even, which
+ * mjpeg requires).
+ *
+ * Rejects on a non-zero exit or a timeout. It NEVER falls back to the original
+ * silently — a caller that quietly served the 4K frame when the resize failed
+ * would reproduce exactly the bug this whole change exists to fix, and nobody
+ * would see it. The caller decides, and logs.
+ */
+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.
+ *
+ * The timestamp is the whole correctness argument: a variant outlives nothing.
+ * When the underlying frame is recaptured its `capturedAt` moves, every variant
+ * derived from the old one stops matching, and the next request re-derives.
+ * Without that check a card would keep showing a thumbnail of a frame the
+ * full-size view had already replaced.
+ */
+export declare class SnapshotVariantCache {
+    private readonly byKey;
+    private readonly keysByDevice;
+    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;
+    deleteDevice(deviceId: number): void;
+    clear(): void;
+}

package/dist/builtins/snapshot/snapshot.addon.d.ts

@@ -30,6 +30,9 @@ interface SnapshotAddonConfig {
  */
 export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
     private readonly cache;
+    /** Card-sized derivatives of the frames above, keyed by width and validated
+     *  against the source frame's timestamp. */
+    private readonly variants;
     /**
      * 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
@@ -78,6 +81,16 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      * effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
      */
     private resolveSnapshotMedia;
+    /**
+     * The frame at a card-sized width, derived once per (device, stream, width)
+     * 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.
+     */
+    private thumbnailBytes;
     protected onShutdown(): Promise<void>;
     /**
      * Drop the cached ingest owner whenever addon-level settings change —

package/dist/builtins/sqlite-storage/filesystem-storage.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-CFinlH7b.js");
+const require_dist = require("../../dist-BECNOXoK.js");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { N as filesystemBrowseCapability, ct as BaseAddon, nt as storageProviderCapability } from "../../dist-DO76YVO2.mjs";
+import { N as filesystemBrowseCapability, ct as BaseAddon, nt as storageProviderCapability } from "../../dist-rjk6L9_P.mjs";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
 import { basename, dirname, join, resolve, sep } from "node:path";

package/dist/builtins/sqlite-storage/sqlite-settings.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-CFinlH7b.js");
+const require_dist = require("../../dist-BECNOXoK.js");
 let node_crypto = require("node:crypto");
 let better_sqlite3 = require("better-sqlite3");
 better_sqlite3 = require_chunk.__toESM(better_sqlite3);

package/dist/builtins/sqlite-storage/sqlite-settings.addon.mjs

@@ -1,4 +1,4 @@
-import { C as dataStoreProviderCapability, ct as BaseAddon, kt as parseJsonUnknown, l as RUNTIME_DEFAULTS, st as errMsg, vt as asJsonObject } from "../../dist-DO76YVO2.mjs";
+import { C as dataStoreProviderCapability, ct as BaseAddon, kt as parseJsonUnknown, l as RUNTIME_DEFAULTS, st as errMsg, vt as asJsonObject } from "../../dist-rjk6L9_P.mjs";
 import { randomUUID } from "node:crypto";
 import Database from "better-sqlite3";
 //#region src/builtins/sqlite-storage/filter-compiler.ts

package/dist/builtins/storage-orchestrator/storage-orchestrator.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-CFinlH7b.js");
+const require_dist = require("../../dist-BECNOXoK.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
 let node_fs_promises = require("node:fs/promises");

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { $ as settingsStoreCapability, Ot as parseJsonObject, ct as BaseAddon, f as StorageLocationTypeSchema, tt as storageCapability } from "../../dist-DO76YVO2.mjs";
+import { $ as settingsStoreCapability, Ot as parseJsonObject, ct as BaseAddon, f as StorageLocationTypeSchema, tt as storageCapability } from "../../dist-rjk6L9_P.mjs";
 import * as path$1 from "node:path";
 import * as fs from "node:fs/promises";
 import { buildStorageLocationRegistry } from "@camstack/system";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CFinlH7b.js");
+const require_dist = require("../../dist-BECNOXoK.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.