@camstack/types 1.2.153 → 1.2.154

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-b8kBSOTT.js");
-const require_sleep = require("./sleep-TVipGseU.js");
+const require_sleep = require("./sleep-Dp0uukHR.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts
 /**

package/dist/addon.mjs

@@ -1,5 +1,5 @@
 import { t as EventCategory } from "./event-category-zAv7pMUz.mjs";
-import { D as adminUiCapability, E as DeviceType, G as scopeKey, H as ReadinessTimeoutError, M as expandCapMethods, R as nodePin, S as DEVICE_CHILDREN_BATCH_MAX, V as ReadinessRegistry, _t as DATAPLANE_SECRET_HEADER, a as asJsonObject, b as deviceOpsCapability, bt as BaseAddon, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as emitReadiness, x as viewerUiCapability, xt as normalizeAddonInitResult, yt as DisposerChain, z as readNodePin } from "./sleep-BRy4r7RG.mjs";
+import { D as adminUiCapability, E as DeviceType, G as scopeKey, H as ReadinessTimeoutError, M as expandCapMethods, R as nodePin, S as DEVICE_CHILDREN_BATCH_MAX, V as ReadinessRegistry, _t as DATAPLANE_SECRET_HEADER, a as asJsonObject, b as deviceOpsCapability, bt as BaseAddon, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as emitReadiness, x as viewerUiCapability, xt as normalizeAddonInitResult, yt as DisposerChain, z as readNodePin } from "./sleep-CgijQHtG.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts
 /**

package/dist/capabilities/index.d.ts

@@ -185,6 +185,7 @@ export { type IPressureSensorProvider, type PressureSensorStatus, PressureSensor
 export { type IPrivacyMaskProvider, type PrivacyMaskOptions, PrivacyMaskOptionsSchema, type PrivacyMaskPatch, PrivacyMaskPatchSchema, type PrivacyMaskRegion, PrivacyMaskRegionSchema, type PrivacyMaskShape, PrivacyMaskShapeSchema, type PrivacyMaskStatus, PrivacyMaskStatusSchema, privacyMaskCapability, summarisePrivacyAudio, } from './privacy-mask.cap.js';
 export { type IPtzProvider, PtzMoveCommandSchema, type PtzOptions, PtzOptionsSchema, PtzPositionSchema, PtzPresetSchema, type PtzStatus, PtzStatusSchema, ptzCapability, } from './ptz.cap.js';
 export { type IPtzAutotrackProvider, type PtzAutotrackRuntimeState, PtzAutotrackRuntimeStateSchema, type PtzAutotrackSettings, PtzAutotrackSettingsSchema, type PtzAutotrackStatus, PtzAutotrackStatusSchema, type PtzAutotrackTargetOption, PtzAutotrackTargetOptionSchema, ptzAutotrackCapability, } from './ptz-autotrack.cap.js';
+export { type INavigationProvider, NAVIGATION_ACTION_CATALOG, NAVIGATION_LIGHT_LEVEL_MAX, NAVIGATION_LIGHT_LEVEL_MIN, type NavigationActionEntry, NavigationActionEntrySchema, type NavigationActionId, NavigationActionIdSchema, navigationCapability, type NavigationEntryKind, NavigationEntryKindSchema, type NavigationFeatures, NavigationFeaturesSchema, type NavigationLightMode, NavigationLightModeSchema, type NavigationMode, NavigationModeSchema, type NavigationMoveCommand, NavigationMoveCommandSchema, type NavigationPoint, NavigationPointSchema, type NavigationRuntimeState, NavigationRuntimeStateSchema, type NavigationStatus, NavigationStatusSchema, } from './navigation.cap.js';
 export { type IRebootProvider, rebootCapability } from './reboot.cap.js';
 export { type IRecordingProvider, type LocateSegmentResult, LocateSegmentResultSchema, RECORDING_TIMELINE_BATCH_MAX, type ReadGopBytesResult, ReadGopBytesResultSchema, type ReadSegmentBytesResult, ReadSegmentBytesResultSchema, type ReadWindowBytesResult, ReadWindowBytesResultSchema, type RecordingAvailability, type RecordingAvailabilityForDevice, RecordingAvailabilityForDeviceSchema, RecordingAvailabilitySchema, type RecordingDays, type RecordingDaysForDevice, RecordingDaysForDeviceSchema, RecordingDaysSchema, type RecordingDeviceUsage, RecordingDeviceUsageSchema, type RecordingLocationUsage, RecordingLocationUsageSchema, type RecordingManifest, RecordingManifestSchema, RecordingRangeSchema, type RecordingRebalanceInput, RecordingRebalanceInputSchema, type RecordingRebalanceMove, RecordingRebalanceMoveSchema, type RecordingRebalancePlan, RecordingRebalancePlanSchema, type RecordingRebalanceSkip, type RecordingRebalanceSkipReason, RecordingRebalanceSkipReasonSchema, RecordingRebalanceSkipSchema, type RecordingStatus, RecordingStatusSchema, type RecordingStorageUsage, RecordingStorageUsageSchema, recordingCapability, } from './recording.cap.js';
 export { EXPORT_DENSE_MAX_RANGES, type ExportBytes, ExportBytesSchema, type ExportDense, type ExportDenseRange, ExportDenseRangeSchema, ExportDenseSchema, type ExportDownload, ExportDownloadSchema, type ExportOptions, ExportOptionsSchema, type ExportRecord, ExportRecordSchema, ExportSpeedSchema, type ExportState, ExportStateSchema, ExportTimelapseSchema, type IRecordingExportProvider, RECORDING_EXPORT_MAX_READ_BYTES, recordingExportCapability, } from './recording-export.cap.js';
@@ -301,6 +302,7 @@ import type { motionTriggerCapability } from './motion-trigger.cap.js';
 import type { motionZonesCapability } from './motion-zones.cap.js';
 import type { mqttBrokerCapability } from './mqtt-broker.cap.js';
 import type { nativeObjectDetectionCapability } from './native-object-detection.cap.js';
+import type { navigationCapability } from './navigation.cap.js';
 import type { networkAccessCapability } from './network-access.cap.js';
 import type { networkQualityCapability } from './network-quality.cap.js';
 import type { nodesCapability } from './nodes.cap.js';
@@ -364,6 +366,6 @@ import type { webrtcSessionCapability } from './webrtc-session.cap.js';
 import type { zoneAnalyticsCapability } from './zone-analytics.cap.js';
 import type { zoneRulesCapability } from './zone-rules.cap.js';
 import type { zonesCapability } from './zones.cap.js';
-type AnyCapability = typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageMigrationCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof logChannelsCapability | typeof logDestinationCapability | typeof loadContributionCapability | typeof failureContributionCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof consumablesCapability | typeof connectionTestCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof eventsCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingExportCapability | typeof deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof networkLinkCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability;
+type AnyCapability = typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageMigrationCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof logChannelsCapability | typeof logDestinationCapability | typeof loadContributionCapability | typeof failureContributionCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof navigationCapability | typeof consumablesCapability | typeof connectionTestCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof eventsCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingExportCapability | typeof deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof networkLinkCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability;
 export type CapabilityName = AnyCapability['name'];
 export type ITypedReadinessRegistry = IReadinessRegistry<CapabilityName>;

package/dist/capabilities/navigation.cap.d.ts

@@ -0,0 +1,463 @@
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+import { DeviceType } from '../device/device-type.js';
+/**
+ * `navigation` — a device-scoped capability that natively expresses the FULL
+ * navigation / action surface of a robot that DRIVES ITSELF and carries an
+ * on-board camera (the Dreame robot-vacuum camera is the first provider).
+ *
+ * Why a NEW cap rather than overloading `ptz`:
+ *   - `ptz` moves a *gimbal* on a fixed camera (pan/tilt/zoom of the lens). A
+ *     robot vacuum has no gimbal — the whole chassis drives, turns and spins.
+ *     The two are different physical models: PTZ is absolute-position + presets,
+ *     navigation is momentary drive nudges + discrete robot ACTIONS
+ *     (dock / spot-clean / follow-pet / go-to-point / …).
+ *   - This cap is the SOURCE OF TRUTH. Two consumers adapt from it rather than
+ *     the reverse:
+ *       1. a native CamStack navigation panel (data-driven from `listActions`
+ *          / `getOptions`), and
+ *       2. the PTZ surface — a thin adapter mimics `ptz` from `navigation` so a
+ *          robot camera shows up in the existing PTZ control path without every
+ *          PTZ provider learning about robots. The mapping lives in the adapter,
+ *          not here (see the addon design note):
+ *            ptz.continuousMove({pan,tilt}) → navigation.move({pan,tilt})
+ *            ptz.stop()                      → navigation.stop()
+ *            ptz.goHome()                    → navigation.runAction('goHome')
+ *            ptz.getPresets()                → navigation.listActions()  (id→preset)
+ *            ptz.goToPreset(id)              → navigation.runAction(id)
+ *
+ * ## Continuous drive
+ *
+ * `move` is MOMENTARY. Fluid navigation comes from the UI (or the PTZ adapter)
+ * sending `move({pan,tilt})` REPEATEDLY at ~1 Hz while a direction is held, and
+ * one `stop()` on release — exactly like the robot app's remote-drive joystick.
+ * The provider forwards EACH `move` to one drive write; it must NOT debounce or
+ * coalesce them. The UI owns the cadence.
+ *
+ * ## The action dictionary
+ *
+ * The discrete controls (dock / locate / spot-clean / follow / flash / sounds)
+ * are a DATA-DRIVEN dictionary the cap exposes via `listActions()`. Each entry
+ * carries `{ id, kind, label, icon }` (plus `soundId` for sound entries) so the
+ * native panel AND the PTZ mimic render buttons WITHOUT hardcoding a
+ * vendor-specific list. `kind: 'action'` entries are triggered with
+ * `runAction({ actionId })`; `kind: 'sound'` entries with `playSound({ soundId })`
+ * (the entry carries the `soundId` to pass). The general primitives — `move`,
+ * `stop`, `goToPoint` — stay as first-class methods, not dictionary entries.
+ *
+ * NOTE (provider wiring): the first provider (Dreame) drives this with the RAW
+ * `callAction(siid,aiid,in)` / `setProperty({siid,piid,value})` MIoT primitives
+ * that the currently-published `@apocaliss92/nodedreame` already exposes on
+ * every device handle. A future nodedreame publish adds a typed
+ * `DreameCameraController` (drive / playPetSound / spotClean / findPet / …); the
+ * provider can then swap the raw calls for the typed methods with no change to
+ * THIS contract.
+ */
+/**
+ * A momentary drive nudge. The robot MOVES (no gimbal) for as long as the caller
+ * keeps sending nudges (~1 Hz); an explicit `stop` (or letting the nudges lapse)
+ * halts it.
+ *
+ *   - `pan`   — turn: negative = left, positive = right, 0 = straight.
+ *   - `tilt`  — throttle: positive = forward, negative = spin / turn-around.
+ *   - `speed` — optional intensity hint [0, 1]; the provider may scale the drive
+ *               vector by it (drivers without proportional drive ignore it).
+ *
+ * `pan` / `tilt` are normalized [-1, 1]. Both optional so a caller can nudge one
+ * axis alone; an all-undefined nudge is a no-op.
+ */
+export declare const NavigationMoveCommandSchema: z.ZodObject<{
+    pan: z.ZodOptional<z.ZodNumber>;
+    tilt: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type NavigationMoveCommand = z.infer<typeof NavigationMoveCommandSchema>;
+/**
+ * The enumerated discrete actions a navigation-capable robot can perform via
+ * `runAction`. This is the CLOSED vocabulary; a given device advertises the
+ * subset it supports through `listActions`. Sounds are NOT here — they go through
+ * `playSound` (see the `sound` dictionary entries).
+ */
+export declare const NavigationActionIdSchema: z.ZodEnum<{
+    stop: "stop";
+    goHome: "goHome";
+    locate: "locate";
+    spotClean: "spotClean";
+    findPet: "findPet";
+    personFollow: "personFollow";
+    startClean: "startClean";
+    pauseClean: "pauseClean";
+    dockWash: "dockWash";
+    autoEmpty: "autoEmpty";
+    flashOn: "flashOn";
+    flashOff: "flashOff";
+}>;
+export type NavigationActionId = z.infer<typeof NavigationActionIdSchema>;
+/** Whether a dictionary entry is a `runAction` action or a `playSound` sound. */
+export declare const NavigationEntryKindSchema: z.ZodEnum<{
+    action: "action";
+    sound: "sound";
+}>;
+export type NavigationEntryKind = z.infer<typeof NavigationEntryKindSchema>;
+/**
+ * One entry in the navigation action dictionary — the DATA-DRIVEN unit both the
+ * native panel and the PTZ mimic render as a button.
+ *
+ *   - `id`      — stable id. For `kind:'action'` it is a {@link NavigationActionId}
+ *                 (pass to `runAction`); for `kind:'sound'` it is a namespaced id
+ *                 (`sound:meow`) whose `soundId` is passed to `playSound`.
+ *   - `icon`    — icon HINT (lucide-style name; the UI maps it to its own set).
+ *   - `label`   — operator-facing English label.
+ *   - `soundId` — wire sound id, present only on `kind:'sound'` entries.
+ *   - `enabled` — per-device FEATURE FLAG. `listActions` reports it so the UI /
+ *                 PTZ render ONLY enabled entries. Data-driven: the provider
+ *                 flips it from config, never by editing code.
+ */
+export declare const NavigationActionEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        action: "action";
+        sound: "sound";
+    }>;
+    label: z.ZodString;
+    icon: z.ZodString;
+    soundId: z.ZodOptional<z.ZodNumber>;
+    enabled: z.ZodBoolean;
+}, z.core.$strip>;
+export type NavigationActionEntry = z.infer<typeof NavigationActionEntrySchema>;
+/**
+ * Canonical dictionary of every navigation control (discrete actions + sounds)
+ * with its default label + icon hint. A provider filters this to the subset a
+ * device supports (and may override a label). Exported so the provider AND the
+ * UI share ONE list instead of re-deriving labels / ids independently.
+ *
+ * Icons are lucide-style hints; the viewer maps them to its own icon set. Every
+ * catalog default is `enabled: true`; a provider overrides per-device from
+ * config (data-driven — enabling / disabling one later is a config change, not a
+ * code change).
+ */
+export declare const NAVIGATION_ACTION_CATALOG: readonly NavigationActionEntry[];
+/** Coordinates for `goToPoint` — a point on the robot's live map. */
+export declare const NavigationPointSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>;
+export type NavigationPoint = z.infer<typeof NavigationPointSchema>;
+/**
+ * Per-device FEATURE-FLAG report for the general (non-dictionary) primitives.
+ * The cap reports which are enabled so the UI / PTZ render only the controls
+ * that are turned on for THIS device. Data-driven: the provider derives these
+ * from config + probe, never hardcoded in the UI. The per-DICTIONARY-entry flags
+ * live on {@link NavigationActionEntrySchema.enabled}; these gate the primitives
+ * that are not dictionary entries.
+ *
+ *   - `move` / `stop`   — the momentary drive joystick.
+ *   - `goToPoint`       — send-to-map-coordinate. Ships OFF on Dreame until the
+ *                         map-coordinate plumbing is wired.
+ *   - `runAction`       — the discrete action buttons (dictionary `kind:'action'`).
+ *   - `playSound`       — the sound buttons (dictionary `kind:'sound'`).
+ *   - `light`           — the on/off fill-light toggle (works anytime).
+ *   - `lightMode`       — the auto/manual selector + manual level slider (a
+ *                         camera-service control; needs an active stream).
+ */
+export declare const NavigationFeaturesSchema: z.ZodObject<{
+    move: z.ZodBoolean;
+    stop: z.ZodBoolean;
+    goToPoint: z.ZodBoolean;
+    runAction: z.ZodBoolean;
+    playSound: z.ZodBoolean;
+    light: z.ZodBoolean;
+    lightMode: z.ZodBoolean;
+}, z.core.$strip>;
+export type NavigationFeatures = z.infer<typeof NavigationFeaturesSchema>;
+/** Light mode: `auto` lets the camera choose brightness; `manual` uses `level`. */
+export declare const NavigationLightModeSchema: z.ZodEnum<{
+    auto: "auto";
+    manual: "manual";
+}>;
+export type NavigationLightMode = z.infer<typeof NavigationLightModeSchema>;
+/** Manual fill-light level bounds (the camera-service accepts 40..100). */
+export declare const NAVIGATION_LIGHT_LEVEL_MIN = 40;
+export declare const NAVIGATION_LIGHT_LEVEL_MAX = 100;
+/** Coarse work mode the robot reports — drives the UI's active-state chips. */
+export declare const NavigationModeSchema: z.ZodEnum<{
+    unknown: "unknown";
+    idle: "idle";
+    paused: "paused";
+    cleaning: "cleaning";
+    spot: "spot";
+    following: "following";
+    goto: "goto";
+    returning: "returning";
+}>;
+export type NavigationMode = z.infer<typeof NavigationModeSchema>;
+/**
+ * Live navigation state so the UI can reflect what the robot is doing:
+ *   - `mode`       — coarse activity (idle / cleaning / following / …).
+ *   - `following`  — person/pet follow is currently armed.
+ *   - `flash`      — the on-camera fill light is on.
+ *   - `lightMode`  — auto vs manual fill-light mode.
+ *   - `lightLevel` — manual fill-light level (40..100); meaningful when
+ *                    `lightMode === 'manual'`.
+ */
+export declare const NavigationStatusSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        unknown: "unknown";
+        idle: "idle";
+        paused: "paused";
+        cleaning: "cleaning";
+        spot: "spot";
+        following: "following";
+        goto: "goto";
+        returning: "returning";
+    }>;
+    following: z.ZodBoolean;
+    flash: z.ZodBoolean;
+    lightMode: z.ZodEnum<{
+        auto: "auto";
+        manual: "manual";
+    }>;
+    lightLevel: z.ZodNumber;
+    lastChangedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type NavigationStatus = z.infer<typeof NavigationStatusSchema>;
+/**
+ * Runtime-state slice owned by this cap (kernel-managed: validated, mirrored,
+ * observable). Adds `lastFetchedAt` on top of the status shape per the
+ * convention.
+ */
+export declare const NavigationRuntimeStateSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        unknown: "unknown";
+        idle: "idle";
+        paused: "paused";
+        cleaning: "cleaning";
+        spot: "spot";
+        following: "following";
+        goto: "goto";
+        returning: "returning";
+    }>;
+    following: z.ZodBoolean;
+    flash: z.ZodBoolean;
+    lightMode: z.ZodEnum<{
+        auto: "auto";
+        manual: "manual";
+    }>;
+    lightLevel: z.ZodNumber;
+    lastChangedAt: z.ZodNumber;
+    lastFetchedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type NavigationRuntimeState = z.infer<typeof NavigationRuntimeStateSchema>;
+export declare const navigationCapability: {
+    readonly name: "navigation";
+    readonly scope: "device";
+    readonly deviceNative: true;
+    readonly mode: "singleton";
+    readonly deviceTypes: readonly [DeviceType.Camera];
+    readonly deviceConfig: {
+        readonly ui: {
+            readonly kind: "widget";
+            readonly widgetId: "host/navigation-panel";
+            readonly tab: "navigation";
+            readonly topTab: true;
+            readonly label: "Navigation";
+            readonly order: 0;
+        };
+    };
+    readonly methods: {
+        /**
+         * Momentary drive nudge (the robot moves). `protected` — mirrors
+         * `ptz.continuousMove` so the Viewer navigation panel (and the PTZ-mimic
+         * path) works for any authenticated user, not admin-only. The UI sends
+         * these at ~1 Hz while a control is held; the provider forwards each one to
+         * a single drive write WITHOUT debouncing.
+         */
+        readonly move: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            pan: z.ZodOptional<z.ZodNumber>;
+            tilt: z.ZodOptional<z.ZodNumber>;
+            speed: z.ZodOptional<z.ZodNumber>;
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Halt all motion immediately (zero drive vector). */
+        readonly stop: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Send the robot to a point on its live map. */
+        readonly goToPoint: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Enumerate the discrete controls THIS device supports (data-driven UI +
+         * PTZ mimic). Camera-probed subset of {@link NAVIGATION_ACTION_CATALOG}.
+         */
+        readonly listActions: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                action: "action";
+                sound: "sound";
+            }>;
+            label: z.ZodString;
+            icon: z.ZodString;
+            soundId: z.ZodOptional<z.ZodNumber>;
+            enabled: z.ZodBoolean;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Run one discrete action (a `kind:'action'` dictionary entry). Invalid /
+         * unsupported action ids are rejected by the provider.
+         */
+        readonly runAction: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            actionId: z.ZodEnum<{
+                stop: "stop";
+                goHome: "goHome";
+                locate: "locate";
+                spotClean: "spotClean";
+                findPet: "findPet";
+                personFollow: "personFollow";
+                startClean: "startClean";
+                pauseClean: "pauseClean";
+                dockWash: "dockWash";
+                autoEmpty: "autoEmpty";
+                flashOn: "flashOn";
+                flashOff: "flashOff";
+            }>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Play a sound by its wire id (the `soundId` of a `kind:'sound'` entry). */
+        readonly playSound: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            soundId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Turn the on-camera fill light on / off (the `OpenFullLight` control —
+         * works anytime, no active stream required).
+         */
+        readonly setLightOn: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            on: z.ZodBoolean;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Set the fill-light mode (auto vs manual). `manual` optionally carries the
+         * initial `level`. The auto/manual + level control is a CAMERA-service
+         * action that generally needs an active camera stream/monitor session — the
+         * UI shows the manual level slider ONLY when `mode === 'manual'`.
+         */
+        readonly setLightMode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            mode: z.ZodEnum<{
+                auto: "auto";
+                manual: "manual";
+            }>;
+            level: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Set the MANUAL fill-light level (40..100). Implies `manual` mode. */
+        readonly setLightLevel: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            level: z.ZodNumber;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * Per-device FEATURE-FLAG report for the general primitives — drives which
+         * controls the UI shows (the per-entry flags for the dictionary come back on
+         * `listActions`).
+         */
+        readonly getFeatures: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            move: z.ZodBoolean;
+            stop: z.ZodBoolean;
+            goToPoint: z.ZodBoolean;
+            runAction: z.ZodBoolean;
+            playSound: z.ZodBoolean;
+            light: z.ZodBoolean;
+            lightMode: z.ZodBoolean;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+    };
+    readonly events: {
+        readonly onStatusChanged: {
+            readonly data: z.ZodObject<{
+                deviceId: z.ZodNumber;
+                status: z.ZodObject<{
+                    mode: z.ZodEnum<{
+                        unknown: "unknown";
+                        idle: "idle";
+                        paused: "paused";
+                        cleaning: "cleaning";
+                        spot: "spot";
+                        following: "following";
+                        goto: "goto";
+                        returning: "returning";
+                    }>;
+                    following: z.ZodBoolean;
+                    flash: z.ZodBoolean;
+                    lightMode: z.ZodEnum<{
+                        auto: "auto";
+                        manual: "manual";
+                    }>;
+                    lightLevel: z.ZodNumber;
+                    lastChangedAt: z.ZodNumber;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+        };
+    };
+    readonly status: {
+        readonly schema: z.ZodObject<{
+            mode: z.ZodEnum<{
+                unknown: "unknown";
+                idle: "idle";
+                paused: "paused";
+                cleaning: "cleaning";
+                spot: "spot";
+                following: "following";
+                goto: "goto";
+                returning: "returning";
+            }>;
+            following: z.ZodBoolean;
+            flash: z.ZodBoolean;
+            lightMode: z.ZodEnum<{
+                auto: "auto";
+                manual: "manual";
+            }>;
+            lightLevel: z.ZodNumber;
+            lastChangedAt: z.ZodNumber;
+        }, z.core.$strip>;
+        readonly kind: "push";
+    };
+    /**
+     * Runtime-state slice mirrored by the kernel. The navigation panel watches it
+     * for live mode / follow / flash changes.
+     */
+    readonly runtimeState: z.ZodObject<{
+        mode: z.ZodEnum<{
+            unknown: "unknown";
+            idle: "idle";
+            paused: "paused";
+            cleaning: "cleaning";
+            spot: "spot";
+            following: "following";
+            goto: "goto";
+            returning: "returning";
+        }>;
+        following: z.ZodBoolean;
+        flash: z.ZodBoolean;
+        lightMode: z.ZodEnum<{
+            auto: "auto";
+            manual: "manual";
+        }>;
+        lightLevel: z.ZodNumber;
+        lastChangedAt: z.ZodNumber;
+        lastFetchedAt: z.ZodNumber;
+    }, z.core.$strip>;
+    /**
+     * Runtime-state durability: **session** — like `vacuum-control`, a restored
+     * `mode: cleaning` / `following: true` is a robot that is not actually doing
+     * that. The live handle re-publishes on connect.
+     *
+     * See `RuntimeStateDurability`. Enforced by
+     * `scripts/check-runtime-state-durability.ts`.
+     */
+    readonly durability: "session";
+};
+export type INavigationProvider = InferProvider<typeof navigationCapability>;

package/dist/generated/addon-api.d.ts

@@ -71,6 +71,7 @@ import type { motionZonesCapability } from '../capabilities/motion-zones.cap.js'
 import type { motionCapability } from '../capabilities/motion.cap.js';
 import type { mqttBrokerCapability } from '../capabilities/mqtt-broker.cap.js';
 import type { nativeObjectDetectionCapability } from '../capabilities/native-object-detection.cap.js';
+import type { navigationCapability } from '../capabilities/navigation.cap.js';
 import type { networkAccessCapability } from '../capabilities/network-access.cap.js';
 import type { networkQualityCapability } from '../capabilities/network-quality.cap.js';
 import type { nodesCapability } from '../capabilities/nodes.cap.js';
@@ -4318,6 +4319,90 @@ export type AppRouter = TrpcCoreRouter<{
             meta: object;
         }>;
     }>>;
