@camstack/addon-post-analysis 1.1.30 → 1.1.31

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-D1cY_vlY.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++) {
@@ -1594,7 +1594,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 +1613,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++;
@@ -2738,7 +2738,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 +2955,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 +3216,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 +3295,7 @@ var TrackStore = class {
 	config;
 	logger;
 	store;
+	frameDims;
 	constructor(deps) {
 		this.logger = deps.logger;
 		this.store = deps.store;
@@ -3093,6 +3303,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 +3650,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: {
-				...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: params.limit ?? 50
+				limit
+			}
+		});
+		const nullEnvQuery = 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));
+		});
+		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);
+				}
+			}
+			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 +3858,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 +3878,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 +3909,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 +3936,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 } : {}
 		};
 	}
 };
@@ -4628,6 +5048,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 +5659,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 +5692,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 +5710,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 +5780,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",
@@ -9727,6 +10550,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 +10605,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 +10702,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 +10720,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 +10757,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 +10997,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 +11368,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);
@@ -11778,6 +12632,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 +12946,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);