@camstack/addon-provider-hikvision 1.1.15 → 1.1.17

package/dist/addon.mjs

@@ -4636,7 +4636,7 @@ function _instanceof(cls, params = {}) {
 	return inst;
 }
 //#endregion
-//#region ../types/dist/sleep-BiDFW0E7.mjs
+//#region ../types/dist/sleep-CZDdRBua.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -7410,7 +7410,16 @@ var DecoderStatsSchema = object({
 	inputFps: number(),
 	outputFps: number(),
 	avgDecodeTimeMs: number(),
-	droppedFrames: number()
+	droppedFrames: number(),
+	/**
+	* Pull-mode adaptive-fps telemetry (optional — only pull sessions run the
+	* lag-driven controller; push sessions omit these). `lagMs` is the EWMA of
+	* the decoder's real-time drift (rising = falling behind live); `adaptiveFps`
+	* is the current lag-throttled emit rate (≤ `effectiveFps` ceiling).
+	*/
+	lagMs: number().optional(),
+	effectiveFps: number().optional(),
+	adaptiveFps: number().optional()
 });
 var DecoderSessionConfigSchema = object({
 	codec: string(),
@@ -7451,7 +7460,15 @@ var DecoderSessionConfigSchema = object({
 	*   other — `pullFrames` returns nothing for an `'shm'` session and
 	*   `pullHandles` returns nothing for a `'callback'` session.
 	*/
-	frameSink: _enum(["callback", "shm"]).default("callback")
+	frameSink: _enum(["callback", "shm"]).default("callback"),
+	/**
+	* Per-camera decoder DEBUG facility. When `true`, a pull-mode session emits
+	* a throttled (~1Hz) structured `decoder debug` line (effective/adaptive fps,
+	* real-time lag, dropped-frame delta, avg decode time, hwaccel). Mirrors the
+	* stream-broker's `streamingDebug` gate — off by default so production logs
+	* stay quiet and the emit path pays zero per-frame cost when disabled.
+	*/
+	debug: boolean().optional()
 });
 var EncodeProfileSchema = object({
 	video: object({
@@ -10515,6 +10532,100 @@ var coverCapability = {
 	runtimeState: CoverStatusSchema
 };
 /**
+* Vendor-neutral day/night (IR-cut) control — the per-camera config cap
+* shared by reolink / hikvision / amcrest. Models the common firmware
+* surface: the IR-cut switching MODE plus the two knobs that gate it
+* (photocell `sensitivity` + `switchDelaySec`). Each vendor maps these
+* onto its own ISAPI / Baichuan / Dahua-CGI fields; the cap standardises
+* the shape so ONE derived-form renders every camera.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** IR-cut switching mode. `schedule` = time-of-day table configured on the camera. */
+var DayNightModeSchema = _enum([
+	"auto",
+	"day",
+	"night",
+	"schedule"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Normalized values are 0–100. */
+var NormalizedRangeSchema$1 = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+/**
+* Current day/night state. Optional fields are absent when the camera
+* does not expose that knob (a photocell-less model reports no
+* `sensitivity`). `lastFetchedAt` feeds the runtime-state bridge.
+*/
+var DayNightStatusSchema = object({
+	mode: DayNightModeSchema,
+	/** IR-cut trigger sensitivity, NORMALIZED 0–100 (higher = switches to night sooner). */
+	sensitivity: number().optional(),
+	/** Delay before the IR-cut filter flips, in seconds. */
+	switchDelaySec: number().optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (normalized 0–100); the mode choice-set as an array. A provider returns
+* honest, camera-probed values — never hardcoded.
+*/
+var DayNightOptionsSchema = object({
+	/** Modes this camera accepts. Empty → the camera has no configurable day/night mode. */
+	modes: array(DayNightModeSchema),
+	supportsSensitivity: boolean(),
+	/** Present when `supportsSensitivity` — the normalized 0–100 range. */
+	sensitivity: NormalizedRangeSchema$1.optional(),
+	supportsSwitchDelay: boolean(),
+	/** Present when `supportsSwitchDelay` — the allowed delay range in seconds. */
+	switchDelaySec: NormalizedRangeSchema$1.optional()
+});
+/**
+* Partial change to the day/night config — every field optional. A
+* provider ignores fields it does not support.
+*/
+var DayNightSettingsPatchSchema = object({
+	mode: DayNightModeSchema.optional(),
+	sensitivity: number().optional(),
+	switchDelaySec: number().optional()
+});
+var dayNightCapability = {
+	name: "day-night",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [DeviceType.Camera],
+	deviceConfig: { ui: {
+		kind: "derived-form",
+		builderId: "day-night",
+		tab: "image"
+	} },
+	methods: {
+		getOptions: method(object({ deviceId: number() }), DayNightOptionsSchema),
+		setSettings: method(object({
+			deviceId: number(),
+			settings: DayNightSettingsPatchSchema
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		})
+	},
+	status: {
+		schema: DayNightStatusSchema,
+		kind: "poll"
+	},
+	runtimeState: DayNightStatusSchema
+};
+/**
 * Identity envelope for a device's upstream-system metadata.
 *
 * Two jobs:
@@ -11173,6 +11284,155 @@ var imageCapability = {
 	runtimeState: ImageStatusSchema
 };
 /**
+* Vendor-neutral image / picture-adjustment cap — the per-camera config
+* cap shared by reolink / hikvision / amcrest. Models the common ISP
+* surface: the four picture sliders (brightness / contrast / saturation /
+* sharpness), orientation (mirror / flip / rotate), white-balance,
+* exposure and backlight-compensation modes.
+*
+* NORMALIZATION: every slider is a normalized int 0–100. Vendors expose
+* these natively as 0–100 or 0–255 (or other ranges); each provider maps
+* its native range to/from this normalized 0–100 space so the cap surface
+* (and the derived form) is identical across cameras. `warmth` (manual
+* white-balance) is likewise normalized 0–100.
+*
+* Follows the D14 `deviceConfig` archetype (see `stream-params.cap.ts`):
+* `getOptions` advertises per-camera availability, `getStatus` (auto-
+* injected from `status`) reports the live values, and a single
+* `setSettings` mutation applies a partial change. No hand-written
+* settings-contribution methods — the framework derives the UI + save
+* routing from this surface.
+*/
+/** Sensor/image rotation, degrees clockwise. */
+var ImageRotateSchema = _enum([
+	"0",
+	"90",
+	"180",
+	"270"
+]);
+/** White-balance mode. `manual` unlocks the normalized `warmth` knob. */
+var WhiteBalanceModeSchema = _enum(["auto", "manual"]);
+/** Exposure mode. */
+var ExposureModeSchema = _enum(["auto", "manual"]);
+/**
+* Backlight-compensation mode:
+*   - `off` — disabled
+*   - `blc` — backlight compensation
+*   - `wdr` — wide dynamic range
+*   - `hlc` — highlight compensation
+*/
+var BacklightModeSchema = _enum([
+	"off",
+	"blc",
+	"wdr",
+	"hlc"
+]);
+/** Normalized numeric range descriptor — `{ min, max, step }` per the
+*  getOptions availability convention. Slider values are normalized 0–100. */
+var NormalizedRangeSchema = object({
+	min: number(),
+	max: number(),
+	step: number()
+});
+/**
+* Current image-adjustment state. Every field optional — absent when the
+* camera does not expose that control. Slider values are NORMALIZED 0–100.
+* `lastFetchedAt` feeds the runtime-state bridge.
+*/
+var ImageSettingsStatusSchema = object({
+	/** Normalized 0–100. */
+	brightness: number().optional(),
+	/** Normalized 0–100. */
+	contrast: number().optional(),
+	/** Normalized 0–100. */
+	saturation: number().optional(),
+	/** Normalized 0–100. */
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	/** Manual white-balance warmth, NORMALIZED 0–100. Meaningful only when `whiteBalance === 'manual'`. */
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional(),
+	lastFetchedAt: number()
+});
+/**
+* Per-camera availability descriptor — drives which controls the admin UI
+* renders. Booleans as `supportsX`; numeric ranges as `{ min, max, step }`
+* (the normalized 0–100 range); enums as arrays of supported values (empty
+* array → control hidden). A provider returns honest, camera-probed values
+* — never hardcoded.
+*/
+var ImageSettingsOptionsSchema = object({
+	supportsBrightness: boolean(),
+	brightness: NormalizedRangeSchema.optional(),
+	supportsContrast: boolean(),
+	contrast: NormalizedRangeSchema.optional(),
+	supportsSaturation: boolean(),
+	saturation: NormalizedRangeSchema.optional(),
+	supportsSharpness: boolean(),
+	sharpness: NormalizedRangeSchema.optional(),
+	supportsMirror: boolean(),
+	supportsFlip: boolean(),
+	/** Supported rotation values. Empty → rotation not configurable. */
+	rotateOptions: array(ImageRotateSchema),
+	/** Supported white-balance modes. Empty → white-balance not configurable. */
+	whiteBalanceModes: array(WhiteBalanceModeSchema),
+	supportsWarmth: boolean(),
+	/** Present when `supportsWarmth` — the normalized 0–100 range. */
+	warmth: NormalizedRangeSchema.optional(),
+	/** Supported exposure modes. Empty → exposure not configurable. */
+	exposureModes: array(ExposureModeSchema),
+	/** Supported backlight modes. Empty → backlight-compensation not configurable. */
+	backlightModes: array(BacklightModeSchema)
+});
+/**
+* Partial change to the image config — every field optional. Slider values
+* are normalized 0–100. A provider ignores fields it does not support.
+*/
+var ImageSettingsPatchSchema = object({
+	brightness: number().optional(),
+	contrast: number().optional(),
+	saturation: number().optional(),
+	sharpness: number().optional(),
+	mirror: boolean().optional(),
+	flip: boolean().optional(),
+	rotate: ImageRotateSchema.optional(),
+	whiteBalance: WhiteBalanceModeSchema.optional(),
+	warmth: number().optional(),
+	exposureMode: ExposureModeSchema.optional(),
+	backlightMode: BacklightModeSchema.optional()
+});
+var imageSettingsCapability = {
+	name: "image-settings",
+	scope: "device",
+	deviceNative: true,
+	mode: "singleton",
+	deviceTypes: [DeviceType.Camera],
+	deviceConfig: { ui: {
+		kind: "derived-form",
+		builderId: "image-settings",
+		tab: "image"
+	} },
+	methods: {
+		getOptions: method(object({ deviceId: number() }), ImageSettingsOptionsSchema),
+		setSettings: method(object({
+			deviceId: number(),
+			settings: ImageSettingsPatchSchema
+		}), _void(), {
+			kind: "mutation",
+			auth: "admin"
+		})
+	},
+	status: {
+		schema: ImageSettingsStatusSchema,
+		kind: "poll"
+	},
+	runtimeState: ImageSettingsStatusSchema
+};
+/**
 * Robotic lawn-mower cap. Models HA `lawn_mower.*` entities — anything
 * with a mowing lifecycle plus a dock action.
 *
@@ -12171,6 +12431,16 @@ var RunnerCameraConfigSchema = object({
 	* this gate is bypassed.
 	*/
 	onboardMotionDrivesAnalyzer: boolean().default(true),
+	/**
+	* Master toggle for the occupancy re-check. When `false` (DEFAULT) the runner
+	* never arms the periodic recheck timer, regardless of `occupancyRecheckSec` —
+	* this is off by default because the recheck re-subscribes a detection session
+	* every N seconds while `watching`, a major source of pull-decoder re-dial
+	* churn (each cycle creates+tears a session → RTSP re-dial → latency). The
+	* `occupancyRecheckSec` / `occupancyRecheckFrames` sliders only take effect
+	* (and only render) when this is enabled.
+	*/
+	occupancyRecheckEnabled: boolean().default(false),
 	occupancyRecheckSec: number().min(occupancyRecheckSecField.min).max(occupancyRecheckSecField.max).default(occupancyRecheckSecField.default),
 	occupancyRecheckFrames: number().min(occupancyRecheckFramesField.min).max(occupancyRecheckFramesField.max).default(occupancyRecheckFramesField.default),
 	/**
@@ -14176,6 +14446,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	contact: contactCapability,
 	control: controlCapability,
 	cover: coverCapability,
+	dayNight: dayNightCapability,
 	deviceDiscovery: deviceDiscoveryCapability,
 	deviceStatus: deviceStatusCapability,
 	doorbell: doorbellCapability,
@@ -14188,6 +14459,7 @@ var DEVICE_LOCAL_STATE_CAPS = {
 	humidifier: humidifierCapability,
 	humiditySensor: humiditySensorCapability,
 	image: imageCapability,
+	imageSettings: imageSettingsCapability,
 	lawnMowerControl: lawnMowerControlCapability,
 	lockControl: lockControlCapability,
 	mediaPlayer: mediaPlayerCapability,
@@ -16114,7 +16386,9 @@ method(object({ codec: string() }), boolean()), method(_void(), object({
 	id: string(),
 	name: string(),
 	isPullMode: boolean().optional(),
-	priority: number().optional()
+	priority: number().optional(),
+	hwaccel: string().optional(),
+	probedBestHwaccel: string().optional()
 })), method(DecoderSessionConfigSchema, object({
 	sessionId: string(),
 	nodeId: string()
@@ -18028,7 +18302,17 @@ var AgentAddonConfigSchema = object({
 });
 var AgentPipelineSettingsSchema = object({
 	addonDefaults: record(string(), AgentAddonConfigSchema).readonly(),
-	maxCameras: number().int().nonnegative().nullable().default(null)
+	maxCameras: number().int().nonnegative().nullable().default(null),
+	/** Per-node detection weight (relative share for the quota balancer). */
+	detectWeight: number().positive().optional(),
+	/** Node is eligible to run the detection pipeline (decode + inference). */
+	detect: boolean().optional(),
+	/** Node is eligible to host decoder sessions. */
+	decode: boolean().optional(),
+	/** Node is eligible to run audio-analyzer sessions. */
+	audio: boolean().optional(),
+	/** Node is eligible to be the ingest / source-owner (serve the restream). */
+	ingest: boolean().optional()
 });
 var CameraPipelineForAgentSchema = object({
 	steps: array(PipelineStepInputSchema).readonly(),
@@ -18334,6 +18618,21 @@ method(object({
 }), object({ success: literal(true) }), {
 	kind: "mutation",
 	auth: "admin"
+}), method(object({
+	agentNodeId: string(),
+	detectWeight: number().positive().nullable()
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	agentNodeId: string(),
+	detect: boolean().nullable().optional(),
+	decode: boolean().nullable().optional(),
+	audio: boolean().nullable().optional(),
+	ingest: boolean().nullable().optional()
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(object({ deviceId: number() }), CameraPipelineSettingsSchema.nullable()), method(object({
 	deviceId: number(),
 	addonId: string(),
@@ -22499,6 +22798,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"dayNight.getOptions": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"dayNight.setSettings": {
+		capName: "day-night",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"decoder.createSession": {
 		capName: "decoder",
 		capScope: "system",
@@ -23429,6 +23740,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"imageSettings.getOptions": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"imageSettings.setSettings": {
+		capName: "image-settings",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"integrations.create": {
 		capName: "integrations",
 		capScope: "system",
@@ -24611,6 +24934,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setAgentCapabilities": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineOrchestrator.setAgentDetectWeight": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setAgentMaxCameras": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -29870,6 +30205,26 @@ async function withTimeout(promise, ms, label) {
 	}
 }
 /**
+* Hikvision's `IrcutFilterType` enumerates the same four values as the
+* `day-night` cap's `DayNightMode` — no value mapping needed, only a
+* type-narrowing guard for the loosely-typed ISAPI response.
+*/
+var HIKVISION_DAY_NIGHT_MODES = [
+	"auto",
+	"day",
+	"night",
+	"schedule"
+];
+function isDayNightMode(mode) {
+	return mode === "auto" || mode === "day" || mode === "night" || mode === "schedule";
+}
+/** Narrow the ISAPI `IrcutFilterType` string to `DayNightMode`, falling
+*  back to `'auto'` for any value outside the known enum (defensive —
+*  firmware is not expected to emit anything else). */
+function toDayNightMode(mode) {
+	return isDayNightMode(mode) ? mode : "auto";
+}
+/**
 * Hikvision camera device — ISAPI control channel for snapshot, reboot,
 * and the alarm event stream; RTSP URLs handed to the broker for video
 * pull (the broker handles the actual TCP/UDP RTSP, codec negotiation,
@@ -29950,6 +30305,10 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 	motionZonesRefreshInFlight = null;
 	/** Single-flight guard for the privacy-mask camera refresh. */
 	privacyMaskRefreshInFlight = null;
+	/** Single-flight guard for the day-night camera refresh. */
+	dayNightRefreshInFlight = null;
+	/** Single-flight guard for the image-settings camera refresh. */
+	imageSettingsRefreshInFlight = null;
 	/**
 	* Single-flight guard for the v0.2 capability discovery probe. Reset
 	* on settings patches that change credentials (`disconnectAll`) so
@@ -30037,6 +30396,8 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 		this.registerStreamParamsCap(1);
 		this.registerMotionZonesCap(1);
 		this.registerPrivacyMaskCap(1);
+		this.registerDayNightCap(1);
+		this.registerImageSettingsCap(1);
 		this.registerStreamCatalogProvider();
 		this.registerDeviceAction("syncTimeFromLocal", deviceCustomAction(object({}), object({ success: boolean() }), { kind: "mutation" }), async () => {
 			try {
@@ -31508,6 +31869,222 @@ var HikvisionCamera = class HikvisionCamera extends BaseDevice {
 		});
 	}
 	/**
+	* Register the `day-night` native cap provider — the vendor-neutral
+	* IR-cut mode control shared with reolink/amcrest. Hikvision exposes
+	* IR-cut switching mode at `/ISAPI/Image/channels/{cam}/IrcutFilter`
+	* (`IrcutFilterType`: auto/day/night/schedule) — the enum matches the
+	* cap's `DayNightMode` one-for-one, so no value mapping is needed.
+	*
+	* TODO: photocell `sensitivity` and `switchDelaySec` have no wired
+	* ISAPI equivalent in `HikvisionIsapiClient` yet — the existing
+	* `IrcutFilter` parser only reads `IrcutFilterType`. Advertised as
+	* unsupported (`false`) rather than guessing an undocumented XML tag;
+	* revisit once a real-device capture confirms the sensitivity/delay
+	* field names.
+	*/
+	registerDayNightCap(cameraNumber) {
+		const isapi = this.ensureClient();
+		const CAP_NAME = "day-night";
+		const STALE_MS = 1e4;
+		/** Round-trip the IR-cut filter mode, map into the cap status, write slice. */
+		const refreshFromCamera = async () => {
+			if (this.dayNightRefreshInFlight) return this.dayNightRefreshInFlight;
+			const promise = (async () => {
+				try {
+					const filter = await isapi.getIrcutFilter(cameraNumber);
+					if (!filter) return;
+					const next = {
+						mode: toDayNightMode(filter.mode),
+						lastFetchedAt: Date.now()
+					};
+					this.runtimeState.setCapState(CAP_NAME, next);
+				} catch (err) {
+					this.ctx.logger.debug("hikvision day-night refresh failed — keeping last slice", {
+						tags: { deviceId: this.id },
+						meta: { error: err instanceof Error ? err.message : String(err) }
+					});
+				}
+			})();
+			this.dayNightRefreshInFlight = promise;
+			try {
+				await promise;
+			} finally {
+				this.dayNightRefreshInFlight = null;
+			}
+		};
+		const provider = {
+			getStatus: createRuntimeStateBridge({
+				runtimeState: this.runtimeState,
+				cap: dayNightCapability,
+				ownDeviceId: this.id,
+				refresh: refreshFromCamera,
+				staleMs: STALE_MS,
+				empty: () => ({
+					mode: "auto",
+					lastFetchedAt: 0
+				})
+			}).getStatus,
+			getOptions: async ({ deviceId }) => {
+				const cold = {
+					modes: [],
+					supportsSensitivity: false,
+					supportsSwitchDelay: false
+				};
+				if (deviceId !== this.id) return cold;
+				if (!await isapi.getIrcutFilter(cameraNumber)) return cold;
+				return {
+					modes: [...HIKVISION_DAY_NIGHT_MODES],
+					supportsSensitivity: false,
+					supportsSwitchDelay: false
+				};
+			},
+			setSettings: async ({ deviceId, settings }) => {
+				if (deviceId !== this.id) return;
+				if (settings.mode !== void 0) await isapi.setIrcutFilter(cameraNumber, { mode: settings.mode });
+				await refreshFromCamera();
+			}
+		};
+		this.ctx.registerNativeCap(dayNightCapability, provider);
+		this.ctx.logger.info("hikvision: day-night cap registered", {
+			tags: { deviceId: this.id },
+			meta: { cameraNumber }
+		});
+	}
+	/**
+	* Register the `image-settings` native cap provider — vendor-neutral
+	* picture-adjustment controls shared with reolink/amcrest. Hikvision's
+	* `/ISAPI/Image/channels/{cam}` sub-resources map cleanly onto FOUR
+	* of the cap's fields:
+	*   - brightness/contrast/saturation ← `/color` (`getImageColor`/`setImageColor`)
+	*   - sharpness                      ← `/sharpness` (separate endpoint)
+	*   - backlightMode `'off'`/`'wdr'`  ← `/WDR` (`getImageWdr`/`setImageWdr`, open/close)
+	* All four are ALREADY normalized 0..100 on the wire (the ISAPI
+	* client's `setImageColor`/`setImageSharpness` clamp to that range),
+	* so no unit conversion is needed for the cap's normalized-0-100
+	* contract — the range descriptor is the identity `{0,100,1}`.
+	*
+	* TODO — no wired ISAPI equivalent in `HikvisionIsapiClient` yet, left
+	* unsupported (honest `false`/`[]` in `getOptions`) rather than
+	* guessing undocumented XML tags:
+	*   - mirror / flip / rotate
+	*   - white-balance mode + manual warmth
+	*   - exposure mode
+	*   - backlightMode `'blc'` / `'hlc'` (only the WDR on/off toggle is wired)
+	*/
+	registerImageSettingsCap(cameraNumber) {
+		const isapi = this.ensureClient();
+		const CAP_NAME = "image-settings";
+		const STALE_MS = 1e4;
+		const NORMALIZED_RANGE = {
+			min: 0,
+			max: 100,
+			step: 1
+		};
+		/** Round-trip color + sharpness + WDR, map into the cap status, write slice. */
+		const refreshFromCamera = async () => {
+			if (this.imageSettingsRefreshInFlight) return this.imageSettingsRefreshInFlight;
+			const promise = (async () => {
+				try {
+					const [color, sharpness, wdr] = await Promise.all([
+						isapi.getImageColor(cameraNumber),
+						isapi.getImageSharpness(cameraNumber),
+						isapi.getImageWdr(cameraNumber)
+					]);
+					if (!color && sharpness === null && !wdr) return;
+					const next = {
+						brightness: color?.brightness ?? void 0,
+						contrast: color?.contrast ?? void 0,
+						saturation: color?.saturation ?? void 0,
+						sharpness: sharpness ?? color?.sharpness ?? void 0,
+						backlightMode: wdr ? wdr.enabled ? "wdr" : "off" : void 0,
+						lastFetchedAt: Date.now()
+					};
+					this.runtimeState.setCapState(CAP_NAME, next);
+				} catch (err) {
+					this.ctx.logger.debug("hikvision image-settings refresh failed — keeping last slice", {
+						tags: { deviceId: this.id },
+						meta: { error: err instanceof Error ? err.message : String(err) }
+					});
+				}
+			})();
+			this.imageSettingsRefreshInFlight = promise;
+			try {
+				await promise;
+			} finally {
+				this.imageSettingsRefreshInFlight = null;
+			}
+		};
+		const provider = {
+			getStatus: createRuntimeStateBridge({
+				runtimeState: this.runtimeState,
+				cap: imageSettingsCapability,
+				ownDeviceId: this.id,
+				refresh: refreshFromCamera,
+				staleMs: STALE_MS,
+				empty: () => ({ lastFetchedAt: 0 })
+			}).getStatus,
+			getOptions: async ({ deviceId }) => {
+				const cold = {
+					supportsBrightness: false,
+					supportsContrast: false,
+					supportsSaturation: false,
+					supportsSharpness: false,
+					supportsMirror: false,
+					supportsFlip: false,
+					rotateOptions: [],
+					whiteBalanceModes: [],
+					supportsWarmth: false,
+					exposureModes: [],
+					backlightModes: []
+				};
+				if (deviceId !== this.id) return cold;
+				const [color, sharpness, wdr] = await Promise.all([
+					isapi.getImageColor(cameraNumber),
+					isapi.getImageSharpness(cameraNumber),
+					isapi.getImageWdr(cameraNumber)
+				]);
+				const hasBrightness = color?.brightness !== null && color?.brightness !== void 0;
+				const hasContrast = color?.contrast !== null && color?.contrast !== void 0;
+				const hasSaturation = color?.saturation !== null && color?.saturation !== void 0;
+				const hasSharpness = sharpness !== null;
+				return {
+					supportsBrightness: hasBrightness,
+					brightness: hasBrightness ? NORMALIZED_RANGE : void 0,
+					supportsContrast: hasContrast,
+					contrast: hasContrast ? NORMALIZED_RANGE : void 0,
+					supportsSaturation: hasSaturation,
+					saturation: hasSaturation ? NORMALIZED_RANGE : void 0,
+					supportsSharpness: hasSharpness,
+					sharpness: hasSharpness ? NORMALIZED_RANGE : void 0,
+					supportsMirror: false,
+					supportsFlip: false,
+					rotateOptions: [],
+					whiteBalanceModes: [],
+					supportsWarmth: false,
+					exposureModes: [],
+					backlightModes: wdr ? ["off", "wdr"] : []
+				};
+			},
+			setSettings: async ({ deviceId, settings }) => {
+				if (deviceId !== this.id) return;
+				if (settings.brightness !== void 0 || settings.contrast !== void 0 || settings.saturation !== void 0) await isapi.setImageColor(cameraNumber, {
+					brightness: settings.brightness,
+					contrast: settings.contrast,
+					saturation: settings.saturation
+				});
+				if (settings.sharpness !== void 0) await isapi.setImageSharpness(cameraNumber, settings.sharpness);
+				if (settings.backlightMode === "wdr") await isapi.setImageWdr(cameraNumber, { enabled: true });
+				else if (settings.backlightMode === "off") await isapi.setImageWdr(cameraNumber, { enabled: false });
+				await refreshFromCamera();
+			}
+		};
+		this.ctx.registerNativeCap(imageSettingsCapability, provider);
+		this.ctx.logger.info("hikvision: image-settings cap registered", {
+			tags: { deviceId: this.id },
+			meta: { cameraNumber }
+		});
+	}
+	/**
 	* Translate a cap-layer `StreamProfilePatch` into the field set
 	* `setStreamingChannel` accepts. `current` is the freshly-read
 	* channel config — used to resolve which quality-mode field a