@camstack/addon-post-analysis 1.1.31 → 1.1.33

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-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 { C as string, S as object, _ as createEvent, a as cosineSimilarity, b as boolean, 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, w as EventCategory, x as number, y as array } from "../dist-CA0GikiM.mjs";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 //#region src/pipeline-analytics/videoclips-provider.ts
@@ -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
@@ -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
 		});
 	}
@@ -4707,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({
@@ -4718,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") {
@@ -4728,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
 		};
 	}
 	/**
@@ -5226,6 +5396,7 @@ var PERSON_COLOR = "#22c55e";
 var VEHICLE_COLOR = "#3b82f6";
 var ANIMAL_COLOR = "#f97316";
 var GENERIC_DETECTION_COLOR = "#64748b";
+var PACKAGE_COLOR = "#a855f7";
 var VEHICLE_CLASSES = new Set([
 	"vehicle",
 	"car",
@@ -5303,6 +5474,34 @@ async function composeEventKinds(deps, deviceId) {
 	} catch (err) {
 		deps.onError?.("observedClassNames", err);
 	}
+	try {
+		if (deps.packageZonesEnabled && await deps.packageZonesEnabled(deviceId)) {
+			out.push({
+				kind: "package-delivered",
+				label: "Package delivered",
+				color: PACKAGE_COLOR,
+				icon: "package",
+				category: "package",
+				source: {
+					capName: "pipeline-analytics",
+					deviceId
+				}
+			});
+			out.push({
+				kind: "package-picked-up",
+				label: "Package picked up",
+				color: PACKAGE_COLOR,
+				icon: "package",
+				category: "package",
+				source: {
+					capName: "pipeline-analytics",
+					deviceId
+				}
+			});
+		}
+	} catch (err) {
+		deps.onError?.("packageZonesEnabled", err);
+	}
 	try {
 		const { devices } = await deps.linkedDevices.getLinkedDevices({ deviceId });
 		const seen = /* @__PURE__ */ new Set();
@@ -7155,6 +7354,208 @@ function resolveMediaSettings(raw) {
 		snapshotMaxIdleMs: pick("snapshotMaxIdleMs")
 	};
 }
