@camstack/system 1.2.79 → 1.2.81

package/dist/builtins/snapshot/index.mjs

@@ -1,8 +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-CIIFhXqm.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, spawn } from "node:child_process";
+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
@@ -198,6 +247,241 @@ function raceForResult(promise, timeoutMs) {
 	});
 }
 //#endregion
+//#region src/builtins/snapshot/snapshot-courtesy.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.
+*
+* `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.
+*/
+/**
+* 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";
+	}
+}
+/**
+* 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 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 SVG the frame is rasterized from: the state large and centred, the
+* camera's name under it, smaller and dimmer.
+*
+* 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 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}`;
+}
+/**
+* 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 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-link-url.ts
+/**
+* Signed, expiring links to a CLIENT-SIZED snapshot frame.
+*
+* ## Why a link plane exists at all
+*
+* 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.
+*
+* 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.
+*
+* 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.
+*
+* 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.
+*
+* ## What is signed, and what is only a cache key
+*
+* 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.
+*
+* `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`.
+*/
+/**
+* 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 SNAPSHOT_LINK_TTL_MS = 12e4;
+/**
+* Quantum the expiry is rounded UP to, so a link is stable between mints.
+*
+* 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.
+*
+* 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.
+*/
+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-media-handler.ts
 /**
 * The widths a thumbnail may be served at.
@@ -348,427 +632,130 @@ function createSnapshotMediaHandler(deps) {
 		if (req.method === "HEAD") res.end();
 		else res.end(Buffer.from(media.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$1(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$1(deviceId, streamId));
-	}
-	set(deviceId, streamId, entry) {
-		const key = keyOf$1(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-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-link-url.ts
+//#region src/builtins/snapshot/snapshot-resize.ts
 /**
-* Signed, expiring links to a CLIENT-SIZED snapshot frame.
+* Downscaling a captured frame to a card-sized thumbnail.
 *
-* ## Why a link plane exists at all
+* 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 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.
+* ── 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.
 *
-* Under D93 the image URL is versioned by the frame identity, and an image
-* request is what enrols a camera in the keep-warm loop. 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 not one enrolment, therefore nothing warming.
-* The operator's report ("gli snapshot sono vecchi, devo aggiornare più volte")
-* is that measurement.
+* 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
 /**
@@ -831,13 +818,22 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*  against the source frame's timestamp. */
 	variants = new SnapshotVariantCache();
 	/**
+	* Rendered courtesy frames, by (reason, size, device name).
+	*
+	* A courtesy frame is a pure function of those three, so it is rendered once
+	* and reused for as long as the process lives — a disabled camera must not
+	* cost an ffmpeg run per poll. Unbounded on purpose: the key space is
+	* (3 reasons × this node's own cameras), not user input.
+	*/
+	courtesyFrames = /* @__PURE__ */ new Map();
+	/**
 	* De-dupes concurrent captures per `${deviceId}:${streamId}` and holds a
 	* settled SUCCESS for COALESCE_MS so a grid-mount burst (and a row of refresh
 	* buttons) collapses into one capture instead of one dial per tile.
 	*/
 	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);
 	/**
@@ -869,17 +865,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*  currently holding, which is a fleet-wide blank grid after each restart. */
 	linkSecret = null;
 	/**
-	* 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
@@ -903,9 +888,12 @@ 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();
-		this.scheduleWarmTick();
 		return [{
 			capability: snapshotCapability,
 			provider
@@ -1051,14 +1039,11 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	async getSnapshotLinks(input) {
 		const secret = await this.ensureLinkSecret();
-		const now = Date.now();
-		const expMs = snapshotLinkExpiry(now, SNAPSHOT_LINK_TTL_MS);
+		const expMs = snapshotLinkExpiry(Date.now(), SNAPSHOT_LINK_TTL_MS);
 		const served = this.linkDataPlane !== null && secret !== null;
 		const prefix = this.linkRoutePrefix();
 		const sleepingByDevice = /* @__PURE__ */ new Map();
 		const refreshes = input.targets.map(async (target) => {
-			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
-			this.subscriptions.note(target.deviceId, void 0, width, now);
 			const sleeping = await this.isSleepingBatteryDevice(target.deviceId);
 			sleepingByDevice.set(target.deviceId, sleeping);
 			if (!sleeping) await this.awaitFreshEnough(target.deviceId);
@@ -1107,7 +1092,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		await this.getSnapshot({
 			deviceId,
 			force: false
-		}, 0, 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", {
@@ -1138,7 +1123,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
 	*/
 	async resolveSnapshotMedia(deviceId, streamId, force, width) {
-		this.subscriptions.note(deviceId, streamId, width, Date.now());
 		const image = await this.getSnapshot({
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
@@ -1184,92 +1168,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		};
 	}
 	/**
-	* Schedule the next warm tick. A CHAINED timer, not `setInterval`: the next
-	* tick is armed only after the previous one settles, so a fleet that is slower
-	* than the interval degrades to "as fast as it can" instead of stacking ticks
-	* on top of each other and exhausting the ffmpeg pool.
-	*
-	* `unref` so the loop never holds the process open.
-	*/
-	scheduleWarmTick() {
-		if (this.stopped) return;
-		this.warmTimer = setTimeout(() => {
-			this.runWarmTick().finally(() => {
-				this.scheduleWarmTick();
-			});
-		}, WARM_INTERVAL_MS);
-		this.warmTimer.unref?.();
-	}
-	/**
-	* Refresh the cache for every camera somebody is currently looking at.
-	*
-	* Deliberately NOT a blind poll of the whole fleet: with nobody watching this
-	* walks an empty list and costs nothing, which is the entire difference
-	* between this and a background poller.
-	*
-	* Battery cameras need no special case here and must not get one. A warm tick
-	* is a plain non-forced `getSnapshot`, so it meets the two gates that already
-	* exist — the 3600 s battery max-age (which makes the tick a cache hit) and
-	* the sleeping-battery gate (which refuses to capture without `force`). A
-	* second battery check here would be a rule that disagrees with the authority
-	* that already owns it.
-	*/
-	async runWarmTick() {
-		if (this.warmTickRunning || this.stopped) return;
-		this.warmTickRunning = true;
-		const logger = this.ctx.logger;
-		try {
-			const targets = this.subscriptions.active(Date.now());
-			if (targets.length === 0) return;
-			const failed = (await Promise.allSettled(targets.map((t) => this.warmOne(t, logger)))).filter((r) => r.status === "rejected").length;
-			logger.debug("snapshot: keep-warm tick", { meta: {
-				watched: targets.length,
-				failed
-			} });
-		} catch (err) {
-			logger.warn("snapshot: keep-warm tick failed", { meta: { error: errMsg(err) } });
-		} finally {
-			this.warmTickRunning = false;
-		}
-	}
-	/**
-	* Warm one (device, stream): refresh the frame, then pre-derive the widths
-	* that were actually requested.
-	*
-	* Deriving the variants matters as much as the capture. Warming only the full
-	* frame would leave every grid tile still paying an ffmpeg resize on the
-	* request path — the cache would be fresh and the tile would still be slow.
-	*/
-	async warmOne(target, logger) {
-		const work = this.warmOneUnbounded(target, logger);
-		work.catch(() => void 0);
-		if (!(await raceForResult(work, 5e3)).settled) logger.debug("snapshot: keep-warm still in flight past the tick — leaving it to land", { tags: { deviceId: target.deviceId } });
-	}
-	async warmOneUnbounded(target, logger) {
-		const { deviceId, streamId, widths } = target;
-		try {
-			if (this.stopped) return;
-			const image = await this.getSnapshot({
-				deviceId,
-				...streamId !== void 0 ? { streamId } : {},
-				force: false
-			}, WARM_INTERVAL_MS);
-			if (!image) return;
-			const capturedAt = this.cache.get(deviceId, streamId)?.ts;
-			if (capturedAt === void 0) return;
-			const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
-			for (const width of widths) {
-				if (this.stopped) return;
-				await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs);
-			}
-		} catch (err) {
-			logger.debug("snapshot: keep-warm failed for device", {
-				tags: { deviceId },
-				meta: { error: errMsg(err) }
-			});
-		}
-	}
-	/**
 	* The frame at a card-sized width, derived once per (device, stream, width)
 	* per capture.
 	*
@@ -1316,12 +1214,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}
 	}
 	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;
@@ -1364,7 +1256,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, warmAheadMs = 0, 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);
@@ -1375,6 +1267,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			...deviceName ? { deviceName } : {}
 		});
 		const now = Date.now();
+		if (meta?.disabled === true) return await this.courtesyImage(deviceId, "disabled", deviceName);
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
 		const rawPref = prefs.snapshotStreamId;
 		const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
@@ -1383,7 +1276,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
 		const hit = this.cache.get(deviceId, effectiveStreamId);
-		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs));
+		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3));
 		const decision = decideSnapshotServe({
 			now,
 			cachedAt: hit?.ts ?? null,
@@ -1409,7 +1302,8 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 					ageMs: hit ? now - hit.ts : null
 				}
 			});
-			return hit ? hit.data : null;
+			if (hit) return hit.data;
+			return await this.courtesyImage(deviceId, "sleeping", deviceName);
 		}
 		const flightKey = `${deviceId}:${effectiveStreamId ?? "auto"}`;
 		const flight = this.captureFlight.run(flightKey, () => this.captureFresh({
@@ -1420,8 +1314,18 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, Math.max(decision.waitMs, minimumCaptureWaitMs));
-		if (raced.settled) return this.resolveOutcome(raced.value, deviceId, hit, log);
+		const raced = await raceForResult(flight, Math.min(Math.max(decision.waitMs, minimumCaptureWaitMs), maximumCaptureWaitMs));
+		if (raced.settled) try {
+			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) {
+			if (meta?.online === false) {
+				const courtesy = await this.courtesyImage(deviceId, "offline", deviceName);
+				if (courtesy !== null) return courtesy;
+			}
+			throw err;
+		}
 		if (decision.staleFallback && hit) {
 			if (prefs.snapshotDebug) log.debug("snapshot: SWR — returning stale frame; refresh continues in background", {
 				tags: { deviceId },
@@ -1432,6 +1336,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			});
 			return hit.data;
 		}
+		if (meta?.online === false) {
+			const courtesy = await this.courtesyImage(deviceId, "offline", deviceName);
+			if (courtesy !== null) return courtesy;
+		}
 		return null;
 	}
 	/**
@@ -1440,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
@@ -1671,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.
@@ -1745,7 +1716,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*/
 	getSnapshotOverview(input) {
 		const now = Date.now();
-		this.subscriptions.renew(input.deviceIds, now);
 		const rows = input.deviceIds.map((deviceId) => {
 			const hit = this.cache.latest(deviceId);
 			if (!hit) return {
@@ -1834,6 +1804,56 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}] };
 	}
 	/**
+	* The frame a camera that CANNOT capture answers with.
+	*
+	* Returns null only if rendering itself fails — the caller then falls through
+	* to its previous behaviour, so a broken courtesy path degrades to the old
+	* 404 rather than masking a real capture failure as a placeholder.
+	*
+	* Rendered at the full tile size; the existing resize ladder derives the
+	* card-sized variants from it exactly as it does for a real frame, so no
+	* downstream consumer needs to know this frame is synthetic.
+	*/
+	async courtesyFrame(deviceId, reason, deviceName) {
+		const width = 640;
+		const height = Math.round(width * 9 / 16);
+		const key = courtesyCacheKey({
+			deviceName,
+			reason,
+			width,
+			height
+		});
+		const cached = this.courtesyFrames.get(key);
+		if (cached !== void 0) return cached;
+		try {
+			const bytes = await renderCourtesyJpeg({
+				deviceName,
+				reason,
+				width,
+				height
+			});
+			this.courtesyFrames.set(key, bytes);
+			return bytes;
+		} catch (err) {
+			this.ctx.logger.warn("snapshot: courtesy frame failed — falling back to no image", {
+				tags: { deviceId },
+				meta: {
+					reason,
+					error: errMsg(err)
+				}
+			});
+			return null;
+		}
+	}
+	/** A courtesy frame shaped as the cap's response, or null when unrenderable. */
+	async courtesyImage(deviceId, reason, deviceName) {
+		const bytes = await this.courtesyFrame(deviceId, reason, deviceName ?? `#${String(deviceId)}`);
+		return bytes === null ? null : {
+			base64: bytes.toString("base64"),
+			contentType: "image/jpeg"
+		};
+	}
+	/**
 	* Single-trip device lookup against device-manager. Returns the
 	* fields the wrapper actually consults — name (logging) + battery
 	* flag (cache window + broker-fallback gate). Sourced from the
@@ -1853,10 +1873,13 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			if (!found) return null;
 			const features = found.features ?? [];
 			const rawType = found.type;
+			const row = found;
 			return {
 				...found.name ? { name: found.name } : {},
 				isBattery: features.includes(DeviceFeature.BatteryOperated),
-				...rawType ? { type: rawType } : {}
+				...rawType ? { type: rawType } : {},
+				disabled: row.disabled === true,
+				online: row.online !== false
 			};
 		} catch (err) {
 			this.ctx.logger.debug("deviceManager.getDevice failed during snapshot", {