@camstack/addon-post-analysis 1.1.30 → 1.1.32

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { S as EventCategory, _ as hydrateSchema, b as object, c as nodePin, d as videoclipsCapability, f as zoneAnalyticsCapability, g as createEvent, 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, v as boolean, x as string, y as number } from "../dist-yPsKFcJL.mjs";
+import { C as EventCategory, S as string, _ as createEvent, a as cosineSimilarity, b as number, d as plateGalleryCapability, f as videoclipsCapability, g as DeviceType, h as BaseAddon, i as audioMetricsCapability, l as nodePin, m as errMsg, n as EVENT_PAD_MS, p as zoneAnalyticsCapability, r as addonWidgetsSourceCapability, s as faceGalleryCapability, t as EVENT_KIND_BY_CAP, u as pipelineAnalyticsCapability, v as hydrateSchema, x as object, y as boolean } from "../dist-CyyCe4TK.mjs";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 //#region src/pipeline-analytics/videoclips-provider.ts
@@ -160,13 +160,13 @@ 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([
+var VEHICLE_CLASSES$1 = new Set([
 	"vehicle",
 	"car",
 	"truck",
 	"bus"
 ]);
-var ANIMAL_CLASSES = new Set([
+var ANIMAL_CLASSES$1 = new Set([
 	"animal",
 	"dog",
 	"cat"
@@ -182,8 +182,8 @@ function clamp01(x) {
 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;
+	if (VEHICLE_CLASSES$1.has(c)) return CLASS_RANK_VEHICLE;
+	if (ANIMAL_CLASSES$1.has(c)) return CLASS_RANK_ANIMAL;
 	return CLASS_RANK_DEFAULT;
 }
 /**
@@ -1081,7 +1081,7 @@ function resolveDetectionLabel(input) {
 //#endregion
 //#region src/pipeline-analytics/pipeline/zones/geometry.ts
 /** Ray-casting point-in-polygon test */
-function pointInPolygon(point, polygon) {
+function pointInPolygon$1(point, polygon) {
 	if (polygon.length < 3) return false;
 	let inside = false;
 	for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
@@ -1472,6 +1472,7 @@ var DEFAULT_EVENT_EMITTER_CONFIG = {
 	minTrackAge: 3,
 	minTrackAgeMs: 0,
 	cooldownSec: 5,
+	emitAppearance: true,
 	enabledTypes: [
 		"object.entering",
 		"object.leaving",
@@ -1496,6 +1497,14 @@ var ZONE_TYPE_TO_EVENT = {
 	"zone-loiter": "zone.enter",
 	"tripwire-cross": "tripwire.cross"
 };
+/**
+* DetectionEventType used for the synthetic per-track APPEARANCE event
+* (Requirement 1). `object.detected` is otherwise unused by the emitter (it maps
+* from no state and no zone type), so repurposing it as the appearance marker
+* needs no new event-type vocabulary. The addon routes these into their own
+* media/persistence path and keeps them OFF the notification bus.
+*/
+var APPEARANCE_EVENT_TYPE = "object.detected";
 var eventIdCounter = 0;
 var DetectionEventEmitter = class {
 	config;
@@ -1508,6 +1517,13 @@ var DetectionEventEmitter = class {
 	* fired: the latent "0 `left` events in 24h" bug).
 	*/
 	lastKnownTracks = /* @__PURE__ */ new Map();
+	/**
+	* Track ids that have already been VALUED — either by a crop-bearing
+	* transition/zone event or by a synthetic appearance event. Ensures a track
+	* gets at most ONE appearance and never a redundant appearance on top of a
+	* real crop-bearing event (Requirement 1).
+	*/
+	valuedTracks = /* @__PURE__ */ new Set();
 	constructor(config = {}) {
 		this.config = {
 			...DEFAULT_EVENT_EMITTER_CONFIG,
@@ -1533,6 +1549,7 @@ var DetectionEventEmitter = class {
 			if ((now - (this.lastEmitted.get(cooldownKey) ?? 0)) / 1e3 < this.config.cooldownSec) continue;
 			this.previousStates.set(state.trackId, state.state);
 			this.lastEmitted.set(cooldownKey, now);
+			if (trackMap.has(state.trackId)) this.valuedTracks.add(state.trackId);
 			events.push({
 				id: `evt-${++eventIdCounter}`,
 				type: eventType,
@@ -1552,6 +1569,7 @@ var DetectionEventEmitter = class {
 			const track = trackMap.get(ze.trackId);
 			if (!track || track.trackAge < this.config.minTrackAge) continue;
 			const state = stateMap.get(ze.trackId);
+			this.valuedTracks.add(ze.trackId);
 			events.push({
 				id: `evt-${++eventIdCounter}`,
 				type: eventType,
@@ -1570,9 +1588,29 @@ var DetectionEventEmitter = class {
 				trackPath: [...track.path]
 			});
 		}
+		if (this.config.emitAppearance) for (const track of tracks) {
+			if (this.valuedTracks.has(track.trackId)) continue;
+			if (track.trackAge < this.config.minTrackAge) continue;
+			const state = stateMap.get(track.trackId);
+			if (!state) continue;
+			if (state.dwellTimeMs < this.config.minTrackAgeMs) continue;
+			this.valuedTracks.add(track.trackId);
+			events.push({
+				id: `evt-${++eventIdCounter}`,
+				type: APPEARANCE_EVENT_TYPE,
+				timestamp: now,
+				deviceId,
+				detection: track,
+				classifications,
+				objectState: state,
+				zoneEvents: [],
+				trackPath: [...track.path]
+			});
+		}
 		for (const state of states) if (state.state === "leaving") {
 			this.previousStates.delete(state.trackId);
 			this.lastKnownTracks.delete(state.trackId);
+			this.valuedTracks.delete(state.trackId);
 		}
 		return events;
 	}
@@ -1580,6 +1618,7 @@ var DetectionEventEmitter = class {
 		this.previousStates.clear();
 		this.lastEmitted.clear();
 		this.lastKnownTracks.clear();
+		this.valuedTracks.clear();
 	}
 };
 //#endregion
@@ -1594,7 +1633,7 @@ function bboxPolygonOverlap(bbox, polygon) {
 	const gridSize = 8;
 	let inside = 0;
 	const total = gridSize * gridSize;
-	for (let row = 0; row < gridSize; row++) for (let col = 0; col < gridSize; col++) if (pointInPolygon({
+	for (let row = 0; row < gridSize; row++) for (let col = 0; col < gridSize; col++) if (pointInPolygon$1({
 		x: bbox.x + (col + .5) * (bbox.w / gridSize),
 		y: bbox.y + (row + .5) * (bbox.h / gridSize)
 	}, polygon)) inside++;
@@ -1613,7 +1652,7 @@ function maskPolygonOverlap(mask, maskWidth, maskHeight, bbox, polygon, _frameWi
 	for (let my = 0; my < maskHeight; my++) for (let mx = 0; mx < maskWidth; mx++) {
 		if (mask[my * maskWidth + mx] === 0) continue;
 		totalMaskPixels++;
-		if (pointInPolygon({
+		if (pointInPolygon$1({
 			x: bbox.x + mx / maskWidth * bbox.w,
 			y: bbox.y + my / maskHeight * bbox.h
 		}, polygon)) insidePolygon++;
@@ -1942,9 +1981,9 @@ var FrameProcessor = class {
 				} : {}
 			};
 		});
-		const objectEvents = rawEvents.filter((e) => e.detection.trackId).map((e) => {
+		const toObjectEvent = (e, forcedState) => {
 			const td = trackedDetections.find((t) => t.trackId === e.detection.trackId);
-			const state = mapObjectStateToTrackState(objectStates.find((o) => o.trackId === e.detection.trackId)?.state);
+			const state = forcedState ?? mapObjectStateToTrackState(objectStates.find((o) => o.trackId === e.detection.trackId)?.state);
 			const zones = zonesByTrack.get(e.detection.trackId) ?? [];
 			const label = td ? resolveDetectionLabel({
 				className: td.class,
@@ -1973,7 +2012,10 @@ var FrameProcessor = class {
 				frameWidth,
 				frameHeight
 			};
-		});
+		};
+		const withTrackId = rawEvents.filter((e) => e.detection.trackId);
+		const objectEvents = withTrackId.filter((e) => e.type !== "object.detected").map((e) => toObjectEvent(e));
+		const appearanceEvents = withTrackId.filter((e) => e.type === "object.detected").map((e) => toObjectEvent(e, "entered"));
 		return {
 			deviceId: this.deviceId,
 			timestamp,
@@ -1981,6 +2023,7 @@ var FrameProcessor = class {
 			frameHeight,
 			tracked,
 			objectEvents,
+			appearanceEvents,
 			rawTrackedDetections: trackedDetections,
 			stationaryConfirmed: gate.confirmed,
 			stationaryWoken: gate.wokenEntryIds
@@ -2066,29 +2109,120 @@ function buildTrackLifecyclePayload(input) {
 		...hasMedia ? { media } : {}
 	};
 }
+/**
+* True when `bbox` sits fully inside the frame — no side within the tolerance
+* band of any border. Degenerate/unknown frame dims (≤ 0) return true so the
+* gate stays neutral (falls back to pure confidence) rather than demoting every
+* frame of a dims-less source.
+*/
+function isEdgeClear(input) {
+	const { bbox, frameWidth, frameHeight } = input;
+	if (frameWidth <= 0 || frameHeight <= 0) return true;
+	const tolerance = input.tolerance ?? .01;
+	const tolX = tolerance * frameWidth;
+	const tolY = tolerance * frameHeight;
+	const left = bbox.x;
+	const top = bbox.y;
+	const right = bbox.x + bbox.w;
+	const bottom = bbox.y + bbox.h;
+	if (left <= tolX) return false;
+	if (top <= tolY) return false;
+	if (right >= frameWidth - tolX) return false;
+	if (bottom >= frameHeight - tolY) return false;
+	return true;
+}
+/**
+* Edge-aware "is `candidate` a new best over `current`?" comparator.
+*
+* Tier order: edge-clear ALWAYS outranks edge-touching (a whole subject beats a
+* clipped one regardless of confidence). WITHIN the same tier, a strictly-higher
+* confidence past the `hysteresis` margin wins. The tier upgrade
+* (touching → clear) bypasses hysteresis — the first clear frame is always taken.
+*
+* Time gating (`minGapMs`) is applied by the caller (`BestDetectionTracker`),
+* not here, so this stays a pure value comparison.
+*/
+function isEdgeAwareNewBest(current, candidate, hysteresis) {
+	if (candidate.edgeClear && !current.edgeClear) return true;
+	if (!candidate.edgeClear && current.edgeClear) return false;
+	return candidate.confidence > current.confidence + hysteresis;
+}
 //#endregion
 //#region src/pipeline-analytics/pipeline/best-detection-tracker.ts
+/**
+* `BestDetectionTracker` — the SINGLE canonical policy for "the best detection
+* per track" (highest detector confidence per `trackId`).
+*
+* Post-analysis derives three per-track "best" artefacts, all keyed by
+* trackId + confidence, that used to each re-implement the same ranking inline:
+*  1. the best FRAME (a boxed `thumbnail`) — `index.ts`,
+*  2. the best FACE crop + its arcface embedding — `face-recognizer.ts`,
+*  3. the best CLIP object embedding — `store/object-embedding-store.ts`.
+*
+* Consumers 1 & 2 now share THIS one implementation so a track's best frame and
+* its best face crop derive from the same confidence ranking (and, when the peak
+* frame carries a detected face, the same frame). Consumer 3 (CLIP) is a
+* DOCUMENTED SEAM: its `upsertIfBetter` is persistence-backed (its best survives
+* an addon restart, which this in-memory tracker deliberately does not), so it
+* keeps its own store-side "if better" gate rather than reading this tracker.
+*
+* The FACE seam: the best FRAME is ranked over ALL tracked detections, while the
+* best FACE can only be captured on a frame that actually produced a face
+* embedding — so the two legitimately diverge when the peak-confidence frame has
+* no detected face. Each consumer therefore keeps its OWN payload (crop /
+* embedding / boxed frame); only the ranking DECISION is unified here.
+*/
 var BestDetectionTracker = class {
 	hysteresis;
 	minGapMs;
 	best = /* @__PURE__ */ new Map();
+	/** Held peak's edge-clear tier, kept PARALLEL to `best` so `peak()`'s
+	*  `{ confidence, atMs }` shape (a public contract) stays unchanged. Absent =
+	*  the edge tier is not in play for the track (treated as clear → the legacy
+	*  pure-confidence policy). */
+	edgeClear = /* @__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.
+	* Returns true when it becomes the track's new best.
+	*
+	* When `edgeClear` is supplied, an EDGE-AWARE policy applies: an edge-clear
+	* frame (whole subject in view) ALWAYS outranks an edge-touching one (a
+	* clipped, partial subject); the tier upgrade bypasses hysteresis + `minGapMs`
+	* so the first clear frame is always taken. WITHIN the same tier — and when
+	* `edgeClear` is omitted (legacy callers: the face + object-embedding paths) —
+	* the classic policy holds: a confidence past the `hysteresis` margin that also
+	* respects `minGapMs` wins. On acceptance the held peak advances.
 	*/
-	observe(trackId, confidence, timestamp) {
+	observe(trackId, confidence, timestamp, edgeClear) {
 		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, {
+		if (cur === void 0) {
+			this.best.set(trackId, {
+				confidence,
+				atMs: timestamp
+			});
+			if (edgeClear !== void 0) this.edgeClear.set(trackId, edgeClear);
+			return true;
+		}
+		const curClear = this.edgeClear.get(trackId) ?? true;
+		const candClear = edgeClear ?? true;
+		const isNewBest = candClear && !curClear ? true : isEdgeAwareNewBest({
+			confidence: cur.confidence,
+			edgeClear: curClear
+		}, {
 			confidence,
-			atMs: timestamp
-		});
+			edgeClear: candClear
+		}, this.hysteresis) && timestamp - cur.atMs >= this.minGapMs;
+		if (isNewBest) {
+			this.best.set(trackId, {
+				confidence,
+				atMs: timestamp
+			});
+			if (edgeClear !== void 0) this.edgeClear.set(trackId, edgeClear);
+		}
 		return isNewBest;
 	}
 	/** The held peak for a track (undefined if never observed). */
@@ -2098,9 +2232,11 @@ var BestDetectionTracker = class {
 	/** Drop a track's peak (call at track end). */
 	delete(trackId) {
 		this.best.delete(trackId);
+		this.edgeClear.delete(trackId);
 	}
 	clear() {
 		this.best.clear();
+		this.edgeClear.clear();
 	}
 };
 //#endregion
@@ -2228,16 +2364,23 @@ function entryToView(e) {
 		...e.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: e.keyFrameMediaKey } : {}
 	};
 }
-/** IoU at/above which a detection is "the same parked object" → suppress its
-*  spawn and refresh the entry's `lastConfirmedAt`. Matches decision #2 (0.6). */
+/** IoU at/above which a detection is unambiguously "the same parked object,
+*  unmoved" → suppress its spawn and refresh `lastConfirmedAt`. Decision #2. */
 var SUPPRESS_IOU = .6;
-/** Centroid move (fraction of the frame diagonal) beyond which a near
-*  same-class detection means the parked object actually MOVED → wake. */
-var WAKE_MOVE_FRAC = .08;
-/** How near (fraction of frame diagonal) a same-class detection's centroid must
-*  be to an entry to be considered "this entry's object" when testing for a
-*  wake. Keeps an unrelated object elsewhere in the frame from waking it. */
-var WAKE_SEARCH_FRAC = .5;
+/**
+* Minimum IoU for a same-class detection to be ASSOCIATED with an entry — i.e.
+* to be considered THIS parked object's own (possibly jittered/shifted) box
+* rather than a DIFFERENT vehicle. Below this floor a detection can neither
+* confirm nor wake the entry (it is a different object).
+*
+* This overlap gate is the fix for the 617 parking-lot flood: the previous
+* wake test used a centroid-distance radius of half the frame diagonal, so any
+* other vehicle merely PRESENT in the lot (a car driving through, or a second
+* car parked ~120px away) satisfied "near + moved" and retired the parked
+* entry — the parked car then re-spawned a fresh track and re-flooded, over and
+* over. Requiring real box overlap means only the entry's OWN box can wake it.
+*/
+var WAKE_ASSOC_IOU = .1;
 /**
 * Look-back window over which a track must have stayed put to be PROMOTED. A
 * car that drives in then parks has a large whole-life displacement but a tiny
@@ -2248,8 +2391,7 @@ var WAKE_SEARCH_FRAC = .5;
 var PROMOTION_WINDOW_MS = 3e4;
 var DEFAULT_MATCH_CONFIG = {
 	suppressIou: SUPPRESS_IOU,
-	wakeMoveFrac: WAKE_MOVE_FRAC,
-	wakeSearchFrac: WAKE_SEARCH_FRAC
+	wakeAssocIou: WAKE_ASSOC_IOU
 };
 //#endregion
 //#region src/pipeline-analytics/pipeline/stationary/stationary-match.ts
@@ -2296,36 +2438,45 @@ function centroid(b) {
 		y: b.y + b.h / 2
 	};
 }
-function diagonalOf(width, height) {
-	return Math.hypot(width, height);
+/** Is point `p` inside box `b`? Used to distinguish box JITTER (centre stays
+*  inside the parked box → suppress) from the object DEPARTING (centre slides
+*  out while the box still overlaps → wake). */
+function centroidInside(b, p) {
+	return p.x >= b.x && p.x <= b.x + b.w && p.y >= b.y && p.y <= b.y + b.h;
 }
 /**
 * Decide, per stationary entry, whether the current frame confirms it, wakes
 * it, or misses it (no matching detection — leave it for the TTL sweep).
 *
-* Per entry, over same-class detections:
-*  - best IoU ≥ `suppressIou` → SUPPRESS the best-overlap detection (it is the
-*    parked object, unmoved) and mark the entry confirmed.
-*  - else if a same-class detection sits within `wakeSearchFrac × diag` of the
-*    entry centroid but has moved > `wakeMoveFrac × diag` → WAKE the entry (the
-*    object slid out of its parked box). The detection is NOT suppressed, so it
-*    spawns a fresh moving track.
-*  - else → MISS (occlusion / brief absence): neither suppress nor wake.
+* Matching is ASSOCIATION-GATED by box overlap so an entry can only ever be
+* confirmed or woken by ITS OWN object — never by a different same-class
+* vehicle merely present elsewhere in the frame (the 617 parking-lot flood:
+* passing/neighbouring cars used to retire parked entries, forcing endless
+* re-spawns). Per entry, over the best-overlapping same-class detection:
+*
+*  - best IoU ≥ `suppressIou` → SUPPRESS (the parked object, near-identical box)
+*    and mark the entry confirmed.
+*  - `wakeAssocIou` ≤ best IoU < `suppressIou`, centroid still INSIDE the parked
+*    box → SUPPRESS (detector box jitter — the box shrank/grew around the same
+*    centre; still the parked object, must not spawn a duplicate track).
+*  - `wakeAssocIou` ≤ best IoU < `suppressIou`, centroid OUTSIDE the parked box
+*    → WAKE (the object's box slid off its spot → it is departing). Not
+*    suppressed, so it spawns a fresh moving track.
+*  - best IoU < `wakeAssocIou` → MISS: no detection overlaps this entry (a
+*    different object, or the parked object is momentarily undetected). Neither
+*    suppress nor wake; the TTL sweep retires it only if the absence persists.
 *
 * A detection can suppress at most one spawn even if it overlaps two entries
 * (`suppressedIndices` is a set).
 */
 function partitionDetectionsAgainstRegistry(input) {
-	const { entries, detections, referenceDiagonalPx, config } = input;
+	const { entries, detections, config } = input;
 	const suppressed = /* @__PURE__ */ new Set();
 	const confirmed = [];
 	const woken = [];
-	const diag = referenceDiagonalPx;
 	for (const entry of entries) {
-		const ec = centroid(entry.bbox);
 		let bestIou = 0;
 		let bestIdx = -1;
-		let wakeCandidate = false;
 		for (let di = 0; di < detections.length; di++) {
 			const det = detections[di];
 			if (det.className !== entry.className) continue;
@@ -2334,20 +2485,17 @@ function partitionDetectionsAgainstRegistry(input) {
 				bestIou = o;
 				bestIdx = di;
 			}
-			if (diag > 0) {
-				const dc = centroid(det.bbox);
-				const dist = Math.hypot(dc.x - ec.x, dc.y - ec.y);
-				if (dist <= config.wakeSearchFrac * diag && dist > config.wakeMoveFrac * diag) wakeCandidate = true;
-			}
 		}
-		if (bestIou >= config.suppressIou && bestIdx >= 0) {
+		if (bestIdx < 0 || bestIou < config.wakeAssocIou) continue;
+		const detCentroid = centroid(detections[bestIdx].bbox);
+		if (bestIou >= config.suppressIou || centroidInside(entry.bbox, detCentroid)) {
 			suppressed.add(bestIdx);
 			confirmed.push({
 				entryId: entry.id,
 				className: entry.className,
 				bbox: { ...entry.bbox }
 			});
-		} else if (wakeCandidate) woken.push(entry.id);
+		} else woken.push(entry.id);
 	}
 	return {
 		suppressedIndices: suppressed,
@@ -2524,7 +2672,6 @@ var StationaryObjectRegistry = class {
 		return partitionDetectionsAgainstRegistry({
 			entries,
 			detections: input.detections,
-			referenceDiagonalPx: diagonalOf(input.frameWidth, input.frameHeight),
 			config: this.matchConfig
 		});
 	}
@@ -2738,7 +2885,7 @@ function computeStationaryEntryZones(entry, zones) {
 	const matched = [];
 	for (const zone of zones) {
 		if (zone.polygon.length < 3) continue;
-		if (pointInPolygon(point, zone.polygon)) matched.push(zone.id);
+		if (pointInPolygon$1(point, zone.polygon)) matched.push(zone.id);
 	}
 	return matched;
 }
@@ -2955,11 +3102,196 @@ var BindingCache = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/store/recent-cursor.ts
+function encodeRecentCursor(cursor) {
+	return Buffer.from(JSON.stringify({
+		l: cursor.lastSeen,
+		i: cursor.trackId
+	}), "utf8").toString("base64url");
+}
+/**
+* Decode + validate an opaque cursor. Fails fast with a clear error on any
+* malformed input (bad base64, bad JSON, wrong field types) — a garbage
+* cursor must never silently degrade into a full-history first page.
+*/
+function decodeRecentCursor(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+	} catch {
+		throw new Error("listRecentTracks: malformed cursor");
+	}
+	if (parsed === null || typeof parsed !== "object" || !("l" in parsed) || !("i" in parsed) || typeof parsed.l !== "number" || !Number.isFinite(parsed.l) || typeof parsed.i !== "string" || parsed.i.length === 0) throw new Error("listRecentTracks: malformed cursor");
+	return {
+		lastSeen: parsed.l,
+		trackId: parsed.i
+	};
+}
+/** Comparator for the (lastSeen DESC, id DESC) total order. */
+function compareRecentDesc(a, b) {
+	if (a.lastSeen !== b.lastSeen) return b.lastSeen - a.lastSeen;
+	if (a.id === b.id) return 0;
+	return a.id < b.id ? 1 : -1;
+}
+/** True when `row` sits strictly AFTER the cursor position in DESC order
+*  (i.e. belongs to the next page). */
+function isAfterCursor(row, cursor) {
+	if (row.lastSeen < cursor.lastSeen) return true;
+	return row.lastSeen === cursor.lastSeen && row.id < cursor.trackId;
+}
+//#endregion
+//#region src/pipeline-analytics/store/zone-geometry.ts
+/**
+* Normalized min/max envelope over every position's bbox. Returns `null`
+* when the frame dimensions are unknown/degenerate or there are no
+* positions — the caller persists NULL envelope columns in that case.
+*/
+function computeTrackEnvelope(positions, frameWidth, frameHeight) {
+	if (frameWidth === void 0 || frameHeight === void 0 || !(frameWidth > 0) || !(frameHeight > 0) || positions.length === 0) return null;
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	for (const p of positions) {
+		const x0 = p.bbox.x / frameWidth;
+		const y0 = p.bbox.y / frameHeight;
+		const x1 = (p.bbox.x + p.bbox.w) / frameWidth;
+		const y1 = (p.bbox.y + p.bbox.h) / frameHeight;
+		if (x0 < minX) minX = x0;
+		if (y0 < minY) minY = y0;
+		if (x1 > maxX) maxX = x1;
+		if (y1 > maxY) maxY = y1;
+	}
+	return {
+		minX,
+		minY,
+		maxX,
+		maxY
+	};
+}
+/**
+* Axis-aligned bounds of a zone filter (rect: itself; polygon: vertex
+* min/max). A degenerate polygon (< 3 points) yields the full frame so the
+* SQL prefilter never silently drops rows the precise test would keep.
+*/
+function zoneBounds(zone) {
+	if (zone.kind === "rect") return {
+		minX: zone.x,
+		minY: zone.y,
+		maxX: zone.x + zone.width,
+		maxY: zone.y + zone.height
+	};
+	if (zone.points.length < 3) return {
+		minX: 0,
+		minY: 0,
+		maxX: 1,
+		maxY: 1
+	};
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	for (const p of zone.points) {
+		if (p.x < minX) minX = p.x;
+		if (p.y < minY) minY = p.y;
+		if (p.x > maxX) maxX = p.x;
+		if (p.y > maxY) maxY = p.y;
+	}
+	return {
+		minX,
+		minY,
+		maxX,
+		maxY
+	};
+}
+/** Whether two axis-aligned envelopes overlap (touching edges count). */
+function envelopesOverlap(a, b) {
+	return a.minX <= b.maxX && a.maxX >= b.minX && a.minY <= b.maxY && a.maxY >= b.minY;
+}
+/**
+* Ray-casting point-in-polygon (even-odd rule). Points on an edge may
+* resolve either way — acceptable for zone filtering. A polygon with
+* fewer than 3 vertices contains nothing.
+*/
+function pointInPolygon(point, polygon) {
+	if (polygon.length < 3) return false;
+	let inside = false;
+	for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+		const a = polygon[i];
+		const b = polygon[j];
+		if (a.y > point.y !== b.y > point.y && point.x < (b.x - a.x) * (point.y - a.y) / (b.y - a.y) + a.x) inside = !inside;
+	}
+	return inside;
+}
+/**
+* Precise per-position zone test.
+*
+*   - rect zone     → any position bbox (normalized) intersects the rect.
+*   - polygon zone  → any position CENTER (normalized `x`/`y` — positions
+*                     store the bbox center) falls inside the polygon.
+*
+* Unknown/degenerate frame dims → `true` (the track cannot be tested, so it
+* PASSES — mirroring the NULL-envelope-matches rule).
+*/
+function positionsIntersectZone(positions, frameWidth, frameHeight, zone) {
+	if (frameWidth === void 0 || frameHeight === void 0 || !(frameWidth > 0) || !(frameHeight > 0)) return true;
+	if (zone.kind === "rect") {
+		const rect = zoneBounds(zone);
+		for (const p of positions) if (envelopesOverlap({
+			minX: p.bbox.x / frameWidth,
+			minY: p.bbox.y / frameHeight,
+			maxX: (p.bbox.x + p.bbox.w) / frameWidth,
+			maxY: (p.bbox.y + p.bbox.h) / frameHeight
+		}, rect)) return true;
+		return false;
+	}
+	for (const p of positions) if (pointInPolygon({
+		x: p.x / frameWidth,
+		y: p.y / frameHeight
+	}, zone.points)) return true;
+	return false;
+}
+//#endregion
 //#region src/pipeline-analytics/store/track-store.ts
 var DEFAULT_CONFIG = {
 	ttlMs: 3e4,
 	maxPositionHistory: 300
 };
+/** `queryRecent` page-size defaults (mirrors the cap input's bounds). */
+var RECENT_DEFAULT_LIMIT = 200;
+var RECENT_MAX_LIMIT = 1e3;
+/** Wide inclusive bound for the envelope-overlap `BETWEEN` prefilter.
+*  Envelope values are normalized ~0..1 but a bbox can spill slightly past
+*  the frame edge; ±1e6 keeps every real value inside the range while the
+*  opposing bound does the actual overlap cut. */
+var ENV_RANGE_SLACK = 1e6;
+function rowMatchesZone(data, zone) {
+	const fw = data["frameWidth"];
+	const fh = data["frameHeight"];
+	if (typeof fw !== "number" || typeof fh !== "number") return true;
+	const positions = data["positions"];
+	if (!Array.isArray(positions)) return true;
+	const positionRows = [];
+	for (const p of positions) {
+		if (p === null || typeof p !== "object") continue;
+		if (!("x" in p) || typeof p.x !== "number" || !("y" in p) || typeof p.y !== "number") continue;
+		if (!("bbox" in p) || p.bbox === null || typeof p.bbox !== "object") continue;
+		const b = p.bbox;
+		if (!("x" in b) || typeof b.x !== "number" || !("y" in b) || typeof b.y !== "number") continue;
+		if (!("w" in b) || typeof b.w !== "number" || !("h" in b) || typeof b.h !== "number") continue;
+		positionRows.push({
+			x: p.x,
+			y: p.y,
+			bbox: {
+				x: b.x,
+				y: b.y,
+				w: b.w,
+				h: b.h
+			}
+		});
+	}
+	return positionsIntersectZone(positionRows, fw, fh, zone);
+}
 var TRACKS_COLLECTION = "pipeline-analytics:tracks";
 var TRACKS_COLUMNS = [
 	{
@@ -3031,6 +3363,30 @@ var TRACKS_COLUMNS = [
 	{
 		name: "audioLabels",
 		type: "JSON"
+	},
+	{
+		name: "envMinX",
+		type: "REAL"
+	},
+	{
+		name: "envMinY",
+		type: "REAL"
+	},
+	{
+		name: "envMaxX",
+		type: "REAL"
+	},
+	{
+		name: "envMaxY",
+		type: "REAL"
+	},
+	{
+		name: "frameWidth",
+		type: "INTEGER"
+	},
+	{
+		name: "frameHeight",
+		type: "INTEGER"
 	}
 ];
 var TRACKS_INDEXES = [{
@@ -3086,6 +3442,7 @@ var TrackStore = class {
 	config;
 	logger;
 	store;
+	frameDims;
 	constructor(deps) {
 		this.logger = deps.logger;
 		this.store = deps.store;
@@ -3093,6 +3450,7 @@ var TrackStore = class {
 			...DEFAULT_CONFIG,
 			...deps.config
 		};
+		this.frameDims = deps.frameDims;
 	}
 	/** One-time collection declaration. Call from addon onInitialize. */
 	static async declare(store) {
@@ -3439,21 +3797,200 @@ var TrackStore = class {
 		}
 		return [...seenDevices];
 	}
-	/** Historical query — hits the persisted collection. */
+	/** Historical query — hits the persisted collection. With `zone` set,
+	*  candidates are SQL-prefiltered on the envelope columns (overlap test via
+	*  `whereBetween`), NULL-envelope rows are re-fetched separately (they must
+	*  still MATCH — `BETWEEN` excludes NULL), and survivors run the precise
+	*  per-position test against the zone. `projection: 'slim'` drops the heavy
+	*  `positions[]` / `snapshots[]` JSON from the returned rows (empty arrays);
+	*  the zone test still runs on the stored positions before the drop. */
 	async queryHistorical(params) {
-		const filter = { where: { deviceId: params.deviceId } };
-		if (params.since !== void 0 || params.until !== void 0) filter.whereBetween = { firstSeen: [params.since ?? 0, params.until ?? Date.now()] };
-		return (await this.store.query.query({
+		const limit = params.limit ?? 50;
+		const timeBetween = params.since !== void 0 || params.until !== void 0 ? { firstSeen: [params.since ?? 0, params.until ?? Date.now()] } : {};
+		if (params.zone === void 0) return (await this.store.query.query({
+			collection: TRACKS_COLLECTION,
+			filter: {
+				where: { deviceId: params.deviceId },
+				...Object.keys(timeBetween).length > 0 ? { whereBetween: timeBetween } : {},
+				orderBy: {
+					field: "firstSeen",
+					direction: "desc"
+				},
+				limit
+			}
+		})).map((r) => this.rowToTrack(r.id, r.data, params.projection));
+		const zone = params.zone;
+		const bounds = zoneBounds(zone);
+		const overlapQuery = this.store.query.query({
+			collection: TRACKS_COLLECTION,
+			filter: {
+				where: { deviceId: params.deviceId },
+				whereBetween: {
+					...timeBetween,
+					envMinX: [-1e6, bounds.maxX],
+					envMaxX: [bounds.minX, ENV_RANGE_SLACK],
+					envMinY: [-1e6, bounds.maxY],
+					envMaxY: [bounds.minY, ENV_RANGE_SLACK]
+				},
+				orderBy: {
+					field: "firstSeen",
+					direction: "desc"
+				},
+				limit
+			}
+		});
+		const nullEnvQuery = this.store.query.query({
 			collection: TRACKS_COLLECTION,
 			filter: {
-				...filter,
+				where: { deviceId: params.deviceId },
+				...Object.keys(timeBetween).length > 0 ? { whereBetween: timeBetween } : {},
 				orderBy: {
 					field: "firstSeen",
 					direction: "desc"
 				},
-				limit: params.limit ?? 50
+				limit
+			}
+		});
+		const [overlapRows, windowRows] = await Promise.all([overlapQuery, nullEnvQuery]);
+		const candidates = /* @__PURE__ */ new Map();
+		for (const r of overlapRows) if (typeof r.data["envMinX"] === "number") candidates.set(r.id, r.data);
+		for (const r of windowRows) if (r.data["envMinX"] === null || r.data["envMinX"] === void 0) candidates.set(r.id, r.data);
+		const matched = [];
+		for (const [id, data] of candidates) if (rowMatchesZone(data, zone)) matched.push({
+			id,
+			data
+		});
+		matched.sort((a, b) => Number(b.data["firstSeen"] ?? 0) - Number(a.data["firstSeen"] ?? 0));
+		return matched.slice(0, limit).map((r) => this.rowToTrack(r.id, r.data, params.projection));
+	}
+	/**
+	* Batched multi-device recent-tracks page (`listRecentTracks`): the
+	* persisted completed tracks of every requested device, merged and ordered
+	* by (`lastSeen` DESC, `trackId` DESC) with a stable opaque cursor.
+	*
+	* Approach — per-device indexed page + k-way merge (documented for the
+	* cap): each device is fetched with ONE indexed query on
+	* `idx_tracks_device_lastSeen` (`WHERE deviceId = ? AND lastSeen BETWEEN
+	* ? AND ? ORDER BY lastSeen DESC LIMIT limit+1`), then the pages are
+	* merged in memory and cut to `limit`. At events-page cardinalities
+	* (≤ dozens of devices × ≤ 1000 rows) the in-memory merge is negligible
+	* next to the row I/O, and every row fetched is a candidate (no scan
+	* waste). The +1 overfetch makes `nextCursor` exact: when the merged
+	* candidate set exceeds `limit` more rows are KNOWN to exist; when it
+	* does not, every device returned fewer rows than asked for and is
+	* therefore exhausted — so the final page always ends with
+	* `nextCursor: null` (no empty trailing page).
+	*
+	* Cursor correctness: SQL can only bound `lastSeen`, and rows sharing the
+	* cursor's exact millisecond have no defined SQL order — so a cursor page
+	* runs TWO ranges per device: an exhaustive same-millisecond tie query
+	* (`lastSeen = cursor.lastSeen`, id tie-break applied in memory) plus the
+	* strictly-older indexed page (`lastSeen ≤ cursor.lastSeen - 1`). Tie
+	* clusters are same-ms track expiries on one camera — physically tiny —
+	* so the unbounded tie query stays O(1) in practice. Known accepted edge:
+	* on a NON-cursor page, a same-ms tie cluster straddling a device's
+	* `limit+1` SQL cut could omit a tie row (needs > limit rows sharing one
+	* millisecond on one camera — unreachable at these cardinalities).
+	*
+	* Errors propagate (no partial merges): a failed device query fails the
+	* page rather than silently returning an incomplete window.
+	*/
+	async queryRecent(params) {
+		const limit = Math.min(Math.max(params.limit ?? RECENT_DEFAULT_LIMIT, 1), RECENT_MAX_LIMIT);
+		const deviceIds = [...new Set(params.deviceIds)];
+		if (deviceIds.length === 0) return {
+			tracks: [],
+			nextCursor: null
+		};
+		const cursor = params.cursor !== void 0 ? decodeRecentCursor(params.cursor) : null;
+		const lo = params.since ?? 0;
+		const winHi = params.until ?? Number.MAX_SAFE_INTEGER;
+		const hi = cursor !== null ? Math.min(cursor.lastSeen, winHi) : winHi;
+		if (hi < lo) return {
+			tracks: [],
+			nextCursor: null
+		};
+		const fetchRange = async (deviceId, range, pageLimit) => this.store.query.query({
+			collection: TRACKS_COLLECTION,
+			filter: {
+				where: { deviceId },
+				whereBetween: { lastSeen: range },
+				orderBy: {
+					field: "lastSeen",
+					direction: "desc"
+				},
+				...pageLimit !== void 0 ? { limit: pageLimit } : {}
+			}
+		});
+		const perDevice = await Promise.all(deviceIds.map(async (deviceId) => {
+			if (cursor === null || cursor.lastSeen > hi) return fetchRange(deviceId, [lo, hi], limit + 1);
+			const tieRange = [cursor.lastSeen, cursor.lastSeen];
+			const belowHi = cursor.lastSeen - 1;
+			const [ties, below] = await Promise.all([cursor.lastSeen >= lo ? fetchRange(deviceId, tieRange) : Promise.resolve([]), belowHi >= lo ? fetchRange(deviceId, [lo, belowHi], limit + 1) : Promise.resolve([])]);
+			return [...ties, ...below];
+		}));
+		const candidates = [];
+		for (const rows of perDevice) for (const r of rows) {
+			const lastSeen = Number(r.data["lastSeen"] ?? 0);
+			if (cursor !== null && !isAfterCursor({
+				lastSeen,
+				id: r.id
+			}, cursor)) continue;
+			candidates.push({
+				id: r.id,
+				lastSeen,
+				data: r.data
+			});
+		}
+		candidates.sort(compareRecentDesc);
+		const page = candidates.slice(0, limit);
+		const tracks = page.map((r) => this.rowToTrack(r.id, r.data, params.projection));
+		const last = page[page.length - 1];
+		return {
+			tracks,
+			nextCursor: candidates.length > limit && last !== void 0 ? encodeRecentCursor({
+				lastSeen: last.lastSeen,
+				trackId: last.id
+			}) : null
+		};
+	}
+	/**
+	* Deduplicated detector class names observed on a device's RECENT persisted
+	* tracks (one indexed page, `lastSeen` desc). Feeds `listEventKinds` — a
+	* representative "what has this camera actually seen" set, not an exhaustive
+	* all-time DISTINCT (the query cap has none). Unions the primary `className`
+	* with the accumulated `classes` array. Best-effort: [] on error.
+	*/
+	async observedClassNames(deviceId, limit = 500) {
+		try {
+			const rows = await this.store.query.query({
+				collection: TRACKS_COLLECTION,
+				filter: {
+					where: { deviceId },
+					orderBy: {
+						field: "lastSeen",
+						direction: "desc"
+					},
+					limit
+				}
+			});
+			const names = /* @__PURE__ */ new Set();
+			for (const r of rows) {
+				const className = r.data["className"];
+				if (typeof className === "string" && className.length > 0) names.add(className);
+				const classes = r.data["classes"];
+				if (Array.isArray(classes)) {
+					for (const c of classes) if (typeof c === "string" && c.length > 0) names.add(c);
+				}
 			}
-		})).map((r) => this.rowToTrack(r.id, r.data));
+			return [...names];
+		} catch (err) {
+			this.logger.warn("TrackStore.observedClassNames failed", { meta: {
+				deviceId,
+				error: String(err)
+			} });
+			return [];
+		}
 	}
 	async getPersistedByTrackId(trackId) {
 		const records = await this.store.query.query({
@@ -3468,6 +4005,8 @@ var TrackStore = class {
 		return this.rowToTrack(row.id, row.data);
 	}
 	async persistCompleted(t) {
+		const dims = this.frameDims?.(t.deviceId);
+		const envelope = computeTrackEnvelope(t.positions, dims?.w, dims?.h);
 		await this.store.set.mutate({
 			collection: TRACKS_COLLECTION,
 			key: t.trackId,
@@ -3486,13 +4025,30 @@ var TrackStore = class {
 				...t.importance !== void 0 ? { importance: t.importance } : {},
 				...t.bestEventId !== void 0 ? { bestEventId: t.bestEventId } : {},
 				...t.importanceReason !== void 0 ? { importanceReason: t.importanceReason } : {},
-				...t.audioLabels !== void 0 ? { audioLabels: [...t.audioLabels] } : {}
+				...t.audioLabels !== void 0 ? { audioLabels: [...t.audioLabels] } : {},
+				...envelope !== null && dims !== void 0 ? {
+					envMinX: envelope.minX,
+					envMinY: envelope.minY,
+					envMaxX: envelope.maxX,
+					envMaxY: envelope.maxY,
+					frameWidth: dims.w,
+					frameHeight: dims.h
+				} : {}
 			}
 		});
 	}
-	rowToTrack(id, data) {
-		const positions = data["positions"] ?? [];
-		const snapshots = data["snapshots"] ?? [];
+	/**
+	* Map a persisted row onto the cap `Track` shape. `projection: 'slim'`
+	* drops the heavy `positions[]` / `snapshots[]` JSON (returned as empty
+	* arrays — they are required on the schema) while keeping every scalar
+	* the list surfaces render; `full` (default) is byte-compatible with the
+	* pre-projection behaviour. The persisted envelope columns surface as the
+	* optional `envelope` object in BOTH projections (four light numbers).
+	*/
+	rowToTrack(id, data, projection) {
+		const slim = projection === "slim";
+		const positions = slim ? [] : data["positions"] ?? [];
+		const snapshots = slim ? [] : data["snapshots"] ?? [];
 		const zones = data["zonesVisited"] ?? [];
 		const classes = data["classes"];
 		const label = data["label"];
@@ -3500,6 +4056,16 @@ var TrackStore = class {
 		const bestEventId = data["bestEventId"];
 		const importanceReason = data["importanceReason"];
 		const audioLabels = data["audioLabels"];
+		const envMinX = data["envMinX"];
+		const envMinY = data["envMinY"];
+		const envMaxX = data["envMaxX"];
+		const envMaxY = data["envMaxY"];
+		const envelope = typeof envMinX === "number" && typeof envMinY === "number" && typeof envMaxX === "number" && typeof envMaxY === "number" ? {
+			minX: envMinX,
+			minY: envMinY,
+			maxX: envMaxX,
+			maxY: envMaxY
+		} : null;
 		return {
 			trackId: id,
 			deviceId: Number(data["deviceId"]),
@@ -3517,7 +4083,8 @@ var TrackStore = class {
 			...typeof importance === "number" ? { importance } : {},
 			...typeof bestEventId === "string" ? { bestEventId } : {},
 			...typeof importanceReason === "string" ? { importanceReason } : {},
-			...Array.isArray(audioLabels) && audioLabels.length > 0 ? { audioLabels } : {}
+			...Array.isArray(audioLabels) && audioLabels.length > 0 ? { audioLabels } : {},
+			...envelope !== null ? { envelope } : {}
 		};
 	}
 };
@@ -4287,10 +4854,21 @@ var EventStore = class {
 	}
 	/**
 	* 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
+	* frame area), and its representative event id — the SHARED per-track ranking
+	* 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.
+	*
+	* `peakConfidence` + `peakBboxAreaFrac` always track the TRUE confidence peak
+	* (over every crop-bearing row) — importance reads them.
+	*
+	* `bestEventId` treats the synthetic APPEARANCE / entry event (state
+	* `'entered'`, Requirement 1) as a FLOOR: it represents the track only when no
+	* genuine ACTIVITY event (any other state — a zone / stationary / moving
+	* moment) exists. So a degenerate passer-by whose only crop-bearing event is
+	* its appearance still gets a representative id, while a track that later
+	* produced a real activity event surfaces THAT as its best. Within a tier the
+	* highest confidence wins.
 	*/
 	async peakForTrack(trackId) {
 		const rows = await this.store.query.query({
@@ -4298,8 +4876,11 @@ var EventStore = class {
 			filter: { where: { trackId } }
 		});
 		let bestConf = -1;
-		let bestEventId;
 		let peakBboxAreaFrac = 0;
+		let activityConf = -1;
+		let activityId;
+		let entryConf = -1;
+		let entryId;
 		for (const row of rows) {
 			const bbox = row.data["bbox"];
 			if (bbox !== null && typeof bbox === "object") {
@@ -4308,15 +4889,24 @@ var EventStore = class {
 				if (bw <= 0 || bh <= 0) continue;
 			}
 			const conf = typeof row.data["confidence"] === "number" ? row.data["confidence"] : 0;
-			if (conf <= bestConf) continue;
-			bestConf = conf;
-			bestEventId = row.id;
-			peakBboxAreaFrac = bboxAreaFrac(row.data);
+			if (conf > bestConf) {
+				bestConf = conf;
+				peakBboxAreaFrac = bboxAreaFrac(row.data);
+			}
+			if (row.data["state"] === "entered") {
+				if (conf > entryConf) {
+					entryConf = conf;
+					entryId = row.id;
+				}
+			} else if (conf > activityConf) {
+				activityConf = conf;
+				activityId = row.id;
+			}
 		}
 		return {
 			peakConfidence: bestConf < 0 ? 0 : bestConf,
 			peakBboxAreaFrac,
-			bestEventId
+			bestEventId: activityId ?? entryId
 		};
 	}
 	/**
@@ -4628,6 +5218,384 @@ function stripNulls(data) {
 	return out;
 }
 //#endregion
+//#region src/pipeline-analytics/store/sensor-event-store.ts
+var SENSOR_EVENTS_COLLECTION = "pipeline-analytics:sensor-events";
+var SENSOR_EVENT_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	(
+	/** The CAMERA the event is attributed to. */
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	}),
+	(
+	/** The linked sensor device whose state changed. */
+	{
+		name: "sourceDeviceId",
+		type: "INTEGER",
+		notNull: true
+	}),
+	(
+	/** Event kind id (matches an `EventKindDescriptor.kind`). */
+	{
+		name: "kind",
+		type: "TEXT",
+		notNull: true
+	}),
+	(
+	/** Snapshot of the sensor cap's runtime-state slice at the change. */
+	{
+		name: "value",
+		type: "JSON"
+	}),
+	{
+		name: "timestamp",
+		type: "INTEGER",
+		notNull: true
+	}
+];
+var SENSOR_EVENT_INDEXES = [{
+	name: "idx_sensor_events_device_ts",
+	columns: ["deviceId", "timestamp"]
+}];
+var DEFAULT_QUERY_LIMIT = 1e3;
+var SensorEventStore = class {
+	store;
+	logger;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+	}
+	/** One-time collection declaration. Call from addon onInitialize. */
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: SENSOR_EVENTS_COLLECTION,
+			columns: [...SENSOR_EVENT_COLUMNS],
+			indexes: [...SENSOR_EVENT_INDEXES]
+		});
+	}
+	/** Insert one attributed sensor event. Best-effort (telemetry-lossy). */
+	async insert(ev) {
+		try {
+			await this.store.insert.mutate({
+				collection: SENSOR_EVENTS_COLLECTION,
+				record: {
+					id: ev.id,
+					data: {
+						deviceId: ev.deviceId,
+						sourceDeviceId: ev.sourceDeviceId,
+						kind: ev.kind,
+						value: ev.value,
+						timestamp: ev.timestamp
+					}
+				}
+			});
+		} catch (err) {
+			this.logger.warn("SensorEventStore.insert failed", {
+				tags: { deviceId: ev.deviceId },
+				meta: {
+					eventId: ev.id,
+					error: String(err)
+				}
+			});
+		}
+	}
+	/** Per-camera sensor-event history, newest first. Mirrors the
+	*  motion/object/audio query semantics; `kinds` narrows via `whereIn`. */
+	async query(q) {
+		const filter = {
+			where: { deviceId: q.deviceId },
+			orderBy: {
+				field: "timestamp",
+				direction: "desc"
+			},
+			limit: q.limit ?? DEFAULT_QUERY_LIMIT
+		};
+		if (q.since !== void 0 || q.until !== void 0) filter["whereBetween"] = { timestamp: [q.since ?? 0, q.until ?? Date.now()] };
+		if (q.kinds !== void 0 && q.kinds.length > 0) filter["whereIn"] = { kind: [...q.kinds] };
+		return (await this.store.query.query({
+			collection: SENSOR_EVENTS_COLLECTION,
+			filter
+		})).map((r) => rowToSensorEvent(r.id, r.data));
+	}
+	/**
+	* Delete every row with `timestamp ≤ cutoffMs`, draining a page at a time
+	* (mirrors `EventStore.evictBefore`, including the infinite-loop guard).
+	* Returns the number of rows deleted. Rides the analytics retention sweep.
+	*/
+	async evictBefore(cutoffMs) {
+		let deleted = 0;
+		for (;;) {
+			const rows = await this.store.query.query({
+				collection: SENSOR_EVENTS_COLLECTION,
+				filter: {
+					whereBetween: { timestamp: [0, cutoffMs] },
+					limit: EVICT_PAGE_SIZE
+				}
+			});
+			if (rows.length === 0) break;
+			let deletedInPage = 0;
+			for (const row of rows) {
+				if (typeof row.id !== "string") continue;
+				try {
+					await this.store.delete.mutate({
+						collection: SENSOR_EVENTS_COLLECTION,
+						key: row.id
+					});
+					deleted++;
+					deletedInPage++;
+				} catch {}
+			}
+			if (deletedInPage === 0) break;
+		}
+		return deleted;
+	}
+};
+/** Page size for the eviction drain loop (mirrors EventStore.PRUNE_PAGE_SIZE). */
+var EVICT_PAGE_SIZE = 500;
+function rowToSensorEvent(id, data) {
+	const value = data["value"];
+	return {
+		id,
+		deviceId: Number(data["deviceId"]),
+		sourceDeviceId: Number(data["sourceDeviceId"]),
+		kind: String(data["kind"]),
+		value: isRecord(value) ? value : null,
+		timestamp: Number(data["timestamp"])
+	};
+}
+function isRecord(x) {
+	return x !== null && typeof x === "object" && !Array.isArray(x);
+}
+//#endregion
+//#region src/pipeline-analytics/services/event-kinds.ts
+/**
+* Extensible per-device event kinds (Part B).
+*
+* `composeEventKinds` builds the `listEventKinds` payload for a camera:
+*   (a) built-ins — motion + audio, always present;
+*   (b) detection classes actually OBSERVED on the device (track history);
+*   (c) sensor kinds contributed by LINKED devices (device-manager
+*       `getLinkedDevices`), one descriptor per bound sensor cap present in
+*       the static `EVENT_KIND_BY_CAP` map. Binding-driven per linked device
+*       (`getBindings`) — never a global cap enumeration (D12).
+*
+* `LinkedCamerasCache` is the ingest-side reverse index (sensor device →
+* linked camera ids) with a TTL, so the `DeviceStateChanged` handler stays
+* cheap at bus rate.
+*/
+var MOTION_COLOR = "#f59e0b";
+var AUDIO_COLOR = "#06b6d4";
+var PERSON_COLOR = "#22c55e";
+var VEHICLE_COLOR = "#3b82f6";
+var ANIMAL_COLOR = "#f97316";
+var GENERIC_DETECTION_COLOR = "#64748b";
+var VEHICLE_CLASSES = new Set([
+	"vehicle",
+	"car",
+	"truck",
+	"bus",
+	"motorcycle",
+	"bicycle",
+	"boat",
+	"train"
+]);
+var ANIMAL_CLASSES = new Set([
+	"animal",
+	"dog",
+	"cat",
+	"bird",
+	"horse",
+	"cow",
+	"sheep"
+]);
+function detectionIcon(className) {
+	if (className === "person") return "person";
+	if (VEHICLE_CLASSES.has(className)) return "vehicle";
+	if (ANIMAL_CLASSES.has(className)) return "animal";
+	return "generic";
+}
+function detectionColor(className) {
+	if (className === "person") return PERSON_COLOR;
+	if (VEHICLE_CLASSES.has(className)) return VEHICLE_COLOR;
+	if (ANIMAL_CLASSES.has(className)) return ANIMAL_COLOR;
+	return GENERIC_DETECTION_COLOR;
+}
+function titleCase(s) {
+	return s.length > 0 ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+/**
+* Full event-kind list for a camera. Sensor kinds are deduped per
+* (kind, source deviceId) — two linked contact sensors each contribute
+* their own entry, distinguishable by `source.deviceId`.
+*/
+async function composeEventKinds(deps, deviceId) {
+	const out = [{
+		kind: "motion",
+		label: "Motion",
+		color: MOTION_COLOR,
+		icon: "motion",
+		category: "motion",
+		source: {
+			capName: "pipeline-analytics",
+			deviceId
+		}
+	}, {
+		kind: "audio",
+		label: "Audio",
+		color: AUDIO_COLOR,
+		icon: "audio",
+		category: "audio",
+		source: {
+			capName: "pipeline-analytics",
+			deviceId
+		}
+	}];
+	try {
+		const classNames = await deps.observedClassNames(deviceId);
+		for (const className of [...classNames].sort()) out.push({
+			kind: className,
+			label: titleCase(className),
+			color: detectionColor(className),
+			icon: detectionIcon(className),
+			category: "detection",
+			source: {
+				capName: "pipeline-analytics",
+				deviceId
+			}
+		});
+	} catch (err) {
+		deps.onError?.("observedClassNames", err);
+	}
+	try {
+		const { devices } = await deps.linkedDevices.getLinkedDevices({ deviceId });
+		const seen = /* @__PURE__ */ new Set();
+		for (const linked of devices) {
+			let capNames;
+			try {
+				const { entries } = await deps.bindings.getBindings({ deviceId: linked.deviceId });
+				capNames = entries.map((e) => e.capName);
+			} catch (err) {
+				deps.onError?.("getBindings", err);
+				continue;
+			}
+			for (const capName of capNames) {
+				const descriptor = EVENT_KIND_BY_CAP[capName];
+				if (descriptor === void 0) continue;
+				const dedupeKey = `${descriptor.kind}:${linked.deviceId}`;
+				if (seen.has(dedupeKey)) continue;
+				seen.add(dedupeKey);
+				out.push({
+					kind: descriptor.kind,
+					label: descriptor.label,
+					color: descriptor.color,
+					icon: descriptor.icon,
+					category: descriptor.category,
+					source: {
+						capName,
+						deviceId: linked.deviceId
+					}
+				});
+			}
+		}
+	} catch (err) {
+		deps.onError?.("getLinkedDevices", err);
+	}
+	return out;
+}
+var DEFAULT_CACHE_TTL_MS = 6e4;
+/**
+* TTL-cached reverse index: source deviceId → camera ids it is linked to.
+* Rebuilds lazily (single-flight) when stale, so the `DeviceStateChanged`
+* handler pays one map lookup per event in the common case.
+*/
+var LinkedCamerasCache = class {
+	deps;
+	ttlMs;
+	index = /* @__PURE__ */ new Map();
+	/** Ms timestamp of the last build; null = never built / invalidated. */
+	builtAt = null;
+	building = null;
+	constructor(deps) {
+		this.deps = deps;
+		this.ttlMs = deps.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+	}
+	/** Camera ids linked to `sourceDeviceId` ([] when none). */
+	async camerasFor(sourceDeviceId, nowMs = Date.now()) {
+		if (this.builtAt === null || nowMs - this.builtAt >= this.ttlMs) {
+			this.building ??= this.rebuild(nowMs).finally(() => {
+				this.building = null;
+			});
+			await this.building;
+		}
+		return this.index.get(sourceDeviceId) ?? [];
+	}
+	/** Drop the cached index (e.g. on link-topology change events). */
+	invalidate() {
+		this.builtAt = null;
+	}
+	/** Test/maintenance hook: replace the index directly. */
+	seed(index, builtAt) {
+		this.index = new Map(index);
+		this.builtAt = builtAt;
+	}
+	async rebuild(nowMs) {
+		try {
+			const cameraIds = await this.deps.cameras.listCameraIds();
+			const next = /* @__PURE__ */ new Map();
+			for (const cameraId of cameraIds) try {
+				const { devices } = await this.deps.linkedDevices.getLinkedDevices({ deviceId: cameraId });
+				for (const d of devices) {
+					const list = next.get(d.deviceId);
+					if (list === void 0) next.set(d.deviceId, [cameraId]);
+					else if (!list.includes(cameraId)) list.push(cameraId);
+				}
+			} catch (err) {
+				this.deps.onError?.("getLinkedDevices", err);
+			}
+			this.index = next;
+			this.builtAt = nowMs;
+		} catch (err) {
+			this.deps.onError?.("listCameraIds", err);
+			this.builtAt = nowMs;
+		}
+	}
+};
+/**
+* One `DeviceStateChanged` → N history rows (one per linked camera). The
+* EVENT_KIND_BY_CAP gate exits first so non-sensor cap churn costs one map
+* lookup. Returns the number of rows inserted (0 when unmapped/unlinked).
+* Telemetry-lossy by design (D8) — inserts are best-effort.
+*/
+async function ingestSensorStateChange(deps, data, timestamp) {
+	const descriptor = EVENT_KIND_BY_CAP[data.capName];
+	if (descriptor === void 0) return 0;
+	const cameraIds = await deps.cache.camerasFor(data.deviceId);
+	if (cameraIds.length === 0) return 0;
+	const slice = data.slice;
+	const value = slice !== null && slice !== void 0 && typeof slice === "object" && !Array.isArray(slice) ? slice : null;
+	const makeId = deps.makeId ?? (() => `pa-sensor-${randomUUID()}`);
+	let inserted = 0;
+	for (const cameraId of cameraIds) {
+		await deps.sink.insert({
+			id: makeId(),
+			deviceId: cameraId,
+			sourceDeviceId: data.deviceId,
+			kind: descriptor.kind,
+			value,
+			timestamp
+		});
+		inserted++;
+	}
+	return inserted;
+}
+//#endregion
 //#region src/shared/frame/resolve-frame.ts
 /**
 * Resolve the pixels a `FrameHandle` refers to via the node-routed fetch.
@@ -4861,22 +5829,26 @@ var EventMediaDispatcher = class {
 		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);
+			const stored = await this.writeTrackSnapshot(deviceId, frameData, fw, fh, sn, input.cropPadding);
 			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).
+	* Periodic per-track media (§5). The boxed FULL frame is encoded once and
+	* shared by the appended `snapshot` (timeline filmstrip) and the rolling
+	* `lastFrame` (overwrite). The best `thumbnail` is DIFFERENT: a clean
+	* subject-centered crop (same output contract as the object-event `crop`
+	* kind) — it is the gallery/reel fallback for tracks that never produced an
+	* object event, and a full frame there shows the scene (e.g. a foreground
+	* parked car), not the track's subject. Returns the appended snapshot for
+	* TrackStore wiring (null when `appendSnapshot` is false or the encode
+	* failed).
 	*/
-	async writeTrackSnapshot(deviceId, frameData, fw, fh, sn) {
+	async writeTrackSnapshot(deviceId, frameData, fw, fh, sn, cropPadding) {
 		if (!sn.appendSnapshot && !sn.rollingLastFrame && !sn.bestThumbnail) return null;
-		let boxed;
-		try {
+		let boxed = null;
+		if (sn.appendSnapshot || sn.rollingLastFrame) try {
 			boxed = await drawBoxedFrame(frameData, fw, fh, [{
 				...sn.bbox,
 				...sn.label ? { label: sn.label } : {}
@@ -4890,10 +5862,9 @@ var EventMediaDispatcher = class {
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
-			return null;
 		}
 		let stored = null;
-		if (sn.appendSnapshot) try {
+		if (sn.appendSnapshot && boxed) try {
 			const mediaKey = await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "track",
@@ -4909,10 +5880,49 @@ var EventMediaDispatcher = class {
 				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);
+		if (sn.rollingLastFrame && boxed) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
+		if (sn.bestThumbnail) try {
+			const crop = await this.cropSubjectRegion(frameData, fw, fh, sn.bbox, cropPadding);
+			await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, crop);
+		} catch (err) {
+			this.deps.logger.warn("event media: track thumbnail crop failed", {
+				tags: { deviceId },
+				meta: {
+					deviceId,
+					trackId: sn.trackId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			if (boxed) await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, boxed);
+		}
 		return stored;
 	}
+	/**
+	* Clean subject-centered crop of `bbox` out of the raw frame — the shared
+	* output contract of the object-event `crop` kind and the track `thumbnail`:
+	* square-safe 16:9 region around the bbox, extracted from the ORIGINAL frame
+	* (no box drawn), resized to 640×360, JPEG q80.
+	*/
+	async cropSubjectRegion(frameData, fw, fh, bbox, cropPadding) {
+		const region = squareSafeCropRegion(bbox, {
+			W: fw,
+			H: fh
+		}, cropPadding);
+		const left = Math.max(0, Math.min(region.x, fw - 1));
+		const top = Math.max(0, Math.min(region.y, fh - 1));
+		const width = Math.max(1, Math.min(region.w, fw - left));
+		const height = Math.max(1, Math.min(region.h, fh - top));
+		return await sharp(frameData, { raw: {
+			width: fw,
+			height: fh,
+			channels: 3
+		} }).extract({
+			left,
+			top,
+			width,
+			height
+		}).resize(CROP_WIDTH, CROP_HEIGHT).jpeg({ quality: CROP_QUALITY }).toBuffer();
+	}
 	async replaceKind(deviceId, trackId, kind, timestamp, data) {
 		try {
 			await this.deps.mediaStore.putReplacing({
@@ -4940,24 +5950,7 @@ var EventMediaDispatcher = class {
 			label: caption(ev.className, ev.confidence, ev.label)
 		};
 		try {
-			const region = squareSafeCropRegion(ev.bbox, {
-				W: fw,
-				H: fh
-			}, cropPadding);
-			const left = Math.max(0, Math.min(region.x, fw - 1));
-			const top = Math.max(0, Math.min(region.y, fh - 1));
-			const width = Math.max(1, Math.min(region.w, fw - left));
-			const height = Math.max(1, Math.min(region.h, fh - top));
-			const crop = await sharp(frameData, { raw: {
-				width: fw,
-				height: fh,
-				channels: 3
-			} }).extract({
-				left,
-				top,
-				width,
-				height
-			}).resize(CROP_WIDTH, CROP_HEIGHT).jpeg({ quality: CROP_QUALITY }).toBuffer();
+			const crop = await this.cropSubjectRegion(frameData, fw, fh, ev.bbox, cropPadding);
 			await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "event",
@@ -9646,10 +10639,18 @@ var MOTION_EVENT_HEARTBEAT_MS = 5e3;
 * Stored media kinds that carry NO drawn bounding box, in fallback preference
 * order. The reel forces `?kind=crop`; when a track has no crop the endpoint may
 * degrade only to one of these CLEAN frames — never `fullFrameBoxed` /
-* `thumbnail` / `lastFrame` / `firstFrame` / `snapshot` (all server-boxed).
+* `lastFrame` / `firstFrame` / `snapshot` (all server-boxed).
+*
+* `thumbnail` joined the clean set on 2026-07-17: the track best-thumbnail is
+* now a subject-centered crop (event-media-dispatcher), and for DEGENERATE
+* tracks (no object event → no `crop`) it is the ONLY subject-centered media —
+* without it a crop-forced request degraded to the `keyFrame` FULL FRAME,
+* which is how 65% of the timeline tiles rendered as whole scenes. It sits
+* right after a real `crop`, before the full-scene `fullFrame`/`keyFrame`.
 */
 var CLEAN_MEDIA_KINDS = [
 	"crop",
+	"thumbnail",
 	"fullFrame",
 	"keyFrame"
 ];
@@ -9727,6 +10728,11 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	stationaryRegistry = null;
 	mediaStore = null;
 	eventStore = null;
+	/** Per-camera history of LINKED-device sensor state changes (Part B). */
+	sensorEventStore = null;
+	/** Ingest-side reverse index (sensor device → linked camera ids), TTL-cached
+	*  so the DeviceStateChanged handler stays cheap. */
+	linkedCamerasCache = null;
 	identityStore = null;
 	faceStore = null;
 	faceRecognizer = null;
@@ -9777,6 +10783,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	unsubNativeDetection = null;
 	unsubBindings = null;
 	unsubDeviceUnreg = null;
+	/** DeviceStateChanged subscription feeding the sensor-event history. */
+	unsubDeviceState = null;
 	ttlSweepTimer = null;
 	retentionSweepTimer = null;
 	/** Handle for the event-media data-plane listener (dispose on shutdown). */
@@ -9872,6 +10880,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		await TrackStore.declare(api.settingsStore);
 		await MediaStore.declare(api.settingsStore);
 		await EventStore.declare(api.settingsStore);
+		await SensorEventStore.declare(api.settingsStore);
 		await IdentityStore.declare(api.settingsStore);
 		await FaceStore.declare(api.settingsStore);
 		await PlateStore.declare(api.settingsStore);
@@ -9889,7 +10898,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		if (!storage) throw new Error("pipeline-analytics requires ctx.kernel.storage");
 		this.trackStore = new TrackStore({
 			store: api.settingsStore,
-			logger: logger.child("TrackStore")
+			logger: logger.child("TrackStore"),
+			frameDims: (deviceId) => this.lastFrameDimsByDevice.get(deviceId)
 		});
 		this.stationaryRegistry = new StationaryObjectRegistry({
 			store: api.settingsStore,
@@ -9925,6 +10935,20 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			logger: logger.child("EventStore"),
 			media: this.mediaStore
 		});
+		this.sensorEventStore = new SensorEventStore({
+			store: api.settingsStore,
+			logger: logger.child("SensorEventStore")
+		});
+		this.linkedCamerasCache = new LinkedCamerasCache({
+			cameras: { listCameraIds: async () => {
+				return (await api.deviceManager.listAll.query({})).filter((d) => d.isCamera).map((d) => d.id);
+			} },
+			linkedDevices: { getLinkedDevices: (input) => api.deviceManager.getLinkedDevices.query(input) },
+			onError: (scope, err) => logger.warn("linked-cameras cache refresh failed", { meta: {
+				scope,
+				error: errMsg(err)
+			} })
+		});
 		this.identityStore = new IdentityStore({
 			store: api.settingsStore,
 			logger: logger.child("IdentityStore")
@@ -10151,6 +11175,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				const data = ev.data;
 				this.handleNativeDetection(data);
 			});
+			this.unsubDeviceState = this.ctx.eventBus.subscribe({ category: EventCategory.DeviceStateChanged }, (ev) => {
+				const data = ev.data;
+				if (EVENT_KIND_BY_CAP[data.capName] === void 0) return;
+				const timestamp = ev.timestamp instanceof Date ? ev.timestamp.getTime() : Date.now();
+				this.handleSensorStateChanged(data, timestamp);
+			});
 			if (await this.embeddingEnabledState.get()) {
 				const encoderClient = {
 					encode: (crop, width, height) => this.ctx.api.embeddingEncoder.encode.query({
@@ -10516,6 +11546,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.unsubBindings = null;
 		this.unsubDeviceUnreg?.();
 		this.unsubDeviceUnreg = null;
+		this.unsubDeviceState?.();
+		this.unsubDeviceState = null;
 		await this.embeddingDispatcher?.stop();
 		this.embeddingDispatcher = null;
 		for (const id of this.proxies.keys()) this.releaseProxy(id);
@@ -10779,7 +11811,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				else dispatcher.onTrackStarted(deviceId, t.trackId, t.className, steps, detailFrame, result.timestamp);
 			}
 		}
-		if (newTrackCount > 0 || lostTrackCount > 0 || result.objectEvents.length > 0) {
+		if (newTrackCount > 0 || lostTrackCount > 0 || result.objectEvents.length > 0 || result.appearanceEvents.length > 0) {
 			const byState = {};
 			for (const t of result.tracked) byState[t.state] = (byState[t.state] ?? 0) + 1;
 			log.info("frame processed", { meta: {
@@ -10789,10 +11821,11 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				newTracks: newTrackCount,
 				lostTracks: lostTrackCount,
 				objectEvents: result.objectEvents.length,
+				appearanceEvents: result.appearanceEvents.length,
 				byState
 			} });
 		}
-		await Promise.all(result.objectEvents.map((e) => this.eventStore.insertObject(e)));
+		await Promise.all([...result.objectEvents, ...result.appearanceEvents].map((e) => this.eventStore.insertObject(e)));
 		const objectEmbeddingBests = [];
 		if (this.objectEmbeddingStore) for (const t of result.tracked) {
 			if (!isClipObjectEmbedding(t)) continue;
@@ -10810,8 +11843,9 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		const faceGloballyEnabled = this.faceRecognizer ? await this.resolveGlobalFaceEnabled() : false;
 		const mediaSettings = await this.resolveDeviceMediaSettings(deviceId);
 		if (this.eventMediaDispatcher && frameHandle) {
-			const childCropsByEvent = buildEventChildCrops(result.objectEvents, frame.detections);
-			const eventTargets = result.objectEvents.filter((e) => e.bbox !== void 0 && e.bbox.w > 0 && e.bbox.h > 0).map((e) => {
+			const mediaEvents = [...result.objectEvents, ...result.appearanceEvents];
+			const childCropsByEvent = buildEventChildCrops(mediaEvents, frame.detections);
+			const eventTargets = mediaEvents.filter((e) => e.bbox !== void 0 && e.bbox.w > 0 && e.bbox.h > 0).map((e) => {
 				const childCrops = childCropsByEvent.get(e.id);
 				return {
 					eventId: e.id,
@@ -11365,7 +12399,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				movementThreshold: media.snapshotMovementThreshold,
 				maxIdleMs: media.snapshotMaxIdleMs
 			}).capture;
-			const isNewBest = this.bestFrameTracker.observe(t.trackId, t.confidence, timestamp);
+			const edgeClear = isEdgeClear({
+				bbox: t.bbox,
+				frameWidth,
+				frameHeight
+			});
+			const isNewBest = this.bestFrameTracker.observe(t.trackId, t.confidence, timestamp, edgeClear);
 			this.maybeEmitTrackLifecycleUpdate(deviceId, t, timestamp, isNewBest);
 			const plan = planPeriodicMedia({
 				saveThumbnails: media.saveThumbnails,
@@ -11778,6 +12817,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				} });
 			}
 			await this.mediaStore.evictBefore(now - 31 * day);
+			if (this.sensorEventStore) try {
+				const sensorDeleted = await this.sensorEventStore.evictBefore(objectCutoffMs);
+				if (sensorDeleted > 0) this.ctx.logger.info("sensor-event retention prune", { meta: {
+					deleted: sensorDeleted,
+					cutoffMs: objectCutoffMs
+				} });
+			} catch (err) {
+				this.ctx.logger.debug("sensor-event prune failed", { meta: { error: String(err) } });
+			}
 			if (this.faceStore) try {
 				const faceCutoffMs = now - FACE_DEFAULTS.bufferRetentionDays * day;
 				const deletedFaceIds = await this.faceStore.pruneAll({
@@ -12083,6 +13131,68 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	async listTracks(input) {
 		return this.trackStore?.queryHistorical(input) ?? [];
 	}
+	/**
+	* Batched cluster-wide track listing — one merged (`lastSeen` DESC,
+	* `trackId` DESC) page across the requested devices with a stable opaque
+	* cursor. Replaces the per-camera `listTracks` fan-out for the events page
+	* first paint + the reel. See `TrackStore.queryRecent` for the per-device
+	* indexed page + k-way merge and the cursor encoding.
+	*/
+	async listRecentTracks(input) {
+		return this.trackStore?.queryRecent(input) ?? {
+			tracks: [],
+			nextCursor: null
+		};
+	}
+	/**
+	* Every event kind the device can produce: built-ins (motion + audio),
+	* detection classes actually observed on the device, and sensor kinds
+	* from LINKED devices (device-manager `getLinkedDevices`, binding-driven
+	* per linked device). Degrades to the built-ins on error.
+	*/
+	async listEventKinds(input) {
+		const api = this.ctx.api;
+		return composeEventKinds({
+			linkedDevices: { getLinkedDevices: (i) => api.deviceManager.getLinkedDevices.query(i) },
+			bindings: { getBindings: (i) => api.deviceManager.getBindings.query(i) },
+			observedClassNames: async (deviceId) => this.trackStore?.observedClassNames(deviceId) ?? [],
+			onError: (scope, err) => this.ctx.logger.warn("listEventKinds: partial compose", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					scope,
+					error: errMsg(err)
+				}
+			})
+		}, input.deviceId);
+	}
+	/** Per-camera sensor-event history (state changes of linked devices). */
+	async getSensorEvents(input) {
+		return this.sensorEventStore?.query(input) ?? [];
+	}
+	/**
+	* Sensor-event ingest handler — `DeviceStateChanged` of a device exposing a
+	* mapped sensor cap. Resolves the linked-camera set through the TTL cache
+	* and inserts ONE row per linked camera. Best-effort (telemetry-lossy).
+	*/
+	async handleSensorStateChanged(data, timestamp) {
+		const store = this.sensorEventStore;
+		const cache = this.linkedCamerasCache;
+		if (store === null || cache === null) return;
+		try {
+			await ingestSensorStateChange({
+				sink: store,
+				cache
+			}, data, timestamp);
+		} catch (err) {
+			this.ctx.logger.warn("sensor-event ingest failed", {
+				tags: { deviceId: data.deviceId },
+				meta: {
+					capName: data.capName,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
 	async clearTracks(input) {
 		this.trackStore?.clearDevice(input.deviceId);
 		this.stationaryRegistry?.clearDevice(input.deviceId);