@camstack/addon-post-analysis 1.1.37 → 1.1.38

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-CThBV9dq.js");
+const require_dist = require("../dist-_h-RM5Lr.js");
 let node_crypto = require("node:crypto");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -1125,8 +1125,29 @@ var DEFAULT_TRACKER_CONFIG = {
 	rescueIouThreshold: .1,
 	rescueCentroidFactor: .75,
 	resurrectionWindowMs: 8e3,
-	stationarySpeedPx: 2
+	stationarySpeedPx: 2,
+	dedupEnabled: true,
+	dedupSpawnIou: .6,
+	dedupMergeIou: .6,
+	dedupMergeFrames: 5,
+	personAnimalDedup: true,
+	animalOverPersonMaxScore: .6,
+	animalOverPersonIou: .2,
+	classVotingEnabled: true,
+	classVoteMinFraction: .5,
+	perClassMinScoreEnabled: true,
+	classMinScores: {
+		animal: .45,
+		vehicle: .45
+	},
+	confirmBypassEnabled: false,
+	confirmBypassScore: .9
 };
+/** Macro-classes the duplicate resolver may collapse across (people in
+*  non-upright poses misdetected as animals). Any other cross-class pair is
+*  NEVER a duplicate. */
+var PERSON_CLASS = "person";
+var ANIMAL_CLASS = "animal";
 var MAX_PATH_LENGTH = 300;
 function clamp(value, min, max) {
 	return Math.max(min, Math.min(max, value));
@@ -1149,16 +1170,102 @@ function containment(inner, outer) {
 	const innerArea = inner.w * inner.h;
 	return innerArea > 0 ? iw * ih / innerArea : 0;
 }
-var SortTracker = class {
+var SortTracker = class SortTracker {
 	config;
 	tracks = [];
 	lostTracks = [];
+	/**
+	* Consecutive-frame overlap streak per unordered live-track pair
+	* (`idA|idB`, ids sorted). Drives the sustained-overlap merge: a pair is
+	* merged only once its streak reaches `dedupMergeFrames`. Entries reset the
+	* moment the pair stops overlapping and are pruned when either track dies.
+	*/
+	dupStreaks = /* @__PURE__ */ new Map();
 	constructor(config = {}) {
 		this.config = {
 			...DEFAULT_TRACKER_CONFIG,
 			...config
 		};
 	}
+	/** Whether two macro-classes may be collapsed as the SAME subject. Same class
+	*  always; the {person,animal} pair only when `personAnimalDedup` is on. */
+	dedupCompatible(a, b) {
+		if (a === b) return true;
+		if (!this.config.personAnimalDedup) return false;
+		return a === PERSON_CLASS && b === ANIMAL_CLASS || a === ANIMAL_CLASS && b === PERSON_CLASS;
+	}
+	/** Unordered, stable key for a track pair (UUIDs never contain `|`). */
+	static pairKey(a, b) {
+		return a < b ? `${a}|${b}` : `${b}|${a}`;
+	}
+	/**
+	* True when spawning a fresh track for `det` would duplicate an already-live
+	* track: (a) it overlaps a concurrent compatible-class track by
+	* `dedupSpawnIou`, or (b) it is a low-confidence `animal` sitting on a
+	* concurrent `person` track (person-in-odd-pose false animal). `live` is the
+	* set of tracks already surviving this frame (matched, coasting, resurrected,
+	* and earlier same-frame spawns).
+	*/
+	isDuplicateSpawn(det, live) {
+		for (const t of live) if (this.dedupCompatible(t.class, det.class) && iou$2(det.bbox, t.bbox) >= this.config.dedupSpawnIou) return true;
+		if (this.config.personAnimalDedup && det.class === ANIMAL_CLASS && det.score < this.config.animalOverPersonMaxScore) {
+			for (const t of live) if (t.class === PERSON_CLASS && iou$2(det.bbox, t.bbox) >= this.config.animalOverPersonIou) return true;
+		}
+		return false;
+	}
+	/** The lower-importance track of a duplicate pair — the one to drop. A
+	*  `person` always beats a cross-class `animal`; otherwise more hits wins,
+	*  ties break to the older track, then the higher score. */
+	static duplicateLoser(a, b) {
+		if (a.class !== b.class) {
+			if (a.class === PERSON_CLASS && b.class === ANIMAL_CLASS) return b;
+			if (b.class === PERSON_CLASS && a.class === ANIMAL_CLASS) return a;
+		}
+		if (a.hits !== b.hits) return a.hits > b.hits ? b : a;
+		if (a.firstSeen !== b.firstSeen) return a.firstSeen < b.firstSeen ? b : a;
+		return a.score >= b.score ? b : a;
+	}
+	/**
+	* Merge concurrent duplicate tracks. Two live compatible-class tracks that
+	* stay overlapped (≥ `dedupMergeIou`) for `dedupMergeFrames` consecutive
+	* frames are collapsed: the lower-importance one is dropped (NOT graveyarded
+	* — a confirmed duplicate must not resurrect). This is the fix for a subject
+	* the detector double-fires (two boxes each frame, each feeding its OWN
+	* track, so neither is ever "unmatched" for spawn-suppression to catch) and
+	* for a person misdetected as `animal` alongside the real person track.
+	*/
+	resolveDuplicates() {
+		if (!this.config.dedupEnabled) return;
+		const live = this.tracks;
+		const liveIds = new Set(live.map((t) => t.id));
+		for (const key of this.dupStreaks.keys()) {
+			const [a, b] = key.split("|");
+			if (a === void 0 || b === void 0 || !liveIds.has(a) || !liveIds.has(b)) this.dupStreaks.delete(key);
+		}
+		const dropIds = /* @__PURE__ */ new Set();
+		for (let i = 0; i < live.length; i++) for (let j = i + 1; j < live.length; j++) {
+			const a = live[i];
+			const b = live[j];
+			if (dropIds.has(a.id) || dropIds.has(b.id)) continue;
+			if (!this.dedupCompatible(a.class, b.class)) continue;
+			const key = SortTracker.pairKey(a.id, b.id);
+			if (iou$2(a.bbox, b.bbox) < this.config.dedupMergeIou) {
+				this.dupStreaks.delete(key);
+				continue;
+			}
+			const streak = (this.dupStreaks.get(key) ?? 0) + 1;
+			if (streak >= this.config.dedupMergeFrames) {
+				dropIds.add(SortTracker.duplicateLoser(a, b).id);
+				this.dupStreaks.delete(key);
+			} else this.dupStreaks.set(key, streak);
+		}
+		if (dropIds.size === 0) return;
+		this.tracks = this.tracks.filter((t) => !dropIds.has(t.id));
+		for (const key of this.dupStreaks.keys()) {
+			const [a, b] = key.split("|");
+			if (a !== void 0 && dropIds.has(a) || b !== void 0 && dropIds.has(b)) this.dupStreaks.delete(key);
+		}
+	}
 	/** Where a track is expected this frame — extrapolated by velocity while
 	*  coasting (predictiveCoasting), else its last known bbox. A stationary
 	*  track (speed < stationarySpeedPx) is frozen so bbox jitter can't walk the
@@ -1193,6 +1300,46 @@ var SortTracker = class {
 		const diag = Math.hypot(track.bbox.w, track.bbox.h);
 		return dist <= this.config.rescueCentroidFactor * diag;
 	}
+	/** Fold a matched detection's class + score into a track's lifetime vote
+	*  tally. A non-positive score still counts as an infinitesimal vote so a
+	*  zero-confidence frame contributes to the frame-count tiebreak. */
+	addClassVote(track, det) {
+		const weight = det.score > 0 ? det.score : Number.EPSILON;
+		track.classVotes.set(det.class, (track.classVotes.get(det.class) ?? 0) + weight);
+	}
+	/**
+	* The class to REPORT for a track: the confidence-weighted lifetime majority
+	* when voting is on and the winner holds ≥ `classVoteMinFraction` of the total
+	* weight; otherwise the latest-frame class (ambiguous vote or voting off).
+	*/
+	resolveReportedClass(t) {
+		if (!this.config.classVotingEnabled || t.classVotes.size === 0) return t.class;
+		let bestClass = t.class;
+		let bestVote = -1;
+		let total = 0;
+		for (const [cls, v] of t.classVotes) {
+			total += v;
+			if (v > bestVote) {
+				bestVote = v;
+				bestClass = cls;
+			}
+		}
+		if (total <= 0) return t.class;
+		return bestVote / total >= this.config.classVoteMinFraction ? bestClass : t.class;
+	}
+	/** Whether a detection clears its per-class spawn score floor. Only gates NEW
+	*  spawns — an established track still matches below its floor. */
+	meetsClassScoreFloor(det) {
+		if (!this.config.perClassMinScoreEnabled) return true;
+		const floor = this.config.classMinScores[det.class] ?? 0;
+		return det.score >= floor;
+	}
+	/** Whether a track is confirmed for EMISSION: it reached `minHits`, or (opt-in)
+	*  a single very-high-confidence detection bypassed the hit gate (fast car). */
+	isConfirmedForEmit(t) {
+		if (t.hits >= this.config.minHits) return true;
+		return this.config.confirmBypassEnabled && t.score >= this.config.confirmBypassScore;
+	}
 	update(detections, timestamp) {
 		if (this.config.maxTrackLifetimeMs > 0) {
 			const alive = [];
@@ -1277,6 +1424,7 @@ var SortTracker = class {
 			};
 			track.path.push(det.bbox);
 			if (track.path.length > MAX_PATH_LENGTH) track.path.shift();
+			this.addClassVote(track, det);
 		}
 		const occluderBoxes = [];
 		for (const track of matchedTracks) occluderBoxes.push(track.bbox);
@@ -1326,13 +1474,30 @@ var SortTracker = class {
 			};
 			best.path.push(det.bbox);
 			if (best.path.length > MAX_PATH_LENGTH) best.path.shift();
+			this.addClassVote(best, det);
 			surviving.push(best);
 			used.add(di);
 		}
-		for (let di = 0; di < detections.length; di++) {
-			if (used.has(di)) continue;
+		const unmatchedIdx = [];
+		for (let di = 0; di < detections.length; di++) if (!used.has(di)) unmatchedIdx.push(di);
+		const classRank = (cls) => cls === PERSON_CLASS ? 0 : cls === ANIMAL_CLASS ? 2 : 1;
+		unmatchedIdx.sort((ia, ib) => {
+			const da = detections[ia];
+			const db = detections[ib];
+			const r = classRank(da.class) - classRank(db.class);
+			return r !== 0 ? r : db.score - da.score;
+		});
+		for (const di of unmatchedIdx) {
 			const det = detections[di];
+			if (!this.meetsClassScoreFloor(det)) {
+				used.add(di);
+				continue;
+			}
 			if (this.config.occlusionEnabled && occluderBoxes.some((ob) => containment(det.bbox, ob) >= this.config.occlusionContainment)) continue;
+			if (this.config.dedupEnabled && this.isDuplicateSpawn(det, surviving)) {
+				used.add(di);
+				continue;
+			}
 			surviving.push({
 				id: (0, node_crypto.randomUUID)(),
 				bbox: det.bbox,
@@ -1350,12 +1515,14 @@ var SortTracker = class {
 				},
 				lost: false,
 				lostAt: 0,
-				resurrectable: true
+				resurrectable: true,
+				classVotes: new Map([[det.class, det.score > 0 ? det.score : Number.EPSILON]])
 			});
 		}
 		this.tracks = surviving;
-		return this.tracks.filter((t) => t.hits >= this.config.minHits).map((t) => ({
-			class: t.class,
+		this.resolveDuplicates();
+		return this.tracks.filter((t) => this.isConfirmedForEmit(t)).map((t) => ({
+			class: this.resolveReportedClass(t),
 			originalClass: t.originalClass,
 			score: t.score,
 			bbox: t.bbox,
@@ -1384,6 +1551,7 @@ var SortTracker = class {
 	reset() {
 		this.tracks = [];
 		this.lostTracks = [];
+		this.dupStreaks.clear();
 	}
 };
 //#endregion
@@ -6101,6 +6269,25 @@ function squareSafeCropRegion(bbox, frame, padding) {
 		h: Math.round(ch)
 	};
 }
+/**
+* The same square-safe 16:9 region as {@link squareSafeCropRegion}, expressed in
+* NORMALIZED [0,1]×[0,1] coordinates instead of pixels.
+*
+* A normalized box maps DIRECTLY onto a native-resolution surface of the SAME
+* aspect ratio (the native crop path downscales while preserving aspect), so the
+* region computed from the detection frame's dimensions addresses the exact same
+* ROI on the runner's retained native frame. Reuses the pixel geometry verbatim
+* (single source of truth) and divides by the frame dimensions.
+*/
+function squareSafeCropRegionNormalized(bbox, frame, padding) {
+	const region = squareSafeCropRegion(bbox, frame, padding);
+	return {
+		x: region.x / frame.W,
+		y: region.y / frame.H,
+		w: region.w / frame.W,
+		h: region.h / frame.H
+	};
+}
 //#endregion
 //#region src/shared/frame/box-drawer.ts
 var DEFAULT_COLOR = require_dist.DEFAULT_EVENT_COLOR;
@@ -6178,10 +6365,20 @@ async function drawBoxedFrame(frameData, frameWidth, frameHeight, boxes, opts =
 *  Small downscaled `thumbnail`s are intentionally left out for now — when we
 *  reintroduce them they'll be a separate small kind. */
 var MEDIA_QUALITY = 88;
-/** Output dimensions for square-safe 16:9 crops (crop/faceCrop/plateCrop). */
+/** Output dimensions for the LOCAL-FALLBACK square-safe 16:9 crops
+*  (crop/faceCrop/plateCrop/thumbnail) cut from the resolved ≤640 frame. */
 var CROP_WIDTH = 640;
 var CROP_HEIGHT = 360;
 var CROP_QUALITY = 80;
+/**
+* Native-surface crop width cap for subject crops (`crop`/`thumbnail`/
+* `faceCrop`/`plateCrop`). ~960px yields a sharp gallery/reel tile AND a
+* ≥224px classifier input straight from the runner's native surface, WITHOUT
+* hauling a full 1920px frame per subject (that width is reserved for the
+* full-frame `keyFrame`). It is an UPPER bound only: a native miss falls back to
+* the ≤640 local crop, so quality never regresses below today's behaviour.
+*/
+var NATIVE_SUBJECT_CROP_MAX_WIDTH = 960;
 function caption(className, confidence, label) {
 	const base = label && label !== className ? `${className} ${label}` : className;
 	return typeof confidence === "number" ? `${base} ${Math.round(confidence * 100)}%` : base;
@@ -6288,12 +6485,12 @@ var EventMediaDispatcher = class {
 			});
 			return empty;
 		}
-		for (const ev of events) await this.writeEventMedia(deviceId, frameData, fw, fh, ev, input.cropPadding);
+		for (const ev of events) await this.writeEventMedia(deviceId, frameHandle, frameData, fw, fh, ev, input.cropPadding);
 		for (const tf of trackFrames) await this.writeTrackFrame(deviceId, frameData, fw, fh, tf);
 		const storedSnapshots = [];
 		const thumbnailTrackIds = [];
 		for (const sn of snapshots) {
-			const res = await this.writeTrackSnapshot(deviceId, frameData, fw, fh, sn, input.cropPadding);
+			const res = await this.writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn, input.cropPadding);
 			if (res.storedSnapshot) storedSnapshots.push(res.storedSnapshot);
 			if (res.thumbnailWritten) thumbnailTrackIds.push(sn.trackId);
 		}
@@ -6314,7 +6511,7 @@ var EventMediaDispatcher = class {
 	* failed). `thumbnailWritten` reports whether a best `thumbnail` actually
 	* landed this frame (#27-A) so the caller can stop forcing retries.
 	*/
-	async writeTrackSnapshot(deviceId, frameData, fw, fh, sn, cropPadding) {
+	async writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn, cropPadding) {
 		if (!sn.appendSnapshot && !sn.rollingLastFrame && !sn.bestThumbnail) return {
 			storedSnapshot: null,
 			thumbnailWritten: false
@@ -6355,7 +6552,7 @@ var EventMediaDispatcher = class {
 		if (sn.rollingLastFrame && boxed) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
 		let thumbnailWritten = false;
 		if (sn.bestThumbnail) try {
-			const crop = await this.cropSubjectRegion(frameData, fw, fh, sn.bbox, cropPadding);
+			const crop = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, sn.bbox, cropPadding);
 			thumbnailWritten = await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, crop);
 		} catch (err) {
 			this.deps.logger.warn("event media: track thumbnail crop failed", {
@@ -6374,12 +6571,38 @@ var EventMediaDispatcher = class {
 		};
 	}
 	/**
-	* Clean subject-centered crop of `bbox` out of the raw frame — the shared
-	* output contract of the object-event `crop` kind and the track `thumbnail`:
-	* square-safe 16:9 region around the bbox, extracted from the ORIGINAL frame
-	* (no box drawn), resized to 640×360, JPEG q80.
+	* Clean subject-centered crop of `bbox` — the shared output contract of the
+	* object-event `crop` kind, the child `faceCrop`/`plateCrop`, and the track
+	* `thumbnail`: the square-safe 16:9 region around the bbox with NO box drawn.
+	*
+	* NATIVE-FIRST: the region is requested from the runner's retained native
+	* surface (normalized [0,1] coords map directly onto it), downscaled to
+	* {@link NATIVE_SUBJECT_CROP_MAX_WIDTH} — a sharp tile at native detail. On any
+	* miss/error (or a runner without the method) it FALLS BACK to cropping the
+	* resolved ≤640 frame locally (today's behaviour), so quality never regresses.
+	* Both paths run inside the live-handle window opened by `captureForFrame`.
+	*/
+	async cropSubjectRegion(frameHandle, frameData, fw, fh, bbox, cropPadding) {
+		if (this.deps.getNativeCropJpeg) try {
+			const norm = squareSafeCropRegionNormalized(bbox, {
+				W: fw,
+				H: fh
+			}, cropPadding);
+			const native = await this.deps.getNativeCropJpeg(frameHandle, norm, NATIVE_SUBJECT_CROP_MAX_WIDTH);
+			if (native) return native;
+		} catch (err) {
+			this.deps.logger.debug("event media: native subject crop failed — local fallback", { meta: {
+				shmId: frameHandle.shmId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+		return this.cropSubjectRegionLocal(frameData, fw, fh, bbox, cropPadding);
+	}
+	/**
+	* Local-fallback square-safe 16:9 crop out of the resolved ≤640 frame, resized
+	* to 640×360, JPEG q80. Used when the native surface is unavailable/missed.
 	*/
-	async cropSubjectRegion(frameData, fw, fh, bbox, cropPadding) {
+	async cropSubjectRegionLocal(frameData, fw, fh, bbox, cropPadding) {
 		const region = squareSafeCropRegion(bbox, {
 			W: fw,
 			H: fh
@@ -6422,13 +6645,13 @@ var EventMediaDispatcher = class {
 			return false;
 		}
 	}
-	async writeEventMedia(deviceId, frameData, fw, fh, ev, cropPadding) {
+	async writeEventMedia(deviceId, frameHandle, frameData, fw, fh, ev, cropPadding) {
 		const box = {
 			...ev.bbox,
 			label: caption(ev.className, ev.confidence, ev.label)
 		};
 		try {
-			const crop = await this.cropSubjectRegion(frameData, fw, fh, ev.bbox, cropPadding);
+			const crop = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, ev.bbox, cropPadding);
 			await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "event",
@@ -6488,24 +6711,7 @@ var EventMediaDispatcher = class {
 			});
 		}
 		if (ev.childCrops) for (const child of ev.childCrops) try {
-			const childRegion = squareSafeCropRegion(child.bbox, {
-				W: fw,
-				H: fh
-			}, cropPadding);
-			const childLeft = Math.max(0, Math.min(childRegion.x, fw - 1));
-			const childTop = Math.max(0, Math.min(childRegion.y, fh - 1));
-			const childWidth = Math.max(1, Math.min(childRegion.w, fw - childLeft));
-			const childHeight = Math.max(1, Math.min(childRegion.h, fh - childTop));
-			const childCropData = await (0, sharp.default)(frameData, { raw: {
-				width: fw,
-				height: fh,
-				channels: 3
-			} }).extract({
-				left: childLeft,
-				top: childTop,
-				width: childWidth,
-				height: childHeight
-			}).resize(CROP_WIDTH, CROP_HEIGHT).jpeg({ quality: CROP_QUALITY }).toBuffer();
+			const childCropData = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, child.bbox, cropPadding);
 			await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "event",
@@ -7666,6 +7872,56 @@ var TrackingSettingsSchema = require_dist.object({
 	/** Speed (px/frame) below which a track's prediction is frozen (stationary
 	*  jitter can't drift the box off a sitting object). */
 	stationarySpeedPx: require_dist.number().min(0).default(2),
+	/** Suppress + merge concurrent duplicate tracks (one subject the detector
+	*  double-fires, or a person misdetected as `animal`, otherwise becomes two
+	*  time-overlapping tracks that never re-associate — each firing its own
+	*  event). Off = legacy behaviour. */
+	dedupEnabled: require_dist.boolean().default(true),
+	/** Envelope IoU at/above which a NEW spawn is treated as a duplicate of a
+	*  concurrent compatible-class track and suppressed. High so distinct
+	*  subjects appearing close together are not collapsed. */
+	dedupSpawnIou: require_dist.number().min(0).max(1).default(.6),
+	/** Envelope IoU at/above which two concurrent tracks count as overlapping for
+	*  the sustained-merge streak. Kept equal to `dedupSpawnIou` by default so a
+	*  merged duplicate cannot re-spawn. */
+	dedupMergeIou: require_dist.number().min(0).max(1).default(.6),
+	/** Consecutive overlapping frames before two live tracks are merged (the
+	*  lower-importance one dropped). Higher = more conservative. */
+	dedupMergeFrames: require_dist.number().int().min(1).default(5),
+	/** Treat the {person,animal} class pair as duplicate-compatible — a person in
+	*  a non-upright pose is misdetected as `animal`; the false animal track
+	*  collapses into the real person track. */
+	personAnimalDedup: require_dist.boolean().default(true),
+	/** A low-confidence `animal` (score below this) overlapping a concurrent
+	*  person track is suppressed at spawn. */
+	animalOverPersonMaxScore: require_dist.number().min(0).max(1).default(.6),
+	/** IoU with a concurrent person track that triggers the low-confidence animal
+	*  spawn suppression. */
+	animalOverPersonIou: require_dist.number().min(0).max(1).default(.2),
+	/** Resolve a track's reported class by a confidence-weighted majority over its
+	*  lifetime (vs. the latest frame) — kills per-frame class flips (a person
+	*  read as `animal` on one crouch frame keeps the `person` label). */
+	classVotingEnabled: require_dist.boolean().default(true),
+	/** Winning class must hold at least this fraction of a track's total vote
+	*  weight to override the latest-frame class; below it the latest wins (so a
+	*  genuine mid-life reclassification is never frozen out). */
+	classVoteMinFraction: require_dist.number().min(0).max(1).default(.5),
+	/** Enforce a per-class minimum detection score at track SPAWN (an established
+	*  track still matches below its floor — only new spawns are gated). */
+	perClassMinScoreEnabled: require_dist.boolean().default(true),
+	/** Minimum spawn score for `person`. 0 = ungated (kept sensitive). */
+	minScorePerson: require_dist.number().min(0).max(1).default(0),
+	/** Minimum spawn score for `animal` (FP-prone — higher floor). */
+	minScoreAnimal: require_dist.number().min(0).max(1).default(.45),
+	/** Minimum spawn score for `vehicle` (FP-prone — higher floor). */
+	minScoreVehicle: require_dist.number().min(0).max(1).default(.45),
+	/** Let a single very-high-confidence detection confirm a track for emission
+	*  before it reaches `minHits` (so a fast car crossing in 1-2 frames still
+	*  registers). Opt-in — default OFF keeps the strict N-hit gate. */
+	confirmBypassEnabled: require_dist.boolean().default(false),
+	/** Score at/above which a detection confirms its track immediately (bypasses
+	*  `minHits`). Only consulted when `confirmBypassEnabled`. */
+	confirmBypassScore: require_dist.number().min(0).max(1).default(.9),
 	/** Skip frames where detections suddenly drop to zero (detector glitch). */
 	dropoutSkipEnabled: require_dist.boolean().default(true),
 	/** Max consecutive all-zero frames absorbed as a glitch before the scene is
@@ -7700,6 +7956,21 @@ function resolveTrackingSettings(raw) {
 		rescueCentroidFactor: s.rescueCentroidFactor.catch(TRACKING_DEFAULTS.rescueCentroidFactor).parse(raw.rescueCentroidFactor),
 		resurrectionWindowMs: s.resurrectionWindowMs.catch(TRACKING_DEFAULTS.resurrectionWindowMs).parse(raw.resurrectionWindowMs),
 		stationarySpeedPx: s.stationarySpeedPx.catch(TRACKING_DEFAULTS.stationarySpeedPx).parse(raw.stationarySpeedPx),
+		dedupEnabled: s.dedupEnabled.catch(TRACKING_DEFAULTS.dedupEnabled).parse(raw.dedupEnabled),
+		dedupSpawnIou: s.dedupSpawnIou.catch(TRACKING_DEFAULTS.dedupSpawnIou).parse(raw.dedupSpawnIou),
+		dedupMergeIou: s.dedupMergeIou.catch(TRACKING_DEFAULTS.dedupMergeIou).parse(raw.dedupMergeIou),
+		dedupMergeFrames: s.dedupMergeFrames.catch(TRACKING_DEFAULTS.dedupMergeFrames).parse(raw.dedupMergeFrames),
+		personAnimalDedup: s.personAnimalDedup.catch(TRACKING_DEFAULTS.personAnimalDedup).parse(raw.personAnimalDedup),
+		animalOverPersonMaxScore: s.animalOverPersonMaxScore.catch(TRACKING_DEFAULTS.animalOverPersonMaxScore).parse(raw.animalOverPersonMaxScore),
+		animalOverPersonIou: s.animalOverPersonIou.catch(TRACKING_DEFAULTS.animalOverPersonIou).parse(raw.animalOverPersonIou),
+		classVotingEnabled: s.classVotingEnabled.catch(TRACKING_DEFAULTS.classVotingEnabled).parse(raw.classVotingEnabled),
+		classVoteMinFraction: s.classVoteMinFraction.catch(TRACKING_DEFAULTS.classVoteMinFraction).parse(raw.classVoteMinFraction),
+		perClassMinScoreEnabled: s.perClassMinScoreEnabled.catch(TRACKING_DEFAULTS.perClassMinScoreEnabled).parse(raw.perClassMinScoreEnabled),
+		minScorePerson: s.minScorePerson.catch(TRACKING_DEFAULTS.minScorePerson).parse(raw.minScorePerson),
+		minScoreAnimal: s.minScoreAnimal.catch(TRACKING_DEFAULTS.minScoreAnimal).parse(raw.minScoreAnimal),
+		minScoreVehicle: s.minScoreVehicle.catch(TRACKING_DEFAULTS.minScoreVehicle).parse(raw.minScoreVehicle),
+		confirmBypassEnabled: s.confirmBypassEnabled.catch(TRACKING_DEFAULTS.confirmBypassEnabled).parse(raw.confirmBypassEnabled),
+		confirmBypassScore: s.confirmBypassScore.catch(TRACKING_DEFAULTS.confirmBypassScore).parse(raw.confirmBypassScore),
 		dropoutSkipEnabled: s.dropoutSkipEnabled.catch(TRACKING_DEFAULTS.dropoutSkipEnabled).parse(raw.dropoutSkipEnabled),
 		dropoutMaxSkipFrames: s.dropoutMaxSkipFrames.catch(TRACKING_DEFAULTS.dropoutMaxSkipFrames).parse(raw.dropoutMaxSkipFrames)
 	};
@@ -8108,6 +8379,40 @@ function planPeriodicMedia(input) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/best-thumbnail-guard.ts
+/**
+* Void/envArea guard for best-`thumbnail` selection.
+*
+* ## Why this exists (the dawn/night "void" thumbnail)
+*
+* At dawn/night a moving subject's tracker box intermittently EXPLODES to
+* (near-)the whole frame — the "envelope exploded to full-frame" signature. If
+* that frame happens to win the best-detection race, the gallery/reel best
+* `thumbnail` becomes a useless full-scene tile (the subject crop is the entire
+* washed-out frame), not the subject. This guard rejects such a frame from the
+* best-`thumbnail` decision so the track keeps a real subject-centered tile.
+*
+* Conservative by design: it only rejects boxes covering ≥ {@link
+* NEAR_FULL_FRAME_AREA} of the frame — a genuine large close-up subject stays
+* well under this. Rejecting a frame does NOT land a thumbnail, so the #27-A
+* per-frame retry keeps trying until a plausible frame wins.
+*/
+/**
+* Area fraction at/above which a detection bbox is treated as an exploded
+* "envelope" (near-full-frame) box rather than a real subject. 0.85 keeps the
+* guard conservative — only boxes covering ≥85% of the frame are rejected.
+*/
+var NEAR_FULL_FRAME_AREA = .85;
+/**
+* True when `bbox` is a plausible SUBJECT box for a best `thumbnail` — i.e. its
+* area is below the near-full-frame threshold. Degenerate frame dimensions
+* (≤0) are treated as plausible (no info to reject on).
+*/
+function isPlausibleThumbnailBox(bbox, frameWidth, frameHeight) {
+	if (frameWidth <= 0 || frameHeight <= 0) return true;
+	return bbox.w * bbox.h / (frameWidth * frameHeight) < NEAR_FULL_FRAME_AREA;
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/key-frame-capture.ts
 /**
 * Pure helpers for the per-track NATIVE-resolution `keyFrame` capture
@@ -11415,6 +11720,35 @@ function toAnalyticsDeviceSections(sections) {
 	}));
 }
 /**
+* Global-analytics section ids that are really per-camera DETECTION knobs and
+* belong in the consolidated `Detection pipeline → Settings` sub-tab alongside
+* Object Detection — NOT under the generic `Analytics` top-tab:
+*   - `detection-sensitivity` — minHits / cooldown / stationary threshold.
+*   - `tracking` — the tracker-tuning form incl. the FP knobs (dedup, person↔
+*     animal dedup, class voting, confirm-bypass, per-class min score).
+*   - `stationary-objects` — stationary promotion + occupancy tuning.
+* `DeviceDetail` folds `tab: 'detection-pipeline'` top-tab sections into the
+* structural Detection pipeline tab, so re-tagging is all that's needed —
+* there is no admin-ui change and no duplicate render (a section has one tab).
+*/
+var DETECTION_PIPELINE_SECTION_IDS = new Set([
+	"detection-sensitivity",
+	"tracking",
+	"stationary-objects"
+]);
+/**
+* Re-home the detection-knob sections from the `Analytics` top-tab onto the
+* `detection-pipeline` top-tab. Pure copy — only the `tab` of a matched
+* section changes; every other section (media policy, retention, faces, track
+* history) stays on Analytics.
+*/
+function retagDetectionSections(sections) {
+	return sections.map((s) => s.id !== void 0 && DETECTION_PIPELINE_SECTION_IDS.has(s.id) ? {
+		...s,
+		tab: "detection-pipeline"
+	} : s);
+}
+/**
 * Fields that live ONLY on the global settings page and must never surface in a
 * per-device contribution. The face-recognition `enabled` switch is the GLOBAL
 * master kill for the whole subsystem — per-camera face production is governed
@@ -11628,7 +11962,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		let storage = this.ctx.kernel.storage;
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
 		if (mediaRoot) {
-			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-CDbDhtGa.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-BiZGDArd.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -11796,11 +12130,6 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				timestamp: 0
 			};
 		};
-		this.eventMediaDispatcher = new EventMediaDispatcher({
-			getRemoteFrame,
-			mediaStore: this.mediaStore,
-			logger: logger.child("EventMediaDispatcher")
-		});
 		const cropMetricLogger = logger.child("NativeCrop");
 		let nativeHits = 0;
 		let nativeFallbacks = 0;
@@ -11832,6 +12161,17 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				return null;
 			}
 		};
+		const getNativeCropJpeg = async (frameHandle, normalizedBbox, maxWidth) => {
+			const jpeg = await tryNativeCrop(frameHandle, normalizedBbox, maxWidth);
+			bumpCropMetric(jpeg !== null);
+			return jpeg;
+		};
+		this.eventMediaDispatcher = new EventMediaDispatcher({
+			getRemoteFrame,
+			getNativeCropJpeg,
+			mediaStore: this.mediaStore,
+			logger: logger.child("EventMediaDispatcher")
+		});
 		const resolveFrameShared = createSharedFrameResolver((frameHandle) => resolveFrame(frameHandle, { getRemoteFrame }));
 		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding, maxWidth) => {
 			const paddedNorm = padBbox({
@@ -13272,7 +13612,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			});
 			if (plan.rollingLastFrame) this.lastFrameAtByTrack.set(t.trackId, timestamp);
 			if (plan.appendSnapshot) this.trackStore.markSnapshotPending(t.trackId, timestamp, t.bbox);
-			if (!plan.appendSnapshot && !plan.rollingLastFrame && !plan.bestThumbnail) continue;
+			const bestThumbnail = plan.bestThumbnail && isPlausibleThumbnailBox(t.bbox, frameWidth, frameHeight);
+			if (!plan.appendSnapshot && !plan.rollingLastFrame && !bestThumbnail) continue;
 			targets.push({
 				trackId: t.trackId,
 				timestamp,
@@ -13280,7 +13621,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				...t.label ? { label: t.label } : {},
 				appendSnapshot: plan.appendSnapshot,
 				rollingLastFrame: plan.rollingLastFrame,
-				bestThumbnail: plan.bestThumbnail
+				bestThumbnail
 			});
 		}
 		return targets;
@@ -13882,7 +14223,24 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				rescueCentroidFactor: trk.rescueCentroidFactor,
 				resurrectionWindowMs: trk.resurrectionWindowMs,
 				stationarySpeedPx: trk.stationarySpeedPx,
-				maxTrackLifetimeMs: trk.maxTrackLifetimeSec * 1e3
+				maxTrackLifetimeMs: trk.maxTrackLifetimeSec * 1e3,
+				dedupEnabled: trk.dedupEnabled,
+				dedupSpawnIou: trk.dedupSpawnIou,
+				dedupMergeIou: trk.dedupMergeIou,
+				dedupMergeFrames: trk.dedupMergeFrames,
+				personAnimalDedup: trk.personAnimalDedup,
+				animalOverPersonMaxScore: trk.animalOverPersonMaxScore,
+				animalOverPersonIou: trk.animalOverPersonIou,
+				classVotingEnabled: trk.classVotingEnabled,
+				classVoteMinFraction: trk.classVoteMinFraction,
+				perClassMinScoreEnabled: trk.perClassMinScoreEnabled,
+				classMinScores: {
+					person: trk.minScorePerson,
+					animal: trk.minScoreAnimal,
+					vehicle: trk.minScoreVehicle
+				},
+				confirmBypassEnabled: trk.confirmBypassEnabled,
+				confirmBypassScore: trk.confirmBypassScore
 			}, { stationaryThresholdSec }, {
 				minTrackAge,
 				cooldownSec,
@@ -15185,6 +15543,69 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						default: TRACKING_DEFAULTS.occlusionMaxMissedMs,
 						unit: "ms"
 					},
+					{
+						type: "boolean",
+						key: "dedupEnabled",
+						label: "Duplicate-track suppression",
+						description: "Suppress and merge concurrent duplicate tracks. Stops one subject the detector double-fires (two boxes for one object, or a person misdetected as an animal) from becoming several time-overlapping tracks that each fire their own event. Off = legacy behaviour.",
+						default: TRACKING_DEFAULTS.dedupEnabled
+					},
+					{
+						type: "number",
+						key: "dedupSpawnIou",
+						label: "Duplicate spawn IoU",
+						description: "Overlap at/above which a NEW track is treated as a duplicate of a concurrent same-kind track and not created. High so two distinct subjects appearing close together are still tracked separately.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.dedupSpawnIou
+					},
+					{
+						type: "number",
+						key: "dedupMergeIou",
+						label: "Duplicate merge IoU",
+						description: "Overlap at/above which two concurrent same-kind tracks count as overlapping for the sustained-merge test.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.dedupMergeIou
+					},
+					{
+						type: "number",
+						key: "dedupMergeFrames",
+						label: "Duplicate merge frames",
+						description: "Consecutive overlapping frames before two concurrent tracks are merged (the shorter / lower-importance one is dropped). Higher = more conservative (only merge sustained overlaps).",
+						min: 1,
+						step: 1,
+						default: TRACKING_DEFAULTS.dedupMergeFrames
+					},
+					{
+						type: "boolean",
+						key: "personAnimalDedup",
+						label: "Person/animal duplicate merge",
+						description: "Treat an animal track overlapping a person track as the same subject (a person in a crouching / bending pose is often misdetected as an animal). The person track wins.",
+						default: TRACKING_DEFAULTS.personAnimalDedup
+					},
+					{
+						type: "number",
+						key: "animalOverPersonMaxScore",
+						label: "Animal-over-person max score",
+						description: "A low-confidence animal detection (score below this) sitting on a concurrent person track is suppressed — the common person-in-odd-pose false animal.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.animalOverPersonMaxScore
+					},
+					{
+						type: "number",
+						key: "animalOverPersonIou",
+						label: "Animal-over-person IoU",
+						description: "Overlap with a concurrent person track that triggers the low-confidence animal spawn suppression.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.animalOverPersonIou
+					},
 					{
 						type: "boolean",
 						key: "dropoutSkipEnabled",
@@ -15200,6 +15621,77 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						min: 0,
 						step: 1,
 						default: TRACKING_DEFAULTS.dropoutMaxSkipFrames
+					},
+					{
+						type: "boolean",
+						key: "classVotingEnabled",
+						label: "Per-track class voting",
+						description: "Report a track’s class by a confidence-weighted majority over its whole life instead of the latest frame — a person read as an animal on a single crouch/bend frame keeps the person label.",
+						default: TRACKING_DEFAULTS.classVotingEnabled
+					},
+					{
+						type: "number",
+						key: "classVoteMinFraction",
+						label: "Class-vote min fraction",
+						description: "The winning class must hold at least this fraction of a track’s total vote weight to override the latest frame; below it the latest frame wins (so a genuine mid-life reclassification is not frozen out).",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.classVoteMinFraction
+					},
+					{
+						type: "boolean",
+						key: "perClassMinScoreEnabled",
+						label: "Per-class spawn confidence",
+						description: "Require a per-class minimum detection score before a NEW track is created. Kills static-object / reflection false spawns from the FP-prone classes. An already-tracked object still matches on a low-confidence frame.",
+						default: TRACKING_DEFAULTS.perClassMinScoreEnabled
+					},
+					{
+						type: "number",
+						key: "minScorePerson",
+						label: "Min spawn score — person",
+						description: "Minimum score to spawn a person track. 0 keeps person fully sensitive.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.minScorePerson
+					},
+					{
+						type: "number",
+						key: "minScoreAnimal",
+						label: "Min spawn score — animal",
+						description: "Minimum score to spawn an animal track (FP-prone — a higher floor drops low-confidence static-object false animals).",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.minScoreAnimal
+					},
+					{
+						type: "number",
+						key: "minScoreVehicle",
+						label: "Min spawn score — vehicle",
+						description: "Minimum score to spawn a vehicle track (FP-prone — a higher floor drops low-confidence false vehicles).",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.minScoreVehicle
+					},
+					{
+						type: "boolean",
+						key: "confirmBypassEnabled",
+						label: "Fast high-confidence confirm",
+						description: "Let a single very-high-confidence detection confirm a track for events before it reaches the min-hits gate, so a fast subject crossing in 1-2 frames (a passing car) still registers. Off by default (strict N-hit confirmation).",
+						default: TRACKING_DEFAULTS.confirmBypassEnabled
+					},
+					{
+						type: "number",
+						key: "confirmBypassScore",
+						label: "Fast-confirm score",
+						description: "Score at/above which a detection confirms its track immediately, bypassing min-hits. Only used when fast high-confidence confirm is on.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.confirmBypassScore
 					}
 				]
 			},
@@ -15275,7 +15767,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		const raw = await this.ctx?.settings?.readDeviceStore(input.deviceId) ?? {};
 		const baseSections = schema ? require_dist.hydrateSchema({
 			...schema,
-			sections: stripGlobalOnlyFields(toAnalyticsDeviceSections(schema.sections))
+			sections: retagDetectionSections(stripGlobalOnlyFields(toAnalyticsDeviceSections(schema.sections)))
 		}, raw).sections : [];
 		const liveStatsSection = {
 			id: "live-stats",
@@ -15324,7 +15816,9 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	}
 };
 //#endregion
+exports.DETECTION_PIPELINE_SECTION_IDS = DETECTION_PIPELINE_SECTION_IDS;
 exports.default = PipelineAnalyticsAddon;
 exports.pickCleanMedia = pickCleanMedia;
+exports.retagDetectionSections = retagDetectionSections;
 exports.stripGlobalOnlyFields = stripGlobalOnlyFields;
 exports.toAnalyticsDeviceSections = toAnalyticsDeviceSections;