+    navigation: TRPCBuiltRouter<{
+        ctx: TrpcContext;
+        meta: object;
+        errorShape: AugmentedErrorShape;
+        transformer: true;
+    }, TRPCDecorateCreateRouterOptions<{
+        getStatus: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof DEVICE_STATUS_METHOD.getStatus.input>;
+            output: z.infer<typeof DEVICE_STATUS_METHOD.getStatus.output>;
+            meta: object;
+        }>;
+        move: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.move.input>;
+            output: z.infer<typeof navigationCapability.methods.move.output>;
+            meta: object;
+        }>;
+        stop: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.stop.input>;
+            output: z.infer<typeof navigationCapability.methods.stop.output>;
+            meta: object;
+        }>;
+        goToPoint: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.goToPoint.input>;
+            output: z.infer<typeof navigationCapability.methods.goToPoint.output>;
+            meta: object;
+        }>;
+        listActions: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.listActions.input>;
+            output: z.infer<typeof navigationCapability.methods.listActions.output>;
+            meta: object;
+        }>;
+        runAction: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.runAction.input>;
+            output: z.infer<typeof navigationCapability.methods.runAction.output>;
+            meta: object;
+        }>;
+        playSound: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.playSound.input>;
+            output: z.infer<typeof navigationCapability.methods.playSound.output>;
+            meta: object;
+        }>;
+        setLightOn: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.setLightOn.input>;
+            output: z.infer<typeof navigationCapability.methods.setLightOn.output>;
+            meta: object;
+        }>;
+        setLightMode: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.setLightMode.input>;
+            output: z.infer<typeof navigationCapability.methods.setLightMode.output>;
+            meta: object;
+        }>;
+        setLightLevel: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.setLightLevel.input>;
+            output: z.infer<typeof navigationCapability.methods.setLightLevel.output>;
+            meta: object;
+        }>;
+        getFeatures: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof navigationCapability.methods.getFeatures.input>;
+            output: z.infer<typeof navigationCapability.methods.getFeatures.output>;
+            meta: object;
+        }>;
+    }>>;
     networkAccess: TRPCBuiltRouter<{
         ctx: TrpcContext;
         meta: object;

package/dist/generated/cap-status-types.d.ts

@@ -42,6 +42,7 @@ import type { MotionTriggerStatusSchema } from '../capabilities/motion-trigger.c
 import type { motionZonesCapability } from '../capabilities/motion-zones.cap.js';
 import type { MqttBrokerStatusSchema } from '../capabilities/mqtt-broker.cap.js';
 import type { NativeObjectDetectionStatusSchema } from '../capabilities/native-object-detection.cap.js';
+import type { NavigationStatusSchema } from '../capabilities/navigation.cap.js';
 import type { NetworkLinkStatusSchema } from '../capabilities/network-link.cap.js';
 import type { NotifierStatusSchema } from '../capabilities/notifier.cap.js';
 import type { NumericSensorStatusSchema } from '../capabilities/numeric-sensor.cap.js';
@@ -117,6 +118,7 @@ export type CapStatusTypeMap = {
     readonly 'motion-zones': z.infer<(typeof motionZonesCapability)['status']['schema']>;
     readonly 'mqtt-broker': z.infer<typeof MqttBrokerStatusSchema>;
     readonly 'native-object-detection': z.infer<typeof NativeObjectDetectionStatusSchema>;
+    readonly 'navigation': z.infer<typeof NavigationStatusSchema>;
     readonly 'network-link': z.infer<typeof NetworkLinkStatusSchema>;
     readonly 'notifier': z.infer<typeof NotifierStatusSchema>;
     readonly 'numeric-sensor': z.infer<typeof NumericSensorStatusSchema>;
@@ -151,4 +153,4 @@ export type CapNameWithStatus = keyof CapStatusTypeMap;
  * aggregator to enumerate caps whose `status` should be polled +
  * streamed via `subscribeDeviceStatusAggregate`.
  */
-export declare const CAP_NAMES_WITH_STATUS: readonly ["accessories", "air-quality-sensor", "alarm-panel", "ambient-light-sensor", "automation-control", "battery", "binary", "brightness", "broker", "camera-credentials", "carbon-monoxide", "climate-control", "color", "connectivity", "consumables", "contact", "control", "cover", "day-night", "device-adoption", "device-discovery", "device-export", "device-status", "doorbell", "enum-sensor", "event-emitter", "fan-control", "feature-probe", "flood", "gas", "humidifier", "humidity-sensor", "image", "image-settings", "intercom", "lawn-mower-control", "lock-control", "media-player", "motion", "motion-trigger", "motion-zones", "mqtt-broker", "native-object-detection", "network-link", "notifier", "numeric-sensor", "osd", "pet-feeder", "power-meter", "presence", "pressure-sensor", "privacy-mask", "ptz", "ptz-autotrack", "recording", "scene-monitor", "script-runner", "smoke", "snapshot", "stream-params", "switch", "tamper", "temperature-sensor", "update", "vacuum-control", "valve", "vibration", "water-heater", "weather"];
+export declare const CAP_NAMES_WITH_STATUS: readonly ["accessories", "air-quality-sensor", "alarm-panel", "ambient-light-sensor", "automation-control", "battery", "binary", "brightness", "broker", "camera-credentials", "carbon-monoxide", "climate-control", "color", "connectivity", "consumables", "contact", "control", "cover", "day-night", "device-adoption", "device-discovery", "device-export", "device-status", "doorbell", "enum-sensor", "event-emitter", "fan-control", "feature-probe", "flood", "gas", "humidifier", "humidity-sensor", "image", "image-settings", "intercom", "lawn-mower-control", "lock-control", "media-player", "motion", "motion-trigger", "motion-zones", "mqtt-broker", "native-object-detection", "navigation", "network-link", "notifier", "numeric-sensor", "osd", "pet-feeder", "power-meter", "presence", "pressure-sensor", "privacy-mask", "ptz", "ptz-autotrack", "recording", "scene-monitor", "script-runner", "smoke", "snapshot", "stream-params", "switch", "tamper", "temperature-sensor", "update", "vacuum-control", "valve", "vibration", "water-heater", "weather"];