@camera.ui/server 0.0.113 → 0.0.117

package/dist/server/src/camera/decoder/detection-coordinator.js

@@ -62,7 +62,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 import { isNoRespondersError, RPCClass, RPCMethod } from '@camera.ui/rpc';
 import { SensorType } from '@camera.ui/sdk';
-// import { writeFileSync } from 'node:fs';
 import { NamespaceManager } from '../../rpc/namespaces.js';
 import { DETECTION_SENSOR_TYPES, SENSOR_TYPE_CONFIG } from '../sensors/types.js';
 import { normalizeZone } from '../utils/filter.js';
@@ -74,19 +73,26 @@ import { DetectionEventManager } from './event-manager.js';
 import { FrameScaler } from './frame-scaler.js';
 import { FrameSource } from './frame-source.js';
 import { PtzAutotracker } from './ptz-autotracker.js';
+import { SnapshotSource } from './snapshot-source.js';
 import { MOTION_WIDTH_MAP } from './types.js';
 // Default cascade hold-open window in seconds
 export const DEFAULT_CASCADE_TIMEOUT = 10;
 // Tracks below this speed (normalized units/s) are considered stationary.
 // Typical values: parked bike ~0.0006, standing person ~0.003–0.03.
 export const STATIONARY_SPEED_THRESHOLD = 0.002;
-// Object detection dwell window — bridges 1-2 missed frames inside an active
-// cascade so a single uncertain frame doesn't fire `detected=false` and split
-// the event. Mirrors the motion/audio dwell pattern.
 const OBJECT_DWELL_SECONDS = 2;
-// Hard deadline on a detector-plugin inference RPC. A hung detector must not
-// stall the whole detection loop — on timeout we skip the frame and continue.
 const DETECT_TIMEOUT_MS = 30_000;
