@camstack/addon-post-analysis 1.1.24 → 1.1.26

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 number, S as boolean, T as string, c as nodePin, d as videoclipsCapability, f as zoneAnalyticsCapability, g as EventCategory, h as DeviceType, i as cosineSimilarity, l as pipelineAnalyticsCapability, m as BaseAddon, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as errMsg, r as audioMetricsCapability, t as EVENT_PAD_MS, u as plateGalleryCapability, w as object, y as hydrateSchema } from "../dist-DytVmDZg.mjs";
 import { n as extractCrop, t as resolveFrame } from "../resolve-frame-CT1T1tWy.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 import sharp from "sharp";
@@ -119,6 +119,138 @@ function clusterByEmbedding(items, threshold = .5) {
 	})).toSorted((a, b) => b.size - a.size || b.cohesion - a.cohesion);
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/key-event-scoring.ts
+/**
+* key-event-scoring — the SINGLE deterministic "importance" scorer for a
+* completed track. A value in [0,1] the viewer sorts events by (events page)
+* and a future reels feature pulls highlights from.
+*
+* PURE + DETERMINISTIC: no Date.now / no random. Time enters ONLY as the
+* precomputed `durationMs` (the caller already knows a track's dwell). Given
+* the same `ScoringInput`, `computeImportance` always returns the same
+* `{ importance, reason }`.
+*
+* The score is a weighted sum of seven independent, individually-saturated
+* signals. Every weight and knee is a NAMED EXPORT so the formula is auditable
+* and the tests can assert exact wiring. The weights sum to exactly 1.0, so an
+* all-signals-maxed track scores exactly 1.0 (the clamp is then a no-op) and an
+* all-zero track scores 0.
+*/
+var WEIGHT_CONFIDENCE = .3;
+var WEIGHT_CLASS = .2;
+var WEIGHT_DWELL = .2;
+var WEIGHT_PROXIMITY = .12;
+var WEIGHT_TRAVEL = .08;
+var WEIGHT_ZONE = .05;
+var WEIGHT_IDENTITY = .05;
+/** Dwell (ms) that saturates the dwell term. */
+var DWELL_FULL_MS = 6e4;
+/** Peak bbox area (as a fraction of frame area) that saturates the size term. */
+var SIZE_FULL = .15;
+var CLASS_RANK_VEHICLE = .8;
+var CLASS_RANK_ANIMAL = .5;
+var CLASS_RANK_DEFAULT = .25;
+var PERSON_CLASSES = new Set(["person", "face"]);
+var VEHICLE_CLASSES = new Set([
+	"vehicle",
+	"car",
+	"truck",
+	"bus"
+]);
+var ANIMAL_CLASSES = new Set([
+	"animal",
+	"dog",
+	"cat"
+]);
+/** Clamp to [0,1]. */
+function clamp01(x) {
+	if (Number.isNaN(x)) return 0;
+	if (x < 0) return 0;
+	if (x > 1) return 1;
+	return x;
+}
+/** Rank a class name into [0,1] by how event-worthy it is. Case-insensitive. */
+function classRank(className) {
+	const c = className.toLowerCase();
+	if (PERSON_CLASSES.has(c)) return 1;
+	if (VEHICLE_CLASSES.has(c)) return CLASS_RANK_VEHICLE;
+	if (ANIMAL_CLASSES.has(c)) return CLASS_RANK_ANIMAL;
+	return CLASS_RANK_DEFAULT;
+}
+/**
+* Compute a deterministic importance score for a completed track.
+*
+* `reason` is the tag of the single largest weighted term. Ties resolve to the
+* first term in a fixed, weight-descending order (confidence → class → dwell →
+* proximity → travel → zone → identity), so the output stays deterministic.
+*/
+function computeImportance(input) {
+	const terms = [
+		{
+			reason: "confidence",
+			value: WEIGHT_CONFIDENCE * clamp01(input.peakConfidence)
+		},
+		{
+			reason: "class",
+			value: WEIGHT_CLASS * classRank(input.className)
+		},
+		{
+			reason: "dwell",
+			value: WEIGHT_DWELL * clamp01(input.durationMs / DWELL_FULL_MS)
+		},
+		{
+			reason: "proximity",
+			value: WEIGHT_PROXIMITY * clamp01(input.peakBboxAreaFrac / SIZE_FULL)
+		},
+		{
+			reason: "travel",
+			value: WEIGHT_TRAVEL * clamp01(input.totalDistance / 2)
+		},
+		{
+			reason: "zone",
+			value: WEIGHT_ZONE * (input.zonesVisited.length > 0 ? 1 : 0)
+		},
+		{
+			reason: "identity",
+			value: WEIGHT_IDENTITY * (input.label ? 1 : 0)
+		}
+	];
+	let sum = 0;
+	let best = terms[0];
+	for (const term of terms) {
+		sum += term.value;
+		if (term.value > best.value) best = term;
+	}
+	return {
+		importance: clamp01(sum),
+		reason: best.reason
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/key-event-recompute.ts
+/**
+* Recompute + persist a persisted track's importance from its current fields
+* (including any newly-assigned label) and re-stamp its object events. No-op
+* when the track is not (yet) persisted.
+*/
+async function recomputeTrackImportance(deps, trackId) {
+	const track = await deps.trackStore.getPersistedByTrackId(trackId);
+	if (track === null) return;
+	const peak = await deps.eventStore.peakForTrack(trackId);
+	const { importance, reason } = computeImportance({
+		peakConfidence: peak.peakConfidence,
+		className: track.className,
+		durationMs: track.lastSeen - track.firstSeen,
+		peakBboxAreaFrac: peak.peakBboxAreaFrac,
+		totalDistance: track.totalDistance,
+		zonesVisited: track.zonesVisited,
+		...track.label !== void 0 ? { label: track.label } : {}
+	});
+	const bestEventId = track.bestEventId ?? peak.bestEventId;
+	await deps.trackStore.setImportance(trackId, importance, reason, bestEventId);
+	await deps.eventStore.setImportanceForTrack(trackId, importance);
+}
+//#endregion
 //#region src/pipeline-analytics/face-gallery-provider.ts
 /** Embedding model id used when enrolling face crops as identity samples. */
 var MODEL_ID = "arcface-r100";
@@ -239,7 +371,9 @@ var FaceGalleryProvider = class {
 				...face.recognizedIdentityId != null ? { recognizedIdentityId: face.recognizedIdentityId } : {},
 				...identityName !== void 0 ? { identityName } : {},
 				assigned: face.assigned,
-				...base64 !== void 0 ? { base64 } : {}
+				...base64 !== void 0 ? { base64 } : {},
+				...face.faceBbox !== void 0 ? { faceBbox: face.faceBbox } : {},
+				...face.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: face.keyFrameMediaKey } : {}
 			});
 		}
 		return result;
