@camstack/system 1.2.80 → 1.2.81

package/dist/builtins/snapshot/index.mjs

@@ -1,9 +1,57 @@
-import { Ft as nodePin, St as DeviceType, bt as DeviceFeature, dt as streamQualityLabel, gt as BaseAddon, ht as errMsg, i as BatteryStatusSchema, st as snapshotCapability, w as bareAddonId } from "../../dist-DZOZtn-0.mjs";
+import { Ft as nodePin, Ht as EventCategory, St as DeviceType, bt as DeviceFeature, dt as streamQualityLabel, gt as BaseAddon, ht as errMsg, i as BatteryStatusSchema, st as snapshotCapability, w as bareAddonId } from "../../dist-DZOZtn-0.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { signExpiringUrl, verifyExpiringUrl } from "@camstack/types/node";
 import { execFile } from "node:child_process";
 import sharp from "sharp";
+//#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-coalescing.ts
 /**
 * Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
@@ -199,563 +247,515 @@ function raceForResult(promise, timeoutMs) {
 	});
 }
 //#endregion
-//#region src/builtins/snapshot/snapshot-media-handler.ts
+//#region src/builtins/snapshot/snapshot-courtesy.ts
 /**
-* The widths a thumbnail may be served at.
+* A courtesy frame for a camera that CANNOT produce one.
 *
-* 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.
+* ── Why this exists ───────────────────────────────────────────────────────
+* A disabled, offline or sleeping camera has no frame, and until 2026-08-11 the
+* snapshot service simply had nothing to say about it: the media route answered
+* **404** and the client painted "Unavailable". Measured on the live grid that
+* day, 10 of 26 tiles were 404s — one genuinely disabled camera plus nine dead
+* legacy rows. A 404 is indistinguishable from a broken camera, so an operator
+* 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").
 *
-* Rungs are chosen for the card sizes the viewer actually renders (180–390 px)
-* with headroom for a 2× device pixel ratio.
+* 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.
+*
+* ── Why sharp and not ffmpeg ──────────────────────────────────────────────
+* The first draft of this file shelled out to `ffmpeg` with a `drawtext`
+* filter. That was written before the resize path was measured, and it was the
+* wrong call for the same reason: this runs in the snapshot wrapper, a system
+* builtin loaded in the hub's ROOT process, so every render was a fork + exec
+* on the loop that serves the API — 52 ms against sharp's 4.8 ms in that
+* container, to draw two lines of text.
+*
+* `terminal-frame-renderer.ts` already renders text this way (SVG → sharp), so
+* this is the house pattern rather than a new one. It also drops the font-PATH
+* probing the ffmpeg version needed: an SVG names a font FAMILY and fontconfig
+* resolves it — verified in the hub image, where `fc-match "DejaVu Sans Mono"`
+* answers with the real file.
+*
+* Rendering is pure input → bytes with no I/O of its own, and the geometry and
+* escaping are separated out so they stay testable without rasterizing.
 */
-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;
+/**
+* Font stack for the rendered text. Family names, not paths — librsvg resolves
+* them through fontconfig, and the trailing generics keep a host without DejaVu
+* rendering something legible instead of nothing.
+*/
+var COURTESY_FONT_STACK = "DejaVu Sans,DejaVu Sans Mono,Helvetica,Arial,sans-serif";
+/** The word the frame carries. Deliberately the operator's vocabulary. */
+function courtesyLabel(reason) {
+	switch (reason) {
+		case "disabled": return "Disabled";
+		case "offline": return "Offline";
+		case "sleeping": return "Sleeping";
+	}
 }
 /**
-* 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`.
+* Background per reason. A disabled camera is a DELIBERATE state and must not
+* read as an alarm, so it is neutral grey; offline is a fault and is warmer.
 */
-function parseSnapshotMediaRequest(url) {
-	const qIdx = url.indexOf("?");
-	const rawPath = qIdx === -1 ? url : url.slice(0, qIdx);
-	const query = qIdx === -1 ? "" : url.slice(qIdx + 1);
-	const segment = rawPath.replace(/^\/+/, "");
-	if (segment.length === 0 || segment.includes("/")) return null;
-	const idPart = segment.replace(/\.jpe?g$/i, "");
-	if (!/^\d+$/.test(idPart)) return null;
-	const deviceId = Number.parseInt(idPart, 10);
-	if (!Number.isSafeInteger(deviceId)) return null;
-	const params = new URLSearchParams(query);
-	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,
-		width: rawWidth !== null && /^\d+$/.test(rawWidth) && Number.parseInt(rawWidth, 10) > 0 ? snapSnapshotWidth(Number.parseInt(rawWidth, 10)) : void 0
-	};
+function courtesyBackground(reason) {
+	switch (reason) {
+		case "disabled": return "#2b2b31";
+		case "offline": return "#3a2b2b";
+		case "sleeping": return "#232b3a";
+	}
+}
+/** XML escaping for text placed inside an SVG `<text>` node. */
+function escapeCourtesyText(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 }
 /**
-* The response's entity tag.
+* The SVG the frame is rasterized from: the state large and centred, the
+* camera's name under it, smaller and dimmer.
 *
-* 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.
+* Sizes derive from the width so a 240 px grid tile and a 1920 px full-bleed
+* frame read the same, with a floor so a thumbnail stays legible.
 */
