@camstack/addon-post-analysis 1.1.24 → 1.1.25

package/dist/{dist-B0VgBdBN.js → dist-CCC79h7t.js}

@@ -10585,6 +10585,7 @@ var PipelineAddonSchemaSchema = object({
 	defaultModelId: string(),
 	defaultModelIdByFormat: record(string(), string()).optional(),
 	enabledByDefault: boolean().optional(),
+	backfillIntoExistingOverrides: boolean().optional(),
 	defaultConfidence: number(),
 	group: string().optional(),
 	configSchema: array(ConfigFieldBridge).readonly().optional()

package/dist/{dist-DRK78NMq.mjs → dist-Csk_yJr_.mjs}

@@ -10563,6 +10563,7 @@ var PipelineAddonSchemaSchema = object({
 	defaultModelId: string(),
 	defaultModelIdByFormat: record(string(), string()).optional(),
 	enabledByDefault: boolean().optional(),
+	backfillIntoExistingOverrides: boolean().optional(),
 	defaultConfidence: number(),
 	group: string().optional(),
 	configSchema: array(ConfigFieldBridge).readonly().optional()

package/dist/embedding-encoder/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-B0VgBdBN.js");
+const require_dist = require("../dist-CCC79h7t.js");
 let node_fs = require("node:fs");
 let node_fs$1 = require_dist.__toESM(node_fs, 1);
 node_fs = require_dist.__toESM(node_fs);

package/dist/embedding-encoder/index.mjs

@@ -1,4 +1,4 @@
-import { a as embeddingEncoderCapability, p as BaseAddon, s as hfModelUrl } from "../dist-DRK78NMq.mjs";
+import { a as embeddingEncoderCapability, p as BaseAddon, s as hfModelUrl } from "../dist-Csk_yJr_.mjs";
 import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";

package/dist/enrichment-engine/index.js

@@ -2,8 +2,8 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-B0VgBdBN.js");
-const require_resolve_frame = require("../resolve-frame-DBXwF5fk.js");
+const require_dist = require("../dist-CCC79h7t.js");
+const require_resolve_frame = require("../resolve-frame-sKYbstL-.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 //#region src/enrichment-engine/types.ts
 var DEFAULT_ENRICHMENT_CONFIG = {

package/dist/enrichment-engine/index.mjs

@@ -1,4 +1,4 @@
-import { C as object, S as number, T as tuple, _ as createEvent, b as array, g as asJsonObject, h as EventCategory, p as BaseAddon, w as string, x as boolean, y as _enum } from "../dist-DRK78NMq.mjs";
+import { C as object, S as number, T as tuple, _ as createEvent, b as array, g as asJsonObject, h as EventCategory, p as BaseAddon, w as string, x as boolean, y as _enum } from "../dist-Csk_yJr_.mjs";
 import { n as extractCrop, t as resolveFrame } from "../resolve-frame-CT1T1tWy.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 //#region src/enrichment-engine/types.ts

package/dist/{node-Cx0LM0Sq.js → node-CIEkEv1F.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-B0VgBdBN.js");
+const require_dist = require("./dist-CCC79h7t.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");

package/dist/pipeline-analytics/{_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-BsRL9Bh-.mjs → _virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-Cb6Z2H5K.mjs}

@@ -18,7 +18,7 @@ var e = {
 	},
 	"@camstack/types": {
 		name: "@camstack/types",
-		version: "1.1.40",
+		version: "1.1.41",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_analytics_widgets",
@@ -33,7 +33,7 @@ var e = {
 	},
 	"@camstack/ui-library": {
 		name: "@camstack/ui-library",
-		version: "1.1.32",
+		version: "1.1.33",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_analytics_widgets",

package/dist/pipeline-analytics/{hostInit-sO1Drmtf.mjs → hostInit-BrqCuPYQ.mjs}

@@ -36,7 +36,7 @@ async function r() {
 				}
 			},
 			"@camstack/types": {
-				version: "1.1.40",
+				version: "1.1.41",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,
@@ -81,7 +81,7 @@ async function r() {
 				}
 			},
 			"@camstack/ui-library": {
-				version: "1.1.32",
+				version: "1.1.33",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,

package/dist/pipeline-analytics/index.js

@@ -2,8 +2,8 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-B0VgBdBN.js");
-const require_resolve_frame = require("../resolve-frame-DBXwF5fk.js");
+const require_dist = require("../dist-CCC79h7t.js");
+const require_resolve_frame = require("../resolve-frame-sKYbstL-.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -1532,6 +1532,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
@@ -1801,6 +1838,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));
@@ -2065,6 +2112,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.
 	*/
@@ -2977,7 +3064,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 require_resolve_frame.resolveFrame(frameHandle, {
@@ -2994,7 +3083,7 @@ var EventMediaDispatcher = class {
 					error: String(err)
 				}
 			});
-			return;
+			return empty;
 		}
 		if (!decoded) {
 			this.deps.logger.debug("event media: frame recycled before resolve", {
@@ -3004,7 +3093,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", {
@@ -3014,13 +3103,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 = {
@@ -4015,11 +4178,20 @@ function resolveFaceSettings(raw) {
 * its default — parse never throws). Mirrors `face-settings` /
 * `audio-detection-settings`.
 */
-var MediaSettingsSchema = require_dist.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: require_dist.number().min(0).max(2).default(.15) });
+var MediaSettingsSchema = require_dist.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: require_dist.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: require_dist.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: require_dist.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
@@ -4030,7 +4202,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
@@ -4926,6 +5102,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;
 	}
@@ -4959,55 +5140,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 },
@@ -5017,14 +5168,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: {
@@ -5033,15 +5190,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
@@ -5052,6 +5247,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,
@@ -5727,6 +5923,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. */
@@ -5838,6 +6040,14 @@ var PipelineAnalyticsAddon = class extends require_dist.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). */
@@ -5871,7 +6081,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-Cx0LM0Sq.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-CIEkEv1F.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -6381,6 +6591,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.processors.clear();
 		this.lastActiveTrackIds.clear();
 		this.dropoutSkipsByKey.clear();
+		this.bestFrameTracker.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
@@ -6487,12 +6698,15 @@ var PipelineAnalyticsAddon = class extends require_dist.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-${(0, node_crypto.randomUUID)()}`,
 					timestamp: new Date(result.timestamp),
@@ -6565,11 +6779,13 @@ var PipelineAnalyticsAddon = class extends require_dist.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
 				} });
@@ -6578,8 +6794,20 @@ var PipelineAnalyticsAddon = class extends require_dist.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({
@@ -6712,6 +6940,35 @@ var PipelineAnalyticsAddon = class extends require_dist.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;
@@ -6966,6 +7223,7 @@ var PipelineAnalyticsAddon = class extends require_dist.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),
@@ -7399,7 +7657,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						min: 500,
 						max: 6e4,
 						step: 500,
-						default: 2e3,
+						default: 5e3,
 						showValue: true,
 						unit: "s",
 						displayScale: 1e3

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-DRK78NMq.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";
@@ -1527,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
@@ -1796,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));
@@ -2060,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.
 	*/
@@ -2972,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, {
@@ -2989,7 +3078,7 @@ var EventMediaDispatcher = class {
 					error: String(err)
 				}
 			});
-			return;
+			return empty;
 		}
 		if (!decoded) {
 			this.deps.logger.debug("event media: frame recycled before resolve", {
@@ -2999,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", {
@@ -3009,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 = {
@@ -4010,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
@@ -4025,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
@@ -4921,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;
 	}
@@ -4954,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 },
@@ -5012,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: {
@@ -5028,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
@@ -5047,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,
@@ -5722,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. */
@@ -5833,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). */
@@ -6376,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();
@@ -6482,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),
@@ -6560,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
 				} });
@@ -6573,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({
@@ -6707,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;
@@ -6961,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),
@@ -7394,7 +7652,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						min: 500,
 						max: 6e4,
 						step: 500,
-						default: 2e3,
+						default: 5e3,
 						showValue: true,
 						unit: "s",
 						displayScale: 1e3

package/dist/pipeline-analytics/remoteEntry.js

@@ -30,7 +30,7 @@ async function d(e) {
 	}
 }
 async function f() {
-	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-BsRL9Bh-.mjs")).catch((e) => {
+	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-Cb6Z2H5K.mjs")).catch((e) => {
 		throw l = void 0, e;
 	}), l;
 }

package/dist/{resolve-frame-DBXwF5fk.js → resolve-frame-sKYbstL-.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-B0VgBdBN.js");
+const require_dist = require("./dist-CCC79h7t.js");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 //#region src/shared/frame/crop-extractor.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-post-analysis",
-  "version": "1.1.24",
+  "version": "1.1.25",
   "description": "CamStack Post-Analysis bundle — enrichment, embedding-encoder, pipeline-analytics. Multi-entry npm package shipping addons that consume pipeline output.",
   "keywords": [
     "camstack",