@camera.ui/sdk 0.0.4 → 0.0.5

package/package.json

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

package/CHANGELOG.md

@@ -1,8 +0,0 @@
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [X.X.X] - ???
-
-- Initial Release

package/CONTRIBUTING.md

@@ -1 +0,0 @@
-# Contributing

package/LICENSE.md

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2023-2026 seydx <hi@seydx.dev>
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/docs/.vitepress/config.ts

@@ -1,77 +0,0 @@
-import { createRequire } from 'node:module';
-import { defineConfig } from 'vitepress';
-
-const require = createRequire(import.meta.url);
-const typedocSidebar = require('../api/typedoc-sidebar.json');
-
-// https://vitepress.dev/reference/site-config
-export default defineConfig({
-  srcDir: '.',
-  base: '/sdk/node/',
-  title: 'camera.ui Node SDK',
-  description: 'TypeScript SDK for building camera.ui plugins',
-  lastUpdated: true,
-  head: [
-    ['link', { rel: 'icon', type: 'image/x-icon', sizes: '32x32', href: '/sdk/node/favicon.ico' }],
-    ['link', { rel: 'icon', type: 'image/x-icon', sizes: '16x16', href: '/sdk/node/favicon-16.ico' }],
-    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/sdk/node/apple-touch-icon.png' }],
-    ['meta', { name: 'theme-color', content: '#df2a4c' }],
-  ],
-  themeConfig: {
-    logo: '/logo.svg',
-
-    // typedocSidebar entries are alphabetical:
-    //   [0] camera, [1] manager, [2] observable, [3] plugin,
-    //   [4] sensor, [5] storage, [6] types
-    sidebar: [
-      {
-        text: 'Plugin API',
-        items: typedocSidebar[3].items,
-      },
-      {
-        text: 'Camera',
-        items: typedocSidebar[0].items,
-      },
-      {
-        text: 'Sensors',
-        items: typedocSidebar[4].items,
-      },
-      {
-        text: 'Storage & Schema',
-        items: typedocSidebar[5].items,
-      },
-      {
-        text: 'Manager',
-        items: typedocSidebar[1].items,
-      },
-      {
-        text: 'Observable',
-        items: typedocSidebar[2].items,
-      },
-      {
-        text: 'Types',
-        items: typedocSidebar[6].items,
-      },
-      {
-        text: 'Plugin Guide',
-        link: '/examples/getting-started',
-      },
-    ],
-
-    search: {
-      provider: 'local',
-    },
-
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/seydx/camera.ui' },
-      { icon: 'discord', link: 'https://discord.gg/bBGnGcbz8N' },
-      {
-        icon: {
-          svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path fill="currentColor" d="M20 10.04a2.18 2.18 0 0 0-3.7-1.55a10.7 10.7 0 0 0-5.79-1.83l.99-4.65l3.23.69a1.55 1.55 0 1 0 .15-.74l-3.59-.76a.37.37 0 0 0-.44.28l-1.1 5.18a10.74 10.74 0 0 0-5.87 1.83a2.19 2.19 0 1 0-2.41 3.59a4 4 0 0 0-.05.66c0 3.36 3.91 6.09 8.74 6.09s8.74-2.73 8.74-6.09a4 4 0 0 0-.05-.66A2.19 2.19 0 0 0 20 10.04m-15 1.56a1.56 1.56 0 1 1 1.56 1.56A1.56 1.56 0 0 1 5 11.6m8.71 4.13c-1.07.81-2.39 1.21-3.71 1.16a5.85 5.85 0 0 1-3.71-1.16a.4.4 0 1 1 .55-.59A4.94 4.94 0 0 0 10 16.1a4.94 4.94 0 0 0 3.16-.96a.41.41 0 0 1 .57.04a.41.41 0 0 1-.02.55m-.16-2.55a1.56 1.56 0 1 1 1.56-1.56a1.56 1.56 0 0 1-1.55 1.56z"/></svg>',
-        },
-        link: 'https://www.reddit.com/r/cameraui/',
-        ariaLabel: 'Reddit',
-      },
-    ],
-  },
-});

package/docs/.vitepress/theme/index.ts

@@ -1,5 +0,0 @@
-import DefaultTheme from 'vitepress/theme';
-
-import './style.css';
-
-export default DefaultTheme;

package/docs/.vitepress/theme/style.css