-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("-")}"`;
+function buildCourtesySvg(spec) {
+	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;
+	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">`,
+		`<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>`
+	].join("");
+}
+/** Cache key — a courtesy frame is a pure function of these four. */
+function courtesyCacheKey(spec) {
+	return `${spec.reason}:${String(spec.width)}x${String(spec.height)}:${spec.deviceName}`;
 }
 /**
-* 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.
+* Render the frame.
+*
+* Rejects on failure — the caller decides what to do, exactly as `resizeJpeg`
+* does, so a broken courtesy path is never mistaken for a broken camera.
 */
-function createSnapshotMediaHandler(deps) {
-	return async (req, res) => {
-		if (req.method !== "GET" && req.method !== "HEAD") {
-			res.writeHead(405, { allow: "GET, HEAD" }).end();
-			return;
-		}
-		const parsed = parseSnapshotMediaRequest(req.url ?? "/");
-		if (parsed === null) {
-			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);
-		} catch {
-			const body = "Internal server error";
-			res.writeHead(500, {
-				"content-type": "text/plain",
-				"content-length": String(Buffer.byteLength(body))
-			});
-			if (req.method === "HEAD") res.end();
-			else res.end(body);
-			return;
-		}
-		if (media === null) {
-			res.writeHead(404).end();
-			return;
-		}
-		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 (inm === etag) {
-			res.writeHead(304, {
-				etag,
-				"cache-control": cacheControl
-			}).end();
-			return;
-		}
-		res.writeHead(200, {
-			"content-type": media.contentType,
-			"cache-control": cacheControl,
-			etag,
-			"content-length": String(media.bytes.byteLength)
-		});
-		if (req.method === "HEAD") res.end();
-		else res.end(Buffer.from(media.bytes));
-	};
+function renderCourtesyJpeg(spec) {
+	return sharp(Buffer.from(buildCourtesySvg(spec))).jpeg({ quality: 82 }).toBuffer().then((bytes) => {
+		if (bytes.length === 0) throw new Error("courtesy frame produced no bytes");
+		return bytes;
+	});
 }
 //#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
+//#region src/builtins/snapshot/snapshot-link-url.ts
 /**
-* Downscaling a captured frame to a card-sized thumbnail.
+* Signed, expiring links to a CLIENT-SIZED snapshot frame.
 *
-* 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.
+* ## Why a link plane exists at all
 *
-* ── Why sharp and not ffmpeg (2026-08-11) ─────────────────────────────────
-* This used to `spawn('ffmpeg')` per resize. The snapshot wrapper is a system
-* builtin, so it loads in the hub's ROOT process: sampled on the live hub,
-* ~1.6 of those children were running at any instant, every one of them
-* parented by the root PID.
+* The authenticated `/addon/snapshot/media/<id>.jpg` plane works, and it is not
+* going away. What it cannot do is guarantee that a client asking for a tile
+* actually REACHES the server — and that turned out to be the whole bug.
 *
-* Be precise about what that cost the root process, because it is easy to
-* overstate. The transcode itself ran in the CHILD and was charged to ffmpeg
-* (16 % + 13 % of a core in that same sample), not to the parent. What the
-* parent paid was the fork, the exec, the JPEG written into one pipe and read
-* back out of the other, and the base64 — real event-loop work, on the loop
-* that also serves the tRPC API, but NOT the 52 ms below.
+* Under D93 the image URL is versioned by the frame identity, and an image
+* request is what signalled demand for a camera. Both halves are satisfied by
+* the client's own image cache: `expo-image` is URL-keyed and never
+* revalidates, so a URL the app painted in a previous session is served from
+* disk with **zero network**. Measured on the live hub, reopening the app after
+* two minutes idle painted 15 of 16 tiles from disk — frames **168 s old**, with
+* not one HTTP request, therefore no demand, therefore no capture. The
+* operator's report ("gli snapshot sono vecchi, devo aggiornare più volte") is
+* that measurement.
 *
-* Benchmarked in that container, 2560×1440 → 640 wide, wall-clock per resize:
+* That gap used to be covered on BOTH sides — by this link plane and by a
+* server-side keep-warm timer. The timer was removed on 2026-08-11 (operator
+* directive: snapshots are on-demand, always), which makes this plane the only
+* thing standing between a client cache and a frozen tile. It carries the whole
+* job now.
 *
-*     ffmpeg   52.0 ms   (fork + exec + pipe round-trip + teardown)
-*     sharp     4.8 ms   (in-process libvips, on its own threadpool)
+* A minted link breaks the loop from both ends. It is produced by an RPC —
+* `snapshot.getSnapshotLinks` — which no image cache can answer, so the demand
+* signal always lands; and it carries the capture identity the RPC just WAITED
+* for, rather than one a cache-only poll happened to be holding.
 *
-* So this removes ~29 % of a core of container CPU and the per-resize process
-* churn from the root process. It was NOT verified to be the cause of that
-* process sitting at 90 % — nobody has profiled it.
+* ## What is signed, and what is only a cache key
 *
-* `sharp` is not a new dependency: it is already a host-external
-* (`HOST_EXTERNAL_SPECIFIERS`), already resolved from the framework closure at
-* runtime, and already used by the terminal frame renderer. The build preset
-* keeps it out of the bundle, so this import costs nothing at pack time.
+* The signature covers `"<deviceId>:<width>"` and the expiry. The width is
+* inside it deliberately: a leaked 240 px tile link must not be replayable as a
+* request for the full 4 K frame. `v` (the capture identity) is NOT signed — it
+* exists only to key the client's image cache, so an unchanged frame is a
+* byte-identical URL and costs no bytes, and a new frame is a new URL and costs
+* exactly one fetch.
 *
-* The cost is still one resize per (device, stream, width) per cache window —
-* not one per request. What changed is what a resize COSTS.
+* `exp` is bucketed rather than exact. A URL that were unique per mint would
+* defeat the client cache completely — correct for freshness, and it would make
+* a phone re-download every tile on every 5 s poll whether or not anything
+* changed. Bucketing means the URL moves when the FRAME moves, and otherwise at
+* most once per bucket.
+*
+* Pure and side-effect-free; the addon owns the secret and the clock. Unit
+* tested in `__tests__/snapshot-link-url.spec.ts`.
 */
