@camstack/types 1.2.267 → 1.2.268

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

@@ -97,6 +97,15 @@ export interface DeviceContext {
     /** Register a native provider for `cap` on the device this context belongs to.
      *  Multiple calls for the same cap throw. */
     registerNativeCap<TCap extends CapabilityDefinition>(cap: TCap, provider: InferNativeProvider<TCap>): void;
+    /**
+     * Remove the native provider THIS context registered for `capName` (D663: the composer ungrafts an added cap when a
+     * foreign native appears or the target is gone). OPTIONAL on the published interface: every `DeviceContext` fake in the
+     * repo keeps compiling, and an older hub that lacks it leaves the graft routable until the composer respawns — a
+     * tolerable degradation, recorded in D663's rollback note. No-op when another addon registered the cap. In a worker
+     * process that holds nothing for the cap, it retracts a binding a PREVIOUS incarnation of this addon left (a respawn):
+     * the hub drops only an entry this addon registered.
+     */
+    unregisterNativeCap?(capName: string): void;
 }
 /** Constructor type for BaseDevice subclasses.
  *

package/dist/device/device-runtime-state.d.ts

@@ -92,10 +92,24 @@ export type Snapshot = Readonly<Record<string, Readonly<Record<string, unknown>>
  * whose schema hasn't been installed yet are kept in-memory verbatim
  * and validated when the cap registers later.
  */