@@ -267,7 +401,9 @@ var FaceGalleryProvider = class {
 			...face.recognizedIdentityId != null ? { recognizedIdentityId: face.recognizedIdentityId } : {},
 			...identityName !== void 0 ? { identityName } : {},
 			assigned: face.assigned,
-			...base64 !== void 0 ? { base64 } : {}
+			...base64 !== void 0 ? { base64 } : {},
+			...face.faceBbox !== void 0 ? { faceBbox: face.faceBbox } : {},
+			...face.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: face.keyFrameMediaKey } : {}
 		};
 	}
 	/**
@@ -344,6 +480,10 @@ var FaceGalleryProvider = class {
 		if (identityName !== void 0) {
 			await this.trackStore.setLabel(currentFace.trackId, identityName);
 			await this.eventStore.setLabelForTrack(currentFace.trackId, identityName);
+			await recomputeTrackImportance({
+				trackStore: this.trackStore,
+				eventStore: this.eventStore
+			}, currentFace.trackId);
 		}
 		this.refreshGallery();
 	}
@@ -1424,6 +1564,10 @@ var FrameProcessor = class {
 				w: det.bbox.width,
 				h: det.bbox.height
 			});
+			if (det.embedding !== void 0 && !embeddingByBbox.has(parentBbox)) embeddingByBbox.set(parentBbox, {
+				embedding: det.embedding,
+				...det.embeddingModelId !== void 0 ? { embeddingModelId: det.embeddingModelId } : {}
+			});
 		}
 		for (const det of frame.detections) {
 			if (det.kind !== "detail" || det.macroClass !== "plate" || !det.parentId) continue;
@@ -1527,6 +1671,152 @@ 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/track-best-detection.ts
+/**
+* `TrackBestSelector` — the ONE unified "best detection per track" primitive.
+*
+* Post-analysis derives several per-track "best" artefacts (best FRAME thumbnail,
+* best OBJECT/CLIP embedding + its crop, best FACE crop). They all rank the same
+* way: highest detector confidence per `trackId`. This selector composes the
+* canonical {@link BestDetectionTracker} ranking with the RESOLVED payload the
+* consumers need at the peak (bbox / className / embedding / faceBbox), so a
+* single "new best" DECISION can drive one capture whose output is shared:
+*  - the boxed best-frame `thumbnail`,
+*  - the tight object crop written onto the CLIP embedding row's `mediaKey`
+*    (so a search hit's thumbnail IS the embedded crop).
+*
+* It is deliberately in-memory (the peak is per live track, dropped at track
+* end). The CLIP embedding's cross-restart persistence stays a SEPARATE store-
+* side gate (`ObjectEmbeddingStore.upsertIfBetter`): this selector unifies the
+* DECISION, not the durable store (see best-detection-tracker.ts docstring).
+*
+* The face path keeps its own hold buffer because a face crop can only come
+* from a face-bearing frame (the documented FRAME↔FACE seam) — but it shares
+* this ranking so best-frame and best-face agree on which frame is "best".
+*/
+var TrackBestSelector = class {
+	tracker;
+	payloads = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.tracker = new BestDetectionTracker(options);
+	}
+	/**
+	* Record an observation for its track. Returns true when it becomes the
+	* track's new best (first sighting, or a confidence that beats the held peak
+	* per the tracker's hysteresis / minGap rules). On acceptance the held payload
+	* advances to this observation so `peak(trackId)` returns the winning frame's
+	* bbox / embedding / faceBbox.
+	*/
+	observe(obs) {
+		const isNewBest = this.tracker.observe(obs.trackId, obs.confidence, obs.atMs);
+		if (isNewBest) {
+			const { trackId, ...payload } = obs;
+			this.payloads.set(trackId, payload);
+		}
+		return isNewBest;
+	}
+	/** The held best payload for a track (undefined if never observed). */
+	peak(trackId) {
+		return this.payloads.get(trackId);
+	}
+	/** The held peak confidence for a track (undefined if never observed). */
+	peakConfidence(trackId) {
+		return this.tracker.peak(trackId)?.confidence;
+	}
+	/** Drop a track's peak + payload (call at track end). */
+	delete(trackId) {
+		this.tracker.delete(trackId);
+		this.payloads.delete(trackId);
+	}
+	clear() {
+		this.tracker.clear();
+		this.payloads.clear();
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/pipeline/object-embedding-selection.ts
+function isClipObjectEmbedding(t) {
+	return Array.isArray(t.embedding) && t.embedding.length > 0 && typeof t.embeddingModelId === "string" && t.embeddingModelId.startsWith("mobileclip-");
+}
+function resolveSearchThumbnailUrl(input) {
+	if (input.baseUrl === null) return void 0;
+	const id = input.embeddingMediaKey ?? input.eventId;
+	return `${input.baseUrl}/${encodeURIComponent(id)}`;
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/key-event-query.ts
+async function rankKeyEvents(candidates, options, peakLookup) {
+	const scored = [];
+	for (const t of candidates) {
+		if (options.classFilter !== void 0 && t.className !== options.classFilter) continue;
+		let importance = t.importance;
+		let bestEventId = t.bestEventId;
+		if (importance === void 0) {
+			const peak = await peakLookup(t.trackId);
+			importance = computeImportance({
+				peakConfidence: peak.peakConfidence,
+				className: t.className,
+				durationMs: t.lastSeen - t.firstSeen,
+				peakBboxAreaFrac: peak.peakBboxAreaFrac,
+				totalDistance: t.totalDistance,
+				zonesVisited: t.zonesVisited,
+				...t.label !== void 0 ? { label: t.label } : {}
+			}).importance;
+			bestEventId = bestEventId ?? peak.bestEventId;
+		}
+		if (options.minImportance !== void 0 && importance < options.minImportance) continue;
+		scored.push({
+			id: bestEventId ?? t.trackId,
+			trackId: t.trackId,
+			timestamp: t.firstSeen,
+			className: t.className,
+			...t.label !== void 0 ? { label: t.label } : {},
+			importance,
+			bestEventId: bestEventId ?? "",
+			windowMs: t.lastSeen - t.firstSeen
+		});
+	}
+	scored.sort((a, b) => b.importance - a.importance);
+	return scored.slice(0, options.limit);
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/native-detection.ts
 /**
 * Nominal frame size used to denormalize native `[0,1]` boxes when a
@@ -1696,6 +1986,18 @@ var TRACKS_COLUMNS = [
 	{
 		name: "state",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
+	},
+	{
+		name: "bestEventId",
+		type: "TEXT"
+	},
+	{
+		name: "importanceReason",
+		type: "TEXT"
 	}
 ];
 var TRACKS_INDEXES = [{
@@ -1727,7 +2029,10 @@ function cloneTrack(t) {
 		zonesVisited: [...t.zonesVisited],
 		totalDistance: t.totalDistance,
 		state: t.state,
-		active: t.active
+		active: t.active,
+		...t.importance !== void 0 ? { importance: t.importance } : {},
+		...t.bestEventId !== void 0 ? { bestEventId: t.bestEventId } : {},
+		...t.importanceReason !== void 0 ? { importanceReason: t.importanceReason } : {}
 	};
 }
 var TrackStore = class {
@@ -1796,6 +2101,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));
@@ -1851,6 +2166,37 @@ var TrackStore = class {
 		}
 	}
 	/**
+	* Stamp a track's importance score (+ dominant reason and best-event pointer).
+	* Updates the in-memory active entry (so the value is carried into an eventual
+	* (re)persist) AND patches the already-persisted row. Mirrors `setLabel`.
+	* Forward-only — never rewrites history beyond these fields.
+	*/
+	async setImportance(trackId, importance, reason, bestEventId) {
+		const active = this.active.get(trackId);
+		if (active) {
+			active.importance = importance;
+			active.importanceReason = reason;
+			if (bestEventId !== void 0) active.bestEventId = bestEventId;
+		}
+		const data = {
+			importance,
+			importanceReason: reason
+		};
+		if (bestEventId !== void 0) data["bestEventId"] = bestEventId;
+		try {
+			await this.store.update.mutate({
+				collection: TRACKS_COLLECTION,
+				id: trackId,
+				data
+			});
+		} catch (err) {
+			this.logger.warn("setImportance persist failed", { meta: {
+				trackId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
 	* Clear a track's label. Sets label to null in the persisted row (so
 	* rowToTrack's `typeof label === 'string'` guard omits it on read → label
 	* is absent/undefined). Also clears the in-memory active entry if present.
@@ -1921,7 +2267,10 @@ var TrackStore = class {
 				snapshots: [...t.snapshots],
 				zonesVisited: [...t.zonesVisited],
 				totalDistance: t.totalDistance,
-				state: t.state
+				state: t.state,
+				...t.importance !== void 0 ? { importance: t.importance } : {},
+				...t.bestEventId !== void 0 ? { bestEventId: t.bestEventId } : {},
+				...t.importanceReason !== void 0 ? { importanceReason: t.importanceReason } : {}
 			}
 		});
 	}
@@ -1930,6 +2279,9 @@ var TrackStore = class {
 		const snapshots = data["snapshots"] ?? [];
 		const zones = data["zonesVisited"] ?? [];
 		const label = data["label"];
+		const importance = data["importance"];
+		const bestEventId = data["bestEventId"];
+		const importanceReason = data["importanceReason"];
 		return {
 			trackId: id,
 			deviceId: Number(data["deviceId"]),
@@ -1942,7 +2294,10 @@ var TrackStore = class {
 			zonesVisited: zones,
 			totalDistance: Number(data["totalDistance"] ?? 0),
 			state: data["state"] ?? "idle",
-			active: false
+			active: false,
+			...typeof importance === "number" ? { importance } : {},
+			...typeof bestEventId === "string" ? { bestEventId } : {},
+			...typeof importanceReason === "string" ? { importanceReason } : {}
 		};
 	}
 };
@@ -2060,6 +2415,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.
 	*/
@@ -2405,6 +2800,10 @@ var OBJECT_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
 	}
 ];
 var AUDIO_COLUMNS = [
@@ -2602,6 +3001,63 @@ var EventStore = class {
 		return updated;
 	}
 	/**
+	* Forward-only: stamp `importance` on every already-emitted object event of a
+	* track. Returns the number of events updated. Best-effort per row. Mirrors
+	* `setLabelForTrack`. Called when a track's key-event score is computed (at
+	* expiry) or recomputed (late label) so an event row carries the parent
+	* track's importance without a join.
+	*/
+	async setImportanceForTrack(trackId, importance) {
+		const rows = await this.store.query.query({
+			collection: OBJECT_EVENTS_COLLECTION,
+			filter: { where: { trackId } }
+		});
+		let updated = 0;
+		for (const row of rows) try {
+			await this.store.update.mutate({
+				collection: OBJECT_EVENTS_COLLECTION,
+				id: row.id,
+				data: { importance }
+			});
+			updated++;
+		} catch (err) {
+			this.logger.warn("setImportanceForTrack update failed", { meta: {
+				trackId,
+				eventId: row.id,
+				error: String(err)
+			} });
+		}
+		return updated;
+	}
+	/**
+	* The track's highest-confidence object event, its bbox area (as a fraction of
+	* frame area), and that event's id — the SHARED per-track ranking already used
+	* for the best frame, read back from the persisted object events (index
+	* `idx_object_track`). Returns zeros + undefined id when the track has none.
+	* Used by the importance scorer at expiry and by `getKeyEvents` compute-on-read.
+	*/
+	async peakForTrack(trackId) {
+		const rows = await this.store.query.query({
+			collection: OBJECT_EVENTS_COLLECTION,
+			filter: { where: { trackId } }
+		});
+		let bestConf = -1;
+		let bestEventId;
+		let peakBboxAreaFrac = 0;
+		for (const row of rows) {
+			const conf = typeof row.data["confidence"] === "number" ? row.data["confidence"] : 0;
+			if (conf <= bestConf) continue;
+			bestConf = conf;
+			bestEventId = row.id;
+			peakBboxAreaFrac = bboxAreaFrac(row.data);
+		}
+		return {
+			peakConfidence: bestConf < 0 ? 0 : bestConf,
+			peakBboxAreaFrac,
+			bestEventId
+		};
+	}
+	/**
 	* Clear `label` on every already-emitted object event of a track (sets label
 	* to null so stripNulls/slimObject omit it on read → label is absent/undefined).
 	* Returns the number of events updated. Best-effort per row. Mirrors
@@ -2796,7 +3252,8 @@ function slimObject(id, data) {
 		timestamp: data["timestamp"],
 		className: data["className"],
 		...typeof data["frameId"] === "string" ? { frameId: data["frameId"] } : {},
-		...typeof data["trackId"] === "string" ? { trackId: data["trackId"] } : {}
+		...typeof data["trackId"] === "string" ? { trackId: data["trackId"] } : {},
+		...typeof data["importance"] === "number" ? { importance: data["importance"] } : {}
 	};
 	if (typeof data["label"] === "string") return {
 		...base,
@@ -2826,6 +3283,17 @@ function slimAudio(id, data) {
 	}
 	return base;
 }
+function bboxAreaFrac(data) {
+	const bbox = data["bbox"];
+	const fw = data["frameWidth"];
+	const fh = data["frameHeight"];
+	if (bbox === null || typeof bbox !== "object") return 0;
+	if (typeof fw !== "number" || typeof fh !== "number" || fw <= 0 || fh <= 0) return 0;
+	const w = "w" in bbox && typeof bbox.w === "number" ? bbox.w : 0;
+	const h = "h" in bbox && typeof bbox.h === "number" ? bbox.h : 0;
+	if (w <= 0 || h <= 0) return 0;
+	return w * h / (fw * fh);
+}
 function stripNulls(data) {
 	const out = {};
 	for (const [k, v] of Object.entries(data)) if (v !== null) out[k] = v;
@@ -2972,7 +3440,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 +3459,7 @@ var EventMediaDispatcher = class {
 					error: String(err)
 				}
 			});
-			return;
+			return empty;
 		}
 		if (!decoded) {
 			this.deps.logger.debug("event media: frame recycled before resolve", {
@@ -2999,7 +3469,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 +3479,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 +4554,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 +4578,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
@@ -4356,6 +4913,14 @@ var FACE_COLUMNS = [
 	{
 		name: "assignedSampleId",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "faceBbox",
+		type: "JSON"
 	}
 ];
 var FACE_INDEXES = [{
@@ -4428,7 +4993,9 @@ var FaceStore = class {
 				assigned: Boolean(r.data.assigned),
 				mediaKey: data.mediaKey ?? void 0,
 				recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-				assignedSampleId: data.assignedSampleId ?? void 0
+				assignedSampleId: data.assignedSampleId ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+				faceBbox: data.faceBbox ?? void 0
 			};
 		}).filter((f) => !f.assigned);
 	}
@@ -4592,8 +5159,11 @@ var FaceStore = class {
 			id: faceId,
 			...data,
 			assigned: Boolean(raw.assigned),
+			mediaKey: data.mediaKey ?? void 0,
 			recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-			assignedSampleId: data.assignedSampleId ?? void 0
+			assignedSampleId: data.assignedSampleId ?? void 0,
+			keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+			faceBbox: data.faceBbox ?? void 0
 		};
 	}
 	/**
@@ -4637,7 +5207,9 @@ var FaceStore = class {
 				assigned: Boolean(r.data.assigned),
 				mediaKey: data.mediaKey ?? void 0,
 				recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-				assignedSampleId: data.assignedSampleId ?? void 0
+				assignedSampleId: data.assignedSampleId ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+				faceBbox: data.faceBbox ?? void 0
 			};
 		});
 		const filterMode = input.filter ?? "all";
@@ -4702,6 +5274,10 @@ var OBJECT_EMBEDDING_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
 	}
 ];
 var ObjectEmbeddingStore = class {
@@ -4748,7 +5324,8 @@ var ObjectEmbeddingStore = class {
 			modelId: input.modelId,
 			dim: input.embedding.length,
 			confidence: input.confidence,
-			...input.mediaKey !== void 0 ? { mediaKey: input.mediaKey } : {}
+			...input.mediaKey !== void 0 ? { mediaKey: input.mediaKey } : {},
+			...input.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: input.keyFrameMediaKey } : {}
 		};
 		try {
 			await this.store.set.mutate({
@@ -4786,7 +5363,8 @@ var ObjectEmbeddingStore = class {
 			return {
 				id: r.id,
 				...data,
-				mediaKey: data.mediaKey ?? void 0
+				mediaKey: data.mediaKey ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0
 			};
 		});
 	}
@@ -4915,12 +5493,22 @@ function updateTrackAggregate(prev, match, opts) {
 }
 //#endregion
 //#region src/pipeline-analytics/face-recognizer.ts
+/** At most one "dropping imageless track" log per this interval, per recognizer. */
+var FACE_IMAGELESS_LOG_THROTTLE_MS = 6e4;
 var FaceRecognizer = class {
 	deps;
 	gallery = [];
 	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();
+	/** Throttle for the "dropping imageless track" log — one line per minute at
+	*  most, so a busy scene that never produces a face crop can't flood logs. */
+	lastImagelessLogAt = 0;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -4954,55 +5542,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 +5570,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 +5592,64 @@ 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)
+					}
+				});
+			}
+			try {
+				await this.deps.recomputeImportance?.(work.trackId);
+			} catch (err) {
+				this.deps.logger.warn("recomputeImportance 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 +5660,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,
@@ -5054,9 +5668,23 @@ var FaceRecognizer = class {
 			} });
 			return;
 		}