-var RESIZE_TIMEOUT_MS = 1e4;
 /**
-* Encode quality for a derived thumbnail. Matches what the ffmpeg path
-* produced (`-q:v 5` on the mjpeg encoder) closely enough that no card visibly
-* changes — this migration is about COST, not about re-tuning the picture.
+* How long a minted link stays valid.
+*
+* A snapshot is a live view of the operator's home, so this is short on purpose
+* — the exposure of a leaked link is bounded by it. Two minutes is long enough
+* that a page renders, re-renders and survives a brief backgrounding on the URL
+* it was given, and short enough that a link pasted somewhere is dead before it
+* is useful. The client re-mints on every overview poll (5 s), so it never
+* depends on the tail of this window.
 */
-var JPEG_QUALITY = 82;
+var SNAPSHOT_LINK_TTL_MS = 12e4;
 /**
-* Scale to `width`, preserving aspect ratio.
-*
-* Rejects on failure or 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 module exists to fix, and nobody would
-* see it. The caller decides, and logs.
+* Quantum the expiry is rounded UP to, so a link is stable between mints.
 *
-* It DOES upscale a source narrower than `width`, and that is deliberate. A
-* `withoutEnlargement: true` was tried first — it is the obvious saving, since
-* upscaling pays encode cost for a blurrier, larger image. But the caller
-* stamps the response ETag from the width it asked for, and its resize-FAILURE
-* path already returns `width: undefined` specifically so a response can never
-* "claim a width the bytes do not have". Silently returning 320 px bytes for a
-* `w=640` request breaks that invariant on the SUCCESS path, where nobody is
-* looking. Honest output width beats a few saved pixels; revisit only together
-* with the ETag.
+* Without it every mint produces a different `exp`, hence a different URL, hence
+* a full re-download of an unchanged frame on every poll. With it the URL is a
+* pure function of (device, width, frame, bucket) — so a tile fetches when its
+* frame moves, and at most once more per bucket.
 */
-function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
-	const work = sharp(bytes).resize({ width }).jpeg({
-		quality: JPEG_QUALITY,
-		mozjpeg: false
-	}).toBuffer().then((out) => {
-		if (out.length === 0) throw new Error("snapshot resize produced no bytes");
-		return out;
-	});
-	let timer;
-	const bound = new Promise((_, reject) => {
-		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`snapshot resize timed out after ${String(timeoutMs)}ms`)), timeoutMs);
-	});
-	return Promise.race([work, bound]).finally(() => {
-		if (timer !== void 0) clearTimeout(timer);
-	});
+var SNAPSHOT_LINK_EXP_BUCKET_MS = 3e4;
+/** The token the signature is computed over. Width is part of the identity so a
+*  tile link cannot be escalated into a full-frame request. */
+function snapshotLinkId(deviceId, width) {
+	return `${String(deviceId)}:${width === void 0 ? "full" : String(width)}`;
+}
+/** The bucketed expiry for a link minted at `nowMs`. Always ≥ `nowMs + TTL`. */
+function snapshotLinkExpiry(nowMs, ttlMs = SNAPSHOT_LINK_TTL_MS, bucketMs = SNAPSHOT_LINK_EXP_BUCKET_MS) {
+	return Math.ceil((nowMs + ttlMs) / bucketMs) * bucketMs;
 }
 /**
-* Resized frames, keyed by (device, stream, width) AND validated against the
-* source frame's timestamp.
+* The link, as a ROOT-RELATIVE path.
 *
-* 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.
+* Deliberately not absolute. The artifact and HA planes must mint absolute URLs
+* because the fetcher is a phone or a notifier backend that has no idea where
+* the hub is — and picking that base is the `hubUrl: localhost` trap the Alexa
+* work paid for. Here the fetcher is a client that is already connected to the
+* hub and holds its own `serverUrl`, so the correct base is the one it used to
+* make the call. Returning a path makes it impossible to hand a client a link
+* pointing somewhere it cannot reach.
 */
