@camstack/core 0.1.14 → 0.1.16

package/dist/builtins/remote-access-orchestrator/index.mjs

@@ -0,0 +1,2 @@
+import { RemoteAccessOrchestratorAddon } from "./remote-access-orchestrator.addon.mjs";
+export { RemoteAccessOrchestratorAddon, RemoteAccessOrchestratorAddon as default };

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.d.ts

@@ -0,0 +1,9 @@
+import { BaseAddon, ProviderRegistration } from '@camstack/types';
+export declare class RemoteAccessOrchestratorAddon extends BaseAddon<Record<string, never>> {
+    constructor();
+    protected onInitialize(): Promise<ProviderRegistration[]>;
+    private resolveImpl;
+    private listProviders;
+}
+export default RemoteAccessOrchestratorAddon;
+//# sourceMappingURL=remote-access-orchestrator.addon.d.ts.map

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-access-orchestrator.addon.d.ts","sourceRoot":"","sources":["../../../src/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,SAAS,EAIT,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAA;AAiBxB,qBAAa,6BAA8B,SAAQ,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;;cAKjE,YAAY,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAkB/D,OAAO,CAAC,WAAW;YAML,aAAa;CA+B5B;AAED,eAAe,6BAA6B,CAAA"}

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js

@@ -0,0 +1,72 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-C13QxCFV.js");
+let _camstack_types = require("@camstack/types");
+//#region src/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.ts
+/**
+* Remote-access orchestrator — singleton facade over the
+* `network-access` collection (Cloudflare Tunnel, ngrok, Tailscale, …).
+* Mirrors the auth-orchestrator and backup-orchestrator patterns.
+*/
+var RemoteAccessOrchestratorAddon = class extends _camstack_types.BaseAddon {
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		const provider = {
+			listProviders: async () => this.listProviders(),
+			startProvider: async ({ addonId }) => {
+				const impl = this.resolveImpl(addonId);
+				if (!impl?.start) throw new Error(`Remote-access provider "${addonId}" does not support start`);
+				return await impl.start();
+			},
+			stopProvider: async ({ addonId }) => {
+				const impl = this.resolveImpl(addonId);
+				if (impl?.stop) await impl.stop();
+				return { success: true };
+			}
+		};
+		this.ctx.logger.info("Remote-access orchestrator initialized");
+		return [{
+			capability: _camstack_types.remoteAccessCapability,
+			provider
+		}];
+	}
+	resolveImpl(addonId) {
+		return (this.capabilities?.getCollectionEntries("network-access") ?? []).find(([id]) => id === addonId)?.[1] ?? null;
+	}
+	async listProviders() {
+		const entries = this.capabilities?.getCollectionEntries("network-access") ?? [];
+		const out = [];
+		for (const [addonId, impl] of entries) {
+			let connected = false;
+			let endpoint = null;
+			let error;
+			if (impl.getStatus) try {
+				const s = await impl.getStatus();
+				connected = s.connected;
+				endpoint = s.endpoint;
+				error = s.error;
+			} catch (err) {
+				error = err instanceof Error ? err.message : String(err);
+			}
+			out.push({
+				addonId,
+				displayName: impl.displayName ?? addonId,
+				kind: impl.kind ?? (addonId.includes("cloudflare") ? "cloudflare-tunnel" : "other"),
+				enabled: true,
+				connected,
+				endpoint,
+				...error !== void 0 ? { error } : {}
+			});
+		}
+		return out;
+	}
+};
+//#endregion
+exports.RemoteAccessOrchestratorAddon = RemoteAccessOrchestratorAddon;
+exports.default = RemoteAccessOrchestratorAddon;
+
+//# sourceMappingURL=remote-access-orchestrator.addon.js.map

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-access-orchestrator.addon.js","names":[],"sources":["../../../src/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.ts"],"sourcesContent":["/**\n * Remote-access orchestrator — singleton facade over the\n * `network-access` collection (Cloudflare Tunnel, ngrok, Tailscale, …).\n * Mirrors the auth-orchestrator and backup-orchestrator patterns.\n */\nimport {\n  BaseAddon,\n  remoteAccessCapability,\n  type IRemoteAccessOrchestrator,\n  type RemoteAccessProviderInfo,\n  type ProviderRegistration,\n} from '@camstack/types'\n\ninterface NetworkAccessLike {\n  start?: () => Promise<{ url: string; hostname: string; port: number; protocol: 'http' | 'https' }>\n  stop?: () => Promise<void>\n  getStatus?: () => Promise<{\n    connected: boolean\n    endpoint: { url: string; hostname: string; port: number; protocol: 'http' | 'https' } | null\n    error?: string\n  }>\n}\n\ninterface NetworkAccessRegistrationMeta {\n  readonly displayName?: string\n  readonly kind?: RemoteAccessProviderInfo['kind']\n}\n\nexport class RemoteAccessOrchestratorAddon extends BaseAddon<Record<string, never>> {\n  constructor() {\n    super({})\n  }\n\n  protected async onInitialize(): Promise<ProviderRegistration[]> {\n    const provider: IRemoteAccessOrchestrator = {\n      listProviders: async () => this.listProviders(),\n      startProvider: async ({ addonId }) => {\n        const impl = this.resolveImpl(addonId)\n        if (!impl?.start) throw new Error(`Remote-access provider \"${addonId}\" does not support start`)\n        return await impl.start()\n      },\n      stopProvider: async ({ addonId }) => {\n        const impl = this.resolveImpl(addonId)\n        if (impl?.stop) await impl.stop()\n        return { success: true as const }\n      },\n    } satisfies IRemoteAccessOrchestrator\n    this.ctx.logger.info('Remote-access orchestrator initialized')\n    return [{ capability: remoteAccessCapability, provider }]\n  }\n\n  private resolveImpl(addonId: string): NetworkAccessLike | null {\n    const entries = this.capabilities?.getCollectionEntries<NetworkAccessLike>('network-access') ?? []\n    const found = entries.find(([id]) => id === addonId)\n    return found?.[1] ?? null\n  }\n\n  private async listProviders(): Promise<readonly RemoteAccessProviderInfo[]> {\n    const entries = this.capabilities?.getCollectionEntries<NetworkAccessLike & NetworkAccessRegistrationMeta>(\n      'network-access',\n    ) ?? []\n    const out: RemoteAccessProviderInfo[] = []\n    for (const [addonId, impl] of entries) {\n      let connected = false\n      let endpoint: RemoteAccessProviderInfo['endpoint'] = null\n      let error: string | undefined\n      if (impl.getStatus) {\n        try {\n          const s = await impl.getStatus()\n          connected = s.connected\n          endpoint = s.endpoint\n          error = s.error\n        } catch (err) {\n          error = err instanceof Error ? err.message : String(err)\n        }\n      }\n      out.push({\n        addonId,\n        displayName: impl.displayName ?? addonId,\n        kind: impl.kind ?? (addonId.includes('cloudflare') ? 'cloudflare-tunnel' as const : 'other' as const),\n        enabled: true,\n        connected,\n        endpoint,\n        ...(error !== undefined ? { error } : {}),\n      })\n    }\n    return out\n  }\n}\n\nexport default RemoteAccessOrchestratorAddon\n"],"mappings":";;;;;;;;;;;;AA4BA,IAAa,gCAAb,cAAmD,gBAAA,UAAiC;CAClF,cAAc;EACZ,MAAM,EAAE,CAAC;;CAGX,MAAgB,eAAgD;EAC9D,MAAM,WAAsC;GAC1C,eAAe,YAAY,KAAK,eAAe;GAC/C,eAAe,OAAO,EAAE,cAAc;IACpC,MAAM,OAAO,KAAK,YAAY,QAAQ;IACtC,IAAI,CAAC,MAAM,OAAO,MAAM,IAAI,MAAM,2BAA2B,QAAQ,0BAA0B;IAC/F,OAAO,MAAM,KAAK,OAAO;;GAE3B,cAAc,OAAO,EAAE,cAAc;IACnC,MAAM,OAAO,KAAK,YAAY,QAAQ;IACtC,IAAI,MAAM,MAAM,MAAM,KAAK,MAAM;IACjC,OAAO,EAAE,SAAS,MAAe;;GAEpC;EACD,KAAK,IAAI,OAAO,KAAK,yCAAyC;EAC9D,OAAO,CAAC;GAAE,YAAY,gBAAA;GAAwB;GAAU,CAAC;;CAG3D,YAAoB,SAA2C;EAG7D,QAFgB,KAAK,cAAc,qBAAwC,iBAAiB,IAAI,EAAE,EAC5E,MAAM,CAAC,QAAQ,OAAO,QACrC,GAAQ,MAAM;;CAGvB,MAAc,gBAA8D;EAC1E,MAAM,UAAU,KAAK,cAAc,qBACjC,iBACD,IAAI,EAAE;EACP,MAAM,MAAkC,EAAE;EAC1C,KAAK,MAAM,CAAC,SAAS,SAAS,SAAS;GACrC,IAAI,YAAY;GAChB,IAAI,WAAiD;GACrD,IAAI;GACJ,IAAI,KAAK,WACP,IAAI;IACF,MAAM,IAAI,MAAM,KAAK,WAAW;IAChC,YAAY,EAAE;IACd,WAAW,EAAE;IACb,QAAQ,EAAE;YACH,KAAK;IACZ,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;;GAG5D,IAAI,KAAK;IACP;IACA,aAAa,KAAK,eAAe;IACjC,MAAM,KAAK,SAAS,QAAQ,SAAS,aAAa,GAAG,sBAA+B;IACpF,SAAS;IACT;IACA;IACA,GAAI,UAAU,KAAA,IAAY,EAAE,OAAO,GAAG,EAAE;IACzC,CAAC;;EAEJ,OAAO"}

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs

@@ -0,0 +1,66 @@
+import { BaseAddon, remoteAccessCapability } from "@camstack/types";
+//#region src/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.ts
+/**
+* Remote-access orchestrator — singleton facade over the
+* `network-access` collection (Cloudflare Tunnel, ngrok, Tailscale, …).
+* Mirrors the auth-orchestrator and backup-orchestrator patterns.
+*/
+var RemoteAccessOrchestratorAddon = class extends BaseAddon {
+	constructor() {
+		super({});
+	}
+	async onInitialize() {
+		const provider = {
+			listProviders: async () => this.listProviders(),
+			startProvider: async ({ addonId }) => {
+				const impl = this.resolveImpl(addonId);
+				if (!impl?.start) throw new Error(`Remote-access provider "${addonId}" does not support start`);
+				return await impl.start();
+			},
+			stopProvider: async ({ addonId }) => {
+				const impl = this.resolveImpl(addonId);
+				if (impl?.stop) await impl.stop();
+				return { success: true };
+			}
+		};
+		this.ctx.logger.info("Remote-access orchestrator initialized");
+		return [{
+			capability: remoteAccessCapability,
+			provider
+		}];
+	}
+	resolveImpl(addonId) {
+		return (this.capabilities?.getCollectionEntries("network-access") ?? []).find(([id]) => id === addonId)?.[1] ?? null;
+	}
+	async listProviders() {
+		const entries = this.capabilities?.getCollectionEntries("network-access") ?? [];
+		const out = [];
+		for (const [addonId, impl] of entries) {
+			let connected = false;
+			let endpoint = null;
+			let error;
+			if (impl.getStatus) try {
+				const s = await impl.getStatus();
+				connected = s.connected;
+				endpoint = s.endpoint;
+				error = s.error;
+			} catch (err) {
+				error = err instanceof Error ? err.message : String(err);
+			}
+			out.push({
+				addonId,
+				displayName: impl.displayName ?? addonId,
+				kind: impl.kind ?? (addonId.includes("cloudflare") ? "cloudflare-tunnel" : "other"),
+				enabled: true,
+				connected,
+				endpoint,
+				...error !== void 0 ? { error } : {}
+			});
+		}
+		return out;
+	}
+};
+//#endregion
+export { RemoteAccessOrchestratorAddon, RemoteAccessOrchestratorAddon as default };
+
+//# sourceMappingURL=remote-access-orchestrator.addon.mjs.map