+		if (held.crop === void 0) {
+			const now = Date.now();
+			if (now - this.lastImagelessLogAt >= FACE_IMAGELESS_LOG_THROTTLE_MS) {
+				this.lastImagelessLogAt = now;
+				this.deps.logger.info("face: dropping imageless track (no crop captured)", {
+					tags: {
+						deviceId,
+						trackId
+					},
+					meta: { score: held.score }
+				});
+			}
+			return;
+		}
 		const faceId = `face-${trackId}`;
 		let mediaKey;
-		if (held.crop !== void 0) try {
+		try {
 			mediaKey = await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "face",
@@ -5074,6 +5702,17 @@ var FaceRecognizer = class {
 				}
 			});
 		}
+		if (mediaKey === void 0) {
+			this.deps.logger.warn("face: crop store failed — dropping face row", {
+				tags: {
+					deviceId,
+					trackId
+				},
+				meta: { faceId }
+			});
+			return;
+		}
+		const keyFrameMediaKey = this.deps.getKeyFrameMediaKey?.(trackId);
 		try {
 			await this.deps.faceStore.insert({
 				id: faceId,
@@ -5081,9 +5720,11 @@ var FaceRecognizer = class {
 				trackId,
 				timestamp: held.timestamp,
 				embedding: held.embedding,
-				...mediaKey !== void 0 ? { mediaKey } : {},
+				mediaKey,
 				...held.recognizedIdentityId !== void 0 ? { recognizedIdentityId: held.recognizedIdentityId } : {},
-				assigned: false
+				assigned: false,
+				faceBbox: held.bbox,
+				...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
 			});
 			this.deps.logger.info("face: buffered to gallery", {
 				tags: {
@@ -5092,7 +5733,7 @@ var FaceRecognizer = class {
 				},
 				meta: {
 					faceId,
-					hasCrop: mediaKey !== void 0,
+					hasCrop: true,
 					recognizedIdentityId: held.recognizedIdentityId ?? null,
 					score: held.score
 				}
@@ -5424,6 +6065,38 @@ var PlateRecognizer = class {
 	}
 };
 //#endregion
+//#region src/shared/frame/shared-frame-resolver.ts
+function frameHandleKey(h) {
+	return `${h.nodeId}:${h.shmId}:${h.slot}:${h.seq}`;
+}
+function createSharedFrameResolver(resolve) {
+	let cache = null;
+	return (handle) => {
+		const key = frameHandleKey(handle);
+		if (cache === null || cache.key !== key) cache = {
+			key,
+			value: resolve(handle)
+		};
+		return cache.value;
+	};
+}
+//#endregion
+//#region src/shared/frame/encode-crop.ts
+/**
+* JPEG-encode an already-cropped raw RGB (24-bit) buffer. Used for the
+* NATIVE-resolution crop path: the decode worker returns the exact ROI pixels
+* at native res, so there is nothing left to crop — only to encode to the same
+* JPEG contract `extractCrop` produces (quality 90). Kept separate from
+* `extractCrop` (which crops a FULL frame) so the native path never re-crops.
+*/
+async function encodeRgbCropToJpeg(bytes, width, height) {
+	return sharp(Buffer.from(bytes), { raw: {
+		width,
+		height,
+		channels: 3
+	} }).jpeg({ quality: 90 }).toBuffer();
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/event-child-crops.ts
 /**
 * Compute Intersection-over-Union between two (x,y,w,h) bounding boxes.
@@ -5722,6 +6395,24 @@ 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;
+/** Design B: cap (px) on the width of the native KEY FRAME (full-frame native
+*  capture). Native resolution is the point, but a full 4K RGB surface over the
+*  transport per new-best is wasteful for a web detail view — 1920px keeps a
+*  sharp native frame while bounding the copy (a miss falls back to the
+*  detection-res frame, which is already ≤640px). */
+var KEYFRAME_NATIVE_MAX_WIDTH = 1920;
+/** getKeyEvents: max completed tracks pulled from a window before importance
+*  ranking. Ordering is by importance (not firstSeen) and legacy rows score on
+*  read, so we over-fetch candidates and trim to `limit` after sorting. */
+var KEY_EVENT_CANDIDATE_CAP = 500;
+/** getKeyEvents: default page size when the caller omits `limit`. */
+var KEY_EVENT_DEFAULT_LIMIT = 50;
 /** 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 +6524,31 @@ 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
+	});
+	/** Best (highest-confidence) CLIP-object detection per track — drives ONE
+	*  tight object-crop capture whose media key is written onto the embedding
+	*  row (so a semantic-search hit's thumbnail IS the embedded crop). Shares the
+	*  unified best-per-track decision (`TrackBestSelector`); the persistent
+	*  cross-restart "best" gate stays in `ObjectEmbeddingStore.upsertIfBetter`. */
+	objectEmbeddingBestSelector = new TrackBestSelector();
+	/** Design B: the track's shared native key-frame media key, captured at the
+	*  best-detection moment (object-embedding best path). Read by the face path
+	*  at track end so a face row links to the SAME single key frame. Cleared on
+	*  track end. */
+	keyFrameKeyByTrackId = /* @__PURE__ */ new Map();
+	/** The shared crop extractor (native-res first, detection-frame fallback),
+	*  captured in the constructor so `processFrame` can crop object thumbnails in
+	*  the same live-frame window as the face/plate/event-media captures. The
+	*  optional `maxWidth` caps the native crop width (used for the full-frame key
+	*  frame so a 4K native surface never floods the transport). */
+	captureCrop = null;
 	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). */
@@ -5932,23 +6648,62 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		});
 		const ownNodeIdForFaces = ownNodeId;
 		const frameReadersForFaces = this.frameReaders;
-		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding) => {
-			const decoded = await resolveFrame(frameHandle, {
-				ownNodeId: ownNodeIdForFaces,
-				readers: frameReadersForFaces,
-				getRemoteFrame
-			});
-			if (!decoded || decoded.format !== "rgb") return null;
-			const data = Buffer.isBuffer(decoded.data) ? decoded.data : Buffer.from(decoded.data);
+		const pipelineRunnerApi = api.pipelineRunner;
+		const cropMetricLogger = logger.child("NativeCrop");
+		let nativeHits = 0;
+		let nativeFallbacks = 0;
+		let lastCropMetricAt = 0;
+		const NATIVE_CROP_METRIC_INTERVAL_MS = 3e4;
+		const bumpCropMetric = (hit) => {
+			if (hit) nativeHits += 1;
+			else nativeFallbacks += 1;
+			const now = Date.now();
+			if (now - lastCropMetricAt < NATIVE_CROP_METRIC_INTERVAL_MS) return;
+			lastCropMetricAt = now;
+			cropMetricLogger.info("native-crop window", { meta: {
+				nativeHits,
+				detectionFrameFallbacks: nativeFallbacks
+			} });
+		};
+		const tryNativeCrop = async (frameHandle, paddedNorm, maxWidth) => {
+			if (!pipelineRunnerApi?.getNativeCrop) return null;
+			try {
+				const native = await pipelineRunnerApi.getNativeCrop.query({
+					handle: frameHandle,
+					bbox: paddedNorm,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, nodePin(frameHandle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return await encodeRgbCropToJpeg(Buffer.from(native.bytes), native.width, native.height);
+			} catch (err) {
+				cropMetricLogger.debug("native crop request failed — falling back", { meta: { error: errMsg(err) } });
+				return null;
+			}
+		};
+		const resolveFrameShared = createSharedFrameResolver((frameHandle) => resolveFrame(frameHandle, {
+			ownNodeId: ownNodeIdForFaces,
+			readers: frameReadersForFaces,
+			getRemoteFrame
+		}));
+		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding, maxWidth) => {
 			const paddedNorm = padBbox({
 				x: bbox.x / frameWidth,
 				y: bbox.y / frameHeight,
 				w: bbox.w / frameWidth,
 				h: bbox.h / frameHeight
 			}, padding);
-			const { crop } = await extractCrop(data, decoded.width, decoded.height, paddedNorm);
+			const nativeCrop = await tryNativeCrop(frameHandle, paddedNorm, maxWidth);
+			if (nativeCrop) {
+				bumpCropMetric(true);
+				return nativeCrop;
+			}
+			bumpCropMetric(false);
+			const decoded = await resolveFrameShared(frameHandle);
+			if (!decoded || decoded.format !== "rgb") return null;
+			const { crop } = await extractCrop(Buffer.isBuffer(decoded.data) ? decoded.data : Buffer.from(decoded.data), decoded.width, decoded.height, paddedNorm);
 			return crop;
 		};
+		this.captureCrop = captureCrop;
 		this.faceRecognizer = new FaceRecognizer({
 			identityStore: this.identityStore,
 			faceStore: this.faceStore,
@@ -5956,6 +6711,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			trackStore: this.trackStore,
 			eventStore: this.eventStore,
 			captureCrop,
+			recomputeImportance: (trackId) => {
+				const trackStore = this.trackStore;
+				const eventStore = this.eventStore;
+				if (!trackStore || !eventStore) return Promise.resolve();
+				return recomputeTrackImportance({
+					trackStore,
+					eventStore
+				}, trackId);
+			},
+			getKeyFrameMediaKey: (trackId) => this.keyFrameKeyByTrackId.get(trackId),
 			logger: logger.child("FaceRecognizer")
 		});
 		this.faceRecognizer.refreshGallery();
@@ -5993,7 +6758,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		try {
 			const handler = createEventMediaHandler({ getMedia: async (id) => {
 				try {
-					return await this.readEventThumbnail(id);
+					return await this.readMediaByEventOrKey(id);
 				} catch (err) {
 					this.ctx.logger.warn("readEventThumbnail failed", { meta: {
 						eventId: id,
@@ -6376,6 +7141,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.processors.clear();
 		this.lastActiveTrackIds.clear();
 		this.dropoutSkipsByKey.clear();
+		this.bestFrameTracker.clear();
+		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
@@ -6482,12 +7249,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),
@@ -6528,16 +7298,18 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			} });
 		}
 		await Promise.all(result.objectEvents.map((e) => this.eventStore.insertObject(e)));
-		if (this.objectEmbeddingStore) {
-			for (const t of result.tracked) if (t.embedding !== void 0 && t.embeddingModelId !== void 0 && t.embeddingModelId.startsWith("mobileclip-")) this.objectEmbeddingStore.upsertIfBetter({
+		const objectEmbeddingBests = [];
+		if (this.objectEmbeddingStore) for (const t of result.tracked) {
+			if (!isClipObjectEmbedding(t)) continue;
+			if (this.objectEmbeddingBestSelector.observe({
 				trackId: t.trackId,
-				deviceId,
-				timestamp: result.timestamp,
+				confidence: t.confidence,
+				atMs: result.timestamp,
 				className: t.className,
+				bbox: t.bbox,
 				embedding: t.embedding,
-				modelId: t.embeddingModelId,
-				confidence: t.confidence
-			});
+				embeddingModelId: t.embeddingModelId
+			})) objectEmbeddingBests.push(t);
 		}
 		const faceSettings = this.faceRecognizer ? await this.resolveDeviceFaceSettings(deviceId) : null;
 		const faceGloballyEnabled = this.faceRecognizer ? await this.resolveGlobalFaceEnabled() : false;
@@ -6560,11 +7332,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 +7347,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({
@@ -6596,6 +7382,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			cropPadding: mediaSettings.cropPadding,
 			...frameHandle !== void 0 ? { frameHandle } : {}
 		});
+		if (objectEmbeddingBests.length > 0) this.persistObjectEmbeddingBests(deviceId, result.timestamp, objectEmbeddingBests, frameHandle, result.frameWidth, result.frameHeight, mediaSettings.cropPadding);
 		for (const e of result.objectEvents) this.ctx.eventBus.emit({
 			id: `pa-${e.id}`,
 			timestamp: new Date(e.timestamp),
@@ -6707,6 +7494,112 @@ 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.
+	*/
+	/**
+	* Capture the tight object crop for each new-best CLIP track (native-res via
+	* the shared extractor) and upsert the embedding row with that crop's media
+	* key. The crop uses `putReplacing` so exactly ONE object crop is kept per
+	* track (the current peak). The embedding is upserted even when no crop was
+	* captured (no frame handle) so semantic search still works — the crop just
+	* enhances the search-hit thumbnail. `upsertIfBetter` remains the durable
+	* cross-restart best gate (R3). Best-effort; issued in the live-frame window.
+	*/
+	async persistObjectEmbeddingBests(deviceId, timestamp, bests, frameHandle, frameWidth, frameHeight, cropPadding) {
+		const store = this.objectEmbeddingStore;
+		if (!store) return;
+		await Promise.all(bests.map(async (t) => {
+			if (!isClipObjectEmbedding(t)) return;
+			let mediaKey;
+			let keyFrameMediaKey;
+			if (frameHandle !== void 0 && this.captureCrop && this.mediaStore) {
+				try {
+					const crop = await this.captureCrop(frameHandle, t.bbox, frameWidth, frameHeight, cropPadding);
+					if (crop) mediaKey = await this.mediaStore.putReplacing({
+						deviceId,
+						ownerKind: "track",
+						ownerId: t.trackId,
+						kind: "crop",
+						timestamp,
+						data: crop
+					});
+				} catch (err) {
+					this.ctx.logger.debug("object-embedding crop capture failed", {
+						tags: { deviceId },
+						meta: {
+							trackId: t.trackId,
+							error: errMsg(err)
+						}
+					});
+				}
+				try {
+					const keyFrame = await this.captureCrop(frameHandle, {
+						x: 0,
+						y: 0,
+						w: frameWidth,
+						h: frameHeight
+					}, frameWidth, frameHeight, 0, KEYFRAME_NATIVE_MAX_WIDTH);
+					if (keyFrame) {
+						keyFrameMediaKey = await this.mediaStore.putReplacing({
+							deviceId,
+							ownerKind: "track",
+							ownerId: t.trackId,
+							kind: "keyFrame",
+							timestamp,
+							data: keyFrame
+						});
+						this.keyFrameKeyByTrackId.set(t.trackId, keyFrameMediaKey);
+					}
+				} catch (err) {
+					this.ctx.logger.debug("key-frame capture failed", {
+						tags: { deviceId },
+						meta: {
+							trackId: t.trackId,
+							error: errMsg(err)
+						}
+					});
+				}
+			}
+			await store.upsertIfBetter({
+				trackId: t.trackId,
+				deviceId,
+				timestamp,
+				className: t.className,
+				embedding: t.embedding,
+				modelId: t.embeddingModelId,
+				confidence: t.confidence,
+				...mediaKey !== void 0 ? { mediaKey } : {},
+				...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
+			});
+		}));
+	}
+	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;
@@ -6959,8 +7852,36 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						positions: t.positions.length
 					}
 				});
-				this.faceRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				const faceEnd = this.faceRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				const dropKeyFrameKey = () => {
+					this.keyFrameKeyByTrackId.delete(t.trackId);
+				};
+				if (faceEnd) faceEnd.finally(dropKeyFrameKey);
+				else dropKeyFrameKey();
 				this.plateRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				try {
+					const peak = await this.eventStore?.peakForTrack(t.trackId);
+					if (peak) {
+						const { importance, reason } = computeImportance({
+							peakConfidence: this.bestFrameTracker.peak(t.trackId)?.confidence ?? peak.peakConfidence,
+							className: t.className,
+							durationMs: duration,
+							peakBboxAreaFrac: peak.peakBboxAreaFrac,
+							totalDistance: t.totalDistance,
+							zonesVisited: t.zonesVisited,
+							...t.label !== void 0 ? { label: t.label } : {}
+						});
+						await this.trackStore?.setImportance(t.trackId, importance, reason, peak.bestEventId);
+						if (peak.bestEventId !== void 0) await this.eventStore?.setImportanceForTrack(t.trackId, importance);
+					}
+				} catch (err) {
+					this.ctx.logger.debug("importance scoring failed", { meta: {
+						trackId: t.trackId,
+						error: String(err)
+					} });
+				}
+				this.bestFrameTracker.delete(t.trackId);
+				this.objectEmbeddingBestSelector.delete(t.trackId);
 				this.ctx.eventBus.emit({
 					id: `pa-end-${t.trackId}`,
 					timestamp: new Date(t.lastSeen),
@@ -7183,6 +8104,32 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		if (input.projection !== "slim" || this.eventMediaBaseUrl === null) return events;
 		return this.withMediaUrl(events);
 	}
+	async getKeyEvents(input) {
+		const trackStore = this.trackStore;
+		if (!trackStore) return [];
+		const eventStore = this.eventStore;
+		try {
+			const candidates = await trackStore.queryHistorical({
+				deviceId: input.deviceId,
+				since: input.since,
+				until: input.until,
+				limit: KEY_EVENT_CANDIDATE_CAP
+			});
+			const peakLookup = (trackId) => eventStore ? eventStore.peakForTrack(trackId) : Promise.resolve({
+				peakConfidence: 0,
+				peakBboxAreaFrac: 0,
+				bestEventId: void 0
+			});
+			return await rankKeyEvents(candidates, {
+				limit: input.limit ?? KEY_EVENT_DEFAULT_LIMIT,
+				...input.minImportance !== void 0 ? { minImportance: input.minImportance } : {},
+				...input.classFilter !== void 0 ? { classFilter: input.classFilter } : {}
+			}, peakLookup);
+		} catch (err) {
+			this.ctx.logger.debug("getKeyEvents failed", { meta: { error: String(err) } });
+			return [];
+		}
+	}
 	async getAudioEvents(input) {
 		const events = await (this.eventStore?.queryAudio(input) ?? Promise.resolve([]));
 		if (input.projection !== "slim" || this.eventMediaBaseUrl === null) return events;
@@ -7225,6 +8172,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			className: input.classFilter
 		});
 		if (embeddingRows.length === 0) return [];
+		const embeddingMediaKeyByTrackId = /* @__PURE__ */ new Map();
+		const keyFrameKeyByTrackId = /* @__PURE__ */ new Map();
+		for (const row of embeddingRows) {
+			if (row.mediaKey !== void 0) embeddingMediaKeyByTrackId.set(row.trackId, row.mediaKey);
+			if (row.keyFrameMediaKey !== void 0) keyFrameKeyByTrackId.set(row.trackId, row.keyFrameMediaKey);
+		}
 		const encoderInfo = await api.embeddingEncoder.getInfo.query().catch((err) => {
 			this.ctx.logger.warn("searchObjectEvents: getInfo failed, proceeding without modelId gate", { meta: { error: String(err) } });
 			return null;
@@ -7271,10 +8224,20 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					score
 				});
 			}
-			for (const { event, score } of bestEventByTrackId.values()) scored.push({
-				...event,
-				score
-			});
+			for (const { event, score } of bestEventByTrackId.values()) {
+				const mediaUrl = resolveSearchThumbnailUrl({
+					baseUrl: this.eventMediaBaseUrl,
+					eventId: event.id,
+					...event.trackId !== void 0 && embeddingMediaKeyByTrackId.has(event.trackId) ? { embeddingMediaKey: embeddingMediaKeyByTrackId.get(event.trackId) } : {}
+				});
+				const keyFrameMediaKey = event.trackId !== void 0 ? keyFrameKeyByTrackId.get(event.trackId) : void 0;
+				scored.push({
+					...event,
+					score,
+					...mediaUrl !== void 0 ? { mediaUrl } : {},
+					...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
+				});
+			}
 		}
 		scored.sort((a, b) => b.score - a.score);
 		return scored.slice(0, input.limit);
@@ -7306,6 +8269,24 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	* (native-res boxed frame) → any available file. Returns `null` if the
 	* event has no media at all.
 	*/
+	/**
+	* Data-plane resolver: an id is EITHER a bare event id (a UUID → the event's
+	* crop, today's behaviour) OR a MediaStore key (`ownerKind:ownerId:kind:ts`,
+	* contains ':' → served directly by key). The object-embedding search hit
+	* points its thumbnail at the embedding row's crop key (a `track:…:crop:…`
+	* key), so this resolves that crop; event ids stay on the event-crop path.
+	*/
+	async readMediaByEventOrKey(id) {
+		if (id.includes(":")) {
+			const file = await (this.mediaStore?.getByKey(id) ?? Promise.resolve(null));
+			if (!file) return null;
+			return {
+				bytes: Buffer.from(file.base64, "base64"),
+				key: file.key
+			};
+		}
+		return this.readEventThumbnail(id);
+	}
 	async readEventThumbnail(eventId) {
 		const files = await (this.mediaStore?.listByOwner("event", eventId) ?? Promise.resolve([]));
 		const chosen = files.find((f) => f.kind === "crop") ?? files.find((f) => f.kind === "fullFrameBoxed") ?? files[0];
@@ -7394,7 +8375,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						min: 500,
 						max: 6e4,
 						step: 500,
-						default: 2e3,
+						default: 5e3,
 						showValue: true,
 						unit: "s",
 						displayScale: 1e3