-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();
-	}
-};
+function buildSnapshotLinkUrl(input) {
+	const base = (input.routePrefix.startsWith("/") ? input.routePrefix : `/${input.routePrefix}`).replace(/\/+$/, "");
+	const id = snapshotLinkId(input.deviceId, input.width);
+	const sig = signExpiringUrl(input.secret, id, input.expMs);
+	const params = new URLSearchParams();
+	if (input.width !== void 0) params.set("w", String(input.width));
+	if (input.capturedAt !== null) params.set("v", String(input.capturedAt));
+	params.set("exp", String(input.expMs));
+	params.set("sig", sig);
+	return `${base}/${String(input.deviceId)}.jpg?${params.toString()}`;
+}
+/**
+* Parse and VERIFY a link request in one step, so a caller cannot accidentally
+* use the device id before checking the signature. Null = refuse (404/403);
+* there is deliberately no way to distinguish "bad signature" from "expired"
+* from "malformed" at this boundary, so a public route cannot be probed.
+*/
+function parseVerifiedSnapshotLink(input) {
+	const qIdx = input.url.indexOf("?");
+	const rawPath = qIdx === -1 ? input.url : input.url.slice(0, qIdx);
+	const query = qIdx === -1 ? "" : input.url.slice(qIdx + 1);
+	const segment = rawPath.replace(/^\/+/, "");
+	if (segment.length === 0 || segment.includes("/")) return null;
+	const idPart = segment.replace(/\.jpe?g$/i, "");
+	if (!/^\d+$/.test(idPart)) return null;
+	const deviceId = Number.parseInt(idPart, 10);
+	if (!Number.isSafeInteger(deviceId) || deviceId <= 0) return null;
+	const params = new URLSearchParams(query);
+	const rawWidth = params.get("w");
+	if (rawWidth !== null && !/^\d+$/.test(rawWidth)) return null;
+	const width = rawWidth === null ? void 0 : Number.parseInt(rawWidth, 10);
+	if (width !== void 0 && (!Number.isSafeInteger(width) || width <= 0)) return null;
+	return verifyExpiringUrl({
+		secret: input.secret,
+		id: snapshotLinkId(deviceId, width),
+		exp: params.get("exp") ?? void 0,
+		sig: params.get("sig") ?? void 0,
+		nowMs: input.nowMs
+	}) ? {
+		deviceId,
+		width
+	} : null;
+}
 //#endregion
-//#region src/builtins/snapshot/snapshot-courtesy.ts
+//#region src/builtins/snapshot/snapshot-media-handler.ts
 /**
-* A courtesy frame for a camera that CANNOT produce one.
-*
-* ── Why this exists ───────────────────────────────────────────────────────
-* A disabled, offline or sleeping camera has no frame, and until 2026-08-11 the
-* snapshot service simply had nothing to say about it: the media route answered
-* **404** and the client painted "Unavailable". Measured on the live grid that
-* day, 10 of 26 tiles were 404s — one genuinely disabled camera plus nine dead
-* legacy rows. A 404 is indistinguishable from a broken camera, so an operator
-* 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.
-*
-* ── Why sharp and not ffmpeg ──────────────────────────────────────────────
-* The first draft of this file shelled out to `ffmpeg` with a `drawtext`
-* filter. That was written before the resize path was measured, and it was the
-* wrong call for the same reason: this runs in the snapshot wrapper, a system
-* builtin loaded in the hub's ROOT process, so every render was a fork + exec
-* on the loop that serves the API — 52 ms against sharp's 4.8 ms in that
-* container, to draw two lines of text.
+* The widths a thumbnail may be served at.
 *
-* `terminal-frame-renderer.ts` already renders text this way (SVG → sharp), so
-* this is the house pattern rather than a new one. It also drops the font-PATH
-* probing the ffmpeg version needed: an SVG names a font FAMILY and fontconfig
-* resolves it — verified in the hub image, where `fc-match "DejaVu Sans Mono"`
-* answers with the real file.
+* 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.
 *
-* Rendering is pure input → bytes with no I/O of its own, and the geometry and
-* escaping are separated out so they stay testable without rasterizing.
-*/
-/**
-* Font stack for the rendered text. Family names, not paths — librsvg resolves
-* them through fontconfig, and the trailing generics keep a host without DejaVu
-* rendering something legible instead of nothing.
+* Rungs are chosen for the card sizes the viewer actually renders (180–390 px)
+* with headroom for a 2× device pixel ratio.
 */
-var COURTESY_FONT_STACK = "DejaVu Sans,DejaVu Sans Mono,Helvetica,Arial,sans-serif";
-/** The word the frame carries. Deliberately the operator's vocabulary. */
-function courtesyLabel(reason) {
-	switch (reason) {
-		case "disabled": return "Disabled";
-		case "offline": return "Offline";
-		case "sleeping": return "Sleeping";
-	}
+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;
 }
 /**
-* Background per reason. A disabled camera is a DELIBERATE state and must not
-* read as an alarm, so it is neutral grey; offline is a fault and is warmer.
+* 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`.
 */
