@camstack/addon-provider-reolink 1.2.5 → 1.2.7

package/dist/addon.js

@@ -222620,6 +222620,33 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	markWakeIssued() {
 		this.lastProactiveWakeAt = Date.now();
 	}
+	/**
+	* Gate for a PROACTIVE camera read, checked BEFORE `ensureApi()`.
+	*
+	* The login itself is the wake. On a sleeping UDP/battery camera the
+	* lib's discovery + handshake nudges the firmware awake (same reason
+	* `refreshParentSettingsSnapshot` refuses to call `ensureApi` while
+	* asleep), so gating only the explicit `wakeUp()` call is useless —
+	* by the time we reach it the camera is already up. Production logs
+	* showed exactly that: a background read produced a full
+	* `Connecting to Reolink` → BCUDP discovery → `battery sleep state
+	* committed` (awake) → whole refresh cascade, on a camera that had
+	* been asleep for six minutes.
+	*
+	* Returns `false` when the caller must serve cache / bail out without
+	* touching the socket. Stamps the cooldown when it does let a wake
+	* through, so "at most one proactive wake per
+	* `PROACTIVE_WAKE_COOLDOWN_MS`" holds across ALL proactive callers
+	* rather than per-caller.
+	*
+	* Demand-driven paths never call this — see `canProactivelyWake`.
+	*/
+	allowProactiveCameraAccess(reason) {
+		if (!this.isBattery || !this.sleeping) return true;
+		if (!this.canProactivelyWake(reason)) return false;
+		this.markWakeIssued();
+		return true;
+	}
 	updateBatteryCache(info) {
 		this.setCapSlice(batteryCapability, this.mapBatteryInfo(info));
 	}
