@camstack/system 1.0.2

package/dist/builtins/snapshot/index.mjs

@@ -0,0 +1,488 @@
+import { BaseAddon, DeviceFeature, DeviceType, errMsg, snapshotCapability, streamQualityLabel } from "@camstack/types";
+import { execFile } from "node:child_process";
+//#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");
+		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)
+			}
+		}];
+	}
+	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;
+				}
+				log.debug("native snapshot returned null — falling through to broker", { tags: { deviceId } });
+			} else {
+				nativeAbsent = true;
+				log.debug("native snapshot provider not resolved — falling through to broker", { tags: { deviceId } });
+			}
+		} 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].toSorted((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");
+}
+/**
+* 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 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");
+}
+function runFfmpegFrameGrab(url, timeoutMs) {
+	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));
+	});
+}
+//#endregion
+export { SnapshotAddon, SnapshotAddon as default };

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

@@ -0,0 +1,120 @@
+import { ProviderRegistration, BaseAddon } from '@camstack/types';
+interface SnapshotAddonConfig {
+    /**
+     * Last-resort cache age (ms): if every live capture path fails
+     * (native + stream-broker fallback) AND a stale entry is older
+     * than this, the wrapper still returns the stale image rather
+     * than `null`. Keeps the UI from going blank during transient
+     * camera unreachability. Per-device freshness is governed by
+     * `snapshotMaxAgeS` instead.
+     */
+    readonly staleTtlMs: number;
+}
+/**
+ * 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.
+ */
+export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
+    private readonly cache;
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
+    protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
+    private getSnapshot;
+    /**
+     * 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.
+     */
+    private grabFrameFromBroker;
+    /**
+     * 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.
+     */
+    private runGrabWithResumeRetry;
+    private invalidateCache;
+    /**
+     * 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.
+     */
+    private hasStreamingBrokerForDevice;
+    /**
+     * 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.
+     */
+    private getStatus;
+    private readDeviceSettings;
+    private buildDeviceSettingsContribution;
+    /**
+     * 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.
+     */
+    private lookupDeviceMeta;
+    /** Settings-UI helper — battery flag drives the default max-age in the field description. */
+    private isDeviceBattery;
+    private getStreamOptions;
+    private saveDeviceSettingsPatch;
+}
+export {};

package/dist/builtins/sqlite-storage/config-store.d.ts

@@ -0,0 +1,8 @@
+import { default as Database } from 'better-sqlite3';
+export declare class ConfigStore {
+    private readonly db;
+    constructor(db: Database.Database);
+    save(addonId: string, stableId: string | null, data: Record<string, unknown>): void;
+    load(addonId: string, stableId: string | null): Record<string, unknown>;
+    remove(addonId: string, stableId: string | null): void;
+}

package/dist/builtins/sqlite-storage/device-store.d.ts

@@ -0,0 +1,23 @@
+import { default as Database } from 'better-sqlite3';
+export interface DeviceRow {
+    readonly stableId: string;
+    readonly type: string;
+    readonly name: string;
+    readonly parentStableId: string | null;
+    readonly enabled: boolean;
+}
+interface InsertInput {
+    readonly stableId: string;
+    readonly type: string;
+    readonly name: string;
+    readonly parentStableId: string | null;
+}
+export declare class DeviceStore {
+    private readonly db;
+    constructor(db: Database.Database);
+    insert(addonId: string, device: InsertInput): void;
+    listByAddon(addonId: string): readonly DeviceRow[];
+    listChildren(addonId: string, parentStableId: string): readonly DeviceRow[];
+    remove(addonId: string, stableId: string): void;
+}
+export {};

package/dist/builtins/sqlite-storage/filesystem-browse-provider.d.ts

@@ -0,0 +1,25 @@
+import { IFilesystemBrowseProvider } from '@camstack/types';
+export declare class FilesystemBrowseProvider implements IFilesystemBrowseProvider {
+    private readonly allowedRoots;
+    /** allowedRoots is injected (read from addon config) so it stays per-node + testable. */
+    constructor(allowedRoots: () => readonly string[]);
+    listAllowedRoots(): Promise<readonly string[]>;
+    browse({ path }: {
+        path: string;
+    }): Promise<{
+        path: string;
+        entries: readonly {
+            name: string;
+            path: string;
+        }[];
+        freeBytes: number;
+        totalBytes: number;
+    }>;
+    createDir({ path }: {
+        path: string;
+    }): Promise<{
+        path: string;
+    }>;
+    /** Allowed roots with symlinks resolved (falls back to the raw root if it does not exist). */
+    private resolvedRoots;
+}