@camstack/types 0.1.40 → 0.1.42

package/dist/device/device-management.d.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
 import type { DeviceType } from './device-type.js';
 import type { IDevice } from './device.js';
+import type { SourceInfo } from './source-info.js';
 export interface DeviceManualCreation {
     getChildCreationSchema(type: DeviceType): z.ZodObject<z.core.$ZodLooseShape>;
     createDevice(type: DeviceType, config: unknown): Promise<IDevice>;
@@ -14,6 +15,10 @@ export interface DiscoveredDevice {
     readonly type: DeviceType;
     readonly suggestedName: string;
     readonly prefilledConfig: Record<string, unknown>;
+    /** Optional upstream-system identity + rendering envelope. See
+     *  `SourceInfo`. Providers populate this when discovery already knows
+     *  the upstream identity / unit / deviceClass (HA-style discovery). */
+    readonly sourceInfo?: SourceInfo;
 }
 export interface SavedDevice {
     /** Numeric id reserved at allocateDeviceId time. */
@@ -56,10 +61,9 @@ export interface SavedDevice {
  */
 /**
  * Free-form device metadata — hardware identity + driver-populated
- * facts the operator can both read and edit. Mirrors Scrypted's
- * `info: { manufacturer, model, serialNumber, ... }` device-level
- * surface but stored as a single JSON blob so future fields (HA
- * matter id, ONVIF profile token, …) don't require schema changes.
+ * facts the operator can both read and edit. Stored as a single JSON
+ * blob so future fields (HA matter id, ONVIF profile token, …) don't
+ * require schema changes.
  *
  * Conventional keys (drivers should populate when known):
  *   - `manufacturer`  e.g. 'Reolink'
@@ -74,6 +78,62 @@ export interface SavedDevice {
  * `ipAddress`, `apiPort`, …). All values must be JSON-serializable.
  */
 export type DeviceMetadata = Record<string, unknown>;
+/** One child-placement directive on a container's `childLayout`. The child is
+ *  identified by its accessory `stableIdSuffix` (the key the provider passes to
+ *  `getAccessoryChildren()`), which is re-sync stable. Children NOT listed here
+ *  render in the plain Overview list as today; listed children are grouped into
+ *  collapsible accordion sections in the UI (built in a follow-up task). */
+export interface ChildLayoutEntry {
+    readonly childKey: string;
+    readonly section: string;
+    readonly order?: number;
+    /** Section-level default-collapsed hint: when true, the accordion section this
+     *  entry belongs to renders closed by default. The section is treated as
+     *  collapsed if ANY of its entries sets `collapsed: true`; consistent values
+     *  across a section's entries are recommended but not enforced. Absent ⇒ open
+     *  by default. */
+    readonly collapsed?: boolean;
+}
+export type ChildLayout = readonly ChildLayoutEntry[];
+/** One end of a device link: a single field on a source device's capability,
+ *  addressed by the source's re-sync-stable accessory `stableIdSuffix`
+ *  (`sourceKey`) — NOT a raw numeric id — so the link survives a re-sync. The
+ *  source must be a sibling accessory under the SAME parent container as the
+ *  target device; resolution is `${parentStableId}-${sourceKey}` (cross-parent
+ *  links are out of scope and resolve to no source). */
+export interface DeviceLinkSource {
+    readonly sourceKey: string;
+    readonly cap: string;
+    readonly fieldPath: string;
+}
+/** The target field a link writes: a dot-path into the target cap's status. */
+export interface DeviceLinkTarget {
+    readonly cap: string;
+    readonly fieldPath: string;
+    /** Optional grouping key for array-of-items target caps (consumables); P2. */
+    readonly itemKey?: string;
+}
+/** Optional value transform applied to the resolved source value. */
+export type DeviceLinkTransform = {
+    readonly kind: 'identity';
+} | {
+    readonly kind: 'enum-map';
+    readonly mapping: Record<string, string | number | boolean>;
+    readonly fallback?: string | number | boolean;
+} | {
+    readonly kind: 'linear';
+    readonly scale: number;
+    readonly offset: number;
+    readonly clamp?: readonly [number, number];
+};
+/** One operator-authored cross-device field wiring, persisted on the TARGET. */
+export interface DeviceLink {
+    readonly id: string;
+    readonly source: DeviceLinkSource;
+    readonly target: DeviceLinkTarget;
+    readonly transform?: DeviceLinkTransform;
+}
+export type DeviceLinks = readonly DeviceLink[];
 export interface DeviceMeta {
     readonly id: number;
     readonly stableId: string;
@@ -85,6 +145,38 @@ export interface DeviceMeta {
     readonly parentDeviceId: number | null;
     /** Hardware + identity blob; null when nothing has been populated yet. */
     readonly metadata: DeviceMetadata | null;
+    /** Optional upstream-system identity + rendering envelope. See
+     *  `SourceInfo`. Persisted under `metadata.sourceInfo` — this field
+     *  is the typed projection callers consume directly. `BaseDevice`
+     *  re-extracts via `extractSourceInfoFromMetadata()` for its own
+     *  getter; kernel-side reader populates this from the same path. */
+    readonly sourceInfo?: SourceInfo;
+    /** Owning integration id, stamped at create — used by the core to
+     *  cascade-delete an integration's devices. Optional: only present
+     *  when the device was created through an integration (e.g. HA). */
+    readonly integrationId?: string;
+    /** Optional soft-link to another device id (peer of integrationId).
+     *  Set at create; inert today — reserved for the Container→child
+     *  passthrough. Nullable: an explicit null means "unlinked". */
+    readonly linkDeviceId?: number | null;
+    /** Durable primary-child override for a CONTAINER device, keyed on the
+     *  chosen child's re-sync/rename-stable `entityId` (its `sourceInfo.id`,
+     *  falling back to `stableId`). Unlike the numeric `linkDeviceId`, this
+     *  survives a re-sync that reallocates the child's numeric id or renames
+     *  its row. `null` explicitly clears the override → priority default.
+     *  Absent ⇒ no override has ever been set. */
+    readonly primaryChildEntityId?: string | null;
+    /** Container-level layout hint: assigns specific child/accessory devices to
+     *  named accordion sections (with optional intra-section order). Each entry's
+     *  `childKey` is the child's re-sync-stable accessory `stableIdSuffix`. Set at
+     *  create, persisted, projected, and preserved across re-register/restore —
+     *  same lifecycle as `primaryChildEntityId`. Absent ⇒ no layout declared (all
+     *  children render in the plain Overview list). */
+    readonly childLayout?: ChildLayout;
+    /** Operator-authored cross-device field wirings (source field → this device's
+     *  cap field). Same create/persist/project/restore lifecycle as `childLayout`.
+     *  Absent ⇒ no links. Overlaid onto the target cap's `getStatus` at read time. */
+    readonly deviceLinks?: DeviceLinks;
 }
 /**
  * Initial meta a provider supplies on `onCreateDevice`. Differs
@@ -95,6 +187,26 @@ export interface InitialDeviceMeta {
     readonly type: DeviceType;
     readonly name: string;
     readonly location?: string | null;
+    /** Semantic role string (`DeviceRole`) — stamped at create for
+     *  accessory children (e.g. 'numeric-sensor', 'binary-sensor').
+     *  Optional: only set when the device is an accessory with a known role. */
+    readonly role?: string;
+    /** Owning integration id, stamped at create — used by the core to
+     *  cascade-delete an integration's devices. Optional: only set when
+     *  the device is being created through an integration. */
+    readonly integrationId?: string;
+    /** Optional soft-link to another device id (peer of integrationId).
+     *  Set at create; inert today — reserved for the Container→child
+     *  passthrough. Nullable: an explicit null means "unlinked". */
+    readonly linkDeviceId?: number | null;
+    /** Container-level layout hint set at create — assigns specific
+     *  child/accessory devices to named accordion sections (with optional order).
+     *  Mirrors `DeviceMeta.childLayout`; persisted, projected, and preserved
+     *  across re-register/restore. Optional: only set for CONTAINER devices that
+     *  declare a layout. */
+    readonly childLayout?: ChildLayout;
+    /** Cross-device field wirings set at create. Mirrors `DeviceMeta.deviceLinks`. */
+    readonly deviceLinks?: DeviceLinks;
 }
 /**
  * Single-call payload returned by `BaseDeviceProvider.onCreateDevice`.

package/dist/device/device-management.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-management.d.ts","sourceRoot":"","sources":["../../src/device/device-management.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"device-management.d.ts","sourceRoot":"","sources":["../../src/device/device-management.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,MAAM,WAAW,oBAAoB;IACnC,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC5E,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,eAAe,IAAI,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAA;IACvD,qBAAqB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjD;;2EAEuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACzC;AAED;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEpD;;;;4EAI4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;sBAIkB;IAClB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AACD,MAAM,MAAM,WAAW,GAAG,SAAS,gBAAgB,EAAE,CAAA;AAErD;;;;;wDAKwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AACD,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AACD,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,GACzI;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC3C,CAAA;AACL,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAA;CACzC;AACD,MAAM,MAAM,WAAW,GAAG,SAAS,UAAU,EAAE,CAAA;AAE/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAA;IACxC;;;;wEAIoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;;wEAEoE;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;oEAEgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC;;;;;kDAK8C;IAC9C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7C;;;;;uDAKmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC;;sFAEkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;gFAE4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;;8DAE0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;oEAEgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC;;;;4BAIwB;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACnE"}

package/dist/device/device-type.d.ts

@@ -7,11 +7,85 @@ export declare enum DeviceType {
     Sensor = "sensor",
     Thermostat = "thermostat",
     Button = "button",
-    Generic = "generic"
+    /** Generic stateless event emitter — carries a device's EXACT declared
+     *  event vocabulary verbatim (no normalization). Installed with the
+     *  `event-emitter` cap. Sources: HA `event.*` entities (structured) and
+     *  HA bus events (e.g. `zha_event`, generic). */
+    EventEmitter = "event-emitter",
+    /** Firmware/software update entity — current vs available version,
+     *  updatable flag, update state, and an install action. Installed with
+     *  the `update` cap. Sources: Homematic firmware-update channels (and
+     *  reusable by other providers, e.g. HA `update.*` entities). */
+    Update = "update",
+    Generic = "generic",
+    /** Generic notification delivery target (HA `notify.<service>`, future
+     *  Telegram / Discord / ntfy / SMTP, …). One device per delivery
+     *  endpoint; the `notifier` cap defines the send surface. */
+    Notifier = "notifier",
+    /** Pre-recorded action sequence with optional parameters
+     *  (HA `script.*`). Runnable via `script-runner` cap. */
+    Script = "script",
+    /** Automation rule (HA `automation.*`) — enable/disable + manual
+     *  trigger surface exposed via `automation-control` cap. */
+    Automation = "automation",
+    /** Door / smart lock device (HA `lock.*`). `lock-control` cap. */
+    Lock = "lock",
+    /** Window covering, blinds, garage door, valve, etc. (HA `cover.*`,
+     *  `valve.*`). `cover` cap with sub-roles for variant. */
+    Cover = "cover",
+    /** Pipe / water / gas valve with open/close/stop and optional
+     *  position (HA `valve.*`). `valve` cap — a cover-sibling actuator
+     *  modelled on the same open/closed lifecycle. */
+    Valve = "valve",
+    /** Humidifier / dehumidifier with on/off + target humidity + mode
+     *  (HA `humidifier.*`). `humidifier` cap — a climate-family actuator
+     *  modelled on the same target / mode lifecycle. */
+    Humidifier = "humidifier",
+    /** Water heater / boiler with target temperature + operation mode +
+     *  away mode (HA `water_heater.*`). `water-heater` cap — a
+     *  climate-family actuator. */
+    WaterHeater = "water-heater",
+    /** Ceiling / standing / exhaust fan (HA `fan.*`). `fan-control` cap. */
+    Fan = "fan",
+    /** Audio / video playback endpoint (HA `media_player.*`). Disjoint from
+     *  the camera surface — those use `Camera`. `media-player` cap. */
+    MediaPlayer = "media-player",
+    /** Security panel / alarm system (HA `alarm_control_panel.*`).
+     *  `alarm-panel` cap. */
+    AlarmPanel = "alarm-panel",
+    /** Generic user-settable input (HA `number` / `input_number` / `select`
+     *  / `input_select` / `text` / `input_text` / `input_datetime`).
+     *  Sub-type via `DeviceRole`: NumericControl / SelectControl /
+     *  TextControl / DateTimeControl. */
+    Control = "control",
+    /** Person / device-tracker presence (HA `person.*`, `device_tracker.*`).
+     *  `presence` cap. */
+    Presence = "presence",
+    /** Weather provider (HA `weather.*`). Tier-3, low MVP priority.
+     *  `weather` cap. */
+    Weather = "weather",
+    /** Robot vacuum (HA `vacuum.*`). Tier-3. `vacuum-control` cap. */
+    Vacuum = "vacuum",
+    /** Robotic lawn mower (HA `lawn_mower.*`). Tier-3.
+     *  `lawn-mower-control` cap. */
+    LawnMower = "lawn-mower",
+    /** Physical HA device group — parent container for entity-children
+     *  adopted from a single HA device entry. Not renderable as a
+     *  standalone device; exists only to anchor child entities. */
+    Container = "container",
+    /** Single still-image entity (HA `image.*`). Read-only display of an
+     *  `entity_picture` signed URL the browser loads directly. `image` cap. */
+    Image = "image"
 }
 export declare enum DeviceFeature {
     BatteryOperated = "battery-operated",
     Rebootable = "rebootable",
+    /**
+     * Device supports an on-demand re-sync of its derived spec with its
+     * upstream source — drives the generic Re-sync button. The owning
+     * provider implements the action via the `device-adoption.resync` cap.
+     */
+    Resyncable = "resyncable",
     NativeSnapshot = "native-snapshot",
     DoorbellButton = "doorbell-button",
     TwoWayAudio = "two-way-audio",
@@ -36,7 +110,88 @@ export declare enum DeviceFeature {
      * fast scalar without binding fetch), notifier rules, and `listAll`
      * filters that want "all devices with on-motion behaviour".
      */
-    MotionTrigger = "motion-trigger"
+    MotionTrigger = "motion-trigger",
+    /** Light supports rgb-triplet color via `color` cap. */
+    LightColorRgb = "light-color-rgb",
+    /** Light supports HSV color via `color` cap. */
+    LightColorHsv = "light-color-hsv",
+    /** Light supports color-temperature (mired) via `color` cap. */
+    LightColorMired = "light-color-mired",
+    /** Thermostat supports a `heat_cool` dual setpoint (targetLow +
+     *  targetHigh). Gates the range slider UI. */
+    ClimateDualSetpoint = "climate-dual-setpoint",
+    /** Thermostat exposes target humidity and/or current humidity
+     *  readings. Gates the humidity controls. */
+    ClimateHumidity = "climate-humidity",
+    /** Thermostat exposes a fan-mode selector. */
+    ClimateFanMode = "climate-fan-mode",
+    /** Thermostat exposes preset modes (eco / away / sleep / vendor). */
+    ClimatePreset = "climate-preset",
+    /** Cover exposes intermediate position control (0..100). Gates the
+     *  position slider UI. */
+    CoverPositionable = "cover-positionable",
+    /** Cover exposes slat-tilt control. Gates the tilt slider UI. */
+    CoverTilt = "cover-tilt",
+    /** Valve exposes intermediate position control (0..100). Gates the
+     *  position slider / drag surface UI. */
+    ValvePositionable = "valve-positionable",
+    /** Fan exposes a speed-percentage setter. Gates the speed slider UI. */
+    FanSpeed = "fan-speed",
+    /** Fan exposes a preset mode selector. */
+    FanPreset = "fan-preset",
+    /** Fan exposes blade direction (forward/reverse) — typical of
+     *  ceiling fans. */
+    FanDirection = "fan-direction",
+    /** Fan exposes an oscillation toggle. */
+    FanOscillating = "fan-oscillating",
+    /** Lock requires a PIN code on lock/unlock. Gates the code-entry
+     *  field on the UI lock-controls panel. */
+    LockPinRequired = "lock-pin-required",
+    /** Lock supports a latch-release ("open door") action distinct from
+     *  unlock. Mirrors HA `LockEntityFeature.OPEN` (bit 1) in
+     *  `supported_features`. Gates the Open Door button in the UI. */
+    LockOpen = "lock-open",
+    /** Media player exposes a seek-to-position surface. */
+    MediaPlayerSeek = "media-player-seek",
+    /** Media player exposes a volume-level setter. */
+    MediaPlayerVolume = "media-player-volume",
+    /** Media player exposes a mute toggle distinct from volume=0. */
+    MediaPlayerMute = "media-player-mute",
+    /** Media player exposes a shuffle toggle. */
+    MediaPlayerShuffle = "media-player-shuffle",
+    /** Media player exposes a repeat mode (off / all / one). */
+    MediaPlayerRepeat = "media-player-repeat",
+    /** Media player exposes a source / input selector. */
+    MediaPlayerSelectSource = "media-player-select-source",
+    /** Media player exposes a play-arbitrary-media surface (URL / id). */
+    MediaPlayerPlayMedia = "media-player-play-media",
+    /** Media player exposes next-track. */
+    MediaPlayerNext = "media-player-next",
+    /** Media player exposes previous-track. */
+    MediaPlayerPrevious = "media-player-previous",
+    /** Media player exposes stop distinct from pause. */
+    MediaPlayerStop = "media-player-stop",
+    /** Alarm panel requires a PIN code on arm/disarm. */
+    AlarmPinRequired = "alarm-pin-required",
+    /** Presence device carries GPS coordinates (lat/lng/accuracy) in
+     *  addition to a textual location. */
+    PresenceGps = "presence-gps",
+    /** Notifier accepts an inline / URL image attachment. */
+    NotifierImage = "notifier-image",
+    /** Notifier accepts a priority hint (high/normal/low). */
+    NotifierPriority = "notifier-priority",
+    /** Notifier accepts a free-form `data` payload for platform-specific
+     *  fields. */
+    NotifierData = "notifier-data",
+    /** Notifier supports interactive action buttons / callbacks. */
+    NotifierActions = "notifier-actions",
+    /** Notifier supports per-call recipient targeting (multi-user). */
+    NotifierRecipients = "notifier-recipients",
+    /** Script runner accepts a variables map on each run invocation. */
+    ScriptVariables = "script-variables",
+    /** Automation `trigger` accepts a skipCondition flag — fires the
+     *  automation's actions while bypassing its condition block. */
+    AutomationSkipCondition = "automation-skip-condition"
 }
 export declare enum ChargingStatus {
     ChargingDC = "charging-dc",
@@ -63,6 +218,62 @@ export declare enum DeviceRole {
     Autotrack = "autotrack",
     Nightvision = "nightvision",
     PrivacyMask = "privacy-mask",
-    Doorbell = "doorbell"
+    Doorbell = "doorbell",
+    /** Virtual HA toggle (input_boolean.*) — distinguishable from a
+     *  real Switch device for UI rendering / export adapters. */
+    BinaryHelper = "binary-helper",
+    /** Generic motion / occupancy / moving event source. Distinct from
+     *  the camera accessory PirSensor role: that one is a camera child;
+     *  this is a standalone HA / 3rd-party motion sensor. */
+    MotionSensor = "motion-sensor",
+    ContactSensor = "contact-sensor",
+    LeakSensor = "leak-sensor",
+    SmokeSensor = "smoke-sensor",
+    COSensor = "co-sensor",
+    GasSensor = "gas-sensor",
+    TamperSensor = "tamper-sensor",
+    VibrationSensor = "vibration-sensor",
+    ConnectivitySensor = "connectivity-sensor",
+    SoundSensor = "sound-sensor",
+    /** Fallback for `binary_sensor` without a known `device_class`. */
+    BinarySensor = "binary-sensor",
+    TemperatureSensor = "temperature-sensor",
+    HumiditySensor = "humidity-sensor",
+    AmbientLightSensor = "ambient-light-sensor",
+    PressureSensor = "pressure-sensor",
+    PowerSensor = "power-sensor",
+    EnergySensor = "energy-sensor",
+    VoltageSensor = "voltage-sensor",
+    CurrentSensor = "current-sensor",
+    AirQualitySensor = "air-quality-sensor",
+    /** Battery level (numeric % via `sensor` OR low-bool via
+     *  `binary_sensor` — the cap distinguishes via the value type). */
+    BatterySensor = "battery-sensor",
+    /** Fallback for `sensor` numeric without a known `device_class`. */
+    NumericSensor = "numeric-sensor",
+    /** String / enum state (HA `sensor` with `state_class: enum` or
+     *  `attributes.options`). */
+    EnumSensor = "enum-sensor",
+    /** Date / timestamp state (HA `sensor` with `device_class: timestamp`
+     *  or `date`). The slice carries the raw ISO string verbatim (hosted on
+     *  the `enum-sensor` cap); the UI renders it locale-formatted. */
+    DateTimeSensor = "datetime-sensor",
+    /** Last-resort fallback when nothing else matches. */
+    GenericSensor = "generic-sensor",
+    NumericControl = "numeric-control",
+    SelectControl = "select-control",
+    TextControl = "text-control",
+    DateTimeControl = "datetime-control",
+    /** Mobile push notifier (HA `notify.mobile_app_*`) — supports
+     *  rich features (image, priority, channel routing). */
+    MobilePushNotifier = "mobile-push-notifier",
+    /** Chat / messaging service (HA `notify.telegram_*`,
+     *  `notify.discord_*`, etc.). */
+    MessagingNotifier = "messaging-notifier",
+    /** Email-based delivery (HA `notify.smtp`, etc.). */
+    EmailNotifier = "email-notifier",
+    /** Fallback when the notifier service name doesn't match a known
+     *  pattern. */
+    GenericNotifier = "generic-notifier"
 }
 //# sourceMappingURL=device-type.d.ts.map

package/dist/device/device-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device-type.d.ts","sourceRoot":"","sources":["../../src/device/device-type.ts"],"names":[],"mappings":"AAAA,oBAAY,UAAU;IACpB,MAAM,WAAW;IACjB,GAAG,QAAQ;IACX,KAAK,UAAU;IACf,KAAK,UAAU;IACf,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,OAAO,YAAY;CACpB;AAED,oBAAY,aAAa;IACvB,eAAe,qBAAqB;IACpC,UAAU,eAAe;IACzB,cAAc,oBAAoB;IAClC,cAAc,oBAAoB;IAClC,WAAW,kBAAkB;IAC7B,WAAW,kBAAkB;IAC7B;;;;;;;;OAQG;IACH,YAAY,kBAAkB;IAC9B;;;;;;;;;OASG;IACH,aAAa,mBAAmB;CACjC;AAED,oBAAY,cAAc;IACxB,UAAU,gBAAgB;IAC1B,aAAa,mBAAmB;IAChC,WAAW,iBAAiB;CAC7B;AAED;;;;;;;;;;GAUG;AACH,oBAAY,UAAU;IAEpB,KAAK,UAAiB;IACtB,UAAU,eAAiB;IAC3B,SAAS,cAAiB;IAC1B,SAAS,eAAkB;IAC3B,KAAK,UAAiB;IACtB,SAAS,cAAiB;IAC1B,WAAW,gBAAiB;IAC5B,WAAW,iBAAkB;IAG7B,QAAQ,aAAiB;CAC1B"}
+{"version":3,"file":"device-type.d.ts","sourceRoot":"","sources":["../../src/device/device-type.ts"],"names":[],"mappings":"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"}

package/dist/device/device.d.ts

@@ -3,6 +3,8 @@ import type { DeviceType, DeviceFeature, DeviceRole } from './device-type.js';
 import type { DeviceConfig } from './device-config.js';
 import type { DeviceContext } from './device-context.js';
 import type { ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
+import type { RawStateResult } from '../capabilities/device-ops.cap.js';
+import type { IDeviceRuntimeState } from './device-runtime-state.js';
 export interface IDevice {
     /** Progressive, system-wide unique numeric id. Assigned by the hub's
      *  `device-manager` at `allocateDeviceId` time, injected through
@@ -55,6 +57,16 @@ export interface IDevice {
     readonly features: readonly DeviceFeature[];
     readonly config: DeviceConfig<z.ZodObject<z.core.$ZodLooseShape>>;
     readonly ctx: DeviceContext;
+    /**
+     * Kernel-managed per-device runtime-state surface (cap-keyed slices:
+     * `device-status`, `feature-probe`, `battery`, …). Present on every
+     * `BaseDevice` subclass; optional here because a handful of direct
+     * `IDevice` implementors (legacy Onvif/Frigate camera classes) predate
+     * the runtime-state machinery and don't carry one. Consumers that read
+     * it (e.g. the device-manager's `probed`-flag derivation) tolerate
+     * `undefined` as "no slice".
+     */
+    readonly runtimeState?: IDeviceRuntimeState;
     removeDevice(): Promise<void>;
     /**
      * Set the device's online flag. Called by `BaseDeviceProvider` after
@@ -83,5 +95,18 @@ export interface IDevice {
      * `config.setAll(patch)` so drivers opt in only when they need reshape.
      */
     applySettingsPatch(patch: Record<string, unknown>): Promise<void>;
+    /**
+     * Invoke a device custom action registered via `registerDeviceAction`.
+     * Validates input against the action's spec, then runs its handler.
+     * Throws on an unknown action. The device equivalent of an addon
+     * customAction; dispatched cross-process via `device-ops.runAction`.
+     */
+    runDeviceAction(action: string, input: unknown): Promise<unknown>;
+    /**
+     * Optional: return this device's RAW upstream state (cached provider
+     * values) as a display-safe `{ source, data }` blob, or `null`/absent
+     * when none. Surfaced via `device-ops.getRawState` in the State panel.
+     */
+    getRawState?(): Promise<RawStateResult | null>;
 }
 //# sourceMappingURL=device.d.ts.map

package/dist/device/device.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/device/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAE1E,MAAM,WAAW,OAAO;IACtB;;;;;0EAKsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;kEAG8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;IAC1B;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAC3C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAA;IACjE,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAE3B,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,wBAAwB,CAAA;IAE/C;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClE"}
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../../src/device/device.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAEpE,MAAM,WAAW,OAAO;IACtB;;;;;0EAKsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;kEAG8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;IAC1B;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;IAC3C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAA;IACjE,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAA;IAE3C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7B;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,mBAAmB,IAAI,wBAAwB,CAAA;IAE/C;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjE;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEjE;;;;OAIG;IACH,WAAW,CAAC,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;CAC/C"}

package/dist/device/index.d.ts

@@ -11,10 +11,14 @@ export type { IDevice } from './device.js';
 export { DEVICE_PROFILES, BATTERY_DEVICE_PROFILE, deviceMatchesProfile, resolveDeviceProfile, } from './device-profile.js';
 export type { DeviceProfile, DeviceProfileMatch, DeviceProfileDefaults, PipelinePhaseMode, } from './device-profile.js';
 export type { ICameraDevice, StreamSourceEntry } from './camera-device.js';
-export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec } from './device-management.js';
+export type { DeviceManualCreation, DeviceDiscovery, DiscoveredDevice, SavedDevice, DeviceMeta, InitialDeviceMeta, CreateDeviceSpec, ChildLayout, ChildLayoutEntry, DeviceLinkSource, DeviceLinkTarget, DeviceLinkTransform, DeviceLink, DeviceLinks } from './device-management.js';
 export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';
 export { createRuntimeStateBridge } from './runtime-state-helpers.js';
 export type { RuntimeStateBridge } from './runtime-state-helpers.js';
 export type { IDeviceRuntimeState, Snapshot as RuntimeStateSnapshot } from './device-runtime-state.js';
+export { getByPath, setByPath } from './path-util.js';
+export { applyTransform } from './device-link-transform.js';
+export { enumerateSchemaFields } from './schema-fields.js';
+export type { WireableField } from './schema-fields.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/device/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EACL,aAAa,EAAE,eAAe,EAAE,iBAAiB,EACjD,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAChI,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrI,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC/E,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACpH,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EACL,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,oBAAoB,GACpF,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EACxD,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC1E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACnK,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,YAAY,EAAE,mBAAmB,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EACL,aAAa,EAAE,eAAe,EAAE,iBAAiB,EACjD,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAChI,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrI,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAC/E,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACpH,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EACL,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,oBAAoB,GACpF,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EACxD,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC1E,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpR,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACpE,YAAY,EAAE,mBAAmB,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACtG,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/device/path-util.d.ts

@@ -0,0 +1,13 @@
+/** Read a dot-path (`a.b.c`) out of an object. Returns `undefined` for any
+ *  missing/non-object segment — never throws. */
+export declare function getByPath(obj: unknown, path: string): unknown;
+/** Immutably set a dot-path on an object, returning a new object. Intermediate
+ *  objects are created when a segment is missing or null. Arrays are NOT
+ *  traversed (P1 has no array-index syntax — see `itemKey` grouping in P2): if a
+ *  segment resolves to an array it is replaced by a fresh object, so the array
+ *  is discarded — the only caller (`mergeLinkedStatus`) re-validates the result
+ *  with the target cap's Zod schema and rejects a malformed overlay.
+ *  The return type `T` preserves the OUTER shape; the rewritten key is not
+ *  narrowed, so callers should re-validate against the status schema. */
+export declare function setByPath<T extends Record<string, unknown>>(obj: T, path: string, value: unknown): T;
+//# sourceMappingURL=path-util.d.ts.map

package/dist/device/path-util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-util.d.ts","sourceRoot":"","sources":["../../src/device/path-util.ts"],"names":[],"mappings":"AAKA;iDACiD;AACjD,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ7D;AAED;;;;;;;yEAOyE;AACzE,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,GAAG,EAAE,CAAC,EACN,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,CAAC,CAWH"}

package/dist/device/schema-fields.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export interface WireableField {
+    readonly path: string;
+    readonly kind: 'string' | 'number' | 'boolean' | 'enum';
+    readonly enumValues?: readonly string[];
+}
+/** Walk a cap status schema into flat wireable leaf fields (dotted paths).
+ *  Recurses into nested ZodObject (unwrapping nullable/optional/default first),
+ *  so fields with null live values are still offered. Arrays / unknown shapes
+ *  are skipped — never throws. */
+export declare function enumerateSchemaFields(schema: z.ZodType, prefix?: string): readonly WireableField[];
+//# sourceMappingURL=schema-fields.d.ts.map

package/dist/device/schema-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-fields.d.ts","sourceRoot":"","sources":["../../src/device/schema-fields.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAqBD;;;kCAGkC;AAClC,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,SAAK,GAAG,SAAS,aAAa,EAAE,CAa9F"}

package/dist/device/source-info.d.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * Identity envelope for a device's upstream-system metadata.
+ *
+ * Two jobs:
+ *
+ *   1. **Dispatch key.** `id` is the natural identifier the SOURCE system
+ *      uses to address this device (HA `entity_id`, Reolink MAC, ONVIF
+ *      WS-Discovery endpoint UUID, …). Provider code keeps a
+ *      `Map<sourceInfo.id, IDevice>` to route inbound push events in O(1)
+ *      without round-tripping through `stableId` / `id` mappings.
+ *
+ *   2. **Stability bridge.** `uniqueId` is the *immutable* upstream id when
+ *      one exists (HA `entity.unique_id`, Reolink MAC again — same as `id`
+ *      for vendors where MAC is the natural key). For systems where the
+ *      live dispatch key can be renamed (HA `entity_id` can be edited),
+ *      providers detect renames by matching `uniqueId` and patch `id`
+ *      in-place so dispatch keeps working.
+ *
+ * **Rendering metadata is NOT stored here.** Display fields (`unit`,
+ * `precision`) live in the cap STATUS SLICE so they flow live with every
+ * state push and are the single source of truth. The `device_class` tag is
+ * an HA-specific input that is consumed at the discovery boundary
+ * (`ha-domain-mapping`) to derive the CamStack `DeviceRole`; it is never
+ * stored after that point.
+ *
+ * The `raw` escape hatch carries provider-specific attributes that don't
+ * fit the structured slots (HA `attributes` whitelist, Reolink `deviceCache`
+ * details, …). Providers control what lands here.
+ */
+export declare const SourceInfoSchema: z.ZodObject<{
+    id: z.ZodString;
+    system: z.ZodString;
+    uniqueId: z.ZodOptional<z.ZodString>;
+    raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type SourceInfo = z.infer<typeof SourceInfoSchema>;
+/**
+ * Build the synthetic SourceInfo every existing provider falls back to
+ * when no upstream value has been persisted. Keeps non-migrated providers
+ * (Reolink / Hikvision / ONVIF / Frigate / RTSP) functional without code
+ * changes — `id` reuses the CamStack stableId, `system` reuses the addon
+ * id. Real upstream identity replaces this once a provider migrates and
+ * calls `updateSourceInfo()` with concrete values.
+ */
+export declare function synthesizeSourceInfo(input: {
+    stableId: string;
+    addonId: string;
+}): SourceInfo;
+/**
+ * Shallow-merge a partial patch over a prior SourceInfo. `undefined`
+ * patch values are ignored (no field clobber); to clear a field
+ * explicitly, providers omit it from the patch and rebuild from scratch
+ * via `updateSourceInfo({})` cycles — uncommon enough that we don't
+ * bother with a `null`-means-delete sentinel.
+ *
+ * The `raw` field is also shallow-merged: passing `raw: { foo: 1 }`
+ * merges over existing `raw` keys instead of replacing the whole bag.
+ */
+export declare function mergeSourceInfo(prev: SourceInfo, patch: Partial<SourceInfo>): SourceInfo;
+/**
+ * Coerce common unit-of-measurement string variants to a canonical form
+ * so the UI's display templates can rely on stable strings. Pure
+ * passthrough for unknown units — kept conservative on purpose, the goal
+ * is to normalise the long tail of HA `unit_of_measurement` values that
+ * have multiple historical spellings (`'°C'` vs `'C'` vs `'celsius'`).
+ *
+ * Extend the map as we encounter real-world data. Returning the raw
+ * input for unknown values is intentional: providers should never
+ * lose information silently here.
+ */
+export declare function normalizeUnit(raw: string | null | undefined): string | undefined;
+/**
+ * Key under which `SourceInfo` lives inside `DeviceMeta.metadata`. The
+ * blob is a free-form `Record<string, unknown>` shared with hardware-
+ * identity fields (`manufacturer`, `model`, `firmware`, …); SourceInfo
+ * lives under a single nested key to keep it composable with those.
+ */
+export declare const SOURCE_INFO_METADATA_KEY = "sourceInfo";
+/**
+ * Extract a SourceInfo from a `DeviceMeta.metadata` blob, validating
+ * with Zod. Returns `null` when the blob is missing or the nested
+ * `sourceInfo` key fails validation — callers fall back to the
+ * synthetic default in that case (see `synthesizeSourceInfo`).
+ */
+export declare function extractSourceInfoFromMetadata(metadata: Record<string, unknown> | null | undefined): SourceInfo | null;
+//# sourceMappingURL=source-info.d.ts.map

package/dist/device/source-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-info.d.ts","sourceRoot":"","sources":["../../src/device/source-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB;;;;;iBAiB3B,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,UAAU,CAKb;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAWxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAsChF;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAA;AAEpD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACnD,UAAU,GAAG,IAAI,CAOnB"}