@camstack/system 1.2.254 → 1.2.255

package/dist/builtins/autotrack/index.js

@@ -0,0 +1,981 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Cek0wNdY.js");
+const require_dist = require("../../dist-BJj6Akye.js");
+//#region src/builtins/autotrack/autotrack-config.ts
+var DEFAULT_AUTOTRACK_LOOP_CONFIG = {
+	deadZoneFraction: .5,
+	settleZoneFraction: .3,
+	maxCommandsPerSecond: 1 / 3,
+	pulseSettleMs: 400,
+	disappearDelayMs: 15e3,
+	speed: .4,
+	mirrorRefreshMs: 3e4,
+	measurementSummaryMs: 3e4
+};
+//#endregion
+//#region src/builtins/autotrack/autotrack-cameras.ts
+/**
+* What this addon persists per camera, and how the cap's cross-vendor settings
+* become this loop's tuning.
+*
+* ## Why the record lives here and not in the cap's runtime state
+*
+* `ptz-autotrack` declares `durability: 'session'` — its slice MIRRORS a
+* camera's own autotrack config and is re-read on connect. For a native
+* provider that is right: the firmware is the record. For the emulated
+* implementation there is no firmware to re-read, so the slice would come back
+* empty on every restart and a camera the operator armed would come up
+* disarmed, silently. The record is therefore ours, in the addon's own
+* settings, and the cap's `getStatus` reads it.
+*
+* ## One switch, not two (D62, D520)
+*
+* Binding this wrapper to a camera chooses the IMPLEMENTATION — the same act as
+* binding `virtual-doorbell`. `setEnabled` is the switch for the function, and
+* it is the cap's own switch: a camera with firmware autotrack uses its native
+* provider for exactly the same method, so the operator never sees two
+* controls that can disagree.
+*/
+/**
+* The defaults a camera starts from.
+*
+* `disappearDelaySeconds` matches the loop's own default so the two cannot
+* disagree on the day nobody has opened the form. `stopDelaySeconds` is
+* persisted and NOT honoured — see {@link loopConfigFor}.
+*/
+var DEFAULT_CAMERA_RECORD = {
+	enabled: false,
+	settings: {
+		targetType: "",
+		stopDelaySeconds: 30,
+		disappearDelaySeconds: DEFAULT_AUTOTRACK_LOOP_CONFIG.disappearDelayMs / 1e3
+	}
+};
+/**
+* What this implementation can follow, as the cap's target options.
+*
+* A vendor list would be a lie here: the emulated loop follows what the
+* DETECTOR emits, and the detector's first-level macro classes are these
+* three. Reolink's `people` and Hikvision's `human` are vendor words for the
+* same thing and are normalised in {@link targetClassFor} rather than offered.
+*/
+var EMULATED_TARGET_OPTIONS = require_dist.FIRST_LEVEL_MACRO_CLASSES.map((macro) => ({
+	value: macro,
+	label: macro === "person" ? "People" : macro === "vehicle" ? "Vehicles" : "Animals"
+}));
+function isRecordObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseSettings(raw) {
+	if (!isRecordObject(raw)) return DEFAULT_CAMERA_RECORD.settings;
+	const targetType = raw["targetType"];
+	const stopDelaySeconds = raw["stopDelaySeconds"];
+	const disappearDelaySeconds = raw["disappearDelaySeconds"];
+	return {
+		targetType: typeof targetType === "string" ? targetType : DEFAULT_CAMERA_RECORD.settings.targetType,
+		stopDelaySeconds: typeof stopDelaySeconds === "number" && Number.isFinite(stopDelaySeconds) ? stopDelaySeconds : DEFAULT_CAMERA_RECORD.settings.stopDelaySeconds,
+		disappearDelaySeconds: typeof disappearDelaySeconds === "number" && Number.isFinite(disappearDelaySeconds) ? disappearDelaySeconds : DEFAULT_CAMERA_RECORD.settings.disappearDelaySeconds
+	};
+}
+/**
+* Read the persisted blob.
+*
+* A malformed ENTRY falls back to the defaults and keeps its `enabled` flag —
+* it is never dropped. Dropping it would disarm a function the operator armed,
+* which is the one direction this must not fail in; a camera that is not in
+* the blob at all is simply a camera nobody has switched on.
+*/
+function parseCameraRecords(raw) {
+	if (!isRecordObject(raw)) return {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		const deviceId = Number(key);
+		if (!Number.isInteger(deviceId) || deviceId <= 0) continue;
+		if (!isRecordObject(value)) continue;
+		out[deviceId] = {
+			enabled: value["enabled"] === true,
+			settings: parseSettings(value["settings"])
+		};
+	}
+	return out;
+}
+/** Immutable per-camera patch — a NEW map, the previous one untouched. */
+function withCameraPatch(records, deviceId, patch) {
+	const current = records[deviceId] ?? DEFAULT_CAMERA_RECORD;
+	return {
+		...records,
+		[deviceId]: {
+			enabled: patch.enabled ?? current.enabled,
+			settings: {
+				...current.settings,
+				...patch.settings
+			}
+		}
+	};
+}
+/**
+* The detection macro class this camera follows.
+*
+* `''` is the cap's "camera default" and means PERSON here — the class an
+* autotrack is asked for in almost every case, and the one the measurement
+* slice used. A vendor string (`people`, `human`) normalises to the macro it
+* names; anything else falls back to person rather than following nothing,
+* because a loop that silently follows nothing is indistinguishable from one
+* that is broken.
+*/
+function targetClassFor(settings) {
+	const raw = settings.targetType.trim().toLowerCase();
+	if (raw === "") return "person";
+	for (const macro of require_dist.FIRST_LEVEL_MACRO_CLASSES) if (raw === macro) return macro;
+	if (raw === "people" || raw === "human" || raw === "humans") return "person";
+	if (raw === "vehicles" || raw === "car" || raw === "motor_vehicle") return "vehicle";
+	if (raw === "pet" || raw === "pets" || raw === "dog" || raw === "cat") return "animal";
+	return "person";
+}
+/**
+* The loop's config for this camera.
+*
+* Only ONE of the cap's three settings reaches the loop:
+*
+* - `disappearDelaySeconds` → {@link AutotrackLoopConfig.disappearDelayMs}. Same
+*   meaning on both sides: how long a target that stopped appearing is held
+*   before it is released and the head goes home.
+* - `targetType` → the detection class, through {@link targetClassFor}.
+* - `stopDelaySeconds` is persisted and NOT honoured. It means "keep tracking a
+*   STATIONARY target for this long before stopping", and a pulse-based loop
+*   already does nothing while the subject is inside the dead zone — there is
+*   no motion to stop. Storing it and ignoring it is deliberate: the cap is
+*   cross-vendor, a native provider honours it, and dropping it from the
+*   payload would make a camera that switches from native to emulated lose a
+*   setting it had. It is reported back by `getStatus` verbatim, never as a
+*   number this loop acted on.
+*
+* Everything else in the loop config is a TUNING CONSTANT that D520 kept out of
+* the operator surface on purpose (dead zone, settle zone, command ceiling,
+* pulse dead time). They stay constants.
+*/
+function loopConfigFor(settings) {
+	return {
+		...DEFAULT_AUTOTRACK_LOOP_CONFIG,
+		disappearDelayMs: Math.max(0, Math.round(settings.disappearDelaySeconds * 1e3))
+	};
+}
+/** The cap's status for one camera. */
+function statusFor(record, lastChangedAt) {
+	return {
+		enabled: record.enabled,
+		lastChangedAt,
+		currentSettings: record.settings,
+		supportedTargetTypes: EMULATED_TARGET_OPTIONS
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/autotrack-decision.ts
+var INITIAL_AUTOTRACK_LOOP_STATE = {
+	correctingX: false,
+	correctingY: false,
+	lastCommandAtMs: null,
+	homeIssued: false
+};
+/**
+* One axis of the hysteresis.
+*
+* Outside the dead zone a correction STARTS; once started it continues until
+* the subject is inside the tighter settle zone, and then it stops — short of
+* the centre, on purpose. Aiming at the centre with an estimated gain
+* overshoots, and an overshoot reverses the sign on the next frame.
+*/
+function stepAxis(error, correcting, config) {
+	const deadHalf = config.deadZoneFraction / 2;
+	const settleHalf = config.settleZoneFraction / 2;
+	const magnitude = Math.abs(error);
+	if (!(correcting ? magnitude > settleHalf : magnitude > deadHalf)) return {
+		step: 0,
+		correcting: false
+	};
+	return {
+		step: error > 0 ? 1 : -1,
+		correcting: true
+	};
+}
+function decideAutotrack(state, input) {
+	const hold = (reason, next) => ({
+		state: next,
+		decision: {
+			action: "hold",
+			reason
+		}
+	});
+	if (!input.armed) return hold("disarmed", state);
+	if (input.target === null) {
+		const idle = {
+			...state,
+			correctingX: false,
+			correctingY: false
+		};
+		if (input.targetLastSeenAtMs === null) return hold("no-target", idle);
+		if (input.nowMs - input.targetLastSeenAtMs < input.config.disappearDelayMs) return hold("target-absent", idle);
+		if (state.homeIssued) return hold("home-already-issued", idle);
+		return {
+			state: {
+				...idle,
+				homeIssued: true,
+				lastCommandAtMs: input.nowMs
+			},
+			decision: {
+				action: "home",
+				reason: "target-gone"
+			}
+		};
+	}
+	const present = {
+		...state,
+		homeIssued: false
+	};
+	if (input.target.error === null) return hold("frame-geometry-unknown", present);
+	const x = stepAxis(input.target.error.x, state.correctingX, input.config);
+	const y = stepAxis(input.target.error.y, state.correctingY, input.config);
+	const tiltStep = y.step === 0 ? 0 : y.step > 0 ? -1 : 1;
+	const aimed = {
+		...present,
+		correctingX: x.correcting,
+		correctingY: y.correcting
+	};
+	if (x.step === 0 && y.step === 0) return hold(state.correctingX || state.correctingY ? "settled" : "inside-dead-zone", aimed);
+	if (input.nativeAutotrack === "enabled") return hold("native-autotrack-enabled", aimed);
+	if (input.nativeAutotrack === "unknown") return hold("native-autotrack-unknown", aimed);
+	const impulseMs = input.moveImpulseMs;
+	if (impulseMs === null) return hold("impulse-duration-unknown", aimed);
+	const lastCommandAtMs = state.lastCommandAtMs;
+	if (lastCommandAtMs !== null) {
+		const sinceMs = input.nowMs - lastCommandAtMs;
+		if (sinceMs < impulseMs + input.config.pulseSettleMs) return hold("pulse-dead-time", aimed);
+		if (sinceMs < 1e3 / input.config.maxCommandsPerSecond) return hold("rate-limited", aimed);
+	}
+	return {
+		state: {
+			...aimed,
+			lastCommandAtMs: input.nowMs
+		},
+		decision: {
+			action: "pulse",
+			pan: x.step,
+			tilt: tiltStep,
+			speed: input.config.speed
+		}
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/frame-error.ts
+function isPositiveFinite(value) {
+	return Number.isFinite(value) && value > 0;
+}
+function isFiniteBox(box) {
+	return Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height);
+}
+/**
+* Error of one subject box against the frame centre.
+*
+* `null` when the frame geometry or the box is unreadable — never a centred
+* zero (D393).
+*/
+function computeNormalizedError(box, geometry) {
+	if (!isPositiveFinite(geometry.frameWidth) || !isPositiveFinite(geometry.frameHeight)) return null;
+	if (!isFiniteBox(box)) return null;
+	const centreX = box.x + box.width / 2;
+	const centreY = box.y + box.height / 2;
+	return {
+		x: centreX / geometry.frameWidth - .5,
+		y: centreY / geometry.frameHeight - .5
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/frame-measurements.ts
+var LATENCY_BUCKET_BOUNDS_MS = [
+	50,
+	100,
+	200,
+	400,
+	800,
+	1600,
+	3200
+];
+var INITIAL_LATENCY_TALLY = {
+	frames: 0,
+	sumMs: 0,
+	minMs: null,
+	maxMs: null,
+	bucketBoundsMs: LATENCY_BUCKET_BOUNDS_MS,
+	bucketCounts: LATENCY_BUCKET_BOUNDS_MS.map(() => 0).concat(0),
+	negativeAgeFrames: 0
+};
+function recordLatency(tally, latencyMs) {
+	if (!Number.isFinite(latencyMs)) return tally;
+	let bucket = tally.bucketBoundsMs.findIndex((bound) => latencyMs <= bound);
+	if (bucket < 0) bucket = tally.bucketBoundsMs.length;
+	const bucketCounts = tally.bucketCounts.map((count, i) => i === bucket ? count + 1 : count);
+	return {
+		frames: tally.frames + 1,
+		sumMs: tally.sumMs + latencyMs,
+		minMs: tally.minMs === null ? latencyMs : Math.min(tally.minMs, latencyMs),
+		maxMs: tally.maxMs === null ? latencyMs : Math.max(tally.maxMs, latencyMs),
+		bucketBoundsMs: tally.bucketBoundsMs,
+		bucketCounts,
+		negativeAgeFrames: tally.negativeAgeFrames + (latencyMs < 0 ? 1 : 0)
+	};
+}
+var INITIAL_PRESENCE_TALLY = {
+	framesWithTarget: 0,
+	absentFrames: 0,
+	currentGapFrames: 0,
+	maxGapFrames: 0,
+	gapRunHistogram: Array.from({ length: 9 }, () => 0)
+};
+/**
+* Count one frame on which a target was held.
+*
+* `present` is "the held track carried a box on THIS frame". A closing gap is
+* binned at the moment it closes, which is why the open gap is reported
+* separately (`currentGapFrames`) instead of being counted twice.
+*/
+function recordPresence(tally, present) {
+	if (present) {
+		if (tally.currentGapFrames === 0) return {
+			...tally,
+			framesWithTarget: tally.framesWithTarget + 1
+		};
+		const slot = Math.min(tally.currentGapFrames, 8) - 1;
+		const index = tally.currentGapFrames > 8 ? 8 : slot;
+		return {
+			framesWithTarget: tally.framesWithTarget + 1,
+			absentFrames: tally.absentFrames,
+			currentGapFrames: 0,
+			maxGapFrames: tally.maxGapFrames,
+			gapRunHistogram: tally.gapRunHistogram.map((n, i) => i === index ? n + 1 : n)
+		};
+	}
+	const currentGapFrames = tally.currentGapFrames + 1;
+	return {
+		framesWithTarget: tally.framesWithTarget + 1,
+		absentFrames: tally.absentFrames + 1,
+		currentGapFrames,
+		maxGapFrames: Math.max(tally.maxGapFrames, currentGapFrames),
+		gapRunHistogram: tally.gapRunHistogram
+	};
+}
+function summarize(latency, presence) {
+	return {
+		frames: latency.frames,
+		latencyMeanMs: latency.frames === 0 ? null : latency.sumMs / latency.frames,
+		latencyMinMs: latency.minMs,
+		latencyMaxMs: latency.maxMs,
+		latencyBucketsMs: latency.bucketBoundsMs,
+		latencyBucketCounts: latency.bucketCounts,
+		negativeAgeFrames: latency.negativeAgeFrames,
+		framesWithTarget: presence.framesWithTarget,
+		absentFrames: presence.absentFrames,
+		absentFraction: presence.framesWithTarget === 0 ? null : presence.absentFrames / presence.framesWithTarget,
+		maxGapFrames: presence.maxGapFrames,
+		openGapFrames: presence.currentGapFrames,
+		gapRunHistogram: presence.gapRunHistogram
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/ptz-mirror.ts
+var INITIAL_PTZ_MIRROR = {
+	moveImpulseMs: null,
+	nativeAutotrack: "unknown",
+	lastRefreshAtMs: null,
+	lastError: null,
+	consecutiveFailures: 0
+};
+function applyMirrorRefresh(mirror, outcome, nowMs) {
+	if (outcome.kind === "failed") return {
+		...mirror,
+		lastError: outcome.error,
+		consecutiveFailures: mirror.consecutiveFailures + 1
+	};
+	return {
+		moveImpulseMs: outcome.moveImpulseMs ?? mirror.moveImpulseMs,
+		nativeAutotrack: outcome.nativeAutotrack,
+		lastRefreshAtMs: nowMs,
+		lastError: null,
+		consecutiveFailures: 0
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/target-selection.ts
+var INITIAL_TARGET_SELECTION_STATE = {
+	trackId: null,
+	lastSeenAtMs: null
+};
+/** Largest box first; `trackId` breaks a tie so the choice is deterministic
+*  rather than dependent on detector ordering. */
+function pickFirst(candidates) {
+	let best = null;
+	for (const c of candidates) {
+		if (best === null || c.areaPx > best.areaPx) {
+			best = c;
+			continue;
+		}
+		if (c.areaPx === best.areaPx && c.trackId < best.trackId) best = c;
+	}
+	return best;
+}
+function selectTarget(state, input) {
+	const held = state.trackId;
+	if (held !== null) {
+		if (input.candidates.some((c) => c.trackId === held)) return {
+			state: {
+				trackId: held,
+				lastSeenAtMs: input.nowMs
+			},
+			trackId: held,
+			present: true,
+			reason: "held"
+		};
+		const lastSeen = state.lastSeenAtMs;
+		if ((lastSeen === null ? Number.POSITIVE_INFINITY : input.nowMs - lastSeen) < input.disappearDelayMs) return {
+			state,
+			trackId: held,
+			present: false,
+			reason: "held-absent"
+		};
+		const replacement = pickFirst(input.candidates);
+		if (replacement === null) return {
+			state: INITIAL_TARGET_SELECTION_STATE,
+			trackId: null,
+			present: false,
+			reason: "released"
+		};
+		return {
+			state: {
+				trackId: replacement.trackId,
+				lastSeenAtMs: input.nowMs
+			},
+			trackId: replacement.trackId,
+			present: true,
+			reason: "switched"
+		};
+	}
+	const picked = pickFirst(input.candidates);
+	if (picked === null) return {
+		state: INITIAL_TARGET_SELECTION_STATE,
+		trackId: null,
+		present: false,
+		reason: "idle"
+	};
+	return {
+		state: {
+			trackId: picked.trackId,
+			lastSeenAtMs: input.nowMs
+		},
+		trackId: picked.trackId,
+		present: true,
+		reason: "acquired"
+	};
+}
+//#endregion
+//#region src/builtins/autotrack/autotrack-loop.ts
+/**
+* Candidates of the configured class on this frame.
+*
+* A detection counts only when it carries a `track` — `buildOverlayDetections`
+* attaches one exactly to the boxes a tracked entry was ASSOCIATED with on this
+* frame, so this set is the observed-and-tracked set and nothing else.
+*/
+function candidatesFromFrame(detections, targetClass) {
+	const out = [];
+	for (const det of detections) {
+		if (det.kind !== "first-level") continue;
+		if (det.macroClass !== targetClass) continue;
+		const trackId = det.track?.trackId;
+		if (trackId === void 0) continue;
+		out.push({
+			trackId,
+			areaPx: Math.max(0, det.bbox.width) * Math.max(0, det.bbox.height)
+		});
+	}
+	return out;
+}
+var AutotrackLoop = class {
+	deps;
+	selection = INITIAL_TARGET_SELECTION_STATE;
+	loopState = INITIAL_AUTOTRACK_LOOP_STATE;
+	mirror = INITIAL_PTZ_MIRROR;
+	latency = INITIAL_LATENCY_TALLY;
+	presence = INITIAL_PRESENCE_TALLY;
+	lastFrameAtMs = null;
+	lastSummaryAtMs = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Read-only view of the mirror, for the addon's startup log. */
+	get ptzMirror() {
+		return this.mirror;
+	}
+	/** Fold one refresh outcome into the mirror. Called by the TIMER, never from
+	*  {@link onFrame}. */
+	applyMirror(outcome) {
+		const nowMs = this.deps.now();
+		this.mirror = applyMirrorRefresh(this.mirror, outcome, nowMs);
+		if (outcome.kind === "failed") {
+			this.deps.logger.warn("autotrack mirror refresh failed", {
+				tags: { deviceId: this.deps.deviceId },
+				meta: {
+					error: outcome.error,
+					consecutiveFailures: this.mirror.consecutiveFailures,
+					moveImpulseMs: this.mirror.moveImpulseMs,
+					nativeAutotrack: this.mirror.nativeAutotrack
+				}
+			});
+			return;
+		}
+		this.deps.logger.debug("autotrack mirror refreshed", {
+			tags: { deviceId: this.deps.deviceId },
+			meta: {
+				moveImpulseMs: this.mirror.moveImpulseMs,
+				nativeAutotrack: this.mirror.nativeAutotrack
+			}
+		});
+	}
+	/** One analysed frame. Measures first, then decides. */
+	async onFrame(frame) {
+		if (frame.deviceId !== this.deps.deviceId) return;
+		const nowMs = this.deps.now();
+		this.lastFrameAtMs = nowMs;
+		const busLatencyMs = nowMs - frame.timestamp;
+		this.latency = recordLatency(this.latency, busLatencyMs);
+		const candidates = candidatesFromFrame(frame.detections, this.deps.targetClass);
+		const selected = selectTarget(this.selection, {
+			nowMs,
+			candidates,
+			disappearDelayMs: this.deps.config.disappearDelayMs
+		});
+		this.selection = selected.state;
+		if (selected.trackId !== null) this.presence = recordPresence(this.presence, selected.present);
+		let error = null;
+		if (selected.present && selected.trackId !== null) {
+			const det = frame.detections.find((d) => d.track?.trackId === selected.trackId);
+			if (det !== void 0) error = computeNormalizedError(det.bbox, {
+				frameWidth: frame.frameWidth,
+				frameHeight: frame.frameHeight
+			});
+		}
+		const result = decideAutotrack(this.loopState, {
+			nowMs,
+			armed: this.deps.armed,
+			target: selected.present && selected.trackId !== null ? {
+				trackId: selected.trackId,
+				error
+			} : null,
+			targetLastSeenAtMs: this.selection.lastSeenAtMs,
+			moveImpulseMs: this.mirror.moveImpulseMs,
+			nativeAutotrack: this.mirror.nativeAutotrack,
+			config: this.deps.config
+		});
+		this.loopState = result.state;
+		this.logDecision(result.decision, {
+			busLatencyMs,
+			candidates: candidates.length,
+			trackId: selected.trackId,
+			present: selected.present,
+			selection: selected.reason,
+			error,
+			source: "frame"
+		});
+		await this.dispatch(result.decision);
+		this.maybeSummarize(nowMs);
+	}
+	/**
+	* Off-event-path tick: the silence watchdog.
+	*
+	* Evaluates the SAME disappear delay against the time since the last frame.
+	* A stream that died is a target that is gone, and the head goes home —
+	* which is also the only thing that would otherwise never happen, because
+	* every other release is driven by a frame arriving.
+	*/
+	async tick() {
+		const nowMs = this.deps.now();
+		const lastFrameAtMs = this.lastFrameAtMs;
+		if (lastFrameAtMs === null) return;
+		const silentForMs = nowMs - lastFrameAtMs;
+		if (silentForMs < this.deps.config.disappearDelayMs) return;
+		const heldTrackId = this.selection.trackId;
+		if (heldTrackId === null) return;
+		this.selection = INITIAL_TARGET_SELECTION_STATE;
+		const result = decideAutotrack(this.loopState, {
+			nowMs,
+			armed: this.deps.armed,
+			target: null,
+			targetLastSeenAtMs: lastFrameAtMs,
+			moveImpulseMs: this.mirror.moveImpulseMs,
+			nativeAutotrack: this.mirror.nativeAutotrack,
+			config: this.deps.config
+		});
+		this.loopState = result.state;
+		this.deps.logger.warn("autotrack frame silence", {
+			tags: { deviceId: this.deps.deviceId },
+			meta: {
+				silentForMs,
+				disappearDelayMs: this.deps.config.disappearDelayMs,
+				heldTrackId
+			}
+		});
+		this.logDecision(result.decision, {
+			busLatencyMs: null,
+			candidates: 0,
+			trackId: heldTrackId,
+			present: false,
+			selection: "silence-released",
+			error: null,
+			source: "tick"
+		});
+		await this.dispatch(result.decision);
+	}
+	/** Emit the aggregates now, whatever the schedule says. Used at shutdown so
+	*  a short run still reports what it measured. */
+	logSummary() {
+		const meta = { ...summarize(this.latency, this.presence) };
+		this.deps.logger.info("autotrack measurements", {
+			tags: { deviceId: this.deps.deviceId },
+			meta
+		});
+	}
+	maybeSummarize(nowMs) {
+		const last = this.lastSummaryAtMs;
+		if (last !== null && nowMs - last < this.deps.config.measurementSummaryMs) return;
+		this.lastSummaryAtMs = nowMs;
+		this.logSummary();
+	}
+	async dispatch(decision) {
+		if (decision.action === "hold") return;
+		try {
+			if (decision.action === "home") {
+				await this.deps.commands.goHome(this.deps.deviceId);
+				return;
+			}
+			await this.deps.commands.pulse({
+				deviceId: this.deps.deviceId,
+				pan: decision.pan,
+				tilt: decision.tilt,
+				speed: decision.speed
+			});
+		} catch (err) {
+			this.deps.logger.warn("autotrack command failed", {
+				tags: { deviceId: this.deps.deviceId },
+				meta: {
+					action: decision.action,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+	}
+	logDecision(decision, context) {
+		const meta = {
+			source: context.source,
+			busLatencyMs: context.busLatencyMs,
+			candidates: context.candidates,
+			trackId: context.trackId,
+			trackPresent: context.present,
+			selection: context.selection,
+			errorX: context.error === null ? null : round3(context.error.x),
+			errorY: context.error === null ? null : round3(context.error.y),
+			action: decision.action,
+			reason: decision.action === "pulse" ? null : decision.reason,
+			pan: decision.action === "pulse" ? decision.pan : null,
+			tilt: decision.action === "pulse" ? decision.tilt : null,
+			moveImpulseMs: this.mirror.moveImpulseMs,
+			nativeAutotrack: this.mirror.nativeAutotrack
+		};
+		if (decision.action === "hold") {
+			this.deps.logger.debug("autotrack hold", {
+				tags: { deviceId: this.deps.deviceId },
+				meta
+			});
+			return;
+		}
+		this.deps.logger.info("autotrack command", {
+			tags: { deviceId: this.deps.deviceId },
+			meta
+		});
+	}
+};
+function round3(value) {
+	return Math.round(value * 1e3) / 1e3;
+}
+//#endregion
+//#region src/builtins/autotrack/autotrack.addon.ts
+/** How often the silence watchdog runs. Small relative to the disappear delay
+*  it enforces — the delay is the budget, this is only the resolution. */
+var WATCHDOG_INTERVAL_MS = 5e3;
+var AutotrackAddon = class extends require_dist.BaseAddon {
+	records = {};
+	sessions = /* @__PURE__ */ new Map();
+	/** Cameras whose `ptz-autotrack` binding names THIS addon, last time we read. */
+	bound = /* @__PURE__ */ new Set();
+	/**
+	* Cameras that ALSO have a `ptz-autotrack` provider that is not us.
+	*
+	* This is the only way to ask about a firmware autotrack without asking
+	* ourselves: on a camera where our wrapper is the binding, `ptzAutotrack.
+	* getStatus` resolves to THIS addon and returns our own switch — so a loop
+	* that read it would see `enabled: true` the moment the operator turned it
+	* on, conclude the firmware was driving the head, and refuse to move. A
+	* self-deadlock that would have looked exactly like the safety gate working.
+	*/
+	foreignProvider = /* @__PURE__ */ new Set();
+	lastChangedAt = /* @__PURE__ */ new Map();
+	unsubscribeFrames = null;
+	unsubscribeBindings = null;
+	mirrorTimer = null;
+	watchdogTimer = null;
+	constructor() {
+		super({ cameras: {} });
+	}
+	async onInitialize() {
+		this.records = parseCameraRecords(this.config.cameras);
+		this.unsubscribeFrames = this.ctx.eventBus.subscribe({ category: require_dist.EventCategory.PipelineAnalyticsFrameTracked }, (event) => {
+			if (!require_dist.isEvent(event, require_dist.EventCategory.PipelineAnalyticsFrameTracked)) return;
+			const session = this.sessions.get(event.data.deviceId);
+			if (session === void 0) return;
+			session.loop.onFrame({
+				deviceId: event.data.deviceId,
+				timestamp: event.data.timestamp,
+				frameWidth: event.data.frameWidth,
+				frameHeight: event.data.frameHeight,
+				detections: event.data.detections
+			}).catch((err) => {
+				this.ctx.logger.warn("autotrack frame handling failed", {
+					tags: { deviceId: event.data.deviceId },
+					meta: { error: require_dist.errMsg(err) }
+				});
+			});
+		});
+		this.unsubscribeBindings = this.ctx.eventBus.subscribe({ category: require_dist.EventCategory.DeviceBindingsChanged }, () => {
+			this.refreshBindings().catch(() => void 0);
+		});
+		this.mirrorTimer = setInterval(() => {
+			this.refreshEverything();
+		}, DEFAULT_AUTOTRACK_LOOP_CONFIG.mirrorRefreshMs);
+		this.watchdogTimer = setInterval(() => {
+			for (const session of this.sessions.values()) session.loop.tick().catch((err) => {
+				this.ctx.logger.warn("autotrack watchdog failed", {
+					tags: { deviceId: session.deviceId },
+					meta: { error: require_dist.errMsg(err) }
+				});
+			});
+		}, WATCHDOG_INTERVAL_MS);
+		await this.refreshEverything();
+		const provider = {
+			getStatus: async ({ deviceId }) => this.statusOf(deviceId),
+			setEnabled: async ({ deviceId, enabled }) => {
+				await this.patchCamera(deviceId, { enabled });
+			},
+			getSettings: async ({ deviceId }) => this.recordOf(deviceId).settings,
+			setSettings: async ({ deviceId, settings }) => {
+				await this.patchCamera(deviceId, { settings });
+			}
+		};
+		this.ctx.logger.info("autotrack ready", { meta: {
+			cameras: Object.keys(this.records).length,
+			running: this.sessions.size
+		} });
+		return { providers: [{
+			capability: require_dist.ptzAutotrackCapability,
+			provider
+		}] };
+	}
+	async onShutdown() {
+		if (this.mirrorTimer !== null) clearInterval(this.mirrorTimer);
+		if (this.watchdogTimer !== null) clearInterval(this.watchdogTimer);
+		this.mirrorTimer = null;
+		this.watchdogTimer = null;
+		this.unsubscribeFrames?.();
+		this.unsubscribeBindings?.();
+		this.unsubscribeFrames = null;
+		this.unsubscribeBindings = null;
+		for (const session of this.sessions.values()) session.loop.logSummary();
+		this.sessions.clear();
+	}
+	async onConfigChanged() {
+		this.records = parseCameraRecords(this.config.cameras);
+		await this.reconcileSessions();
+	}
+	recordOf(deviceId) {
+		return this.records[deviceId] ?? DEFAULT_CAMERA_RECORD;
+	}
+	statusOf(deviceId) {
+		return statusFor(this.recordOf(deviceId), this.lastChangedAt.get(deviceId) ?? 0);
+	}
+	async patchCamera(deviceId, patch) {
+		const before = this.recordOf(deviceId).enabled;
+		this.records = withCameraPatch(this.records, deviceId, patch);
+		if (before !== this.recordOf(deviceId).enabled) this.lastChangedAt.set(deviceId, Date.now());
+		await this.updateGlobalSettings({ cameras: this.serialiseRecords() });
+		await this.reconcileSessions();
+	}
+	serialiseRecords() {
+		const out = {};
+		for (const [deviceId, record] of Object.entries(this.records)) out[deviceId] = {
+			enabled: record.enabled,
+			settings: record.settings
+		};
+		return out;
+	}
+	/** Bindings first, then sessions: a session must never outlive its binding. */
+	async refreshEverything() {
+		await this.refreshBindings();
+		await this.reconcileSessions();
+		for (const session of this.sessions.values()) await this.refreshMirror(session);
+	}
+	/**
+	* Which cameras have this addon bound as their `ptz-autotrack` provider.
+	*
+	* Only cameras the operator has a record for are asked about: a wrapper that
+	* enumerated every camera on every refresh would walk the whole fleet to
+	* learn nothing about the ones nobody switched on.
+	*
+	* A read that FAILS leaves the previous answer standing (D49) — a transient
+	* store blip must not stop a running loop. A read that SUCCEEDS and omits us
+	* is believed immediately: unlike a doorbell press, the cost of erring open
+	* here is a head that keeps moving after the operator unbound it.
+	*/
+	async refreshBindings() {
+		const next = /* @__PURE__ */ new Set();
+		const foreign = new Set(this.foreignProvider);
+		const me = require_dist.bareAddonId(this.ctx.id);
+		for (const key of Object.keys(this.records)) {
+			const deviceId = Number(key);
+			if (!Number.isInteger(deviceId)) continue;
+			try {
+				const { entries } = await this.ctx.api.deviceManager.getBindings.query({ deviceId });
+				const autotrackEntries = entries.filter((entry) => entry.capName === require_dist.ptzAutotrackCapability.name);
+				if (autotrackEntries.some((entry) => require_dist.bareAddonId(entry.providerAddonId) === me)) next.add(deviceId);
+				if (autotrackEntries.some((entry) => require_dist.bareAddonId(entry.providerAddonId) !== me)) foreign.add(deviceId);
+				else foreign.delete(deviceId);
+			} catch (err) {
+				if (this.bound.has(deviceId)) next.add(deviceId);
+				this.ctx.logger.debug("autotrack: could not read bindings", {
+					tags: { deviceId },
+					meta: { error: require_dist.errMsg(err) }
+				});
+			}
+		}
+		this.bound = next;
+		this.foreignProvider = foreign;
+	}
+	/** Start a loop for every camera that is bound AND switched on; stop the rest. */
+	async reconcileSessions() {
+		for (const [key, record] of Object.entries(this.records)) {
+			const deviceId = Number(key);
+			const shouldRun = record.enabled && this.bound.has(deviceId);
+			const running = this.sessions.get(deviceId);
+			if (shouldRun && running === void 0) {
+				this.startSession(deviceId, record);
+				continue;
+			}
+			if (!shouldRun && running !== void 0) this.stopSession(deviceId, record.enabled ? "unbound" : "switched-off");
+		}
+		for (const deviceId of this.sessions.keys()) if (this.records[deviceId] === void 0) this.stopSession(deviceId, "record-gone");
+	}
+	startSession(deviceId, record) {
+		const config = loopConfigFor(record.settings);
+		const targetClass = targetClassFor(record.settings);
+		const loop = new AutotrackLoop({
+			deviceId,
+			targetClass,
+			armed: true,
+			config,
+			logger: this.ctx.logger,
+			commands: {
+				pulse: (command) => this.ctx.api.ptz.move.mutate({
+					deviceId: command.deviceId,
+					pan: command.pan,
+					tilt: command.tilt,
+					speed: command.speed
+				}),
+				goHome: (target) => this.ctx.api.ptz.goHome.mutate({ deviceId: target })
+			},
+			now: () => Date.now()
+		});
+		this.sessions.set(deviceId, {
+			loop,
+			deviceId
+		});
+		this.refreshMirror({
+			loop,
+			deviceId
+		});
+		this.ctx.logger.info("autotrack following", {
+			tags: { deviceId },
+			meta: {
+				targetClass,
+				deadZoneFraction: config.deadZoneFraction,
+				settleZoneFraction: config.settleZoneFraction,
+				maxCommandsPerSecond: config.maxCommandsPerSecond,
+				disappearDelayMs: config.disappearDelayMs
+			}
+		});
+		this.ctx.logger.warn("autotrack ON: this camera must not be driven by anyone else", { tags: { deviceId } });
+	}
+	stopSession(deviceId, reason) {
+		const session = this.sessions.get(deviceId);
+		if (session === void 0) return;
+		session.loop.logSummary();
+		this.sessions.delete(deviceId);
+		this.ctx.logger.info("autotrack stopped following", {
+			tags: { deviceId },
+			meta: { reason }
+		});
+	}
+	/**
+	* One off-event-path refresh of a camera's mirror.
+	*
+	* Two reads, and either one failing fails the whole refresh: a mirror half
+	* from now and half from twenty minutes ago is worse than one that says it
+	* is stale. The previous answers stand (D49).
+	*/
+	async refreshMirror(session) {
+		try {
+			const options = await this.ctx.api.ptz.getOptions.query({ deviceId: session.deviceId });
+			const nativeAutotrack = await this.readNativeAutotrack(session.deviceId);
+			session.loop.applyMirror({
+				kind: "read",
+				moveImpulseMs: options.moveImpulseMs,
+				nativeAutotrack
+			});
+		} catch (err) {
+			session.loop.applyMirror({
+				kind: "failed",
+				error: require_dist.errMsg(err)
+			});
+			this.ctx.logger.warn("autotrack mirror refresh failed — the loop holds its last answers", {
+				tags: { deviceId: session.deviceId },
+				meta: { error: require_dist.errMsg(err) }
+			});
+		}
+	}
+	/**
+	* Is the camera's OWN autotrack on?
+	*
+	* `null` when the camera has no native autotrack at all — which is the case
+	* this addon exists for, and is NOT an error. A camera that HAS one and has
+	* it armed makes this loop refuse: two implementations driving one head is
+	* the thing the single-switch rule exists to prevent (D62).
+	*/
+	async readNativeAutotrack(deviceId) {
+		if (!this.foreignProvider.has(deviceId)) return "absent";
+		try {
+			return (await this.ctx.api.ptzAutotrack.getStatus.query({ deviceId })).enabled ? "enabled" : "disabled";
+		} catch {
+			return "unknown";
+		}
+	}
+};
+//#endregion
+exports.AutotrackAddon = AutotrackAddon;
+exports.default = AutotrackAddon;