@camstack/core 0.1.15 → 0.1.17

package/dist/builtins/snapshot/index.mjs

@@ -1,477 +1,488 @@
-// src/builtins/snapshot/snapshot.addon.ts
-import { execFile } from "child_process";
-import { DeviceFeature, DeviceType, snapshotCapability } from "@camstack/types";
-import { BaseAddon, errMsg, streamQualityLabel } from "@camstack/types";
+import { execFile } from "node:child_process";
+import { BaseAddon, DeviceFeature, DeviceType, errMsg, snapshotCapability, streamQualityLabel } from "@camstack/types";
+//#region src/builtins/snapshot/snapshot.addon.ts
+/** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
+/** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
 var BATTERY_DEFAULT_MAX_AGE_S = 3600;
+/**
+* SnapshotAddon — wrapper over the `snapshot` capability.
+*
+* Activated per-device (toggleable by user; default active). When active,
+* caches fresh snapshots in memory. On cache miss, delegates to the native
+* provider for this device via `ctx.getNativeProvider(snapshotCapability, id)`.
+*
+* No silent fallback — if the native fails, propagate the error up. Stale
+* cache is returned ONLY when the native throws AND a stale entry exists,
+* and the failure is logged so the fallback is never silent.
+*
+* Frame-grab fallback: when the native provider is absent (or returns null /
+* throws), we ask the `stream-broker` capability for the device's RTSP
+* restream URL and pipe one JPEG out of ffmpeg. stream-broker intentionally
+* does NOT expose a `grabFrame` method — the orchestration (native-first,
+* ffmpeg fallback, caching) is this addon's concern; stream-broker only
+* publishes stream endpoints.
+*/
 var SnapshotAddon = class extends BaseAddon {
-  cache = /* @__PURE__ */ new Map();
-  constructor() {
-    super({
-      staleTtlMs: 6e4
-    });
-  }
-  async onInitialize() {
-    this.ctx.logger.info("Snapshot wrapper initialized");
-    const provider = {
-      getSnapshot: (input) => this.getSnapshot(input),
-      invalidateCache: (input) => this.invalidateCache(input),
-      // DeviceSettingsContribution surface — numeric deviceId end-to-end.
-      getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
-      getDeviceLiveContribution: async () => null,
-      applyDeviceSettingsPatch: (input) => this.saveDeviceSettingsPatch(input.deviceId, input.patch),
-      // Status surface — derives a diagnostic snapshot from the cache
-      // bookkeeping (lastCapturedAt, cacheAgeMs, lastBytes, lastStreamId).
-      // Returns null when the device has never been captured.
-      getStatus: async (input) => this.getStatus(input.deviceId)
-    };
-    return [{
-      capability: snapshotCapability,
-      provider,
-      kind: "wrapper",
-      defaultActive: true
-    }];
-  }
-  async onShutdown() {
-    this.cache.clear();
-  }
-  globalSettingsSchema() {
-    return this.schema({
-      sections: [{
-        id: "snapshot-cache",
-        title: "Snapshot Cache",
-        description: "Stale fallback when live capture fails. Per-device freshness is configured under Device \u2192 Snapshot \u2192 Max cache age.",
-        columns: 1,
-        fields: [
-          this.field({
-            type: "number",
-            key: "staleTtlMs",
-            label: "Stale fallback TTL (ms)",
-            description: "If live capture fails, cached snapshot younger than this is still returned.",
-            min: 0,
-            max: 36e5,
-            step: 1e3,
-            default: 6e4
-          })
-        ]
-      }]
-    });
-  }
-  // ── Capability methods ────────────────────────────────────────────────
-  async getSnapshot(input) {
-    const { deviceId, force } = input;
-    const meta = await this.lookupDeviceMeta(deviceId);
-    const deviceName = meta?.name;
-    const isBatteryDevice = meta?.isBattery ?? false;
-    const log = this.ctx.logger.withTags({ deviceId, ...deviceName ? { deviceName } : {} });
-    const now = Date.now();
-    const hit = this.cache.get(deviceId);
-    const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
-    const rawPref = prefs.snapshotStreamId;
-    const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
-    if (prefs.snapshotDebug) {
-      log.info("debug on", { tags: { deviceId }, meta: { stream: effectiveStreamId ?? "auto" } });
-    }
-    const defaultMaxAgeS = isBatteryDevice ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
-    const effectiveMaxAgeMs = (typeof prefs.snapshotMaxAgeS === "number" && prefs.snapshotMaxAgeS >= 0 ? prefs.snapshotMaxAgeS : defaultMaxAgeS) * 1e3;
-    if (!force && hit && now - hit.ts < effectiveMaxAgeMs) {
-      if (prefs.snapshotDebug) {
-        log.debug("snapshot: cache hit", {
-          tags: { deviceId },
-          meta: { ageMs: now - hit.ts, maxAgeMs: effectiveMaxAgeMs, isBattery: isBatteryDevice }
-        });
-      }
-      return hit.data;
-    }
-    let nativeError = null;
-    let nativeAbsent = false;
-    try {
-      const native = this.ctx.getNativeProvider(snapshotCapability, deviceId);
-      if (native) {
-        const result = await native.getSnapshot(input);
-        if (result) {
-          this.cache.set(deviceId, { data: result, ts: now, streamId: effectiveStreamId ?? null });
-          return result;
-        }
-      } else {
-        nativeAbsent = true;
-      }
-    } catch (err) {
-      const msg = errMsg(err);
-      if (isAbsentNativeError(msg)) {
-        nativeAbsent = true;
-        log.debug("native snapshot absent", { tags: { deviceId }, meta: { error: msg } });
-      } else {
-        nativeError = err;
-        log.warn("native snapshot failed", { tags: { deviceId }, meta: { error: msg } });
-      }
-    }
-    const skipBrokerForBattery = isBatteryDevice && nativeAbsent && !await this.hasStreamingBrokerForDevice(deviceId);
-    if (!skipBrokerForBattery) {
-      try {
-        const fallback = await this.grabFrameFromBroker(deviceId, effectiveStreamId);
-        if (fallback) {
-          this.cache.set(deviceId, { data: fallback, ts: now, streamId: effectiveStreamId ?? null });
-          return fallback;
-        }
-      } catch (err) {
-        log.warn("stream-broker snapshot fallback failed", { tags: { deviceId }, meta: { error: errMsg(err) } });
-      }
-    } else {
-      log.debug("snapshot: skipping broker fallback \u2014 battery device with absent native and no streaming broker", {
-        tags: { deviceId }
-      });
-    }
-    if (hit) {
-      const ageMs = now - hit.ts;
-      if (ageMs > this.config.staleTtlMs) {
-        log.warn("snapshot: all live paths failed \u2014 serving stale cache", { tags: { deviceId }, meta: { ageMs } });
-      }
-      return hit.data;
-    }
-    if (nativeError) throw nativeError;
-    if (nativeAbsent) return null;
-    return null;
-  }
-  /**
-   * Tell apart "native provider isn't registered for this device" from
-   * "native provider ran and threw a real error". The former is the steady
-   * state for cameras without a vendor snapshot endpoint and should not
-   * propagate as a 500; the latter should.
-   */
-  /**
-   * Pull one JPEG from the device's stream-broker RTSP restream using
-   * a short-lived ffmpeg invocation.
-   *
-   * Stream selection strategy (picks the broker that won't stall):
-   *   1. Explicit `preferredStreamId` (user set in per-device settings)
-   *      — always honoured, even if currently idle. Operator choice
-   *      wins.
-   *   2. Auto: highest-quality broker currently in `streaming` state.
-   *      This is the whole point — prefer the stream that has active
-   *      subscribers (usually `low` for detection, but `mid`/`high`
-   *      if WebRTC is watching) so ffmpeg hits a warm pipe and
-   *      doesn't race the broker's resume.
-   *   3. Fallback: highest-quality enabled entry regardless of status
-   *      (will wake a suspended broker — retry-guarded against the
-   *      cold-start error).
-   *
-   * The stream-broker auto-suspends idle streams on the "no demand"
-   * signal; snapshots used to default to `high` which was often the
-   * first to go idle, racing every snapshot with a broker resume.
-   * Now we ask the orchestrator of streams which one is warm and grab
-   * from there.
-   */
-  async grabFrameFromBroker(deviceId, preferredStreamId) {
-    const dev = await this.ctx.fetchDevice(deviceId);
-    const prefix = `${deviceId}/`;
-    const [deviceEntries, profileSlots] = await Promise.all([
-      dev.cameraStreams?.getRtspEntries({}) ?? [],
-      dev.cameraStreams?.getBrokerStreams({}) ?? []
-    ]);
-    const usable = deviceEntries.filter((e) => e.enabled && !!e.url);
-    if (usable.length === 0) return null;
-    if (preferredStreamId && preferredStreamId !== "auto") {
-      const explicit = usable.find((e) => e.brokerId === `${prefix}${preferredStreamId}`);
-      if (explicit) {
-        const grabbed = await this.runGrabWithResumeRetry(explicit.url, deviceId);
-        if (grabbed) return grabbed;
-        this.ctx.logger.debug("grabFrame: explicit stream failed \u2014 falling back to auto", { meta: { preferredStreamId } });
-      }
-    }
-    const ranked = [...usable].sort(
-      (a, b) => qualityRank(b.brokerId, prefix) - qualityRank(a.brokerId, prefix)
-    );
-    const statusByBrokerId = /* @__PURE__ */ new Map();
-    for (const slot of profileSlots) statusByBrokerId.set(slot.brokerId, slot.status);
-    const statuses = ranked.map((e) => ({ entry: e, status: statusByBrokerId.get(e.brokerId) ?? "idle" }));
-    const warm = statuses.find((s) => s.status === "streaming");
-    if (warm) {
-      const grabbed = await this.runGrabWithResumeRetry(warm.entry.url, deviceId);
-      if (grabbed) return grabbed;
-    }
-    for (const { entry } of statuses) {
-      const grabbed = await this.runGrabWithResumeRetry(entry.url, deviceId).catch(() => null);
-      if (grabbed) return grabbed;
-    }
-    return null;
-  }
-  /**
-   * Ffmpeg grab with one retry on the broker-cold-start error
-   * signature. Covers the window between "client connected" and
-   * "first keyframe" when a suspended broker resumes.
-   */
-  async runGrabWithResumeRetry(url, deviceId) {
-    let buf;
-    try {
-      buf = await runFfmpegFrameGrab(url, 15e3);
-    } catch (err) {
-      const msg = errMsg(err);
-      if (isBrokerColdError(msg)) {
-        this.ctx.logger.debug("grabFrame: broker-resume race \u2014 retrying in 1500ms", { tags: { deviceId } });
-        await new Promise((r) => setTimeout(r, 1500));
-        buf = await runFfmpegFrameGrab(url, 15e3);
-      } else {
-        throw err;
-      }
-    }
-    if (buf.length === 0) return null;
-    return { base64: buf.toString("base64"), contentType: "image/jpeg" };
-  }
-  async invalidateCache(input) {
-    this.cache.delete(input.deviceId);
-  }
-  /**
-   * Non-throwing probe of the device's battery cap. Returns true only
-   * when a battery native is registered AND its current status says
-   * `sleeping: true`. Any error (no provider, native absent, getStatus
-   * missing, RPC timeout) is swallowed and treated as "awake" — we'd
-   * rather pay a wake-up than strand the caller on a cache that's
-   * semantically stale. Debug-logged for observability.
-   */
-  /**
-   * True when at least one of the device's brokers is actively
-   * streaming (status === 'streaming'). Used by the battery-cam guard
-   * around `grabFrameFromBroker` to allow the fallback ONLY when
-   * grabbing a frame is free (a consumer is already keeping the
-   * stream warm). When everything is suspended, the fallback would
-   * dial the camera and wake it — defeats the sleeping cache.
-   */
-  async hasStreamingBrokerForDevice(deviceId) {
-    try {
-      const dev = await this.ctx.fetchDevice(deviceId);
-      const slots = await dev.cameraStreams?.getBrokerStreams({}) ?? [];
-      return slots.some((s) => s.status === "streaming");
-    } catch {
-      return false;
-    }
-  }
-  /**
-   * Diagnostic status for the `status` auto-injected cap method. Reports
-   * the cache bookkeeping for this device — when the last snapshot was
-   * captured, how stale the cached image is, its size, and which stream
-   * was used. Returns null when the device has never been captured
-   * (cache miss) since the addon started.
-   */
-  async getStatus(deviceId) {
-    const hit = this.cache.get(deviceId);
-    if (!hit) return null;
-    return {
-      lastCapturedAt: hit.ts,
-      cacheAgeMs: Date.now() - hit.ts,
-      lastBytes: hit.data.base64.length,
-      // approx bytes = base64 length * 3/4, but length is stable enough
-      lastStreamId: hit.streamId
-    };
-  }
-  // ── DeviceSettingsContribution ────────────────────────────────────────
-  //
-  // Snapshot carries two per-device knobs:
-  //   - `snapshotStreamId` — which stream to prefer when grabbing frames
-  //     (empty = auto / default "main")
-  //   - `snapshotDebug` — extra logging for troubleshooting snapshot paths
-  //
-  // Storage uses the addon's own per-device store (`ctx.settings
-  // .writeDeviceStore`), not the device's config. The schema isn't
-  // captured in a Zod object: the keys are optional and the UI layer
-  // validates shapes.
-  async readDeviceSettings(deviceId) {
-    if (!this.ctx.settings) return {};
-    const raw = await this.ctx.settings.readDeviceStore(deviceId);
-    const rawAge = raw["snapshotMaxAgeS"];
-    const maxAgeS = typeof rawAge === "number" && rawAge >= 0 && Number.isFinite(rawAge) ? rawAge : void 0;
-    return {
-      snapshotStreamId: typeof raw["snapshotStreamId"] === "string" ? raw["snapshotStreamId"] : void 0,
-      snapshotDebug: raw["snapshotDebug"] === true,
-      ...maxAgeS !== void 0 ? { snapshotMaxAgeS: maxAgeS } : {}
-    };
-  }
-  async buildDeviceSettingsContribution(deviceId) {
-    const meta = await this.lookupDeviceMeta(deviceId);
-    if (meta && meta.type !== DeviceType.Camera) return null;
-    const current = await this.readDeviceSettings(deviceId);
-    const streamOptions = await this.getStreamOptions(deviceId);
-    const isBattery = await this.isDeviceBattery(deviceId);
-    const defaultMaxAgeS = isBattery ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
-    return {
-      sections: [{
-        id: "snapshot-preferences",
-        title: "Snapshot",
-        tab: "snapshot",
-        order: 60,
-        fields: [
-          {
-            type: "select",
-            key: "snapshotStreamId",
-            label: "Preferred stream",
-            description: "Stream used when grabbing a snapshot",
-            options: streamOptions,
-            required: true,
-            value: current.snapshotStreamId || "auto"
-          },
-          {
-            type: "number",
-            key: "snapshotMaxAgeS",
-            label: "Max cache age (s)",
-            description: `Serve cached snapshot up to this age before re-capturing. Default ${defaultMaxAgeS}s for ${isBattery ? "battery cams (avoids gratuitous wake-ups)" : "non-battery cams (live-feel)"}. The UI refresh button always forces a fresh capture regardless of this value.`,
-            min: 0,
-            max: 24 * 3600,
-            step: 1,
-            value: current.snapshotMaxAgeS ?? defaultMaxAgeS
-          },
-          {
-            type: "boolean",
-            key: "snapshotDebug",
-            label: "Debug logging",
-            description: "Log stream selection and timing details for this device.",
-            value: current.snapshotDebug ?? false
-          }
-        ]
-      }]
-    };
-  }
-  /**
-   * 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
-   * device-manager registry rather than the battery cap so the answer
-   * survives a momentarily-unreachable provider (the very condition
-   * we're trying to be resilient to).
-   *
-   * Logged at debug + null return on failure: every call site already
-   * has a sensible fallback path (cache hit, conservative default, …),
-   * so we don't want a transient device-manager hiccup to throw.
-   */
-  async lookupDeviceMeta(deviceId) {
-    const api = this.ctx.api;
-    if (!api) return null;
-    try {
-      const found = await api.deviceManager.getDevice.query({ deviceId });
-      if (!found) return null;
-      const features = found.features ?? [];
-      const rawType = found.type;
-      return {
-        ...found.name ? { name: found.name } : {},
-        isBattery: features.includes(DeviceFeature.BatteryOperated),
-        ...rawType ? { type: rawType } : {}
-      };
-    } catch (err) {
-      this.ctx.logger.debug("deviceManager.getDevice failed during snapshot", {
-        tags: { deviceId },
-        meta: { error: err instanceof Error ? err.message : String(err) }
-      });
-      return null;
-    }
-  }
-  /** Settings-UI helper — battery flag drives the default max-age in the field description. */
-  async isDeviceBattery(deviceId) {
-    return (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false;
-  }
-  async getStreamOptions(deviceId) {
-    const prefix = `${deviceId}/`;
-    try {
-      const dev = await this.ctx.fetchDevice(deviceId);
-      const entries = await dev.cameraStreams?.getRtspEntries({}) ?? [];
-      const streamIds = entries.filter((e) => e.enabled).map((e) => e.brokerId.slice(prefix.length));
-      return [
-        { value: "auto", label: "Auto" },
-        ...streamIds.map((id) => ({ value: id, label: streamQualityLabel(id) }))
-      ];
-    } catch (err) {
-      this.ctx.logger.error("getStreamOptions failed", { tags: { deviceId }, meta: { error: errMsg(err) } });
-      return [{ value: "auto", label: "Auto" }];
-    }
-  }
-  async saveDeviceSettingsPatch(deviceId, patch) {
-    if (!this.ctx.settings) {
-      throw new Error("[snapshot] settings store unavailable \u2014 cannot persist per-device settings");
-    }
-    const current = await this.ctx.settings.readDeviceStore(deviceId);
-    const next = { ...current };
-    if ("snapshotStreamId" in patch) {
-      const v = patch["snapshotStreamId"];
-      next["snapshotStreamId"] = typeof v === "string" && v.trim().length > 0 ? v.trim() : "";
-    }
-    if ("snapshotDebug" in patch) {
-      next["snapshotDebug"] = patch["snapshotDebug"] === true;
-    }
-    if ("snapshotMaxAgeS" in patch) {
-      const v = patch["snapshotMaxAgeS"];
-      if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
-        next["snapshotMaxAgeS"] = v;
-      } else {
-        delete next["snapshotMaxAgeS"];
-      }
-    }
-    await this.ctx.settings.writeDeviceStore(deviceId, next);
-    this.cache.delete(deviceId);
-    return { success: true };
-  }
+	cache = /* @__PURE__ */ new Map();
+	constructor() {
+		super({ staleTtlMs: 6e4 });
+	}
+	async onInitialize() {
+		this.ctx.logger.info("Snapshot wrapper initialized");
+		return [{
+			capability: snapshotCapability,
+			provider: {
+				getSnapshot: (input) => this.getSnapshot(input),
+				invalidateCache: (input) => this.invalidateCache(input),
+				getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
+				getDeviceLiveContribution: async () => null,
+				applyDeviceSettingsPatch: (input) => this.saveDeviceSettingsPatch(input.deviceId, input.patch),
+				getStatus: async (input) => this.getStatus(input.deviceId)
+			},
+			kind: "wrapper",
+			defaultActive: true
+		}];
+	}
+	async onShutdown() {
+		this.cache.clear();
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "snapshot-cache",
+			title: "Snapshot Cache",
+			description: "Stale fallback when live capture fails. Per-device freshness is configured under Device → Snapshot → Max cache age.",
+			columns: 1,
+			fields: [this.field({
+				type: "number",
+				key: "staleTtlMs",
+				label: "Stale fallback TTL (ms)",
+				description: "If live capture fails, cached snapshot younger than this is still returned.",
+				min: 0,
+				max: 36e5,
+				step: 1e3,
+				default: 6e4
+			})]
+		}] });
+	}
+	async getSnapshot(input) {
+		const { deviceId, force } = input;
+		const meta = await this.lookupDeviceMeta(deviceId);
+		const deviceName = meta?.name;
+		const isBatteryDevice = meta?.isBattery ?? false;
+		const log = this.ctx.logger.withTags({
+			deviceId,
+			...deviceName ? { deviceName } : {}
+		});
+		const now = Date.now();
+		const hit = this.cache.get(deviceId);
+		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
+		const rawPref = prefs.snapshotStreamId;
+		const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
+		if (prefs.snapshotDebug) log.info("debug on", {
+			tags: { deviceId },
+			meta: { stream: effectiveStreamId ?? "auto" }
+		});
+		const defaultMaxAgeS = isBatteryDevice ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
+		const effectiveMaxAgeMs = (typeof prefs.snapshotMaxAgeS === "number" && prefs.snapshotMaxAgeS >= 0 ? prefs.snapshotMaxAgeS : defaultMaxAgeS) * 1e3;
+		if (!force && hit && now - hit.ts < effectiveMaxAgeMs) {
+			if (prefs.snapshotDebug) log.debug("snapshot: cache hit", {
+				tags: { deviceId },
+				meta: {
+					ageMs: now - hit.ts,
+					maxAgeMs: effectiveMaxAgeMs,
+					isBattery: isBatteryDevice
+				}
+			});
+			return hit.data;
+		}
+		let nativeError = null;
+		let nativeAbsent = false;
+		try {
+			const native = this.ctx.getNativeProvider(snapshotCapability, deviceId);
+			if (native) {
+				const result = await native.getSnapshot(input);
+				if (result) {
+					this.cache.set(deviceId, {
+						data: result,
+						ts: now,
+						streamId: effectiveStreamId ?? null
+					});
+					return result;
+				}
+			} else nativeAbsent = true;
+		} catch (err) {
+			const msg = errMsg(err);
+			if (isAbsentNativeError(msg)) {
+				nativeAbsent = true;
+				log.debug("native snapshot absent", {
+					tags: { deviceId },
+					meta: { error: msg }
+				});
+			} else {
+				nativeError = err;
+				log.warn("native snapshot failed", {
+					tags: { deviceId },
+					meta: { error: msg }
+				});
+			}
+		}
+		if (!(isBatteryDevice && nativeAbsent && !await this.hasStreamingBrokerForDevice(deviceId))) try {
+			const fallback = await this.grabFrameFromBroker(deviceId, effectiveStreamId);
+			if (fallback) {
+				this.cache.set(deviceId, {
+					data: fallback,
+					ts: now,
+					streamId: effectiveStreamId ?? null
+				});
+				return fallback;
+			}
+		} catch (err) {
+			log.warn("stream-broker snapshot fallback failed", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+		}
+		else log.debug("snapshot: skipping broker fallback — battery device with absent native and no streaming broker", { tags: { deviceId } });
+		if (hit) {
+			const ageMs = now - hit.ts;
+			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
+				tags: { deviceId },
+				meta: { ageMs }
+			});
+			return hit.data;
+		}
+		if (nativeError) throw nativeError;
+		if (nativeAbsent) return null;
+		return null;
+	}
+	/**
+	* Tell apart "native provider isn't registered for this device" from
+	* "native provider ran and threw a real error". The former is the steady
+	* state for cameras without a vendor snapshot endpoint and should not
+	* propagate as a 500; the latter should.
+	*/
+	/**
+	* Pull one JPEG from the device's stream-broker RTSP restream using
+	* a short-lived ffmpeg invocation.
+	*
+	* Stream selection strategy (picks the broker that won't stall):
+	*   1. Explicit `preferredStreamId` (user set in per-device settings)
+	*      — always honoured, even if currently idle. Operator choice
+	*      wins.
+	*   2. Auto: highest-quality broker currently in `streaming` state.
+	*      This is the whole point — prefer the stream that has active
+	*      subscribers (usually `low` for detection, but `mid`/`high`
+	*      if WebRTC is watching) so ffmpeg hits a warm pipe and
+	*      doesn't race the broker's resume.
+	*   3. Fallback: highest-quality enabled entry regardless of status
+	*      (will wake a suspended broker — retry-guarded against the
+	*      cold-start error).
+	*
+	* The stream-broker auto-suspends idle streams on the "no demand"
+	* signal; snapshots used to default to `high` which was often the
+	* first to go idle, racing every snapshot with a broker resume.
+	* Now we ask the orchestrator of streams which one is warm and grab
+	* from there.
+	*/
+	async grabFrameFromBroker(deviceId, preferredStreamId) {
+		const dev = await this.ctx.fetchDevice(deviceId);
+		const prefix = `${deviceId}/`;
+		const [deviceEntries, profileSlots] = await Promise.all([dev.cameraStreams?.getRtspEntries({}) ?? [], dev.cameraStreams?.getBrokerStreams({}) ?? []]);
+		const usable = deviceEntries.filter((e) => e.enabled && !!e.url);
+		if (usable.length === 0) return null;
+		if (preferredStreamId && preferredStreamId !== "auto") {
+			const explicit = usable.find((e) => e.brokerId === `${prefix}${preferredStreamId}`);
+			if (explicit) {
+				const grabbed = await this.runGrabWithResumeRetry(explicit.url, deviceId);
+				if (grabbed) return grabbed;
+				this.ctx.logger.debug("grabFrame: explicit stream failed — falling back to auto", { meta: { preferredStreamId } });
+			}
+		}
+		const ranked = [...usable].sort((a, b) => qualityRank(b.brokerId, prefix) - qualityRank(a.brokerId, prefix));
+		const statusByBrokerId = /* @__PURE__ */ new Map();
+		for (const slot of profileSlots) statusByBrokerId.set(slot.brokerId, slot.status);
+		const statuses = ranked.map((e) => ({
+			entry: e,
+			status: statusByBrokerId.get(e.brokerId) ?? "idle"
+		}));
+		const warm = statuses.find((s) => s.status === "streaming");
+		if (warm) {
+			const grabbed = await this.runGrabWithResumeRetry(warm.entry.url, deviceId);
+			if (grabbed) return grabbed;
+		}
+		for (const { entry } of statuses) {
+			const grabbed = await this.runGrabWithResumeRetry(entry.url, deviceId).catch(() => null);
+			if (grabbed) return grabbed;
+		}
+		return null;
+	}
+	/**
+	* Ffmpeg grab with one retry on the broker-cold-start error
+	* signature. Covers the window between "client connected" and
+	* "first keyframe" when a suspended broker resumes.
+	*/
+	async runGrabWithResumeRetry(url, deviceId) {
+		let buf;
+		try {
+			buf = await runFfmpegFrameGrab(url, 15e3);
+		} catch (err) {
+			if (isBrokerColdError(errMsg(err))) {
+				this.ctx.logger.debug("grabFrame: broker-resume race — retrying in 1500ms", { tags: { deviceId } });
+				await new Promise((r) => setTimeout(r, 1500));
+				buf = await runFfmpegFrameGrab(url, 15e3);
+			} else throw err;
+		}
+		if (buf.length === 0) return null;
+		return {
+			base64: buf.toString("base64"),
+			contentType: "image/jpeg"
+		};
+	}
+	async invalidateCache(input) {
+		this.cache.delete(input.deviceId);
+	}
+	/**
+	* Non-throwing probe of the device's battery cap. Returns true only
+	* when a battery native is registered AND its current status says
+	* `sleeping: true`. Any error (no provider, native absent, getStatus
+	* missing, RPC timeout) is swallowed and treated as "awake" — we'd
+	* rather pay a wake-up than strand the caller on a cache that's
+	* semantically stale. Debug-logged for observability.
+	*/
+	/**
+	* True when at least one of the device's brokers is actively
+	* streaming (status === 'streaming'). Used by the battery-cam guard
+	* around `grabFrameFromBroker` to allow the fallback ONLY when
+	* grabbing a frame is free (a consumer is already keeping the
+	* stream warm). When everything is suspended, the fallback would
+	* dial the camera and wake it — defeats the sleeping cache.
+	*/
+	async hasStreamingBrokerForDevice(deviceId) {
+		try {
+			return (await (await this.ctx.fetchDevice(deviceId)).cameraStreams?.getBrokerStreams({}) ?? []).some((s) => s.status === "streaming");
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Diagnostic status for the `status` auto-injected cap method. Reports
+	* the cache bookkeeping for this device — when the last snapshot was
+	* captured, how stale the cached image is, its size, and which stream
+	* was used. Returns null when the device has never been captured
+	* (cache miss) since the addon started.
+	*/
+	async getStatus(deviceId) {
+		const hit = this.cache.get(deviceId);
+		if (!hit) return null;
+		return {
+			lastCapturedAt: hit.ts,
+			cacheAgeMs: Date.now() - hit.ts,
+			lastBytes: hit.data.base64.length,
+			lastStreamId: hit.streamId
+		};
+	}
+	async readDeviceSettings(deviceId) {
+		if (!this.ctx.settings) return {};
+		const raw = await this.ctx.settings.readDeviceStore(deviceId);
+		const rawAge = raw["snapshotMaxAgeS"];
+		const maxAgeS = typeof rawAge === "number" && rawAge >= 0 && Number.isFinite(rawAge) ? rawAge : void 0;
+		return {
+			snapshotStreamId: typeof raw["snapshotStreamId"] === "string" ? raw["snapshotStreamId"] : void 0,
+			snapshotDebug: raw["snapshotDebug"] === true,
+			...maxAgeS !== void 0 ? { snapshotMaxAgeS: maxAgeS } : {}
+		};
+	}
+	async buildDeviceSettingsContribution(deviceId) {
+		const meta = await this.lookupDeviceMeta(deviceId);
+		if (meta && meta.type !== DeviceType.Camera) return null;
+		const current = await this.readDeviceSettings(deviceId);
+		const streamOptions = await this.getStreamOptions(deviceId);
+		const isBattery = await this.isDeviceBattery(deviceId);
+		const defaultMaxAgeS = isBattery ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
+		return { sections: [{
+			id: "snapshot-preferences",
+			title: "Snapshot",
+			tab: "snapshot",
+			order: 60,
+			fields: [
+				{
+					type: "select",
+					key: "snapshotStreamId",
+					label: "Preferred stream",
+					description: "Stream used when grabbing a snapshot",
+					options: streamOptions,
+					required: true,
+					value: current.snapshotStreamId || "auto"
+				},
+				{
+					type: "number",
+					key: "snapshotMaxAgeS",
+					label: "Max cache age (s)",
+					description: `Serve cached snapshot up to this age before re-capturing. Default ${defaultMaxAgeS}s for ${isBattery ? "battery cams (avoids gratuitous wake-ups)" : "non-battery cams (live-feel)"}. The UI refresh button always forces a fresh capture regardless of this value.`,
+					min: 0,
+					max: 24 * 3600,
+					step: 1,
+					value: current.snapshotMaxAgeS ?? defaultMaxAgeS
+				},
+				{
+					type: "boolean",
+					key: "snapshotDebug",
+					label: "Debug logging",
+					description: "Log stream selection and timing details for this device.",
+					value: current.snapshotDebug ?? false
+				}
+			]
+		}] };
+	}
+	/**
+	* 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
+	* device-manager registry rather than the battery cap so the answer
+	* survives a momentarily-unreachable provider (the very condition
+	* we're trying to be resilient to).
+	*
+	* Logged at debug + null return on failure: every call site already
+	* has a sensible fallback path (cache hit, conservative default, …),
+	* so we don't want a transient device-manager hiccup to throw.
+	*/
+	async lookupDeviceMeta(deviceId) {
+		const api = this.ctx.api;
+		if (!api) return null;
+		try {
+			const found = await api.deviceManager.getDevice.query({ deviceId });
+			if (!found) return null;
+			const features = found.features ?? [];
+			const rawType = found.type;
+			return {
+				...found.name ? { name: found.name } : {},
+				isBattery: features.includes(DeviceFeature.BatteryOperated),
+				...rawType ? { type: rawType } : {}
+			};
+		} catch (err) {
+			this.ctx.logger.debug("deviceManager.getDevice failed during snapshot", {
+				tags: { deviceId },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+			return null;
+		}
+	}
+	/** Settings-UI helper — battery flag drives the default max-age in the field description. */
+	async isDeviceBattery(deviceId) {
+		return (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false;
+	}
+	async getStreamOptions(deviceId) {
+		const prefix = `${deviceId}/`;
+		try {
+			return [{
+				value: "auto",
+				label: "Auto"
+			}, ...(await (await this.ctx.fetchDevice(deviceId)).cameraStreams?.getRtspEntries({}) ?? []).filter((e) => e.enabled).map((e) => e.brokerId.slice(prefix.length)).map((id) => ({
+				value: id,
+				label: streamQualityLabel(id)
+			}))];
+		} catch (err) {
+			this.ctx.logger.error("getStreamOptions failed", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return [{
+				value: "auto",
+				label: "Auto"
+			}];
+		}
+	}
+	async saveDeviceSettingsPatch(deviceId, patch) {
+		if (!this.ctx.settings) throw new Error("[snapshot] settings store unavailable — cannot persist per-device settings");
+		const next = { ...await this.ctx.settings.readDeviceStore(deviceId) };
+		if ("snapshotStreamId" in patch) {
+			const v = patch["snapshotStreamId"];
+			next["snapshotStreamId"] = typeof v === "string" && v.trim().length > 0 ? v.trim() : "";
+		}
+		if ("snapshotDebug" in patch) next["snapshotDebug"] = patch["snapshotDebug"] === true;
+		if ("snapshotMaxAgeS" in patch) {
+			const v = patch["snapshotMaxAgeS"];
+			if (typeof v === "number" && Number.isFinite(v) && v >= 0) next["snapshotMaxAgeS"] = v;
+			else delete next["snapshotMaxAgeS"];
+		}
+		await this.ctx.settings.writeDeviceStore(deviceId, next);
+		this.cache.delete(deviceId);
+		return { success: true };
+	}
 };
 function isAbsentNativeError(msg) {
-  return msg.includes("no provider for") || msg.includes("no native provider for capability");
+	return msg.includes("no provider for") || msg.includes("no native provider for capability");
 }
+/**
+* Quality ordering for broker picker: `high` > `mid` > `low` > other.
+* The streamId is the suffix after `${deviceId}/` in the brokerId.
+* Unknown labels fall through to 0 so they land at the bottom of the
+* preference list without crashing.
+*/
 function qualityRank(brokerId, prefix) {
-  const streamId = brokerId.startsWith(prefix) ? brokerId.slice(prefix.length) : brokerId;
-  const normalized = streamId.toLowerCase();
-  if (normalized.includes("high") || normalized === "main" || normalized === "hd") return 3;
-  if (normalized.includes("mid") || normalized === "medium") return 2;
-  if (normalized.includes("low") || normalized === "sub" || normalized === "sd") return 1;
-  return 0;
+	const normalized = (brokerId.startsWith(prefix) ? brokerId.slice(prefix.length) : brokerId).toLowerCase();
+	if (normalized.includes("high") || normalized === "main" || normalized === "hd") return 3;
+	if (normalized.includes("mid") || normalized === "medium") return 2;
+	if (normalized.includes("low") || normalized === "sub" || normalized === "sd") return 1;
+	return 0;
 }
+/**
+* Detect ffmpeg failure signatures that indicate the broker wasn't
+* streaming yet when we tried to read its RTSP restream — a race
+* window that closes as soon as the broker lands its first keyframe.
+* Used by `grabFrameFromBroker` to retry once instead of giving up.
+*/
 function isBrokerColdError(msg) {
-  return msg.includes("Invalid data found when processing input") || msg.includes("Error opening input") || msg.includes("Connection refused") || msg.includes("No route to host");
+	return msg.includes("Invalid data found when processing input") || msg.includes("Error opening input") || msg.includes("Connection refused") || msg.includes("No route to host");
 }
 function runFfmpegFrameGrab(url, timeoutMs) {
-  return new Promise((resolve, reject) => {
-    const child = execFile(
-      "ffmpeg",
-      [
-        "-loglevel",
-        "error",
-        "-rtsp_transport",
-        "tcp",
-        "-fflags",
-        "+discardcorrupt",
-        "-skip_frame",
-        "nokey",
-        "-i",
-        url,
-        "-vf",
-        "select=eq(pict_type\\,I)",
-        "-vsync",
-        "vfr",
-        "-frames:v",
-        "1",
-        "-q:v",
-        "3",
-        "-f",
-        "image2pipe",
-        "-vcodec",
-        "mjpeg",
-        "pipe:1"
-      ],
-      { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs },
-      (err, stdout, stderr) => {
-        if (err) {
-          const errWithMeta = err;
-          const stderrText = Buffer.isBuffer(stderr) ? stderr.toString("utf8").trim() : String(stderr ?? "").trim();
-          const parts = [err instanceof Error ? err.message : String(err)];
-          if (errWithMeta.killed) parts.push("killed=true");
-          if (errWithMeta.code !== void 0) parts.push(`code=${String(errWithMeta.code)}`);
-          if (errWithMeta.signal) parts.push(`signal=${errWithMeta.signal}`);
-          if (stderrText) parts.push(`stderr: ${stderrText.slice(0, 500)}`);
-          reject(new Error(parts.join(" \u2014 ")));
-          return;
-        }
-        resolve(Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout));
-      }
-    );
-    child.on("error", (e) => reject(e));
-  });
+	return new Promise((resolve, reject) => {
+		execFile("ffmpeg", [
+			"-loglevel",
+			"error",
+			"-rtsp_transport",
+			"tcp",
+			"-fflags",
+			"+discardcorrupt",
+			"-skip_frame",
+			"nokey",
+			"-i",
+			url,
+			"-vf",
+			"select=eq(pict_type\\,I)",
+			"-vsync",
+			"vfr",
+			"-frames:v",
+			"1",
+			"-q:v",
+			"3",
+			"-f",
+			"image2pipe",
+			"-vcodec",
+			"mjpeg",
+			"pipe:1"
+		], {
+			encoding: "buffer",
+			maxBuffer: 16 * 1024 * 1024,
+			timeout: timeoutMs
+		}, (err, stdout, stderr) => {
+			if (err) {
+				const errWithMeta = err;
+				const stderrText = Buffer.isBuffer(stderr) ? stderr.toString("utf8").trim() : String(stderr ?? "").trim();
+				const parts = [err instanceof Error ? err.message : String(err)];
+				if (errWithMeta.killed) parts.push("killed=true");
+				if (errWithMeta.code !== void 0) parts.push(`code=${String(errWithMeta.code)}`);
+				if (errWithMeta.signal) parts.push(`signal=${errWithMeta.signal}`);
+				if (stderrText) parts.push(`stderr: ${stderrText.slice(0, 500)}`);
+				reject(new Error(parts.join(" — ")));
+				return;
+			}
+			resolve(Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout));
+		}).on("error", (e) => reject(e));
+	});
 }
-export {
-  SnapshotAddon,
-  SnapshotAddon as default
-};
+//#endregion
+export { SnapshotAddon, SnapshotAddon as default };
+
 //# sourceMappingURL=index.mjs.map