@camstack/addon-post-analysis 1.1.23 → 1.1.25

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { C as object, S as number, c as pipelineAnalyticsCapability, d as zoneAnalyticsCapability, f as errMsg, h as EventCategory, i as cosineSimilarity, l as plateGalleryCapability, m as DeviceType, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as BaseAddon, r as audioMetricsCapability, t as EVENT_PAD_MS, u as videoclipsCapability, v as hydrateSchema, w as string, x as boolean } from "../dist-DiIUcFdN.mjs";
+import { C as object, S as number, c as pipelineAnalyticsCapability, d as zoneAnalyticsCapability, f as errMsg, h as EventCategory, i as cosineSimilarity, l as plateGalleryCapability, m as DeviceType, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as BaseAddon, r as audioMetricsCapability, t as EVENT_PAD_MS, u as videoclipsCapability, v as hydrateSchema, w as string, x as boolean } from "../dist-Csk_yJr_.mjs";
 import { n as extractCrop, t as resolveFrame } from "../resolve-frame-CT1T1tWy.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 import sharp from "sharp";
@@ -694,17 +694,24 @@ function normalizeToPixel(p, width, height) {
 //#region src/pipeline-analytics/pipeline/tracker/sort-tracker.ts
 var DEFAULT_TRACKER_CONFIG = {
 	iouThreshold: .3,
-	maxMissedFrames: 30,
+	maxMissedMs: 4e3,
 	minHits: 3,
 	predictiveCoasting: true,
 	classGating: true,
 	occlusionEnabled: true,
 	occlusionContainment: .6,
-	occlusionMaxMissedFrames: 60,
-	maxTrackLifetimeMs: 3e5
+	occlusionMaxMissedMs: 8e3,
+	maxTrackLifetimeMs: 3e5,
+	rescueIouThreshold: .1,
+	rescueCentroidFactor: .75,
+	resurrectionWindowMs: 8e3,
+	stationarySpeedPx: 2
 };
 var MAX_PATH_LENGTH = 300;
 var nextTrackId = 1;
+function clamp(value, min, max) {
+	return Math.max(min, Math.min(max, value));
+}
 function iou$1(a, b) {
 	const ax1 = a.x, ay1 = a.y, ax2 = a.x + a.w, ay2 = a.y + a.h;
 	const bx1 = b.x, by1 = b.y, bx2 = b.x + b.w, by2 = b.y + b.h;
@@ -734,26 +741,51 @@ var SortTracker = class {
 		};
 	}
 	/** Where a track is expected this frame — extrapolated by velocity while
-	*  coasting (predictiveCoasting), else its last known bbox. */
+	*  coasting (predictiveCoasting), else its last known bbox. A stationary
+	*  track (speed < stationarySpeedPx) is frozen so bbox jitter can't walk the
+	*  box off a sitting object; otherwise the drift is capped at one bbox size
+	*  so a stale velocity can't fling the box across the frame. Public so the
+	*  clamp is directly unit-testable. */
 	predicted(t) {
 		if (!this.config.predictiveCoasting) return t.bbox;
+		if (Math.hypot(t.velocity.dx, t.velocity.dy) < this.config.stationarySpeedPx) return t.bbox;
 		const f = t.age + 1;
+		const driftX = clamp(t.velocity.dx * f, -t.bbox.w, t.bbox.w);
+		const driftY = clamp(t.velocity.dy * f, -t.bbox.h, t.bbox.h);
 		return {
-			x: t.bbox.x + t.velocity.dx * f,
-			y: t.bbox.y + t.velocity.dy * f,
+			x: t.bbox.x + driftX,
+			y: t.bbox.y + driftY,
 			w: t.bbox.w,
 			h: t.bbox.h
 		};
 	}
+	/**
+	* Loose same-class 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`.
+	*/
+	looseMatch(track, det) {
+		if (track.class !== det.class) return false;
+		if (iou$1(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return true;
+		const tc = bboxCentroid(track.bbox);
+		const dc = bboxCentroid(det.bbox);
+		const dist = Math.hypot(tc.x - dc.x, tc.y - dc.y);
+		const diag = Math.hypot(track.bbox.w, track.bbox.h);
+		return dist <= this.config.rescueCentroidFactor * diag;
+	}
 	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();
@@ -778,6 +810,27 @@ var SortTracker = class {
 			matchedTracks.add(pair.track);
 			used.add(pair.detIdx);
 		}
+		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;
+				const det = detections[di];
+				if (!this.looseMatch(track, det)) continue;
+				rescuePairs.push({
+					track,
+					detIdx: di,
+					score: iou$1(track.bbox, det.bbox)
+				});
+			}
+		}
+		rescuePairs.sort((a, b) => b.score - a.score);
+		for (const pair of rescuePairs) {
+			if (matchedTracks.has(pair.track) || used.has(pair.detIdx)) continue;
+			matched.set(pair.track, detections[pair.detIdx]);
+			matchedTracks.add(pair.track);
+			used.add(pair.detIdx);
+		}
 		for (const [track, det] of matched) {
 			const prevCenter = bboxCentroid({
 				x: track.bbox.x,
@@ -816,12 +869,47 @@ var SortTracker = class {
 			}
 			const occluded = this.config.occlusionEnabled && occluderBoxes.some((ob) => containment(this.predicted(track), ob) >= this.config.occlusionContainment);
 			track.age++;
-			const limit = occluded ? this.config.occlusionMaxMissedFrames : this.config.maxMissedFrames;
-			if (track.age > limit) {
+			if (timestamp - track.lastSeen > (occluded ? this.config.occlusionMaxMissedMs : this.config.maxMissedMs)) {
 				track.lost = true;
+				track.lostAt = timestamp;
+				track.resurrectable = true;
 				this.lostTracks.push(track);
 			} else surviving.push(track);
 		}
+		for (let di = 0; di < detections.length; di++) {
+			if (used.has(di)) continue;
+			const det = detections[di];
+			let best;
+			let bestScore = -1;
+			for (const lost of this.lostTracks) {
+				if (!lost.resurrectable) continue;
+				if (timestamp - lost.lostAt > this.config.resurrectionWindowMs) continue;
+				if (!this.looseMatch(lost, det)) continue;
+				const score = iou$1(lost.bbox, det.bbox);
+				if (score > bestScore) {
+					best = lost;
+					bestScore = score;
+				}
+			}
+			if (!best) continue;
+			this.lostTracks = this.lostTracks.filter((t) => t !== best);
+			best.bbox = det.bbox;
+			best.class = det.class;
+			best.originalClass = det.originalClass;
+			best.score = det.score;
+			best.age = 0;
+			best.hits++;
+			best.lost = false;
+			best.lastSeen = timestamp;
+			best.velocity = {
+				dx: 0,
+				dy: 0
+			};
+			best.path.push(det.bbox);
+			if (best.path.length > MAX_PATH_LENGTH) best.path.shift();
+			surviving.push(best);
+			used.add(di);
+		}
 		for (let di = 0; di < detections.length; di++) {
 			if (used.has(di)) continue;
 			const det = detections[di];
@@ -841,7 +929,9 @@ var SortTracker = class {
 					dx: 0,
 					dy: 0
 				},
-				lost: false
+				lost: false,
+				lostAt: 0,
+				resurrectable: true
 			});
 		}
 		this.tracks = surviving;
@@ -956,6 +1046,7 @@ var StateAnalyzer = class {
 //#region src/pipeline-analytics/pipeline/events/event-filter.ts
 var DEFAULT_EVENT_EMITTER_CONFIG = {
 	minTrackAge: 3,
+	minTrackAgeMs: 0,
 	cooldownSec: 5,
 	enabledTypes: [
 		"object.entering",
@@ -986,6 +1077,13 @@ var DetectionEventEmitter = class {
 	config;
 	previousStates = /* @__PURE__ */ new Map();
 	lastEmitted = /* @__PURE__ */ new Map();
+	/**
+	* Last-known track per id. A `leaving` state fires for a track that is ABSENT
+	* from the current frame, so it can't be resolved from `trackMap` — it is
+	* resolved from this snapshot instead (without it, leaving events never
+	* fired: the latent "0 `left` events in 24h" bug).
+	*/
+	lastKnownTracks = /* @__PURE__ */ new Map();
 	constructor(config = {}) {
 		this.config = {
 			...DEFAULT_EVENT_EMITTER_CONFIG,
@@ -997,10 +1095,12 @@ var DetectionEventEmitter = class {
 		const now = Date.now();
 		const stateMap = new Map(states.map((s) => [s.trackId, s]));
 		const trackMap = new Map(tracks.map((t) => [t.trackId, t]));
+		for (const t of tracks) this.lastKnownTracks.set(t.trackId, t);
 		for (const state of states) {
-			const track = trackMap.get(state.trackId);
+			const track = trackMap.get(state.trackId) ?? this.lastKnownTracks.get(state.trackId);
 			if (!track) continue;
 			if (track.trackAge < this.config.minTrackAge) continue;
+			if (state.dwellTimeMs < this.config.minTrackAgeMs) continue;
 			const eventType = STATE_TO_EVENT[state.state];
 			if (!eventType) continue;
 			if (!this.config.enabledTypes.includes(eventType)) continue;
@@ -1046,12 +1146,16 @@ var DetectionEventEmitter = class {
 				trackPath: [...track.path]
 			});
 		}
-		for (const state of states) if (state.state === "leaving") this.previousStates.delete(state.trackId);
+		for (const state of states) if (state.state === "leaving") {
+			this.previousStates.delete(state.trackId);
+			this.lastKnownTracks.delete(state.trackId);
+		}
 		return events;
 	}
 	reset() {
 		this.previousStates.clear();
 		this.lastEmitted.clear();
+		this.lastKnownTracks.clear();
 	}
 };
 //#endregion
@@ -1423,6 +1527,43 @@ var FrameProcessor = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/pipeline/best-detection-tracker.ts
+var BestDetectionTracker = class {
+	hysteresis;
+	minGapMs;
+	best = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.hysteresis = options.hysteresis ?? 0;
+		this.minGapMs = options.minGapMs ?? 0;
+	}
+	/**
+	* Record a detection's `confidence` (at wall-clock `timestamp`) for `trackId`.
+	* Returns true when it becomes the track's new best — the first sighting, or a
+	* confidence that beats the held peak by more than `hysteresis` AND respects
+	* `minGapMs`. On acceptance the held peak is advanced to this observation.
+	*/
+	observe(trackId, confidence, timestamp) {
+		const cur = this.best.get(trackId);
+		const isNewBest = cur === void 0 || confidence > cur.confidence + this.hysteresis && timestamp - cur.atMs >= this.minGapMs;
+		if (isNewBest) this.best.set(trackId, {
+			confidence,
+			atMs: timestamp
+		});
+		return isNewBest;
+	}
+	/** The held peak for a track (undefined if never observed). */
+	peak(trackId) {
+		return this.best.get(trackId);
+	}
+	/** Drop a track's peak (call at track end). */
+	delete(trackId) {
+		this.best.delete(trackId);
+	}
+	clear() {
+		this.best.clear();
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/pipeline/native-detection.ts
 /**
 * Nominal frame size used to denormalize native `[0,1]` boxes when a
@@ -1692,6 +1833,16 @@ var TrackStore = class {
 	lastSnapshotAt(trackId) {
 		return this.active.get(trackId)?.lastSnapshotAt ?? 0;
 	}
+	/**
+	* Seed the snapshot cadence clock (once, at track start) WITHOUT appending a
+	* snapshot, so the first periodic snapshot fires ~snapshotIntervalMs after the
+	* track begins rather than immediately — the `firstFrame` already covers the
+	* track's start. No-op if a snapshot was already taken (clock already set).
+	*/
+	seedSnapshotClock(trackId, timestamp) {
+		const t = this.active.get(trackId);
+		if (t && t.lastSnapshotAt === 0) t.lastSnapshotAt = timestamp;
+	}
 	getActive(deviceId) {
 		const out = [];
 		for (const t of this.active.values()) if (t.deviceId === deviceId && t.active) out.push(cloneTrack(t));
@@ -1956,6 +2107,46 @@ 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.
+	*/
+	async putReplacing(params) {
+		const existing = await this.store.query.query({
+			collection: MEDIA_COLLECTION,
+			filter: { where: {
+				ownerKind: params.ownerKind,
+				ownerId: params.ownerId,
+				kind: params.kind
+			} }
+		});
+		const newKey = await this.put(params);
+		for (const row of existing) {
+			if (row.id === newKey) continue;
+			const path = String(row.data["path"] ?? "");
+			if (path) try {
+				await this.storage.delete({
+					location: "eventMedia",
+					relativePath: path
+				});
+			} catch {}
+			try {
+				await this.store.delete.mutate({
+					collection: MEDIA_COLLECTION,
+					key: row.id
+				});
+			} catch (err) {
+				this.logger.debug("media putReplacing: stale row delete failed", { meta: {
+					key: row.id,
+					error: String(err)
+				} });
+			}
+		}
+		return newKey;
+	}
+	/**
 	* Fetch one media entry by its key (id). Returns null if the key is not
 	* found in the index or if the blob is missing from storage.
 	*/
@@ -2868,7 +3059,9 @@ var EventMediaDispatcher = class {
 	}
 	async captureForFrame(input) {
 		const { deviceId, frameHandle, events, trackFrames } = input;
-		if (events.length === 0 && trackFrames.length === 0) return;
+		const snapshots = input.snapshots ?? [];
+		const empty = { storedSnapshots: [] };
+		if (events.length === 0 && trackFrames.length === 0 && snapshots.length === 0) return empty;
 		let decoded;
 		try {
 			decoded = await resolveFrame(frameHandle, {
@@ -2885,7 +3078,7 @@ var EventMediaDispatcher = class {
 					error: String(err)
 				}
 			});
-			return;
+			return empty;
 		}
 		if (!decoded) {
 			this.deps.logger.debug("event media: frame recycled before resolve", {
@@ -2895,7 +3088,7 @@ var EventMediaDispatcher = class {
 					shmId: frameHandle.shmId
 				}
 			});
-			return;
+			return empty;
 		}
 		if (decoded.format !== "rgb") {
 			this.deps.logger.debug("event media: resolved frame is not RGB", {
@@ -2905,13 +3098,87 @@ var EventMediaDispatcher = class {
 					format: decoded.format
 				}
 			});
-			return;
+			return empty;
 		}
 		const frameData = Buffer.isBuffer(decoded.data) ? decoded.data : Buffer.from(decoded.data);
 		const fw = decoded.width;
 		const fh = decoded.height;
 		for (const ev of events) await this.writeEventMedia(deviceId, frameData, fw, fh, ev, input.cropPadding);
 		for (const tf of trackFrames) await this.writeTrackFrame(deviceId, frameData, fw, fh, tf);
+		const storedSnapshots = [];
+		for (const sn of snapshots) {
+			const stored = await this.writeTrackSnapshot(deviceId, frameData, fw, fh, sn);
+			if (stored) storedSnapshots.push(stored);
+		}
+		return { storedSnapshots };
+	}
+	/**
+	* Periodic per-track media (§5). Encodes the boxed frame ONCE and fans it out
+	* to whichever of the three destinations is requested: an appended `snapshot`
+	* (timeline filmstrip), the rolling `lastFrame` (overwrite), and the best
+	* `thumbnail` (overwrite). Returns the appended snapshot for TrackStore wiring
+	* (null when `appendSnapshot` is false or the encode failed).
+	*/
+	async writeTrackSnapshot(deviceId, frameData, fw, fh, sn) {
+		if (!sn.appendSnapshot && !sn.rollingLastFrame && !sn.bestThumbnail) return null;
+		let boxed;
+		try {
+			boxed = await drawBoxedFrame(frameData, fw, fh, [{
+				...sn.bbox,
+				...sn.label ? { label: sn.label } : {}
+			}], { quality: MEDIA_QUALITY });
+		} catch (err) {
+			this.deps.logger.warn("event media: track snapshot encode failed", {
+				tags: { deviceId },
+				meta: {
+					deviceId,
+					trackId: sn.trackId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			return null;
+		}
+		let stored = null;
+		if (sn.appendSnapshot) try {
+			const mediaKey = await this.deps.mediaStore.put({
+				deviceId,
+				ownerKind: "track",
+				ownerId: sn.trackId,
+				kind: "snapshot",
+				timestamp: sn.timestamp,
+				data: boxed
+			});
+			stored = {
+				trackId: sn.trackId,
+				mediaKey,
+				timestamp: sn.timestamp,
+				bbox: sn.bbox
+			};
+		} catch {}
+		if (sn.rollingLastFrame) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
+		if (sn.bestThumbnail) await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, boxed);
+		return stored;
+	}
+	async replaceKind(deviceId, trackId, kind, timestamp, data) {
+		try {
+			await this.deps.mediaStore.putReplacing({
+				deviceId,
+				ownerKind: "track",
+				ownerId: trackId,
+				kind,
+				timestamp,
+				data
+			});
+		} catch (err) {
+			this.deps.logger.debug(`event media: ${kind} replace failed`, {
+				tags: { deviceId },
+				meta: {
+					deviceId,
+					trackId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
 	}
 	async writeEventMedia(deviceId, frameData, fw, fh, ev, cropPadding) {
 		const box = {
@@ -3772,22 +4039,22 @@ function resolveDetectionSensitivitySettings(raw) {
 		stationaryThresholdSec: pick("stationaryThresholdSec")
 	};
 }
-//#endregion
-//#region src/pipeline-analytics/tracking-settings.ts
-/**
-* Per-device tracker tuning. These drive the SORT tracker (association,
-* coasting, occlusion, lifetime) and the detector-dropout frame skip. Every
-* field is independently overridable per camera from the admin UI; unknown or
-* invalid values fall back to the field default (never throws on a bad blob).
-*
-* Note: `minHits` lives in detection-sensitivity-settings (it predates this
-* file and already flows to the tracker) — it is NOT duplicated here.
-*/
 var TrackingSettingsSchema = object({
 	/** IoU required to match a (predicted) track to a detection. */
 	iouThreshold: number().min(0).max(1).default(.3),
-	/** Frames a track may miss detections (coast) before it is dropped. */
+	/** Wall-clock coasting budget (ms) before a missed track is dropped. Time-
+	*  based so behaviour is identical across camera frame rates. */
+	maxMissedMs: number().min(0).default(4e3),
+	/** Minimum wall-clock track age (ms) before it may produce events. */
+	minTrackAgeMs: number().min(0).default(1e3),
+	/** Extended coasting budget (ms) while a track is occluded. */
+	occlusionMaxMissedMs: number().min(0).default(8e3),
+	/** @deprecated frame-based alias for {@link maxMissedMs}. Retained so
+	*  existing per-device blobs keep working — resolved into `maxMissedMs`
+	*  (× {@link NOMINAL_FRAME_MS}) only when `maxMissedMs` is unset. */
 	maxMissedFrames: number().int().min(0).default(30),
+	/** @deprecated frame-based alias for {@link occlusionMaxMissedMs}. */
+	occlusionMaxMissedFrames: number().int().min(0).default(60),
 	/** Hard cap on total track lifetime — retire+restart beyond this to bound
 	*  drift / long-lived false positives. 0 = unlimited. */
 	maxTrackLifetimeSec: number().min(0).default(300),
@@ -3801,8 +4068,17 @@ var TrackingSettingsSchema = object({
 	/** Containment ratio (intersection / occluded-area) above which a missed
 	*  track is considered hidden behind another track. */
 	occlusionContainment: number().min(0).max(1).default(.6),
-	/** Extended coasting budget (frames) while a track is occluded. */
-	occlusionMaxMissedFrames: number().int().min(0).default(60),
+	/** Loose IoU gate (vs. last-known bbox) for the second (rescue) association
+	*  pass + graveyard resurrection. */
+	rescueIouThreshold: number().min(0).max(1).default(.1),
+	/** Centroid gate for rescue/resurrection: fraction of the bbox diagonal. */
+	rescueCentroidFactor: number().min(0).default(.75),
+	/** Wall-clock graveyard retention (ms): a dropped track re-attaches to a new
+	*  same-class detection (keeping its id) for this long. */
+	resurrectionWindowMs: number().min(0).default(8e3),
+	/** Speed (px/frame) below which a track's prediction is frozen (stationary
+	*  jitter can't drift the box off a sitting object). */
+	stationarySpeedPx: number().min(0).default(2),
 	/** Skip frames where detections suddenly drop to zero (detector glitch). */
 	dropoutSkipEnabled: boolean().default(true),
 	/** Max consecutive all-zero frames absorbed as a glitch before the scene is
@@ -3817,15 +4093,26 @@ var TRACKING_DEFAULTS = TrackingSettingsSchema.parse({});
 */
 function resolveTrackingSettings(raw) {
 	const s = TrackingSettingsSchema.shape;
+	const maxMissedFrames = s.maxMissedFrames.catch(TRACKING_DEFAULTS.maxMissedFrames).parse(raw.maxMissedFrames);
+	const occlusionMaxMissedFrames = s.occlusionMaxMissedFrames.catch(TRACKING_DEFAULTS.occlusionMaxMissedFrames).parse(raw.occlusionMaxMissedFrames);
+	const maxMissedMs = raw.maxMissedMs !== void 0 ? s.maxMissedMs.catch(TRACKING_DEFAULTS.maxMissedMs).parse(raw.maxMissedMs) : raw.maxMissedFrames !== void 0 ? Math.round(maxMissedFrames * 133) : TRACKING_DEFAULTS.maxMissedMs;
+	const occlusionMaxMissedMs = raw.occlusionMaxMissedMs !== void 0 ? s.occlusionMaxMissedMs.catch(TRACKING_DEFAULTS.occlusionMaxMissedMs).parse(raw.occlusionMaxMissedMs) : raw.occlusionMaxMissedFrames !== void 0 ? Math.round(occlusionMaxMissedFrames * 133) : TRACKING_DEFAULTS.occlusionMaxMissedMs;
 	return {
 		iouThreshold: s.iouThreshold.catch(TRACKING_DEFAULTS.iouThreshold).parse(raw.iouThreshold),
-		maxMissedFrames: s.maxMissedFrames.catch(TRACKING_DEFAULTS.maxMissedFrames).parse(raw.maxMissedFrames),
+		maxMissedMs,
+		minTrackAgeMs: s.minTrackAgeMs.catch(TRACKING_DEFAULTS.minTrackAgeMs).parse(raw.minTrackAgeMs),
+		occlusionMaxMissedMs,
+		maxMissedFrames,
+		occlusionMaxMissedFrames,
 		maxTrackLifetimeSec: s.maxTrackLifetimeSec.catch(TRACKING_DEFAULTS.maxTrackLifetimeSec).parse(raw.maxTrackLifetimeSec),
 		predictiveCoasting: s.predictiveCoasting.catch(TRACKING_DEFAULTS.predictiveCoasting).parse(raw.predictiveCoasting),
 		classGating: s.classGating.catch(TRACKING_DEFAULTS.classGating).parse(raw.classGating),
 		occlusionEnabled: s.occlusionEnabled.catch(TRACKING_DEFAULTS.occlusionEnabled).parse(raw.occlusionEnabled),
 		occlusionContainment: s.occlusionContainment.catch(TRACKING_DEFAULTS.occlusionContainment).parse(raw.occlusionContainment),
-		occlusionMaxMissedFrames: s.occlusionMaxMissedFrames.catch(TRACKING_DEFAULTS.occlusionMaxMissedFrames).parse(raw.occlusionMaxMissedFrames),
+		rescueIouThreshold: s.rescueIouThreshold.catch(TRACKING_DEFAULTS.rescueIouThreshold).parse(raw.rescueIouThreshold),
+		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),
 		dropoutSkipEnabled: s.dropoutSkipEnabled.catch(TRACKING_DEFAULTS.dropoutSkipEnabled).parse(raw.dropoutSkipEnabled),
 		dropoutMaxSkipFrames: s.dropoutMaxSkipFrames.catch(TRACKING_DEFAULTS.dropoutMaxSkipFrames).parse(raw.dropoutMaxSkipFrames)
 	};
@@ -3886,11 +4173,20 @@ function resolveFaceSettings(raw) {
 * its default — parse never throws). Mirrors `face-settings` /
 * `audio-detection-settings`.
 */
-var MediaSettingsSchema = object({ 
-/** Fractional padding added around a detection bbox before cropping.
-*  0 = tight crop, 0.15 = expand each side by 15% of the box dimension,
-*  max 2 (200%). */
-cropPadding: number().min(0).max(2).default(.15) });
+var MediaSettingsSchema = object({
+	/** Fractional padding added around a detection bbox before cropping.
+	*  0 = tight crop, 0.15 = expand each side by 15% of the box dimension,
+	*  max 2 (200%). */
+	cropPadding: number().min(0).max(2).default(.15),
+	/** Master switch for periodic per-track snapshots (the timeline filmstrip +
+	*  the rolling `lastFrame` + the best `thumbnail`). When false, only the
+	*  per-track `firstFrame` and per-event media are produced. */
+	saveThumbnails: boolean().default(true),
+	/** Cadence (ms) for the periodic per-track `snapshot` + rolling `lastFrame`.
+	*  A snapshot is captured for an active track only after this much wall-clock
+	*  has elapsed since its previous one. */
+	snapshotIntervalMs: number().int().min(500).max(6e4).default(5e3)
+});
 var MEDIA_DEFAULTS = MediaSettingsSchema.parse({});
 /**
 * Resolve a per-device store blob into typed media settings. Unknown/invalid
@@ -3901,7 +4197,11 @@ function resolveMediaSettings(raw) {
 		const parsed = MediaSettingsSchema.shape[key].safeParse(raw[key]);
 		return parsed.success ? parsed.data : MEDIA_DEFAULTS[key];
 	};
-	return { cropPadding: pick("cropPadding") };
+	return {
+		cropPadding: pick("cropPadding"),
+		saveThumbnails: pick("saveThumbnails"),
+		snapshotIntervalMs: pick("snapshotIntervalMs")
+	};
 }
 //#endregion
 //#region src/pipeline-analytics/store/identity-store.ts
@@ -4797,6 +5097,11 @@ var FaceRecognizer = class {
 	names = /* @__PURE__ */ new Map();
 	aggregates = /* @__PURE__ */ new Map();
 	bestFace = /* @__PURE__ */ new Map();
+	/** The ONE best-detection-per-track policy, shared with the best-frame path
+	*  (`index.ts`). Face params: no hysteresis / no rate-limit — always keep the
+	*  true highest-confidence face (holding a buffer in memory is cheap, and a
+	*  track may last well under the best-frame rate-limit window). */
+	bestTracker = new BestDetectionTracker();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -4830,55 +5135,25 @@ var FaceRecognizer = class {
 			threshold: settings.similarityThreshold,
 			margin: settings.margin
 		}) : /* @__PURE__ */ new Map();
+		const labelWork = [];
 		for (const c of candidates) {
 			const match = matches.get(c.trackId) ?? null;
 			const { state, changed } = updateTrackAggregate(this.aggregates.get(c.trackId) ?? EMPTY_AGGREGATE, match, { confirmFrames: settings.confirmFrames });
 			this.aggregates.set(c.trackId, state);
-			if (changed && state.assignedIdentityId !== null) {
-				const name = this.names.get(state.assignedIdentityId);
-				this.deps.logger.info("face: identity assigned", {
-					tags: {
-						deviceId: input.deviceId,
-						trackId: c.trackId
-					},
-					meta: {
-						identityId: state.assignedIdentityId,
-						name: name ?? null,
-						score: match?.score ?? null
-					}
-				});
-				if (name !== void 0) {
-					try {
-						await this.deps.trackStore.setLabel(c.trackId, name);
-					} catch (err) {
-						this.deps.logger.warn("setLabel failed", {
-							tags: { deviceId: input.deviceId },
-							meta: {
-								trackId: c.trackId,
-								error: String(err)
-							}
-						});
-					}
-					try {
-						await this.deps.eventStore.setLabelForTrack(c.trackId, name);
-					} catch (err) {
-						this.deps.logger.warn("setLabelForTrack failed", {
-							tags: { deviceId: input.deviceId },
-							meta: {
-								trackId: c.trackId,
-								error: String(err)
-							}
-						});
-					}
-				}
-			}
+			if (changed && state.assignedIdentityId !== null) labelWork.push({
+				trackId: c.trackId,
+				assignedIdentityId: state.assignedIdentityId,
+				matchScore: match?.score ?? null
+			});
 			const recognizedIdentityId = state.assignedIdentityId ?? match?.identityId ?? void 0;
 			const held = this.bestFace.get(c.trackId);
-			if (held === void 0 || c.confidence > held.score) {
+			const isNewBest = this.bestTracker.observe(c.trackId, c.confidence, input.timestamp);
+			const needsCrop = held !== void 0 && held.crop === void 0;
+			if (isNewBest || needsCrop) {
 				const cropBbox = c.faceBbox ?? c.bbox;
 				let crop;
-				if (input.frameHandle !== void 0) try {
-					crop = await this.deps.captureCrop(input.frameHandle, cropBbox, input.frameWidth, input.frameHeight, input.cropPadding) ?? void 0;
+				if (c.faceBbox !== void 0 && input.frameHandle !== void 0) try {
+					crop = await this.deps.captureCrop(input.frameHandle, c.faceBbox, input.frameWidth, input.frameHeight, input.cropPadding) ?? void 0;
 				} catch (err) {
 					this.deps.logger.debug("FaceRecognizer crop capture failed", {
 						tags: { deviceId: input.deviceId },
@@ -4888,14 +5163,20 @@ var FaceRecognizer = class {
 						}
 					});
 				}
-				this.bestFace.set(c.trackId, {
-					score: c.confidence,
-					embedding: c.embedding,
-					embeddingModelId: c.embeddingModelId,
-					bbox: cropBbox,
-					timestamp: input.timestamp,
-					...crop !== void 0 ? { crop } : {},
-					...recognizedIdentityId !== void 0 ? { recognizedIdentityId } : {}
+				if (isNewBest) {
+					const bestCrop = crop ?? held?.crop;
+					this.bestFace.set(c.trackId, {
+						score: c.confidence,
+						embedding: c.embedding,
+						embeddingModelId: c.embeddingModelId,
+						bbox: cropBbox,
+						timestamp: input.timestamp,
+						...bestCrop !== void 0 ? { crop: bestCrop } : {},
+						...recognizedIdentityId !== void 0 ? { recognizedIdentityId } : {}
+					});
+				} else if (crop !== void 0 && held !== void 0) this.bestFace.set(c.trackId, {
+					...held,
+					crop
 				});
 				this.deps.logger.debug("face: best-face held", {
 					tags: {
@@ -4904,15 +5185,53 @@ var FaceRecognizer = class {
 					},
 					meta: {
 						score: c.confidence,
-						hasCrop: crop !== void 0,
+						isNewBest,
+						hasCrop: this.bestFace.get(c.trackId)?.crop !== void 0,
 						recognizedIdentityId: recognizedIdentityId ?? null
 					}
 				});
-			} else if (recognizedIdentityId !== void 0 && held.recognizedIdentityId === void 0) this.bestFace.set(c.trackId, {
+			} else if (held !== void 0 && recognizedIdentityId !== void 0 && held.recognizedIdentityId === void 0) this.bestFace.set(c.trackId, {
 				...held,
 				recognizedIdentityId
 			});
 		}
+		for (const work of labelWork) {
+			const name = this.names.get(work.assignedIdentityId);
+			this.deps.logger.info("face: identity assigned", {
+				tags: {
+					deviceId: input.deviceId,
+					trackId: work.trackId
+				},
+				meta: {
+					identityId: work.assignedIdentityId,
+					name: name ?? null,
+					score: work.matchScore
+				}
+			});
+			if (name === void 0) continue;
+			try {
+				await this.deps.trackStore.setLabel(work.trackId, name);
+			} catch (err) {
+				this.deps.logger.warn("setLabel failed", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						trackId: work.trackId,
+						error: String(err)
+					}
+				});
+			}
+			try {
+				await this.deps.eventStore.setLabelForTrack(work.trackId, name);
+			} catch (err) {
+				this.deps.logger.warn("setLabelForTrack failed", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						trackId: work.trackId,
+						error: String(err)
+					}
+				});
+			}
+		}
 	}
 	/**
 	* Persist the held best face for a finished track as ONE FaceStore buffer
@@ -4923,6 +5242,7 @@ var FaceRecognizer = class {
 		const held = this.bestFace.get(trackId);
 		this.aggregates.delete(trackId);
 		this.bestFace.delete(trackId);
+		this.bestTracker.delete(trackId);
 		if (held === void 0) {
 			this.deps.logger.debug("face: track ended without a held face", { tags: {
 				deviceId,
@@ -5598,6 +5918,12 @@ function createEventMediaHandler(deps) {
 */
 var TTL_SWEEP_INTERVAL_MS = 5e3;
 var SETTINGS_CACHE_TTL_MS = 5e3;
+/** §5 best-frame: a track's `thumbnail` is overwritten only when the current
+*  detection confidence beats the held best by at least this margin (hysteresis
+*  so jitter around a plateau doesn't churn the write). */
+var BEST_FRAME_HYSTERESIS = .05;
+/** §5 best-frame: at most one best-thumbnail capture per this interval per track. */
+var BEST_FRAME_MIN_GAP_MS = 2e3;
 /** Cluster setting key (in the centralized addon store) selecting the SINGLE
 *  node that runs post-analysis (event/media/audio/motion generation). All
 *  other nodes are fully inert. No multi-node balancing. Default: the hub. */
@@ -5709,6 +6035,14 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	mediaCacheByDevice = /* @__PURE__ */ new Map();
 	/** Consecutive detector-dropout frames skipped per (deviceId, source) key. */
 	dropoutSkipsByKey = /* @__PURE__ */ new Map();
+	/** Best (highest-confidence) frame per track — drives the single overwrite
+	*  `thumbnail` (§5 best-frame). Shares the ONE best-detection policy with the
+	*  face path (`face-recognizer.ts`); rate-limited here since each best-frame
+	*  capture re-encodes a full boxed frame. */
+	bestFrameTracker = new BestDetectionTracker({
+		hysteresis: BEST_FRAME_HYSTERESIS,
+		minGapMs: BEST_FRAME_MIN_GAP_MS
+	});
 	shuttingDown = false;
 	/** True only on the cluster's designated post-processing node. When false the
 	*  addon subscribes to NOTHING — fully inert (no event/media generation). */
@@ -6252,6 +6586,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.processors.clear();
 		this.lastActiveTrackIds.clear();
 		this.dropoutSkipsByKey.clear();
+		this.bestFrameTracker.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
@@ -6358,12 +6693,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					className: t.className,
 					source
 				} });
-				if (this.eventMediaDispatcher && frameHandle) firstFrameTargets.push({
-					trackId: id,
-					timestamp: result.timestamp,
-					bbox: { ...t.bbox },
-					...t.label ? { label: t.label } : {}
-				});
+				if (this.eventMediaDispatcher && frameHandle) {
+					firstFrameTargets.push({
+						trackId: id,
+						timestamp: result.timestamp,
+						bbox: { ...t.bbox },
+						...t.label ? { label: t.label } : {}
+					});
+					this.trackStore.seedSnapshotClock(id, result.timestamp);
+				}
 				this.ctx.eventBus.emit({
 					id: `pa-${randomUUID()}`,
 					timestamp: new Date(result.timestamp),
@@ -6436,11 +6774,13 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			let plateCrops = 0;
 			for (const crops of childCropsByEvent.values()) for (const c of crops) if (c.kind === "faceCrop") faceCrops += 1;
 			else plateCrops += 1;
-			if (eventTargets.length > 0 || firstFrameTargets.length > 0) {
+			const snapshotTargets = this.buildSnapshotTargets(result.tracked, result.timestamp, mediaSettings);
+			if (eventTargets.length > 0 || firstFrameTargets.length > 0 || snapshotTargets.length > 0) {
 				log.info("media capture", { meta: {
 					source,
 					events: eventTargets.length,
 					trackFrames: firstFrameTargets.length,
+					snapshots: snapshotTargets.length,
 					faceCrops,
 					plateCrops
 				} });
@@ -6449,8 +6789,20 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					frameHandle,
 					events: eventTargets,
 					trackFrames: firstFrameTargets,
+					snapshots: snapshotTargets,
 					cropPadding: mediaSettings.cropPadding
-				});
+				}).then((res) => {
+					for (const s of res.storedSnapshots) this.trackStore?.addSnapshot(s.trackId, {
+						timestamp: s.timestamp,
+						position: {
+							x: s.bbox.x + s.bbox.w / 2,
+							y: s.bbox.y + s.bbox.h / 2,
+							timestamp: s.timestamp,
+							bbox: s.bbox
+						},
+						mediaKey: s.mediaKey
+					});
+				}).catch(() => {});
 			}
 		}
 		if (this.faceRecognizer && faceGloballyEnabled && faceSettings) this.faceRecognizer.processFrame({
@@ -6583,6 +6935,35 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		});
 		return settings;
 	}
+	/**
+	* §5 — decide which active tracks need periodic media THIS frame. Pure over
+	* TrackStore.lastSnapshotAt + the per-track best-confidence map:
+	*  • `snapshot` (append) + `lastFrame` (rolling overwrite) fire together on
+	*    the snapshotIntervalMs cadence, gated by `saveThumbnails`;
+	*  • `thumbnail` (best) fires when confidence beats the held best by the
+	*    hysteresis margin, rate-limited to one per BEST_FRAME_MIN_GAP_MS, and is
+	*    NOT gated by saveThumbnails (a single best still-frame is always useful).
+	* The per-track best-confidence map is updated here as a side effect.
+	*/
+	buildSnapshotTargets(tracked, timestamp, media) {
+		const targets = [];
+		for (const t of tracked) {
+			const lastSnap = this.trackStore.lastSnapshotAt(t.trackId);
+			const dueSnapshot = media.saveThumbnails && lastSnap > 0 && timestamp - lastSnap >= media.snapshotIntervalMs;
+			const isNewBest = this.bestFrameTracker.observe(t.trackId, t.confidence, timestamp);
+			if (!dueSnapshot && !isNewBest) continue;
+			targets.push({
+				trackId: t.trackId,
+				timestamp,
+				bbox: { ...t.bbox },
+				...t.label ? { label: t.label } : {},
+				appendSnapshot: dueSnapshot,
+				rollingLastFrame: dueSnapshot,
+				bestThumbnail: isNewBest
+			});
+		}
+		return targets;
+	}
 	async handleAudioResult(data) {
 		if (this.shuttingDown) return;
 		const { deviceId, frame } = data;
@@ -6837,6 +7218,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				});
 				this.faceRecognizer?.onTrackEnd(t.deviceId, t.trackId);
 				this.plateRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				this.bestFrameTracker.delete(t.trackId);
 				this.ctx.eventBus.emit({
 					id: `pa-end-${t.trackId}`,
 					timestamp: new Date(t.lastSeen),
@@ -6970,16 +7352,21 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			p = new FrameProcessor(deviceId, {
 				minHits,
 				iouThreshold: trk.iouThreshold,
-				maxMissedFrames: trk.maxMissedFrames,
+				maxMissedMs: trk.maxMissedMs,
 				predictiveCoasting: trk.predictiveCoasting,
 				classGating: trk.classGating,
 				occlusionEnabled: trk.occlusionEnabled,
 				occlusionContainment: trk.occlusionContainment,
-				occlusionMaxMissedFrames: trk.occlusionMaxMissedFrames,
+				occlusionMaxMissedMs: trk.occlusionMaxMissedMs,
+				rescueIouThreshold: trk.rescueIouThreshold,
+				rescueCentroidFactor: trk.rescueCentroidFactor,
+				resurrectionWindowMs: trk.resurrectionWindowMs,
+				stationarySpeedPx: trk.stationarySpeedPx,
 				maxTrackLifetimeMs: trk.maxTrackLifetimeSec * 1e3
 			}, { stationaryThresholdSec }, {
 				minTrackAge,
-				cooldownSec
+				cooldownSec,
+				minTrackAgeMs: trk.minTrackAgeMs
 			}, source);
 			this.processors.set(key, p);
 		}
@@ -7265,7 +7652,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						min: 500,
 						max: 6e4,
 						step: 500,
-						default: 2e3,
+						default: 5e3,
 						showValue: true,
 						unit: "s",
 						displayScale: 1e3
@@ -7540,12 +7927,53 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					},
 					{
 						type: "number",
-						key: "maxMissedFrames",
-						label: "Max missed frames",
-						description: "Frames a track may miss detections (coast) before it is dropped.",
+						key: "maxMissedMs",
+						label: "Max coasting time",
+						description: "How long (ms) a track may miss detections before it is dropped. Time-based so it behaves the same on a 5fps and a 23fps camera.",
 						min: 0,
-						step: 1,
-						default: TRACKING_DEFAULTS.maxMissedFrames
+						step: 100,
+						default: TRACKING_DEFAULTS.maxMissedMs,
+						unit: "ms"
+					},
+					{
+						type: "number",
+						key: "minTrackAgeMs",
+						label: "Min track age",
+						description: "A track must exist for at least this long (ms) before it can produce events — stops sub-second flicker fragments from becoming events.",
+						min: 0,
+						step: 100,
+						default: TRACKING_DEFAULTS.minTrackAgeMs,
+						unit: "ms"
+					},
+					{
+						type: "number",
+						key: "resurrectionWindowMs",
+						label: "Resurrection window",
+						description: "How long (ms) a dropped track can be re-attached to a re-appearing same-class detection (keeping its id) — the main fix for a stationary object fragmenting into many tracks.",
+						min: 0,
+						step: 500,
+						default: TRACKING_DEFAULTS.resurrectionWindowMs,
+						unit: "ms"
+					},
+					{
+						type: "number",
+						key: "rescueIouThreshold",
+						label: "Rescue IoU threshold",
+						description: "Looser overlap (vs. a track’s last-known box) for the second association + resurrection passes. Lower = more aggressive re-attachment.",
+						min: 0,
+						max: 1,
+						step: .05,
+						default: TRACKING_DEFAULTS.rescueIouThreshold
+					},
+					{
+						type: "number",
+						key: "stationarySpeedPx",
+						label: "Stationary speed",
+						description: "Speed (px/frame) below which a track is treated as stationary and its prediction is frozen, so bbox jitter cannot walk the box off a sitting object.",
+						min: 0,
+						step: .5,
+						default: TRACKING_DEFAULTS.stationarySpeedPx,
+						unit: "px"
 					},
 					{
 						type: "number",
@@ -7590,12 +8018,13 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					},
 					{
 						type: "number",
-						key: "occlusionMaxMissedFrames",
-						label: "Occlusion max missed frames",
-						description: "Extended coasting budget (frames) while a track is occluded.",
+						key: "occlusionMaxMissedMs",
+						label: "Occlusion max coasting time",
+						description: "Extended coasting time (ms) while a track is hidden behind another.",
 						min: 0,
-						step: 1,
-						default: TRACKING_DEFAULTS.occlusionMaxMissedFrames
+						step: 100,
+						default: TRACKING_DEFAULTS.occlusionMaxMissedMs,
+						unit: "ms"
 					},
 					{
 						type: "boolean",