@camera.ui/sdk 0.0.21 → 0.0.22

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 type CameraType = 'camera' | 'doorbell';
 /**
  * Detection zone intersection type.
- * - `intersect`: Trigger when object touches the zone boundary
+ * - `intersect`: Trigger when object overlaps the zone at all
  * - `contain`: Trigger only when object is fully inside the zone
  */
 type ZoneType = 'intersect' | 'contain';
@@ -108,7 +108,7 @@ interface CameraInputSettings {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -469,7 +469,7 @@ interface JsonBaseSchemaWithoutCallbacks<T extends string | string[] | number |
 interface JsonBaseSchema<T extends string | string[] | number | number[] | boolean | boolean[] = any> extends JsonBaseSchemaWithoutCallbacks<T> {
     /** Whether to persist this field to storage */
     store?: boolean;
-    /** Callback when value changes */
+    /** Callback after a write. `setValue` fires it whether or not the value changed; `setConfig` fires it only for keys that changed. */
     onSet?: (newValue: any, oldValue: any) => Promise<void>;
     /** Callback to get computed value */
     onGet?: () => Promise<any>;
@@ -707,8 +707,9 @@ interface DeviceStorage<T extends Record<string, any> = Record<string, any>> {
     /**
      * Get a configuration value.
      *
-     * Resolves in order: the schema's `onGet` callback (if any), then the stored
-     * value, then the schema default, then the provided default.
+     * If the schema declares an `onGet` callback, its result is returned as-is,
+     * with no fallback. Otherwise resolves in order: the stored value, then the
+     * schema default, then the provided default.
      *
      * @param key - Configuration key
      *
@@ -924,7 +925,7 @@ interface ModelSpec {
     input: VideoInputSpec;
     /** Labels emitted by an upstream object detector that activate this detector (e.g. `['person']` for face detection). */
     triggerLabels: DetectionLabel[];
-    /** Embedding model identifier for face recognition. */
+    /** Embedding model identifier. Required for face recognition and for CLIP: embeddings are stored and matched under this id. */
     embeddingModel?: string;
 }
 /**
@@ -1461,8 +1462,9 @@ declare abstract class FaceDetectorSensor<TStorage extends object = Record<strin
     /** Declares the expected input dimensions and trigger labels. The backend scales frames to match. */
     abstract get modelSpec(): ModelSpec;
     /**
-     * Detect faces in batch. Each frame is a pre-cropped, pre-scaled person
-     * region produced by the upstream object detector. Must return exactly one
+     * Detect faces in batch. Each frame is pre-scaled to `modelSpec.input`:
+     * normally a person region cropped by the upstream object detector, but the
+     * whole scene when no decoded frame is available. Must return exactly one
      * FaceResult per input frame, in the same order.
      */
     abstract detectFaces(frames: VideoFrameData[]): Promise<FaceResult[]>;
@@ -2114,7 +2116,7 @@ declare class MotionSensor<TStorage extends object = Record<string, any>> extend
 }
 /** Return type for {@link MotionDetectorSensor.detectMotion}. */
 interface MotionResult {
-    /** Whether motion is detected in this frame. */
+    /** Whether motion is detected in this frame. Ignored by the backend, which re-derives it from the detections. */
     detected: boolean;
     /** Detections emitted for this frame. */
     detections: Detection[];
@@ -2123,7 +2125,9 @@ interface MotionResult {
  * Motion detector that receives video frames from the backend pipeline.
  * Extend this class and implement {@link detectMotion} to analyze frames
  * for motion. The backend calls `detectMotion()` at the configured frame
- * interval and applies the returned result to the sensor.
+ * interval, zone-filters the returned detections and applies them.
+ * `detected` is re-derived from the surviving detections, so a result with
+ * no detections reports no motion.
  */
 declare abstract class MotionDetectorSensor<TStorage extends object = Record<string, any>> extends MotionSensor<TStorage> {
     _requiresFrames: boolean;
@@ -2464,12 +2468,13 @@ declare class PTZControl<TStorage extends object = Record<string, any>> extends
      * Continuous-move command. Override to drive hardware and call
      * `await super.setVelocity(value)` after success to sync the SDK state.
      *
-     * @param value - Per-axis speeds in `[-1, 1]`, or `undefined` to stop.
+     * @param value - Per-axis speeds in `[-1, 1]`. Stop is zero on every axis.
+     * `undefined` is ignored and the published `velocity` keeps its last value.
      *
      * @example
      * ```ts
      * await ptz.setVelocity({ panSpeed: 0.5, tiltSpeed: 0, zoomSpeed: 0 });
-     * await ptz.setVelocity(undefined); // stop
+     * await ptz.setVelocity({ panSpeed: 0, tiltSpeed: 0, zoomSpeed: 0 }); // stop
      * ```
      */
     setVelocity(value: PTZDirection | undefined): Promise<void>;
@@ -2492,7 +2497,8 @@ declare class PTZControl<TStorage extends object = Record<string, any>> extends
      * Preset-move command. Override to drive hardware and call
      * `await super.setTargetPreset(value)` after success to sync the SDK state.
      *
-     * @param value - Preset name to move to, or `undefined` to clear.
+     * @param value - Preset name to move to. `undefined` is ignored and the
+     * published `targetPreset` keeps its last value.
      *
      * @example
      * ```ts
@@ -2535,7 +2541,7 @@ declare class PTZControl<TStorage extends object = Record<string, any>> extends
      * Cross-process consumer entry point. Dispatches writable properties
      * to semantic methods so plugin overrides (hardware actions) are honored.
      * `moving` and `presets` are observed/discovered state and not externally writable;
-     * only `Position`, `Velocity`, and `TargetPreset` may be set.
+     * only `Position`, `Velocity`, `TargetPreset`, and `RelativeMove` may be set.
      *
      * @param property - Property name to write.
      *
@@ -3133,7 +3139,7 @@ declare abstract class Sensor<TProperties extends object, TStorage extends objec
     /**
      * Get a read-only snapshot of all property values.
      *
-     * @returns Frozen view of every property currently held by the sensor.
+     * @returns Shallow copy of every property currently held by the sensor.
      *
      * @example
      * ```ts
@@ -3214,8 +3220,9 @@ declare abstract class Sensor<TProperties extends object, TStorage extends objec
      * override can safely access `this.cameraId`, `this.storage`, and publish
      * properties via the semantic helper methods.
      *
-     * Errors thrown here are caught and logged — they will NOT break assignment
-     * bookkeeping. If your work can fail, handle it inside the override.
+     * Errors thrown here are caught and swallowed, not logged. They will NOT
+     * break assignment bookkeeping, but nothing surfaces them either. If your
+     * work can fail, handle it inside the override.
      *
      * Paired 1:1 with `onDeassigned` — for every `onAssigned` call there is
      * exactly one matching `onDeassigned` later (on deassignment or cleanup).
@@ -3356,7 +3363,7 @@ interface DetectionLine {
 }
 /**
  * Detection zone configuration.
- * Defines areas for detection filtering or privacy masking.
+ * Defines areas that restrict or drop detections.
  */
 interface DetectionZone {
     /** Zone display name */
@@ -3369,7 +3376,7 @@ interface DetectionZone {
     filter: ZoneFilter;
     /** Labels to filter (empty = all labels) */
     labels: DetectionLabel[];
-    /** Whether this is a privacy mask (blur/block area) */
+    /** Whether this is an ignore zone: detections fully inside it are dropped. */
     isPrivacyMask: boolean;
     /** Zone display color (hex) */
     color: string;
@@ -3387,7 +3394,7 @@ interface MotionDetectionSettings {
  * Object detection settings.
  */
 interface ObjectDetectionSettings {
-    /** Minimum confidence threshold (0-1) */
+    /** Minimum confidence threshold (0.3 - 1.0) */
     confidence: number;
     /** Suppress events from objects that stay stationary across events (e.g. parked cars). Defaults to true. */
     suppressStatic?: boolean;
@@ -3422,11 +3429,11 @@ interface PtzAutotrackSettings {
      */
     trackingSpeed: number;
     /**
-     * Motion prediction: aim this many detection-frames ahead along the target's
-     * measured velocity so a moving target is followed without lag. 0 disables
-     * prediction. Range 0 - 6.
+     * Motion prediction: aim this many milliseconds ahead along the target's
+     * measured velocity, covering the time the camera needs to move and settle.
+     * 0 disables prediction. Range 0 - 4000.
      */
-    leadFrames: number;
+    leadMs: number;
     /**
      * Camera pan-rate calibration — assumed pan travel at full motor speed, in
      * normalized frame-widths per second. Lower it if the camera stops short of
@@ -3919,7 +3926,7 @@ interface CameraInput {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -4089,7 +4096,6 @@ interface Camera extends BaseCamera {
  * the host) and emits a log entry at the corresponding severity:
  *
  *   - log:       general informational message (default level).
- *   - info:      same as log; informational message.
  *   - warn:      potential problem that does not stop execution.
  *   - error:     a failure or unexpected condition.
  *   - success:   confirmation of a completed operation.
@@ -4161,7 +4167,7 @@ interface EventDetection {
     maxCount: number;
     /** Bounding box of the highest-confidence detection (normalized 0–1) */
     box?: BoundingBox;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Only present on 'segment-start' and 'segment-end' messages, and omitted when it is the same image as the segment thumbnail. */
     thumbnail?: Uint8Array;
     /** Object tracker ID (links this detection across frames) */
     trackId?: number;
@@ -4178,7 +4184,7 @@ interface EventAttribute {
     label: string;
     /** Detection confidence (0-1) */
     confidence?: number;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end' messages, and on 'segment-update' for unknown faces. */
     thumbnail?: Uint8Array;
     /** Face embedding vector for unknown face persistence. Only present for face attributes. */
     embedding?: number[];
@@ -4199,7 +4205,7 @@ interface EventSegment {
     firstSeen: number;
     /** Segment end time (Unix ms) */
     lastSeen: number;
-    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events. */
+    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-start' and 'segment-end' messages, plus once on a 'segment-update' if the start message had none. */
     thumbnail?: Uint8Array;
     /** Object detections in this segment */
     detections: EventDetection[];
@@ -4455,17 +4461,17 @@ interface CameraDevice {
      * @param sensorId - ID of sensor to remove
      */
     removeSensor(sensorId: string): Promise<void>;
-    /** Observable for sensor additions. Emits { sensorId, sensorType } when a sensor from another plugin is added. */
+    /** Observable for sensor additions. Emits for this plugin's own sensors and for other plugins' sensors whose type is listed in `contract.consumes`, also when such a sensor is activated for this camera. */
     readonly onSensorAdded: Observable<{
         sensorId: string;
         sensorType: SensorType;
     }>;
-    /** Observable for sensor removals. Emits { sensorId, sensorType } when a sensor from another plugin is removed. */
+    /** Observable for sensor removals. Emits for this plugin's own sensors and for other plugins' sensors on this camera, also when a sensor is deactivated for this camera. */
     readonly onSensorRemoved: Observable<{
         sensorId: string;
         sensorType: SensorType;
     }>;
-    /** Observable for detection events (start/update/end). Thumbnails in segments are only populated on 'end' events. */
+    /** Observable for detection events (start/update/end/segment-*). Segments are only present on 'segment-*' messages; thumbnails are populated on 'segment-start' and 'segment-end'. */
     readonly onDetectionEvent: Observable<{
         type: DetectionEventType;
         event: DetectionEvent;
@@ -4991,9 +4997,10 @@ interface Notification {
      */
     severity?: Severity;
     /**
-     * Collapse-key for dedup at both manager and notifier level (e.g.
-     * 'motion:cam-1' — multiple events with the same tag inside the throttle
-     * window collapse into one notification on the device).
+     * Collapse-key (e.g. 'motion:cam-1'). The host uses it to replace an older
+     * entry with the same tag in the in-app notification list. Delivery is not
+     * throttled: every publish is sent. Notifiers may map it to a platform
+     * collapse-id.
      */
     tag?: string;
     /** Optional inline JPEG attached to the notification. */
@@ -5324,9 +5331,8 @@ type PluginInterfaces = Partial<MotionDetectionInterface & ObjectDetectionInterf
 
 /**
  * Core manager event payload.
- * Emitted when a core system event occurs (e.g. cloud account changes,
- * remote-server availability, plugin lifecycle changes). Subscribe via
- * `coreManager.onEvent` to react to system-level state changes.
+ * The host currently publishes one event type, 'cloudAccountChanged'.
+ * Subscribe via `coreManager.onEvent` to react to it.
  */
 interface CoreManagerEvent {
     /** Event type identifier (e.g. 'cloudAccountChanged'). */
@@ -5338,8 +5344,8 @@ interface CoreManagerEvent {
  * Core manager interface for system-level operations.
  *
  * Provides access to cross-cutting services like the FFmpeg binary path,
- * server addresses, HMAC signing for cloud requests, inter-plugin lookup,
- * and a stream of core system events.
+ * server addresses, the cloud server id, inter-plugin lookup, and a stream
+ * of core system events.
  *
  * Accessed via `api.coreManager` in plugins.
  *
@@ -5386,7 +5392,9 @@ interface CoreManager {
      */
     getCloudServerId(): Promise<string>;
     /**
-     * Get all active plugins that implement a specific interface.
+     * Get all installed, enabled plugins that implement a specific interface.
+     * Plugins the admin disabled are excluded. A returned plugin may still be
+     * starting up or may have crashed, so a call into one can fail.
      *
      * @param interfaceName - Name of the plugin interface (e.g., 'ClipDetection')
      *

package/dist/internal/index.d.ts

@@ -45,7 +45,7 @@ interface ModelSpec {
     input: VideoInputSpec;
     /** Labels emitted by an upstream object detector that activate this detector (e.g. `['person']` for face detection). */
     triggerLabels: DetectionLabel[];
-    /** Embedding model identifier for face recognition. */
+    /** Embedding model identifier. Required for face recognition and for CLIP: embeddings are stored and matched under this id. */
     embeddingModel?: string;
 }
 
@@ -608,7 +608,7 @@ interface CameraInputSettings {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -732,7 +732,7 @@ interface EventDetection {
     maxCount: number;
     /** Bounding box of the highest-confidence detection (normalized 0–1) */
     box?: BoundingBox;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Only present on 'segment-start' and 'segment-end' messages, and omitted when it is the same image as the segment thumbnail. */
     thumbnail?: Uint8Array;
     /** Object tracker ID (links this detection across frames) */
     trackId?: number;
@@ -749,7 +749,7 @@ interface EventAttribute {
     label: string;
     /** Detection confidence (0-1) */
     confidence?: number;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end' messages, and on 'segment-update' for unknown faces. */
     thumbnail?: Uint8Array;
     /** Face embedding vector for unknown face persistence. Only present for face attributes. */
     embedding?: number[];
@@ -770,7 +770,7 @@ interface EventSegment {
     firstSeen: number;
     /** Segment end time (Unix ms) */
     lastSeen: number;
-    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events. */
+    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-start' and 'segment-end' messages, plus once on a 'segment-update' if the start message had none. */
     thumbnail?: Uint8Array;
     /** Object detections in this segment */
     detections: EventDetection[];

package/dist/sensor/base.js

@@ -179,7 +179,7 @@ export class Sensor {
     /**
      * Get a read-only snapshot of all property values.
      *
-     * @returns Frozen view of every property currently held by the sensor.
+     * @returns Shallow copy of every property currently held by the sensor.
      *
      * @example
      * ```ts
@@ -305,8 +305,9 @@ export class Sensor {
      * override can safely access `this.cameraId`, `this.storage`, and publish
      * properties via the semantic helper methods.
      *
-     * Errors thrown here are caught and logged — they will NOT break assignment
-     * bookkeeping. If your work can fail, handle it inside the override.
+     * Errors thrown here are caught and swallowed, not logged. They will NOT
+     * break assignment bookkeeping, but nothing surfaces them either. If your
+     * work can fail, handle it inside the override.
      *
      * Paired 1:1 with `onDeassigned` — for every `onAssigned` call there is
      * exactly one matching `onDeassigned` later (on deassignment or cleanup).

package/dist/sensor/motion.js

@@ -111,7 +111,9 @@ export class MotionSensor extends Sensor {
  * Motion detector that receives video frames from the backend pipeline.
  * Extend this class and implement {@link detectMotion} to analyze frames
  * for motion. The backend calls `detectMotion()` at the configured frame
- * interval and applies the returned result to the sensor.
+ * interval, zone-filters the returned detections and applies them.
+ * `detected` is re-derived from the surviving detections, so a result with
+ * no detections reports no motion.
  */
 export class MotionDetectorSensor extends MotionSensor {
     _requiresFrames = true;

package/dist/sensor/ptz.js

@@ -90,12 +90,13 @@ export class PTZControl extends Sensor {
      * Continuous-move command. Override to drive hardware and call
      * `await super.setVelocity(value)` after success to sync the SDK state.
      *
-     * @param value - Per-axis speeds in `[-1, 1]`, or `undefined` to stop.
+     * @param value - Per-axis speeds in `[-1, 1]`. Stop is zero on every axis.
+     * `undefined` is ignored and the published `velocity` keeps its last value.
      *
      * @example
      * ```ts
      * await ptz.setVelocity({ panSpeed: 0.5, tiltSpeed: 0, zoomSpeed: 0 });
-     * await ptz.setVelocity(undefined); // stop
+     * await ptz.setVelocity({ panSpeed: 0, tiltSpeed: 0, zoomSpeed: 0 }); // stop
      * ```
      */
     async setVelocity(value) {
@@ -122,7 +123,8 @@ export class PTZControl extends Sensor {
      * Preset-move command. Override to drive hardware and call
      * `await super.setTargetPreset(value)` after success to sync the SDK state.
      *
-     * @param value - Preset name to move to, or `undefined` to clear.
+     * @param value - Preset name to move to. `undefined` is ignored and the
+     * published `targetPreset` keeps its last value.
      *
      * @example
      * ```ts
@@ -173,7 +175,7 @@ export class PTZControl extends Sensor {
      * Cross-process consumer entry point. Dispatches writable properties
      * to semantic methods so plugin overrides (hardware actions) are honored.
      * `moving` and `presets` are observed/discovered state and not externally writable;
-     * only `Position`, `Velocity`, and `TargetPreset` may be set.
+     * only `Position`, `Velocity`, `TargetPreset`, and `RelativeMove` may be set.
      *
      * @param property - Property name to write.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camera.ui/sdk",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "camera.ui sdk",
   "exports": {
     ".": {