+export type RuntimeStateWriter = (capName: string, slice: Record<string, unknown>) => Promise<void>;
+/**
+ * Called when the hub REFUSES a write (the slice is not mirrored). The device
+ * logs it; the state re-sends the cap's next write even when the value is
+ * unchanged, so a refusal is never final (D391, ruling S6).
+ */
+export type RuntimeStateWriteFailed = (capName: string, error: string) => void;
 export declare class DeviceRuntimeState implements IDeviceRuntimeState {
     private readonly writer;
+    private readonly onWriteFailed;
     /** In-flight writer promises tracked so `flush()` can await them. */
     private readonly pendingWrites;
+    /**
+     * Caps whose last write the hub refused. The equality gate in
+     * `applyCapWrite` is bypassed for these, so the SAME value is re-sent on the
+     * next write instead of being swallowed forever; a landing write clears it.
+     */
+    private readonly failedWrites;
     /** Per-cap committed slice — after schema validation when known. */
     private slices;
     /** Per-cap registered schema (set by `installCapSchema`). */
@@ -103,7 +117,7 @@ export declare class DeviceRuntimeState implements IDeviceRuntimeState {
     private readonly listeners;
     private readonly capListeners;
     private constructor();
-    static fromInitial(initial: Record<string, unknown>, writer: (capName: string, slice: Record<string, unknown>) => Promise<void>): DeviceRuntimeState;
+    static fromInitial(initial: Record<string, unknown>, writer: RuntimeStateWriter, onWriteFailed?: RuntimeStateWriteFailed): DeviceRuntimeState;
     installCapSchema(capName: string, schema: z.ZodObject<z.core.$ZodLooseShape>): void;
     getCapState<T extends Record<string, unknown> = Record<string, unknown>>(capName: string): Readonly<T> | undefined;
     getCapField(capName: string, key: string): unknown;

package/dist/device/index.d.ts

@@ -25,7 +25,7 @@ export { REACHABILITY_FAILURES_TO_OFFLINE, REACHABILITY_POLL_INTERVAL_MS, REACHA
 export type { RuntimeStateBridge, RuntimeStateStaleReadPolicy, } from './runtime-state-helpers.js';
 export { createRuntimeStateBridge, OPERATOR_WRITTEN_STALE_MS, RUNTIME_STATE_REFRESH_MISS_COOLDOWN_MS, } from './runtime-state-helpers.js';
 export type { WireableField } from './schema-fields.js';
-export { enumerateItemArrayFields, enumerateSchemaFields } from './schema-fields.js';
+export { enumerateItemArrayFields, enumerateSchemaFields, unwrapSchema } from './schema-fields.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';
 export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
 export type { SiteZone } from './site-zone.js';

package/dist/device-extension/slot-descriptor.d.ts

@@ -10,20 +10,19 @@
  * collection contract that lists and writes them. The contract persists
  * NOTHING: each slot is served by the addon that owns its store (D62).
  *
- * Two shapes:
+ * One shape, `association` — the host LISTS other devices (a camera's linked
+ * devices, its doorbell trigger sources). Removing every source is "off";
+ * there is no separate switch.
  *
- *  - `association` — the host LISTS other devices (a camera's linked devices,
- *    its doorbell trigger sources). Removing every source is "off"; there is
- *    no separate switch.
- *  - `graft` — the host GAINS a whole capability (`projects`), registered
- *    natively by the host's own provider from sources it owns. Declared here
- *    so the contract has room for it; the first graft (HA consumables) is
- *    slice 2, and a graft carries its own `enabled` switch.
+ * A host that GAINS a whole capability from other devices is not a slot: that
+ * is a COMPOSITION (D663, amends D648). D648 reserved a `graft` shape for it
+ * (with a `projects` cap and an `enabled` switch); none was ever implemented,
+ * and it was retired in favour of composed devices and device customization.
  */
 import type { z } from 'zod';
 import type { DeviceType } from '../device/device-type.js';
 /** How a slot extends its host. See the module docblock. */
-export type ExtensionSlotShape = 'association' | 'graft';
+export type ExtensionSlotShape = 'association';
 /** How many sources a slot takes. */
 export type ExtensionSlotCardinality = 'one' | 'many';
 /**
@@ -55,8 +54,6 @@ export interface ExtensionSlotDescriptor<TValue extends z.ZodObject = z.ZodObjec
      */
     readonly sourceCaps: readonly string[] | 'any';
     readonly cardinality: ExtensionSlotCardinality;
-    /** graft only — MUST equal the declaring cap's `name` (guarded). */
-    readonly projects?: string;
     /** The slot's editable value. See the interface docblock. */
     readonly value: TValue;
 }

package/dist/device-extension/slot-provider.d.ts

@@ -24,8 +24,6 @@ export type ExtensionSlotValueOf<Id extends ExtensionSlotId> = Extract<Extension
 export interface ExtensionSlotListing<Id extends ExtensionSlotId> {
     /** The store written (D62), `<addon>:<key>`. */
     readonly authority: string;
-    /** graft: its switch; association: null. */
-    readonly enabled: boolean | null;
     readonly activation: ExtensionSlotActivation | null;
     readonly value: ExtensionSlotValueOf<Id>;
     readonly sources: readonly ExtensionSlotSource[];

package/dist/enums/event-category.d.ts

@@ -360,6 +360,16 @@ export declare enum EventCategory {
      * without filtering on `capName`.
      */
     DeviceStateChanged = "device.state-changed",
+    /**
+     * The NATIVE shadow of a cap a composition has claimed fields of moved
+     * (D663). Payload: `{ deviceId, capName, native }` — what the provider
+     * wrote, BEFORE the owned fields are overlaid. Owner-only (D224): it is for
+     * the composer's native self-reads, and the public event routers refuse it
+     * (`isOwnerOnlyEventCategory`) so no consumer surface ever shows a second
+     * truth beside the merged `DeviceStateChanged.slice`. Emitted only under a
+     * `replace` claim, one per native write of that cap.
+     */
+    DeviceNativeShadowChanged = "device.native-shadow-changed",
     /**
      * Frame occupancy for a camera CHANGED — a tracked object was gained or
      * lost. Carries `{ deviceId, totalObjects, byClass, zones }`.
@@ -686,3 +696,18 @@ export declare enum EventCategory {
      */
     ModelConvertProgress = "model-convert.progress"
 }
+/**
+ * Categories that never leave the hub's trusted addon closure: the public
+ * event routers (`systemEvents.*`, `live.*`) refuse them in every path, so a
+ * UI or a share-scope subscriber cannot receive them by omitting the category
+ * filter. Add a category here when its payload is a truth only one owner may
+ * read (D224).
+ */
+export declare const OWNER_ONLY_EVENT_CATEGORIES: ReadonlySet<string>;
+export declare function isOwnerOnlyEventCategory(category: string): boolean;
+/**
+ * Every category a PUBLIC surface may offer or show — the enum minus the
+ * owner-only set, unique, sorted. A picker built from the raw enum would offer
+ * a filter that can never match, because the routers refuse that category.
+ */
+export declare function publicEventCategories(): readonly string[];

package/dist/enums.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_category = require("./event-category-BVfsrBYA.js");
+const require_event_category = require("./event-category-MbnB-6AN.js");
 //#region src/enums/event-source-type.ts
 var EventSourceType = /* @__PURE__ */ function(EventSourceType) {
 	EventSourceType["Addon"] = "addon";

package/dist/enums.mjs

@@ -1,4 +1,4 @@
-import { t as EventCategory } from "./event-category-BVDXG4tB.mjs";
+import { t as EventCategory } from "./event-category-C5xZWqz6.mjs";
 //#region src/enums/event-source-type.ts
 var EventSourceType = /* @__PURE__ */ function(EventSourceType) {
 	EventSourceType["Addon"] = "addon";

package/dist/err-msg-DX6i_MY4.mjs

@@ -0,0 +1,339 @@
+//#region src/device/device-type.ts
+var DeviceType = /* @__PURE__ */ function(DeviceType) {
+	DeviceType["Camera"] = "camera";
+	DeviceType["Hub"] = "hub";
+	DeviceType["Light"] = "light";
+	DeviceType["Siren"] = "siren";
+	DeviceType["Switch"] = "switch";
+	DeviceType["Sensor"] = "sensor";
+	DeviceType["Thermostat"] = "thermostat";
+	/** Air-conditioner / heat-pump climate device (HVAC) — shares the
+	*  `climate-control` cap surface with `Thermostat` but renders a
+	*  dedicated AC-appropriate control UI (mode chips, fan speed,
+	*  independent vertical/horizontal swing). Sources: native Gree, and
+	*  reusable by other AC integrations. */
+	DeviceType["Climate"] = "climate";
+	DeviceType["Button"] = "button";
+	/** 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). */
+	DeviceType["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). */
+	DeviceType["Update"] = "update";
+	DeviceType["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. */
+	DeviceType["Notifier"] = "notifier";
+	/** Pre-recorded action sequence with optional parameters
+	*  (HA `script.*`). Runnable via `script-runner` cap. */
+	DeviceType["Script"] = "script";
+	/** Automation rule (HA `automation.*`) — enable/disable + manual
+	*  trigger surface exposed via `automation-control` cap. */
+	DeviceType["Automation"] = "automation";
+	/** Door / smart lock device (HA `lock.*`). `lock-control` cap. */
+	DeviceType["Lock"] = "lock";
+	/** Window covering, blinds, garage door, valve, etc. (HA `cover.*`,
+	*  `valve.*`). `cover` cap with sub-roles for variant. */
+	DeviceType["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. */
+	DeviceType["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. */
+	DeviceType["Humidifier"] = "humidifier";
+	/** Water heater / boiler with target temperature + operation mode +
+	*  away mode (HA `water_heater.*`). `water-heater` cap — a
+	*  climate-family actuator. */
+	DeviceType["WaterHeater"] = "water-heater";
+	/** Ceiling / standing / exhaust fan (HA `fan.*`). `fan-control` cap. */
+	DeviceType["Fan"] = "fan";
+	/** Audio / video playback endpoint (HA `media_player.*`). Disjoint from
+	*  the camera surface — those use `Camera`. `media-player` cap. */
+	DeviceType["MediaPlayer"] = "media-player";
+	/** Security panel / alarm system (HA `alarm_control_panel.*`).
+	*  `alarm-panel` cap. */
+	DeviceType["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. */
+	DeviceType["Control"] = "control";
+	/** Person / device-tracker presence (HA `person.*`, `device_tracker.*`).
+	*  `presence` cap. */
+	DeviceType["Presence"] = "presence";
+	/** Weather provider (HA `weather.*`). Tier-3, low MVP priority.
+	*  `weather` cap. */
+	DeviceType["Weather"] = "weather";
+	/** Robot vacuum (HA `vacuum.*`). Tier-3. `vacuum-control` cap. */
+	DeviceType["Vacuum"] = "vacuum";
+	/** Robotic lawn mower (HA `lawn_mower.*`). Tier-3.
+	*  `lawn-mower-control` cap. */
+	DeviceType["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. */
+	DeviceType["Container"] = "container";
+	/** Single still-image entity (HA `image.*`). Read-only display of an
+	*  `entity_picture` signed URL the browser loads directly. `image` cap. */
+	DeviceType["Image"] = "image";
+	/** Smart pet feeder — cloud-connected food dispenser with a bowl food
+	*  level, battery, desiccant life, feeding state and manual-feed /
+	*  call-pet / maintenance actions. Installed with the `pet-feeder` cap;
+	*  dual-hopper models (D4S/D4SH) expose per-hopper portions. Sources:
+	*  native PetKit (`nodepetkit` `FeederDevice`), reusable by other feeder
+	*  integrations sharing the same food/desiccant/hopper surface. */
+	DeviceType["PetFeeder"] = "pet-feeder";
+	return DeviceType;
+}({});
+var DeviceFeature = /* @__PURE__ */ function(DeviceFeature) {
+	DeviceFeature["BatteryOperated"] = "battery-operated";
+	DeviceFeature["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.
+	*/
+	DeviceFeature["Resyncable"] = "resyncable";
+	DeviceFeature["NativeSnapshot"] = "native-snapshot";
+	DeviceFeature["DoorbellButton"] = "doorbell-button";
+	DeviceFeature["TwoWayAudio"] = "two-way-audio";
+	DeviceFeature["PanTiltZoom"] = "pan-tilt-zoom";
+	/**
+	* Camera supports the on-firmware autotrack subsystem (subject-
+	* following). Distinct from `PanTiltZoom` because not every PTZ
+	* camera ships autotrack — the admin UI uses this flag to gate
+	* the autotrack toggle / settings card without re-deriving from
+	* the cap registry. Mirrors `ptz-autotrack` cap registration:
+	* driver sets this feature when probe confirms the firmware
+	* surface, and registers the cap in the same code path.
+	*/
+	DeviceFeature["PtzAutotrack"] = "ptz-autotrack";
+	/**
+	* Accessory exposes a "trigger on motion" toggle — the parent camera's
+	* motion detection automatically activates this device. Mirrors
+	* `motion-trigger` cap registration: drivers set this feature in the
+	* same code path that calls `ctx.registerNativeCap(motionTriggerCapability, ...)`.
+	*
+	* Used by admin UI (gate the in-hero `MotionTriggerToggle` against a
+	* fast scalar without binding fetch), notifier rules, and `listAll`
+	* filters that want "all devices with on-motion behaviour".
+	*/
+	DeviceFeature["MotionTrigger"] = "motion-trigger";
+	/** Light supports rgb-triplet color via `color` cap. */
+	DeviceFeature["LightColorRgb"] = "light-color-rgb";
+	/** Light supports HSV color via `color` cap. */
+	DeviceFeature["LightColorHsv"] = "light-color-hsv";
+	/** Light supports color-temperature (mired) via `color` cap. */
+	DeviceFeature["LightColorMired"] = "light-color-mired";
+	/** Thermostat supports a `heat_cool` dual setpoint (targetLow +
+	*  targetHigh). Gates the range slider UI. */
+	DeviceFeature["ClimateDualSetpoint"] = "climate-dual-setpoint";
+	/** Thermostat exposes target humidity and/or current humidity
+	*  readings. Gates the humidity controls. */
+	DeviceFeature["ClimateHumidity"] = "climate-humidity";
+	/** Thermostat exposes a fan-mode selector. */
+	DeviceFeature["ClimateFanMode"] = "climate-fan-mode";
+	/** Thermostat exposes preset modes (eco / away / sleep / vendor). */
+	DeviceFeature["ClimatePreset"] = "climate-preset";
+	/** Thermostat exposes a vertical louver swing toggle. Gates the
+	*  vertical-swing switch in the climate UI. Independent of horizontal. */
+	DeviceFeature["ClimateSwingVertical"] = "climate-swing-vertical";
+	/** Thermostat exposes a horizontal louver swing toggle. Gates the
+	*  horizontal-swing switch in the climate UI. Independent of vertical. */
+	DeviceFeature["ClimateSwingHorizontal"] = "climate-swing-horizontal";
+	/** Cover exposes intermediate position control (0..100). Gates the
+	*  position slider UI. */
+	DeviceFeature["CoverPositionable"] = "cover-positionable";
+	/** Cover exposes slat-tilt control. Gates the tilt slider UI. */
+	DeviceFeature["CoverTilt"] = "cover-tilt";
+	/** Valve exposes intermediate position control (0..100). Gates the
+	*  position slider / drag surface UI. */
+	DeviceFeature["ValvePositionable"] = "valve-positionable";
+	/** Fan exposes a speed-percentage setter. Gates the speed slider UI. */
+	DeviceFeature["FanSpeed"] = "fan-speed";
+	/** Fan exposes a preset mode selector. */
+	DeviceFeature["FanPreset"] = "fan-preset";
+	/** Fan exposes blade direction (forward/reverse) — typical of
+	*  ceiling fans. */
+	DeviceFeature["FanDirection"] = "fan-direction";
+	/** Fan exposes an oscillation toggle. */
+	DeviceFeature["FanOscillating"] = "fan-oscillating";
+	/** Lock requires a PIN code on lock/unlock. Gates the code-entry
+	*  field on the UI lock-controls panel. */
+	DeviceFeature["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. */
+	DeviceFeature["LockOpen"] = "lock-open";
+	/** Media player exposes a seek-to-position surface. */
+	DeviceFeature["MediaPlayerSeek"] = "media-player-seek";
+	/** Media player exposes a volume-level setter. */
+	DeviceFeature["MediaPlayerVolume"] = "media-player-volume";
+	/** Media player exposes a mute toggle distinct from volume=0. */
+	DeviceFeature["MediaPlayerMute"] = "media-player-mute";
+	/** Media player exposes a shuffle toggle. */
+	DeviceFeature["MediaPlayerShuffle"] = "media-player-shuffle";
+	/** Media player exposes a repeat mode (off / all / one). */
+	DeviceFeature["MediaPlayerRepeat"] = "media-player-repeat";
+	/** Media player exposes a source / input selector. */
+	DeviceFeature["MediaPlayerSelectSource"] = "media-player-select-source";
+	/** Media player exposes a play-arbitrary-media surface (URL / id). */
+	DeviceFeature["MediaPlayerPlayMedia"] = "media-player-play-media";
+	/** Media player exposes next-track. */
+	DeviceFeature["MediaPlayerNext"] = "media-player-next";
+	/** Media player exposes previous-track. */
+	DeviceFeature["MediaPlayerPrevious"] = "media-player-previous";
+	/** Media player exposes stop distinct from pause. */
+	DeviceFeature["MediaPlayerStop"] = "media-player-stop";
+	/** Alarm panel requires a PIN code on arm/disarm. */
+	DeviceFeature["AlarmPinRequired"] = "alarm-pin-required";
+	/** Presence device carries GPS coordinates (lat/lng/accuracy) in
+	*  addition to a textual location. */
+	DeviceFeature["PresenceGps"] = "presence-gps";
+	/** Notifier accepts an inline / URL image attachment. */
+	DeviceFeature["NotifierImage"] = "notifier-image";
+	/** Notifier accepts a priority hint (high/normal/low). */
+	DeviceFeature["NotifierPriority"] = "notifier-priority";
+	/** Notifier accepts a free-form `data` payload for platform-specific
+	*  fields. */
+	DeviceFeature["NotifierData"] = "notifier-data";
+	/** Notifier supports interactive action buttons / callbacks. */
+	DeviceFeature["NotifierActions"] = "notifier-actions";
+	/** Notifier supports per-call recipient targeting (multi-user). */
+	DeviceFeature["NotifierRecipients"] = "notifier-recipients";
+	/** Script runner accepts a variables map on each run invocation. */
+	DeviceFeature["ScriptVariables"] = "script-variables";
+	/** Automation `trigger` accepts a skipCondition flag — fires the
+	*  automation's actions while bypassing its condition block. */
+	DeviceFeature["AutomationSkipCondition"] = "automation-skip-condition";
+	/** Robot vacuum exposes a live cleaning map (image child). Gates the
+	*  map tile in the vacuum UI. */
+	DeviceFeature["VacuumHasMap"] = "vacuum-has-map";
+	/** Robot vacuum exposes AI obstacle-detection toggles. Gates the AI
+	*  switches group. */
+	DeviceFeature["VacuumHasAi"] = "vacuum-has-ai";
+	/** Robot mower exposes a live mowing map (SVG image child). Gates the
+	*  mower map tile. */
+	DeviceFeature["MowerHasMap"] = "mower-has-map";
+	/** Robot mower exposes targeted mowing (all-area / zones / edges /
+	*  spots) — gates the Mow action + map selectors. */
+	DeviceFeature["MowerHasTargetedMowing"] = "mower-has-targeted-mowing";
+	return DeviceFeature;
+}({});
+var ChargingStatus = /* @__PURE__ */ function(ChargingStatus) {
+	ChargingStatus["ChargingDC"] = "charging-dc";
+	ChargingStatus["ChargingSolar"] = "charging-solar";
+	ChargingStatus["NotCharging"] = "not-charging";
+	return ChargingStatus;
+}({});
+/**
+* Semantic role a device plays within its parent. Populated by driver
+* addons when creating accessory devices (Reolink siren/floodlight/
+* PIR/chime/autotrack/doorbell, ONVIF relay outputs, …). Used by the
+* admin UI to pick icons, labels, and widgets — a `Switch` with
+* `role: Floodlight` renders as a bulb with a brightness slider,
+* whereas a `Switch` with `role: Siren` renders as a klaxon.
+*
+* Undefined for top-level devices (cameras, NVRs, hubs). Persisted in
+* sqlite as a nullable TEXT column — old rows keep working unchanged.
+*/
+var DeviceRole = /* @__PURE__ */ function(DeviceRole) {
+	DeviceRole["Siren"] = "siren";
+	DeviceRole["Floodlight"] = "floodlight";
+	DeviceRole["Spotlight"] = "spotlight";
+	DeviceRole["PirSensor"] = "pir-sensor";
+	DeviceRole["Chime"] = "chime";
+	DeviceRole["Autotrack"] = "autotrack";
+	DeviceRole["Nightvision"] = "nightvision";
+	DeviceRole["PrivacyMask"] = "privacy-mask";
+	DeviceRole["Doorbell"] = "doorbell";
+	/** Virtual HA toggle (input_boolean.*) — distinguishable from a
+	*  real Switch device for UI rendering / export adapters. */
+	DeviceRole["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. */
+	DeviceRole["MotionSensor"] = "motion-sensor";
+	DeviceRole["ContactSensor"] = "contact-sensor";
+	DeviceRole["LeakSensor"] = "leak-sensor";
+	DeviceRole["SmokeSensor"] = "smoke-sensor";
+	DeviceRole["COSensor"] = "co-sensor";
+	DeviceRole["GasSensor"] = "gas-sensor";
+	DeviceRole["TamperSensor"] = "tamper-sensor";
+	DeviceRole["VibrationSensor"] = "vibration-sensor";
+	DeviceRole["ConnectivitySensor"] = "connectivity-sensor";
+	DeviceRole["SoundSensor"] = "sound-sensor";
+	/** Fallback for `binary_sensor` without a known `device_class`. */
+	DeviceRole["BinarySensor"] = "binary-sensor";
+	DeviceRole["TemperatureSensor"] = "temperature-sensor";
+	DeviceRole["HumiditySensor"] = "humidity-sensor";
+	DeviceRole["AmbientLightSensor"] = "ambient-light-sensor";
+	DeviceRole["PressureSensor"] = "pressure-sensor";
+	/** Wind speed or direction (weather-station `wind-sensor` cap). */
+	DeviceRole["WindSensor"] = "wind-sensor";
+	/** Rain accumulation or rate (weather-station `rain-sensor` cap). */
+	DeviceRole["RainSensor"] = "rain-sensor";
+	/** UV index (weather-station `uv-sensor` cap). */
+	DeviceRole["UvSensor"] = "uv-sensor";
+	/** Solar irradiance W/m² (weather-station `solar-radiation-sensor` cap).
+	*  Distinct from AmbientLightSensor (lux). */
+	DeviceRole["SolarRadiationSensor"] = "solar-radiation-sensor";
+	/** Soil moisture % (garden/weather `soil-moisture-sensor` cap). */
+	DeviceRole["SoilMoistureSensor"] = "soil-moisture-sensor";
+	DeviceRole["PowerSensor"] = "power-sensor";
+	DeviceRole["EnergySensor"] = "energy-sensor";
+	DeviceRole["VoltageSensor"] = "voltage-sensor";
+	DeviceRole["CurrentSensor"] = "current-sensor";
+	DeviceRole["AirQualitySensor"] = "air-quality-sensor";
+	/** Battery level (numeric % via `sensor` OR low-bool via
+	*  `binary_sensor` — the cap distinguishes via the value type). */
+	DeviceRole["BatterySensor"] = "battery-sensor";
+	/** Fallback for `sensor` numeric without a known `device_class`. */
+	DeviceRole["NumericSensor"] = "numeric-sensor";
+	/** String / enum state (HA `sensor` with `state_class: enum` or
+	*  `attributes.options`). */
+	DeviceRole["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. */
+	DeviceRole["DateTimeSensor"] = "datetime-sensor";
+	/** Last-resort fallback when nothing else matches. */
+	DeviceRole["GenericSensor"] = "generic-sensor";
+	DeviceRole["NumericControl"] = "numeric-control";
+	DeviceRole["SelectControl"] = "select-control";
+	DeviceRole["TextControl"] = "text-control";
+	DeviceRole["DateTimeControl"] = "datetime-control";
+	/** Mobile push notifier (HA `notify.mobile_app_*`) — supports
+	*  rich features (image, priority, channel routing). */
+	DeviceRole["MobilePushNotifier"] = "mobile-push-notifier";
+	/** Chat / messaging service (HA `notify.telegram_*`,
+	*  `notify.discord_*`, etc.). */
+	DeviceRole["MessagingNotifier"] = "messaging-notifier";
+	/** Email-based delivery (HA `notify.smtp`, etc.). */
+	DeviceRole["EmailNotifier"] = "email-notifier";
+	/** Fallback when the notifier service name doesn't match a known
+	*  pattern. */
+	DeviceRole["GenericNotifier"] = "generic-notifier";
+	return DeviceRole;
+}({});
+//#endregion
+//#region src/utils/err-msg.ts
+/**
+import { errMsg } from '@camstack/types'
+* Extract a human-readable message from an unknown error value.
+* Replaces the ubiquitous `errMsg(err)` pattern.
+*/
+function errMsg(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	return String(err);
+}
+//#endregion
+export { DeviceType as a, DeviceRole as i, ChargingStatus as n, DeviceFeature as r, errMsg as t };