@camstack/system 1.2.253 → 1.2.255

package/dist/{dist-DH6ThyTd.mjs → dist-Ch93tyHB.mjs}

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import "node:crypto";
 //#region ../types/dist/event-category-BVDXG4tB.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -690,7 +691,7 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	return EventCategory;
 }({});
 //#endregion
-//#region ../types/dist/sleep-Bs3xPtSh.mjs
+//#region ../types/dist/sleep-GU_us3DG.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -1025,6 +1026,22 @@ function typeOf(field) {
 	}
 }
 /**
+* Narrow a SystemEvent to a typed event by checking its category.
+* Returns `true` (and narrows the type) if the category matches.
+*
+* @example
+* ```typescript
+* eventBus.subscribe({ category: 'addon.started' }, (event) => {
+*   if (isEvent(event, 'addon.started')) {
+*     event.data.addonId  // ✓ typed as string
+*   }
+* })
+* ```
+*/
+function isEvent(event, category) {
+	return event.category === category;
+}
+/**
 * Create a typed event with less boilerplate.
 *
 * @example
@@ -3387,6 +3404,360 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 //#endregion
+//#region ../types/dist/canonical-hash-biq7T_dN.mjs
+var AUDIO_ENCODER_BY_CODEC = {
+	opus: "libopus",
+	aac: "aac",
+	pcmu: "pcm_mulaw",
+	pcma: "pcm_alaw"
+};
+/**
+* Camera-microphone audio, per codec. Lives HERE rather than in
+* `encode-defaults.ts` only to avoid an import cycle (`encode-defaults` depends
+* on these types); it is re-exported from there, which is where to read it.
+*
+* Every source in this repo is a mono camera mic. The former broker preset
+* encoded Opus at `channels: 2`, spending bitrate duplicating one channel —
+* that is the value this consolidation changed.
+*/
+var AUDIO_PRESETS = {
+	aac: {
+		kind: "encode",
+		codec: "aac",
+		bitrateKbps: 128,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	opus: {
+		kind: "encode",
+		codec: "opus",
+		bitrateKbps: 64,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	pcmu: {
+		kind: "encode",
+		codec: "pcmu",
+		sampleRateHz: 8e3,
+		channels: 1
+	}
+};
+/** `-hide_banner -loglevel <level>` — every ffmpeg site opens with this. */
+function logBannerArgs(level) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		level
+	];
+}
+/** `true` when the resolved value means "decode in software" (⇒ no `-hwaccel`). */
+function isSoftwareDecode(decodeHwAccel) {
+	return !decodeHwAccel || decodeHwAccel === "none" || decodeHwAccel === "copy";
+}
+/**
+* Every INPUT option, in order, terminated by `-i <url>`. Nothing may be
+* appended to this list by a caller — that is the whole point of the function.
+*/
+function buildInputArgs(input, decodeHwAccel) {
+	const args = [];
+	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
+	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
+	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
+	if (input.lowDelay === true) args.push("-flags", "low_delay");
+	if (input.fflags?.length) for (const flag of input.fflags) args.push("-fflags", flag);
+	if (input.rtspTransport) args.push("-rtsp_transport", input.rtspTransport);
+	args.push("-i", input.url);
+	return args;
+}
+/**
+* Derive the output `-map` selectors. The three cases, in the order they are
+* decided:
+*
+* 1. **A filter graph** — the picture is the graph's declared video pad, and
+*    the audio is its audio pad when it has one, otherwise input 0's mic. A
+*    graph's output is not addressable any other way.
+* 2. **N inputs, no graph** — map input 0 EXPLICITLY. ffmpeg's own selection
+*    picks the "best" stream across ALL inputs, so the egress would silently
+*    become whichever camera happens to have the largest frame.
+* 3. **One input, no graph** — no `-map`. Anything else would change the argv
+*    of every call site that exists today for no gain.
+*/
+function resolveStreamMaps(selection) {
+	const graph = selection.filterGraph;
+	if (graph) return {
+		video: `[${graph.videoOutLabel}]`,
+		audio: graph.audioOutLabel ? `[${graph.audioOutLabel}]` : "0:a:0?"
+	};
+	if (selection.extraInputs?.length) return {
+		video: "0:v:0",
+		audio: "0:a:0?"
+	};
+	return {
+		video: null,
+		audio: null
+	};
+}
+/** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
+function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+	if (filterGraph) {
+		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
+		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
+		return [];
+	}
+	if (!scale) return [];
+	if (outputArgs.some((a) => a === "-vf")) return [];
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+}
+/** Rate-control args for an encode plan. */
+function buildRateControlArgs(video) {
+	const kbps = video.bitrateKbps;
+	if (kbps === void 0) return [];
+	const rc = video.rateControl ?? {
+		kind: "cap",
+		vbvSeconds: 2
+	};
+	const bufsize = Math.max(1, Math.round(kbps * rc.vbvSeconds));
+	return [
+		...rc.kind === "cbr" ? ["-b:v", `${kbps}k`] : [],
+		"-maxrate",
+		`${kbps}k`,
+		"-bufsize",
+		`${bufsize}k`
+	];
+}
+/** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
+function buildVideoArgs(video, outputArgs, filterGraph) {
+	if (video.kind === "copy") {
+		if (filterGraph) throw new Error("FfmpegInvocation: a filter graph produces a NEW picture, so video.kind must be `encode`");
+		return [
+			"-c:v",
+			"copy",
+			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+		];
+	}
+	const args = [
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
+		"-c:v",
+		video.encoder
+	];
+	if (video.preset !== void 0) args.push("-preset", video.preset);
+	if (video.tune !== void 0) args.push("-tune", video.tune);
+	if (video.singleSlicePerFrame === true && video.encoder === "libx264") args.push("-x264-params", "sliced-threads=0");
+	if (video.profile !== void 0) args.push("-profile:v", video.profile);
+	if (video.level !== void 0) args.push("-level", video.level);
+	if (video.pixelFormat !== void 0) args.push("-pix_fmt", video.pixelFormat);
+	if (video.fps !== void 0) args.push("-r", String(video.fps));
+	if (video.gopFrames !== void 0) args.push("-g", String(video.gopFrames));
+	if (video.forceKeyFramesSeconds !== void 0) args.push("-force_key_frames", `expr:gte(t,n_forced*${video.forceKeyFramesSeconds})`);
+	if (video.bf !== void 0) args.push("-bf", String(video.bf));
+	args.push(...buildRateControlArgs(video));
+	if (video.bitstreamFilter !== void 0) args.push("-bsf:v", video.bitstreamFilter);
+	return args;
+}
+/** The whole audio block, after `-i`. */
+function buildAudioArgs(audio) {
+	if (audio.kind === "none") return ["-an"];
+	if (audio.kind === "copy") return ["-c:a", "copy"];
+	const args = [];
+	if (audio.filter !== void 0) args.push("-af", audio.filter);
+	args.push("-c:a", AUDIO_ENCODER_BY_CODEC[audio.codec]);
+	if (audio.application !== void 0) args.push("-application", audio.application);
+	if (audio.frameDurationMs !== void 0) args.push("-frame_duration", String(audio.frameDurationMs));
+	if (audio.globalHeader === true) args.push("-flags", "+global_header");
+	if (audio.sampleRateHz !== void 0) args.push("-ar", String(audio.sampleRateHz));
+	if (audio.bitrateKbps !== void 0) args.push("-b:a", `${audio.bitrateKbps}k`);
+	if (audio.vbvBufferKbits !== void 0) args.push("-bufsize", `${audio.vbvBufferKbits}k`);
+	if (audio.channels !== void 0) args.push("-ac", String(audio.channels));
+	return args;
+}
+/** RTP output-leg args (`-payload_type`, `-ssrc`, `-sdp_file`, `-f rtp <url>`). */
+function buildRtpOutputArgs(out) {
+	const args = [];
+	if (out.payloadType !== void 0) args.push("-payload_type", String(out.payloadType));
+	if (out.ssrc !== void 0) args.push("-ssrc", String(out.ssrc));
+	if (out.sdpFile !== void 0) args.push("-sdp_file", out.sdpFile);
+	args.push("-f", "rtp", out.url);
+	return args;
+}
+/** `true` when the sink is a raw elementary bytestream that cannot mux audio. */
+function isElementaryVideoSink(sink) {
+	return sink.kind === "stdout" && (sink.container === "h264" || sink.container === "hevc");
+}
+/**
+* The fragmented-MP4 muxer flags, in the order the recorder has proven them
+* (`recorder/addon/ffmpeg-args.ts` passes the same `movflags` string through
+* `-segment_format_options`, across every vendor in the fleet):
+*
+* - `frag_keyframe` — cut a fragment at each key frame, so every fragment
+*   opens on a sync sample. HKSV's whole requirement.
+* - `empty_moov` — write `ftyp`+`moov` up front with no samples in it, which
+*   is what makes the head a standalone INITIALISATION segment.
+* - `default_base_moof` — fragment offsets are self-relative, so a fragment is
+*   demuxable without the bytes that preceded it. D31's byte-range read path
+*   depends on exactly this property of the recorder's segments.
+*/
+var FMP4_MOVFLAGS = "+frag_keyframe+empty_moov+default_base_moof";
+/**
+* The terminal sink args for every non-`rtp-outputs` sink. Exhaustive over the
+* union so a new member cannot fall through to `['-f', container, 'pipe:1']`,
+* which is what a plain `container` read would have done for `mp4` — a valid
+* argv that writes a NON-fragmented, unseekable-to-a-pipe MP4 and produces one
+* unusable byte stream.
+*/
+function buildStdoutOrRtspSinkArgs(sink) {
+	if (sink.kind === "rtsp-listen") return [
+		"-f",
+		"rtsp",
+		"-rtsp_transport",
+		"tcp",
+		"-rtsp_flags",
+		"listen",
+		sink.url
+	];
+	if (sink.kind === "rtp-outputs") return [];
+	return sink.container === "mp4" ? buildFmp4SinkArgs(sink) : [
+		"-f",
+		sink.container,
+		"pipe:1"
+	];
+}
+/**
+* How far BELOW the negotiated fragment length `-min_frag_duration` is set.
+*
+* `-min_frag_duration` refuses to cut before that much media has accumulated,
+* and then waits for the next key frame. Set to exactly `fragmentMs`, the
+* commonest camera configuration in existence — a key-frame grid EQUAL to the
+* requested fragment length — lands the deadline on the same instant as the key
+* frame, loses the race, and skips to the following one: **every fragment comes
+* out at twice the requested length.**
+*
+* Measured on the live fleet 2026-08-07, camera 615, `-c:v copy` (D84):
+*
+* | slot | GOP | `-min_frag_duration` | median gap |
+* | --- | --- | --- | --- |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 4000 ms | **7944 ms** |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 3600 ms | 3973 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 4000 ms | 8042 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 3600 ms | 3998 ms |
+*
+* A doubled fragment is not a cosmetic overshoot: HKSV requires every fragment
+* to be no longer than the length the controller SELECTED, so the shipped-but-
+* inert phase-1 sink would have violated the contract on its first real clip.
+*
+* 10 % is chosen against the two failures either side of it. Too small and
+* ordinary jitter (measured spread 3953-4096 ms) re-loses the race; too large
+* and a source with a key frame slightly EARLY than the grid gets cut there,
+* yielding a short fragment for no reason.
+*/
+var FMP4_MIN_FRAG_MARGIN = .9;
+/** `-movflags … -min_frag_duration <us> -f mp4 pipe:1`. */
+function buildFmp4SinkArgs(sink) {
+	return [
+		"-movflags",
+		FMP4_MOVFLAGS,
+		"-min_frag_duration",
+		String(Math.max(0, Math.round(sink.fragmentMs * FMP4_MIN_FRAG_MARGIN * 1e3))),
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
+}
+/**
+* A second output mapping source audio to RTP-over-UDP. `0:a:0?` makes the
+* audio optional so a source with no audio skips it instead of failing the
+* whole invocation.
+*/
+function buildAudioSidecarArgs(sidecar) {
+	return [
+		"-map",
+		"0:a:0?",
+		...buildAudioArgs(sidecar.codec === "pcma" ? {
+			kind: "encode",
+			codec: "pcma",
+			sampleRateHz: 8e3,
+			channels: 1
+		} : AUDIO_PRESETS[sidecar.codec]),
+		...buildRtpOutputArgs({
+			url: sidecar.rtpUrl,
+			sdpFile: sidecar.sdpFile
+		})
+	];
+}
+/**
+* Assemble the full ffmpeg argument list. Layout:
+*
+*   -hide_banner -loglevel <level>
+*   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
+*   [<input.extraArgs>]               │
+*   [-fflags <flag>…]                 │
+*   [-rtsp_transport tcp]             │
+*   -i <url>                         ─┘ …repeated per extraInput
+*   [-filter_complex <graph>]         ─ global, after the LAST -i
+*   [-map <video>]  <video block>  <threads>  ─┐ OUTPUT options.
+*   [-map <audio>]  <audio block>              │
+*   <consumer outputArgs verbatim>             │
+*   <sink>                                    ─┘ terminal
+*
+* The `-map`s are DERIVED (see {@link resolveStreamMaps}), never constants:
+* one input with no graph emits none at all, which is why the argv of every
+* call site that predates the N-input extension is unchanged to the byte.
+*
+* {@link FfmpegInvocation.audioSidecar} is the one map that stays literal
+* (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
+* output, not as whatever the main output happens to carry.
+*/
+function buildFfmpegArgs(inv) {
+	const graph = inv.filterGraph ?? null;
+	const head = [
+		...logBannerArgs(inv.logLevel),
+		...buildInputArgs(inv.input, inv.decodeHwAccel),
+		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
+		...graph ? ["-filter_complex", graph.graph] : []
+	];
+	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	const maps = resolveStreamMaps(inv);
+	const videoMapArgs = maps.video ? ["-map", maps.video] : [];
+	const audioMapArgs = maps.audio ? ["-map", maps.audio] : [];
+	if (inv.sink.kind === "rtp-outputs") {
+		const videoLeg = inv.sink.video ? [
+			"-an",
+			"-map",
+			maps.video ?? "0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs, graph),
+			...threadArgs,
+			...inv.outputArgs,
+			...buildRtpOutputArgs(inv.sink.video)
+		] : [];
+		const audioLeg = inv.sink.audio ? [
+			"-vn",
+			"-map",
+			maps.audio ?? "0:a:0?",
+			...buildAudioArgs(inv.audio),
+			...buildRtpOutputArgs(inv.sink.audio)
+		] : [];
+		return [
+			...head,
+			...videoLeg,
+			...audioLeg
+		];
+	}
+	const mutedAudio = isElementaryVideoSink(inv.sink) || inv.audio.kind === "none";
+	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
+	return [
+		...head,
+		...videoMapArgs,
+		...buildVideoArgs(inv.video, inv.outputArgs, graph),
+		...threadArgs,
+		...mutedAudio ? [] : audioMapArgs,
+		...audioArgs,
+		...inv.outputArgs,
+		...buildStdoutOrRtspSinkArgs(inv.sink),
+		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
+	];
+}
+//#endregion
 //#region ../types/dist/err-msg-IQTHeDzc.mjs
 /**
 import { errMsg } from '@camstack/types'
@@ -3912,6 +4283,14 @@ var CameraSwitchGroupSchema = z.object({
 	fetchedAt: z.number()
 });
 /**
+* The wrapper capability each wrapper-backed switch controls. Named constants
+* because the same strings appear in `legacy-migrations.ts`, in
+* `isCapActiveForDevice` call sites and in the fake harness — a typo in any of
+* them is a switch that silently writes a binding nobody reads.
+*/
+var DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
+var AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/**
 * The value a redacted secret is replaced with on every read surface.
 *
 * It is also the WRITE-BACK token: an `upsertLocation` that sends this value
@@ -10974,6 +11353,45 @@ var SourceInfoSchema = z.object({
 	raw: z.record(z.string(), z.unknown()).optional()
 });
 /**
+* Build the synthetic SourceInfo every existing provider falls back to
+* when no upstream value has been persisted. Keeps non-migrated providers
+* (Reolink / Hikvision / ONVIF / RTSP) functional without code
+* changes — `id` reuses the CamStack stableId, `system` reuses the addon
+* id. Real upstream identity replaces this once a provider migrates and
+* calls `updateSourceInfo()` with concrete values.
+*/
+function synthesizeSourceInfo(input) {
+	return {
+		id: input.stableId,
+		system: input.addonId
+	};
+}
+/**
+* Shallow-merge a partial patch over a prior SourceInfo. `undefined`
+* patch values are ignored (no field clobber); to clear a field
+* explicitly, providers omit it from the patch and rebuild from scratch
+* via `updateSourceInfo({})` cycles — uncommon enough that we don't
+* bother with a `null`-means-delete sentinel.
+*
+* The `raw` field is also shallow-merged: passing `raw: { foo: 1 }`
+* merges over existing `raw` keys instead of replacing the whole bag.
+*/
+function mergeSourceInfo(prev, patch) {
+	const next = { ...prev };
+	for (const [k, v] of Object.entries(patch)) {
+		if (v === void 0) continue;
+		if (k === "raw" && typeof v === "object" && v !== null) {
+			next.raw = {
+				...prev.raw,
+				...v
+			};
+			continue;
+		}
+		next[k] = v;
+	}
+	return next;
+}
+/**
 * Coerce common unit-of-measurement string variants to a canonical form
 * so the UI's display templates can rely on stable strings. Pure
 * passthrough for unknown units — kept conservative on purpose, the goal
@@ -11019,6 +11437,27 @@ function normalizeUnit(raw) {
 	return trimmed;
 }
 /**
+* Key under which `SourceInfo` lives inside `DeviceMeta.metadata`. The
+* blob is a free-form `Record<string, unknown>` shared with hardware-
+* identity fields (`manufacturer`, `model`, `firmware`, …); SourceInfo
+* lives under a single nested key to keep it composable with those.
+*/
+var SOURCE_INFO_METADATA_KEY = "sourceInfo";
+/**
+* Extract a SourceInfo from a `DeviceMeta.metadata` blob, validating
+* with Zod. Returns `null` when the blob is missing or the nested
+* `sourceInfo` key fails validation — callers fall back to the
+* synthetic default in that case (see `synthesizeSourceInfo`).
+*/
+function extractSourceInfoFromMetadata(metadata) {
+	if (!metadata) return null;
+	const raw = metadata[SOURCE_INFO_METADATA_KEY];
+	if (!raw) return null;
+	const parsed = SourceInfoSchema.safeParse(raw);
+	if (!parsed.success) return null;
+	return parsed.data;
+}
+/**
 * device-discovery — device-scoped capability for parents that host /
 * enumerate child devices (Reolink Hub / NVR, ONVIF gateway, future
 * integrations). The parent advertises a list of discoverable children,
@@ -30645,11 +31084,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
 *
@@ -30739,13 +31182,24 @@ var cameraGridLayoutCapability = {
 	deviceNative: true,
 	mode: "singleton",
 	deviceTypes: [DeviceType.Camera],
-	deviceConfig: { ui: {
-		kind: "widget",
-		widgetId: "host/camera-grid-layout",
-		tab: "streaming",
-		label: "Grid layout",
-		order: 20
-	} },
+	/**
+	* The section is built by the ADDON and returned from
+	* `getDeviceSettingsContribution`, not derived by the framework from a
+	* `deviceConfig.ui` block.
+	*
+	* Both mechanisms render the same widget. This one hands the addon two
+	* things the framework-derived route cannot give it:
+	*
+	*  - it chooses its own section, `tab`, `location` and `order`, the way any
+	*    other setting does, instead of receiving them from a cap declaration;
+	*  - it can DECLINE per device. A camera that is not a grid gets no section
+	*    at all, rather than a widget that renders its own "not a grid" state.
+	*
+	* `recording` is the precedent (`recorder/recording-device-settings.ts`): it
+	* returns `null` for anything that is not a camera, so the Recording tab
+	* never appears there.
+	*/
+	exposesDeviceSettings: true,
 	methods: {
 		/**
 		* The grid behind this device.
@@ -33354,6 +33808,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",
@@ -37496,6 +37969,807 @@ var AccessoryKind = {
 	PrivacyMask: DeviceRole.PrivacyMask
 };
 AccessoryKind.Siren, AccessoryKind.Floodlight, AccessoryKind.Spotlight, AccessoryKind.PirSensor, AccessoryKind.Chime, AccessoryKind.Autotrack, AccessoryKind.Nightvision, AccessoryKind.PrivacyMask;
+var DeviceConfig = class DeviceConfig {
+	schema;
+	data;
+	persistFn;
+	constructor(schema, data, persist) {
+		this.schema = schema;
+		this.data = data;
+		this.persistFn = persist;
+	}
+	/**
+	* Build a `DeviceConfig` from a persisted blob, with automatic
+	* recovery from schema-validation failures. Boot must never be
+	* blocked by stale persisted values: if Zod rejects the blob,
+	* we drop every offending top-level field, retry, and persist
+	* the cleaned blob so the bad value is healed in the DB on next
+	* write. The most common trigger is a tightened range constraint
+	* (e.g. `max(100) → max(50)`) on a field that already has an
+	* out-of-range value persisted from the previous schema. Without
+	* this safety net, the device would fail to instantiate and end
+	* up with no caps registered — exactly the failure mode that
+	* stranded device 15 when `motionSensitivity: 90` no longer fit
+	* the new `1..50` schema.
+	*
+	* Recovery rules:
+	*  1. Try `safeParse(initialData)`. If it succeeds, done.
+	*  2. On failure, walk `error.issues`, collect the top-level path
+	*     of each issue, and drop those keys from `initialData`.
+	*  3. Re-run `safeParse`. If the cleaned blob now passes (Zod
+	*     fills the missing keys with schema defaults / undefined for
+	*     `.optional()`), persist it via `persist()` so the bad
+	*     values disappear from the DB, and return the device.
+	*  4. If the cleaned blob STILL fails (very rare — would require
+	*     a non-recoverable required field), fall back to
+	*     `schema.parse({})` so the device still boots with pure
+	*     schema defaults. Persist nothing in that path so the next
+	*     successful `setAll` still writes a coherent blob.
+	*/
+	static fromSchema(schema, persist, initialData = {}, onRecover) {
+		const first = schema.safeParse(initialData);
+		if (first.success) return new DeviceConfig(schema, first.data, persist);
+		const droppedKeys = /* @__PURE__ */ new Set();
+		for (const issue of first.error.issues) {
+			const top = issue.path[0];
+			if (typeof top === "string") droppedKeys.add(top);
+		}
+		const cleaned = { ...initialData };
+		for (const k of droppedKeys) delete cleaned[k];
+		const second = schema.safeParse(cleaned);
+		onRecover?.({
+			droppedKeys: [...droppedKeys],
+			issues: first.error.issues
+		});
+		if (second.success) {
+			persist(second.data).catch(() => {});
+			return new DeviceConfig(schema, second.data, persist);
+		}
+		return new DeviceConfig(schema, schema.parse({}), persist);
+	}
+	get values() {
+		return this.data;
+	}
+	get(key) {
+		return this.data[key];
+	}
+	async set(key, value) {
+		const next = this.schema.parse({
+			...this.data,
+			[key]: value
+		});
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	/**
+	* Merge an untyped patch onto the current config and persist. Accepts
+	* `Record<string, unknown>` because the patch typically comes from the
+	* UI form layer (a `ConfigField.key → value` map) where the caller
+	* doesn't hold the Zod schema's static type. Runtime validation is
+	* authoritative: `this.schema.parse` rejects unknown keys or invalid
+	* shapes before touching storage.
+	*/
+	async setAll(partial) {
+		const next = this.schema.parse({
+			...this.data,
+			...partial
+		});
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	async deleteKey(key) {
+		const { [key]: _, ...rest } = this.data;
+		const next = this.schema.parse(rest);
+		this.data = next;
+		await this.persistFn(this.data);
+	}
+	entries() {
+		const shape = this.schema.shape;
+		return Object.entries(shape).map(([key, fieldSchema]) => ({
+			key,
+			schema: fieldSchema,
+			value: this.data[key],
+			description: fieldSchema.description
+		}));
+	}
+};
+/**
+* Concrete implementation. Routes every successful write through
+* `writer(capName, slice)` — the kernel hooks this up to
+* `device-state.setCapSlice`, the canonical cross-layer write
+* entrypoint, which handles disk persistence (debounced on the hub)
+* and mirror updates.
+*
+* Schema validation runs in-process before the writer is called —
+* the round-trip should never carry an invalid slice. `flush()`
+* awaits any in-flight writer promises so shutdown is lossless.
+*
+* `initial` is the persisted blob loaded at boot. Slices for caps
+* whose schema hasn't been installed yet are kept in-memory verbatim
+* and validated when the cap registers later.
+*/
+var DeviceRuntimeState = class DeviceRuntimeState {
+	writer;
+	/** In-flight writer promises tracked so `flush()` can await them. */
+	pendingWrites = /* @__PURE__ */ new Set();
+	/** Per-cap committed slice — after schema validation when known. */
+	slices;
+	/** Per-cap registered schema (set by `installCapSchema`). */
+	schemas = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	capListeners = /* @__PURE__ */ new Map();
+	constructor(initial, writer) {
+		this.writer = writer;
+		this.slices = /* @__PURE__ */ new Map();
+		for (const [k, v] of Object.entries(initial)) if (v && typeof v === "object" && !Array.isArray(v)) this.slices.set(k, { ...v });
+	}
+	static fromInitial(initial, writer) {
+		return new DeviceRuntimeState(initial, writer);
+	}
+	installCapSchema(capName, schema) {
+		const existing = this.schemas.get(capName);
+		if (existing) {
+			if (existing !== schema) throw new Error(`[DeviceRuntimeState] capability "${capName}" registered a different runtime-state schema; each cap must declare ONE shape across every provider`);
+			return;
+		}
+		this.schemas.set(capName, schema);
+		const stored = this.slices.get(capName);
+		if (stored) {
+			const result = schema.safeParse(stored);
+			if (result.success) this.slices.set(capName, result.data);
+			else this.slices.delete(capName);
+		}
+	}
+	getCapState(capName) {
+		const slice = this.slices.get(capName);
+		if (!slice) return void 0;
+		return Object.freeze({ ...slice });
+	}
+	getCapField(capName, key) {
+		return this.slices.get(capName)?.[key];
+	}
+	setCapState(capName, value) {
+		this.applyCapWrite(capName, value, false);
+	}
+	patchCapState(capName, partial) {
+		this.applyCapWrite(capName, partial, true);
+	}
+	/**
+	* Internal worker. `merge` controls whether `value` replaces or
+	* shallow-merges into the existing slice. Schema validation runs
+	* on the FINAL composed object regardless.
+	*/
+	applyCapWrite(capName, value, merge) {
+		const schema = this.schemas.get(capName);
+		if (!schema) throw new Error(`[DeviceRuntimeState] no schema registered for cap "${capName}" — did the device register it via ctx.registerNativeCap before writing?`);
+		const current = this.slices.get(capName) ?? {};
+		const next = merge ? {
+			...current,
+			...value
+		} : { ...value };
+		const parsed = schema.parse(next);
+		if (shallowEqual(current, parsed)) return;
+		this.slices.set(capName, parsed);
+		this.fireListeners([capName]);
+		const writePromise = this.writer(capName, { ...parsed }).catch(() => {});
+		this.pendingWrites.add(writePromise);
+		writePromise.finally(() => {
+			this.pendingWrites.delete(writePromise);
+		});
+	}
+	fireListeners(changed) {
+		const snap = this.snapshot();
+		for (const cb of this.listeners) try {
+			cb(changed, snap);
+		} catch {}
+		for (const capName of changed) {
+			const subs = this.capListeners.get(capName);
+			if (!subs) continue;
+			const slice = this.getCapState(capName);
+			for (const cb of subs) try {
+				cb(slice);
+			} catch {}
+		}
+	}
+	subscribe(cb) {
+		this.listeners.add(cb);
+		return () => {
+			this.listeners.delete(cb);
+		};
+	}
+	subscribeCap(capName, cb) {
+		let subs = this.capListeners.get(capName);
+		if (!subs) {
+			subs = /* @__PURE__ */ new Set();
+			this.capListeners.set(capName, subs);
+		}
+		const adapter = (slice) => {
+			cb(slice);
+		};
+		subs.add(adapter);
+		return () => {
+			const set = this.capListeners.get(capName);
+			if (!set) return;
+			set.delete(adapter);
+			if (set.size === 0) this.capListeners.delete(capName);
+		};
+	}
+	snapshot() {
+		const out = {};
+		for (const [k, v] of this.slices) out[k] = Object.freeze({ ...v });
+		return Object.freeze(out);
+	}
+	async flush() {
+		if (this.pendingWrites.size === 0) return;
+		const inflight = [...this.pendingWrites];
+		await Promise.allSettled(inflight);
+	}
+};
+function shallowEqual(a, b) {
+	const ak = Object.keys(a);
+	const bk = Object.keys(b);
+	if (ak.length !== bk.length) return false;
+	for (const k of ak) if (a[k] !== b[k]) return false;
+	return true;
+}
+/**
+* Runtime registry: cap-property-name → cap definition. `BaseDevice`'s
+* `state` getter looks up the cap definition here to construct a
+* `sliceProxy()` lazily on first access. Generated alongside the type
+* so type and runtime registry can never drift apart.
+*/
+var DEVICE_LOCAL_STATE_CAPS = {
+	airQualitySensor: airQualitySensorCapability,
+	alarmPanel: alarmPanelCapability,
+	ambientLightSensor: ambientLightSensorCapability,
+	audioMetrics: audioMetricsCapability,
+	automationControl: automationControlCapability,
+	battery: batteryCapability,
+	binary: binaryCapability,
+	brightness: brightnessCapability,
+	cameraStreams: cameraStreamsCapability,
+	carbonMonoxide: carbonMonoxideCapability,
+	climateControl: climateControlCapability,
+	color: colorCapability,
+	connectivity: connectivityCapability,
+	consumables: consumablesCapability,
+	contact: contactCapability,
+	control: controlCapability,
+	cover: coverCapability,
+	dayNight: dayNightCapability,
+	deviceDiscovery: deviceDiscoveryCapability,
+	deviceStatus: deviceStatusCapability,
+	doorbell: doorbellCapability,
+	enumSensor: enumSensorCapability,
+	eventEmitter: eventEmitterCapability,
+	fanControl: fanControlCapability,
+	featureProbe: featureProbeCapability,
+	flood: floodCapability,
+	gas: gasCapability,
+	humidifier: humidifierCapability,
+	humiditySensor: humiditySensorCapability,
+	image: imageCapability,
+	imageSettings: imageSettingsCapability,
+	intercom: intercomCapability,
+	lawnMowerControl: lawnMowerControlCapability,
+	lockControl: lockControlCapability,
+	mediaPlayer: mediaPlayerCapability,
+	motion: motionCapability,
+	motionTrigger: motionTriggerCapability,
+	motionZones: motionZonesCapability,
+	nativeObjectDetection: nativeObjectDetectionCapability,
+	navigation: navigationCapability,
+	networkLink: networkLinkCapability,
+	notifier: notifierCapability,
+	numericSensor: numericSensorCapability,
+	petFeeder: petFeederCapability,
+	powerMeter: powerMeterCapability,
+	presence: presenceCapability,
+	pressureSensor: pressureSensorCapability,
+	privacyMask: privacyMaskCapability,
+	ptzAutotrack: ptzAutotrackCapability,
+	recordingSignal: recordingSignalCapability,
+	sceneMonitor: sceneMonitorCapability,
+	scriptRunner: scriptRunnerCapability,
+	smoke: smokeCapability,
+	streamCatalog: streamCatalogCapability,
+	streamParams: streamParamsCapability,
+	streamSignals: streamSignalsCapability,
+	switch: switchCapability,
+	tamper: tamperCapability,
+	temperatureSensor: temperatureSensorCapability,
+	update: updateCapability,
+	vacuumControl: vacuumControlCapability,
+	valve: valveCapability,
+	vibration: vibrationCapability,
+	waterHeater: waterHeaterCapability,
+	weather: weatherCapability,
+	zoneAnalytics: zoneAnalyticsCapability,
+	zoneRules: zoneRulesCapability,
+	zones: zonesCapability
+};
+var BaseDevice = class {
+	id;
+	stableId;
+	type;
+	name;
+	parentDeviceId;
+	role;
+	/**
+	* Cap-keyed runtime-state slice is the single source of truth for
+	* `online`. Both getter and setter proxy to the slice — drivers can
+	* write `this.online = true` ergonomically, and the cap event fires
+	* automatically through the runtime-state writer. `markOnline()` is
+	* kept as the explicit method form mandated by `IDevice`.
+	*/
+	get online() {
+		return this.runtimeState.getCapState("device-status")?.online ?? false;
+	}
+	set online(value) {
+		this.markOnline(value);
+	}
+	/**
+	* Generic per-cap runtime-state namespace. One entry per cap with
+	* `runtimeState:` declared, auto-generated by codegen — see
+	* `device-local-state.ts`. Drivers access via:
+	*
+	*   `this.state.battery.sleeping = true`        // patches the battery slice
+	*   `const pct = this.state.battery.percentage` // reads the battery slice
+	*   `this.state.deviceStatus.online = true`     // mirrors `markOnline(true)`
+	*
+	* Adding a new cap with `runtimeState:` automatically extends this
+	* namespace — drivers don't have to declare proxies. Reads return
+	* `undefined` when the slice hasn't been seeded; writes patch via
+	* `runtimeState.patchCapState` and validate against the cap's schema
+	* (so partial writes need the slice to be seeded with the required
+	* fields first — drivers do this on cap registration).
+	*
+	* For caps not exposed in `DeviceLocalState`, drivers can build their
+	* own typed proxy via `this.sliceProxy(cap)`.
+	*/
+	get state() {
+		if (!this._stateProxyCache) {
+			const cache = {};
+			const handler = { get: (_target, key) => {
+				const k = key;
+				if (k in cache) return cache[k];
+				const cap = DEVICE_LOCAL_STATE_CAPS[k];
+				if (!cap) return void 0;
+				const proxy = this.sliceProxy(cap);
+				cache[k] = proxy;
+				return proxy;
+			} };
+			this._stateProxyCache = new Proxy(cache, handler);
+		}
+		return this._stateProxyCache;
+	}
+	_stateProxyCache;
+	config;
+	/**
+	* Per-device runtime state, cap-keyed. Always installed — slices
+	* for individual caps materialise as those caps register their
+	* native providers (`ctx.registerNativeCap`). The cap's own
+	* `runtimeState` schema is the source of truth for the slice
+	* shape; drivers don't redeclare it, they just write through.
+	*
+	* Read: `this.runtimeState.getCapState('battery')` →
+	*   `{percentage, charging, sleeping, lastUpdated}` for any
+	*   provider that registers `batteryCapability`.
+	* Write: `this.runtimeState.setCapState('battery', { … })`.
+	*
+	* Cross-process consumers reach this state through the
+	* `deviceState` cap router (or via cap-specific events the driver
+	* emits — e.g. `battery.onStatusChanged`). The local handle is
+	* accessed in-process by the driver to avoid roundtrips.
+	*/
+	runtimeState;
+	ctx;
+	/**
+	* Operator-organisational location label (room / area / zone).
+	* Read from `ctx.deviceMeta.location`; mutated via
+	* `kernel.devices.setLocation(id, value)`. Free-text — providers
+	* don't interpret it; the UI groups devices by this for filters
+	* like "show me all cameras in Kitchen". `null` when unset.
+	*/
+	location;
+	/**
+	* Soft-disabled flag. When `true`, the device class is still
+	* instantiated and visible in the UI (so the operator can flip
+	* back on without re-adding) but lifecycle hooks (publishToBroker,
+	* alarm-stream subscribe, …) MUST be gated by the driver to skip
+	* work. The `BaseDevice` enforces this by exposing the flag here;
+	* it does NOT mutate cap behaviour automatically — drivers consult
+	* `this.disabled` at the top of their lifecycle methods. Read from
+	* `ctx.deviceMeta.disabled`; mutated via
+	* `kernel.devices.setDisabled(id, value)`.
+	*/
+	disabled;
+	/**
+	* Cached materialised `SourceInfo` — either the value persisted under
+	* `metadata.sourceInfo` at construction time, or a synthetic
+	* `{ id: stableId, system: addonId }` for providers that haven't
+	* migrated yet. Lazily populated on first `sourceInfo` read so the
+	* cost of Zod-parsing the meta blob is paid once per device boot.
+	* Invalidated by `updateSourceInfo()` so providers see the new value
+	* back through the getter without a re-fetch from the meta surface.
+	*/
+	_sourceInfoCache = null;
+	constructor(ctx, schema, options) {
+		this.ctx = ctx;
+		this.id = ctx.id;
+		this.stableId = ctx.stableId;
+		this.type = options.type;
+		if (!ctx.deviceMeta) throw new Error(`BaseDevice constructor: ctx.deviceMeta is required (id=${ctx.id} stableId=${ctx.stableId})`);
+		this.name = ctx.deviceMeta.name;
+		this.location = ctx.deviceMeta.location;
+		this.disabled = ctx.deviceMeta.disabled;
+		this.role = options.role;
+		this.parentDeviceId = ctx.parentDeviceId;
+		const seedData = ctx.persistedConfig ?? {};
+		this.config = DeviceConfig.fromSchema(schema, (data) => ctx.persistConfig(data), seedData, ({ droppedKeys, issues }) => {
+			ctx.logger.warn("Device config recovery: dropping invalid persisted fields", {
+				tags: {
+					deviceId: ctx.id,
+					stableId: ctx.stableId
+				},
+				meta: {
+					droppedKeys: [...droppedKeys],
+					firstIssue: issues[0]?.message ?? null
+				}
+			});
+		});
+		let cachedProxy = null;
+		const writer = async (capName, slice) => {
+			if (!cachedProxy) cachedProxy = ctx.fetchDevice(ctx.id);
+			await (await cachedProxy).deviceState.setCapSlice({
+				capName,
+				slice
+			});
+		};
+		const initial = ctx.initialRuntimeState ?? {};
+		this.runtimeState = DeviceRuntimeState.fromInitial(initial, writer);
+		ctx.bindRuntimeState?.(this.runtimeState);
+		ctx.registerNativeCap?.(deviceStatusCapability, {});
+		const seed = {
+			online: true,
+			lastChangedAt: Date.now()
+		};
+		this.runtimeState.setCapState("device-status", seed);
+		ctx.registerNativeCap?.(featureProbeCapability, {});
+		this.runtimeState.setCapState("feature-probe", {
+			flags: {},
+			deviceType: null,
+			model: null,
+			channelCount: null,
+			lastProbedAt: 0,
+			lastFetchedAt: 0
+		});
+	}
+	deviceActions = /* @__PURE__ */ new Map();
+	/** Declare a device custom action + its typed handler. Idempotent per name. */
+	registerDeviceAction(name, spec, handler) {
+		this.deviceActions.set(name, {
+			spec,
+			handler
+		});
+	}
+	/** Invoke a registered device action. Validates input against the spec. */
+	async runDeviceAction(action, input) {
+		const entry = this.deviceActions.get(action);
+		if (!entry) throw new Error(`unknown device action "${action}" on device ${this.id}`);
+		const parsed = entry.spec.input.parse(input);
+		return entry.handler(parsed);
+	}
+	async removeDevice() {}
+	/**
+	* Set the device's online flag. Called by `BaseDeviceProvider` after
+	* aggregating per-profile stream-broker health, or directly by drivers
+	* that have provider-side liveness signals (e.g. ONVIF heartbeats,
+	* Reolink Baichuan firmware push events). Mirrors the new value into
+	* the `device-status` runtime-state slice so cross-process consumers
+	* pick it up via the standard cap-state channel. Subclasses can
+	* override to gate side effects on the transition.
+	*/
+	markOnline(online) {
+		if (this.online === online) return;
+		const next = {
+			online,
+			lastChangedAt: Date.now()
+		};
+		this.runtimeState.setCapState("device-status", next);
+	}
+	/**
+	* Upstream-system identity + rendering envelope for this device. See
+	* `SourceInfo` for the field contract. Always returns a valid object:
+	* if the persisted `metadata.sourceInfo` blob is absent or fails Zod
+	* validation, falls back to a synthetic `{ id: stableId, system: addonId }`
+	* so providers that haven't migrated keep working without code changes.
+	*
+	* The value is cached after the first read. `updateSourceInfo()`
+	* invalidates the cache so subsequent reads see the new patch. The
+	* returned object is frozen to prevent accidental in-place mutation —
+	* use `updateSourceInfo({ patch })` to change fields.
+	*/
+	get sourceInfo() {
+		if (this._sourceInfoCache) return this._sourceInfoCache;
+		const resolved = extractSourceInfoFromMetadata(this.ctx.deviceMeta.metadata) ?? synthesizeSourceInfo({
+			stableId: this.stableId,
+			addonId: this.ctx.deviceMeta.addonId
+		});
+		this._sourceInfoCache = Object.freeze({ ...resolved });
+		return this._sourceInfoCache;
+	}
+	/**
+	* Convenience accessor for the upstream dispatch key. Equivalent to
+	* `this.sourceInfo.id` — providers use this to keep a
+	* `Map<sourceId, IDevice>` for routing inbound push events.
+	*/
+	get sourceId() {
+		return this.sourceInfo.id;
+	}
+	/**
+	* Patch the device's `SourceInfo`. Shallow-merges `patch` over the
+	* current value, persists the merged result under
+	* `metadata.sourceInfo` via the `device-manager.setMetadata` cap, and
+	* emits `EventCategory.DeviceSourceInfoChanged` for live consumers.
+	*
+	* Safe to call from anywhere in the device's lifetime — the call is
+	* idempotent for `undefined` patch values (ignored) and best-effort
+	* for persistence (a transient device-manager error doesn't unwind
+	* the local cache update, so subsequent reads still see the patch).
+	*
+	* Drivers populate this on adoption + on every metadata change push
+	* from the upstream source. Subscribers (UI, export adapters) react
+	* via the `DeviceSourceInfoChanged` event without polling.
+	*/
+	async updateSourceInfo(patch) {
+		const next = mergeSourceInfo(this.sourceInfo, patch);
+		this._sourceInfoCache = Object.freeze({ ...next });
+		const action = this.ctx.api?.deviceManager?.setMetadata;
+		if (action) try {
+			await action.mutate({
+				deviceId: this.id,
+				patch: { [SOURCE_INFO_METADATA_KEY]: next }
+			});
+		} catch {}
+		this.ctx.eventBus.emit(createEvent("device.source-info-changed", {
+			type: "device",
+			id: this.stableId
+		}, {
+			deviceId: this.id,
+			sourceInfo: next
+		}));
+	}
+	/**
+	* Re-publish the device's current `features` array to the persisted
+	* meta blob. Drivers call this after a probe finishes when the live
+	* `features` getter has gained new flags (e.g. `hasIntercom` flips
+	* to true → `DeviceFeature.TwoWayAudio` joins the list).
+	*
+	* Without this, only the construction-time snapshot is written —
+	* `deviceManager.registerDevice` is invoked once per boot, so probe-
+	* driven additions don't reach the persisted index until the next
+	* server restart, and `getDevice` / `listAll` keep returning the
+	* stale list for forked-worker devices (whose live IDevice instance
+	* is invisible to the hub registry).
+	*
+	* Idempotent: re-calling with the same features just no-ops on the
+	* persisted meta. Best-effort: lookup or write failures are logged
+	* at debug and swallowed — the live `device.features` getter is
+	* still authoritative within this process, so callers never block
+	* device boot on a meta refresh.
+	*/
+	async refreshFeatures() {
+		const action = this.ctx.api?.deviceManager?.registerDevice;
+		if (!action) return;
+		try {
+			await action.mutate({
+				addonId: this.ctx.deviceMeta.addonId,
+				stableId: this.stableId,
+				id: this.id,
+				type: this.type,
+				name: this.name,
+				parentDeviceId: this.parentDeviceId,
+				features: [...this.features],
+				config: {}
+			});
+		} catch (err) {}
+	}
+	/**
+	* Typed read-through to a cap-keyed runtime-state slice. Drivers
+	* call `this.getCapSlice(batteryCapability)` and the return type
+	* is inferred from the cap's `runtimeState` Zod schema — no string
+	* key, no manual generic. Returns `null` when the slice hasn't
+	* been written yet (e.g. driver hasn't seeded battery yet).
+	*/
+	getCapSlice(cap) {
+		return this.runtimeState.getCapState(cap.name) ?? null;
+	}
+	/**
+	* Typed writer to a cap-keyed runtime-state slice. Routes through
+	* the runtime-state writer (validate → persist → emit cap event).
+	* Equivalent to `this.runtimeState.setCapState(cap.name, value)`
+	* but with the cap's `runtimeState` schema enforcing the value
+	* shape at compile time. Mirrors the symmetry of
+	* `getCapSlice` / `setCapSlice` for cross-cap consistency.
+	*/
+	setCapSlice(cap, value) {
+		this.runtimeState.setCapState(cap.name, value);
+	}
+	/**
+	* Field-level read/write proxy over a cap's runtime-state slice.
+	* Drivers that want ergonomic per-field access declare:
+	*
+	* ```ts
+	* protected battery = this.sliceProxy(batteryCapability)
+	* // …
+	* this.battery.sleeping = true        // patches the slice
+	* const charging = this.battery.charging  // reads the slice
+	* ```
+	*
+	* Reads return `undefined` when the slice hasn't been seeded yet
+	* (cap not registered, or seeded but the field is absent). Writes
+	* route through `runtimeState.patchCapState` so the cap's `runtimeState`
+	* schema validates the merged result and the cap event fires.
+	*
+	* Pattern is generic — same shape works for `battery`, `device-status`,
+	* `motion`, `doorbell`, anything with a `runtimeState:` schema. Drivers
+	* declare one proxy per cap they read/write directly.
+	*/
+	sliceProxy(cap) {
+		return new Proxy({}, {
+			get: (_, key) => {
+				return this.runtimeState.getCapState(cap.name)?.[key];
+			},
+			set: (_, key, value) => {
+				this.runtimeState.patchCapState(cap.name, { [key]: value });
+				return true;
+			},
+			has: (_, key) => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				return slice ? key in slice : false;
+			},
+			ownKeys: () => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				return slice ? Object.keys(slice) : [];
+			},
+			getOwnPropertyDescriptor: (_, key) => {
+				const slice = this.runtimeState.getCapState(cap.name);
+				if (!slice || !(key in slice)) return void 0;
+				return {
+					configurable: true,
+					enumerable: true,
+					value: slice[key]
+				};
+			}
+		});
+	}
+	/**
+	* Default empty settings UI. Drivers override this to expose an
+	* editable form in the device-details page. Returning an empty sections
+	* array signals "nothing to contribute" — the aggregator drops the
+	* contribution entirely rather than rendering a blank panel.
+	*/
+	getSettingsUISchema() {
+		return { sections: [] };
+	}
+	/**
+	* Default write path: forward the flat patch directly to storage.
+	* Drivers that project a UI shape different from storage (e.g. `RtspCamera`
+	* exposing `mainStreamUrl`/`subStreamUrl` over `streams[]`) override this
+	* to reshape before `config.setAll`.
+	*/
+	async applySettingsPatch(patch) {
+		await this.config.setAll(patch);
+	}
+	/**
+	* Phase 3 — populate device-scoped state needed by downstream phases
+	* (accessory reconciliation, public `features` array, optional cap
+	* registration). Called ONCE per construction, after register but
+	* before `getAccessoryChildren()`.
+	*
+	* Drivers write the `feature-probe` runtime-state slice via
+	* `this.runtimeState.setCapState('feature-probe', {...})` — flag bag
+	* is open (Reolink writes `hasPtz/hasIntercom`, Hikvision writes
+	* `hasSupplementalLight/hasAlarmIo`, etc).
+	*
+	* Default: nothing to probe → mark the device PROBED (set `lastProbedAt`) so
+	* the kernel treats it as ready immediately. A device that derives its shape
+	* from a spec (a container, or an accessory sensor) rather than from a
+	* hardware probe has no probe to "complete"; without stamping `lastProbedAt`
+	* it would look perpetually un-probed — logging "Initial probe did not
+	* complete" on every boot and spinning a pointless retry chain. Drivers that
+	* DO probe override this and write their own `feature-probe` slice (including
+	* `lastProbedAt`) once their probe actually succeeds.
+	*/
+	async onProbe() {
+		const base = this.runtimeState.getCapState("feature-probe") ?? {
+			flags: {},
+			deviceType: null,
+			model: null,
+			channelCount: null,
+			lastProbedAt: 0,
+			lastFetchedAt: 0
+		};
+		this.runtimeState.setCapState("feature-probe", {
+			...base,
+			lastProbedAt: Date.now()
+		});
+	}
+	/**
+	* Phase 5 — fired after the device + its accessories are registered.
+	* Drivers publish streams to the broker, kick off background tasks,
+	* or subscribe to lib events that need a fully-registered device id.
+	*
+	* Default: no-op.
+	*
+	* RENAMED FROM `onCreated` (which still exists for back-compat in this
+	* pass). The new name reflects the post-probe, post-accessory contract.
+	*/
+	async onActivate() {}
+	/**
+	* Re-run the probe + reconcile accessories + refresh features meta.
+	* Drivers call this when device-side state changes (battery cam wakes,
+	* firmware update, manual operator trigger).
+	*
+	* The kernel injects `_kernelReprobe` on registration so this method
+	* delegates to the same orchestrator that runs the boot-time phase
+	* 3 + 4 sequence. Drivers should NOT override this — they override
+	* `onProbe()` instead.
+	*/
+	async reprobe() {
+		if (this._kernelReprobe) await this._kernelReprobe();
+		else await this.onProbe();
+	}
+	/**
+	* Kernel-injected callback that runs the full post-probe orchestration
+	* (onProbe → registerDevice meta refresh → accessory reconciliation).
+	* Set by `device-cap-proxy.register()`. Drivers should not touch this
+	* directly — call `reprobe()` instead.
+	*/
+	_kernelReprobe;
+	/**
+	* Declare accessory child devices the kernel should auto-spawn
+	* after `onProbe()` resolves. Each spec fully describes one child
+	* — stableId suffix (deterministic per kind for restore-safety),
+	* meta (type / name / location), config (initial blob the child
+	* self-hydrates), and a factory that constructs the concrete
+	* class with whatever closure-captured refs it needs (typically
+	* `this` for the parent reference).
+	*
+	* The kernel handles the rest: allocateDeviceId, persistInitialConfig
+	* (skipped on restore when the row already exists),
+	* persistInitialMeta, createContext, factory invocation, register,
+	* and recursive lifecycle (probe + accessories + activate).
+	*
+	* Implementations should derive children from
+	* `this.runtimeState.getCapState('feature-probe')` (post-probe truth).
+	* Drivers can use the `getProbeFlags()` helper to read the flag bag
+	* with a typed cast.
+	*
+	* Default: no children.
+	*/
+	getAccessoryChildren() {
+		return [];
+	}
+	/**
+	* Read the current feature-probe flag bag with a typed cast. Helper
+	* for `getAccessoryChildren()` and `features` getters that derive
+	* outputs from the probe results.
+	*/
+	getProbeFlags() {
+		return this.runtimeState.getCapState("feature-probe")?.flags ?? {};
+	}
+	/**
+	* Returns true once `onProbe` has completed at least once
+	* (`lastProbedAt > 0`). Drivers gate `getAccessoryChildren()` on this
+	* to avoid spawning stale accessories on a fresh device whose probe
+	* hasn't landed yet.
+	*/
+	hasProbed() {
+		return (this.runtimeState.getCapState("feature-probe")?.lastProbedAt ?? 0) > 0;
+	}
+};
 /**
 * THE derivation. One crop rectangle, one presence verdict — see D52 for why
 * this repo insists a derived value has exactly one implementation.
@@ -47482,4 +48756,4 @@ function enumerateInferenceDevices(hw) {
 	return out;
 }
 //#endregion
-export { evaluateSensorEdge as $, DEVICE_SETTINGS_CONTRIBUTION_METHODS as $t, addonPagesCapability as A, resolveBucketMs as At, coreBlockAddonId as B, snapshotCapability as Bt, STREAM_PROFILE_META as C, EventCategory as Cn, modeMayWrite as Ct, StorageLocationTypeSchema as D, platformProbeCapability as Dt, StorageLocationModeSchema as E, parseStreamParamsFormPatch as Et, backupCapability as F, scopesAllowAddon as Ft, deriveBatteryPresence as G, streamQualityLabel as Gt, coreBlocksCapability as H, storageMigrationCapability as Ht, bareAddonId as I, scopesAllowDeviceCap as It, deviceStatusCapability as J, vectorStoreCapability as Jt, deviceManagerCapability as K, userManagementCapability as Kt, batteryCapability as L, scoreRuntimes as Lt, addonWidgetsCapability as M, resolveLocationMode as Mt, alertsCapability as N, resolveMethodAuth as Nt, StorageMigrationJobSchema as O, procedureAuthKey as Ot, authProviderCapability as P, runtimeStatePolicyFor as Pt, enumerateSchemaFields as Q, DATAPLANE_SECRET_HEADER as Qt, buildStreamParamsConfigSchema as R, settingsStoreCapability as Rt, STORAGE_ACCESS_FALLBACK as S, sleep as Sn, metricsProviderCapability as St, StorageCleanupJobSchema as T, objectInputDeclaresAddonId as Tt, dataStoreProviderCapability as U, storageOccupancyCapability as Ut, coreBlockIdFromAddonId as V, storageCapability as Vt, decodeVectorBase64 as W, storageProviderCapability as Wt, enumerateInferenceDevices as X, errMsg as Xt, doorbellCapability as Y, withLocationMode as Yt, enumerateItemArrayFields as Z, BaseAddon as Zt, REDACTED_SECRET as _, parseJsonObject as _n, logDestinationCapability as _t, CAMERA_SWITCH_ORDER as a, ReadinessTimeoutError as an, isArrayOutputSchema as at, SOURCE_CAPS as b, resolveCapMount as bn, mayReadLocation as bt, CORE_BLOCK_ADDON_PREFIX as c, asNumber as cn, isObjectInput as ct, DeclaredDevices as d, emitDownForOwnedCaps as dn, isVoidInput as dt, DEVICE_STATUS_METHOD as en, evictionPolicyOfLocation as et, DeviceStatusSchema as f, emitReadiness as fn, kebabToCamel as ft, METHOD_ACCESS_MAP as g, nodePin as gn, locationIconKey as gt, LocationIconIdSchema as h, isDeviceConfigCap as hn, localNetworkCapability as ht, BatteryStatusSchema as i, ReadinessRegistry as in, gbToBytes as it, addonSettingsCapability as j, resolveContainerPrimaryChild as jt, UserRecordSchema as k, reducePoints as kt, CoreBlockSchema as l, asString as ln, isSameAddonId as lt, LegacyStorageLocationDefaultSchema as m, hydrateSchema as mn, lifecycleJobSchema as mt, AlertSchema as n, DeviceRole as nn, filesystemBrowseCapability as nt, CAP_NAMES_WITH_STATUS as o, WELL_KNOWN_TAB_MAP as on, isCollectionArrayMethod as ot, LOG_LEVEL_RANK as p, expandCapMethods as pn, legacyModeOf as pt, deviceStateCapability as q, vectorDimFromBase64 as qt, ApiKeyRecordSchema as r, DeviceType as rn, foldSnapshotByFunction as rt, CORE_BLOCKS_ADDON_ID as s, asJsonObject as sn, isLocationEnabled as st, ALL_CAPABILITY_DEFINITIONS as t, DeviceFeature as tn, extractNestedAddonId as tt, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as u, createEvent as un, isSourceCap as ut, RUNTIME_DEFAULTS as v, parseJsonUnknown as vn, logLevelAtMost as vt, ScopedTokenSchema as w, normalizeUnit as wt, SOURCE_DEVICE_TYPES as x, scopeKey as xn, mayWriteToLocation as xt, RecordingStatusSchema as y, readinessKey as yn, looseSchema as yt, collectSecretConfigKeys as z, siteZoneKey as zt };
+export { deviceStateCapability as $, streamQualityLabel as $t, StorageLocationModeSchema as A, resolveCapMount as An, normalizeUnit as At, bareAddonId as B, resolveMethodAuth as Bt, RecordingStatusSchema as C, hydrateSchema as Cn, logDestinationCapability as Ct, STREAM_PROFILE_META as D, parseJsonObject as Dn, mayWriteToLocation as Dt, STORAGE_ACCESS_FALLBACK as E, nodePin as En, mayReadLocation as Et, addonSettingsCapability as F, ptzAutotrackCapability as Ft, coreBlockAddonId as G, settingsStoreCapability as Gt, buildStreamParamsConfigSchema as H, scopesAllowAddon as Ht, addonWidgetsCapability as I, reducePoints as It, dataStoreProviderCapability as J, storageCapability as Jt, coreBlockIdFromAddonId as K, siteZoneKey as Kt, alertsCapability as L, resolveBucketMs as Lt, StorageMigrationJobSchema as M, sleep as Mn, parseStreamParamsFormPatch as Mt, UserRecordSchema as N, EventCategory as Nn, platformProbeCapability as Nt, ScopedTokenSchema as O, parseJsonUnknown as On, metricsProviderCapability as Ot, addonPagesCapability as P, procedureAuthKey as Pt, deviceManagerCapability as Q, streamCatalogCapability as Qt, authProviderCapability as R, resolveContainerPrimaryChild as Rt, RUNTIME_DEFAULTS as S, expandCapMethods as Sn, locationIconKey as St, SOURCE_DEVICE_TYPES as T, isEvent as Tn, looseSchema as Tt, cameraGridLayoutCapability as U, scopesAllowDeviceCap as Ut, batteryCapability as V, runtimeStatePolicyFor as Vt, collectSecretConfigKeys as W, scoreRuntimes as Wt, decodeVectorBase64 as X, storageOccupancyCapability as Xt, declarationOwnerNodeId as Y, storageMigrationCapability as Yt, deriveBatteryPresence as Z, storageProviderCapability as Zt, LOG_LEVEL_RANK as _, asNumber as _n, isVoidInput as _t, BaseDevice as a, buildFfmpegArgs as an, evaluateSensorEdge as at, METHOD_ACCESS_MAP as b, emitDownForOwnedCaps as bn, lifecycleJobSchema as bt, CAP_NAMES_WITH_STATUS as c, DEVICE_SETTINGS_CONTRIBUTION_METHODS as cn, filesystemBrowseCapability as ct, CoreBlockSchema as d, DeviceRole as dn, isArrayOutputSchema as dt, userManagementCapability as en, deviceStatusCapability as et, DEFAULT_FIRST_SIGHTING_FRESHNESS_MS as f, DeviceType as fn, isCollectionArrayMethod as ft, FIRST_LEVEL_MACRO_CLASSES as g, asJsonObject as gn, isSourceCap as gt, DeviceStatusSchema as h, WELL_KNOWN_TAB_MAP as hn, isSameAddonId as ht, ApiKeyRecordSchema as i, errMsg as in, enumerateSchemaFields as it, StorageLocationTypeSchema as j, scopeKey as jn, objectInputDeclaresAddonId as jt, StorageCleanupJobSchema as k, readinessKey as kn, modeMayWrite as kt, CORE_BLOCKS_ADDON_ID as l, DEVICE_STATUS_METHOD as ln, foldSnapshotByFunction as lt, DeclaredDevices as m, ReadinessTimeoutError as mn, isObjectInput as mt, AUDIO_ANALYSIS_CAP_NAME as n, vectorStoreCapability as nn, enumerateInferenceDevices as nt, BatteryStatusSchema as o, BaseAddon as on, evictionPolicyOfLocation as ot, DETECTION_PIPELINE_CAP_NAME as p, ReadinessRegistry as pn, isLocationEnabled as pt, coreBlocksCapability as q, snapshotCapability as qt, AlertSchema as r, withLocationMode as rn, enumerateItemArrayFields as rt, CAMERA_SWITCH_ORDER as s, DATAPLANE_SECRET_HEADER as sn, extractNestedAddonId as st, ALL_CAPABILITY_DEFINITIONS as t, vectorDimFromBase64 as tn, doorbellCapability as tt, CORE_BLOCK_ADDON_PREFIX as u, DeviceFeature as un, gbToBytes as ut, LegacyStorageLocationDefaultSchema as v, asString as vn, kebabToCamel as vt, SOURCE_CAPS as w, isDeviceConfigCap as wn, logLevelAtMost as wt, REDACTED_SECRET as x, emitReadiness as xn, localNetworkCapability as xt, LocationIconIdSchema as y, createEvent as yn, legacyModeOf as yt, backupCapability as z, resolveLocationMode as zt };