@camstack/addon-provider-reolink 1.2.142 → 1.2.144

package/dist/addon.mjs

@@ -5381,7 +5381,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-Bs3xPtSh.mjs
+//#region ../types/dist/sleep-CiR4z7r9.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6523,6 +6523,17 @@ var CamProfileSchema = _enum([
 	"mid",
 	"low"
 ]);
+/**
+* Which rung a per-camera consumer listens on: an explicit profile, or `auto`.
+*
+* `auto` is a REAL value, not an absent one — it means "resolve it by the rule
+* that consumer owns". It lives beside `CamProfile` because a rung is the only
+* operator-facing way to name a stream: a cam-stream id is broker-internal and
+* moves when a slot is reassigned, so a stored id silently stops meaning what
+* the operator picked. Today's one user is the audio analyser, whose rule is
+* "the lowest AVAILABLE native rung" (D537).
+*/
+var AudioStreamPickSchema = union([CamProfileSchema, literal("auto")]);
 var CamStreamKindSchema = _enum([
 	"pull-rtsp",
 	"pull-rtmp",
@@ -7789,6 +7800,7 @@ var CameraSwitchIdSchema = _enum([
 	"device-audio",
 	"broker-audio",
 	"audio-analysis",
+	"event-saving",
 	"recording",
 	"notifications"
 ]);
@@ -8263,11 +8275,31 @@ var RecordingBandTriggersSchema = RecordingTriggersSchema;
 * band engine's `applies` rule). `start`/`end` are `HH:MM`; an `end <= start`
 * span wraps past midnight (handled by the band engine).
 */
+/**
+* Whether a band's footage carries sound.
+*
+* The recorder has always attached with `audio: 'aac'`, so every band of every
+* camera recorded sound whether anyone wanted it or not. The broker already
+* serves the other answer — `audio: 'none'` takes the video-only `/muted`
+* restream — so this was a choice the product could always have offered.
+*
+* It belongs on the BAND rather than the camera because one camera can want
+* both: silent across the shop floor during opening hours, sound overnight.
+* And it applies to BOTH modes — an events band firing on motion has the same
+* question to answer as a continuous one.
+*/
+var RecordingBandAudioSchema = _enum(["on", "muted"]);
 var RecordingBandSchema = object({
 	days: array(RecordingWeekdaySchema),
 	start: string().regex(HHMM),
 	end: string().regex(HHMM),
 	mode: RecordingBandModeSchema,
+	/**
+	* Sound, or silence. OPTIONAL and absent-means-`on`: every recording
+	* written before this existed carried sound, and a band whose key is
+	* missing must keep meaning what it meant. See {@link RecordingBandAudioSchema}.
+	*/
+	audio: RecordingBandAudioSchema.optional(),
 	triggers: RecordingBandTriggersSchema.optional(),
 	/**
 	* RETIRED (D381). A band no longer carries a pre-buffer of its own.
@@ -20889,6 +20921,7 @@ var MediaFileKindEnum = _enum([
 	"keyFrameSmall",
 	"thumbnailSmall",
 	"confirmationCrop",
+	"debugCrop",
 	"sceneFrame"
 ]);
 /**
@@ -22553,6 +22586,18 @@ var RunnerCameraConfigSchema = object({
 	motionStreamId: string(),
 	detectionStreamId: string(),
 	/**
+	* Which rung this camera's audio analysis listens on — `auto` (the lowest
+	* AVAILABLE native rung) or an explicit one.
+	*
+	* Not consumed by the runner: carried here so it travels with the camera's
+	* config the way `audioMotionWindowMs` does, and so the orchestrator's
+	* watchdog resolves the same stream the audio subscription did. OPTIONAL
+	* with no default — absent means `auto`, which is what every camera written
+	* before this field had, and an absent optional adds nothing to the
+	* generated cap-input defaults (D537).
+	*/
+	audioStreamPick: AudioStreamPickSchema.optional(),
+	/**
 	* Motion sources that can activate the pipeline. At least one must
 	* be present. Multiple sources OR-ed: any one firing arms the
 	* cooldown timer and transitions watching → active. The same
@@ -25148,6 +25193,104 @@ var WebrtcStreamChoiceSchema = object({
 	/** Bitrate in kbps (null for adaptive). */
 	bitrateKbps: number().nullable()
 });
+/**
+* The last move the adaptive ladder made on this session, and the numbers it
+* rested on. Mirrors `LadderDecision` in the stream-broker's
+* `adaptive-controller.ts` — the log line's evidence, made readable.
+*
+* Nullability is load-bearing: `lossRatio: null` means the loss tracker had
+* no window to report, which is NOT a link with zero loss.
+*/
+var WebrtcLadderDecisionSchema = object({
+	/** `loss` — RTCP / client-reported packet loss; `stall` — the picture
+	*  stopped moving; `healthy` — a promotion. */
+	cause: _enum([
+		"loss",
+		"stall",
+		"healthy"
+	]),
+	/** The rung the ladder moved TO. Null for a move that changed no rung
+	*  (an MTU reduction, a forced transcode-down at the bottom). */
+	tier: CamProfileSchema.nullable(),
+	/** Whether that move forced the egress transcode-down rung. */
+	forcedTranscodeDown: boolean(),
+	/** Loss ratio over the tracker's window at the moment of the decision. */
+	lossRatio: number().nullable(),
+	/** The client's reported downlink at that moment, in kbps. */
+	clientKbps: number().nullable(),
+	/** How long the stall detector had been seeing nothing arrive. */
+	stalledForMs: number().nullable(),
+	/** Whether the broker WAS sending while that was measured — the half that
+	*  separates "the camera stopped" from "the link stopped". */
+	serverSending: boolean().nullable(),
+	/** Epoch ms. The overlay prints its age; a decision from 40 minutes ago
+	*  must not read like one from this second. */
+	at: number()
+});
+/** Per-tier count of MEASURED downgrades this viewer session has suffered. */
+var WebrtcTierFailureSchema = object({
+	tier: CamProfileSchema,
+	failures: number().int().nonnegative()
+});
+/**
+* What the SERVER decided for one WebRTC session — the half the client cannot
+* measure. See `getSessionDebug`.
+*/
+var WebrtcSessionDebugSchema = object({
+	sessionId: string(),
+	/** Whether the session still exists here. Everything below is null when
+	*  it does not — a dead session has no measurements, not zero ones. */
+	alive: boolean(),
+	/** Epoch ms this snapshot was taken, so the overlay can show its age. */
+	observedAt: number(),
+	/** The broker actually feeding this session (`<deviceId>/<camStreamId>`). */
+	brokerId: string().nullable(),
+	camStreamId: string().nullable(),
+	/** `derived` = this hub BUILT the rung being served (a transcode/scale of
+	*  another stream); `native` = the camera's own encode. */
+	sourceKind: _enum([
+		"native",
+		"derived",
+		"unknown"
+	]),
+	/** Whether the ladder is running at all (an `adaptive` target). */
+	adaptive: boolean(),
+	/** The rung `auto` ACTUALLY resolved to right now. Null when the broker
+	*  is bound to no profile slot (a manually-activated stream). */
+	servedTier: CamProfileSchema.nullable(),
+	/** Which node ingests the source. Null when unresolved. */
+	ingestNodeId: string().nullable(),
+	/** Whether that node is a remote one (the media crosses a node boundary
+	*  before it reaches this session). Null when unresolved. */
+	ingestIsRemote: boolean().nullable(),
+	/** Codec off the source, and the one negotiated with this client. */
+	sourceCodec: string().nullable(),
+	negotiatedCodec: string().nullable(),
+	/** Whether the EGRESS leg re-encodes for this client or forwards the
+	*  source bytes untouched. */
+	egressLeg: _enum([
+		"copy",
+		"transcode",
+		"unknown"
+	]),
+	/** What the broker itself reports about the rung it is serving. */
+	brokerStatus: string().nullable(),
+	brokerCodec: string().nullable(),
+	brokerBitrateKbps: number().nullable(),
+	brokerInputFps: number().nullable(),
+	brokerUptimeMs: number().nullable(),
+	/** RTP packets this session has sent — the server's own "am I sending?". */
+	rtpPacketsSent: number().nullable(),
+	/** D42: the track may be carrying the recorded feeder, not live. The ladder
+	*  is suspended there, so a frozen picture in `recorded` mode means
+	*  something entirely different. */
+	trackMode: _enum(["live", "recorded"]).nullable(),
+	lastDecision: WebrtcLadderDecisionSchema.nullable(),
+	tierFailures: array(WebrtcTierFailureSchema),
+	/** Successful promotions in this viewer session (drives the progressive
+	*  healthy timer). Null when no ladder is running. */
+	upgradeCount: number().nullable()
+});
 DeviceType.Camera, method(object({ deviceId: number().int().nonnegative() }), array(WebrtcStreamChoiceSchema)), method(object({
 	deviceId: number().int().nonnegative(),
 	target: WebrtcStreamTargetSchema,
@@ -25312,7 +25455,10 @@ DeviceType.Camera, method(object({ deviceId: number().int().nonnegative() }), ar
 	* the same answer as "it ended": either way nothing is holding it up.
 	*/
 	alive: boolean()
-}));
+})), method(object({
+	deviceId: number().int().nonnegative(),
+	sessionId: string()
+}), WebrtcSessionDebugSchema, { kind: "query" });
 object({
 	/** All accessory children of the parent. */
 	childDeviceIds: array(number()).readonly(),
@@ -29647,11 +29793,15 @@ var motionTriggerCapability = {
 *
 * Adding a fifth name to that list would have been the wrong fix twice over:
 * that page is per-camera DETECTION tuning, and a grid's geometry belongs
-* beside PTZ and motion zones on the camera itself — which is exactly where the
-* framework already puts a widget, when the widget is declared on a CAPABILITY.
-* `deviceConfig.ui` is the mechanism (`motion-zones`, `ptz`, `ptz-autotrack`
-* all use it): the framework emits the structural section and the widget
-* self-persists through the cap's own mutations.
+* beside PTZ and motion zones on the camera itself. The device page is
+* BINDING-driven (D12), so the way in is a capability bound to the device —
+* and this cap carries its section the way `recording` does, by RETURNING it
+* from `getDeviceSettingsContribution`.
+*
+* Seven other widgets are still declared the other way, through a
+* `deviceConfig.ui` block the framework derives a section from. That route
+* gives the addon no say in where its own panel lands and no way to decline
+* for a device the panel does not suit, which is why this one does not use it.
 *
 * ## Why one addon may implement it
 *
@@ -29707,16 +29857,37 @@ var GridProfileOfferSchema = object({
 	]),
 	offered: boolean(),
 	/** Sources that cannot serve it. Empty when it is offered, or when there are no cells. */
-	missingSources: array(number().int().positive())
+	missingSources: array(number().int().positive()),
+	/**
+	* The canvas this profile composes onto, `WxH`, or empty when it is not
+	* offered. DERIVED from the cells and the sources' own size at this profile —
+	* it is reported because nothing else in the system would ever say what the
+	* grid came out as, and because it is the number an operator would otherwise
+	* expect to type.
+	*/
+	canvas: string(),
+	/**
+	* Whether this profile is PUBLISHED, of the ones the grid could serve.
+	*
+	* A grid's `high` is composed of its sources' `high`, so on a 4K fleet it is
+	* a 4K canvas built from 4K decodes — something to opt into, not something a
+	* viewer's adaptive should be handed by climbing to the top rung it can see.
+	* Default is `mid` + `low`.
+	*/
+	published: boolean()
 });
 var GridLayoutViewSchema = object({
 	/** The persisted grid row this camera was declared from. */
 	instanceId: string(),
 	deviceId: number().int().nonnegative(),
 	name: string(),
-	/** The canvas the operator laid out — this grid's `high`. mid/low are scaled from it. */
-	width: number().int(),
-	height: number().int(),
+	/**
+	* NO canvas size. A grid's resolution is not authored: each profile derives
+	* its own from the cells and its sources' dimensions. The two numbers that
+	* used to be here were a text field that silently decided both how much the
+	* composite cost and how sharp it was — see `profiles[].canvas` for what it
+	* came out as.
+	*/
 	fps: number().int(),
 	cells: array(GridLayoutCellSchema),
 	/** What the catalog will publish, and what it refuses to. Read-only. */
@@ -29725,9 +29896,13 @@ var GridLayoutViewSchema = object({
 var GridLayoutPatchSchema = object({
 	deviceId: number().int().nonnegative(),
 	name: string().min(1).max(160).optional(),
-	width: number().int().min(160).max(7680).optional(),
-	height: number().int().min(120).max(4320).optional(),
 	fps: number().int().min(1).max(60).optional(),
+	/** Which profiles to publish. See `GridProfileOffer.published`. */
+	publishedProfiles: array(_enum([
+		"high",
+		"mid",
+		"low"
+	])).max(3).optional(),
 	/**
 	* The whole cell list at once. A per-cell patch would need an ordering the
 	* editor does not have, and a half-applied layout is a picture nobody asked
@@ -32142,6 +32317,25 @@ var ptzAutotrackCapability = {
 	scope: "device",
 	deviceNative: true,
 	mode: "singleton",
+	/**
+	* Two kinds of provider behind one name, the same shape `snapshot` and
+	* `doorbell` use:
+	*
+	*  - **Native**: the camera's own firmware autotrack, registered per device by
+	*    the driver when the probe says it exists (Reolink: yes; Hikvision:
+	*    model-dependent).
+	*  - **Wrapper**: the emulated implementation (`@camstack/system`'s `autotrack` builtin),
+	*    which follows a subject with `ptz.move` pulses driven by the detection
+	*    pipeline. `defaultActive: false` — the operator binds it per camera in
+	*    the bindings UI, exactly as `virtual-doorbell` is bound.
+	*
+	* The binding chooses WHICH implementation answers; `setEnabled` stays the
+	* one switch for the function either way. A camera never has both driving its
+	* head, which is the whole reason this is not a second cap with a second
+	* toggle (D62, D520).
+	*/
+	kind: "wrapper",
+	defaultActive: false,
 	deviceTypes: [DeviceType.Camera],
 	deviceConfig: { ui: {
 		kind: "widget",
@@ -43513,6 +43707,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"webrtcSession.getSessionDebug": {
+		capName: "webrtc-session",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"webrtcSession.getSessionState": {
 		capName: "webrtc-session",
 		capScope: "device",
@@ -45496,6 +45696,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"webrtcSession.getSessionDebug": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"webrtcSession.getSessionState": [{
 		name: "deviceId",
 		form: "single",
@@ -75181,7 +75386,7 @@ var require_lz4 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	};
 }));
 //#endregion
-//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-CE77DTET.js
+//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-7JMYBUEB.js
 var import_fxp = require_fxp();
 var import_lz4 = /* @__PURE__ */ __toESM(require_lz4(), 1);
 function encodeHeader(h) {
@@ -83641,10 +83846,14 @@ function applyOsdDatetimePatch(rawXml, patch) {
 	return xml;
 }
 var OSD_POSITION_MAX = 65536;
+var OSD_POSITION_START_WRITE = 1;
+var OSD_POSITION_CENTER = 65537;
 var OSD_CORNERS = [
 	"top-left",
+	"top-center",
 	"top-right",
 	"bottom-left",
+	"bottom-center",
 	"bottom-right"
 ];
 function isStartEdge(value) {
@@ -83656,7 +83865,7 @@ function isEndEdge(value) {
 function readOsdPosition(x, y) {
 	if (typeof x !== "number" || typeof y !== "number") return { kind: "unknown" };
 	if (!Number.isFinite(x) || !Number.isFinite(y)) return { kind: "unknown" };
-	const horizontal = isStartEdge(x) ? "left" : isEndEdge(x) ? "right" : null;
+	const horizontal = x === OSD_POSITION_CENTER ? "center" : isStartEdge(x) ? "left" : isEndEdge(x) ? "right" : null;
 	const vertical = isStartEdge(y) ? "top" : isEndEdge(y) ? "bottom" : null;
 	if (horizontal === null || vertical === null) return {
 		kind: "custom",
@@ -83670,8 +83879,8 @@ function readOsdPosition(x, y) {
 }
 function coordsForOsdCorner(corner) {
 	return {
-		x: corner.endsWith("-right") ? OSD_POSITION_MAX : 0,
-		y: corner.startsWith("bottom-") ? OSD_POSITION_MAX : 0
+		x: corner.endsWith("-center") ? OSD_POSITION_CENTER : corner.endsWith("-right") ? OSD_POSITION_MAX : OSD_POSITION_START_WRITE,
+		y: corner.startsWith("bottom-") ? OSD_POSITION_MAX : OSD_POSITION_START_WRITE
 	};
 }
 function isOsdCorner(value) {
@@ -83682,8 +83891,10 @@ function formatOsdCoords(x, y) {
 }
 var OSD_CORNER_LABELS = {
 	"top-left": "Top left",
+	"top-center": "Top centre",
 	"top-right": "Top right",
 	"bottom-left": "Bottom left",
+	"bottom-center": "Bottom centre",
 	"bottom-right": "Bottom right"
 };
 function wireFloat(value) {
@@ -88210,8 +88421,12 @@ var ReolinkBaichuanApi = class _ReolinkBaichuanApi {
 	/** Generic Baichuan cmd_id call, returns XML (if any). */
 	async sendXml(params, retry = 3) {
 		if (!this.client.loggedIn) await this.client.login();
-		const frame = await this.client.sendFrame(params);
-		if (frame.header.responseCode === 400) return await this.handleSendXml400(params, frame, retry);
+		const addressed = params.channel != null && params.extensionXml == null ? {
+			...params,
+			extensionXml: buildChannelExtensionXml(params.channel)
+		} : params;
+		const frame = await this.client.sendFrame(addressed);
+		if (frame.header.responseCode === 400) return await this.handleSendXml400(addressed, frame, retry);
 		if (frame.body.length === 0) return "";
 		return this.client.tryDecryptXml(frame.body, frame.header.channelId, this.client.enc);
 	}
@@ -94512,6 +94727,7 @@ ${xml}`);
 		await this.sendXml({
 			cmdId: 45,
 			channel: ch,
+			extensionXml: buildChannelExtensionXml(ch),
 			payloadXml: ensureXmlHeader(xml),
 			...timeoutOpts
 		});
@@ -145546,6 +145762,7 @@ var RAW_READ_CATALOG = {
 			kind: "deviceCache",
 			snapshotKey: "autoFocusSnapshot"
 		},
+		needs: "ptz",
 		invoke: (api, channel) => api.getAutoFocus(channel, { timeoutMs: 1500 })
 	},
 	netPort: {
@@ -145742,6 +145959,7 @@ var RawReadResultSchema = discriminatedUnion("ok", [object({
 	slice: RawReadSliceSchema,
 	reason: _enum([
 		"sleeping",
+		"unsupported",
 		"login-failed",
 		"read-failed"
 	]),
@@ -145785,6 +146003,20 @@ function toPlainJson(value) {
 async function performRawRead(slice, deps) {
 	const entry = RAW_READ_CATALOG[slice];
 	const believed = believedState(deps, entry);
+	if (entry.needs === "ptz" && !deps.hasPtz) {
+		deps.logger.info("reolink raw read refused — the camera has no PTZ head", {
+			tags: { deviceId: deps.deviceId },
+			meta: { slice }
+		});
+		return {
+			ok: false,
+			deviceId: deps.deviceId,
+			slice,
+			reason: "unsupported",
+			message: `This camera has no pan/tilt/zoom head, so it has no focus motor and no "${slice}" to read — the Reolink app does not ask it either. Nothing is wrong with the camera.`,
+			believed
+		};
+	}
 	const servedWithoutTouchingCamera = deps.hubChild && entry.servedByParentHub === true;
 	if (deps.sleeping && !servedWithoutTouchingCamera) {
 		deps.logger.info("reolink raw read refused — battery cam is sleeping", {
@@ -149448,7 +149680,6 @@ var reolinkCameraSchema = object({
 	* read via 52). Toggles the `<Shelter><enable>` flag. Zone
 	* editing is a separate flow not exposed by this driver.
 	*/
-	privacyMaskEnabled: boolean().optional(),
 	/**
 	* Audio noise reduction level — pushed via `setAudioNoise`
 	* (cmd_id 440, read via 439). 0 disables; 1..3 maps to
@@ -150282,7 +150513,6 @@ function slicesForPatch(patch) {
 	if (has("motionEnabled", "motionSensitivity")) out.add("motion");
 	if (Object.keys(patch).some((k) => /^ai(Person|Vehicle|Animal|Face|Package)/.test(k))) out.add("ai");
 	if (has("gop")) out.add("enc");
-	if (has("privacyMaskEnabled")) out.add("mask");
 	if (has("audioNoiseLevel")) out.add("audioNoise");
 	if (has("autoFocusEnabled")) out.add("autofocus");
 	if (has("netHttpEnable", "netHttpPort", "netHttpsEnable", "netHttpsPort", "netRtspEnable", "netRtspPort", "netRtmpEnable", "netRtmpPort", "netOnvifEnable", "netOnvifPort")) out.add("netPort");
@@ -150294,6 +150524,20 @@ function slicesForPatch(patch) {
 	if (has("timeZoneId")) out.add("systemGeneral");
 	return out;
 }
+/**
+* What the operator's "Refresh from camera" actually managed.
+*
+* Returned rather than logged, because the button is the one place a person
+* asks "is what I am looking at true right now" — and an answer of `void`
+* cannot distinguish a full re-read from a camera that never woke.
+*/
+var RefreshSettingsResultSchema = object({
+	/** False when a battery camera did not come up — everything below is then stale. */
+	awake: boolean(),
+	snapshotRefreshed: boolean(),
+	capsWarmed: number(),
+	capsTotal: number()
+});
 var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	type = DeviceType.Camera;
 	/**
@@ -150763,9 +151007,12 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	* `setVideoInput`); motion is writable via `setMotionAlarm` so its
 	* snapshot also drives the dispatch's known-good baseline.
 	*/
-	async refreshParentSettingsSnapshot(slices) {
-		if (this.isBattery && this.sleeping) {
-			this.ctx.logger.info("refreshParentSettingsSnapshot skipped — battery cam is sleeping", { tags: { deviceId: this.id } });
+	async refreshParentSettingsSnapshot(slices, reason = "background") {
+		if (this.isBattery && this.sleeping && reason !== "post-write") {
+			this.ctx.logger.info("refreshParentSettingsSnapshot skipped — battery cam is sleeping", { tags: {
+				deviceId: this.id,
+				reason
+			} });
 			return;
 		}
 		let api;
@@ -151010,6 +151257,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			channel: this.getChannel(),
 			sleeping: this.isBattery && this.sleeping,
 			hubChild: this.isHubChild(),
+			hasPtz: this.getProbeFlags().hasPtz === true,
 			getApi: () => this.ensureApi(),
 			cache: this.config.get("deviceCache"),
 			batteryState: this.runtimeState.getCapState("battery"),
@@ -151103,6 +151351,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				});
 				await sleep$2(1500);
 			})(), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error("wakeIfSleeping timeout")), timeoutMs))]);
+			if (this.commitSleepState(false, "confirmed-wake")) {
+				this.ctx.logger.info("proactive action: camera is up — committing the mirror", { tags: { deviceId: this.id } });
+				this.onWakeTransition("confirmed-wake").catch(() => {});
+			}
 			return true;
 		} catch (err) {
 			this.ctx.logger.warn("proactive action: wake did not complete in time", {
@@ -151274,8 +151526,26 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		this.registerDeviceAction("auto-configure-email-push", deviceCustomAction(unknown(), _void(), { kind: "mutation" }), async () => {
 			await this.autoConfigureEmailPush();
 		});
-		this.registerDeviceAction("refresh-settings", deviceCustomAction(unknown(), _void(), { kind: "mutation" }), async () => {
-			await Promise.allSettled([this.refreshParentSettingsSnapshot(), this.refreshStreamParamsFromCamera?.() ?? Promise.resolve()]);
+		this.registerDeviceAction("refresh-settings", deviceCustomAction(unknown(), RefreshSettingsResultSchema, { kind: "mutation" }), async () => {
+			const awake = await this.wakeIfSleeping();
+			const [snapshot, warm] = await Promise.allSettled([this.refreshParentSettingsSnapshot(void 0, "operator"), this.warmCapSlicesOnWake({ force: true })]);
+			const warmed = warm.status === "fulfilled" ? warm.value.warmed : 0;
+			const capsTotal = this.capWarmers.size;
+			this.ctx.logger.info("refresh from camera: operator rehydrate", {
+				tags: { deviceId: this.id },
+				meta: {
+					awake,
+					snapshot: snapshot.status,
+					warmed,
+					capsTotal
+				}
+			});
+			return {
+				awake,
+				snapshotRefreshed: snapshot.status === "fulfilled",
+				capsWarmed: warmed,
+				capsTotal
+			};
 		});
 		this.registerDeviceAction("refresh-sessions", deviceCustomAction(unknown(), _void(), { kind: "mutation" }), async () => {
 			await this.refreshSessionsSnapshot();
@@ -151315,7 +151585,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	*  registration so the general "Refresh from camera" button can warm
 	*  the `stream-params` runtime-state slice (the editable Stream
 	*  section's current values read from it). */
-	refreshStreamParamsFromCamera = null;
 	/** Single-flight guard for the motion-zones cap refresh. */
 	motionZonesRefreshInFlight = null;
 	/** Single-flight guard for the privacy-mask cap refresh. */
@@ -151449,6 +151718,16 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						};
 					}
 					if (confirmed && !observedAwake && parent !== null) this.watchHubChildAwake(parent).catch(() => {});
+					if (this.commitSleepState(false, "confirmed-wake")) {
+						this.ctx.logger.info("battery wakeForStream: answering awake — committing the mirror", {
+							tags: { deviceId: this.id },
+							meta: {
+								confirmedMs: Date.now() - startedAt,
+								observedAwake
+							}
+						});
+						this.onWakeTransition("confirmed-wake").catch(() => {});
+					}
 					return {
 						awoke: true,
 						durationMs: Date.now() - startedAt
@@ -151574,7 +151853,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	commitSleepState(next, source) {
 		if (!this.isBattery) return false;
 		if (this.sleeping === next) return false;
-		if (source !== "hub-summary" && !this.acceptSleepingTransition(next)) return false;
+		if (source === "confirmed-wake" && next === false) this.sleepStateChangedAt = Date.now();
+		else if (source !== "hub-summary" && !this.acceptSleepingTransition(next)) return false;
 		if (source === "hub-summary") {
 			const sinceCommitMs = Date.now() - this.sleepStateChangedAt;
 			if (next === true && this.sleepStateChangedAt > 0 && sinceCommitMs < ReolinkCamera.HUB_SUMMARY_SLEEP_GRACE_MS) {
@@ -152710,14 +152990,14 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	* swallowed: the window is short, partial progress accumulates across
 	* wakes because the slices persist.
 	*/
-	async warmCapSlicesOnWake() {
+	async warmCapSlicesOnWake(opts) {
 		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) {
+			if (opts?.force !== true && fetchedAt > 0 && now - fetchedAt < ReolinkCamera.WAKE_WARM_MAX_AGE_MS) {
 				skipped += 1;
 				continue;
 			}
@@ -152742,6 +153022,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				total: this.capWarmers.size
 			}
 		});
+		return {
+			warmed,
+			skipped
+		};
 	}
 	/**
 	* Ask the snapshot wrapper for a frame while the camera is up, so its
@@ -152807,7 +153091,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	registerStreamParamsCap() {
 		const channel = this.getChannel();
 		const CAP_NAME = "stream-params";
-		const STALE_MS = 1e4;
 		/** Round-trip `getEnc`, map into the cap status schema, write slice. */
 		const refreshFromCamera = async () => {
 			if (this.streamParamsRefreshInFlight) return this.streamParamsRefreshInFlight;
@@ -152840,13 +153123,13 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				this.streamParamsRefreshInFlight = null;
 			}
 		};
-		this.refreshStreamParamsFromCamera = refreshFromCamera;
 		const bridge = createRuntimeStateBridge({
 			runtimeState: this.runtimeState,
 			cap: streamParamsCapability,
 			ownDeviceId: this.id,
 			refresh: this.sleepGatedRefresh(CAP_NAME, refreshFromCamera),
-			staleMs: STALE_MS,
+			staleMs: OPERATOR_WRITTEN_STALE_MS,
+			staleRead: "serve-and-revalidate",
 			empty: () => ({ lastFetchedAt: 0 })
 		});
 		const resolveOptions = async () => this.resolveCapOptions({
@@ -152931,7 +153214,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	registerMotionZonesCap() {
 		const channel = this.getChannel();
 		const CAP_NAME = "motion-zones";
-		const STALE_MS = 1e4;
 		/** Round-trip `getMotionAlarm`, map into the cap status schema, write slice. */
 		const refreshFromCamera = async () => {
 			if (this.motionZonesRefreshInFlight) return this.motionZonesRefreshInFlight;
@@ -152981,7 +153263,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				cap: motionZonesCapability,
 				ownDeviceId: this.id,
 				refresh: this.sleepGatedRefresh(CAP_NAME, refreshFromCamera),
-				staleMs: STALE_MS,
+				staleMs: OPERATOR_WRITTEN_STALE_MS,
+				staleRead: "serve-and-revalidate",
 				empty: () => ({
 					enabled: false,
 					sensitivity: 1,
@@ -153312,7 +153595,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	registerDayNightCap() {
 		const channel = this.getChannel();
 		const CAP_NAME = "day-night";
-		const STALE_MS = 1e4;
 		/** Round-trip `getVideoInput` + `getDayNightThreshold`, map into the
 		*  cap status schema, write slice. */
 		const refreshFromCamera = async () => {
@@ -153355,7 +153637,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				cap: dayNightCapability,
 				ownDeviceId: this.id,
 				refresh: this.sleepGatedRefresh(CAP_NAME, refreshFromCamera),
-				staleMs: STALE_MS,
+				staleMs: OPERATOR_WRITTEN_STALE_MS,
+				staleRead: "serve-and-revalidate",
 				empty: () => ({
 					mode: "auto",
 					lastFetchedAt: 0
@@ -153448,7 +153731,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	registerImageSettingsCap() {
 		const channel = this.getChannel();
 		const CAP_NAME = "image-settings";
-		const STALE_MS = 1e4;
 		const SLIDER_MIN = 0;
 		const SLIDER_MAX = 255;
 		const NORMALIZED_RANGE = {
@@ -153492,7 +153774,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				cap: imageSettingsCapability,
 				ownDeviceId: this.id,
 				refresh: this.sleepGatedRefresh(CAP_NAME, refreshFromCamera),
-				staleMs: STALE_MS,
+				staleMs: OPERATOR_WRITTEN_STALE_MS,
+				staleRead: "serve-and-revalidate",
 				empty: () => ({ lastFetchedAt: 0 })
 			}).getStatus,
 			getOptions: async ({ deviceId }) => {
@@ -153809,7 +154092,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		/** Stale-after window for served-from-cache reads. ~10s is short
 		*  enough that the UI's 5s poll always sees a fresh round-trip,
 		*  long enough that two consumers in the same tick fold into one. */
-		const STALE_MS = 1e4;
 		const SUPPORTED_TARGET_TYPES = [
 			{
 				value: "people",
@@ -153875,7 +154157,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			cap: ptzAutotrackCapability,
 			ownDeviceId: this.id,
 			refresh: this.sleepGatedRefresh(CAP_NAME, refreshFromCamera),
-			staleMs: STALE_MS,
+			staleMs: OPERATOR_WRITTEN_STALE_MS,
+			staleRead: "serve-and-revalidate",
 			empty: () => ({
 				enabled: false,
 				lastChangedAt: 0,
@@ -155636,7 +155919,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 					id: "driver-refresh",
 					tab: "general",
 					title: "Camera data",
-					description: "Re-read the camera's current configuration (encoder, ports, time, image, motion). Use this after changing settings from the Reolink app so the form reflects the camera's live state.",
+					description: "Go and ask the camera now. Every other read here is deliberately cheap about a battery camera — it serves what it already knows and refreshes quietly behind you, and never wakes a sleeping camera just because you opened this tab. This button is the exception: it wakes the camera, re-reads everything, and tells you what it got. Use it after changing settings from the Reolink app, or whenever you want to be sure the form is showing the camera and not a memory of it.",
 					columns: 1,
 					fields: [{
 						type: "device-action-button",
@@ -155644,7 +155927,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						label: "Refresh from camera",
 						buttonLabel: "Refresh now",
 						action: "refresh-settings",
-						variant: "default"
+						variant: "default",
+						successMessage: "Camera awake: {awake} · settings re-read: {snapshotRefreshed} · slices refreshed: {capsWarmed}/{capsTotal}"
 					}]
 				},
 				{
@@ -156131,20 +156415,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 					sleeping: this.isBattery && this.sleeping,
 					now: Date.now()
 				}),
-				{
-					id: "privacy-mask",
-					tab: "image",
-					title: "Privacy mask",
-					description: "Master enable for the privacy zones configured on the camera (set up via the Reolink mobile app + camera UI). Pushed via `SetMask` (cmd_id 53). Disabling shows the full frame; enabling re-applies the persisted zones.",
-					columns: 1,
-					fields: [{
-						type: "boolean",
-						key: "privacyMaskEnabled",
-						label: "Privacy mask enabled",
-						default: cache?.maskSnapshot?.enabled ?? false,
-						style: "switch"
-					}]
-				},
 				...cache?.autoFocusSnapshot?.supported === true ? [{
 					id: "auto-focus",
 					tab: "image",
@@ -156499,7 +156769,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			audioVolume: this.config.get("audioVolume") ?? 50,
 			audioTalkAndReplyVolume: this.config.get("audioTalkAndReplyVolume") ?? 50,
 			audioVisitorVolume: this.config.get("audioVisitorVolume") ?? 50,
-			privacyMaskEnabled: this.config.get("privacyMaskEnabled") ?? cache?.maskSnapshot?.enabled ?? false,
 			audioNoiseLevel: this.config.get("audioNoiseLevel") ?? (cache?.audioNoiseSnapshot?.enabled ? cache.audioNoiseSnapshot?.level ?? 1 : 0),
 			autoFocusEnabled: this.config.get("autoFocusEnabled") ?? cache?.autoFocusSnapshot?.enabled ?? true,
 			pirReduceFalseAlarm: this.config.get("pirReduceFalseAlarm") ?? cache?.pirSnapshot?.reduceFalseAlarm ?? false,
@@ -156515,6 +156784,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	}
 	async applySettingsPatch(patch) {
 		const { emailSmtpServer, emailSmtpPort, emailUserName, emailPassword, emailSsl, emailRecipient1, emailRecipient2, emailRecipient3, emailSendNickname, emailScheduleEnabled, osdChannelEnabled, osdChannelName, osdChannelPosition, osdTimeEnabled, osdTimePosition, osdWatermark, ...rest } = patch;
+		if ((osdChannelEnabled !== void 0 || osdChannelName !== void 0 || osdChannelPosition !== void 0 || osdTimeEnabled !== void 0 || osdTimePosition !== void 0 || osdWatermark !== void 0 || emailSmtpServer !== void 0 || emailRecipient1 !== void 0) && !await this.wakeIfSleeping()) this.ctx.logger.warn("settings write: battery cam did not wake — writing anyway", { tags: { deviceId: this.id } });
 		const emailFields = {
 			emailSmtpServer,
 			emailSmtpPort,
@@ -156825,13 +157095,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				this.ctx.logger.warn("reolink setNtp push failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 			}
 		}
-		if ("privacyMaskEnabled" in patch) try {
-			const api = await this.ensureApi();
-			const v = typedPatch.privacyMaskEnabled;
-			if (typeof v === "boolean") await api.setMask(this.getChannel(), { enable: v });
-		} catch (err) {
-			this.ctx.logger.warn("mask push failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
-		}
 		if ("audioNoiseLevel" in patch) try {
 			const api = await this.ensureApi();
 			const v = typedPatch.audioNoiseLevel;
@@ -156889,15 +157152,40 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			}
 		}
 		const changedSlices = slicesForPatch(patch);
-		if (changedSlices.size > 0) await this.refreshParentSettingsSnapshot(changedSlices).catch((err) => {
-			this.ctx.logger.info("reolink targeted settings refresh failed — snapshots left stale", {
-				tags: { deviceId: this.id },
-				meta: {
-					slices: [...changedSlices],
-					error: err instanceof Error ? err.message : String(err)
-				}
+		if (changedSlices.size > 0) {
+			await this.refreshParentSettingsSnapshot(changedSlices, "post-write").catch((err) => {
+				this.ctx.logger.info("reolink targeted settings refresh failed — snapshots left stale", {
+					tags: { deviceId: this.id },
+					meta: {
+						slices: [...changedSlices],
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
 			});
-		});
+			this.assertOsdWriteLanded(patch);
+		}
+	}
+	/**
+	* Compare what the operator asked for with what the camera now reports, and
+	* REFUSE to call a lost write a success.
+	*
+	* Nothing used to do this, so an applied write and a write the camera never
+	* took were indistinguishable — to the code and to the operator, who was
+	* told `{success: true}` for a change the camera discarded (3825,
+	* 2026-09-19). Throwing is the right shape: the admin UI's in-flight
+	* overlay hands the operator their own edit back, marked unsaved, instead
+	* of quietly reverting the field to the old value.
+	*
+	* Silence is the pass. A slice we could not re-read at all is already
+	* reported by the caller as "snapshots left stale" — absence of a reading
+	* is not evidence of a lost write, and must never be treated as one (D393).
+	*/
+	assertOsdWriteLanded(patch) {
+		const asked = patch.osdTimePosition;
+		if (typeof asked !== "string") return;
+		const got = resolveOsdValues(this.config.get("deviceCache")?.osdSnapshot).osdTimePosition;
+		if (typeof got !== "string" || got === asked) return;
+		throw new Error(`the camera did not take the timestamp position: asked "${asked}", it reports "${got}"`);
 	}
 	/**
 	* Optionally inject an already-logged-in Baichuan api — used by