@camstack/addon-provider-onvif 1.2.108 → 1.2.110

package/dist/addon.js

@@ -5363,7 +5363,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-BDR76Ykr.mjs
+//#region ../types/dist/sleep-B1y0Fo1U.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -28886,14 +28886,81 @@ DeviceType.Camera, method(object({ deviceId: number() }), PrivacyMaskOptionsSche
 	kind: "mutation",
 	auth: "admin"
 });
+/**
+* What a preset id DOES on this camera.
+*
+* On several PTZ firmwares the preset namespace is shared: low ids are stored
+* positions, a reserved band triggers camera FUNCTIONS. The dispensa camera
+* (Hikvision) returns its own reserved band in the preset list, named by the
+* firmware:
+*
+*   34 Back to origin · 39 Day mode · 40 Night mode · 46 Day/Night Auto Mode
+*   92 Set manual limits · 93 Save manual limits · 94 Remote reboot
+*   95 Call OSD menu
+*
+* We used to hand all of these to the UI as ordinary presets. Saving over one
+* is what produced `PUT /ISAPI/PTZCtrl/channels/1/presets/34 -> HTTP 500`: the
+* camera refusing to let "Back to origin" be overwritten, surfaced to the
+* operator as a transport failure.
+*
+* A function preset stays fully usable as a DESTINATION -- `goToPreset('34')`
+* is the single most useful thing that camera can do. Only `savePreset` and
+* `deletePreset` are gated.
+*/
+var PtzPresetFunctionSchema = _enum([
+	"home",
+	"day-mode",
+	"night-mode",
+	"day-night-auto",
+	"set-limits",
+	"save-limits",
+	"reboot",
+	"osd-menu"
+]);
 var PtzPresetSchema = object({
 	id: string(),
-	name: string()
+	name: string(),
+	/**
+	* The firmware function this id performs, when the provider KNOWS the id is
+	* reserved. `null` = an ordinary stored position, OR a reserved id this
+	* provider does not recognise -- the two are told apart by `writable`.
+	*/
+	fn: PtzPresetFunctionSchema.nullable(),
+	/**
+	* Whether `savePreset` / `deletePreset` may target this id. A provider sets
+	* it false only for a band it KNOWS is reserved; where the firmware is not
+	* documented it stays true and a refusal comes from the camera, named.
+	*/
+	writable: boolean()
 });