-function courtesyBackground(reason) {
-	switch (reason) {
-		case "disabled": return "#2b2b31";
-		case "offline": return "#3a2b2b";
-		case "sleeping": return "#232b3a";
-	}
-}
-/** XML escaping for text placed inside an SVG `<text>` node. */
-function escapeCourtesyText(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+function parseSnapshotMediaRequest(url) {
+	const qIdx = url.indexOf("?");
+	const rawPath = qIdx === -1 ? url : url.slice(0, qIdx);
+	const query = qIdx === -1 ? "" : url.slice(qIdx + 1);
+	const segment = rawPath.replace(/^\/+/, "");
+	if (segment.length === 0 || segment.includes("/")) return null;
+	const idPart = segment.replace(/\.jpe?g$/i, "");
+	if (!/^\d+$/.test(idPart)) return null;
+	const deviceId = Number.parseInt(idPart, 10);
+	if (!Number.isSafeInteger(deviceId)) return null;
+	const params = new URLSearchParams(query);
+	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,
+		width: rawWidth !== null && /^\d+$/.test(rawWidth) && Number.parseInt(rawWidth, 10) > 0 ? snapSnapshotWidth(Number.parseInt(rawWidth, 10)) : void 0
+	};
 }
 /**
-* The SVG the frame is rasterized from: the state large and centred, the
-* camera's name under it, smaller and dimmer.
+* The response's entity tag.
 *
-* Sizes derive from the width so a 240 px grid tile and a 1920 px full-bleed
-* frame read the same, with a floor so a thumbnail stays legible.
+* 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 buildCourtesySvg(spec) {
-	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;
-	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">`,
-		`<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>`
-	].join("");
-}
-/** Cache key — a courtesy frame is a pure function of these four. */
-function courtesyCacheKey(spec) {
-	return `${spec.reason}:${String(spec.width)}x${String(spec.height)}:${spec.deviceName}`;
+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("-")}"`;
 }
 /**
-* Render the frame.
-*
-* Rejects on failure — the caller decides what to do, exactly as `resizeJpeg`
-* does, so a broken courtesy path is never mistaken for a broken camera.
+* 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.
 */
-function renderCourtesyJpeg(spec) {
-	return sharp(Buffer.from(buildCourtesySvg(spec))).jpeg({ quality: 82 }).toBuffer().then((bytes) => {
-		if (bytes.length === 0) throw new Error("courtesy frame produced no bytes");
-		return bytes;
-	});
+function createSnapshotMediaHandler(deps) {
+	return async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" }).end();
+			return;
+		}
+		const parsed = parseSnapshotMediaRequest(req.url ?? "/");
+		if (parsed === null) {
+			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);
+		} catch {
+			const body = "Internal server error";
+			res.writeHead(500, {
+				"content-type": "text/plain",
+				"content-length": String(Buffer.byteLength(body))
+			});
+			if (req.method === "HEAD") res.end();
+			else res.end(body);
+			return;
+		}
+		if (media === null) {
+			res.writeHead(404).end();
+			return;
+		}
+		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 (inm === etag) {
+			res.writeHead(304, {
+				etag,
+				"cache-control": cacheControl
+			}).end();
+			return;
+		}
+		res.writeHead(200, {
+			"content-type": media.contentType,
+			"cache-control": cacheControl,
+			etag,
+			"content-length": String(media.bytes.byteLength)
+		});
+		if (req.method === "HEAD") res.end();
+		else res.end(Buffer.from(media.bytes));
+	};
 }
 //#endregion
