@camstack/system 1.2.78 → 1.2.80

package/dist/builtins/snapshot/index.mjs

@@ -1,8 +1,9 @@
-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, 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-coalescing.ts
 /**
 * Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
@@ -355,7 +356,7 @@ function createSnapshotMediaHandler(deps) {
 *  per-device preference decides what it captures, and conflating it with an
 *  explicit request is how the original bug read. */
 var AUTO = "auto";
-function keyOf$1(deviceId, streamId) {
+function keyOf(deviceId, streamId) {
 	return `${deviceId}:${streamId ?? AUTO}`;
 }
 var SnapshotCache = class {
@@ -363,10 +364,10 @@ var SnapshotCache = class {
 	/** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
 	keysByDevice = /* @__PURE__ */ new Map();
 	get(deviceId, streamId) {
-		return this.byKey.get(keyOf$1(deviceId, streamId));
+		return this.byKey.get(keyOf(deviceId, streamId));
 	}
 	set(deviceId, streamId, entry) {
-		const key = keyOf$1(deviceId, streamId);
+		const key = keyOf(deviceId, streamId);
 		this.byKey.set(key, entry);
 		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
 		keys.add(key);
@@ -408,80 +409,75 @@ var SnapshotCache = class {
 * 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`.
+* ── 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.
+*
+* 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.
+*
+* Benchmarked in that container, 2560×1440 → 640 wide, wall-clock per resize:
 *
-* `ffmpeg` is already this addon's dependency (the keyframe grab shells out to
-* it), so this adds no new one.
+*     ffmpeg   52.0 ms   (fork + exec + pipe round-trip + teardown)
+*     sharp     4.8 ms   (in-process libvips, on its own threadpool)
+*
+* 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.
+*
+* `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 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;
 /**
-* Scale to `width`, preserving aspect ratio (`-2` keeps the height even, which
-* mjpeg requires).
+* 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 JPEG_QUALITY = 82;
+/**
+* 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.
 *
-* 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.
+* 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 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);
+	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);
 	});
 }
 /**
@@ -526,122 +522,107 @@ var SnapshotVariantCache = class SnapshotVariantCache {
 	}
 };
 //#endregion
-//#region src/builtins/snapshot/snapshot-keep-warm.ts
+//#region src/builtins/snapshot/snapshot-courtesy.ts
 /**
-* Subscription bookkeeping for the snapshot keep-warm loop.
+* 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").
 *
-* 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.
+* 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.
 *
-* 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.
+* ── 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.
 *
-* 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`.
+* `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.
 */
 /**
-* 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.
+* 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 WARM_INTERVAL_MS = 5e3;
+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";
+	}
+}
 /**
-* 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.
+* 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.
 */
-var WARM_WINDOW_MS = 12e4;
-function keyOf(deviceId, streamId) {
-	return `${deviceId}:${streamId ?? "auto"}`;
+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;");
 }
 /**
-* Who is being watched right now, and at what sizes.
+* The SVG the frame is rasterized from: the state large and centred, the
+* camera's name under it, smaller and dimmer.
 *
-* `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.
+* 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.
 */
-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();
-	}
-};
+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
 /**
@@ -654,14 +635,20 @@ var SnapshotSubscriptions = class {
 * 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 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
+* 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 not one enrolment, therefore nothing warming.
-* The operator's report ("gli snapshot sono vecchi, devo aggiornare più volte")
-* is that measurement.
+* 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
@@ -831,6 +818,15 @@ 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.
@@ -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
@@ -905,7 +890,6 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		};
 		await this.serveMediaDataPlane();
 		await this.serveLinkDataPlane();
-		this.scheduleWarmTick();
 		return [{
 			capability: snapshotCapability,
 			provider
@@ -1051,14 +1035,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 +1088,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).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 +1119,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 +1164,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 +1210,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 +1252,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) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1375,6 +1263,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 +1272,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 +1298,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({
@@ -1421,7 +1311,17 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		}));
 		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);
+		if (raced.settled) try {
+			const resolved = 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 +1332,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;
 	}
 	/**
@@ -1745,7 +1649,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 +1737,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 +1806,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", {