package/dist/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-access-orchestrator.addon.mjs","names":[],"sources":["../../../src/builtins/remote-access-orchestrator/remote-access-orchestrator.addon.ts"],"sourcesContent":["/**\n * Remote-access orchestrator — singleton facade over the\n * `network-access` collection (Cloudflare Tunnel, ngrok, Tailscale, …).\n * Mirrors the auth-orchestrator and backup-orchestrator patterns.\n */\nimport {\n  BaseAddon,\n  remoteAccessCapability,\n  type IRemoteAccessOrchestrator,\n  type RemoteAccessProviderInfo,\n  type ProviderRegistration,\n} from '@camstack/types'\n\ninterface NetworkAccessLike {\n  start?: () => Promise<{ url: string; hostname: string; port: number; protocol: 'http' | 'https' }>\n  stop?: () => Promise<void>\n  getStatus?: () => Promise<{\n    connected: boolean\n    endpoint: { url: string; hostname: string; port: number; protocol: 'http' | 'https' } | null\n    error?: string\n  }>\n}\n\ninterface NetworkAccessRegistrationMeta {\n  readonly displayName?: string\n  readonly kind?: RemoteAccessProviderInfo['kind']\n}\n\nexport class RemoteAccessOrchestratorAddon extends BaseAddon<Record<string, never>> {\n  constructor() {\n    super({})\n  }\n\n  protected async onInitialize(): Promise<ProviderRegistration[]> {\n    const provider: IRemoteAccessOrchestrator = {\n      listProviders: async () => this.listProviders(),\n      startProvider: async ({ addonId }) => {\n        const impl = this.resolveImpl(addonId)\n        if (!impl?.start) throw new Error(`Remote-access provider \"${addonId}\" does not support start`)\n        return await impl.start()\n      },\n      stopProvider: async ({ addonId }) => {\n        const impl = this.resolveImpl(addonId)\n        if (impl?.stop) await impl.stop()\n        return { success: true as const }\n      },\n    } satisfies IRemoteAccessOrchestrator\n    this.ctx.logger.info('Remote-access orchestrator initialized')\n    return [{ capability: remoteAccessCapability, provider }]\n  }\n\n  private resolveImpl(addonId: string): NetworkAccessLike | null {\n    const entries = this.capabilities?.getCollectionEntries<NetworkAccessLike>('network-access') ?? []\n    const found = entries.find(([id]) => id === addonId)\n    return found?.[1] ?? null\n  }\n\n  private async listProviders(): Promise<readonly RemoteAccessProviderInfo[]> {\n    const entries = this.capabilities?.getCollectionEntries<NetworkAccessLike & NetworkAccessRegistrationMeta>(\n      'network-access',\n    ) ?? []\n    const out: RemoteAccessProviderInfo[] = []\n    for (const [addonId, impl] of entries) {\n      let connected = false\n      let endpoint: RemoteAccessProviderInfo['endpoint'] = null\n      let error: string | undefined\n      if (impl.getStatus) {\n        try {\n          const s = await impl.getStatus()\n          connected = s.connected\n          endpoint = s.endpoint\n          error = s.error\n        } catch (err) {\n          error = err instanceof Error ? err.message : String(err)\n        }\n      }\n      out.push({\n        addonId,\n        displayName: impl.displayName ?? addonId,\n        kind: impl.kind ?? (addonId.includes('cloudflare') ? 'cloudflare-tunnel' as const : 'other' as const),\n        enabled: true,\n        connected,\n        endpoint,\n        ...(error !== undefined ? { error } : {}),\n      })\n    }\n    return out\n  }\n}\n\nexport default RemoteAccessOrchestratorAddon\n"],"mappings":";;;;;;;AA4BA,IAAa,gCAAb,cAAmD,UAAiC;CAClF,cAAc;EACZ,MAAM,EAAE,CAAC;;CAGX,MAAgB,eAAgD;EAC9D,MAAM,WAAsC;GAC1C,eAAe,YAAY,KAAK,eAAe;GAC/C,eAAe,OAAO,EAAE,cAAc;IACpC,MAAM,OAAO,KAAK,YAAY,QAAQ;IACtC,IAAI,CAAC,MAAM,OAAO,MAAM,IAAI,MAAM,2BAA2B,QAAQ,0BAA0B;IAC/F,OAAO,MAAM,KAAK,OAAO;;GAE3B,cAAc,OAAO,EAAE,cAAc;IACnC,MAAM,OAAO,KAAK,YAAY,QAAQ;IACtC,IAAI,MAAM,MAAM,MAAM,KAAK,MAAM;IACjC,OAAO,EAAE,SAAS,MAAe;;GAEpC;EACD,KAAK,IAAI,OAAO,KAAK,yCAAyC;EAC9D,OAAO,CAAC;GAAE,YAAY;GAAwB;GAAU,CAAC;;CAG3D,YAAoB,SAA2C;EAG7D,QAFgB,KAAK,cAAc,qBAAwC,iBAAiB,IAAI,EAAE,EAC5E,MAAM,CAAC,QAAQ,OAAO,QACrC,GAAQ,MAAM;;CAGvB,MAAc,gBAA8D;EAC1E,MAAM,UAAU,KAAK,cAAc,qBACjC,iBACD,IAAI,EAAE;EACP,MAAM,MAAkC,EAAE;EAC1C,KAAK,MAAM,CAAC,SAAS,SAAS,SAAS;GACrC,IAAI,YAAY;GAChB,IAAI,WAAiD;GACrD,IAAI;GACJ,IAAI,KAAK,WACP,IAAI;IACF,MAAM,IAAI,MAAM,KAAK,WAAW;IAChC,YAAY,EAAE;IACd,WAAW,EAAE;IACb,QAAQ,EAAE;YACH,KAAK;IACZ,QAAQ,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;;GAG5D,IAAI,KAAK;IACP;IACA,aAAa,KAAK,eAAe;IACjC,MAAM,KAAK,SAAS,QAAQ,SAAS,aAAa,GAAG,sBAA+B;IACpF,SAAS;IACT;IACA;IACA,GAAI,UAAU,KAAA,IAAY,EAAE,OAAO,GAAG,EAAE;IACzC,CAAC;;EAEJ,OAAO"}

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