@@ -1,117 +0,0 @@
-@import 'vitepress/dist/client/theme-default/styles/vars.css';
-
-/* camera.ui brand colors — mirror ui/src/plugins/preset.ts */
-:root {
-  --cui-primary-50: #fdf4f6;
-  --cui-primary-100: #f7ccd4;
-  --cui-primary-200: #f1a3b2;
-  --cui-primary-300: #eb7b90;
-  --cui-primary-400: #e5526e;
-  --cui-primary-500: #df2a4c;
-  --cui-primary-600: #be2441;
-  --cui-primary-700: #9c1d35;
-  --cui-primary-800: #7b172a;
-  --cui-primary-900: #59111e;
-  --cui-primary-950: #380b13;
-}
-
-:root {
-  --vp-c-brand-1: var(--cui-primary-500);
-  --vp-c-brand-2: var(--cui-primary-600);
-  --vp-c-brand-3: var(--cui-primary-700);
-  --vp-c-brand-soft: rgba(223, 42, 76, 0.14);
-
-  --vp-c-default-1: var(--vp-c-gray-1);
-  --vp-c-default-2: var(--vp-c-gray-2);
-  --vp-c-default-3: var(--vp-c-gray-3);
-  --vp-c-default-soft: var(--vp-c-gray-soft);
-
-  --vp-button-brand-border: transparent;
-  --vp-button-brand-text: #ffffff;
-  --vp-button-brand-bg: var(--cui-primary-500);
-  --vp-button-brand-hover-border: transparent;
-  --vp-button-brand-hover-text: #ffffff;
-  --vp-button-brand-hover-bg: var(--cui-primary-600);
-  --vp-button-brand-active-border: transparent;
-  --vp-button-brand-active-text: #ffffff;
-  --vp-button-brand-active-bg: var(--cui-primary-700);
-
-  --vp-home-hero-name-color: transparent;
-  --vp-home-hero-name-background: linear-gradient(
-    135deg,
-    var(--cui-primary-500) 0%,
-    var(--cui-primary-700) 100%
-  );
-  --vp-home-hero-image-background-image: linear-gradient(
-    135deg,
-    rgba(223, 42, 76, 0.32) 0%,
-    rgba(123, 23, 42, 0.32) 100%
-  );
-  --vp-home-hero-image-filter: blur(56px);
-
-  --vp-custom-block-tip-border: transparent;
-  --vp-custom-block-tip-text: var(--cui-primary-700);
-  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
-  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
-}
-
-/* dark surface palette mirrors ui preset.ts (neutral grey, not slate) */
-.dark {
-  --cui-surface-0: #ffffff;
-  --cui-surface-50: #f5f5f5;
-  --cui-surface-100: #d1d1d1;
-  --cui-surface-200: #adadad;
-  --cui-surface-300: #898989;
-  --cui-surface-400: #646464;
-  --cui-surface-500: #404040;
-  --cui-surface-600: #363636;
-  --cui-surface-700: #2d2d2d;
-  --cui-surface-800: #232323;
-  --cui-surface-850: #1d1d1d;
-  --cui-surface-900: #1a1a1a;
-  --cui-surface-925: #161616;
-  --cui-surface-950: #101010;
-  --cui-surface-1000: #0d0d0d;
-
-  --vp-c-brand-1: var(--cui-primary-400);
-  --vp-c-brand-2: var(--cui-primary-300);
-  --vp-c-brand-3: var(--cui-primary-200);
-  --vp-c-brand-soft: rgba(229, 82, 110, 0.16);
-
-  --vp-c-bg: var(--cui-surface-900);
-  --vp-c-bg-alt: var(--cui-surface-950);
-  --vp-c-bg-elv: var(--cui-surface-800);
-  --vp-c-bg-soft: var(--cui-surface-850);
-
-  --vp-c-divider: var(--cui-surface-800);
-  --vp-c-gutter: var(--cui-surface-950);
-  --vp-c-border: var(--cui-surface-700);
-
-  --vp-c-default-1: var(--cui-surface-800);
-  --vp-c-default-2: var(--cui-surface-700);
-  --vp-c-default-3: var(--cui-surface-600);
-  --vp-c-default-soft: rgba(64, 64, 64, 0.4);
-
-  --vp-c-text-1: rgba(255, 255, 255, 0.92);
-  --vp-c-text-2: rgba(255, 255, 255, 0.66);
-  --vp-c-text-3: rgba(255, 255, 255, 0.42);
-
-  --vp-code-bg: var(--cui-surface-925);
-  --vp-code-block-bg: var(--cui-surface-925);
-
-  --vp-button-brand-text: #ffffff;
-  --vp-button-brand-bg: var(--cui-primary-500);
-  --vp-button-brand-hover-bg: var(--cui-primary-400);
-  --vp-button-brand-active-bg: var(--cui-primary-600);
-
-  --vp-custom-block-tip-text: var(--cui-primary-200);
-}
-
-/* Pull search/box accents in line with brand */
-.dark .DocSearch {
-  --docsearch-primary-color: var(--cui-primary-400);
-}
-
-.DocSearch {
-  --docsearch-primary-color: var(--cui-primary-500);
-}

package/docs/index.md