@@ -222865,6 +222892,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	}
 	async fetchSnapshotWithSingleFlight() {
 		if (this.snapshotInFlight) return this.snapshotInFlight;
+		if (!this.allowProactiveCameraAccess("snapshot")) {
+			this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
+			return null;
+		}
 		const promise = (async () => {
 			let api;
 			try {
@@ -222882,23 +222913,16 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				} catch {
 					return true;
 				}
-			})()) {
-				if (!this.canProactivelyWake("snapshot")) {
-					this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
-					return null;
-				}
-				this.markWakeIssued();
-				try {
-					await api.wakeUp(this.getChannel(), {
-						waitAfterWakeMs: 1500,
-						attempts: 2
-					});
-				} catch (err) {
-					this.ctx.logger.debug("snapshot: pre-wake failed (will still try getSnapshot)", {
-						tags: { deviceId: this.id },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-				}
+			})()) try {
+				await api.wakeUp(this.getChannel(), {
+					waitAfterWakeMs: 1500,
+					attempts: 2
+				});
+			} catch (err) {
+				this.ctx.logger.debug("snapshot: pre-wake failed (will still try getSnapshot)", {
+					tags: { deviceId: this.id },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
 			}
 			const tryOnce = async (timeoutMs) => {
 				const buf = await api.getSnapshot(this.getChannel(), {
@@ -223441,6 +223465,97 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 	}
 	/**
+	* Per-cap "warm the cache while the camera is up" closures, registered
+	* by each device-config cap alongside its provider and run by
+	* `onWakeTransition`.
+	*
+	* This is the OTHER half of the read discipline. Gating reads stops us
+	* waking the camera, but on its own it leaves the caches empty — and an
+	* empty cache is what the operator actually sees: the State panel reads
+	* the runtime-state slices (`deviceState.getAllSnapshots`), so a
+	* sleeping camera whose slices were never written shows null for
+	* everything. Before the gate, the admin UI's 2.5s aggregate poll kept
+	* those slices warm by waking the camera every time — the very bug we
+	* fixed. So the refresh has to move to the moment the camera is
+	* ALREADY up, which is exactly the wake transition.
+	*/
+	capWarmers = /* @__PURE__ */ new Map();
+	/** How fresh a slice must be for the wake warm-up to skip it. A battery
+	*  cam can wake many times an hour on motion; re-probing every cap on
+	*  every wake would spend the (~14s) window on data we already have. */
+	static WAKE_WARM_MAX_AGE_MS = 10 * 6e4;
+	registerCapWarmer(capName, warm) {
+		this.capWarmers.set(capName, warm);
+	}
+	/**
+	* Refresh the device-config cap caches during a wake window.
+	*
+	* SERIALIZED, like every other wake-path refresh — concurrent Baichuan
+	* traffic on the single BCUDP stream starves the heavy reads. Each cap
+	* is skipped when its slice is still fresh, and each failure is
+	* swallowed: the window is short, partial progress accumulates across
+	* wakes because the slices persist.
+	*/
+	async warmCapSlicesOnWake() {
+		const now = Date.now();
+		let warmed = 0;
+		let skipped = 0;
+		for (const [capName, warm] of this.capWarmers) {
+			const slice = this.runtimeState.getCapState(capName);
+			const fetchedAt = typeof slice?.lastFetchedAt === "number" ? slice.lastFetchedAt : 0;
+			if (fetchedAt > 0 && now - fetchedAt < ReolinkCamera.WAKE_WARM_MAX_AGE_MS) {
+				skipped += 1;
+				continue;
+			}
+			try {
+				await warm();
+				warmed += 1;
+			} catch (err) {
+				this.ctx.logger.debug("wake warm-up: cap refresh failed — retrying on next wake", {
+					tags: { deviceId: this.id },
+					meta: {
+						capName,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.ctx.logger.info("wake warm-up: cap caches refreshed", {
+			tags: { deviceId: this.id },
+			meta: {
+				warmed,
+				skipped,
+				total: this.capWarmers.size
+			}
+		});
+	}
+	/**
+	* Ask the snapshot wrapper for a frame while the camera is up, so its
+	* cache holds something recent to serve for the whole sleep window.
+	*
+	* The wrapper already does the right thing on a miss — `resolveOutcome`
+	* falls back to the stale frame rather than blanking the UI — but only
+	* if a frame was ever captured. With reads gated, nothing captures one
+	* any more: the tile stayed empty for as long as the camera slept.
+	* `force: true` bypasses the wrapper's freshness gate; our own
+	* proactive gate lets it through because `sleeping` is false here.
+	* Mirrors the reference's `updateBatteryAndSnapshot`.
+	*/
+	async warmSnapshotOnWake() {
+		try {
+			await this.ctx.api.snapshot.getSnapshot.query({
+				deviceId: this.id,
+				force: true
+			});
+			this.ctx.logger.debug("wake warm-up: snapshot cache refreshed", { tags: { deviceId: this.id } });
+		} catch (err) {
+			this.ctx.logger.debug("wake warm-up: snapshot refresh failed", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+	}
+	/**
 	* Wrap a cap's `refreshFromCamera` so the READ side (the bridge's
 	* stale-check behind `getStatus`) never wakes a sleeping battery cam.
 	* The bridge then projects whatever the slice last held — which is
@@ -223545,6 +223660,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				this.ctx.eventBus.emit(createEvent(EventCategory.StreamParamsChanged, this.eventSource(), { deviceId: this.id }));
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(streamParamsCapability, provider);
 		this.ctx.logger.info("Reolink stream-params cap registered", { tags: { deviceId: this.id } });
 	}
@@ -223735,6 +223854,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(motionZonesCapability, provider);
 		this.ctx.logger.info("Reolink motion-zones cap registered", { tags: { deviceId: this.id } });
 	}
@@ -223870,6 +223993,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				});
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(privacyMaskCapability, provider);
 		this.ctx.logger.info("Reolink privacy-mask cap registered (read + enable + zone write)", { tags: { deviceId: this.id } });
 	}
@@ -224005,6 +224132,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(dayNightCapability, provider);
 		this.ctx.logger.info("Reolink day-night cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224142,6 +224273,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(imageSettingsCapability, provider);
 		this.ctx.logger.info("Reolink image-settings cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224411,6 +224546,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, refreshFromCamera);
 		this.ctx.registerNativeCap(ptzAutotrackCapability, provider);
 		this.ctx.logger.info("Reolink ptz-autotrack cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224418,148 +224554,154 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		if (this.ptzRegistered) return;
 		if (!this.getProbeFlags().hasPtz) return;
 		this.ptzRegistered = true;
-		this.ctx.registerNativeCap(ptzCapability, {
-			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
-				if (deviceId !== this.id) return;
-				await this.runPtz(pan, tilt, zoom, speed, false);
-			},
-			continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
-				if (deviceId !== this.id) return;
-				await this.runPtz(pan, tilt, zoom, speed, true);
-			},
-			stop: async ({ deviceId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				try {
-					await api.ptz(channel, {
-						action: "stop",
-						command: "Up"
-					});
-				} catch {}
-			},
-			getPresets: async ({ deviceId }) => {
-				if (deviceId !== this.id) return [];
-				try {
+		{
+			const ptzProvider = {
+				move: async ({ deviceId, pan, tilt, zoom, speed }) => {
+					if (deviceId !== this.id) return;
+					await this.runPtz(pan, tilt, zoom, speed, false);
+				},
+				continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
+					if (deviceId !== this.id) return;
+					await this.runPtz(pan, tilt, zoom, speed, true);
+				},
+				stop: async ({ deviceId }) => {
+					if (deviceId !== this.id) return;
 					const api = await this.ensureApi();
 					const channel = this.getChannel();
-					return (await api.getPtzPresets(channel)).map((p) => ({
-						id: String(p.id),
-						name: p.name
-					}));
-				} catch {
-					return [];
-				}
-			},
-			goToPreset: async ({ deviceId, presetId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.moveToPtzPreset(channel, id);
-			},
-			savePreset: async ({ deviceId, presetId, name }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.setPtzPreset(channel, id, name);
-			},
-			deletePreset: async ({ deviceId, presetId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.deletePtzPreset(channel, id);
-			},
-			getOptions: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					hasPan: false,
-					hasTilt: false,
-					hasZoom: false,
-					supportsPresets: false,
-					hasAutofocus: false
-				};
-				const hasAutofocus = this.config.get("deviceCache")?.autoFocusSnapshot?.supported === true;
-				return this.resolveCapOptions({
-					capName: "ptz",
-					schema: PtzOptionsSchema,
-					probe: async () => {
-						const { capabilities } = await (await this.ensureApi()).getDeviceCapabilities(this.getChannel());
-						return {
-							hasPan: capabilities.hasPan,
-							hasTilt: capabilities.hasTilt,
-							hasZoom: capabilities.hasZoom,
-							supportsPresets: capabilities.hasPresets,
-							hasAutofocus
-						};
-					},
-					fallback: () => {
-						const hasPtz = this.getProbeFlags().hasPtz === true;
-						return {
-							hasPan: hasPtz,
-							hasTilt: hasPtz,
-							hasZoom: hasPtz,
-							supportsPresets: hasPtz,
-							hasAutofocus
-						};
+					try {
+						await api.ptz(channel, {
+							action: "stop",
+							command: "Up"
+						});
+					} catch {}
+				},
+				getPresets: async ({ deviceId }) => {
+					if (deviceId !== this.id) return [];
+					try {
+						const api = await this.ensureApi();
+						const channel = this.getChannel();
+						return (await api.getPtzPresets(channel)).map((p) => ({
+							id: String(p.id),
+							name: p.name
+						}));
+					} catch {
+						return [];
 					}
-				});
-			},
-			goHome: async ({ deviceId }) => {
-				if (deviceId !== this.id) return;
-				try {
+				},
+				goToPreset: async ({ deviceId, presetId }) => {
+					if (deviceId !== this.id) return;
 					const api = await this.ensureApi();
 					const channel = this.getChannel();
-					await api.moveToPtzPreset(channel, 0);
-				} catch {}
-			},
-			getPosition: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
-				};
-				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
-				};
-			},
-			getStatus: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
-					autofocus: false
-				};
-				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
-					autofocus: (this.config.get("deviceCache")?.autoFocusSnapshot)?.enabled === true
-				};
-			},
-			setAutofocus: async ({ deviceId, enabled }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				await api.setAutoFocus(channel, enabled ? 0 : 1);
-				try {
-					const a = (await api.getAutoFocus(channel, { timeoutMs: 1500 }))?.body?.AutoFocus;
-					if (a) await this.config.setAll({ deviceCache: {
-						...this.config.get("deviceCache"),
-						autoFocusSnapshot: {
-							enabled: typeof a.disable === "number" ? a.disable === 0 : null,
-							supported: true
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.moveToPtzPreset(channel, id);
+				},
+				savePreset: async ({ deviceId, presetId, name }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.setPtzPreset(channel, id, name);
+				},
+				deletePreset: async ({ deviceId, presetId }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.deletePtzPreset(channel, id);
+				},
+				getOptions: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						hasPan: false,
+						hasTilt: false,
+						hasZoom: false,
+						supportsPresets: false,
+						hasAutofocus: false
+					};
+					const hasAutofocus = this.config.get("deviceCache")?.autoFocusSnapshot?.supported === true;
+					return this.resolveCapOptions({
+						capName: "ptz",
+						schema: PtzOptionsSchema,
+						probe: async () => {
+							const { capabilities } = await (await this.ensureApi()).getDeviceCapabilities(this.getChannel());
+							return {
+								hasPan: capabilities.hasPan,
+								hasTilt: capabilities.hasTilt,
+								hasZoom: capabilities.hasZoom,
+								supportsPresets: capabilities.hasPresets,
+								hasAutofocus
+							};
+						},
+						fallback: () => {
+							const hasPtz = this.getProbeFlags().hasPtz === true;
+							return {
+								hasPan: hasPtz,
+								hasTilt: hasPtz,
+								hasZoom: hasPtz,
+								supportsPresets: hasPtz,
+								hasAutofocus
+							};
 						}
-					} });
-				} catch {}
-			}
-		});
+					});
+				},
+				goHome: async ({ deviceId }) => {
+					if (deviceId !== this.id) return;
+					try {
+						const api = await this.ensureApi();
+						const channel = this.getChannel();
+						await api.moveToPtzPreset(channel, 0);
+					} catch {}
+				},
+				getPosition: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0
+					};
+					return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0
+					};
+				},
+				getStatus: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0,
+						autofocus: false
+					};
+					return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0,
+						autofocus: (this.config.get("deviceCache")?.autoFocusSnapshot)?.enabled === true
+					};
+				},
+				setAutofocus: async ({ deviceId, enabled }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					await api.setAutoFocus(channel, enabled ? 0 : 1);
+					try {
+						const a = (await api.getAutoFocus(channel, { timeoutMs: 1500 }))?.body?.AutoFocus;
+						if (a) await this.config.setAll({ deviceCache: {
+							...this.config.get("deviceCache"),
+							autoFocusSnapshot: {
+								enabled: typeof a.disable === "number" ? a.disable === 0 : null,
+								supported: true
+							}
+						} });
+					} catch {}
+				}
+			};
+			this.registerCapWarmer("ptz", async () => {
+				await ptzProvider.getOptions({ deviceId: this.id });
+			});
+			this.ctx.registerNativeCap(ptzCapability, ptzProvider);
+		}
 	}
 	/**
 	* Translate normalized (-1..1) pan/tilt/zoom to one or more discrete
@@ -225262,6 +225404,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		if (this.batteryUpdateInFlight) return this.batteryUpdateInFlight;
 		const cycle = (async () => {
 			try {
+				if (!this.allowProactiveCameraAccess("battery-update")) {
+					this.ctx.logger.debug("battery-update: cam sleeping — skipping cycle without connecting", { tags: { deviceId: this.id } });
+					return;
+				}
 				let api;
 				try {
 					api = await this.ensureApi();
@@ -225360,6 +225506,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
 		}
+		await this.warmCapSlicesOnWake();
+		await this.warmSnapshotOnWake();
 		await this.alignAuxDevicesState("wake");
 		await this.refreshParentSettingsSnapshot();
 	}
@@ -227113,6 +227261,13 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		if (this.api) return this.api;
 		if (this.loginPromise) return this.loginPromise;
+		if (this.isBattery && this.sleeping) {
+			const frames = (/* @__PURE__ */ new Error("wake-attribution")).stack?.split("\n").slice(2, 7).join(" | ");
+			this.ctx.logger.info("battery cam login while sleeping — this wakes the camera", {
+				tags: { deviceId: this.id },
+				meta: { caller: frames ?? "unavailable" }
+			});
+		}
 		const host = this.config.get("host");
 		const port = this.config.get("port");
 		const username = this.config.get("username");

package/dist/addon.mjs

@@ -222600,6 +222600,33 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	markWakeIssued() {
 		this.lastProactiveWakeAt = Date.now();
 	}
+	/**
+	* Gate for a PROACTIVE camera read, checked BEFORE `ensureApi()`.
+	*
+	* The login itself is the wake. On a sleeping UDP/battery camera the
+	* lib's discovery + handshake nudges the firmware awake (same reason
+	* `refreshParentSettingsSnapshot` refuses to call `ensureApi` while
+	* asleep), so gating only the explicit `wakeUp()` call is useless —
+	* by the time we reach it the camera is already up. Production logs
+	* showed exactly that: a background read produced a full
+	* `Connecting to Reolink` → BCUDP discovery → `battery sleep state
+	* committed` (awake) → whole refresh cascade, on a camera that had
+	* been asleep for six minutes.
+	*
+	* Returns `false` when the caller must serve cache / bail out without
+	* touching the socket. Stamps the cooldown when it does let a wake
+	* through, so "at most one proactive wake per
+	* `PROACTIVE_WAKE_COOLDOWN_MS`" holds across ALL proactive callers
+	* rather than per-caller.
+	*
+	* Demand-driven paths never call this — see `canProactivelyWake`.
+	*/
+	allowProactiveCameraAccess(reason) {
+		if (!this.isBattery || !this.sleeping) return true;
+		if (!this.canProactivelyWake(reason)) return false;
+		this.markWakeIssued();
+		return true;
+	}
 	updateBatteryCache(info) {
 		this.setCapSlice(batteryCapability, this.mapBatteryInfo(info));
 	}
@@ -222845,6 +222872,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	}
 	async fetchSnapshotWithSingleFlight() {
 		if (this.snapshotInFlight) return this.snapshotInFlight;
+		if (!this.allowProactiveCameraAccess("snapshot")) {
+			this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
+			return null;
+		}
 		const promise = (async () => {
 			let api;
 			try {
@@ -222862,23 +222893,16 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				} catch {
 					return true;
 				}
-			})()) {
-				if (!this.canProactivelyWake("snapshot")) {
-					this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
-					return null;
-				}
-				this.markWakeIssued();
-				try {
-					await api.wakeUp(this.getChannel(), {
-						waitAfterWakeMs: 1500,
-						attempts: 2
-					});
-				} catch (err) {
-					this.ctx.logger.debug("snapshot: pre-wake failed (will still try getSnapshot)", {
-						tags: { deviceId: this.id },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-				}
+			})()) try {
+				await api.wakeUp(this.getChannel(), {
+					waitAfterWakeMs: 1500,
+					attempts: 2
+				});
+			} catch (err) {
+				this.ctx.logger.debug("snapshot: pre-wake failed (will still try getSnapshot)", {
+					tags: { deviceId: this.id },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
 			}
 			const tryOnce = async (timeoutMs) => {
 				const buf = await api.getSnapshot(this.getChannel(), {
@@ -223421,6 +223445,97 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 	}
 	/**
+	* Per-cap "warm the cache while the camera is up" closures, registered
+	* by each device-config cap alongside its provider and run by
+	* `onWakeTransition`.
+	*
+	* This is the OTHER half of the read discipline. Gating reads stops us
+	* waking the camera, but on its own it leaves the caches empty — and an
+	* empty cache is what the operator actually sees: the State panel reads
+	* the runtime-state slices (`deviceState.getAllSnapshots`), so a
+	* sleeping camera whose slices were never written shows null for
+	* everything. Before the gate, the admin UI's 2.5s aggregate poll kept
+	* those slices warm by waking the camera every time — the very bug we
+	* fixed. So the refresh has to move to the moment the camera is
+	* ALREADY up, which is exactly the wake transition.
+	*/
+	capWarmers = /* @__PURE__ */ new Map();
+	/** How fresh a slice must be for the wake warm-up to skip it. A battery
+	*  cam can wake many times an hour on motion; re-probing every cap on
+	*  every wake would spend the (~14s) window on data we already have. */
+	static WAKE_WARM_MAX_AGE_MS = 10 * 6e4;
+	registerCapWarmer(capName, warm) {
+		this.capWarmers.set(capName, warm);
+	}
+	/**
+	* Refresh the device-config cap caches during a wake window.
+	*
+	* SERIALIZED, like every other wake-path refresh — concurrent Baichuan
+	* traffic on the single BCUDP stream starves the heavy reads. Each cap
+	* is skipped when its slice is still fresh, and each failure is
+	* swallowed: the window is short, partial progress accumulates across
+	* wakes because the slices persist.
+	*/
+	async warmCapSlicesOnWake() {
+		const now = Date.now();
+		let warmed = 0;
+		let skipped = 0;
+		for (const [capName, warm] of this.capWarmers) {
+			const slice = this.runtimeState.getCapState(capName);
+			const fetchedAt = typeof slice?.lastFetchedAt === "number" ? slice.lastFetchedAt : 0;
+			if (fetchedAt > 0 && now - fetchedAt < ReolinkCamera.WAKE_WARM_MAX_AGE_MS) {
+				skipped += 1;
+				continue;
+			}
+			try {
+				await warm();
+				warmed += 1;
+			} catch (err) {
+				this.ctx.logger.debug("wake warm-up: cap refresh failed — retrying on next wake", {
+					tags: { deviceId: this.id },
+					meta: {
+						capName,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.ctx.logger.info("wake warm-up: cap caches refreshed", {
+			tags: { deviceId: this.id },
+			meta: {
+				warmed,
+				skipped,
+				total: this.capWarmers.size
+			}
+		});
+	}
+	/**
+	* Ask the snapshot wrapper for a frame while the camera is up, so its
+	* cache holds something recent to serve for the whole sleep window.
+	*
+	* The wrapper already does the right thing on a miss — `resolveOutcome`
+	* falls back to the stale frame rather than blanking the UI — but only
+	* if a frame was ever captured. With reads gated, nothing captures one
+	* any more: the tile stayed empty for as long as the camera slept.
+	* `force: true` bypasses the wrapper's freshness gate; our own
+	* proactive gate lets it through because `sleeping` is false here.
+	* Mirrors the reference's `updateBatteryAndSnapshot`.
+	*/
+	async warmSnapshotOnWake() {
+		try {
+			await this.ctx.api.snapshot.getSnapshot.query({
+				deviceId: this.id,
+				force: true
+			});
+			this.ctx.logger.debug("wake warm-up: snapshot cache refreshed", { tags: { deviceId: this.id } });
+		} catch (err) {
+			this.ctx.logger.debug("wake warm-up: snapshot refresh failed", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+	}
+	/**
 	* Wrap a cap's `refreshFromCamera` so the READ side (the bridge's
 	* stale-check behind `getStatus`) never wakes a sleeping battery cam.
 	* The bridge then projects whatever the slice last held — which is
@@ -223525,6 +223640,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				this.ctx.eventBus.emit(createEvent(EventCategory.StreamParamsChanged, this.eventSource(), { deviceId: this.id }));
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(streamParamsCapability, provider);
 		this.ctx.logger.info("Reolink stream-params cap registered", { tags: { deviceId: this.id } });
 	}
@@ -223715,6 +223834,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(motionZonesCapability, provider);
 		this.ctx.logger.info("Reolink motion-zones cap registered", { tags: { deviceId: this.id } });
 	}
@@ -223850,6 +223973,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				});
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(privacyMaskCapability, provider);
 		this.ctx.logger.info("Reolink privacy-mask cap registered (read + enable + zone write)", { tags: { deviceId: this.id } });
 	}
@@ -223985,6 +224112,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(dayNightCapability, provider);
 		this.ctx.logger.info("Reolink day-night cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224122,6 +224253,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, async () => {
+			await provider.getOptions({ deviceId: this.id });
+			await refreshFromCamera();
+		});
 		this.ctx.registerNativeCap(imageSettingsCapability, provider);
 		this.ctx.logger.info("Reolink image-settings cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224391,6 +224526,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				await refreshFromCamera();
 			}
 		};
+		this.registerCapWarmer(CAP_NAME, refreshFromCamera);
 		this.ctx.registerNativeCap(ptzAutotrackCapability, provider);
 		this.ctx.logger.info("Reolink ptz-autotrack cap registered", { tags: { deviceId: this.id } });
 	}
@@ -224398,148 +224534,154 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		if (this.ptzRegistered) return;
 		if (!this.getProbeFlags().hasPtz) return;
 		this.ptzRegistered = true;
-		this.ctx.registerNativeCap(ptzCapability, {
-			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
-				if (deviceId !== this.id) return;
-				await this.runPtz(pan, tilt, zoom, speed, false);
-			},
-			continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
-				if (deviceId !== this.id) return;
-				await this.runPtz(pan, tilt, zoom, speed, true);
-			},
-			stop: async ({ deviceId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				try {
-					await api.ptz(channel, {
-						action: "stop",
-						command: "Up"
-					});
-				} catch {}
-			},
-			getPresets: async ({ deviceId }) => {
-				if (deviceId !== this.id) return [];
-				try {
+		{
+			const ptzProvider = {
+				move: async ({ deviceId, pan, tilt, zoom, speed }) => {
+					if (deviceId !== this.id) return;
+					await this.runPtz(pan, tilt, zoom, speed, false);
+				},
+				continuousMove: async ({ deviceId, pan, tilt, zoom, speed }) => {
+					if (deviceId !== this.id) return;
+					await this.runPtz(pan, tilt, zoom, speed, true);
+				},
+				stop: async ({ deviceId }) => {
+					if (deviceId !== this.id) return;
 					const api = await this.ensureApi();
 					const channel = this.getChannel();
-					return (await api.getPtzPresets(channel)).map((p) => ({
-						id: String(p.id),
-						name: p.name
-					}));
-				} catch {
-					return [];
-				}
-			},
-			goToPreset: async ({ deviceId, presetId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.moveToPtzPreset(channel, id);
-			},
-			savePreset: async ({ deviceId, presetId, name }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.setPtzPreset(channel, id, name);
-			},
-			deletePreset: async ({ deviceId, presetId }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				const id = Number(presetId);
-				if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
-				await api.deletePtzPreset(channel, id);
-			},
-			getOptions: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					hasPan: false,
-					hasTilt: false,
-					hasZoom: false,
-					supportsPresets: false,
-					hasAutofocus: false
-				};
-				const hasAutofocus = this.config.get("deviceCache")?.autoFocusSnapshot?.supported === true;
-				return this.resolveCapOptions({
-					capName: "ptz",
-					schema: PtzOptionsSchema,
-					probe: async () => {
-						const { capabilities } = await (await this.ensureApi()).getDeviceCapabilities(this.getChannel());
-						return {
-							hasPan: capabilities.hasPan,
-							hasTilt: capabilities.hasTilt,
-							hasZoom: capabilities.hasZoom,
-							supportsPresets: capabilities.hasPresets,
-							hasAutofocus
-						};
-					},
-					fallback: () => {
-						const hasPtz = this.getProbeFlags().hasPtz === true;
-						return {
-							hasPan: hasPtz,
-							hasTilt: hasPtz,
-							hasZoom: hasPtz,
-							supportsPresets: hasPtz,
-							hasAutofocus
-						};
+					try {
+						await api.ptz(channel, {
+							action: "stop",
+							command: "Up"
+						});
+					} catch {}
+				},
+				getPresets: async ({ deviceId }) => {
+					if (deviceId !== this.id) return [];
+					try {
+						const api = await this.ensureApi();
+						const channel = this.getChannel();
+						return (await api.getPtzPresets(channel)).map((p) => ({
+							id: String(p.id),
+							name: p.name
+						}));
+					} catch {
+						return [];
 					}
-				});
-			},
-			goHome: async ({ deviceId }) => {
-				if (deviceId !== this.id) return;
-				try {
+				},
+				goToPreset: async ({ deviceId, presetId }) => {
+					if (deviceId !== this.id) return;
 					const api = await this.ensureApi();
 					const channel = this.getChannel();
-					await api.moveToPtzPreset(channel, 0);
-				} catch {}
-			},
-			getPosition: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
-				};
-				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0
-				};
-			},
-			getStatus: async ({ deviceId }) => {
-				if (deviceId !== this.id) return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
-					autofocus: false
-				};
-				return {
-					pan: 0,
-					tilt: 0,
-					zoom: 0,
-					autofocus: (this.config.get("deviceCache")?.autoFocusSnapshot)?.enabled === true
-				};
-			},
-			setAutofocus: async ({ deviceId, enabled }) => {
-				if (deviceId !== this.id) return;
-				const api = await this.ensureApi();
-				const channel = this.getChannel();
-				await api.setAutoFocus(channel, enabled ? 0 : 1);
-				try {
-					const a = (await api.getAutoFocus(channel, { timeoutMs: 1500 }))?.body?.AutoFocus;
-					if (a) await this.config.setAll({ deviceCache: {
-						...this.config.get("deviceCache"),
-						autoFocusSnapshot: {
-							enabled: typeof a.disable === "number" ? a.disable === 0 : null,
-							supported: true
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.moveToPtzPreset(channel, id);
+				},
+				savePreset: async ({ deviceId, presetId, name }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.setPtzPreset(channel, id, name);
+				},
+				deletePreset: async ({ deviceId, presetId }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					const id = Number(presetId);
+					if (!Number.isFinite(id)) throw new Error(`Invalid presetId: ${presetId}`);
+					await api.deletePtzPreset(channel, id);
+				},
+				getOptions: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						hasPan: false,
+						hasTilt: false,
+						hasZoom: false,
+						supportsPresets: false,
+						hasAutofocus: false
+					};
+					const hasAutofocus = this.config.get("deviceCache")?.autoFocusSnapshot?.supported === true;
+					return this.resolveCapOptions({
+						capName: "ptz",
+						schema: PtzOptionsSchema,
+						probe: async () => {
+							const { capabilities } = await (await this.ensureApi()).getDeviceCapabilities(this.getChannel());
+							return {
+								hasPan: capabilities.hasPan,
+								hasTilt: capabilities.hasTilt,
+								hasZoom: capabilities.hasZoom,
+								supportsPresets: capabilities.hasPresets,
+								hasAutofocus
+							};
+						},
+						fallback: () => {
+							const hasPtz = this.getProbeFlags().hasPtz === true;
+							return {
+								hasPan: hasPtz,
+								hasTilt: hasPtz,
+								hasZoom: hasPtz,
+								supportsPresets: hasPtz,
+								hasAutofocus
+							};
 						}
-					} });
-				} catch {}
-			}
-		});
+					});
+				},
+				goHome: async ({ deviceId }) => {
+					if (deviceId !== this.id) return;
+					try {
+						const api = await this.ensureApi();
+						const channel = this.getChannel();
+						await api.moveToPtzPreset(channel, 0);
+					} catch {}
+				},
+				getPosition: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0
+					};
+					return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0
+					};
+				},
+				getStatus: async ({ deviceId }) => {
+					if (deviceId !== this.id) return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0,
+						autofocus: false
+					};
+					return {
+						pan: 0,
+						tilt: 0,
+						zoom: 0,
+						autofocus: (this.config.get("deviceCache")?.autoFocusSnapshot)?.enabled === true
+					};
+				},
+				setAutofocus: async ({ deviceId, enabled }) => {
+					if (deviceId !== this.id) return;
+					const api = await this.ensureApi();
+					const channel = this.getChannel();
+					await api.setAutoFocus(channel, enabled ? 0 : 1);
+					try {
+						const a = (await api.getAutoFocus(channel, { timeoutMs: 1500 }))?.body?.AutoFocus;
+						if (a) await this.config.setAll({ deviceCache: {
+							...this.config.get("deviceCache"),
+							autoFocusSnapshot: {
+								enabled: typeof a.disable === "number" ? a.disable === 0 : null,
+								supported: true
+							}
+						} });
+					} catch {}
+				}
+			};
+			this.registerCapWarmer("ptz", async () => {
+				await ptzProvider.getOptions({ deviceId: this.id });
+			});
+			this.ctx.registerNativeCap(ptzCapability, ptzProvider);
+		}
 	}
 	/**
 	* Translate normalized (-1..1) pan/tilt/zoom to one or more discrete
@@ -225242,6 +225384,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		if (this.batteryUpdateInFlight) return this.batteryUpdateInFlight;
 		const cycle = (async () => {
 			try {
+				if (!this.allowProactiveCameraAccess("battery-update")) {
+					this.ctx.logger.debug("battery-update: cam sleeping — skipping cycle without connecting", { tags: { deviceId: this.id } });
+					return;
+				}
 				let api;
 				try {
 					api = await this.ensureApi();
@@ -225340,6 +225486,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
 		}
+		await this.warmCapSlicesOnWake();
+		await this.warmSnapshotOnWake();
 		await this.alignAuxDevicesState("wake");
 		await this.refreshParentSettingsSnapshot();
 	}
@@ -227093,6 +227241,13 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		if (this.api) return this.api;
 		if (this.loginPromise) return this.loginPromise;
+		if (this.isBattery && this.sleeping) {
+			const frames = (/* @__PURE__ */ new Error("wake-attribution")).stack?.split("\n").slice(2, 7).join(" | ");
+			this.ctx.logger.info("battery cam login while sleeping — this wakes the camera", {
+				tags: { deviceId: this.id },
+				meta: { caller: frames ?? "unavailable" }
+			});
+		}
 		const host = this.config.get("host");
 		const port = this.config.get("port");
 		const username = this.config.get("username");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-reolink",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Reolink camera device provider addon for CamStack — native Baichuan protocol",
   "keywords": [
     "camstack",