@@ -0,0 +1,3 @@
+export { SnapshotAddon } from './snapshot.addon.js';
+export { SnapshotAddon as default } from './snapshot.addon.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/builtins/snapshot/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/builtins/snapshot/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,IAAI,OAAO,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/builtins/snapshot/index.js

@@ -0,0 +1,494 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-C13QxCFV.js");
+let node_child_process = require("node:child_process");
+let _camstack_types = require("@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 _camstack_types.BaseAddon {
+	cache = /* @__PURE__ */ new Map();
+	constructor() {
+		super({ staleTtlMs: 6e4 });
+	}
+	async onInitialize() {
+		this.ctx.logger.info("Snapshot wrapper initialized");
+		return [{
+			capability: _camstack_types.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(_camstack_types.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 = (0, _camstack_types.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: (0, _camstack_types.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((0, _camstack_types.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 !== _camstack_types.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(_camstack_types.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: (0, _camstack_types.streamQualityLabel)(id)
+			}))];
+		} catch (err) {
+			this.ctx.logger.error("getStreamOptions failed", {
+				tags: { deviceId },
+				meta: { error: (0, _camstack_types.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) => {
+		(0, node_child_process.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
+exports.SnapshotAddon = SnapshotAddon;
+exports.default = SnapshotAddon;
+
+//# sourceMappingURL=index.js.map