@@ -1,16 +0,0 @@
-# camera.ui Node SDK
-
-TypeScript SDK for building plugins that extend [camera.ui](https://github.com/seydx/camera.ui) — add cameras, run motion / object / face / license-plate / audio detection, deliver notifications, and more.
-
-## Install
-
-```bash
-npm install @camera.ui/sdk
-```
-
-## Next steps
-
-- **[Plugin Guide](/examples/getting-started)** — everything you need to ship a Node plugin in one page: contract, lifecycle, sensors, storage, optional interfaces.
-- **[API Reference](/api/)** — module-by-module reference auto-generated from JSDoc.
-
-For complete production plugins to study, see [`plugins/`](https://github.com/seydx/camera.ui/tree/main/plugins) in the camera.ui repo.

package/docs/public/logo.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 233.63 233.63"><defs><style>.cls-1{fill:url(#dark_wine);}.cls-2{fill:url(#light_wine);}.cls-3{fill:none;stroke:#000;stroke-miterlimit:10;opacity:0;}.cls-4{fill:#c5c6c8;}.cls-5{fill:#1a1e21;stroke:#3a3a3a;stroke-width:2px;}.cls-6{fill:#fff;}</style><linearGradient id="dark_wine" x1="87.36" y1="158.67" x2="87.36" y2="59.85" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#730000"/><stop offset="0.49" stop-color="#a51733"/></linearGradient><linearGradient id="light_wine" x1="113.06" y1="197.59" x2="113.06" y2="80.87" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#f44a6b"/><stop offset="0.28" stop-color="#df294c"/></linearGradient></defs><g id="CameraUI_U"><path id="U_Left" class="cls-1" d="M47.05,119.47s7.58,16,14.12,23.42a45.28,45.28,0,0,0,16.37,11.86A49.46,49.46,0,0,0,99,158.62c9.43-.46,20.55-3.87,29.24-11.86-3.9,2.5-9.87,5.1-15.9,4.77a25.63,25.63,0,0,1-18.38-9.09c-9.39-10.31-7.62-28.35-7.75-32.68-.35-11.42.77-21.92-1.76-36.19-.46-2.64-1.79-5.19-4.55-8-1.83-1.86-8.4-5.75-13.42-5.74-7.31,0-12.95,3.71-15.38,7.84-2,3.41-3.06,4.22-4.23,25.08a217.23,217.23,0,0,0,.22,26.76Z" transform="translate(0.5 0.5)"/><path id="U_Right" class="cls-2" d="M144.12,89.6a16.24,16.24,0,0,1,4.06-4.9c4.16-3.4,9-3.67,10.92-3.82a19.7,19.7,0,0,1,12.53,4.58c1.19,1,6.11,5.58,7.13,17.29.73,8.51,3.31,65.93-37,87.14-4.22,2.22-18,9.25-35.66,7.38a62.43,62.43,0,0,1-20.8-6.11,65.8,65.8,0,0,1-18.89-14.23c-20.21-21.67-19.36-57.46-19.36-57.46s7.58,16,14.12,23.42a45.28,45.28,0,0,0,16.37,11.86A49.46,49.46,0,0,0,99,158.62c11.66-.57,25.93-5.64,35-18.32C143.52,126.8,138.46,100.51,144.12,89.6Z" transform="translate(0.5 0.5)"/></g><g id="CameraUI_Lens"><circle id="ellipse" class="cls-3" cx="116.81" cy="116.81" r="116.31"/><g id="lens"><circle id="lens_bg" class="cls-4" cx="159.13" cy="58.39" r="18.66"/><path id="lens_inner" class="cls-5" d="M169.64,58.31a11,11,0,1,1-22,0c0-6.08,4.93-11.86,11-11.86S169.64,52.23,169.64,58.31Z" transform="translate(0.5 0.5)"/><g id="reflections"><ellipse id="dot_1" class="cls-6" cx="174.36" cy="53.69" rx="1.84" ry="1.42"/><ellipse id="dot_2" class="cls-6" cx="174.36" cy="57.08" rx="1.84" ry="1.42"/><ellipse id="dot_3" class="cls-6" cx="174.36" cy="60.46" rx="1.84" ry="1.42"/><circle id="dot_4" class="cls-6" cx="164.09" cy="63.77" r="1.66"/><path id="wide_1" class="cls-6" d="M156.63,48.9c-1.07-.88-5.52,3.09-6.31,5.43a1.53,1.53,0,0,0,0,1.26c.43.69,1.73.61,2.19.54,2.68-.44,4.71-4.09,4.8-4.37A3.21,3.21,0,0,0,156.63,48.9Z" transform="translate(0.5 0.5)"/></g></g></g></svg>

package/examples/README.md

@@ -1,7 +0,0 @@
-# Plugin Guide
-
-Everything you need to ship a camera.ui plugin in one page: contract, lifecycle, sensors, storage, optional interfaces (discovery, notifier, detection), and inter-plugin communication.
-
-[Read the guide →](./getting-started.md)
-
-For complete production plugins to read alongside, see [`plugins/`](https://github.com/seydx/camera.ui/tree/main/plugins) in the camera.ui repo.

package/examples/getting-started.md

@@ -1,535 +0,0 @@
-# Plugin Guide
-
-A camera.ui plugin is a Node package the host loads at runtime to extend cameras with new capabilities — a detection model, a vendor camera integration, a notifier, a smart-home bridge. This guide is the single reference for shipping one. You should be comfortable with TypeScript and have the SDK installed (`npm install @camera.ui/sdk`).
-
-## 1. Plugin anatomy
-
-A plugin is a folder with two files the host expects:
-
-- `contract.ts` — the manifest. A static object describing what the plugin is.
-- `index.ts` — the runtime. A class extending `BasePlugin`, exported as `default`.
-
-The minimal compilable plugin:
-
-```ts
-// contract.ts
-import { PluginRole } from '@camera.ui/sdk';
-import type { PluginContract } from '@camera.ui/sdk';
-
-export const contract: PluginContract = {
-  name: 'My Plugin',
-  role: PluginRole.SensorProvider,
-  provides: [],
-  consumes: [],
-  interfaces: [],
-};
-
-export default contract;
-```
-
-```ts
-// index.ts
-import { BasePlugin } from '@camera.ui/sdk';
-import type { CameraDevice } from '@camera.ui/sdk';
-
-export default class MyPlugin extends BasePlugin {
-  async configureCameras(_cameras: CameraDevice[]): Promise<void> {}
-  async onCameraAdded(_camera: CameraDevice): Promise<void> {}
-  async onCameraReleased(_cameraId: string): Promise<void> {}
-}
-```
-
-The host instantiates the class with three arguments: a `LoggerService`, a `PluginAPI`, and a typed `DeviceStorage`. Everything else — sensors, discovery, schemas — is opt-in.
-
-## 2. The contract
-
-`PluginContract` is the static manifest the host reads before starting the plugin. The fields:
-
-- **`name`** — stable identifier; doubles as log prefix and storage namespace.
-- **`role`** — what the plugin does at the highest level (see table below).
-- **`provides`** — sensor types the plugin attaches to cameras (e.g. `[SensorType.Motion]`).
-- **`consumes`** — sensor types the plugin reads from other plugins.
-- **`interfaces`** — capability flags (`DiscoveryProvider`, `Notifier`, detection types, …).
-
-| Role | Use when |
-| --- | --- |
-| `SensorProvider` | You add detection or smart-home sensors to existing cameras (motion plugin, classifier, contact sensor). |
-| `CameraController` | You bring your own cameras and own their streams (RTSP, ONVIF, vendor SDK), but produce no sensors. |
-| `CameraAndSensorProvider` | You bring your own cameras AND want to attach sensors to them. Most vendor integrations land here. |
-| `Hub` | Cloud-service integration that owns its cameras end-to-end via a vendor account, OR a bridge plugin that consumes other plugins' sensors and forwards them to an external system (HomeKit, MQTT, automations) or implements a `Notifier`. |
-
-Examples:
-
-```ts
-// Detection plugin attaching motion sensors
-{ name: 'My Motion', role: PluginRole.SensorProvider,
-  provides: [SensorType.Motion], consumes: [], interfaces: [PluginInterface.MotionDetection] }
-
-// ONVIF-style integration with discovery
-{ name: 'ACME Cameras', role: PluginRole.CameraAndSensorProvider,
-  provides: [SensorType.Motion], consumes: [], interfaces: [PluginInterface.DiscoveryProvider] }
-
-// HomeKit bridge consuming sensor state from other plugins
-{ name: 'HomeKit Bridge', role: PluginRole.Hub,
-  provides: [], consumes: [SensorType.Motion, SensorType.Doorbell], interfaces: [] }
-```
-
-## 3. The plugin class
-
-`BasePlugin<TStorage>` is generic over your storage shape so `this.storage.values.X` is typed. Its constructor takes the three host-injected dependencies in order: `logger`, `api`, `storage`.
-
-```ts
-import { API_EVENT, BasePlugin } from '@camera.ui/sdk';
-import type { CameraDevice, DeviceStorage, LoggerService, PluginAPI } from '@camera.ui/sdk';
-
-interface MyStorage {
-  pollIntervalSec: number;
-}
-
-export default class MyPlugin extends BasePlugin<MyStorage> {
-  private state = new Map<string, MyCameraState>();
-
-  constructor(logger: LoggerService, api: PluginAPI, storage: DeviceStorage<MyStorage>) {
-    super(logger, api, storage);
-    this.api.on(API_EVENT.SHUTDOWN, () => this.shutdown());
-  }
-
-  async configureCameras(cameras: CameraDevice[]): Promise<void> {
-    for (const camera of cameras) await this.attach(camera);
-  }
-
-  async onCameraAdded(camera: CameraDevice): Promise<void> {
-    await this.attach(camera);
-  }
-
-  async onCameraReleased(cameraId: string): Promise<void> {
-    this.state.get(cameraId)?.dispose();
-    this.state.delete(cameraId);
-  }
-
-  private async attach(_camera: CameraDevice): Promise<void> { /* ... */ }
-  private shutdown(): void { /* drop timers, close sockets */ }
-}
-```
-
-Things to internalize:
-
-- `configureCameras` runs once at startup with the cameras already assigned to the plugin. A rejection aborts plugin startup.
-- `onCameraAdded` runs whenever the user assigns a new camera at runtime. Set up the same per-camera state as `configureCameras`.
-- `onCameraReleased` runs when a camera is removed or reassigned. Drop timers, close vendor sessions.
-- A `Map<cameraId, X>` is the conventional pattern for per-camera state — cheap to look up, trivial to clean up.
-- `API_EVENT.SHUTDOWN` fires when the host tears the plugin down (reload, server stop). Listeners must release everything synchronously enough for the host to stop the process. There is also `API_EVENT.FINISH_LAUNCHING`, fired once after `configureCameras` returns — useful for kicking off background work that should wait until the camera set is stable.
-
-## 4. Adding sensors to cameras
-
-A sensor is the unit of state the host (and other plugins) sees on a camera. Detection sensors push results from analyzing video; control sensors expose user-toggleable hardware (lights, sirens, locks); event sensors fire one-shot triggers (doorbell).
-
-For detection, subclass the matching `*DetectorSensor` and implement the detect method. The host pushes one frame at the configured rate:
-
-```ts
-import { MotionDetectorSensor } from '@camera.ui/sdk';
-import type { MotionResult, VideoFrameData } from '@camera.ui/sdk';
-
-class MyMotionSensor extends MotionDetectorSensor {
-  constructor() {
-    super('My Motion');
-  }
-
-  async detectMotion(_frame: VideoFrameData): Promise<MotionResult> {
-    // analyze frame.data, return detections
-    return { detected: false, detections: [] };
-  }
-}
-```
-
-Then attach it from the plugin's `attach()` helper:
-
-```ts
-const sensor = new MyMotionSensor();
-await camera.addSensor(sensor);
-```
-
-Other detector base classes follow the same shape but expect a batch (`frames: VideoFrameData[]`) and an abstract `modelSpec` getter: `ObjectDetectorSensor` (`detectObjects(frame)` — singular here), `FaceDetectorSensor.detectFaces(frames)`, `LicensePlateDetectorSensor.detectLicensePlates(frames)`, `AudioDetectorSensor.detectAudio(audio)`, `ClassifierDetectorSensor.detectClassifications(frames)`, `ClipDetectorSensor.detectEmbeddings(frames)`. Smart-home sensors expose semantic methods instead — e.g. `LightControl` gives you `setOn()` / `setOff()` / `setBrightness(value)`, `ContactSensor` gives you `setDetected(value)`, `DoorbellTrigger` gives you `trigger()`. You construct them, call `camera.addSensor`, and then call those methods when your hardware reports a change.
-
-The host removes sensors automatically when a camera is released. Your `onCameraReleased` hook just needs to drop your reference to it.
-
-## 5. Storage and configuration schema
-
-User-facing settings live in storage. Storage is split into two scopes — plugin-level and sensor-level — each with its own `storageSchema` getter that returns a JSON schema array. The host renders the schemas as form fields and persists the values; you read them via `storage.values.X`.
-
-**Plugin-level** schemas appear on the plugin's settings page. Override the getter on your `BasePlugin` subclass.
-
-```ts
-override get storageSchema(): JsonSchema[] {
-  return [
-    {
-      type: 'number',
-      key: 'pollIntervalSec',
-      title: 'Poll interval (seconds)',
-      description: 'How often background work runs',
-      defaultValue: 30,
-      minimum: 5,
-      maximum: 300,
-      step: 5,
-      store: true,
-      required: true,
-      onSet: async (newValue, oldValue) => {
-        this.logger.log(`Poll interval ${oldValue} -> ${newValue}`);
-        this.reschedule();
-      },
-    },
-  ];
-}
-```
-
-**Sensor-level** schemas appear on the camera detail page next to that one sensor. Override the getter on your `Sensor` subclass.
-
-```ts
-class ConfigurableMotion extends MotionDetectorSensor<{ sensitivity: number; mode: 'fast' | 'accurate' }> {
-  override get storageSchema(): JsonSchema[] {
-    return [
-      {
-        type: 'number',
-        key: 'sensitivity',
-        title: 'Sensitivity',
-        description: 'Higher = trigger on smaller motion',
-        defaultValue: 50,
-        minimum: 0, maximum: 100, step: 1,
-        store: true,
-        onSet: async () => this.reconfigure(),
-      },
-      {
-        type: 'string',
-        key: 'mode',
-        title: 'Mode',
-        description: 'Trade-off between speed and accuracy',
-        defaultValue: 'fast',
-        enum: ['fast', 'accurate'],
-        store: true,
-      },
-      {
-        type: 'button',
-        key: 'reset',
-        title: 'Reset to defaults',
-        description: 'Restore sensitivity / mode',
-        color: 'danger',
-        onSet: async () => {
-          await this.storage.setValue('sensitivity', 50);
-          await this.storage.setValue('mode', 'fast');
-        },
-      },
-    ];
-  }
-
-  async detectMotion(_frame: VideoFrameData): Promise<MotionResult> {
-    const sensitivity = this.storage.values.sensitivity;
-    const _mode = this.storage.values.mode;
-    void sensitivity;
-    return { detected: false, detections: [] };
-  }
-
-  private reconfigure(): void { /* re-warm caches */ }
-}
-```
-
-Field types:
-
-- `number` — slider/input with optional `minimum`, `maximum`, `step`.
-- `string` — text input; add `enum: [...]` for a dropdown, `format: 'password'` to mask, `format: 'image'` / `'qrCode'` for media display.
-- `boolean` — toggle.
-- `button` — fires `onSet()` on click; stores no value. Useful for actions like "Test connection" or "Reset".
-
-`onSet(newValue, oldValue)` runs after the host has persisted the new value. Use it to re-warm caches, restart sessions, or anything else that depends on the changed setting. It's async, but the host doesn't block UI on it — keep work scoped to the plugin.
-
-For the full schema reference (conditional visibility, submit handlers with toast feedback, array fields), see `src/storage/index.ts` in the SDK.
-
-## 6. Optional interfaces
-
-`BasePlugin` covers the lifecycle. Specific capabilities are unlocked by implementing one of the optional interfaces and listing it in `contract.interfaces`. The rest of this section shows each one with a working snippet.
-
-### 6.1 DiscoveryProvider
-
-Let users scan and adopt cameras. Three methods: `onDiscoverCameras` returns adoption candidates, `onGetCameraSettings` returns the schema for the adoption form, `onAdoptCamera` resolves the form values into a `CameraConfig` for the host to persist. Available only for camera-controlling roles (`CameraController`, `CameraAndSensorProvider`).
-
-```ts
-import { API_EVENT, BasePlugin } from '@camera.ui/sdk';
-import type {
-  CameraConfig, CameraDevice, DeviceStorage, DiscoveredCamera, DiscoveryProvider,
-  JsonSchemaWithoutCallbacks, LoggerService, PluginAPI,
-} from '@camera.ui/sdk';
-
-interface FakeDevice { id: string; name: string; manufacturer: string; model: string; host: string; }
-const FAKE_DEVICES: FakeDevice[] = [
-  { id: 'fake-001', name: 'Front Door', manufacturer: 'ACME', model: 'X1', host: '192.0.2.10' },
-];
-
-export default class CameraProvider extends BasePlugin implements DiscoveryProvider {
-  private cameras = new Map<string, CameraDevice>();
-
-  constructor(logger: LoggerService, api: PluginAPI, storage: DeviceStorage) {
-    super(logger, api, storage);
-    this.api.on(API_EVENT.SHUTDOWN, () => this.cameras.clear());
-  }
-
-  async configureCameras(cameras: CameraDevice[]): Promise<void> {
-    for (const c of cameras) this.cameras.set(c.id, c);
-  }
-  async onCameraAdded(camera: CameraDevice): Promise<void> { this.cameras.set(camera.id, camera); }
-  async onCameraReleased(cameraId: string): Promise<void> { this.cameras.delete(cameraId); }
-
-  async onDiscoverCameras(): Promise<DiscoveredCamera[]> {
-    const adopted = new Set(Array.from(this.cameras.values()).map((c) => c.nativeId));
-    return FAKE_DEVICES
-      .filter((d) => !adopted.has(d.id))
-      .map(({ id, name, manufacturer, model }) => ({ id, name, manufacturer, model }));
-  }
-
-  async onGetCameraSettings(_camera: DiscoveredCamera): Promise<JsonSchemaWithoutCallbacks[]> {
-    return [
-      { type: 'string', key: 'username', title: 'Username', description: '', required: true },
-      { type: 'string', key: 'password', title: 'Password', description: '', format: 'password', required: true },
-    ];
-  }
-
-  async onAdoptCamera(camera: DiscoveredCamera, settings: Record<string, unknown>): Promise<CameraConfig> {
-    const device = FAKE_DEVICES.find((d) => d.id === camera.id);
-    if (!device) throw new Error(`Unknown device: ${camera.id}`);
-    const u = encodeURIComponent(String(settings.username ?? ''));
-    const p = encodeURIComponent(String(settings.password ?? ''));
-    return {
-      name: device.name,
-      nativeId: device.id,
-      info: { manufacturer: device.manufacturer, model: device.model },
-      sources: [{
-        name: 'main',
-        role: 'high-resolution',
-        urls: [`rtsp://${u}:${p}@${device.host}/stream0`],
-        useForSnapshot: true,
-        hotMode: true,
-        preload: true,
-        prebuffer: false,
-      }],
-    };
-  }
-}
-```
-
-For asynchronous discovery (cloud OAuth callbacks, mDNS bursts), you can also push candidates directly into the UI without waiting for the next poll: `await api.deviceManager.pushDiscoveredCameras([...])`.
-
-### 6.2 NotifierInterface
-
-Register as a notification target so the host's `NotificationManager` can dispatch through you. The plugin owns its device list — the manager queries through these methods rather than maintaining a shared registry.
-
-```ts
-import { API_EVENT, BasePlugin } from '@camera.ui/sdk';
-import type {
-  CameraDevice, DeviceStorage, LoggerService, Notification,
-  NotifierDevice, NotifierInterface, PluginAPI,
-} from '@camera.ui/sdk';
-
-export default class MyNotifier extends BasePlugin implements NotifierInterface {
-  private devices: NotifierDevice[] = [];
-
-  constructor(logger: LoggerService, api: PluginAPI, storage: DeviceStorage) {
-    super(logger, api, storage);
-    this.api.on(API_EVENT.SHUTDOWN, () => this.devices.splice(0));
-  }
-
-  async configureCameras(_cameras: CameraDevice[]): Promise<void> {}
-  async onCameraAdded(_camera: CameraDevice): Promise<void> {}
-  async onCameraReleased(_cameraId: string): Promise<void> {}
-
-  async getDevices(ownerUserId: string): Promise<NotifierDevice[]> {
-    return this.devices.filter((d) => d.ownerUserId === ownerUserId);
-  }
-
-  async getDevice(deviceId: string): Promise<NotifierDevice | null> {
-    return this.devices.find((d) => d.id === deviceId) ?? null;
-  }
-
-  async sendNotification(deviceId: string, n: Notification): Promise<void> {
-    const device = this.devices.find((d) => d.id === deviceId);
-    if (!device?.active) return;
-    this.logger.log(`[${device.name}] ${n.title}: ${n.body ?? ''}`);
-  }
-
-  async registerDevice(ownerUserId: string, input: Record<string, unknown>): Promise<NotifierDevice> {
-    const device: NotifierDevice = {
-      id: crypto.randomUUID(),
-      ownerUserId,
-      type: String(input.type ?? 'mobile'),
-      name: String(input.name ?? 'Unnamed device'),
-      active: true,
-    };
-    this.devices.push(device);
-    return device;
-  }
-
-  async revokeDevice(deviceId: string): Promise<void> {
-    const idx = this.devices.findIndex((d) => d.id === deviceId);
-    if (idx >= 0) this.devices.splice(idx, 1);
-  }
-
-  async updateDevice(deviceId: string, patch: Record<string, unknown>): Promise<NotifierDevice | null> {
-    const device = this.devices.find((d) => d.id === deviceId);
-    if (!device) return null;
-    if (typeof patch.name === 'string') device.name = patch.name;
-    if (typeof patch.active === 'boolean') device.active = patch.active;
-    return device;
-  }
-}
-```
-
-`Notification.tag` is a collapse key for dedup at both the manager and notifier level — multiple events with the same tag inside the throttle window collapse into one notification. `Notification.severity` is `'info' | 'warn' | 'error' | 'critical'`; map `critical` to whatever DND-bypass mechanism your platform offers.
-
-### 6.3 Detection interfaces
-
-The seven detection capabilities follow a single pattern. Each interface has:
-
-- A required `test*` method invoked by the UI when the user uploads a clip/image and clicks "Test" — it accepts raw media bytes plus metadata and returns the same result shape the per-frame detector would.
-- An optional pre-processed `detect*` method invoked by automations and benchmarks — it accepts already-decoded frames.
-- An optional `*Settings()` method that returns a schema for the detection configuration UI.
-
-All seven (`MotionDetectionInterface`, `ObjectDetectionInterface`, `AudioDetectionInterface`, `FaceDetectionInterface`, `LicensePlateDetectionInterface`, `ClassifierDetectionInterface`, `ClipDetectionInterface`) share that shape. `ClipDetectionInterface` additionally requires `getTextEmbedding(text)` for semantic search.
-
-Motion as a worked example:
-
-```ts
-import type {
-  MotionDetectionInterface, MotionDetectionPluginResponse,
-  VideoFrameData, JsonSchema,
-} from '@camera.ui/sdk';
-
-export default class MotionPlugin extends BasePlugin implements MotionDetectionInterface {
-  // ... lifecycle methods omitted ...
-
-  async testMotionDetection(
-    videoData: Buffer | Uint8Array,
-    _config: Record<string, unknown>,
-  ): Promise<MotionDetectionPluginResponse | undefined> {
-    const detections = await this.runOnEncodedClip(videoData);
-    return { detected: detections.length > 0, detections };
-  }
-
-  async detectMotion(
-    frames: VideoFrameData[],
-    _config?: Record<string, unknown>,
-  ): Promise<MotionDetectionPluginResponse | undefined> {
-    const detections = await this.runOnFrames(frames);
-    return { detected: detections.length > 0, detections };
-  }
-
-  async motionDetectionSettings(): Promise<JsonSchema[] | undefined> {
-    return [
-      { type: 'number', key: 'minArea', title: 'Min area (%)', description: '',
-        defaultValue: 1, minimum: 0, maximum: 100, step: 1, store: true },
-    ];
-  }
-
-  private async runOnEncodedClip(_v: Buffer | Uint8Array): Promise<[]> { return []; }
-  private async runOnFrames(_f: VideoFrameData[]): Promise<[]> { return []; }
-}
-```
-
-The image-based detection interfaces (`ObjectDetectionInterface`, `FaceDetectionInterface`, `LicensePlateDetectionInterface`, `ClassifierDetectionInterface`, `ClipDetectionInterface`) take an extra `metadata: ImageMetadata` argument with `width` / `height`. The audio interface takes `metadata: AudioMetadata` with the `mimeType`. Otherwise the wiring is identical to the motion example above — add the matching `PluginInterface.X` flag to the contract and implement the `test*` / optional `detect*` / optional settings trio.
-
-A detection plugin almost always implements both halves: the appropriate `*DetectorSensor` subclass (Section 4) for the live pipeline, AND the matching `*DetectionInterface` here for UI test dialogs and ad-hoc benchmarks.
-
-## 7. Logging
-
-`this.logger` is a `LoggerService`. The methods are `log`, `warn`, `error`, `success`, `debug`, `trace`, and `attention` — each accepts a list of arguments joined with spaces by the host. `debug` and `trace` are gated by host log level.
-
-```ts
-this.logger.log('Plugin started');
-this.logger.success(`Connected to vendor cloud as ${user}`);
-this.logger.warn('Falling back to substream');
-this.logger.error('Adopt failed:', err);
-```
-
-Every `CameraDevice` exposes `camera.logger` — same interface, but the output is prefixed with the camera name. Prefer it over `this.logger` whenever the message is about a specific camera:
-
-```ts
-async onCameraAdded(camera: CameraDevice): Promise<void> {
-  camera.logger.log('attached');
-}
-```
-
-## 8. Inter-plugin communication
-
-The cleanest way for one plugin to react to another's sensors is `camera.onSensorProperty<T>(type, property, callback)`. It auto-subscribes when a sensor of the requested type appears (now or later), unsubscribes when it goes away, and tears down everything when you dispose the returned handle. The callback receives `(value, timestamp, sensor)`. This is the pattern Hub plugins (HomeKit, automations) use.
-
-A complete Hub consumer that listens to motion AND doorbell on every assigned camera:
-
-```ts
-import { API_EVENT, BasePlugin, DoorbellProperty, MotionProperty, SensorType } from '@camera.ui/sdk';
-import type {
-  CameraDevice, DeviceStorage, Disposable, LoggerService, PluginAPI,
-} from '@camera.ui/sdk';
-
-export default class HubConsumer extends BasePlugin {
-  private subs = new Map<string, Disposable[]>();
-
-  constructor(logger: LoggerService, api: PluginAPI, storage: DeviceStorage) {
-    super(logger, api, storage);
-    this.api.on(API_EVENT.SHUTDOWN, () => this.disposeAll());
-  }
-
-  async configureCameras(cameras: CameraDevice[]): Promise<void> {
-    for (const camera of cameras) this.bind(camera);
-  }
-
-  async onCameraAdded(camera: CameraDevice): Promise<void> {
-    this.bind(camera);
-  }
-
-  async onCameraReleased(cameraId: string): Promise<void> {
-    for (const sub of this.subs.get(cameraId) ?? []) sub.dispose();
-    this.subs.delete(cameraId);
-  }
-
-  private bind(camera: CameraDevice): void {
-    const motion = camera.onSensorProperty<boolean>(
-      SensorType.Motion, MotionProperty.Detected,
-      (detected) => { if (detected) camera.logger.log('motion started'); },
-    );
-
-    const doorbell = camera.onSensorProperty<boolean>(
-      SensorType.Doorbell, DoorbellProperty.Ring,
-      (ring) => { if (ring) camera.logger.log('doorbell rang'); },
-    );
-
-    this.subs.set(camera.id, [motion, doorbell]);
-  }
-
-  private disposeAll(): void {
-    for (const list of this.subs.values()) for (const sub of list) sub.dispose();
-    this.subs.clear();
-  }
-}
-```
-
-Two things to notice:
-
-- The bridge keeps one `Disposable[]` per camera and disposes it in `onCameraReleased`. This is critical — `onSensorProperty` keeps an internal subscription alive until you call `.dispose()`.
-- The bind happens in both `configureCameras` AND `onCameraAdded` for cameras that show up after startup. Same shape as for sensor-providing plugins.
-
-For direct plugin-to-plugin RPC (e.g. asking a face plugin to compute embeddings on demand), use `api.coreManager.connectToPlugin(name)`. It returns a typed proxy of the target plugin including any optional interfaces it implements:
-
-```ts
-const face = await this.api.coreManager.connectToPlugin('Face Plugin');
-const result = await face?.testFaceDetection(jpegBytes, { width: 640, height: 480 }, {});
-```
-
-Use `api.coreManager.getPluginsByInterface(PluginInterface.FaceDetection)` to discover candidate plugins by capability rather than by name.
-
-## 9. Common pitfalls
-
-- **Always release per-camera state in `onCameraReleased`.** Timers, vendor sessions, RTP sockets, `Disposable`s from `onSensorProperty` — drop them all. Leaking them keeps the camera object alive forever and prevents reassignment from working.
-- **Don't block in `configureCameras`.** It runs on the host's startup path; a slow vendor handshake delays every other plugin. Do the network work in `API_EVENT.FINISH_LAUNCHING` instead.
-- **Don't import from `@camera.ui/sdk/internal`.** The `internal` subpath exposes types the host uses to talk to plugins via RPC. The shapes there are not part of the stable public surface and may change without notice.
-- **Don't construct sensors in the constructor.** The host hasn't finished wiring up `api` / `storage` until `super()` returns and `configureCameras` is called. Construct sensors inside the lifecycle hooks.
-- **Don't log frame data.** Detection paths run dozens of times per second per camera. Use `logger.debug` / `logger.trace` (host-gated) for anything per-frame, and prefer aggregated counters over per-event logs.
-
-## 10. Next steps
-
-For complete production plugins to read alongside this guide, see [`plugins/`](https://github.com/seydx/camera.ui/tree/main/plugins) in the camera.ui repo. They cover everything documented above — discovery, notifier, detection, hub bridges — wired into a real UI.

package/scripts/build-example-docs.mjs

@@ -1,62 +0,0 @@
-/* eslint-disable @stylistic/max-len */
-import { readdirSync, readFileSync, writeFileSync, mkdirSync, statSync, rmSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const examplesDir = join(here, '..', 'examples');
-const outDir = join(here, '..', 'docs', 'examples');
-const apiDir = join(here, '..', 'docs', 'api');
-
-const apiIndex = `# API Reference
-
-Module-by-module reference, auto-generated from the JSDoc in \`@camera.ui/sdk\`.
-
-| Module | What's in it |
-| --- | --- |
-| [Plugin API](./plugin/) | \`BasePlugin\`, the manifest contract, optional interfaces (discovery, notifier, detection). |
-| [Camera](./camera/) | Camera config, frames, streaming sessions, detection events, runtime device API. |
-| [Sensors](./sensor/) | Detection sensors (motion, object, face, license-plate, audio, classifier, clip) and smart-home sensors (contact, doorbell, lock, garage, light, switch, ptz, security system, environmental). |
-| [Storage & Schema](./storage/) | Schema-driven per-device config rendered as UI forms by the host. |
-| [Manager](./manager/) | \`CoreManager\` / \`DeviceManager\` / \`DownloadManager\` for system-level services. |
-| [Observable](./observable/) | Reactive primitives — \`Observable\`, \`Subject\`, \`BehaviorSubject\`, \`ReplaySubject\` — and operators. |
-| [Types](./types/) | Shared types (\`LoggerService\`, \`PluginAPI\`, …). |
-
-If you're new to the SDK, start with the [Plugin Guide](/examples/getting-started) instead — it walks through these modules in the order you'll actually use them.
-`;
-
-writeFileSync(join(apiDir, 'index.md'), apiIndex);
-
-rmSync(outDir, { recursive: true, force: true });
-mkdirSync(outDir, { recursive: true });
-
-const indexSrc = readFileSync(join(examplesDir, 'README.md'), 'utf8');
-const indexOut = indexSrc.replace(/\[`([^`]+)\/`\]\(\.\/\1\/\)/g, '[`$1`](/examples/$1)').replace(/^# .+/m, '# Examples');
-writeFileSync(join(outDir, 'index.md'), indexOut);
-
-const entries = readdirSync(examplesDir).sort();
-
-for (const name of entries) {
-  const full = join(examplesDir, name);
-  const stat = statSync(full);
-
-  if (stat.isFile() && name.endsWith('.md') && name !== 'README.md') {
-    const src = readFileSync(full, 'utf8');
-    writeFileSync(join(outDir, name), src);
-    continue;
-  }
-
-  if (!stat.isDirectory()) continue;
-
-  const readme = readFileSync(join(full, 'README.md'), 'utf8');
-  const contract = readFileSync(join(full, 'contract.ts'), 'utf8');
-  const index = readFileSync(join(full, 'index.ts'), 'utf8');
-
-  const page = [readme.trimEnd(), '', '## `contract.ts`', '', '```ts', contract.trimEnd(), '```', '', '## `index.ts`', '', '```ts', index.trimEnd(), '```', ''].join(
-    '\n',
-  );
-
-  writeFileSync(join(outDir, `${name}.md`), page);
-}
-
-console.log(`Built example pages to ${outDir}`);

package/tsconfig.node.json

@@ -1,31 +0,0 @@
-{
-  "compilerOptions": {
-    "outDir": "./dist",
-    "target": "es2024",
-    "moduleResolution": "NodeNext",
-    "module": "NodeNext",
-    "lib": [
-      "ES2024",
-    ],
-    "declaration": false,
-    "strict": true,
-    "esModuleInterop": true,
-    "preserveConstEnums": true,
-    "skipLibCheck": true,
-    "useUnknownInCatchVariables": false,
-    "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "verbatimModuleSyntax": true,
-    "noImplicitAny": true,
-  },
-  "include": [
-    "src",
-  ],
-  "exclude": [
-    "node_modules",
-    "dist",
-    "src/**/*.test.ts",
-  ],
-}

package/typedoc.json

@@ -1,42 +0,0 @@
-{
-  "plugin": [
-    "typedoc-plugin-markdown",
-    "typedoc-vitepress-theme"
-  ],
-  "entryPoints": [
-    "./src/camera/index.ts",
-    "./src/sensor/index.ts",
-    "./src/plugin/index.ts",
-    "./src/manager/index.ts",
-    "./src/storage/index.ts",
-    "./src/observable/index.ts",
-    "./src/types.ts"
-  ],
-  "exclude": [
-    "**/*.test.ts",
-    "**/dist/**",
-    "**/node_modules/**"
-  ],
-  "externalPattern": [
-    "**/*.test.ts",
-    "**/dist/**",
-    "**/node_modules/**"
-  ],
-  "excludeExternals": true,
-  "excludeInternal": true,
-  "out": "./docs/api",
-  "docsRoot": "./docs",
-  "sidebar": {
-    "autoConfiguration": true,
-    "format": "vitepress",
-    "pretty": false,
-    "collapsed": true
-  },
-  "validation": {
-    "notExported": true,
-    "invalidLink": true,
-    "rewrittenLink": true,
-    "notDocumented": false,
-    "unusedMergeModuleWith": true
-  }
-}