@camstack/ui-library 1.2.348 → 1.2.349

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.349] - 2026-10-29
+
+### Changed
+
+- Live detection boxes ignore out-of-order frames and fade by frame age
+- Live detection boxes come straight from the detector; faces, plates and names attach as they arrive
+
 ## [1.2.348] - 2026-10-29
 
 ### Added

package/dist/hooks/merge-detections.d.ts

@@ -0,0 +1,16 @@
+/**
+* Merge of the two live overlay sources into the one flat list the overlay
+* renders. Root boxes ALWAYS come from the raw detector frame; the enriched
+* (post-analysis) frame contributes only EXTRAS — detail children (face,
+* plate…) and identity labels — attached to the matching raw root.
+*/
+import type { ObjectDetection } from "@camstack/types";
+/** Minimum IoU between an enriched root and a raw root to call them one subject
+*  when no trackId pairs them. */
+export declare const EXTRA_MATCH_IOU_THRESHOLD = .3;
+export interface FramePart {
+	readonly detections: readonly ObjectDetection[];
+	readonly frameWidth: number;
+	readonly frameHeight: number;
+}
+export declare function mergeDetections(raw: FramePart | null, extras: FramePart | null): FramePart | null;

package/dist/index.cjs

@@ -71030,6 +71030,90 @@ function useDeviceCapSlice(trpc, deviceId, capName) {
 	return useDeviceStateSlice(handleRef.current);
 }
 //#endregion
+//#region src/hooks/merge-detections.ts
+/** Minimum IoU between an enriched root and a raw root to call them one subject
+*  when no trackId pairs them. */
+var EXTRA_MATCH_IOU_THRESHOLD = .3;
+function iou(a, b) {
+	const x1 = Math.max(a.x, b.x);
+	const y1 = Math.max(a.y, b.y);
+	const x2 = Math.min(a.x + a.width, b.x + b.width);
+	const y2 = Math.min(a.y + a.height, b.y + b.height);
+	const inter = Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
+	const union = a.width * a.height + b.width * b.height - inter;
+	return union > 0 ? inter / union : 0;
+}
+function isRoot(d) {
+	return d.kind !== "detail";
+}
+function scaleBox(b, sx, sy) {
+	return {
+		x: b.x * sx,
+		y: b.y * sy,
+		width: b.width * sx,
+		height: b.height * sy
+	};
+}
+/** The raw root an enriched root describes: same trackId, else best IoU. */
+function matchRawRoot(enrichedRoot, rawRoots, sx, sy) {
+	const trackId = enrichedRoot.track?.trackId;
+	if (trackId !== void 0) {
+		const byTrack = rawRoots.find((r) => r.track?.trackId === trackId);
+		if (byTrack) return byTrack;
+	}
+	const scaled = scaleBox(enrichedRoot.bbox, sx, sy);
+	let best = null;
+	let bestIou = EXTRA_MATCH_IOU_THRESHOLD;
+	for (const r of rawRoots) {
+		const v = iou(scaled, r.bbox);
+		if (v >= bestIou) {
+			best = r;
+			bestIou = v;
+		}
+	}
+	return best;
+}
+function mergeDetections(raw, extras) {
+	if (!extras) return raw;
+	const frameWidth = raw?.frameWidth ?? extras.frameWidth;
+	const frameHeight = raw?.frameHeight ?? extras.frameHeight;
+	const sx = extras.frameWidth > 0 ? frameWidth / extras.frameWidth : 1;
+	const sy = extras.frameHeight > 0 ? frameHeight / extras.frameHeight : 1;
+	const rawDets = raw?.detections ?? [];
+	const rawRoots = rawDets.filter(isRoot);
+	const rawRootFor = /* @__PURE__ */ new Map();
+	const extraLabels = /* @__PURE__ */ new Map();
+	for (const root of extras.detections.filter(isRoot)) {
+		const match = matchRawRoot(root, rawRoots, sx, sy);
+		rawRootFor.set(root.id, match);
+		if (match && root.labels.length > 0) extraLabels.set(match, [...extraLabels.get(match) ?? [], ...root.labels]);
+	}
+	const out = rawDets.map((d) => {
+		const add = extraLabels.get(d);
+		if (!add) return d;
+		const have = new Set(d.labels.map((l) => l.label));
+		const fresh = add.filter((l) => !have.has(l.label));
+		return fresh.length > 0 ? {
+			...d,
+			labels: [...d.labels, ...fresh]
+		} : d;
+	});
+	for (const d of extras.detections) {
+		if (isRoot(d)) continue;
+		const parent = d.parentId !== void 0 ? rawRootFor.get(d.parentId) : void 0;
+		out.push({
+			...d,
+			bbox: scaleBox(d.bbox, sx, sy),
+			...parent ? { parentId: parent.id } : {}
+		});
+	}
+	return {
+		detections: out,
+		frameWidth,
+		frameHeight
+	};
+}
+//#endregion
 //#region src/hooks/use-device-detections.ts
 /**
 * useDeviceDetections — subscribes to motion, raw motion, and detection events for a device.
@@ -71038,12 +71122,18 @@ function useDeviceCapSlice(trpc, deviceId, capName) {
 * admin-ui (BackendClient.trpc) and addon pages (AddonPageProps.trpc).
 */
 var MOTION_FADE_MS = 500;