-//#region src/builtins/snapshot/snapshot-link-url.ts
+//#region src/builtins/snapshot/snapshot-resize.ts
 /**
-* Signed, expiring links to a CLIENT-SIZED snapshot frame.
-*
-* ## Why a link plane exists at all
+* Downscaling a captured frame to a card-sized thumbnail.
 *
-* The authenticated `/addon/snapshot/media/<id>.jpg` plane works, and it is not
-* going away. What it cannot do is guarantee that a client asking for a tile
-* actually REACHES the server — and that turned out to be the whole bug.
+* 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.
 *
-* Under D93 the image URL is versioned by the frame identity, and an image
-* request is what signalled demand for a camera. Both halves are satisfied by
-* the client's own image cache: `expo-image` is URL-keyed and never
-* revalidates, so a URL the app painted in a previous session is served from
-* disk with **zero network**. Measured on the live hub, reopening the app after
-* two minutes idle painted 15 of 16 tiles from disk — frames **168 s old**, with
-* not one HTTP request, therefore no demand, therefore no capture. The
-* operator's report ("gli snapshot sono vecchi, devo aggiornare più volte") is
-* that measurement.
+* ── Why sharp and not ffmpeg (2026-08-11) ─────────────────────────────────
+* This used to `spawn('ffmpeg')` per resize. The snapshot wrapper is a system
+* builtin, so it loads in the hub's ROOT process: sampled on the live hub,
+* ~1.6 of those children were running at any instant, every one of them
+* parented by the root PID.
 *
-* That gap used to be covered on BOTH sides — by this link plane and by a
-* server-side keep-warm timer. The timer was removed on 2026-08-11 (operator
-* directive: snapshots are on-demand, always), which makes this plane the only
-* thing standing between a client cache and a frozen tile. It carries the whole
-* job now.
+* Be precise about what that cost the root process, because it is easy to
+* overstate. The transcode itself ran in the CHILD and was charged to ffmpeg
+* (16 % + 13 % of a core in that same sample), not to the parent. What the
+* parent paid was the fork, the exec, the JPEG written into one pipe and read
+* back out of the other, and the base64 — real event-loop work, on the loop
+* that also serves the tRPC API, but NOT the 52 ms below.
 *
-* A minted link breaks the loop from both ends. It is produced by an RPC —
-* `snapshot.getSnapshotLinks` — which no image cache can answer, so the demand
-* signal always lands; and it carries the capture identity the RPC just WAITED
-* for, rather than one a cache-only poll happened to be holding.
+* Benchmarked in that container, 2560×1440 → 640 wide, wall-clock per resize:
 *
-* ## What is signed, and what is only a cache key
+*     ffmpeg   52.0 ms   (fork + exec + pipe round-trip + teardown)
+*     sharp     4.8 ms   (in-process libvips, on its own threadpool)
 *
-* The signature covers `"<deviceId>:<width>"` and the expiry. The width is
-* inside it deliberately: a leaked 240 px tile link must not be replayable as a
-* request for the full 4 K frame. `v` (the capture identity) is NOT signed — it
-* exists only to key the client's image cache, so an unchanged frame is a
-* byte-identical URL and costs no bytes, and a new frame is a new URL and costs
-* exactly one fetch.
+* So this removes ~29 % of a core of container CPU and the per-resize process
+* churn from the root process. It was NOT verified to be the cause of that
+* process sitting at 90 % — nobody has profiled it.
 *
-* `exp` is bucketed rather than exact. A URL that were unique per mint would
-* defeat the client cache completely — correct for freshness, and it would make
-* a phone re-download every tile on every 5 s poll whether or not anything
-* changed. Bucketing means the URL moves when the FRAME moves, and otherwise at
-* most once per bucket.
+* `sharp` is not a new dependency: it is already a host-external
+* (`HOST_EXTERNAL_SPECIFIERS`), already resolved from the framework closure at
+* runtime, and already used by the terminal frame renderer. The build preset
+* keeps it out of the bundle, so this import costs nothing at pack time.
 *
-* Pure and side-effect-free; the addon owns the secret and the clock. Unit
-* tested in `__tests__/snapshot-link-url.spec.ts`.
+* The cost is still one resize per (device, stream, width) per cache window —
+* not one per request. What changed is what a resize COSTS.
 */
+var RESIZE_TIMEOUT_MS = 1e4;
 /**
-* How long a minted link stays valid.
-*
-* A snapshot is a live view of the operator's home, so this is short on purpose
-* — the exposure of a leaked link is bounded by it. Two minutes is long enough
-* that a page renders, re-renders and survives a brief backgrounding on the URL
-* it was given, and short enough that a link pasted somewhere is dead before it
-* is useful. The client re-mints on every overview poll (5 s), so it never
-* depends on the tail of this window.
+* Encode quality for a derived thumbnail. Matches what the ffmpeg path
+* produced (`-q:v 5` on the mjpeg encoder) closely enough that no card visibly
+* changes — this migration is about COST, not about re-tuning the picture.
 */
-var SNAPSHOT_LINK_TTL_MS = 12e4;
+var JPEG_QUALITY = 82;
 /**
-* Quantum the expiry is rounded UP to, so a link is stable between mints.
+* Scale to `width`, preserving aspect ratio.
 *
-* Without it every mint produces a different `exp`, hence a different URL, hence
-* a full re-download of an unchanged frame on every poll. With it the URL is a
-* pure function of (device, width, frame, bucket) — so a tile fetches when its
-* frame moves, and at most once more per bucket.
-*/
-var SNAPSHOT_LINK_EXP_BUCKET_MS = 3e4;
-/** The token the signature is computed over. Width is part of the identity so a
-*  tile link cannot be escalated into a full-frame request. */
-function snapshotLinkId(deviceId, width) {
-	return `${String(deviceId)}:${width === void 0 ? "full" : String(width)}`;
-}
-/** The bucketed expiry for a link minted at `nowMs`. Always ≥ `nowMs + TTL`. */
-function snapshotLinkExpiry(nowMs, ttlMs = SNAPSHOT_LINK_TTL_MS, bucketMs = SNAPSHOT_LINK_EXP_BUCKET_MS) {
-	return Math.ceil((nowMs + ttlMs) / bucketMs) * bucketMs;
-}
-/**
-* The link, as a ROOT-RELATIVE path.
+* Rejects on failure or 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 module exists to fix, and nobody would
+* see it. The caller decides, and logs.
 *
-* Deliberately not absolute. The artifact and HA planes must mint absolute URLs
-* because the fetcher is a phone or a notifier backend that has no idea where
-* the hub is — and picking that base is the `hubUrl: localhost` trap the Alexa
-* work paid for. Here the fetcher is a client that is already connected to the
-* hub and holds its own `serverUrl`, so the correct base is the one it used to
-* make the call. Returning a path makes it impossible to hand a client a link
-* pointing somewhere it cannot reach.
+* It DOES upscale a source narrower than `width`, and that is deliberate. A
+* `withoutEnlargement: true` was tried first — it is the obvious saving, since
+* upscaling pays encode cost for a blurrier, larger image. But the caller
+* stamps the response ETag from the width it asked for, and its resize-FAILURE
+* path already returns `width: undefined` specifically so a response can never
+* "claim a width the bytes do not have". Silently returning 320 px bytes for a
+* `w=640` request breaks that invariant on the SUCCESS path, where nobody is
+* looking. Honest output width beats a few saved pixels; revisit only together
+* with the ETag.
 */
