@camstack/addon-post-analysis 1.1.25 → 1.1.26

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-CCC79h7t.js");
-const require_resolve_frame = require("../resolve-frame-sKYbstL-.js");
+const require_dist = require("../dist-BEx5ST1W.js");
+const require_resolve_frame = require("../resolve-frame-Cbm_NFuq.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -124,6 +124,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";
@@ -244,7 +376,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;
@@ -272,7 +406,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 } : {}
 		};
 	}
 	/**
@@ -349,6 +485,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();
 	}
@@ -1429,6 +1569,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;
@@ -1569,6 +1713,115 @@ var BestDetectionTracker = class {
 	}
 };
 //#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
@@ -1738,6 +1991,18 @@ var TRACKS_COLUMNS = [
 	{
 		name: "state",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
+	},
+	{
+		name: "bestEventId",
+		type: "TEXT"
+	},
+	{
+		name: "importanceReason",
+		type: "TEXT"
 	}
 ];
 var TRACKS_INDEXES = [{
@@ -1769,7 +2034,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 {
@@ -1903,6 +2171,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.
@@ -1973,7 +2272,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 } : {}
 			}
 		});
 	}
@@ -1982,6 +2284,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"]),
@@ -1994,7 +2299,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 } : {}
 		};
 	}
 };
@@ -2497,6 +2805,10 @@ var OBJECT_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
 	}
 ];
 var AUDIO_COLUMNS = [
@@ -2694,6 +3006,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
@@ -2888,7 +3257,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,
@@ -2918,6 +3288,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;
@@ -4537,6 +4918,14 @@ var FACE_COLUMNS = [
 	{
 		name: "assignedSampleId",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "faceBbox",
+		type: "JSON"
 	}
 ];
 var FACE_INDEXES = [{
@@ -4609,7 +4998,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);
 	}
@@ -4773,8 +5164,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
 		};
 	}
 	/**
@@ -4818,7 +5212,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";
@@ -4883,6 +5279,10 @@ var OBJECT_EMBEDDING_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
 	}
 ];
 var ObjectEmbeddingStore = class {
@@ -4929,7 +5329,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({
@@ -4967,7 +5368,8 @@ var ObjectEmbeddingStore = class {
 			return {
 				id: r.id,
 				...data,
-				mediaKey: data.mediaKey ?? void 0
+				mediaKey: data.mediaKey ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0
 			};
 		});
 	}
@@ -5096,6 +5498,8 @@ 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 = [];
@@ -5107,6 +5511,9 @@ var FaceRecognizer = class {
 	*  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;
 	}
@@ -5236,6 +5643,17 @@ var FaceRecognizer = class {
 					}
 				});
 			}
+			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)
+					}
+				});
+			}
 		}
 	}
 	/**
@@ -5255,9 +5673,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",
@@ -5275,6 +5707,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,
@@ -5282,9 +5725,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: {
@@ -5293,7 +5738,7 @@ var FaceRecognizer = class {
 				},
 				meta: {
 					faceId,
-					hasCrop: mediaKey !== void 0,
+					hasCrop: true,
 					recognizedIdentityId: held.recognizedIdentityId ?? null,
 					score: held.score
 				}
@@ -5625,6 +6070,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 (0, sharp.default)(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.
@@ -5929,6 +6406,18 @@ var SETTINGS_CACHE_TTL_MS = 5e3;
 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. */
@@ -6048,6 +6537,23 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		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). */
@@ -6081,7 +6587,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-CIEkEv1F.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-Cg_cGqs0.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -6147,23 +6653,62 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		});
 		const ownNodeIdForFaces = ownNodeId;
 		const frameReadersForFaces = this.frameReaders;
-		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding) => {
-			const decoded = await require_resolve_frame.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 } : {}
+				}, require_dist.nodePin(frameHandle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return await encodeRgbCropToJpeg(Buffer.from(native.bytes), native.width, native.height);
+			} catch (err) {
+				cropMetricLogger.debug("native crop request failed — falling back", { meta: { error: require_dist.errMsg(err) } });
+				return null;
+			}
+		};
+		const resolveFrameShared = createSharedFrameResolver((frameHandle) => require_resolve_frame.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 require_resolve_frame.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 require_resolve_frame.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,
@@ -6171,6 +6716,16 @@ var PipelineAnalyticsAddon = class extends require_dist.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();
@@ -6208,7 +6763,7 @@ var PipelineAnalyticsAddon = class extends require_dist.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,
@@ -6592,6 +7147,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.lastActiveTrackIds.clear();
 		this.dropoutSkipsByKey.clear();
 		this.bestFrameTracker.clear();
+		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
@@ -6747,16 +7303,18 @@ var PipelineAnalyticsAddon = class extends require_dist.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;
@@ -6829,6 +7387,7 @@ var PipelineAnalyticsAddon = class extends require_dist.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),
@@ -6950,6 +7509,83 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*    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: require_dist.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: require_dist.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) {
@@ -7221,9 +7857,36 @@ var PipelineAnalyticsAddon = class extends require_dist.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),
@@ -7446,6 +8109,32 @@ var PipelineAnalyticsAddon = class extends require_dist.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;
@@ -7488,6 +8177,12 @@ var PipelineAnalyticsAddon = class extends require_dist.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;
@@ -7534,10 +8229,20 @@ var PipelineAnalyticsAddon = class extends require_dist.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);
@@ -7569,6 +8274,24 @@ var PipelineAnalyticsAddon = class extends require_dist.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];