+//#endregion
+//#region src/pipeline-analytics/package-settings.ts
+/**
+* Per-device package-drop detector settings (surface C of the
+* detection-config-exposure plan — a per-device post-analysis section).
+* Cascade: a per-device override on top of the declared default, resolved
+* per field (an invalid/missing value falls back to its default — parse
+* never throws). Mirrors `media-settings` / `tracking-settings`.
+*
+* Keys are namespaced (`packageDrop*`) because the device store is a FLAT
+* blob shared across every post-analysis section — a bare `enabled` would
+* collide with another section.
+*
+* See docs/superpowers/specs/2026-07-17-package-zones-design.md §3.3 +
+* docs/superpowers/specs/2026-07-17-detection-config-exposure-design.md
+* (surface C). Dwell default is 15s per operator decision (the design's
+* §3.3 draft said 45s).
+*/
+var PackageDropSettingsSchema = object({
+	/** Master switch — off by default; opt-in per camera (porch/door cams). */
+	packageDropEnabled: boolean().default(false),
+	/**
+	* Minimum OBSERVED dwell (seconds, since first-seen) before a newly
+	* promoted stationary package counts as a delivery. Kills a bag briefly
+	* set down and snatched back. Operator default 15s. Values beyond the
+	* stationary promotion window (30s) are satisfied only once the entry
+	* has actually been observed that long.
+	*/
+	packageDropDwellSec: number().int().min(0).max(3600).default(15),
+	/** Reject tiny far-field blobs: min bbox area as a fraction of the frame. */
+	packageDropMinBboxAreaFrac: number().min(0).max(1).default(.004),
+	/** Emit `package-picked-up` when a delivered package's entry departs. */
+	packageDropPickupEnabled: boolean().default(true),
+	/**
+	* Stationary classes that count as a package. MODEL-AGNOSTIC: defaults to
+	* the single `package` class a dedicated parcel model emits; the interim
+	* COCO vector (suitcase/backpack/handbag) already maps to `package`
+	* upstream, so this stays `['package']`.
+	*/
+	packageDropClassFilter: array(string()).default(["package"])
+});
+var PACKAGE_DROP_DEFAULTS = PackageDropSettingsSchema.parse({});
+/**
+* Resolve a per-device store blob into typed package-drop settings.
+* Unknown/invalid fields fall back to the default for that field (never
+* throws on a bad blob).
+*/
+function resolvePackageDropSettings(raw) {
+	const pick = (key) => {
+		const parsed = PackageDropSettingsSchema.shape[key].safeParse(raw[key]);
+		return parsed.success ? parsed.data : PACKAGE_DROP_DEFAULTS[key];
+	};
+	return {
+		packageDropEnabled: pick("packageDropEnabled"),
+		packageDropDwellSec: pick("packageDropDwellSec"),
+		packageDropMinBboxAreaFrac: pick("packageDropMinBboxAreaFrac"),
+		packageDropPickupEnabled: pick("packageDropPickupEnabled"),
+		packageDropClassFilter: pick("packageDropClassFilter")
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/package-drop-detector.ts
+/** The class every durable package event carries. */
+var PACKAGE_EVENT_CLASS = "package";
+/** Fixed high importance — package delivery is inherently high-signal (§6). */
+var PACKAGE_IMPORTANCE = 1;
+/** Object-event `state` used for a delivery (a parked package) / a pick-up
+*  (its departure). Both are valid `TrackState` enum members so the events
+*  stay `getObjectEvents`-output-valid. */
+var DELIVERED_STATE = "idle";
+var PICKED_UP_STATE = "left";
+/** Deterministic durable-event ids keyed on the stationary entry id. */
+function deliveredEventId(entryId) {
+	return `pa-pkg-${entryId}-delivered`;
+}
+function pickedUpEventId(entryId) {
+	return `pa-pkg-${entryId}-pickedup`;
+}
+var PackageDropDetector = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Single entrypoint — bridge the registry's `onChange` here. Never
+	*  throws (telemetry-lossy, D8): a failure only misses one package event. */
+	async onStationaryChange(change) {
+		try {
+			if (change.phase === "appeared") await this.onAppeared(change.entry, change.timestamp);
+			else await this.onDeparted(change.entry, change.timestamp);
+		} catch (err) {
+			this.deps.onError?.("onStationaryChange", err);
+			this.deps.logger.warn("package-drop detector failed on change", {
+				tags: { deviceId: change.entry.deviceId },
+				meta: {
+					phase: change.phase,
+					entryId: change.entry.id,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+		}
+	}
+	async onAppeared(entry, timestamp) {
+		const settings = await this.deps.resolveSettings(entry.deviceId);
+		if (!settings.packageDropEnabled) return;
+		if (!settings.packageDropClassFilter.includes(entry.className)) return;
+		const rules = (await this.deps.resolvePackageRules(entry.deviceId)).filter((r) => r.enabled !== false);
+		if (rules.length === 0) return;
+		const ruleZoneIds = new Set(rules.flatMap((r) => r.zoneIds));
+		const hitZones = computeStationaryEntryZones(entry, await this.deps.resolveZones(entry.deviceId)).filter((z) => ruleZoneIds.has(z));
+		if (hitZones.length === 0) return;
+		if (timestamp - entry.firstSeenAt < settings.packageDropDwellSec * 1e3) return;
+		const frameArea = entry.frameWidth * entry.frameHeight;
+		if (frameArea <= 0) return;
+		if (entry.bbox.w * entry.bbox.h / frameArea < settings.packageDropMinBboxAreaFrac) return;
+		const eventId = deliveredEventId(entry.id);
+		if ((await this.deps.events.queryObject({
+			deviceId: entry.deviceId,
+			classFilter: "package"
+		})).some((e) => e.id === eventId)) return;
+		const ev = {
+			id: eventId,
+			kind: "object",
+			deviceId: entry.deviceId,
+			timestamp,
+			source: "pipeline",
+			trackId: entry.sourceTrackId ?? entry.id,
+			className: PACKAGE_EVENT_CLASS,
+			...entry.label !== void 0 ? { label: entry.label } : {},
+			confidence: PACKAGE_IMPORTANCE,
+			bbox: {
+				x: entry.bbox.x,
+				y: entry.bbox.y,
+				w: entry.bbox.w,
+				h: entry.bbox.h
+			},
+			zones: hitZones,
+			state: DELIVERED_STATE,
+			frameWidth: entry.frameWidth,
+			frameHeight: entry.frameHeight,
+			...entry.keyFrameMediaKey !== void 0 ? { mediaKey: entry.keyFrameMediaKey } : {},
+			importance: PACKAGE_IMPORTANCE
+		};
+		await this.deps.events.insertObject(ev);
+		this.deps.emit.delivered({
+			deviceId: entry.deviceId,
+			entryId: entry.id,
+			eventId,
+			className: entry.className,
+			zoneIds: hitZones,
+			...entry.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: entry.keyFrameMediaKey } : {},
+			bbox: {
+				x: entry.bbox.x,
+				y: entry.bbox.y,
+				w: entry.bbox.w,
+				h: entry.bbox.h
+			},
+			timestamp
+		});
+	}
+	async onDeparted(entry, timestamp) {
+		if (!(await this.deps.resolveSettings(entry.deviceId)).packageDropPickupEnabled) return;
+		const deliveredId = deliveredEventId(entry.id);
+		const pickedUpId = pickedUpEventId(entry.id);
+		const rows = await this.deps.events.queryObject({
+			deviceId: entry.deviceId,
+			classFilter: PACKAGE_EVENT_CLASS
+		});
+		const delivered = rows.find((e) => e.id === deliveredId);
+		if (delivered === void 0) return;
+		if (rows.some((e) => e.id === pickedUpId)) return;
+		const ev = {
+			id: pickedUpId,
+			kind: "object",
+			deviceId: entry.deviceId,
+			timestamp,
+			source: "pipeline",
+			trackId: entry.sourceTrackId ?? entry.id,
+			className: PACKAGE_EVENT_CLASS,
+			...entry.label !== void 0 ? { label: entry.label } : {},
+			confidence: PACKAGE_IMPORTANCE,
+			bbox: {
+				x: entry.bbox.x,
+				y: entry.bbox.y,
+				w: entry.bbox.w,
+				h: entry.bbox.h
+			},
+			...delivered.zones !== void 0 ? { zones: delivered.zones } : {},
+			state: PICKED_UP_STATE,
+			frameWidth: entry.frameWidth,
+			frameHeight: entry.frameHeight,
+			importance: PACKAGE_IMPORTANCE
+		};
+		await this.deps.events.insertObject(ev);
+		this.deps.emit.pickedUp({
+			deviceId: entry.deviceId,
+			entryId: entry.id,
+			deliveredEventId: deliveredId,
+			className: entry.className,
+			timestamp
+		});
+	}
+};
 function centroidOf(b) {
 	return {
 		x: b.x + b.w / 2,
@@ -10469,10 +10870,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"
 ];
@@ -10627,6 +11036,9 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	/** GLOBAL face-recognition master switch (addon store), TTL-cached. */
 	faceGlobalEnabledCache = null;
 	mediaCacheByDevice = /* @__PURE__ */ new Map();
+	packageDropCacheByDevice = /* @__PURE__ */ new Map();
+	/** Turns stationary appear/depart into package-delivered/picked-up events. */
+	packageDropDetector = null;
 	/** Consecutive detector-dropout frames skipped per (deviceId, source) key. */
 	dropoutSkipsByKey = /* @__PURE__ */ new Map();
 	/** Best (highest-confidence) frame per track — drives the single overwrite
@@ -10744,6 +11156,11 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						timestamp
 					}
 				});
+				this.packageDropDetector?.onStationaryChange({
+					phase,
+					entry,
+					timestamp
+				});
 			}
 		});
 		await this.stationaryRegistry.load();
@@ -10752,15 +11169,55 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			store: api.settingsStore,
 			logger: logger.child("MediaStore")
 		});
-		this.eventStore = new EventStore({
+		const eventStore = new EventStore({
 			store: api.settingsStore,
 			logger: logger.child("EventStore"),
 			media: this.mediaStore
 		});
+		this.eventStore = eventStore;
 		this.sensorEventStore = new SensorEventStore({
 			store: api.settingsStore,
 			logger: logger.child("SensorEventStore")
 		});
+		this.packageDropDetector = new PackageDropDetector({
+			events: eventStore,
+			emit: {
+				delivered: (payload) => {
+					this.ctx.eventBus.emit({
+						id: `pa-package-delivered-${payload.entryId}`,
+						timestamp: new Date(payload.timestamp),
+						source: {
+							type: "addon",
+							id: "pipeline-analytics",
+							addonId: "pipeline-analytics"
+						},
+						category: EventCategory.PipelineAnalyticsPackageDelivered,
+						data: { ...payload }
+					});
+				},
+				pickedUp: (payload) => {
+					this.ctx.eventBus.emit({
+						id: `pa-package-pickedup-${payload.entryId}`,
+						timestamp: new Date(payload.timestamp),
+						source: {
+							type: "addon",
+							id: "pipeline-analytics",
+							addonId: "pipeline-analytics"
+						},
+						category: EventCategory.PipelineAnalyticsPackagePickedUp,
+						data: { ...payload }
+					});
+				}
+			},
+			logger: logger.child("PackageDropDetector"),
+			resolveZones: (deviceId) => this.resolveDeviceZones(deviceId),
+			resolvePackageRules: (deviceId) => this.resolveDevicePackageRules(deviceId),
+			resolveSettings: (deviceId) => this.resolveDevicePackageDropSettings(deviceId),
+			onError: (scope, err) => logger.warn("package-drop detector error", { meta: {
+				scope,
+				error: errMsg(err)
+			} })
+		});
 		this.linkedCamerasCache = new LinkedCamerasCache({
 			cameras: { listCameraIds: async () => {
 				return (await api.deviceManager.listAll.query({})).filter((d) => d.isCamera).map((d) => d.id);
@@ -11040,6 +11497,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				this.trackingCacheByDevice.delete(data.deviceId);
 				this.faceCacheByDevice.delete(data.deviceId);
 				this.mediaCacheByDevice.delete(data.deviceId);
+				this.packageDropCacheByDevice.delete(data.deviceId);
 			}
 		});
 		this.unsubDeviceUnreg = this.ctx.eventBus.subscribe({ category: EventCategory.DeviceUnregistered }, (ev) => {
@@ -11055,6 +11513,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			this.trackingCacheByDevice.delete(deviceId);
 			this.faceCacheByDevice.delete(deviceId);
 			this.mediaCacheByDevice.delete(deviceId);
+			this.packageDropCacheByDevice.delete(deviceId);
 			this.bindingCache?.invalidate(deviceId);
 			this.zoneAnalytics?.forgetDevice(deviceId);
 			this.audioMetrics?.forgetDevice(deviceId);
@@ -11402,6 +11861,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.faceCacheByDevice.clear();
 		this.faceGlobalEnabledCache = null;
 		this.mediaCacheByDevice.clear();
+		this.packageDropCacheByDevice.clear();
 		this.trackStore?.clearAll();
 		this.stationaryRegistry = null;
 		this.bindingCache?.clearAll();
@@ -11633,7 +12093,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: {
@@ -11643,10 +12103,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;
@@ -11664,8 +12125,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,
@@ -11875,6 +12337,32 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		});
 		return settings;
 	}
+	async resolveDevicePackageDropSettings(deviceId) {
+		const now = Date.now();
+		const cached = this.packageDropCacheByDevice.get(deviceId);
+		if (cached && now < cached.expiresAt) return cached.settings;
+		const settings = resolvePackageDropSettings(await this.ctx?.settings?.readDeviceStore(deviceId) ?? {});
+		this.packageDropCacheByDevice.set(deviceId, {
+			settings,
+			expiresAt: now + SETTINGS_CACHE_TTL_MS
+		});
+		return settings;
+	}
+	/**
+	* Resolve a device's ENABLED `package`-stage zone rules independent of the
+	* live frame path (mirrors `resolveDeviceZones`). Warms the proxy and,
+	* when the cached slice is empty, forces one refresh. The `package` slice
+	* is written by the orchestrator's package-stage provider (a later slice);
+	* until then this returns `[]` and no package events fire.
+	*/
+	async resolveDevicePackageRules(deviceId) {
+		const proxy = await this.ensureProxy(deviceId);
+		if (!proxy) return [];
+		const cached = proxy.state.zoneRules.value?.package;
+		if (cached && cached.length > 0) return cached;
+		await proxy.state.zoneRules.refresh().catch(() => void 0);
+		return proxy.state.zoneRules.value?.package ?? [];
+	}
 	/**
 	* Route one track's `runDetailSubtree` results (two-plane detail dispatch)
 	* into the EXISTING per-track consumers, discriminated by payload SHAPE:
@@ -12219,7 +12707,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,
@@ -12971,6 +13464,9 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			linkedDevices: { getLinkedDevices: (i) => api.deviceManager.getLinkedDevices.query(i) },
 			bindings: { getBindings: (i) => api.deviceManager.getBindings.query(i) },
 			observedClassNames: async (deviceId) => this.trackStore?.observedClassNames(deviceId) ?? [],
+			packageZonesEnabled: async (deviceId) => {
+				return (await this.resolveDevicePackageRules(deviceId)).some((r) => r.enabled !== false);
+			},
 			onError: (scope, err) => this.ctx.logger.warn("listEventKinds: partial compose", {
 				tags: { deviceId: input.deviceId },
 				meta: {
@@ -13634,6 +14130,51 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					}
 				]
 			},
+			{
+				id: "package-drop",
+				title: "Package detection",
+				description: "Detect a delivered package (a package-class object left parked inside a package zone) and, symmetrically, its pick-up. Draw the package zone in the zone editor; enable the package class in the object-detection step. Per-device override.",
+				columns: 2,
+				fields: [
+					{
+						type: "boolean",
+						key: "packageDropEnabled",
+						label: "Enable package detection",
+						description: "Turn package delivered / picked-up detection on for this camera (off elsewhere).",
+						default: PACKAGE_DROP_DEFAULTS.packageDropEnabled
+					},
+					{
+						type: "boolean",
+						key: "packageDropPickupEnabled",
+						label: "Emit pick-up",
+						description: "Also emit a package-picked-up event when the delivered package leaves.",
+						default: PACKAGE_DROP_DEFAULTS.packageDropPickupEnabled
+					},
+					{
+						type: "slider",
+						key: "packageDropDwellSec",
+						label: "Minimum dwell",
+						description: "How long a package must stay parked before it counts as a delivery. Higher = fewer false positives from bags briefly set down.",
+						min: 0,
+						max: 300,
+						step: 5,
+						default: PACKAGE_DROP_DEFAULTS.packageDropDwellSec,
+						showValue: true,
+						unit: "s"
+					},
+					{
+						type: "slider",
+						key: "packageDropMinBboxAreaFrac",
+						label: "Minimum package size",
+						description: "Reject tiny far-field blobs: the package box must cover at least this fraction of the frame.",
+						min: 0,
+						max: .1,
+						step: .001,
+						default: PACKAGE_DROP_DEFAULTS.packageDropMinBboxAreaFrac,
+						showValue: true
+					}
+				]
+			},
 			{
 				id: "audio-detection",
 				title: "Audio detection",