-function buildSnapshotLinkUrl(input) {
-	const base = (input.routePrefix.startsWith("/") ? input.routePrefix : `/${input.routePrefix}`).replace(/\/+$/, "");
-	const id = snapshotLinkId(input.deviceId, input.width);
-	const sig = signExpiringUrl(input.secret, id, input.expMs);
-	const params = new URLSearchParams();
-	if (input.width !== void 0) params.set("w", String(input.width));
-	if (input.capturedAt !== null) params.set("v", String(input.capturedAt));
-	params.set("exp", String(input.expMs));
-	params.set("sig", sig);
-	return `${base}/${String(input.deviceId)}.jpg?${params.toString()}`;
+function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
+	const work = sharp(bytes).resize({ width }).jpeg({
+		quality: JPEG_QUALITY,
+		mozjpeg: false
+	}).toBuffer().then((out) => {
+		if (out.length === 0) throw new Error("snapshot resize produced no bytes");
+		return out;
+	});
+	let timer;
+	const bound = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`snapshot resize timed out after ${String(timeoutMs)}ms`)), timeoutMs);
+	});
+	return Promise.race([work, bound]).finally(() => {
+		if (timer !== void 0) clearTimeout(timer);
+	});
 }
 /**
-* Parse and VERIFY a link request in one step, so a caller cannot accidentally
-* use the device id before checking the signature. Null = refuse (404/403);
-* there is deliberately no way to distinguish "bad signature" from "expired"
-* from "malformed" at this boundary, so a public route cannot be probed.
+* 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.
 */
-function parseVerifiedSnapshotLink(input) {
-	const qIdx = input.url.indexOf("?");
-	const rawPath = qIdx === -1 ? input.url : input.url.slice(0, qIdx);
-	const query = qIdx === -1 ? "" : input.url.slice(qIdx + 1);
-	const segment = rawPath.replace(/^\/+/, "");
-	if (segment.length === 0 || segment.includes("/")) return null;
-	const idPart = segment.replace(/\.jpe?g$/i, "");
-	if (!/^\d+$/.test(idPart)) return null;
-	const deviceId = Number.parseInt(idPart, 10);
-	if (!Number.isSafeInteger(deviceId) || deviceId <= 0) return null;
-	const params = new URLSearchParams(query);
-	const rawWidth = params.get("w");
-	if (rawWidth !== null && !/^\d+$/.test(rawWidth)) return null;
-	const width = rawWidth === null ? void 0 : Number.parseInt(rawWidth, 10);
-	if (width !== void 0 && (!Number.isSafeInteger(width) || width <= 0)) return null;
-	return verifyExpiringUrl({
-		secret: input.secret,
-		id: snapshotLinkId(deviceId, width),
-		exp: params.get("exp") ?? void 0,
-		sig: params.get("sig") ?? void 0,
-		nowMs: input.nowMs
-	}) ? {
-		deviceId,
-		width
-	} : null;
-}
+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
 /**
@@ -833,7 +833,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	captureFlight = new SingleFlight(COALESCE_MS, (outcome) => outcome.ok && outcome.image !== null);
 	/** Bounds simultaneous ffmpeg keyframe grabs (the wrapper path — common case). */
-	grabPool = new Semaphore(3);
+	grabPool = new Semaphore(6);
 	/** Bounds simultaneous native (vendor HTTP/ONVIF) snapshot fetches. */
 	nativePool = new Semaphore(6);
 	/**
@@ -888,6 +888,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			getSnapshotOverview: (input) => this.getSnapshotOverview(input),
 			getSnapshotLinks: (input) => this.getSnapshotLinks(input)
 		};
+		this.subscribe({ category: EventCategory.DeviceUnregistered }, (event) => {
+			const deviceId = event.data.deviceId;
+			if (typeof deviceId === "number") this.evictRemovedDevice(deviceId, "device-unregistered");
+		});
 		await this.serveMediaDataPlane();
 		await this.serveLinkDataPlane();
 		return [{
@@ -1088,7 +1092,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		await this.getSnapshot({
 			deviceId,
 			force: false
-		}, LINK_MINT_DEADLINE_MS, LINK_CURRENT_MAX_AGE_MS).catch(() => null);
+		}, LINK_MINT_DEADLINE_MS, LINK_CURRENT_MAX_AGE_MS, LINK_MINT_DEADLINE_MS).catch(() => null);
 		const current = this.cache.latest(deviceId)?.ts ?? null;
 		if (alreadyCurrent || current !== null && (before === null || current > before)) return;
 		this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
@@ -1252,7 +1256,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY) {
+	async getSnapshot(input, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY, maximumCaptureWaitMs = Number.POSITIVE_INFINITY) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1310,9 +1314,9 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, Math.max(decision.waitMs, minimumCaptureWaitMs));
+		const raced = await raceForResult(flight, Math.min(Math.max(decision.waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
 		if (raced.settled) try {
-			const resolved = this.resolveOutcome(raced.value, deviceId, hit, log);
+			const resolved = await this.resolveOutcome(raced.value, deviceId, hit, log);
 			if (resolved !== null) return resolved;
 			return meta?.online === false ? await this.courtesyImage(deviceId, "offline", deviceName) : null;
 		} catch (err) {
@@ -1344,30 +1348,54 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* falls back to stale cache (or null); a HARD native error with no frame
 	* and no cache propagates.
 	*/
