@camstack/addon-post-analysis 1.1.38 → 1.1.39

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-_h-RM5Lr.js");
+const require_dist = require("../dist-DUcGHr9E.js");
 let node_crypto = require("node:crypto");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -1141,7 +1141,13 @@ var DEFAULT_TRACKER_CONFIG = {
 		vehicle: .45
 	},
 	confirmBypassEnabled: false,
-	confirmBypassScore: .9
+	confirmBypassScore: .9,
+	byteTrackEnabled: true,
+	byteTrackHighThreshold: .4,
+	byteTrackLowIouThreshold: .2,
+	minSpawnAreaEnabled: true,
+	classSpawnAreaFracs: { person: 5e-4 },
+	classGroupAssoc: true
 };
 /** Macro-classes the duplicate resolver may collapse across (people in
 *  non-upright poses misdetected as animals). Any other cross-class pair is
@@ -1198,6 +1204,31 @@ var SortTracker = class SortTracker {
 	static pairKey(a, b) {
 		return a < b ? `${a}|${b}` : `${b}|${a}`;
 	}
+	/** Association-gating group of a class. When `classGroupAssoc` is on the
+	*  {person,animal} pair collapses to one group so a per-frame class flip
+	*  (crouch person → animal) re-matches the existing track instead of spawning a
+	*  concurrent id. Every other class is its own group. */
+	assocGroup(cls) {
+		if (this.config.classGroupAssoc && (cls === PERSON_CLASS || cls === ANIMAL_CLASS)) return `${PERSON_CLASS}|${ANIMAL_CLASS}`;
+		return cls;
+	}
+	/** Whether a detection may associate to a track under the current class gate:
+	*  exact class when `classGating` is off (no gate at all) — matching the legacy
+	*  contract — otherwise same association group (group == exact class unless
+	*  `classGroupAssoc` widened it to {person,animal}). */
+	associable(trackClass, detClass) {
+		if (!this.config.classGating) return true;
+		return this.assocGroup(trackClass) === this.assocGroup(detClass);
+	}
+	/** Whether a spawn candidate clears its per-class minimum bbox-area floor
+	*  (fraction of frame area). Ungated when disabled, when the class has no floor,
+	*  or when the caller supplied no frame dimensions (fraction is uncomputable). */
+	meetsSpawnAreaFloor(det, frameArea) {
+		if (!this.config.minSpawnAreaEnabled) return true;
+		const floor = this.config.classSpawnAreaFracs[det.class] ?? 0;
+		if (floor <= 0 || frameArea <= 0) return true;
+		return det.bbox.w * det.bbox.h / frameArea >= floor;
+	}
 	/**
 	* True when spawning a fresh track for `det` would duplicate an already-live
 	* track: (a) it overlaps a concurrent compatible-class track by
@@ -1286,13 +1317,16 @@ var SortTracker = class SortTracker {
 		};
 	}
 	/**
-	* Loose same-class gate used by the rescue and resurrection passes: accept
+	* Loose same-group gate used by the rescue and resurrection passes: accept
 	* when the detection overlaps the track's LAST-KNOWN bbox by `rescueIou`, or
-	* its centroid is within `rescueCentroidFactor × bbox-diagonal`. Always class-
-	* gated (a rescue must never cross classes), independent of `classGating`.
+	* its centroid is within `rescueCentroidFactor × bbox-diagonal`. Always group-
+	* gated (a rescue must never cross association groups) independent of
+	* `classGating`, so a coasting person track can be rescued by its own
+	* crouch→animal flip when `classGroupAssoc` is on, but never by an unrelated
+	* class.
 	*/
 	looseMatch(track, det) {
-		if (track.class !== det.class) return false;
+		if (this.assocGroup(track.class) !== this.assocGroup(det.class)) return false;
 		if (iou$2(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return true;
 		const tc = bboxCentroid(track.bbox);
 		const dc = bboxCentroid(det.bbox);
@@ -1340,29 +1374,25 @@ var SortTracker = class SortTracker {
 		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 = [];
-			for (const track of this.tracks) if (timestamp - track.firstSeen > this.config.maxTrackLifetimeMs) {
-				track.lost = true;
-				track.lostAt = timestamp;
-				track.resurrectable = false;
-				this.lostTracks.push(track);
-			} else alive.push(track);
-			this.tracks = alive;
-		}
-		this.lostTracks = this.lostTracks.filter((t) => timestamp - t.lostAt <= this.config.resurrectionWindowMs);
-		const used = /* @__PURE__ */ new Set();
-		const matchedTracks = /* @__PURE__ */ new Set();
-		const matched = /* @__PURE__ */ new Map();
+	/**
+	* One greedy IoU association pass over a candidate detection subset against the
+	* currently-UNMATCHED tracks, on each track's PREDICTED box. Highest-IoU pairs
+	* bind first; a track/detection binds at most once. Shared by the high-score
+	* first stage and the low-score second stage (different candidate sets + IoU
+	* gates) so the two-tier ByteTrack association stays a single implementation.
+	* Mutates `used` / `matchedTracks` / `matched` in place.
+	*/
+	greedyAssociate(detections, candidateIdxs, iouThreshold, used, matchedTracks, matched) {
 		const pairs = [];
 		for (const track of this.tracks) {
+			if (matchedTracks.has(track)) continue;
 			const pbox = this.predicted(track);
-			for (let di = 0; di < detections.length; di++) {
+			for (const di of candidateIdxs) {
+				if (used.has(di)) continue;
 				const det = detections[di];
-				if (this.config.classGating && track.class !== det.class) continue;
+				if (!this.associable(track.class, det.class)) continue;
 				const score = iou$2(pbox, det.bbox);
-				if (score >= this.config.iouThreshold) pairs.push({
+				if (score >= iouThreshold) pairs.push({
 					track,
 					detIdx: di,
 					score
@@ -1376,11 +1406,34 @@ var SortTracker = class SortTracker {
 			matchedTracks.add(pair.track);
 			used.add(pair.detIdx);
 		}
+	}
+	update(detections, timestamp, frameContext) {
+		const frameArea = frameContext ? frameContext.frameWidth * frameContext.frameHeight : 0;
+		if (this.config.maxTrackLifetimeMs > 0) {
+			const alive = [];
+			for (const track of this.tracks) if (timestamp - track.firstSeen > this.config.maxTrackLifetimeMs) {
+				track.lost = true;
+				track.lostAt = timestamp;
+				track.resurrectable = false;
+				this.lostTracks.push(track);
+			} else alive.push(track);
+			this.tracks = alive;
+		}
+		this.lostTracks = this.lostTracks.filter((t) => timestamp - t.lostAt <= this.config.resurrectionWindowMs);
+		const used = /* @__PURE__ */ new Set();
+		const matchedTracks = /* @__PURE__ */ new Set();
+		const matched = /* @__PURE__ */ new Map();
+		const highIdxs = [];
+		const lowIdxs = [];
+		for (let di = 0; di < detections.length; di++) if (this.config.byteTrackEnabled && detections[di].score < this.config.byteTrackHighThreshold) lowIdxs.push(di);
+		else highIdxs.push(di);
+		const lowSet = new Set(lowIdxs);
+		this.greedyAssociate(detections, highIdxs, this.config.iouThreshold, used, matchedTracks, matched);
 		const rescuePairs = [];
 		for (const track of this.tracks) {
 			if (matchedTracks.has(track)) continue;
 			for (let di = 0; di < detections.length; di++) {
-				if (used.has(di)) continue;
+				if (used.has(di) || lowSet.has(di)) continue;
 				const det = detections[di];
 				if (!this.looseMatch(track, det)) continue;
 				rescuePairs.push({
@@ -1397,6 +1450,7 @@ var SortTracker = class SortTracker {
 			matchedTracks.add(pair.track);
 			used.add(pair.detIdx);
 		}
+		if (this.config.byteTrackEnabled && lowIdxs.length > 0) this.greedyAssociate(detections, lowIdxs, this.config.byteTrackLowIouThreshold, used, matchedTracks, matched);
 		for (const [track, det] of matched) {
 			const prevCenter = bboxCentroid({
 				x: track.bbox.x,
@@ -1493,6 +1547,10 @@ var SortTracker = class SortTracker {
 				used.add(di);
 				continue;
 			}
+			if (!this.meetsSpawnAreaFloor(det, frameArea)) {
+				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);
@@ -1529,7 +1587,8 @@ var SortTracker = class SortTracker {
 			trackId: t.id,
 			trackAge: t.hits,
 			velocity: t.velocity,
-			path: [...t.path]
+			path: [...t.path],
+			matchedThisFrame: t.lastSeen === timestamp
 		}));
 	}
 	/**
@@ -2111,7 +2170,10 @@ var FrameProcessor = class {
 			wokenEntryIds: []
 		};
 		const trackerInput = gate.suppressedIndices.size > 0 ? filteredDetections.filter((_, i) => !gate.suppressedIndices.has(i)) : filteredDetections;
-		const trackedDetections = this.tracker.update(trackerInput, timestamp);
+		const trackedDetections = this.tracker.update(trackerInput, timestamp, {
+			frameWidth,
+			frameHeight
+		});
 		const objectStates = this.stateAnalyzer.analyze(trackedDetections, timestamp);
 		const rawEvents = this.eventEmitter.emit(trackedDetections, objectStates, [], [], String(this.deviceId));
 		const zonesByTrack = /* @__PURE__ */ new Map();
@@ -2140,6 +2202,7 @@ var FrameProcessor = class {
 				bbox: { ...td.bbox },
 				zones: zonesByTrack.get(td.trackId) ?? [],
 				state,
+				matchedThisFrame: td.matchedThisFrame !== false,
 				...label ? { label } : {},
 				...emb !== void 0 ? {
 					embedding: emb.embedding,
@@ -4412,6 +4475,26 @@ var FACE_MEDIA_OWNER_PREFIX = "face-";
 *  `plate-<trackId>`. Used by `deleteByTracks` to derive the plate crop owners
 *  of a set of tracks without a `trackId` column on media rows. */
 var PLATE_MEDIA_OWNER_PREFIX = "plate-";
+/**
+* Kinds that hold exactly ONE row per `(ownerKind, ownerId)` — the current
+* "best"/rolling/first artefact, never a filmstrip. Their row id + blob path are
+* DETERMINISTIC (`owner:kind`, NO timestamp) and written via an UPSERT
+* (`store.set`, atomic `INSERT … ON CONFLICT DO UPDATE`), so N concurrent
+* captures for the same `(track, kind)` all address the SAME row/blob — one can
+* never become thirteen regardless of interleaving (RC-1). Accumulating kinds
+* (`snapshot`, event `crop`/`fullFrame*`, `faceCrop`/`plateCrop`) keep their
+* per-instance timestamped id so the filmstrip / per-event / per-enrollment rows
+* still accumulate.
+*/
+var SINGLE_INSTANCE_KINDS = new Set([
+	"keyFrame",
+	"thumbnail",
+	"firstFrame",
+	"lastFrame"
+]);
+function isSingleInstanceKind(kind) {
+	return SINGLE_INSTANCE_KINDS.has(kind);
+}
 var MEDIA_COLUMNS = [
 	{
 		name: "id",
@@ -4463,10 +4546,11 @@ var MEDIA_INDEXES = [{
 	columns: ["deviceId", "timestamp"]
 }];
 function buildKey(params) {
-	return `${params.ownerKind}:${params.ownerId}:${params.kind}:${params.timestamp}`;
+	return isSingleInstanceKind(params.kind) ? `${params.ownerKind}:${params.ownerId}:${params.kind}` : `${params.ownerKind}:${params.ownerId}:${params.kind}:${params.timestamp}`;
 }
 function buildPath(params) {
-	return `pipeline-analytics/${params.deviceId}/${params.ownerKind}/${params.ownerId}/${params.kind}-${params.timestamp}.jpg`;
+	const base = `pipeline-analytics/${params.deviceId}/${params.ownerKind}/${params.ownerId}`;
+	return isSingleInstanceKind(params.kind) ? `${base}/${params.kind}.jpg` : `${base}/${params.kind}-${params.timestamp}.jpg`;
 }
 var MediaStore = class {
 	storage;
@@ -4489,25 +4573,31 @@ var MediaStore = class {
 	async put(params) {
 		const key = buildKey(params);
 		const path = buildPath(params);
+		const record = {
+			deviceId: params.deviceId,
+			ownerKind: params.ownerKind,
+			ownerId: params.ownerId,
+			kind: params.kind,
+			timestamp: params.timestamp,
+			path,
+			sizeBytes: params.data.length
+		};
 		try {
 			await this.storage.write({
 				location: "eventMedia",
 				relativePath: path,
 				data: params.data
 			});
-			await this.store.insert.mutate({
+			if (isSingleInstanceKind(params.kind)) await this.store.set.mutate({
+				collection: MEDIA_COLLECTION,
+				key,
+				value: record
+			});
+			else await this.store.insert.mutate({
 				collection: MEDIA_COLLECTION,
 				record: {
 					id: key,
-					data: {
-						deviceId: params.deviceId,
-						ownerKind: params.ownerKind,
-						ownerId: params.ownerId,
-						kind: params.kind,
-						timestamp: params.timestamp,
-						path,
-						sizeBytes: params.data.length
-					}
+					data: record
 				}
 			});
 			return key;
@@ -4526,8 +4616,14 @@ var MediaStore = class {
 	* Overwrite semantics: keep exactly ONE media entry per (ownerKind, ownerId,
 	* kind). Used for the rolling `lastFrame` and the best `thumbnail` per track —
 	* each new capture replaces the previous one (blob + index row) rather than
-	* accumulating a filmstrip the way `put` does. Deletes any existing rows of
-	* that (owner, kind) first, then writes the fresh one. Returns the new key.
+	* accumulating a filmstrip the way `put` does.
+	*
+	* These kinds are {@link SINGLE_INSTANCE_KINDS}, so `put` writes them to a
+	* DETERMINISTIC `owner:kind` row/blob via an UPSERT — N concurrent racing
+	* calls therefore all collapse onto the SAME row (RC-1), no query/insert/delete
+	* interleaving can leave survivors. The query+delete pass below is retained
+	* ONLY to reap LEGACY timestamped rows/blobs written before the deterministic
+	* scheme (transition back-compat); once migrated it is a no-op.
 	*/
 	async putReplacing(params) {
 		const existing = await this.store.query.query({
@@ -7926,7 +8022,35 @@ var TrackingSettingsSchema = require_dist.object({
 	dropoutSkipEnabled: require_dist.boolean().default(true),
 	/** Max consecutive all-zero frames absorbed as a glitch before the scene is
 	*  treated as genuinely empty. */
-	dropoutMaxSkipFrames: require_dist.number().int().min(0).default(5)
+	dropoutMaxSkipFrames: require_dist.number().int().min(0).default(5),
+	/** Two-stage (ByteTrack) association: match high-confidence detections first,
+	*  then recover coasting tracks with the low-confidence leftovers before they
+	*  die. The single biggest fragmentation reducer. Off = legacy single pass. */
+	byteTrackEnabled: require_dist.boolean().default(true),
+	/** Score at/above which a detection is HIGH (matched first); below it a detection
+	*  is LOW and only gets the second-stage recovery match. Does not gate spawning
+	*  (the per-class score/area floors do). */
+	byteTrackHighThreshold: require_dist.number().min(0).max(1).default(.4),
+	/** Looser IoU gate for the low-score second (recovery) association stage — a
+	*  coasting box is stale, and the match only re-attaches an existing track. */
+	byteTrackLowIouThreshold: require_dist.number().min(0).max(1).default(.2),
+	/** Enforce a per-class minimum bbox-area (fraction of frame) at track SPAWN —
+	*  kills tiny far-field / vanishing-point noise tracks. An established track
+	*  still matches a shrinking box; only spawns are gated. */
+	minSpawnAreaEnabled: require_dist.boolean().default(true),
+	/** Min spawn bbox area for `person` as a fraction of the frame (0 = ungated).
+	*  Person is the only spawn-score-ungated class, so far-field person noise is
+	*  the worst offender; a conservative 0.05% rejects only vanishing-point blips. */
+	minSpawnAreaFracPerson: require_dist.number().min(0).max(1).default(5e-4),
+	/** Min spawn bbox area for `animal` as a fraction of the frame (0 = ungated). */
+	minSpawnAreaFracAnimal: require_dist.number().min(0).max(1).default(0),
+	/** Min spawn bbox area for `vehicle` as a fraction of the frame (0 = ungated). */
+	minSpawnAreaFracVehicle: require_dist.number().min(0).max(1).default(0),
+	/** Gate association on a class GROUP ({person,animal}) instead of the exact
+	*  per-frame class, so a person that flips to `animal` for a frame re-matches
+	*  its existing track (no concurrent animal id). Reported label stays via the
+	*  class vote. Off = exact per-frame class gating. */
+	classGroupAssoc: require_dist.boolean().default(true)
 });
 var TRACKING_DEFAULTS = TrackingSettingsSchema.parse({});
 /**
@@ -7972,7 +8096,15 @@ function resolveTrackingSettings(raw) {
 		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)
+		dropoutMaxSkipFrames: s.dropoutMaxSkipFrames.catch(TRACKING_DEFAULTS.dropoutMaxSkipFrames).parse(raw.dropoutMaxSkipFrames),
+		byteTrackEnabled: s.byteTrackEnabled.catch(TRACKING_DEFAULTS.byteTrackEnabled).parse(raw.byteTrackEnabled),
+		byteTrackHighThreshold: s.byteTrackHighThreshold.catch(TRACKING_DEFAULTS.byteTrackHighThreshold).parse(raw.byteTrackHighThreshold),
+		byteTrackLowIouThreshold: s.byteTrackLowIouThreshold.catch(TRACKING_DEFAULTS.byteTrackLowIouThreshold).parse(raw.byteTrackLowIouThreshold),
+		minSpawnAreaEnabled: s.minSpawnAreaEnabled.catch(TRACKING_DEFAULTS.minSpawnAreaEnabled).parse(raw.minSpawnAreaEnabled),
+		minSpawnAreaFracPerson: s.minSpawnAreaFracPerson.catch(TRACKING_DEFAULTS.minSpawnAreaFracPerson).parse(raw.minSpawnAreaFracPerson),
+		minSpawnAreaFracAnimal: s.minSpawnAreaFracAnimal.catch(TRACKING_DEFAULTS.minSpawnAreaFracAnimal).parse(raw.minSpawnAreaFracAnimal),
+		minSpawnAreaFracVehicle: s.minSpawnAreaFracVehicle.catch(TRACKING_DEFAULTS.minSpawnAreaFracVehicle).parse(raw.minSpawnAreaFracVehicle),
+		classGroupAssoc: s.classGroupAssoc.catch(TRACKING_DEFAULTS.classGroupAssoc).parse(raw.classGroupAssoc)
 	};
 }
 //#endregion
@@ -8444,11 +8576,12 @@ function isPlausibleThumbnailBox(bbox, frameWidth, frameHeight) {
 var KEYFRAME_NATIVE_MAX_WIDTH = 1920;
 /**
 * The tracks whose native `keyFrame` should be (re)captured THIS frame: exactly
-* the tracks that hit a new best-frame moment (`bestThumbnail`). `putReplacing`
-* downstream keeps one `keyFrame` per track (the current peak).
+* the tracks that hit a GENUINE new best-frame moment (`keyFrame`), NOT the
+* per-frame best-thumbnail retry. `putReplacing` downstream keeps one `keyFrame`
+* per track (the current peak).
 */
 function selectKeyFrameTrackIds(targets) {
-	return targets.filter((t) => t.bestThumbnail).map((t) => t.trackId);
+	return targets.filter((t) => t.keyFrame).map((t) => t.trackId);
 }
 /**
 * Build the `captureCrop` request for a track's native `keyFrame`: the FULL
@@ -8468,6 +8601,15 @@ function buildKeyFrameCaptureRequest(frameWidth, frameHeight) {
 		maxWidth: KEYFRAME_NATIVE_MAX_WIDTH
 	};
 }
+/**
+* True when a native subject crop of `width` px is a plausible native hit worth
+* keeping, rather than a sub-threshold fallback stamp. Clamps the floor to the
+* requested `maxWidth` so a caller that legitimately asked for a narrow crop
+* (`maxWidth < MIN`) is not rejected for honouring its own cap.
+*/
+function nativeSubjectCropMeetsFloor(width, maxWidth) {
+	return width >= Math.min(320, maxWidth);
+}
 //#endregion
 //#region src/pipeline-analytics/track-retention-sweep.ts
 /**
@@ -9550,6 +9692,7 @@ var FaceRecognizer = class {
 			bbox: input.parentBbox,
 			zones: [],
 			state: "moving",
+			matchedThisFrame: true,
 			embedding: input.embedding,
 			embeddingModelId: modelId,
 			...input.faceBbox !== void 0 ? { faceBbox: input.faceBbox } : {},
@@ -11905,6 +12048,19 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*  (recycled/blank live frame) still gets a subject crop for the gallery
 	*  instead of degrading to a full-scene tile. Cleared on track end + reset. */
 	thumbnailLandedTracks = /* @__PURE__ */ new Set();
+	/** Tracks with a best-`thumbnail` capture CURRENTLY in flight (RC-1). The
+	*  #27-A retry re-fired a fresh best-thumbnail capture every frame while one
+	*  was still resolving (capture latency stacks 0.1–3s under the native path),
+	*  so a short track issued N overlapping captures. While a track sits here
+	*  `buildSnapshotTargets` suppresses a new best-thumbnail request; the pending
+	*  result clears the flag (and, if it landed, sets `thumbnailLandedTracks`).
+	*  Cleared on track end + reset. */
+	thumbnailInFlight = /* @__PURE__ */ new Set();
+	/** Tracks with a native `keyFrame` capture CURRENTLY in flight (RC-1). Guards
+	*  the fire-and-forget `persistKeyFrames` so a burst of new-best frames issues
+	*  at most ONE outstanding 1920px native capture per track instead of one per
+	*  frame. Cleared when the capture settles (+ on track end / reset). */
+	keyFrameInFlight = /* @__PURE__ */ new Set();
 	/** Per-track update-gate memory for `PipelineAnalyticsTrackLifecycle`
 	*  `phase:'update'` — the last-emitted best (confidence / label / crop
 	*  area) + emit time, so a material improvement is measured against the
@@ -11962,7 +12118,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-BiZGDArd.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-B7HfyyIy.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -12146,7 +12302,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				detectionFrameFallbacks: nativeFallbacks
 			} });
 		};
-		const tryNativeCrop = async (frameHandle, paddedNorm, maxWidth) => {
+		const fetchNativeCropRgb = async (frameHandle, paddedNorm, maxWidth) => {
 			if (!pipelineRunnerApi?.getNativeCrop) return null;
 			try {
 				const native = await pipelineRunnerApi.getNativeCrop.query({
@@ -12155,14 +12311,33 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 					...maxWidth !== void 0 ? { maxWidth } : {}
 				}, require_dist.nodePin(frameHandle.nodeId));
 				if (!native || native.width <= 0 || native.height <= 0) return null;
-				return await encodeRgbCropToJpeg(Buffer.from(native.bytes), native.width, native.height);
+				return {
+					bytes: Buffer.from(native.bytes),
+					width: native.width,
+					height: native.height
+				};
 			} catch (err) {
 				cropMetricLogger.debug("native crop request failed — falling back", { meta: { error: require_dist.errMsg(err) } });
 				return null;
 			}
 		};
+		const tryNativeCrop = async (frameHandle, paddedNorm, maxWidth) => {
+			const native = await fetchNativeCropRgb(frameHandle, paddedNorm, maxWidth);
+			if (!native) return null;
+			return await encodeRgbCropToJpeg(native.bytes, native.width, native.height);
+		};
 		const getNativeCropJpeg = async (frameHandle, normalizedBbox, maxWidth) => {
-			const jpeg = await tryNativeCrop(frameHandle, normalizedBbox, maxWidth);
+			const native = await fetchNativeCropRgb(frameHandle, normalizedBbox, maxWidth);
+			if (!native || !nativeSubjectCropMeetsFloor(native.width, maxWidth)) {
+				if (native) cropMetricLogger.debug("native subject crop below floor — local fallback", { meta: {
+					width: native.width,
+					height: native.height,
+					maxWidth
+				} });
+				bumpCropMetric(false);
+				return null;
+			}
+			const jpeg = await encodeRgbCropToJpeg(native.bytes, native.width, native.height);
 			bumpCropMetric(jpeg !== null);
 			return jpeg;
 		};
@@ -12715,6 +12890,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.bestFrameTracker.clear();
 		this.lastFrameAtByTrack.clear();
 		this.thumbnailLandedTracks.clear();
+		this.thumbnailInFlight.clear();
+		this.keyFrameInFlight.clear();
 		this.trackLifecycleUpdateMem.clear();
 		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
@@ -13035,6 +13212,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 					frames: captureAgg.frames,
 					...captureAgg.sums
 				} });
+				const thumbInFlightTrackIds = snapshotTargets.filter((t) => t.bestThumbnail).map((t) => t.trackId);
+				for (const trackId of thumbInFlightTrackIds) this.thumbnailInFlight.add(trackId);
 				this.eventMediaDispatcher.captureForFrame({
 					deviceId,
 					frameHandle,
@@ -13054,7 +13233,9 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						mediaKey: s.mediaKey
 					});
 					for (const trackId of res.thumbnailTrackIds) this.thumbnailLandedTracks.add(trackId);
-				}).catch(() => {});
+				}).catch(() => {}).finally(() => {
+					for (const trackId of thumbInFlightTrackIds) this.thumbnailInFlight.delete(trackId);
+				});
 			}
 		}
 		if (this.faceRecognizer && faceGloballyEnabled && faceSettings) this.faceRecognizer.processFrame({
@@ -13499,7 +13680,10 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		const mediaStore = this.mediaStore;
 		if (!capture || !mediaStore) return;
 		const req = buildKeyFrameCaptureRequest(frameWidth, frameHeight);
-		await Promise.all(trackIds.map(async (trackId) => {
+		const pending = trackIds.filter((id) => !this.keyFrameInFlight.has(id));
+		if (pending.length === 0) return;
+		for (const id of pending) this.keyFrameInFlight.add(id);
+		await Promise.all(pending.map(async (trackId) => {
 			try {
 				const keyFrame = await capture(frameHandle, req.bbox, frameWidth, frameHeight, req.padding, req.maxWidth);
 				if (!keyFrame) return;
@@ -13520,6 +13704,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						error: require_dist.errMsg(err)
 					}
 				});
+			} finally {
+				this.keyFrameInFlight.delete(trackId);
 			}
 		}));
 	}
@@ -13581,6 +13767,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	buildSnapshotTargets(deviceId, tracked, timestamp, media, frameWidth, frameHeight) {
 		const targets = [];
 		for (const t of tracked) {
+			if (t.matchedThisFrame === false) continue;
 			const lastSnap = this.trackStore.lastSnapshotAt(t.trackId);
 			const dueSnapshot = media.saveThumbnails && evaluatePeriodicSnapshot({
 				lastSnapshotAt: lastSnap,
@@ -13612,8 +13799,10 @@ 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);
-			const bestThumbnail = plan.bestThumbnail && isPlausibleThumbnailBox(t.bbox, frameWidth, frameHeight);
-			if (!plan.appendSnapshot && !plan.rollingLastFrame && !bestThumbnail) continue;
+			const plausibleBox = isPlausibleThumbnailBox(t.bbox, frameWidth, frameHeight);
+			const bestThumbnail = plan.bestThumbnail && plausibleBox && !this.thumbnailInFlight.has(t.trackId);
+			const keyFrame = isNewBest && plausibleBox;
+			if (!plan.appendSnapshot && !plan.rollingLastFrame && !bestThumbnail && !keyFrame) continue;
 			targets.push({
 				trackId: t.trackId,
 				timestamp,
@@ -13621,7 +13810,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				...t.label ? { label: t.label } : {},
 				appendSnapshot: plan.appendSnapshot,
 				rollingLastFrame: plan.rollingLastFrame,
-				bestThumbnail
+				bestThumbnail,
+				keyFrame
 			});
 		}
 		return targets;
@@ -13928,6 +14118,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				this.objectEmbeddingBestSelector.delete(t.trackId);
 				this.lastFrameAtByTrack.delete(t.trackId);
 				this.thumbnailLandedTracks.delete(t.trackId);
+				this.thumbnailInFlight.delete(t.trackId);
+				this.keyFrameInFlight.delete(t.trackId);
 				this.detailDispatcher?.onTrackEnded(t.deviceId, t.trackId);
 				this.overlayState.onTrackEnded(t.deviceId, t.trackId);
 				if ((this.trackStore?.getActive(t.deviceId).length ?? 0) === 0) {
@@ -14190,6 +14382,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.objectEmbeddingBestSelector.delete(track.trackId);
 		this.lastFrameAtByTrack.delete(track.trackId);
 		this.thumbnailLandedTracks.delete(track.trackId);
+		this.thumbnailInFlight.delete(track.trackId);
+		this.keyFrameInFlight.delete(track.trackId);
 		this.trackLifecycleUpdateMem.delete(track.trackId);
 		this.detailDispatcher?.onTrackEnded(deviceId, track.trackId);
 		this.overlayState.onTrackEnded(deviceId, track.trackId);
@@ -14240,7 +14434,17 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 					vehicle: trk.minScoreVehicle
 				},
 				confirmBypassEnabled: trk.confirmBypassEnabled,
-				confirmBypassScore: trk.confirmBypassScore
+				confirmBypassScore: trk.confirmBypassScore,
+				byteTrackEnabled: trk.byteTrackEnabled,
+				byteTrackHighThreshold: trk.byteTrackHighThreshold,
+				byteTrackLowIouThreshold: trk.byteTrackLowIouThreshold,
+				minSpawnAreaEnabled: trk.minSpawnAreaEnabled,
+				classSpawnAreaFracs: {
+					person: trk.minSpawnAreaFracPerson,
+					animal: trk.minSpawnAreaFracAnimal,
+					vehicle: trk.minSpawnAreaFracVehicle
+				},
+				classGroupAssoc: trk.classGroupAssoc
 			}, { stationaryThresholdSec }, {
 				minTrackAge,
 				cooldownSec,
@@ -15692,6 +15896,77 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						max: 1,
 						step: .05,
 						default: TRACKING_DEFAULTS.confirmBypassScore
+					},
+					{
+						type: "boolean",
+						key: "byteTrackEnabled",
+						label: "Two-stage association (ByteTrack)",
+						description: "Match high-confidence detections first, then recover coasting tracks with the low-confidence leftovers before they die. The single biggest fix for a subject fragmenting into many tracks. Off = legacy single pass.",
+						default: TRACKING_DEFAULTS.byteTrackEnabled
+					},
+					{
+						type: "number",
+						key: "byteTrackHighThreshold",
+						label: "Two-stage high threshold",
+						description: "Score at/above which a detection is matched in the first stage. Below it a detection is LOW and gets a second, looser recovery match against still-unmatched (coasting) tracks. This does not change which detections can start a track (the spawn confidence/size floors do). Only used with two-stage association.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.byteTrackHighThreshold
+					},
+					{
+						type: "number",
+						key: "byteTrackLowIouThreshold",
+						label: "Two-stage low IoU",
+						description: "Looser overlap gate for re-attaching a low-confidence detection to a coasting track in the second stage. Only used with two-stage association.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.byteTrackLowIouThreshold
+					},
+					{
+						type: "boolean",
+						key: "minSpawnAreaEnabled",
+						label: "Minimum spawn size",
+						description: "Require a new track’s box to cover at least a minimum fraction of the frame before it is created — stops tiny far-field / vanishing-point blips from spawning full tracks. An already-tracked subject that shrinks into the distance is unaffected.",
+						default: TRACKING_DEFAULTS.minSpawnAreaEnabled
+					},
+					{
+						type: "number",
+						key: "minSpawnAreaFracPerson",
+						label: "Min spawn area — person",
+						description: "Smallest person box (as a fraction of the frame area) allowed to start a NEW track. 0 = ungated. Conservative default (0.0005 = 0.05% of frame) drops only vanishing-point noise. Raise on cameras with a distant road / horizon.",
+						min: 0,
+						max: 1,
+						step: 5e-4,
+						default: TRACKING_DEFAULTS.minSpawnAreaFracPerson
+					},
+					{
+						type: "number",
+						key: "minSpawnAreaFracAnimal",
+						label: "Min spawn area — animal",
+						description: "Smallest animal box (fraction of frame area) allowed to start a NEW track. 0 = ungated (animal already has a spawn-score floor).",
+						min: 0,
+						max: 1,
+						step: 5e-4,
+						default: TRACKING_DEFAULTS.minSpawnAreaFracAnimal
+					},
+					{
+						type: "number",
+						key: "minSpawnAreaFracVehicle",
+						label: "Min spawn area — vehicle",
+						description: "Smallest vehicle box (fraction of frame area) allowed to start a NEW track. 0 = ungated (vehicle already has a spawn-score floor).",
+						min: 0,
+						max: 1,
+						step: 5e-4,
+						default: TRACKING_DEFAULTS.minSpawnAreaFracVehicle
+					},
+					{
+						type: "boolean",
+						key: "classGroupAssoc",
+						label: "Person/animal group matching",
+						description: "Let a detection that flips between person and animal for a frame (a crouching / bending person is often read as an animal) re-match its existing track instead of spawning a concurrent animal track. The reported class is still decided by the per-track class vote.",
+						default: TRACKING_DEFAULTS.classGroupAssoc
 					}
 				]
 			},