-/** Detection overlay fade — ALSO the raw-fallback suppression window: while an
-*  enriched frame-tracked event arrived within this window, raw detection.result
-*  frames are ignored (post-analysis is the richer source; raw remains the
-*  fallback when post-analysis is absent). Keeping the two equal means raw
-*  resumes exactly when the enriched display fades — no blank gap. */
+/** Fade of each detection source (raw roots, enriched extras), counted from the
+*  frame's capture time so a late frame is not kept for the full window. */
 var DETECTION_FADE_MS = 800;
+/** A frame older than this at arrival is replayed pre-roll and never drawn.
+*  Same meaning as the server's OVERLAY_MAX_FRAME_AGE_MS. */
+var OVERLAY_MAX_FRAME_AGE_MS = 1e3;
+/**
+* The most of a frame's age (arrival minus its capture timestamp) the fade
+* deducts. Bounded so a skewed server/browser clock can never make boxes vanish
+* on arrival.
+*/
+var MAX_FRAME_AGE_FADE_DEDUCTION_MS = DETECTION_FADE_MS / 2;
 /** Helper: subscribe to live.onEvent without optional chaining on subscribe() */
 function safeSubscribe(trpc, category, onData) {
 	try {
@@ -71066,8 +71156,26 @@ function useDeviceDetections(trpc, deviceId) {
 	const [phase, setPhase] = (0, react$1.useState)("watching");
 	const motionTimer = (0, react$1.useRef)(void 0);
 	const motionRawTimer = (0, react$1.useRef)(void 0);
-	const detectionTimer = (0, react$1.useRef)(void 0);
-	const lastEnrichedAt = (0, react$1.useRef)(0);
+	const rawTimer = (0, react$1.useRef)(void 0);
+	const extrasTimer = (0, react$1.useRef)(void 0);
+	/** Live part of each source: raw roots and enriched extras fade independently. */
+	const rawPart = (0, react$1.useRef)(null);
+	const extrasPart = (0, react$1.useRef)(null);
+	/** Capture timestamp of the newest frame shown, per source; older arrivals are dropped. */
+	const lastRawTs = (0, react$1.useRef)(0);
+	const lastExtrasTs = (0, react$1.useRef)(0);
+	const publish = (0, react$1.useCallback)(() => {
+		setDetection(mergeDetections(rawPart.current, extrasPart.current));
+	}, []);
+	/** Admit a frame: null = rejected (stale or out of order), else its fade in ms. */
+	const admit = (0, react$1.useCallback)((frameTs, lastTs) => {
+		if (frameTs !== null) {
+			if (Date.now() - frameTs > OVERLAY_MAX_FRAME_AGE_MS) return null;
+			if (frameTs < lastTs.current) return null;
+			lastTs.current = frameTs;
+		}
+		return DETECTION_FADE_MS - (frameTs === null ? 0 : Math.min(Math.max(Date.now() - frameTs, 0), MAX_FRAME_AGE_FADE_DEDUCTION_MS));
+	}, []);
 	(0, react$1.useEffect)(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.motion-analysis", (event) => {
@@ -71116,48 +71224,72 @@ function useDeviceDetections(trpc, deviceId) {
 		};
 	}, [trpc, deviceId]);
 	(0, react$1.useEffect)(() => {
-		lastEnrichedAt.current = 0;
+		extrasPart.current = null;
+		rawPart.current = null;
+		lastExtrasTs.current = 0;
+		lastRawTs.current = 0;
+		setDetection(null);
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "pipeline-analytics.frame-tracked", (event) => {
 			const data = event?.data;
 			if (!data || data.deviceId !== deviceId) return;
 			if (!data.detections?.length) return;
 			if (typeof data.detections[0]?.kind !== "string") return;
-			lastEnrichedAt.current = Date.now();
-			setDetection({
+			const fadeInMs = admit(typeof data.timestamp === "number" ? data.timestamp : null, lastExtrasTs);
+			if (fadeInMs === null) return;
+			extrasPart.current = {
 				detections: data.detections,
 				frameWidth: data.frameWidth,
 				frameHeight: data.frameHeight
-			});
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
-			detectionTimer.current = setTimeout(() => setDetection(null), DETECTION_FADE_MS);
+			};
+			publish();
+			if (extrasTimer.current) clearTimeout(extrasTimer.current);
+			extrasTimer.current = setTimeout(() => {
+				extrasPart.current = null;
+				publish();
+			}, fadeInMs);
 		});
 		return () => {
 			sub?.unsubscribe();
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
+			if (extrasTimer.current) clearTimeout(extrasTimer.current);
 		};
-	}, [trpc, deviceId]);
+	}, [
+		trpc,
+		deviceId,
+		admit,
+		publish
+	]);
 	(0, react$1.useEffect)(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.result", (event) => {
 			const e = event;
 			if (!matchesDevice(e?.source, deviceId)) return;
-			if (Date.now() - lastEnrichedAt.current < DETECTION_FADE_MS) return;
 			const frame = e.data?.frame;
 			if (!frame?.detections?.length) return;
-			setDetection({
+			const fadeInMs = admit(typeof frame.timestamp === "number" ? frame.timestamp : null, lastRawTs);
+			if (fadeInMs === null) return;
+			rawPart.current = {
 				detections: frame.detections,
 				frameWidth: frame.width,
 				frameHeight: frame.height
-			});
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
-			detectionTimer.current = setTimeout(() => setDetection(null), DETECTION_FADE_MS);
+			};
+			publish();
+			if (rawTimer.current) clearTimeout(rawTimer.current);
+			rawTimer.current = setTimeout(() => {
+				rawPart.current = null;
+				publish();
+			}, fadeInMs);
 		});
 		return () => {
 			sub?.unsubscribe();
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
+			if (rawTimer.current) clearTimeout(rawTimer.current);
 		};