+/**
+* Where the head is pointing -- per axis, and `null` when the driver cannot
+* read it.
+*
+* It used to be three REQUIRED numbers, which left a provider that cannot read
+* position no way to say so. All four said `0`:
+*
+*   reolink   `return { pan: 0, tilt: 0, zoom: 0 }`  "until a position-query
+*                                                     path lands upstream"
+*   hikvision stub, "firmware-dependent and frequently absent"
+*   amcrest   stub, "no generic absolute-position read for this model family"
+*   onvif     throws
+*
+* So every consumer asking where a camera points was told "perfectly centred"
+* by four cameras that had never looked. That is D393 -- a measurement that
+* FAILED is `null`, never `0`, and the type says so all the way to the
+* decision -- the same shape as the unreadable `statfs` folded into "0 bytes of
+* headroom", which evacuated a healthy disk.
+*
+* D393 also says to check for a narrower structural TWIN of the result type.
+* There is one: `PtzStatusSchema` extends this, so the lie had already
+* propagated into `getStatus`, which is the surface `getPosition`'s own comment
+* tells callers to migrate to.
+*/
 var PtzPositionSchema = object({
-	pan: number(),
-	tilt: number(),
-	zoom: number()
+	pan: number().nullable(),
+	tilt: number().nullable(),
+	zoom: number().nullable()
 });
 var PtzMoveCommandSchema = object({
 	pan: number().optional(),
@@ -28915,7 +28982,72 @@ var PtzOptionsSchema = object({
 	maxPresets: number().optional(),
 	/** Whether the camera exposes a controllable autofocus toggle
 	*  (boolean `hasX` per the getOptions availability convention). */
-	hasAutofocus: boolean()
+	hasAutofocus: boolean(),
+	/**
+	* How many distinct speeds this camera's NATIVE scale offers.
+	*
+	* The cap's `speed` is normalized 0..1 and each provider maps it down --
+	* Baichuan 1..63, Dahua 1..8, ISAPI's percentage -100..100. The normalized
+	* value hides how coarse that really is: asking an amcrest for `0.37` is
+	* meaningless, because it has eight steps and three of them round to the
+	* same one. A loop that tunes its own gain has to know the granularity of
+	* the knob it is turning.
+	*
+	* `null` = the driver does not know, or the scale is continuous (ONVIF takes
+	* a float). Never a made-up number.
+	*/
+	speedSteps: number().int().positive().nullable(),
+	/**
+	* How long ONE `move` pulse runs on this driver, ms.
+	*
+	* `move` is a self-terminating burst everywhere, but every provider hardcoded
+	* its own duration in private -- 200 reolink, 350 amcrest, 500 hikvision,
+	* 1000 onvif -- so no caller could read it. It is the DENOMINATOR of "how far
+	* did the head travel per pulse": without it a measured displacement has no
+	* gain to be divided into.
+	*
+	* `null` = the driver cannot say.
+	*/
+	moveImpulseMs: number().int().positive().nullable()
+});
+/**
+* Which preset `goHome` goes to, and WHO decided.
+*
+* `goHome` used to be three vendor "conventions" written in three comments --
+* Reolink preset 0, Hikvision preset '1', Dahua preset 1 -- and on this fleet
+* not one of the three cameras honours its own:
+*
+*   592  Videocamera camera Daniel (reolink)   preset 0 holds "stanza"
+*   1438 Videocamera dispensa (hikvision)      preset 1 holds "Credenza"
+*   3836 Videocamera studio (amcrest)          preset 1 holds "Preset1"
+*
+* So `goHome` meant "go wherever the operator happened to save in slot 0 or 1",
+* and two of the three swallowed the failure in a bare `catch`. For autotrack
+* this is the HOTTEST path -- it runs every time a subject is released -- so it
+* needs an answer that is true per camera and audible when it is missing.
+*
+* `source` is what makes it honest:
+*   - `operator` -- picked in the UI, stored by the provider.
+*   - `firmware` -- the camera itself named a preset `fn: 'home'` (Hikvision's
+*     "Back to origin"), adopted as the default with nothing to configure.
+*   - `native`   -- the driver homes WITHOUT a preset at all. ONVIF does:
+*     `goHome` is `ptzAbsoluteMove({x:0, y:0, zoom:0})`. `presetId` is null and
+*     that is not a failure -- there is nothing to pick, and the UI must offer
+*     no picker.
+*   - `none`     -- nothing is configured and the camera names nothing.
+*     `goHome` REFUSES rather than moving the head somewhere arbitrary.
+*
+* `source === 'none'` is the refusal condition, NOT `presetId === null`: the
+* native case has no preset and homes perfectly well.
+*/
+var PtzHomePresetSchema = object({
+	presetId: string().nullable(),
+	source: _enum([
+		"operator",
+		"firmware",
+		"native",
+		"none"
+	])
 });
 var ptzCapability = {
 	name: "ptz",
@@ -28956,7 +29088,25 @@ var ptzCapability = {
 			auth: "admin"
 		}),
 		getOptions: method(object({ deviceId: number() }), PtzOptionsSchema),
+		/**
+		* Move to the camera's configured home preset. THROWS when
+		* `getHomePreset()` resolves to `none` -- a head that did not move must
+		* never look like a head that went home.
+		*/
 		goHome: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
+		/** Which preset `goHome` targets, and who decided it. */
+		getHomePreset: method(object({ deviceId: number() }), PtzHomePresetSchema),
+		/**
+		* Pin the home preset for this camera. `null` clears the operator's choice
+		* and falls back to whatever the firmware names, or to `none`.
+		*/
+		setHomePreset: method(object({
+			deviceId: number(),
+			presetId: string().nullable()
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/**
 		* Pull the current PTZ position. Redundant with the auto-injected
 		* `getStatus` method (see `status` below); kept for callers that
@@ -36813,6 +36963,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"ptz.getHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"ptz.getOptions": {
 		capName: "ptz",
 		capScope: "device",
@@ -36861,6 +37017,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"ptz.setHomePreset": {
+		capName: "ptz",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"ptz.stop": {
 		capName: "ptz",
 		capScope: "device",
@@ -40034,6 +40196,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.getHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.getOptions": [{
 		name: "deviceId",
 		form: "single",
@@ -40074,6 +40241,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"ptz.setHomePreset": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"ptz.stop": [{
 		name: "deviceId",
 		form: "single",
@@ -41109,295 +41281,6 @@ DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
 //#endregion
-//#region src/onvif-camera.ts
-var onvifCameraSchema = object({
-	name: string().describe("Camera display name"),
-	host: string().describe("Camera IP address or hostname"),
-	port: number().default(80).describe("ONVIF port (default: 80)"),
-	username: string().default("").describe("ONVIF username"),
-	password: string().default("").describe("ONVIF password"),
-	rtspUrl: string().describe("Primary RTSP stream URL"),
-	subStreamUrl: string().default("").describe("Sub-stream RTSP URL (optional)"),
-	snapshotUrl: string().default("").describe("Native snapshot URL (optional)"),
-	profileToken: string().default("").describe("Main ONVIF media profile token"),
-	subProfileToken: string().default("").describe("Sub-stream ONVIF media profile token (optional)"),
-	videoWidth: number().optional().describe("Main stream video width"),
-	videoHeight: number().optional().describe("Main stream video height"),
-	subVideoWidth: number().optional().describe("Sub-stream video width"),
-	subVideoHeight: number().optional().describe("Sub-stream video height"),
-	hasPtz: boolean().default(false).describe("Whether camera supports PTZ"),
-	manufacturer: string().default("").describe("Camera manufacturer"),
-	model: string().default("").describe("Camera model"),
-	firmware: string().default("").describe("Camera firmware version")
-});
-/**
-* ONVIF camera device.
-*
-* Implements `IDevice` with the `NativeSnapshot` feature when a snapshot
-* URL is available.  PTZ methods are exposed as plain instance methods so the
-* addon / capability layer can delegate to them; they are NOT registered as a
-* `DeviceFeature` because the existing capability system handles PTZ via
-* the `PanTiltZoom` feature.
-*/
-var OnvifCamera = class {
-	id;
-	stableId;
-	type = DeviceType.Camera;
-	name;
-	/** Operator-organisational location label. Settable via the
-	*  device-manager cap; legacy ONVIF cameras default to null. */
-	location = null;
-	/** Soft-disabled flag — drivers consult this; the kernel doesn't
-	*  enforce. Defaults to false (active). */
-	disabled = false;
-	parentDeviceId;
-	features;
-	config;
-	ctx;
-	online = true;
-	markOnline(online) {
-		this.online = online;
-	}
-	/**
-	* Invoke a device custom action. ONVIF cameras register no device
-	* custom actions, so every action is unknown — mirrors `BaseDevice`'s
-	* default of throwing for an unregistered action.
-	*/
-	async runDeviceAction(action, _input) {
-		throw new Error(`unknown device action "${action}" on device ${this.id}`);
-	}
-	/**
-	* Live ONVIF client — injected after connection is established.
-	* `null` when the camera is being restored from DB without a live connection.
-	*/
-	client;
-	/** Control-plane reachability poll — drives `online` from ONVIF
-	*  `getDeviceInformation` liveness, decoupled from stream-broker video
-	*  health. Started on `attachClient`, stopped on `removeDevice`. */
-	reachabilityPoll = null;
-	constructor(ctx, initialData, client = null) {
-		this.ctx = ctx;
-		this.id = ctx.id;
-		this.stableId = ctx.stableId;
-		this.parentDeviceId = ctx.parentDeviceId;
-		this.client = client;
-		this.config = DeviceConfig.fromSchema(onvifCameraSchema, ctx.persistConfig, initialData);
-		this.name = this.config.get("name") || String(initialData["name"] ?? "ONVIF Camera");
-		this.features = this.config.get("snapshotUrl") ? [DeviceFeature.NativeSnapshot] : [];
-		this.registerNativeCapabilities();
-	}
-	/**
-	* Publish per-device native capability providers via
-	* `DeviceContext.registerNativeCap`. Called once from the constructor
-	* after `config` and `features` are settled. The kernel cleans these
-	* registrations up automatically on `device-manager.remove(deviceId)`
-	* via `CapabilityRegistry.unregisterAllNativeForDevice`.
-	*
-	* Note: legacy `INativeSnapshot` / direct PTZ method exposure on the
-	* class is intentionally retained — it will be removed in Task 8.1
-	* after the legacy consumers are swept.
-	*/
-	registerNativeCapabilities() {
-		if (this.config.get("snapshotUrl")) this.ctx.registerNativeCap(snapshotCapability, {
-			getSnapshot: async ({ deviceId }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				const buf = await this.getSnapshot();
-				if (buf.length === 0) return null;
-				return {
-					base64: buf.toString("base64"),
-					contentType: "image/jpeg"
-				};
-			},
-			invalidateCache: async () => {}
-		});
-		if (this.hasPtz()) this.ctx.registerNativeCap(ptzCapability, {
-			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				await this.ptzMove({
-					pan,
-					tilt,
-					zoom,
-					speed
-				});
-			},
-			continuousMove: async () => {
-				throw new Error("OnvifCamera: continuousMove not implemented");
-			},
-			stop: async ({ deviceId }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				await this.ptzStop();
-			},
-			getPresets: async ({ deviceId }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				return this.getPtzPresets();
-			},
-			goToPreset: async ({ deviceId, presetId }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				await this.goToPreset(presetId);
-			},
-			savePreset: async () => {
-				throw new Error("OnvifCamera: savePreset not implemented");
-			},
-			deletePreset: async () => {
-				throw new Error("OnvifCamera: deletePreset not implemented");
-			},
-			goHome: async ({ deviceId }) => {
-				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				await this.goHome();
-			},
-			getPosition: async () => {
-				throw new Error("OnvifCamera: getPosition not implemented");
-			},
-			getOptions: async () => {
-				return {
-					hasPan: true,
-					hasTilt: true,
-					hasZoom: true,
-					supportsPresets: true,
-					hasAutofocus: false
-				};
-			},
-			getStatus: async () => ({
-				pan: 0,
-				tilt: 0,
-				zoom: 0,
-				autofocus: false
-			}),
-			setAutofocus: async () => {}
-		});
-	}
-	async getSnapshot() {
-		const url = this.config.get("snapshotUrl");
-		if (!url) return Buffer.alloc(0);
-		const res = await fetch(url);
-		if (!res.ok) throw new Error(`ONVIF snapshot fetch failed: ${res.status} ${res.statusText}`);
-		return Buffer.from(await res.arrayBuffer());
-	}
-	hasPtz() {
-		return this.config.get("hasPtz");
-	}
-	async ptzMove(cmd) {
-		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
-		await this.client.ptzMove({
-			x: cmd.pan,
-			y: cmd.tilt,
-			zoom: cmd.zoom,
-			speed: cmd.speed
-		});
-	}
-	async ptzStop() {
-		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
-		await this.client.ptzStop();
-	}
-	async getPtzPresets() {
-		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
-		return (await this.client.getPtzPresets()).map((p) => ({
-			id: p.token,
-			name: p.name
-		}));
-	}
-	async goToPreset(presetId) {
-		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
-		await this.client.gotoPreset(presetId);
-	}
-	async goHome() {
-		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
-		await this.client.ptzAbsoluteMove({
-			x: 0,
-			y: 0,
-			zoom: 0
-		});
-	}
-	getRtspUrl() {
-		return this.config.get("rtspUrl");
-	}
-	getSubStreamUrl() {
-		return this.config.get("subStreamUrl");
-	}
-	async getStreamSources() {
-		const sources = [];
-		const rtspUrl = this.config.get("rtspUrl");
-		if (rtspUrl) {
-			const videoWidth = this.config.get("videoWidth");
-			const videoHeight = this.config.get("videoHeight");
-			const mainSource = {
-				id: "main",
-				label: "Main Stream",
-				protocol: "rtsp",
-				url: rtspUrl,
-				profileHint: "high",
-				...videoWidth !== void 0 && videoHeight !== void 0 ? { resolution: {
-					width: videoWidth,
-					height: videoHeight
-				} } : {}
-			};
-			sources.push(mainSource);
-		}
-		const subStreamUrl = this.config.get("subStreamUrl");
-		if (subStreamUrl) {
-			const subVideoWidth = this.config.get("subVideoWidth");
-			const subVideoHeight = this.config.get("subVideoHeight");
-			const subSource = {
-				id: "sub",
-				label: "Sub Stream",
-				protocol: "rtsp",
-				url: subStreamUrl,
-				profileHint: "low",
-				...subVideoWidth !== void 0 && subVideoHeight !== void 0 ? { resolution: {
-					width: subVideoWidth,
-					height: subVideoHeight
-				} } : {}
-			};
-			sources.push(subSource);
-		}
-		return sources;
-	}
-	/**
-	* Attach a live ONVIF client after the device has been created from DB.
-	* Called by the addon when it successfully connects to the camera on boot.
-	*/
-	attachClient(client) {
-		this.client = client;
-		this.online = true;
-		this.startReachabilityPolling();
-	}
-	/** Start the control-plane reachability poll: an ONVIF
-	*  `getDeviceInformation` round-trip every 30s drives `online`, with
-	*  hysteresis. Replaces the old stream-health→online coupling so a
-	*  reachable on-demand camera still reports ONLINE. Re-armed on each
-	*  `attachClient` (reconnect) — the prior poll is stopped first. */
-	startReachabilityPolling() {
-		this.reachabilityPoll?.stop();
-		this.reachabilityPoll = startReachabilityPoll({
-			probe: async () => {
-				const client = this.client;
-				if (!client) return false;
-				await client.getDeviceInfo();
-				return true;
-			},
-			setOnline: (online) => {
-				this.markOnline(online);
-			},
-			isEnabled: () => !this.disabled && this.client !== null,
-			logger: this.ctx.logger
-		});
-	}
-	async removeDevice() {
-		this.reachabilityPoll?.stop();
-		this.reachabilityPoll = null;
-		this.client?.disconnect();
-		this.client = null;
-		this.online = false;
-		this.ctx.logger.info("Removed ONVIF camera", { meta: { stableId: this.stableId } });
-	}
-	getSettingsUISchema() {
-		return { sections: [] };
-	}
-	async applySettingsPatch(patch) {
-		await this.config.setAll(patch);
-	}
-};
-//#endregion
 //#region ../../node_modules/xml2js/lib/defaults.js
 var require_defaults = /* @__PURE__ */ __commonJSMin(((exports) => {
 	(function() {
@@ -50193,6 +50076,12 @@ var import_onvif = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		Discovery: require_discovery().Discovery
 	};
 })))();
+/**
+* How long one ONVIF `ContinuousMove` runs before the camera stops itself, ms.
+* The DENOMINATOR of "how far did the head travel per pulse", so it is named
+* and exported rather than left inline where no caller could read it.
+*/
+var ONVIF_PTZ_TIMEOUT_MS = 1e3;
 var OnvifClient = class {
 	host;
 	port;
@@ -50288,7 +50177,7 @@ var OnvifClient = class {
 				x: options.x ?? 0,
 				y: options.y ?? 0,
 				zoom: options.zoom ?? 0,
-				timeout: 1e3
+				timeout: ONVIF_PTZ_TIMEOUT_MS
 			}, (err) => {
 				if (err) reject(err);
 				else resolve();
@@ -50347,6 +50236,311 @@ var OnvifClient = class {
 	}
 };
 //#endregion
+//#region src/onvif-camera.ts
+var onvifCameraSchema = object({
+	name: string().describe("Camera display name"),
+	host: string().describe("Camera IP address or hostname"),
+	port: number().default(80).describe("ONVIF port (default: 80)"),
+	username: string().default("").describe("ONVIF username"),
+	password: string().default("").describe("ONVIF password"),
+	rtspUrl: string().describe("Primary RTSP stream URL"),
+	subStreamUrl: string().default("").describe("Sub-stream RTSP URL (optional)"),
+	snapshotUrl: string().default("").describe("Native snapshot URL (optional)"),
+	profileToken: string().default("").describe("Main ONVIF media profile token"),
+	subProfileToken: string().default("").describe("Sub-stream ONVIF media profile token (optional)"),
+	videoWidth: number().optional().describe("Main stream video width"),
+	videoHeight: number().optional().describe("Main stream video height"),
+	subVideoWidth: number().optional().describe("Sub-stream video width"),
+	subVideoHeight: number().optional().describe("Sub-stream video height"),
+	hasPtz: boolean().default(false).describe("Whether camera supports PTZ"),
+	manufacturer: string().default("").describe("Camera manufacturer"),
+	model: string().default("").describe("Camera model"),
+	firmware: string().default("").describe("Camera firmware version")
+});
+/**
+* ONVIF camera device.
+*
+* Implements `IDevice` with the `NativeSnapshot` feature when a snapshot
+* URL is available.  PTZ methods are exposed as plain instance methods so the
+* addon / capability layer can delegate to them; they are NOT registered as a
+* `DeviceFeature` because the existing capability system handles PTZ via
+* the `PanTiltZoom` feature.
+*/
+var OnvifCamera = class {
+	id;
+	stableId;
+	type = DeviceType.Camera;
+	name;
+	/** Operator-organisational location label. Settable via the
+	*  device-manager cap; legacy ONVIF cameras default to null. */
+	location = null;
+	/** Soft-disabled flag — drivers consult this; the kernel doesn't
+	*  enforce. Defaults to false (active). */
+	disabled = false;
+	parentDeviceId;
+	features;
+	config;
+	ctx;
+	online = true;
+	markOnline(online) {
+		this.online = online;
+	}
+	/**
+	* Invoke a device custom action. ONVIF cameras register no device
+	* custom actions, so every action is unknown — mirrors `BaseDevice`'s
+	* default of throwing for an unregistered action.
+	*/
+	async runDeviceAction(action, _input) {
+		throw new Error(`unknown device action "${action}" on device ${this.id}`);
+	}
+	/**
+	* Live ONVIF client — injected after connection is established.
+	* `null` when the camera is being restored from DB without a live connection.
+	*/
+	client;
+	/** Control-plane reachability poll — drives `online` from ONVIF
+	*  `getDeviceInformation` liveness, decoupled from stream-broker video
+	*  health. Started on `attachClient`, stopped on `removeDevice`. */
+	reachabilityPoll = null;
+	constructor(ctx, initialData, client = null) {
+		this.ctx = ctx;
+		this.id = ctx.id;
+		this.stableId = ctx.stableId;
+		this.parentDeviceId = ctx.parentDeviceId;
+		this.client = client;
+		this.config = DeviceConfig.fromSchema(onvifCameraSchema, ctx.persistConfig, initialData);
+		this.name = this.config.get("name") || String(initialData["name"] ?? "ONVIF Camera");
+		this.features = this.config.get("snapshotUrl") ? [DeviceFeature.NativeSnapshot] : [];
+		this.registerNativeCapabilities();
+	}
+	/**
+	* Publish per-device native capability providers via
+	* `DeviceContext.registerNativeCap`. Called once from the constructor
+	* after `config` and `features` are settled. The kernel cleans these
+	* registrations up automatically on `device-manager.remove(deviceId)`
+	* via `CapabilityRegistry.unregisterAllNativeForDevice`.
+	*
+	* Note: legacy `INativeSnapshot` / direct PTZ method exposure on the
+	* class is intentionally retained — it will be removed in Task 8.1
+	* after the legacy consumers are swept.
+	*/
+	registerNativeCapabilities() {
+		if (this.config.get("snapshotUrl")) this.ctx.registerNativeCap(snapshotCapability, {
+			getSnapshot: async ({ deviceId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				const buf = await this.getSnapshot();
+				if (buf.length === 0) return null;
+				return {
+					base64: buf.toString("base64"),
+					contentType: "image/jpeg"
+				};
+			},
+			invalidateCache: async () => {}
+		});
+		if (this.hasPtz()) this.ctx.registerNativeCap(ptzCapability, {
+			move: async ({ deviceId, pan, tilt, zoom, speed }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				await this.ptzMove({
+					pan,
+					tilt,
+					zoom,
+					speed
+				});
+			},
+			continuousMove: async () => {
+				throw new Error("OnvifCamera: continuousMove not implemented");
+			},
+			stop: async ({ deviceId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				await this.ptzStop();
+			},
+			getPresets: async ({ deviceId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				return (await this.getPtzPresets()).map((preset) => ({
+					...preset,
+					fn: null,
+					writable: false
+				}));
+			},
+			goToPreset: async ({ deviceId, presetId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				await this.goToPreset(presetId);
+			},
+			savePreset: async () => {
+				throw new Error("OnvifCamera: savePreset not implemented");
+			},
+			deletePreset: async () => {
+				throw new Error("OnvifCamera: deletePreset not implemented");
+			},
+			goHome: async ({ deviceId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				await this.goHome();
+			},
+			getHomePreset: async ({ deviceId }) => {
+				if (deviceId !== this.id) throw new Error(`OnvifCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
+				return {
+					presetId: null,
+					source: "native"
+				};
+			},
+			setHomePreset: async () => {
+				throw new Error("OnvifCamera: home is the PTZ origin on ONVIF and cannot be pointed at a preset");
+			},
+			getPosition: async () => {
+				throw new Error("OnvifCamera: getPosition not implemented");
+			},
+			getOptions: async () => {
+				return {
+					hasPan: true,
+					hasTilt: true,
+					hasZoom: true,
+					supportsPresets: true,
+					hasAutofocus: false,
+					speedSteps: null,
+					moveImpulseMs: ONVIF_PTZ_TIMEOUT_MS
+				};
+			},
+			getStatus: async () => ({
+				pan: null,
+				tilt: null,
+				zoom: null,
+				autofocus: false
+			}),
+			setAutofocus: async () => {}
+		});
+	}
+	async getSnapshot() {
+		const url = this.config.get("snapshotUrl");
+		if (!url) return Buffer.alloc(0);
+		const res = await fetch(url);
+		if (!res.ok) throw new Error(`ONVIF snapshot fetch failed: ${res.status} ${res.statusText}`);
+		return Buffer.from(await res.arrayBuffer());
+	}
+	hasPtz() {
+		return this.config.get("hasPtz");
+	}
+	async ptzMove(cmd) {
+		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
+		await this.client.ptzMove({
+			x: cmd.pan,
+			y: cmd.tilt,
+			zoom: cmd.zoom,
+			speed: cmd.speed
+		});
+	}
+	async ptzStop() {
+		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
+		await this.client.ptzStop();
+	}
+	async getPtzPresets() {
+		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
+		return (await this.client.getPtzPresets()).map((p) => ({
+			id: p.token,
+			name: p.name
+		}));
+	}
+	async goToPreset(presetId) {
+		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
+		await this.client.gotoPreset(presetId);
+	}
+	async goHome() {
+		if (!this.client) throw new Error(`OnvifCamera ${this.stableId}: no live client for PTZ`);
+		await this.client.ptzAbsoluteMove({
+			x: 0,
+			y: 0,
+			zoom: 0
+		});
+	}
+	getRtspUrl() {
+		return this.config.get("rtspUrl");
+	}
+	getSubStreamUrl() {
+		return this.config.get("subStreamUrl");
+	}
+	async getStreamSources() {
+		const sources = [];
+		const rtspUrl = this.config.get("rtspUrl");
+		if (rtspUrl) {
+			const videoWidth = this.config.get("videoWidth");
+			const videoHeight = this.config.get("videoHeight");
+			const mainSource = {
+				id: "main",
+				label: "Main Stream",
+				protocol: "rtsp",
+				url: rtspUrl,
+				profileHint: "high",
+				...videoWidth !== void 0 && videoHeight !== void 0 ? { resolution: {
+					width: videoWidth,
+					height: videoHeight
+				} } : {}
+			};
+			sources.push(mainSource);
+		}
+		const subStreamUrl = this.config.get("subStreamUrl");
+		if (subStreamUrl) {
+			const subVideoWidth = this.config.get("subVideoWidth");
+			const subVideoHeight = this.config.get("subVideoHeight");
+			const subSource = {
+				id: "sub",
+				label: "Sub Stream",
+				protocol: "rtsp",
+				url: subStreamUrl,
+				profileHint: "low",
+				...subVideoWidth !== void 0 && subVideoHeight !== void 0 ? { resolution: {
+					width: subVideoWidth,
+					height: subVideoHeight
+				} } : {}
+			};
+			sources.push(subSource);
+		}
+		return sources;
+	}
+	/**
+	* Attach a live ONVIF client after the device has been created from DB.
+	* Called by the addon when it successfully connects to the camera on boot.
+	*/
+	attachClient(client) {
+		this.client = client;
+		this.online = true;
+		this.startReachabilityPolling();
+	}
+	/** Start the control-plane reachability poll: an ONVIF
+	*  `getDeviceInformation` round-trip every 30s drives `online`, with
+	*  hysteresis. Replaces the old stream-health→online coupling so a
+	*  reachable on-demand camera still reports ONLINE. Re-armed on each
+	*  `attachClient` (reconnect) — the prior poll is stopped first. */
+	startReachabilityPolling() {
+		this.reachabilityPoll?.stop();
+		this.reachabilityPoll = startReachabilityPoll({
+			probe: async () => {
+				const client = this.client;
+				if (!client) return false;
+				await client.getDeviceInfo();
+				return true;
+			},
+			setOnline: (online) => {
+				this.markOnline(online);
+			},
+			isEnabled: () => !this.disabled && this.client !== null,
+			logger: this.ctx.logger
+		});
+	}
+	async removeDevice() {
+		this.reachabilityPoll?.stop();
+		this.reachabilityPoll = null;
+		this.client?.disconnect();
+		this.client = null;
+		this.online = false;
+		this.ctx.logger.info("Removed ONVIF camera", { meta: { stableId: this.stableId } });
+	}
+	getSettingsUISchema() {
+		return { sections: [] };
+	}
+	async applySettingsPatch(patch) {
+		await this.config.setAll(patch);
+	}
+};
+//#endregion
 //#region src/onvif-discovery.ts
 /**
 * Discovers ONVIF cameras on the local network via WS-Discovery.