+const EVENT_THUMB_MAX_WIDTH = 640;
+const DETECTION_THUMB_MAX_WIDTH = 640;
+const DETECTION_THUMB_MIN_CROP = 160;
+const DETECTION_THUMB_HQ_MAX_WIDTH = 640;
+const DETECTION_THUMB_HQ_MIN_CROP = 640;
+const DETECTION_THUMB_HQ_QUALITY = 80;
+const ATTRIBUTE_THUMB_MAX_WIDTH = 640;
+const ATTRIBUTE_THUMB_MIN_CROP = 128;
+const EVENT_THUMB_HQ_MAX_WIDTH = 960;
+const EVENT_THUMB_HQ_QUALITY = 75;
+const HQ_FRAME_MAX_AGE_MS = 500;
 async function withTimeout(promise, ms, label) {
     let timer;
     const timeout = new Promise((_resolve, reject) => {
@@ -121,6 +127,9 @@ let DetectionCoordinator = class DetectionCoordinator {
     pipeline;
     adHocVideoLoop = false;
     processingExternalSecondary = false;
+    hqSnapshotSource;
+    hqUpgradeInflight = false;
+    hqAspectWarned = false;
     cascadeUnsubscribe;
     dwellUnsubscribe;
     seenStationaryTracks = new Set();
@@ -159,6 +168,11 @@ let DetectionCoordinator = class DetectionCoordinator {
         this.frameSource = new FrameSource(frameSourceConfig, logger);
         this.frameScaler = new FrameScaler(null, logger);
         this.pipeline = new DetectionPipeline(config.zones, config.detectionSettings);
+        const hqUrl = this.resolveHqSourceUrl(config.availableSources);
+        if (hqUrl) {
+            this.hqSnapshotSource = new SnapshotSource({ url: hqUrl }, logger);
+        }
+        this.syncHqSnapshotSource();
         if (config.lines.length > 0) {
             this.pipeline.updateLines(config.lines, this.videoAspectRatio);
         }
@@ -312,19 +326,13 @@ let DetectionCoordinator = class DetectionCoordinator {
             detected: filtered.length > 0,
         };
     }
+    // PTZ-suppression gating happens upstream — callers decide whether a write
+    // belongs in the full pipeline or autotracker-only.
     ingestDetectionResult(sensorType, sensorId, properties, pluginId) {
-        // Note: PTZ-suppression gating happens upstream — processDetection and
-        // reportSensorWrite decide whether to route to autotracker-only vs. full
-        // ingest. By the time we land here, the caller has already decided this
-        // write belongs in the full pipeline.
-        // Update aggregated buffer based on sensor type. Each type maps to a different
-        // ProcessedDetectionData field — partial-merge with what's already buffered.
         this.updateBufferForType(sensorType, properties, pluginId);
         const detected = properties.detected === true;
-        // Motion/Audio: refresh dwell on positive detection. Dwell drives the
-        // `detected` / `blocked` / `lastTriggered` lifecycle entirely — see the
-        // dwell.onChange listener wired in the constructor. Motion additionally
-        // triggers cascade.
+        // Motion/Audio: dwell drives the detected/blocked/lastTriggered lifecycle
+        // entirely (see dwell.onChange in the constructor); motion also cascades.
         if (sensorType === SensorType.Motion && detected) {
             const motionTimeout = this.config.detectionSettings.motion.timeout;
             this.dwell.refresh(sensorId, motionTimeout);
@@ -340,15 +348,11 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
         }
         else if (sensorType === SensorType.Object && detected) {
-            // Object dwell — anti-chatter for object detection. Single missed frame
-            // (model uncertain for ~100ms) must not split the event into two.
-            //
-            // Stationary object gating: a track that is stationary AND was already
-            // seen in a previous frame during this event must NOT refresh the dwell.
-            // This prevents parked cars/bikes from keeping events alive forever.
-            // Moving tracks always refresh. Stationary tracks refresh only once
-            // (first time seen) — after that they're in seenStationaryTracks and
-            // get skipped. The set is cleared on cascade deactivate (event boundary).
+            // Object dwell — anti-chatter: a single missed frame must not split the
+            // event. Stationary tracks refresh the dwell only ONCE (first sighting);
+            // afterwards they're in seenStationaryTracks and don't count, so parked
+            // cars/bikes can't keep events alive forever. Moving tracks always count.
+            // The set is cleared on cascade deactivate (event boundary).
             const detections = properties.detections ?? [];
             let hasActiveTrack = false;
             for (const t of detections) {
@@ -357,40 +361,31 @@ let DetectionCoordinator = class DetectionCoordinator {
                 const isStationary = (t.trackSpeed ?? 0) < STATIONARY_SPEED_THRESHOLD;
                 if (isStationary) {
                     if (t.trackId !== undefined && !this.seenStationaryTracks.has(t.trackId)) {
-                        // First time seeing this stationary track — count it as active
                         this.seenStationaryTracks.add(t.trackId);
                         hasActiveTrack = true;
                     }
-                    // Already seen stationary track — does not count
                 }
                 else {
-                    // Moving track — always counts
                     hasActiveTrack = true;
                 }
             }
             if (hasActiveTrack) {
                 this.dwell.refresh(sensorId, OBJECT_DWELL_SECONDS);
-                // this.logger.debug('[stationary-debug] active track found, dwell refreshed');
             }
             else {
-                // Only known stationary tracks — suppress detected and clear detections
-                // from the buffer so the EventManager doesn't open a new segment for
-                // objects we've already seen. The UI still gets the bboxes via the
-                // property publish (publishProps path below).
+                // Only known stationary tracks — suppress detected and clear buffered
+                // detections so the EventManager doesn't open a new segment; the UI
+                // still gets the bboxes via the property publish below.
                 properties.detected = false;
                 if (this.currentDetectionState.object) {
                     this.currentDetectionState.object.detected = false;
                     this.currentDetectionState.object.detections = [];
                 }
-                // this.logger.debug('[stationary-debug] suppressed — all tracks stationary+known');
             }
         }
-        // Publish path. For motion/audio sensors, dwell is the SOLE owner of
-        // `detected` / `blocked` / `lastTriggered` regardless of the current
-        // frame's detected value — anti-chatter means a "no detection" frame
-        // must NOT overwrite the dwell-set `detected=true`. Always strip these
-        // dwell-managed properties from the publish, and let `dwell.onChange`
-        // (activated/expired) be the only path that writes them.
+        // Dwell is the SOLE owner of detected/blocked/lastTriggered for these
+        // types — a "no detection" frame must not overwrite the dwell-set state,
+        // so strip them from the publish; dwell.onChange is the only writer.
         let publishProps = properties;
         if (sensorType === SensorType.Motion || sensorType === SensorType.Audio || sensorType === SensorType.Object) {
             const { detected: _d, blocked: _b, lastTriggered: _t, ...rest } = properties;
@@ -399,8 +394,7 @@ let DetectionCoordinator = class DetectionCoordinator {
         if (Object.keys(publishProps).length > 0) {
             this.writeSensorProperties(sensorId, publishProps);
         }
-        // EventManager is NOT ticked here — detection-coordinator flushes once
-        // per frame at the end of processDetection() after all detectors + thumbnails.
+        // EventManager is NOT ticked here — processDetection flushes once per frame.
     }
     updateBufferForType(sensorType, properties, pluginId) {
         const cs = this.currentDetectionState;
@@ -455,6 +449,7 @@ let DetectionCoordinator = class DetectionCoordinator {
     }
     updateFrameWorkerSettings(settings) {
         this.config.frameWorkerSettings = settings;
+        this.syncHqSnapshotSource();
     }
     updateInterfaceSettings(settings) {
         this.config.interfaceSettings = settings;
@@ -465,6 +460,7 @@ let DetectionCoordinator = class DetectionCoordinator {
     async dispose() {
         await this.stopVideoLoop();
         await this.stopAudioLoop();
+        await this.hqSnapshotSource?.stop();
         this.ptzAutotracker.dispose();
         this.cascadeUnsubscribe?.();
         this.dwellUnsubscribe?.();
@@ -571,9 +567,8 @@ let DetectionCoordinator = class DetectionCoordinator {
         if (!this.singlePlugins.has(SensorType.Object)) {
             this.adHocVideoLoop = false;
         }
-        // Hot-reload: if the ad-hoc loop is no longer needed after removing the
-        // plugin, stop it. Uses needsAdHocLoop() (not shouldVideoBeActive) so we
-        // don't accidentally stop a loop still needed for F object (requiresFrames=true).
+        // Hot-reload: uses needsAdHocLoop() (not shouldVideoBeActive) so a loop
+        // still needed by a frame-based object plugin isn't stopped accidentally.
         if (this.adHocVideoLoop && !this.needsAdHocLoop()) {
             this.adHocVideoLoop = false;
             this.logger.debug('Stopping ad-hoc video loop — last frame-based consumer removed');
@@ -591,17 +586,13 @@ let DetectionCoordinator = class DetectionCoordinator {
     async reportSensorWrite(sensorId, sensorType, properties) {
         if (sensorType === SensorType.Object) {
             const filtered = this.applyExternalDetectionFilters(sensorType, properties);
-            // Always feed the autotracker — it needs fresh data every write, even
-            // (especially) during suppression, so it can decide when to stop.
-            // External-sensor object writes are presence-only (SDK synthesises a
-            // full-frame bbox when the plugin reports without coordinates), so use
-            // the presence channel — it holds the return-to-home timer without
-            // driving the motor.
+            // Always feed the autotracker (even during suppression, so it can decide
+            // when to stop). External writes are presence-only — the presence channel
+            // holds the return-to-home timer without driving the motor.
             const externalDetections = filtered.detections ?? [];
             this.ptzAutotracker.handlePresenceDetections(externalDetections);
-            // During PTZ suppression: autotracker got the data, but tracker/pipeline/
-            // events/UI are gated (no stale bboxes, no false events from camera pose
-            // change). Skip the rest.
+            // During suppression tracker/pipeline/events stay gated — no stale
+            // bboxes or false events from the camera pose change.
             if (this.ptzAutotracker.suppressionActive)
                 return;
             this.ingestDetectionResult(SensorType.Object, sensorId, filtered);
@@ -612,9 +603,8 @@ let DetectionCoordinator = class DetectionCoordinator {
                 return; // busy-skip: previous RPC still running
             this.processingExternalSecondary = true;
             try {
-                // Wrap the zone-filtered external boxes as TrackedDetection (no real
-                // tracking, just shape adapter — `trackLost: false`) so the secondary
-                // pipeline can treat them uniformly with frame-driven output.
+                // Wrap external boxes as TrackedDetection (shape adapter, no real
+                // tracking) so the secondary pipeline treats them like loop output.
                 const rawExternal = filtered.detections ?? [];
                 const objectDetections = this.pipeline.processExternal(rawExternal);
                 // Fast path: loop is running and has a frame → crop mode.
@@ -635,9 +625,8 @@ let DetectionCoordinator = class DetectionCoordinator {
                     }
                     return;
                 }
-                // Slow path: loop hasn't produced a frame yet → snapshot fetch fallback.
-                // Full-frame mode (no per-detection crops) — secondaries run global
-                // detection on the whole scaled frame.
+                // Slow path: no loop frame yet → snapshot fetch, secondaries run
+                // full-frame (no per-detection crops).
                 const fetched = await this.frameSource.fetchSnapshotFrame();
                 if (!fetched)
                     return;
@@ -648,7 +637,11 @@ let DetectionCoordinator = class DetectionCoordinator {
                     const snapshot = this.buildSnapshot();
                     if (sceneJpeg)
                         snapshot.eventThumbnail = sceneJpeg;
+                    const wantsEventThumb = this.eventManager.needsThumbnail() || this.snapshotWillStartEvent(snapshot);
                     this.eventManager.processResults(snapshot);
+                    if (wantsEventThumb) {
+                        this.upgradeEventThumbnailAsync();
+                    }
                 }
                 finally {
                     await fetched[Symbol.asyncDispose]();
@@ -660,8 +653,7 @@ let DetectionCoordinator = class DetectionCoordinator {
             return;
         }
         if (sensorType === SensorType.Motion) {
-            // Motion: fully gated during suppression. Frame-diff is fake during
-            // camera repositioning.
+            // Fully gated during suppression — frame-diff is fake while the camera repositions.
             if (this.ptzAutotracker.suppressionActive)
                 return;
             const filtered = this.applyExternalDetectionFilters(sensorType, properties);
@@ -670,9 +662,8 @@ let DetectionCoordinator = class DetectionCoordinator {
             this.fetchEventThumbnailAsync();
             return;
         }
-        // External secondaries (Face/Plate/Classifier/Clip with requiresFrames=false):
-        // direct ingest, no pixel work. For multi-provider types (Classifier), look
-        // up the owning pluginId for buffer keying.
+        // External secondaries: direct ingest, no pixel work. Classifier (multi-
+        // provider) needs the owning pluginId for buffer keying.
         let pluginId;
         if (sensorType === SensorType.Classifier) {
             const typePlugins = this.multiPlugins.get(SensorType.Classifier);
@@ -690,26 +681,19 @@ let DetectionCoordinator = class DetectionCoordinator {
         this.eventManager.processResults(this.buildSnapshot());
     }
     reportSensorTrigger(sensorId, triggerType, action, _sustained, timeoutSeconds) {
-        // Use namespaced dwell key so sensor trigger dwells don't overwrite
-        // the sensor's own properties (detected/blocked). Motion/audio sensors
-        // have their properties managed by dwell; contact/switch/light sensors don't.
+        // Namespaced dwell key so trigger dwells don't overwrite the sensor's own
+        // detected/blocked properties (contact/switch/light manage those themselves).
         const dwellKey = `trigger:${sensorId}`;
-        // Track active sensor trigger types for snapshot
         if (action === 'activate') {
             this.activeSensorTriggerTypes.set(dwellKey, triggerType);
         }
-        // Dwell for event lifecycle — consistent with motion/audio.
-        // Activate: starts/extends the event. Deactivate: refreshes for cooldown window.
         this.dwell.refresh(dwellKey, timeoutSeconds);
-        // Cascade for object-detection gating — only on activate
         if (action === 'activate' && this.cascadeEnabled) {
             this.cascade.triggerMomentary(this.cascadeTimeoutSeconds);
         }
-        // Flush immediately so EventManager sees the trigger (like reportSensorWrite)
         this.eventManager.processResults(this.buildSnapshot());
-        // Async event-thumb fetch via snapshot URL — covers the trigger-only path
-        // (doorbell, contact sensor) where no loop frame is available to encode from.
-        // No-op if a loop frame already populated the thumb earlier.
+        // Trigger-only path (doorbell, contact) has no loop frame to encode from —
+        // fetch the event thumb async; no-op if one was already captured.
         if (action === 'activate') {
             this.fetchEventThumbnailAsync();
         }
@@ -913,10 +897,15 @@ let DetectionCoordinator = class DetectionCoordinator {
             try {
                 const env_1 = { stack: [], error: void 0, hasError: false };
                 try {
+                    const hqJpeg = await this.hqSnapshotSource?.snapshotJpeg(EVENT_THUMB_HQ_MAX_WIDTH, EVENT_THUMB_HQ_QUALITY);
+                    if (hqJpeg) {
+                        this.eventManager.publishEventThumbnail(hqJpeg);
+                        return;
+                    }
                     const handle = __addDisposableResource(env_1, await this.frameSource.fetchSnapshotFrame(), true);
                     if (!handle)
                         return;
-                    const jpeg = await this.frameScaler.frameToJPEG(handle.frame, 320);
+                    const jpeg = await this.frameScaler.frameToJPEG(handle.frame, EVENT_THUMB_MAX_WIDTH);
                     if (!jpeg)
                         return;
                     this.eventManager.publishEventThumbnail(jpeg);
@@ -936,6 +925,81 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
         })();
     }
+    // Fallback: async snapshot replacement of a substream event thumbnail —
+    // only reached when the HQ source couldn't deliver a frame inline at event
+    // start (still connecting, buffer not warm yet).
+    upgradeEventThumbnailAsync() {
+        const source = this.hqSnapshotSource;
+        if (!source?.isRunning || !source.hasBuffer || this.hqUpgradeInflight)
+            return;
+        this.hqUpgradeInflight = true;
+        void (async () => {
+            try {
+                const jpeg = await source.snapshotJpeg(EVENT_THUMB_HQ_MAX_WIDTH, EVENT_THUMB_HQ_QUALITY);
+                if (jpeg && this.eventManager.hasActiveEvent()) {
+                    this.eventManager.publishEventThumbnail(jpeg);
+                }
+            }
+            catch (error) {
+                this.logger.debug('Snapshot event thumbnail upgrade failed:', error);
+            }
+            finally {
+                this.hqUpgradeInflight = false;
+            }
+        })();
+    }
+    // Recent snapshot frame + its scaler (own hardware context); caller disposes
+    // the frame. With a reference size the aspect ratios must match — normalized
+    // boxes only transfer between streams showing the same sensor area.
+    async acquireHqFrame(reference) {
+        const source = this.hqSnapshotSource;
+        if (!source?.isRunning || !source.hasBuffer)
+            return null;
+        const scaler = source.scaler;
+        if (!scaler)
+            return null;
+        const frame = await source.getFrame(HQ_FRAME_MAX_AGE_MS);
+        if (!frame)
+            return null;
+        if (reference) {
+            const refAspect = reference.width / reference.height;
+            const hqAspect = frame.width / frame.height;
+            if (Math.abs(refAspect - hqAspect) / refAspect > 0.02) {
+                if (!this.hqAspectWarned) {
+                    this.hqAspectWarned = true;
+                    this.logger.warn(`[hq-thumb] aspect mismatch (detection ${reference.width}x${reference.height} vs snapshot ${frame.width}x${frame.height}) — detection crops stay on the substream`);
+                }
+                frame[Symbol.dispose]?.();
+                return null;
+            }
+        }
+        return { frame, scaler };
+    }
+    resolveHqSourceUrl(sources) {
+        if (!sources?.length)
+            return undefined;
+        const order = ['high-resolution', 'mid-resolution', 'low-resolution'];
+        const byRole = new Map(sources.map((s) => [s.role, s]));
+        // Detection consumes the LOWEST available role (worker: lowRes ?? midRes
+        // ?? streamSource) — the HQ companion is only worth a session when a
+        // strictly higher-resolution role exists.
+        const detectionRole = [...order].reverse().find((role) => byRole.has(role));
+        const hqRole = order.find((role) => byRole.has(role));
+        if (!detectionRole || !hqRole || hqRole === detectionRole)
+            return undefined;
+        return byRole.get(hqRole).url;
+    }
+    syncHqSnapshotSource() {
+        if (!this.hqSnapshotSource)
+            return;
+        const wanted = this.config.frameWorkerSettings.hqSnapshots === true;
+        if (wanted && !this.hqSnapshotSource.isRunning) {
+            this.hqSnapshotSource.start();
+        }
+        else if (!wanted && this.hqSnapshotSource.isRunning) {
+            void this.hqSnapshotSource.stop();
+        }
+    }
     calculateDBFS(data, format) {
         let sumSquares = 0;
         let sampleCount = 0;
@@ -1118,28 +1182,19 @@ let DetectionCoordinator = class DetectionCoordinator {
         let motionDetected = false;
         let objectDetections = [];
         const results = { timestamp: t0 };
-        // Refresh ReID counters every frame while cascade is active so dead
-        // tracks never expire during the cascade window — exactly tied to
-        // cascade lifecycle, no estimated timeout needed.
+        // Refresh ReID every frame while cascade is active so dead tracks never
+        // expire during the cascade window.
         if (this.cascade.isActive) {
             this.pipeline.refreshReid();
         }
-        // PTZ-suppression gating:
-        //  - Motion: skipped entirely. Frame-diff is genuinely wrong while the camera
-        //    is repositioning (whole scene "moves") — the detector produces garbage.
-        //  - Object: runs through the full pipeline unchanged. Norfair is fed the
-        //    per-frame PTZ pose delta (via `consumePoseDelta()`) so Kalman
-        //    predictions stay aligned with the world frame across pans — track ids
-        //    survive camera motion instead of being lost-and-re-acquired every
-        //    cycle. The autotracker itself gates motor decisions on its own
-        //    `isPtzMoving` state, so it doesn't issue commands during a pan.
+        // PTZ suppression: motion is skipped entirely (frame-diff is garbage while
+        // the camera repositions); object keeps running — Norfair gets the pose
+        // delta so track ids survive pans, and the autotracker gates motor
+        // commands on its own isPtzMoving state.
         const ptzSuppressed = this.ptzAutotracker.suppressionActive;
-        // 1. Motion detection — runs every frame whenever a motion plugin is registered,
-        // regardless of cascade state. Two reasons:
-        //   a) Motion sensor properties (bboxes shown in UI) need to stay fresh during cascade
-        //   b) Re-triggering cascade.triggerMomentary on each detected frame extends the cascade
-        //      naturally, so a sustained motion event keeps cascade alive as long as motion happens.
-        // The cascade is the gate for OBJECT detection, not for motion.
+        // 1. Motion — every frame regardless of cascade state: keeps UI bboxes
+        // fresh AND re-triggers the cascade so sustained motion keeps it alive.
+        // The cascade gates OBJECT detection, not motion.
         const motionPlugin = this.singlePlugins.get(SensorType.Motion);
         if (motionPlugin?.requiresFrames && !ptzSuppressed) {
             const motionFrame = await this.scaleForMotion(rawFrame);
@@ -1172,29 +1227,18 @@ let DetectionCoordinator = class DetectionCoordinator {
             motionDetected = true;
             results.cascadeTriggered = true;
         }
-        // Funnel motion result through unified ingest path (handles dwell + cascade + buffer + EventManager tick).
-        // `detected` is re-derived from post-zone-filter detections: if the plugin reported
-        // motion but the zone filter wiped all boxes, effective detected is false. The plugin's
-        // own `detected` flag is ignored on purpose — zone filtering wins.
+        // `detected` is re-derived from post-zone-filter detections — the plugin's
+        // own flag is ignored on purpose, zone filtering wins.
         if (results.motion && motionPlugin) {
             this.ingestDetectionResult(SensorType.Motion, motionPlugin.sensorId, {
                 detected: motionDetected,
                 detections: results.motion.detections,
             });
         }
-        // 2. Object detection — runs only when the cascade is active (i.e. some
-        // wake source has fired: frame-based motion, external motion, audio, or
-        // a configured sensor trigger). When cascade is disabled in the camera
-        // config, runs unconditionally as an always-on detector.
-        //
-        // A motion plugin (frame-based OR external) must be registered for object
-        // detection to ever fire — without one, no wake source exists for object,
-        // so the cascade would never become active.
+        // 2. Object — gated by the cascade (wake sources: motion, audio, sensor
+        // trigger), always-on when cascade is disabled, and kept running during
+        // PTZ suppression so the tracker holds its lock across pans.
         const objectPlugin = this.singlePlugins.get(SensorType.Object);
-        // Object detection runs during suppression too — the tracker stays alive
-        // across pans via Norfair's camera-motion compensation so autotracker
-        // keeps a stable lock. Without suppression: needs an active cascade (or
-        // cascade disabled globally).
         const shouldDetectObjects = objectPlugin?.requiresFrames === true && (ptzSuppressed || !this.cascadeEnabled || this.cascade.isActive);
         if (shouldDetectObjects) {
             const objectFrame = await this.scaleForObject(rawFrame);
@@ -1205,23 +1249,14 @@ let DetectionCoordinator = class DetectionCoordinator {
                     const result = await withTimeout(objectPlugin.proxy.detectObjects(objectFrame), DETECT_TIMEOUT_MS, 'Object');
                     if (!this.loopRunning)
                         return;
-                    // Full pipeline (always): NMS → merge → zone filter → track (with
-                    // appearance ReID) → line crossing. Runs even on empty-detection
-                    // frames so Norfair advances Kalman state and the autotracker sees
-                    // extrapolated positions instead of a momentary hole.
-                    //
-                    // The PTZ pose delta is handed to Norfair so Kalman predictions
-                    // are transformed into a world-stable frame — track ids survive
-                    // pans instead of going through LOST → REACQUIRE every cycle.
+                    // Full pipeline even on empty frames so Norfair advances Kalman
+                    // state; the PTZ pose delta keeps predictions world-stable across
+                    // pans (track ids survive instead of LOST → REACQUIRE).
                     const poseDelta = this.ptzAutotracker.consumePoseDelta();
                     const pipelineResult = this.pipeline.process(result.detections, objectFrame, poseDelta);
-                    // Tracks for UI: matched always pass, extrapolated (Kalman-only)
-                    // are shown for smooth bbox display across single-frame detector
-                    // misses — but filtered when they've drifted too far off-frame.
-                    // When a fast-moving target walks off-screen, Norfair keeps
-                    // extrapolating based on the last-known velocity; without this
-                    // guard the UI ends up drawing ghost bboxes floating outside the
-                    // stream and the autotracker has no reason to chase them anyway.
+                    // Extrapolated (Kalman-only) tracks smooth single-frame detector
+                    // misses in the UI, but are dropped once they drift off-frame —
+                    // otherwise ghost bboxes float outside the stream.
                     const visibleTracks = pipelineResult.tracked.filter((t) => {
                         if (!t.trackLost)
                             return true;
@@ -1233,16 +1268,9 @@ let DetectionCoordinator = class DetectionCoordinator {
                     results.object = { ...result, detections: visibleTracks };
                     if (pipelineResult.crossings.length > 0)
                         results.lineCrossings = pipelineResult.crossings;
-                    // Feed the autotracker with ALL tracked detections, incl. Kalman-
-                    // extrapolated ones. When the object detector misses a single frame
-                    // (normal with YOLO-style models), Norfair's extrapolation gives
-                    // the best estimate of where the target still is — hiding that
-                    // from the autotracker would cause a one-frame "target gone" blip
-                    // and flip it into LOST, only to REACQUIRE on the very next frame
-                    // when the detection returns. That churn is orthogonal to camera
-                    // motion and shouldn't drive state transitions. The autotracker
-                    // gates motor decisions on its own `isPtzMoving` flag, so during
-                    // suppression it observes without commanding.
+                    // Feed the autotracker ALL tracked detections incl. extrapolated —
+                    // a single missed detector frame must not flip it into LOST/REACQUIRE
+                    // churn. It gates motor decisions on its own isPtzMoving flag.
                     this.ptzAutotracker.handleObjectDetections(pipelineResult.tracked);
                 }
                 catch (error) {
@@ -1259,9 +1287,7 @@ let DetectionCoordinator = class DetectionCoordinator {
             // Buffer line crossings so the EventManager snapshot picks them up
             this.currentDetectionState.lineCrossings = results.lineCrossings;
         }
-        // Funnel object result through unified ingest path. Same rule as motion:
-        // detected is re-derived from post-pipeline detections, the plugin's own
-        // detected flag is ignored after pipeline filtering.
+        // Same rule as motion: detected is re-derived from post-pipeline detections.
         if (results.object && objectPlugin) {
             this.ingestDetectionResult(SensorType.Object, objectPlugin.sensorId, {
                 detected: objectDetections.length > 0,
@@ -1270,49 +1296,62 @@ let DetectionCoordinator = class DetectionCoordinator {
         }
         if (!this.loopRunning)
             return;
-        // 3. Secondary detectors + per-detection thumbnails. Result-collection only —
-        //    ingest happens via ingestResultsForAllSecondaries below so the loop tick
-        //    and the external-RPC path share the same secondary-processing helper.
+        // 3. Secondary detectors + per-detection thumbnails. Result-collection
+        // only — the shared ingest below keeps loop tick and external-RPC path
+        // on the same helper.
         if (objectDetections.length > 0) {
             await this.runSecondariesAndThumbnails(rawFrame, objectDetections, results);
         }
         if (!this.loopRunning)
             return;
-        // 4. Funnel secondary results through unified ingest path.
+        // 4. Unified ingest.
         this.ingestResultsForAllSecondaries(results);
-        // 5. Single flush — one processResults per frame, AFTER all detectors + thumbnails.
-        // This ensures segment-start messages have thumbnails and all secondary detection
-        // data (faces, plates, classifiers, clips) is available when the segment opens.
+        // 5. Single flush per frame, AFTER all detectors + thumbnails — so
+        // segment-start messages already carry thumbnails and secondary data.
         if (!this.loopRunning)
             return;
         const snapshot = this.buildSnapshot();
         if (results.thumbnails && results.thumbnails.length > 0) {
             snapshot.thumbnails = results.thumbnails;
         }
-        // 5a. Event-level thumbnail — full-frame downscaled JPEG. Generated lazily
-        // whenever the EventManager signals it still needs one. This covers two cases:
-        //   1. Event was already started by a non-frame path (sensor trigger, motion
-        //      ingest from a plugin) — first frame after start fills it in.
-        //   2. Event will be started by THIS frame's triggers — pre-encode so the
-        //      'start' message carries the thumbnail inline.
-        // We use `eventManagerWillStart` heuristically here: if there's a trigger
-        // signal in the snapshot AND no active event yet, the event will be started
-        // by this processResults call. Either way, attaching is harmless because
-        // EventManager only consumes it if `needsEventThumbnail` is true.
-        if (this.eventManager.needsThumbnail() || this.snapshotWillStartEvent(snapshot)) {
+        // Event-level thumbnail — generated lazily when the EventManager still
+        // needs one OR this frame's triggers will start an event (pre-encode so
+        // the 'start' message carries it inline). Attaching is harmless either
+        // way; EventManager only consumes it while needsEventThumbnail is true.
+        // Full frame prefers the snapshot source (no aspect constraint needed).
+        const wantsEventThumb = this.eventManager.needsThumbnail() || this.snapshotWillStartEvent(snapshot);
+        let hqThumbAttached = false;
+        if (wantsEventThumb) {
             try {
-                const jpeg = await this.frameScaler.frameToJPEG(rawFrame, 320);
-                if (jpeg)
-                    snapshot.eventThumbnail = jpeg;
+                const hq = await this.acquireHqFrame();
+                try {
+                    if (hq) {
+                        const jpeg = await hq.scaler.frameToJPEG(hq.frame, EVENT_THUMB_HQ_MAX_WIDTH, EVENT_THUMB_HQ_QUALITY);
+                        if (jpeg) {
+                            snapshot.eventThumbnail = jpeg;
+                            hqThumbAttached = true;
+                        }
+                    }
+                    if (!snapshot.eventThumbnail) {
+                        const jpeg = await this.frameScaler.frameToJPEG(rawFrame, EVENT_THUMB_MAX_WIDTH);
+                        if (jpeg)
+                            snapshot.eventThumbnail = jpeg;
+                    }
+                }
+                finally {
+                    hq?.frame[Symbol.dispose]?.();
+                }
             }
             catch (error) {
                 this.logger.error('Event thumbnail generation error:', error);
             }
         }
-        // this.logger.debug(
-        //   `[flush-debug] objects=${snapshot.objects.length} faces=${snapshot.faces.length} plates=${snapshot.plates.length} cls=${snapshot.classifiers.length} clips=${snapshot.clips.length} cascade=${snapshot.hasCascadeTrigger} thumbs=${snapshot.thumbnails?.length ?? 0}`,
-        // );
         this.eventManager.processResults(snapshot);
+        // Inline HQ succeeded → nothing to upgrade; otherwise the async path
+        // covers the window where the HQ source wasn't ready at event start.
+        if (wantsEventThumb && !hqThumbAttached) {
+            this.upgradeEventThumbnailAsync();
+        }
     }
     snapshotWillStartEvent(snapshot) {
         if (this.eventManager.hasActiveEvent())
@@ -1375,7 +1414,6 @@ let DetectionCoordinator = class DetectionCoordinator {
     }
     async prepareSecondaryRegions(rawFrame, objectDetections) {
         const result = new Map();
-        // Collect all active secondary plugins and their requirements
         const consumers = [];
         const facePlugin = this.singlePlugins.get(SensorType.Face);
         if (facePlugin && this.hasSecondaryModelSpec(facePlugin.modelSpec) && this.isVideoInputSpec(facePlugin.modelSpec.input)) {
@@ -1399,7 +1437,6 @@ let DetectionCoordinator = class DetectionCoordinator {
         }
         if (consumers.length === 0)
             return result;
-        // For each detection, determine which consumers need it and what sizes
         for (const detection of objectDetections) {
             const detLabel = detection.label.toLowerCase();
             const targets = [];
@@ -1410,8 +1447,7 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
             if (targets.length === 0)
                 continue;
-            // Deduplicate targets with identical dimensions (e.g. two classifiers at same size)
-            // — keep first key, share the result
+            // Consumers with identical dimensions share one scaled region
             const uniqueTargets = [];
             const dupeMap = new Map(); // sizeKey → [consumerKey, ...]
             for (const t of targets) {
@@ -1426,7 +1462,6 @@ let DetectionCoordinator = class DetectionCoordinator {
                 }
             }
             const regions = await this.frameScaler.cropAndScaleMulti(rawFrame, detection, uniqueTargets);
-            // Distribute results to all consumers (including those sharing dimensions)
             for (const [_sizeKey, consumerKeys] of dupeMap) {
                 const primaryKey = consumerKeys[0];
                 const region = regions.get(primaryKey);
@@ -1534,7 +1569,15 @@ let DetectionCoordinator = class DetectionCoordinator {
             this.currentDetectionState.faceEmbeddingModel = results.faceEmbeddingModel;
         }
         try {
-            results.thumbnails = await this.generateThumbnails(rawFrame, objectDetections, results);
+            // Detectors consumed the substream frame above; images destined for the
+            // event (chips, scene) prefer the snapshot frame when available.
+            const hq = await this.acquireHqFrame({ width: rawFrame.width, height: rawFrame.height });
+            try {
+                results.thumbnails = await this.generateThumbnails(hq?.frame ?? rawFrame, hq?.scaler ?? this.frameScaler, hq !== null, objectDetections, results);
+            }
+            finally {
+                hq?.frame[Symbol.dispose]?.();
+            }
         }
         catch (error) {
             this.logger.error('Thumbnail generation error:', error);
@@ -1556,7 +1599,7 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
         }
         try {
-            return await this.frameScaler.frameToJPEG(rawFrame, 320);
+            return await this.frameScaler.frameToJPEG(rawFrame, EVENT_THUMB_MAX_WIDTH);
         }
         catch (error) {
             this.logger.debug('Full-frame scene thumbnail failed:', error);
@@ -1617,65 +1660,12 @@ let DetectionCoordinator = class DetectionCoordinator {
         const facePlugin = this.singlePlugins.get(SensorType.Face);
         if (!facePlugin || croppedRegions.length === 0)
             return undefined;
-        // for (let i = 0; i < croppedRegions.length; i++) {
-        //   const r = croppedRegions[i];
-        //   // prettier-ignore
-        //   this.logger.debug(
-        //     `[face-debug] crop[${i}] label=${r.detection.label} ` +
-        //     `cropSize=${r.cropSize.width}x${r.cropSize.height} ` +
-        //     `scaledTo=${r.frame.width}x${r.frame.height} ` +
-        //     `offset=(${r.offset.x},${r.offset.y}) ` +
-        //     `original=${r.originalSize.width}x${r.originalSize.height}`,
-        //   );
-        //   // Debug: save person crop as raw RGB for visual inspection
-        //   if (r.frame.data && r.detection.label === 'person') {
-        //     try {
-        //       const ts = Date.now();
-        //       writeFileSync(`/tmp/crop_person_${ts}_${r.frame.width}x${r.frame.height}.rgb`, Buffer.from(r.frame.data as Buffer));
-        //       this.logger.debug(`[face-debug] saved person crop: /tmp/crop_person_${ts}_${r.frame.width}x${r.frame.height}.rgb`);
-        //     } catch {
-        //       /* ignore */
-        //     }
-        //   }
-        // }
         const batchResults = await withTimeout(facePlugin.proxy.detectFaces(this.prepareSecondaryFrames(croppedRegions)), DETECT_TIMEOUT_MS, 'Face');
         const allFaces = [];
         for (let i = 0; i < batchResults.length; i++) {
             const parentTrackId = 'trackId' in croppedRegions[i].detection ? croppedRegions[i].detection.trackId : undefined;
             for (const face of batchResults[i].detections) {
                 const transformed = this.transformBoxToOriginal(face.box, croppedRegions[i]);
-                // const rawBox = face.box;
-                // // prettier-ignore
-                // this.logger.debug(
-                //   `[face-debug] face in crop[${i}] [parentTrackId=${parentTrackId}]: ` +
-                //   `raw=(${rawBox.x.toFixed(4)},${rawBox.y.toFixed(4)},${rawBox.width.toFixed(4)},${rawBox.height.toFixed(4)}) ` +
-                //   `transformed=(${transformed.x.toFixed(4)},${transformed.y.toFixed(4)},${transformed.width.toFixed(4)},${transformed.height.toFixed(4)}) ` +
-                //   `conf=${face.confidence.toFixed(3)}`,
-                // );
-                // // Debug: save face crop region from the person crop for visual inspection
-                // if (croppedRegions[i].frame.data && face.confidence > 0.6) {
-                //   try {
-                //     const cropData = croppedRegions[i].frame.data as Buffer;
-                //     const fw = croppedRegions[i].frame.width;
-                //     const fh = croppedRegions[i].frame.height;
-                //     const bpp = cropData.length / (fw * fh); // bytes per pixel (3 for rgb)
-                //     const fx = Math.floor(rawBox.x * fw);
-                //     const fy = Math.floor(rawBox.y * fh);
-                //     const fbw = Math.floor(rawBox.width * fw);
-                //     const fbh = Math.floor(rawBox.height * fh);
-                //     const faceBuf = Buffer.alloc(fbw * fbh * bpp);
-                //     for (let row = 0; row < fbh; row++) {
-                //       const srcOff = ((fy + row) * fw + fx) * bpp;
-                //       const dstOff = row * fbw * bpp;
-                //       cropData.copy(faceBuf, dstOff, srcOff, srcOff + fbw * bpp);
-                //     }
-                //     const ts = Date.now();
-                //     writeFileSync(`/tmp/crop_face_${ts}_${fbw}x${fbh}.rgb`, faceBuf);
-                //     this.logger.debug(`[face-debug] saved face crop: /tmp/crop_face_${ts}_${fbw}x${fbh}.rgb`);
-                //   } catch {
-                //     /* ignore */
-                //   }
-                // }
                 allFaces.push({ ...face, box: transformed, parentTrackId });
             }
         }
@@ -1753,10 +1743,19 @@ let DetectionCoordinator = class DetectionCoordinator {
         const embeddingModel = clipPlugin.modelSpec?.embeddingModel ?? '';
         return { embeddings: allEmbeddings, embeddingModel };
     }
-    async generateThumbnails(rawFrame, objectDetections, results) {
+    async generateThumbnails(sourceFrame, scaler, usingHq, objectDetections, results) {
         const thumbnails = [];
+        const attributePadding = usingHq ? 0.4 : 0.75;
+        const detectionMaxWidth = usingHq ? DETECTION_THUMB_HQ_MAX_WIDTH : DETECTION_THUMB_MAX_WIDTH;
+        const detectionMinCrop = usingHq ? DETECTION_THUMB_HQ_MIN_CROP : DETECTION_THUMB_MIN_CROP;
+        const detectionQuality = usingHq ? DETECTION_THUMB_HQ_QUALITY : undefined;
         // Object thumbnails — objectDetections are TrackedDetection[] when tracker ran
-        const objectCrops = await this.frameScaler.cropToJPEG(rawFrame, objectDetections);
+        const objectCrops = await scaler.cropToJPEG(sourceFrame, objectDetections, {
+            maxWidth: detectionMaxWidth,
+            padding: 0.3,
+            minCrop: detectionMinCrop,
+            quality: detectionQuality,
+        });
         for (const crop of objectCrops) {
             const detection = objectDetections[crop.index];
             if (detection) {
@@ -1772,24 +1771,16 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
         }
         if (results.face?.detections) {
-            const faceCrops = await this.frameScaler.cropToJPEG(rawFrame, results.face.detections, { padding: 0.1 });
+            const faceCrops = await scaler.cropToJPEG(sourceFrame, results.face.detections, {
+                maxWidth: ATTRIBUTE_THUMB_MAX_WIDTH,
+                padding: attributePadding,
+                minCrop: ATTRIBUTE_THUMB_MIN_CROP,
+            });
             for (const crop of faceCrops) {
                 const detection = results.face.detections[crop.index];
                 if (detection) {
-                    // Debug: save face thumbnail (cropped from rawFrame with transformed coords) for verification
-                    // try {
-                    //   const ts = Date.now();
-                    //   writeFileSync(`/tmp/face_thumb_${ts}_${crop.index}.jpg`, crop.jpeg);
-                    //   this.logger.debug(
-                    //     `[face-debug] saved face thumbnail from rawFrame: /tmp/face_thumb_${ts}_${crop.index}.jpg ` +
-                    //     `box=(${detection.box.x.toFixed(4)},${detection.box.y.toFixed(4)},${detection.box.width.toFixed(4)},${detection.box.height.toFixed(4)}) ` +
-                    //     `rawFrame=${rawFrame.width}x${rawFrame.height}`,
-                    //   );
-                    // } catch {
-                    //   /* ignore */
-                    // }
-                    // Set thumbnail on the detection itself so enrichSegment can inline it
-                    // for unknown faces (needed for face store persistence).
+                    // Inline on the detection so enrichSegment can persist unknown
+                    // faces to the face store.
                     detection.thumbnail ??= crop.jpeg;
                     thumbnails.push({
                         label: `face:${detection.identity ?? 'unknown'}`,
@@ -1802,7 +1793,11 @@ let DetectionCoordinator = class DetectionCoordinator {
             }
         }
         if (results.licensePlate?.detections) {
-            const plateCrops = await this.frameScaler.cropToJPEG(rawFrame, results.licensePlate.detections, { padding: 0.1 });
+            const plateCrops = await scaler.cropToJPEG(sourceFrame, results.licensePlate.detections, {
+                maxWidth: ATTRIBUTE_THUMB_MAX_WIDTH,
+                padding: attributePadding,
+                minCrop: ATTRIBUTE_THUMB_MIN_CROP,
+            });
             for (const crop of plateCrops) {
                 const detection = results.licensePlate.detections[crop.index];
                 if (detection) {
@@ -1818,7 +1813,12 @@ let DetectionCoordinator = class DetectionCoordinator {
         }
         if (results.classifiers) {
             for (const classifierResult of Object.values(results.classifiers)) {
-                const clsCrops = await this.frameScaler.cropToJPEG(rawFrame, classifierResult.detections);
+                const clsCrops = await scaler.cropToJPEG(sourceFrame, classifierResult.detections, {
+                    maxWidth: detectionMaxWidth,
+                    padding: 0.3,
+                    minCrop: detectionMinCrop,
+                    quality: detectionQuality,
+                });
                 for (const crop of clsCrops) {
                     const detection = classifierResult.detections[crop.index];
                     if (detection) {