-	resolveOutcome(outcome, deviceId, hit, log) {
+	async resolveOutcome(outcome, deviceId, hit, log) {
 		if (outcome.ok) {
 			if (outcome.image) return outcome.image;
 			if (hit) {
 				const ageMs = Date.now() - hit.ts;
-				if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
-					tags: { deviceId },
-					meta: { ageMs }
-				});
+				if (ageMs > this.config.staleTtlMs) {
+					if (await this.staleHitBelongsToRemovedDevice(deviceId, ageMs)) return null;
+					log.warn("snapshot: all live paths failed — serving stale cache", {
+						tags: { deviceId },
+						meta: { ageMs }
+					});
+				}
 				return hit.data;
 			}
 			return null;
 		}
 		if (hit) {
 			const ageMs = Date.now() - hit.ts;
-			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: native failed — serving stale cache", {
-				tags: { deviceId },
-				meta: { ageMs }
-			});
+			if (ageMs > this.config.staleTtlMs) {
+				if (await this.staleHitBelongsToRemovedDevice(deviceId, ageMs)) return null;
+				log.warn("snapshot: native failed — serving stale cache", {
+					tags: { deviceId },
+					meta: { ageMs }
+				});
+			}
 			return hit.data;
 		}
 		throw outcome.error;
 	}
 	/**
+	* Reconcile backstop for a stale hit: is the frame we are about to serve the
+	* property of a device that no longer exists?
+	*
+	* Asked ONLY past `staleTtlMs`, which is already the "something is wrong"
+	* threshold — so the common path costs nothing. A `true` answer evicts and
+	* the caller returns null; anything else leaves the existing
+	* keep-the-UI-from-going-blank contract untouched.
+	*/
+	async staleHitBelongsToRemovedDevice(deviceId, ageMs) {
+		if (await this.deviceStillExists(deviceId) !== false) return false;
+		this.evictRemovedDevice(deviceId, "stale-hit-absent");
+		this.ctx.logger.debug("snapshot: refused a stale frame for a device that is gone", {
+			tags: { deviceId },
+			meta: { ageMs }
+		});
+		return true;
+	}
+	/**
 	* Run the capture ladder ONCE for a device: native provider first, then the
 	* stream-broker ffmpeg fallback. Never rejects — resolves a {@link
 	* CaptureOutcome}. On a produced frame it populates the cache (so a
@@ -1575,9 +1603,48 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		};
 	}
 	async invalidateCache(input) {
-		this.cache.deleteDevice(input.deviceId);
-		this.variants.deleteDevice(input.deviceId);
-		this.captureFlight.invalidatePrefix(`${input.deviceId}:`);
+		this.dropDeviceCaches(input.deviceId);
+	}
+	/** Forget every cached artefact of one device: frames, derived variants and
+	*  any settled single-flight result that would answer the next request. */
+	dropDeviceCaches(deviceId) {
+		this.cache.deleteDevice(deviceId);
+		this.variants.deleteDevice(deviceId);
+		this.captureFlight.invalidatePrefix(`${deviceId}:`);
+	}
+	/**
+	* The device is GONE — drop its cached frames and say so.
+	*
+	* Distinct from `invalidateCache` (a refresh, expected and silent): this is
+	* the terminal case, and a deleted camera that keeps answering with its last
+	* JPEG looks to an operator exactly like a camera that was never deleted.
+	*/
+	evictRemovedDevice(deviceId, reason) {
+		this.dropDeviceCaches(deviceId);
+		this.ctx.logger.info("snapshot: dropped cache for removed device", {
+			tags: { deviceId },
+			meta: { reason }
+		});
+	}
+	/**
+	* Does device-manager still know this id?
+	*
+	* `null` means the question could not be answered — a transport hiccup is
+	* not a deletion (D49), and the caller keeps serving what it has. Only an
+	* explicit "no such device" evicts.
+	*/
+	async deviceStillExists(deviceId) {
+		const api = this.ctx.api;
+		if (!api) return null;
+		try {
+			return await api.deviceManager.getDevice.query({ deviceId }) ? true : false;
+		} catch (err) {
+			this.ctx.logger.debug("snapshot: device existence check failed — keeping cache", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return null;
+		}
 	}
 	/**
 	* Sleep state from the device-state MIRROR, not from a cap round-trip.