-	}, [trpc, deviceId]);
+	}, [
+		trpc,
+		deviceId,
+		admit,
+		publish
+	]);
 	(0, react$1.useEffect)(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.phase-transition", (event) => {

package/dist/index.js

@@ -71006,6 +71006,90 @@ function useDeviceCapSlice(trpc, deviceId, capName) {
 	return useDeviceStateSlice(handleRef.current);
 }
 //#endregion
+//#region src/hooks/merge-detections.ts
+/** Minimum IoU between an enriched root and a raw root to call them one subject
+*  when no trackId pairs them. */
+var EXTRA_MATCH_IOU_THRESHOLD = .3;
+function iou(a, b) {
+	const x1 = Math.max(a.x, b.x);
+	const y1 = Math.max(a.y, b.y);
+	const x2 = Math.min(a.x + a.width, b.x + b.width);
+	const y2 = Math.min(a.y + a.height, b.y + b.height);
+	const inter = Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
+	const union = a.width * a.height + b.width * b.height - inter;
+	return union > 0 ? inter / union : 0;
+}
+function isRoot(d) {
+	return d.kind !== "detail";
+}
+function scaleBox(b, sx, sy) {
+	return {
+		x: b.x * sx,
+		y: b.y * sy,
+		width: b.width * sx,
+		height: b.height * sy
+	};
+}
+/** The raw root an enriched root describes: same trackId, else best IoU. */
+function matchRawRoot(enrichedRoot, rawRoots, sx, sy) {
+	const trackId = enrichedRoot.track?.trackId;
+	if (trackId !== void 0) {
+		const byTrack = rawRoots.find((r) => r.track?.trackId === trackId);
+		if (byTrack) return byTrack;
+	}
+	const scaled = scaleBox(enrichedRoot.bbox, sx, sy);
+	let best = null;
+	let bestIou = EXTRA_MATCH_IOU_THRESHOLD;
+	for (const r of rawRoots) {
+		const v = iou(scaled, r.bbox);
+		if (v >= bestIou) {
+			best = r;
+			bestIou = v;
+		}
+	}
+	return best;
+}
+function mergeDetections(raw, extras) {
+	if (!extras) return raw;
+	const frameWidth = raw?.frameWidth ?? extras.frameWidth;
+	const frameHeight = raw?.frameHeight ?? extras.frameHeight;
+	const sx = extras.frameWidth > 0 ? frameWidth / extras.frameWidth : 1;
+	const sy = extras.frameHeight > 0 ? frameHeight / extras.frameHeight : 1;
+	const rawDets = raw?.detections ?? [];
+	const rawRoots = rawDets.filter(isRoot);
+	const rawRootFor = /* @__PURE__ */ new Map();
+	const extraLabels = /* @__PURE__ */ new Map();
+	for (const root of extras.detections.filter(isRoot)) {
+		const match = matchRawRoot(root, rawRoots, sx, sy);
+		rawRootFor.set(root.id, match);
+		if (match && root.labels.length > 0) extraLabels.set(match, [...extraLabels.get(match) ?? [], ...root.labels]);
+	}
+	const out = rawDets.map((d) => {
+		const add = extraLabels.get(d);
+		if (!add) return d;
+		const have = new Set(d.labels.map((l) => l.label));
+		const fresh = add.filter((l) => !have.has(l.label));
+		return fresh.length > 0 ? {
+			...d,
+			labels: [...d.labels, ...fresh]
+		} : d;
+	});
+	for (const d of extras.detections) {
+		if (isRoot(d)) continue;
+		const parent = d.parentId !== void 0 ? rawRootFor.get(d.parentId) : void 0;
+		out.push({
+			...d,
+			bbox: scaleBox(d.bbox, sx, sy),
+			...parent ? { parentId: parent.id } : {}
+		});
+	}
+	return {
+		detections: out,
+		frameWidth,
+		frameHeight
+	};
+}
+//#endregion
 //#region src/hooks/use-device-detections.ts
 /**
 * useDeviceDetections — subscribes to motion, raw motion, and detection events for a device.
@@ -71014,12 +71098,18 @@ function useDeviceCapSlice(trpc, deviceId, capName) {
 * admin-ui (BackendClient.trpc) and addon pages (AddonPageProps.trpc).
 */
 var MOTION_FADE_MS = 500;
-/** Detection overlay fade — ALSO the raw-fallback suppression window: while an
-*  enriched frame-tracked event arrived within this window, raw detection.result
-*  frames are ignored (post-analysis is the richer source; raw remains the
-*  fallback when post-analysis is absent). Keeping the two equal means raw
-*  resumes exactly when the enriched display fades — no blank gap. */
+/** Fade of each detection source (raw roots, enriched extras), counted from the
+*  frame's capture time so a late frame is not kept for the full window. */
 var DETECTION_FADE_MS = 800;
+/** A frame older than this at arrival is replayed pre-roll and never drawn.
+*  Same meaning as the server's OVERLAY_MAX_FRAME_AGE_MS. */
+var OVERLAY_MAX_FRAME_AGE_MS = 1e3;
+/**
+* The most of a frame's age (arrival minus its capture timestamp) the fade
+* deducts. Bounded so a skewed server/browser clock can never make boxes vanish
+* on arrival.
+*/
+var MAX_FRAME_AGE_FADE_DEDUCTION_MS = DETECTION_FADE_MS / 2;
 /** Helper: subscribe to live.onEvent without optional chaining on subscribe() */
 function safeSubscribe(trpc, category, onData) {
 	try {
@@ -71042,8 +71132,26 @@ function useDeviceDetections(trpc, deviceId) {
 	const [phase, setPhase] = useState("watching");
 	const motionTimer = useRef(void 0);
 	const motionRawTimer = useRef(void 0);
-	const detectionTimer = useRef(void 0);
-	const lastEnrichedAt = useRef(0);
+	const rawTimer = useRef(void 0);
+	const extrasTimer = useRef(void 0);
+	/** Live part of each source: raw roots and enriched extras fade independently. */
+	const rawPart = useRef(null);
+	const extrasPart = useRef(null);
+	/** Capture timestamp of the newest frame shown, per source; older arrivals are dropped. */
+	const lastRawTs = useRef(0);
+	const lastExtrasTs = useRef(0);
+	const publish = useCallback(() => {
+		setDetection(mergeDetections(rawPart.current, extrasPart.current));
+	}, []);
+	/** Admit a frame: null = rejected (stale or out of order), else its fade in ms. */
+	const admit = useCallback((frameTs, lastTs) => {
+		if (frameTs !== null) {
+			if (Date.now() - frameTs > OVERLAY_MAX_FRAME_AGE_MS) return null;
+			if (frameTs < lastTs.current) return null;
+			lastTs.current = frameTs;
+		}
+		return DETECTION_FADE_MS - (frameTs === null ? 0 : Math.min(Math.max(Date.now() - frameTs, 0), MAX_FRAME_AGE_FADE_DEDUCTION_MS));
+	}, []);
 	useEffect(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.motion-analysis", (event) => {
@@ -71092,48 +71200,72 @@ function useDeviceDetections(trpc, deviceId) {
 		};
 	}, [trpc, deviceId]);
 	useEffect(() => {
-		lastEnrichedAt.current = 0;
+		extrasPart.current = null;
+		rawPart.current = null;
+		lastExtrasTs.current = 0;
+		lastRawTs.current = 0;
+		setDetection(null);
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "pipeline-analytics.frame-tracked", (event) => {
 			const data = event?.data;
 			if (!data || data.deviceId !== deviceId) return;
 			if (!data.detections?.length) return;
 			if (typeof data.detections[0]?.kind !== "string") return;
-			lastEnrichedAt.current = Date.now();
-			setDetection({
+			const fadeInMs = admit(typeof data.timestamp === "number" ? data.timestamp : null, lastExtrasTs);
+			if (fadeInMs === null) return;
+			extrasPart.current = {
 				detections: data.detections,
 				frameWidth: data.frameWidth,
 				frameHeight: data.frameHeight
-			});
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
-			detectionTimer.current = setTimeout(() => setDetection(null), DETECTION_FADE_MS);
+			};
+			publish();
+			if (extrasTimer.current) clearTimeout(extrasTimer.current);
+			extrasTimer.current = setTimeout(() => {
+				extrasPart.current = null;
+				publish();
+			}, fadeInMs);
 		});
 		return () => {
 			sub?.unsubscribe();
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
+			if (extrasTimer.current) clearTimeout(extrasTimer.current);
 		};
-	}, [trpc, deviceId]);
+	}, [
+		trpc,
+		deviceId,
+		admit,
+		publish
+	]);
 	useEffect(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.result", (event) => {
 			const e = event;
 			if (!matchesDevice(e?.source, deviceId)) return;
-			if (Date.now() - lastEnrichedAt.current < DETECTION_FADE_MS) return;
 			const frame = e.data?.frame;
 			if (!frame?.detections?.length) return;
-			setDetection({
+			const fadeInMs = admit(typeof frame.timestamp === "number" ? frame.timestamp : null, lastRawTs);
+			if (fadeInMs === null) return;
+			rawPart.current = {
 				detections: frame.detections,
 				frameWidth: frame.width,
 				frameHeight: frame.height
-			});
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
-			detectionTimer.current = setTimeout(() => setDetection(null), DETECTION_FADE_MS);
+			};
+			publish();
+			if (rawTimer.current) clearTimeout(rawTimer.current);
+			rawTimer.current = setTimeout(() => {
+				rawPart.current = null;
+				publish();
+			}, fadeInMs);
 		});
 		return () => {
 			sub?.unsubscribe();
-			if (detectionTimer.current) clearTimeout(detectionTimer.current);
+			if (rawTimer.current) clearTimeout(rawTimer.current);
 		};
-	}, [trpc, deviceId]);
+	}, [
+		trpc,
+		deviceId,
+		admit,
+		publish
+	]);
 	useEffect(() => {
 		if (deviceId === null) return;
 		const sub = safeSubscribe(trpc, "detection.phase-transition", (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/ui-library",
-  "version": "1.2.348",
+  "version": "1.2.349",
   "repository": {
     "type": "git",
     "url": "https://github.com/camstack/server.git",