@camstack/addon-provider-gree 0.2.77 → 0.2.79

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/addon.js +621 -488
  2. package/dist/addon.mjs +621 -488
  3. package/package.json +1 -1
package/dist/addon.js CHANGED
@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  let dgram = require("dgram");
3
3
  let crypto$1 = require("crypto");
4
4
  let events = require("events");
5
- //#region ../types/dist/event-category-zAv7pMUz.mjs
5
+ //#region ../types/dist/event-category-CnLqLOKs.mjs
6
6
  var EventCategory = /* @__PURE__ */ function(EventCategory) {
7
7
  EventCategory["SystemBoot"] = "system.boot";
8
8
  EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -197,6 +197,19 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
197
197
  EventCategory["ProcessCrashed"] = "process.crashed";
198
198
  EventCategory["ProcessRestartScheduled"] = "process.restart_scheduled";
199
199
  EventCategory["ProcessRestarted"] = "process.restarted";
200
+ /**
201
+ * The SET of storage locations changed — one was created, edited, enabled,
202
+ * disabled or deleted through `storage.upsertLocation` / `deleteLocation`.
203
+ *
204
+ * Telemetry, not a transaction (D8/D11): every consumer that re-resolves on
205
+ * it must also converge on its own periodic path, because a dropped event
206
+ * must not leave a node writing to yesterday's disk set forever. It exists
207
+ * because there was NO signal at all — an operator who added a second
208
+ * recordings disk in the admin UI got nothing, and the recorder kept its
209
+ * resolved locations until something else happened to re-resolve them
210
+ * (D387). Payload `StorageLocationsChangedPayload`.
211
+ */
212
+ EventCategory["StorageLocationsChanged"] = "storage.locations-changed";
200
213
  EventCategory["RecordingStarted"] = "recording.started";
201
214
  EventCategory["RecordingStopped"] = "recording.stopped";
202
215
  EventCategory["RecordingError"] = "recording.error";
@@ -7618,111 +7631,6 @@ var CameraSwitchGroupSchema = object({
7618
7631
  fetchedAt: number()
7619
7632
  });
7620
7633
  /**
7621
- * Per-component log CHANNELS — the gate a hot path consults, and the registry
7622
- * an addon declares its channels in.
7623
- *
7624
- * ## Two axes, deliberately separated
7625
- *
7626
- * - **DECLARATION** — which channels exist. Only the addon knows:
7627
- * `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
7628
- * baichuan/handshake. A hand-wired central list rots at the first addition,
7629
- * and rots silently. So a channel is declared where it is consulted, and the
7630
- * `log-channels` capability enumerates the declarations.
7631
- * - **VALUE** — at which level, for which scope, until when. That stays ONE
7632
- * thing: the logging settings document on the `system` cap. Two authorities
7633
- * over the values is the exact defect
7634
- * `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
7635
- * remove; re-introducing it from the cure side would be grotesque.
7636
- *
7637
- * Nothing in this file reads a clock, an env var or a store. The registry is
7638
- * a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
7639
- * the hot path with a value somebody actually read, and by
7640
- * {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
7641
- * never reaches here, so it can neither disarm an armed channel nor arm a
7642
- * disarmed one (D49).
7643
- *
7644
- * ## The canonical call shape
7645
- *
7646
- * ```ts
7647
- * if (CH_RTP.on && CH_RTP.wants(deviceId)) {
7648
- * CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
7649
- * }
7650
- * ```
7651
- *
7652
- * `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
7653
- * read. Disarmed, a call site costs one load and one branch, and the `extras`
7654
- * object literal is never constructed because it lives inside the branch. It
7655
- * is the same shape already proven in production at `stream-broker.ts:1650`,
7656
- * and the same discipline `LoggingGate.allowsDestination` uses for the
7657
- * destination floor (measured at 1.93 ns/call when off).
7658
- *
7659
- * ## Why a channel emits at `info`
7660
- *
7661
- * `loki-logging.addon.ts` pins the destination default at `info` and
7662
- * `loki-destination.ts` drops everything below it, so a line emitted at
7663
- * `debug` never reaches Loki and the hub's in-memory ring only holds ~35
7664
- * minutes. A diagnostic that cannot be read an hour later is worse than no
7665
- * diagnostic, because it looks done. {@link LogChannelGate.log} therefore
7666
- * emits at the channel's declared level, whose schema floor is `info`.
7667
- */
7668
- /**
7669
- * The level a channel writes at once armed.
7670
- *
7671
- * `debug` is absent ON PURPOSE and not by omission: below `info` the line does
7672
- * not leave the process for Loki, and the whole point of arming a channel is
7673
- * to read it later.
7674
- */
7675
- var LogChannelLevelSchema = _enum([
7676
- "info",
7677
- "warn",
7678
- "error"
7679
- ]);
7680
- /**
7681
- * What an addon declares about one channel. No value, no state — a
7682
- * declaration is inert.
7683
- */
7684
- var LogChannelDescriptorSchema = object({
7685
- /**
7686
- * Dotted `area.thing`, unique across the workspace. `area` is conventionally
7687
- * the addon's short name so an operator reading a channel list can tell who
7688
- * owns it without a second lookup.
7689
- */
7690
- name: string().min(3).regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/, "a channel name is dotted lower-kebab, e.g. area.thing"),
7691
- /** One sentence: what the operator will SEE after arming it. */
7692
- description: string().min(1),
7693
- /** The level its lines are emitted at. Never below `info`. */
7694
- defaultLevel: LogChannelLevelSchema,
7695
- /**
7696
- * Whether this channel can be narrowed to a camera.
7697
- *
7698
- * `true` is a PROMISE with two halves, and both must hold: the gate is
7699
- * consulted with the numeric device id, AND every line the channel admits
7700
- * carries `tags: { deviceId }` with that same numeric id. The second half is
7701
- * what makes `| json | deviceId="617"` work in Loki — `loki-payload.ts`
7702
- * keeps `deviceId` out of the stream labels for cardinality, so the tag in
7703
- * the body is the only way to filter.
7704
- *
7705
- * A channel whose lines carry the device only in `meta` (or not at all) is
7706
- * declared `false`. Declaring it `true` anyway would be a lie the UI repeats:
7707
- * the operator narrows to one camera, sees nothing, and concludes the code
7708
- * path was never taken.
7709
- */
7710
- perDevice: boolean()
7711
- });
7712
- /**
7713
- * An armed window over one channel, as the document hands it to a mirror.
7714
- *
7715
- * A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
7716
- * expires by itself, which is the one failure a boolean cannot avoid.
7717
- */
7718
- var LogChannelWindowSchema = object({
7719
- channel: string().min(1),
7720
- /** Epoch ms the window closes at. */
7721
- armedUntilMs: number(),
7722
- /** `null` = every camera. A non-empty list narrows to those numeric ids. */
7723
- deviceIds: array(number().int()).readonly().nullable()
7724
- });
7725
- /**
7726
7634
  * Ops-log — the durable, append-only operations audit shared by the
7727
7635
  * recordings and events management surfaces.
7728
7636
  *
@@ -8644,6 +8552,21 @@ var StorageCleanupJobSchema = object({
8644
8552
  });
8645
8553
  var StorageCleanupStatusInputSchema = object({ jobId: string().optional() });
8646
8554
  /**
8555
+ * The one typed state of a storage location. Authoritative Zod schema — the TS
8556
+ * alias below is `z.infer<>` of it, never a second spelling.
8557
+ */
8558
+ var StorageLocationModeSchema = _enum([
8559
+ "active",
8560
+ "readonly",
8561
+ "drain",
8562
+ "disabled"
8563
+ ]);
8564
+ _enum([
8565
+ "normal",
8566
+ "never",
8567
+ "drain"
8568
+ ]);
8569
+ /**
8647
8570
  * `StorageLocationType` — an addon-declared id that identifies the *kind* of
8648
8571
  * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
8649
8572
  * so the persisted record schema and the consumer-facing cap can both consume it
@@ -8668,8 +8591,11 @@ var StorageLocationTypeSchema = string().regex(/^[a-z][a-zA-Z0-9-]*$/);
8668
8591
  * `STORAGE_LOCATION_CARDINALITY` map has been removed.
8669
8592
  *
8670
8593
  * `id` is a stable namespaced string of the form `<type>:<slug>`.
8671
- * The default location for a type uses `id === <type>:default` by
8672
- * convention (the bare type ref like `'backups'` resolves to it).
8594
+ * The seed names its first instance `<type>:default` — a NAME, not a flag.
8595
+ * There is no default location any more (D383): `enabled` is the whole write
8596
+ * model, and a bare type ref resolves to the sole location of the type, or —
8597
+ * transitionally, only while legacy NULL-stamped rows exist — to the row whose
8598
+ * slug is `default`.
8673
8599
  *
8674
8600
  * `isSystem` is a legacy persisted flag. Seed still creates the initial
8675
8601
  * `<type>:default` locations; the flag is no longer a lock, a badge, or a
@@ -8690,23 +8616,37 @@ var StorageLocationSchema = object({
8690
8616
  * flag at upsert time, not here (the schema is provider-agnostic).
8691
8617
  */
8692
8618
  nodeId: string().optional(),
8693
- isDefault: boolean().default(false),
8694
8619
  isSystem: boolean().default(false),
8695
8620
  /**
8696
- * Operator opt-in: whether consumers that BALANCE across several locations
8697
- * of a type may write here. Recordings reads it today; event media and
8698
- * backups are the next consumers, which is why the flag lives on the
8699
- * location rather than in any one addon's store — nothing has to be
8700
- * extended to add the next consumer.
8621
+ * THE write switch, and the only one (D383). `enabled: true` means every
8622
+ * consumer that chooses a write target for this type may write here, and all
8623
+ * enabled locations of a type are used TOGETHER; `false` means read-only —
8624
+ * still read, still played back, still age-swept, still drained, never
8625
+ * written.
8701
8626
  *
8702
- * OPTIONAL, and ABSENT MEANS ACTIVE. Every location persisted before the
8703
- * flag existed reads back with no flag and keeps working exactly as before;
8704
- * that is the whole compat story, and it is why no migration ships with it.
8705
- * A newly CREATED sibling is stamped `false` by the orchestrator (creating a
8706
- * disk must not silently start writing to it); the default of a type is
8707
- * always stamped `true`.
8627
+ * OPTIONAL only for the wire: an upsert that omits it means "leave what is
8628
+ * stored" on an update and "born inert unless it is the first location of its
8629
+ * type" on a create. On a PERSISTED row absence is legacy and it means
8630
+ * enabled — {@link isLocationEnabled} is the one place that says so, and the
8631
+ * orchestrator stamps every flagless row `true` once at hydrate so absence
8632
+ * stops existing rather than being re-derived on every read.
8708
8633
  */
8709
8634
  enabled: boolean().optional(),
8635
+ /**
8636
+ * THE state of this location (D385), and the only authority on what may be
8637
+ * written, read or evicted here. Interpreted in exactly one place —
8638
+ * `storage-location-mode.ts` — which also folds the legacy
8639
+ * `enabled` / `config.readOnly` pair into a mode so an old row is never
8640
+ * ambiguous.
8641
+ *
8642
+ * OPTIONAL only for the wire and for rows written before D385: absence is
8643
+ * resolved by `resolveLocationMode`, and the orchestrator stamps every
8644
+ * unstamped row ONCE at hydrate so absence stops existing rather than being
8645
+ * re-derived on every read. `enabled` survives one release as a DERIVED
8646
+ * mirror (`mode === 'active'`); `withLocationMode` is the only writer of
8647
+ * either, so the two cannot disagree.
8648
+ */
8649
+ mode: StorageLocationModeSchema.optional(),
8710
8650
  /** COMPUTED at read time by the orchestrator (statfs of the backing volume
8711
8651
  * for node-local locations it can reach) — never persisted, absent when the
8712
8652
  * volume is remote/unreachable. The single capacity truth every UI reads. */
@@ -8714,13 +8654,50 @@ var StorageLocationSchema = object({
8714
8654
  totalBytes: number(),
8715
8655
  availableBytes: number()
8716
8656
  }).nullable().optional(),
8657
+ /**
8658
+ * How much of that volume CamStack ITSELF holds on this location (D388) —
8659
+ * COMPUTED at read time from the `storage-occupancy` providers' own figures,
8660
+ * never persisted, never a filesystem walk.
8661
+ *
8662
+ * **ABSENT MEANS UNKNOWN, never zero.** No provider has reported for this
8663
+ * location yet — nobody stores here, the owning addon is down, or the first
8664
+ * refresh has not completed. A UI must omit the segment rather than draw it
8665
+ * at zero, which would claim we occupy nothing (D315). It is an OBJECT and
8666
+ * not a bare number precisely so that a `?? 0` on the consuming side has to
8667
+ * be spelled out loud instead of appearing by accident.
8668
+ *
8669
+ * `measuredAtMs` is the OLDEST contributing measurement, so it is honest
8670
+ * about the whole figure rather than about its freshest part.
8671
+ */
8672
+ owned: object({
8673
+ bytes: number().int().nonnegative(),
8674
+ measuredAtMs: number().int().nonnegative()
8675
+ }).optional(),
8717
8676
  createdAt: number(),
8718
8677
  updatedAt: number()
8719
8678
  });
8679
+ object({ isDefault: boolean().optional() });
8680
+ /**
8681
+ * How far a `drain` has got (D386) — the read a UI renders, and nothing more.
8682
+ *
8683
+ * `estimatedEmptyAtMs` is derived from the growth the ratchet has actually
8684
+ * OBSERVED and is `null` when it has observed none. Never a fabricated date: a
8685
+ * drain with no observed growth has no honest ETA, and inventing one is how an
8686
+ * operator learns not to believe the screen.
8687
+ */
8688
+ var StorageDrainProgressSchema = object({
8689
+ locationId: string(),
8690
+ startedAtMs: number(),
8691
+ startBytes: number(),
8692
+ bytesRemaining: number(),
8693
+ drained: boolean(),
8694
+ estimatedEmptyAtMs: number().nullable()
8695
+ });
8720
8696
  /**
8721
8697
  * Reference accepted by consumer-facing `api.storage.*` calls.
8722
8698
  * Either:
8723
- * - a `StorageLocationType` (e.g. `'backups'`) → orchestrator resolves to the default of that type
8699
+ * - a `StorageLocationType` (e.g. `'backups'`) → the sole location of that type
8700
+ * (transitionally, the `<type>:default`-slugged row when several exist)
8724
8701
  * - a fully-qualified id (e.g. `'backups:nas-01'`) → addresses a specific instance
8725
8702
  *
8726
8703
  * The orchestrator's `resolveRef(ref)` handles both cases.
@@ -8896,6 +8873,111 @@ var DecoderSessionConfigSchema = object({
8896
8873
  */
8897
8874
  debug: boolean().optional()
8898
8875
  });
8876
+ /**
8877
+ * Per-component log CHANNELS — the gate a hot path consults, and the registry
8878
+ * an addon declares its channels in.
8879
+ *
8880
+ * ## Two axes, deliberately separated
8881
+ *
8882
+ * - **DECLARATION** — which channels exist. Only the addon knows:
8883
+ * `stream-broker` knows webrtc/ICE/RTP, `provider-reolink` knows
8884
+ * baichuan/handshake. A hand-wired central list rots at the first addition,
8885
+ * and rots silently. So a channel is declared where it is consulted, and the
8886
+ * `log-channels` capability enumerates the declarations.
8887
+ * - **VALUE** — at which level, for which scope, until when. That stays ONE
8888
+ * thing: the logging settings document on the `system` cap. Two authorities
8889
+ * over the values is the exact defect
8890
+ * `docs/design/plans/2026-08-26-logging-per-componente.md` was written to
8891
+ * remove; re-introducing it from the cure side would be grotesque.
8892
+ *
8893
+ * Nothing in this file reads a clock, an env var or a store. The registry is
8894
+ * a MIRROR: it is moved only by {@link LogChannelRegistry.apply}, called off
8895
+ * the hot path with a value somebody actually read, and by
8896
+ * {@link LogChannelRegistry.tick}, called on a timer. A store read that fails
8897
+ * never reaches here, so it can neither disarm an armed channel nor arm a
8898
+ * disarmed one (D49).
8899
+ *
8900
+ * ## The canonical call shape
8901
+ *
8902
+ * ```ts
8903
+ * if (CH_RTP.on && CH_RTP.wants(deviceId)) {
8904
+ * CH_RTP.log(logger, 'rtp subscriber added', { tags: { deviceId }, meta: { ssrc } })
8905
+ * }
8906
+ * ```
8907
+ *
8908
+ * `on` is a plain boolean FIELD — never a getter — and it is the FIRST thing
8909
+ * read. Disarmed, a call site costs one load and one branch, and the `extras`
8910
+ * object literal is never constructed because it lives inside the branch. It
8911
+ * is the same shape already proven in production at `stream-broker.ts:1650`,
8912
+ * and the same discipline `LoggingGate.allowsDestination` uses for the
8913
+ * destination floor (measured at 1.93 ns/call when off).
8914
+ *
8915
+ * ## Why a channel emits at `info`
8916
+ *
8917
+ * `loki-logging.addon.ts` pins the destination default at `info` and
8918
+ * `loki-destination.ts` drops everything below it, so a line emitted at
8919
+ * `debug` never reaches Loki and the hub's in-memory ring only holds ~35
8920
+ * minutes. A diagnostic that cannot be read an hour later is worse than no
8921
+ * diagnostic, because it looks done. {@link LogChannelGate.log} therefore
8922
+ * emits at the channel's declared level, whose schema floor is `info`.
8923
+ */
8924
+ /**
8925
+ * The level a channel writes at once armed.
8926
+ *
8927
+ * `debug` is absent ON PURPOSE and not by omission: below `info` the line does
8928
+ * not leave the process for Loki, and the whole point of arming a channel is
8929
+ * to read it later.
8930
+ */
8931
+ var LogChannelLevelSchema = _enum([
8932
+ "info",
8933
+ "warn",
8934
+ "error"
8935
+ ]);
8936
+ /**
8937
+ * What an addon declares about one channel. No value, no state — a
8938
+ * declaration is inert.
8939
+ */
8940
+ var LogChannelDescriptorSchema = object({
8941
+ /**
8942
+ * Dotted `area.thing`, unique across the workspace. `area` is conventionally
8943
+ * the addon's short name so an operator reading a channel list can tell who
8944
+ * owns it without a second lookup.
8945
+ */
8946
+ name: string().min(3).regex(/^[a-z0-9-]+(\.[a-z0-9-]+)+$/, "a channel name is dotted lower-kebab, e.g. area.thing"),
8947
+ /** One sentence: what the operator will SEE after arming it. */
8948
+ description: string().min(1),
8949
+ /** The level its lines are emitted at. Never below `info`. */
8950
+ defaultLevel: LogChannelLevelSchema,
8951
+ /**
8952
+ * Whether this channel can be narrowed to a camera.
8953
+ *
8954
+ * `true` is a PROMISE with two halves, and both must hold: the gate is
8955
+ * consulted with the numeric device id, AND every line the channel admits
8956
+ * carries `tags: { deviceId }` with that same numeric id. The second half is
8957
+ * what makes `| json | deviceId="617"` work in Loki — `loki-payload.ts`
8958
+ * keeps `deviceId` out of the stream labels for cardinality, so the tag in
8959
+ * the body is the only way to filter.
8960
+ *
8961
+ * A channel whose lines carry the device only in `meta` (or not at all) is
8962
+ * declared `false`. Declaring it `true` anyway would be a lie the UI repeats:
8963
+ * the operator narrows to one camera, sees nothing, and concludes the code
8964
+ * path was never taken.
8965
+ */
8966
+ perDevice: boolean()
8967
+ });
8968
+ /**
8969
+ * An armed window over one channel, as the document hands it to a mirror.
8970
+ *
8971
+ * A window is a DEADLINE, never a flag (ADR-0244): a channel somebody forgot
8972
+ * expires by itself, which is the one failure a boolean cannot avoid.
8973
+ */
8974
+ var LogChannelWindowSchema = object({
8975
+ channel: string().min(1),
8976
+ /** Epoch ms the window closes at. */
8977
+ armedUntilMs: number(),
8978
+ /** `null` = every camera. A non-empty list narrows to those numeric ids. */
8979
+ deviceIds: array(number().int()).readonly().nullable()
8980
+ });
8899
8981
  var MODEL_FORMATS = [
8900
8982
  "onnx",
8901
8983
  "coreml",
@@ -21928,7 +22010,7 @@ method(object({
21928
22010
  downloadId: string(),
21929
22011
  offset: number(),
21930
22012
  length: number()
21931
- }), _instanceof(Uint8Array)), method(object({ downloadId: string() }), _void(), { kind: "mutation" }), method(object({ type: StorageLocationTypeSchema.optional() }), array(StorageLocationSchema).readonly()), method(object({ type: StorageLocationTypeSchema }), StorageLocationSchema.nullable()), method(_void(), array(StorageLocationDeclarationSchema).readonly()), method(StorageLocationSchema.omit({
22013
+ }), _instanceof(Uint8Array)), method(object({ downloadId: string() }), _void(), { kind: "mutation" }), method(object({ type: StorageLocationTypeSchema.optional() }), array(StorageLocationSchema).readonly()), method(_void(), array(StorageLocationDeclarationSchema).readonly()), method(StorageLocationSchema.omit({
21932
22014
  createdAt: true,
21933
22015
  updatedAt: true
21934
22016
  }), StorageLocationSchema, {
@@ -21940,7 +22022,7 @@ method(object({
21940
22022
  }), _void(), {
21941
22023
  kind: "mutation",
21942
22024
  auth: "admin"
21943
- }), method(object({ id: string() }), object({
22025
+ }), method(_void(), array(StorageDrainProgressSchema).readonly()), method(object({ id: string() }), object({
21944
22026
  ok: boolean(),
21945
22027
  error: string().optional()
21946
22028
  }), { auth: "admin" }), method(_void(), array(ProviderListEntrySchema).readonly()), method(object({
@@ -22010,6 +22092,51 @@ method(StorageMigrationInputSchema, StorageMigrationPlanSchema, { auth: "admin"
22010
22092
  kind: "mutation",
22011
22093
  auth: "admin"
22012
22094
  }), method(object({}), array(StorageMigrationJobSchema).readonly(), { auth: "admin" });
22095
+ /**
22096
+ * `storage-occupancy` — how many bytes an addon actually HOLDS on a storage
22097
+ * location (D388).
22098
+ *
22099
+ * ## Why this is not `storage-evictable`
22100
+ *
22101
+ * `storage-evictable.getEvictableUsage` looks like the same question and is
22102
+ * not, in two ways that both matter and both bite hardest on the locations an
22103
+ * operator most wants a figure for:
22104
+ *
22105
+ * - it reports the whole eviction DOMAIN, not the location. `recordings:default`
22106
+ * and `recordingsLow:default` deliberately share one root and evict as one
22107
+ * oldest-first pool, so both answer with the SAME combined total. As an
22108
+ * occupancy figure that double-counts the disk.
22109
+ * - it reports ZERO for a location whose eviction policy is `never` (D385) —
22110
+ * a `readonly` or `disabled` disk. Those are exactly the disks an operator
22111
+ * is retiring and staring at.
22112
+ *
22113
+ * So this is its own contract with its own quantity, and the quantity is
22114
+ * OCCUPIED: every byte the addon holds on that location, whether or not it
22115
+ * would ever be willing to delete it. A provider that can only answer
22116
+ * "evictable" must not register here — a number that silently means different
22117
+ * things per class is worse than no number.
22118
+ *
22119
+ * ## Absence is an answer
22120
+ *
22121
+ * A location nobody reports for is UNKNOWN, never zero (D315). The orchestrator
22122
+ * stamps `StorageLocation.owned` only for locations it has a report for, and
22123
+ * the field is an OBJECT rather than a bare number so that a `?? 0` on the
22124
+ * consuming side has to be written out loud instead of appearing by accident.
22125
+ *
22126
+ * `internal: true` — consumed by the orchestrator's `listLocations` stamp, never
22127
+ * a public client surface. Clients read the stamped `StorageLocation.owned`.
22128
+ */
22129
+ /** One provider's occupancy answer for one location. */
22130
+ var StorageOccupancyReportSchema = object({
22131
+ locationId: string(),
22132
+ /** Bytes this provider holds on THAT location — not its eviction domain, and
22133
+ * not net of what it is willing to delete. */
22134
+ ownedBytes: number().int().nonnegative(),
22135
+ /** When the provider last actually measured this. The orchestrator carries it
22136
+ * through so a UI can say how old the figure is instead of implying "now". */
22137
+ measuredAtMs: number().int().nonnegative()
22138
+ });
22139
+ method(object({ locationIds: array(string()).readonly() }), array(StorageOccupancyReportSchema).readonly(), { auth: "admin" });
22013
22140
  var ProviderInfoSchema = discriminatedUnion("shouldSaveDiskSpace", [object({
22014
22141
  providerId: string().min(1),
22015
22142
  displayName: string().min(1),
@@ -23845,88 +23972,6 @@ onStatusChanged: { data: object({
23845
23972
  volatileStateFields: ["lastUpdated"]
23846
23973
  };
23847
23974
  /**
23848
- * Network-link snapshot. Same shape for every provider (a Reolink wifi
23849
- * camera, a Home Assistant device with a signal-strength sensor, a Tapo
23850
- * plug): one slice under `device.runtimeState['network-link']`, one badge,
23851
- * one Home Assistant projection.
23852
- */
23853
- var NetworkLinkStatusSchema = object({
23854
- /** The link the device is on. `'unknown'` = not read yet, not "no link". */
23855
- type: _enum([
23856
- "wifi",
23857
- "ethernet",
23858
- "cellular",
23859
- "unknown"
23860
- ]),
23861
- /**
23862
- * Link quality, 0..100 inclusive, normalised by the provider from whatever
23863
- * the firmware reports (bars, RSSI, a vendor scale). **`null` means NOT
23864
- * KNOWN or NOT APPLICABLE** — a wired link has no signal, and a wireless
23865
- * one whose reading has not landed must not be drawn at 0 %. Consumers
23866
- * SKIP a null rather than coerce it.
23867
- */
23868
- signalPercent: number().min(0).max(100).nullable(),
23869
- /** Raw received signal strength in dBm, when the firmware reports one. */
23870
- rssiDbm: number().optional(),
23871
- /** Network name of a wireless link, when the firmware reports it. */
23872
- ssid: string().optional(),
23873
- /** Ms epoch of the last observation. Lets consumers reason about freshness. */
23874
- lastUpdated: number()
23875
- });
23876
- var networkLinkCapability = {
23877
- name: "network-link",
23878
- scope: "device",
23879
- deviceNative: true,
23880
- mode: "singleton",
23881
- deviceTypes: [
23882
- DeviceType.Camera,
23883
- DeviceType.Sensor,
23884
- DeviceType.Button,
23885
- DeviceType.Switch,
23886
- DeviceType.Light,
23887
- DeviceType.Lock,
23888
- DeviceType.Siren
23889
- ],
23890
- methods: {},
23891
- events: {
23892
- /**
23893
- * Emitted whenever the cached status changes (a link switch, a signal
23894
- * reading that moved). Mirrored on the parent chain by the
23895
- * DeviceEventPropagator like `battery.onStatusChanged`.
23896
- */
23897
- onStatusChanged: { data: object({
23898
- deviceId: number(),
23899
- status: NetworkLinkStatusSchema
23900
- }) } },
23901
- status: {
23902
- schema: NetworkLinkStatusSchema,
23903
- kind: "push",
23904
- empty: {
23905
- type: "unknown",
23906
- signalPercent: null,
23907
- lastUpdated: 0
23908
- }
23909
- },
23910
- /**
23911
- * Runtime-state slice — every provider stores the same shape under
23912
- * `device.runtimeState['network-link']`, read once by the badge and the
23913
- * Home Assistant projector regardless of the driver.
23914
- */
23915
- runtimeState: NetworkLinkStatusSchema,
23916
- /**
23917
- * Runtime-state durability: **restored** — a link reading is slow to
23918
- * change and a sleeping battery camera may not report for hours; the
23919
- * restored slice is what the badge shows until the next read.
23920
- *
23921
- * See `RuntimeStateDurability`. Enforced by
23922
- * `scripts/check-runtime-state-durability.ts`.
23923
- */
23924
- durability: "restored",
23925
- /** Clock fields: written, but excluded from the compare that decides
23926
- * whether persisting is worth a SQLite commit. */
23927
- volatileStateFields: ["lastUpdated"]
23928
- };
23929
- /**
23930
23975
  * Generic boolean sensor — last-resort fallback when no domain-
23931
23976
  * specific binary cap fits (Home Assistant `binary_sensor` without a
23932
23977
  * known `device_class`, or a domain we haven't typed yet). Pure
@@ -27456,6 +27501,369 @@ var nativeObjectDetectionCapability = {
27456
27501
  volatileStateFields: ["lastFetchedAt"]
27457
27502
  };
27458
27503
  /**
27504
+ * `navigation` — a device-scoped capability that natively expresses the FULL
27505
+ * navigation / action surface of a robot that DRIVES ITSELF and carries an
27506
+ * on-board camera (the Dreame robot-vacuum camera is the first provider).
27507
+ *
27508
+ * Why a NEW cap rather than overloading `ptz`:
27509
+ * - `ptz` moves a *gimbal* on a fixed camera (pan/tilt/zoom of the lens). A
27510
+ * robot vacuum has no gimbal — the whole chassis drives, turns and spins.
27511
+ * The two are different physical models: PTZ is absolute-position + presets,
27512
+ * navigation is momentary drive nudges + discrete robot ACTIONS
27513
+ * (dock / spot-clean / follow-pet / go-to-point / …).
27514
+ * - This cap is the SOURCE OF TRUTH. Two consumers adapt from it rather than
27515
+ * the reverse:
27516
+ * 1. a native CamStack navigation panel (data-driven from `listActions`
27517
+ * / `getOptions`), and
27518
+ * 2. the PTZ surface — a thin adapter mimics `ptz` from `navigation` so a
27519
+ * robot camera shows up in the existing PTZ control path without every
27520
+ * PTZ provider learning about robots. The mapping lives in the adapter,
27521
+ * not here (see the addon design note):
27522
+ * ptz.continuousMove({pan,tilt}) → navigation.move({pan,tilt})
27523
+ * ptz.stop() → navigation.stop()
27524
+ * ptz.goHome() → navigation.runAction('goHome')
27525
+ * ptz.getPresets() → navigation.listActions() (id→preset)
27526
+ * ptz.goToPreset(id) → navigation.runAction(id)
27527
+ *
27528
+ * ## Continuous drive
27529
+ *
27530
+ * `move` is MOMENTARY. Fluid navigation comes from the UI (or the PTZ adapter)
27531
+ * sending `move({pan,tilt})` REPEATEDLY at ~1 Hz while a direction is held, and
27532
+ * one `stop()` on release — exactly like the robot app's remote-drive joystick.
27533
+ * The provider forwards EACH `move` to one drive write; it must NOT debounce or
27534
+ * coalesce them. The UI owns the cadence.
27535
+ *
27536
+ * ## The action dictionary
27537
+ *
27538
+ * The discrete controls (dock / locate / spot-clean / follow / flash / sounds)
27539
+ * are a DATA-DRIVEN dictionary the cap exposes via `listActions()`. Each entry
27540
+ * carries `{ id, kind, label, icon }` (plus `soundId` for sound entries) so the
27541
+ * native panel AND the PTZ mimic render buttons WITHOUT hardcoding a
27542
+ * vendor-specific list. `kind: 'action'` entries are triggered with
27543
+ * `runAction({ actionId })`; `kind: 'sound'` entries with `playSound({ soundId })`
27544
+ * (the entry carries the `soundId` to pass). The general primitives — `move`,
27545
+ * `stop`, `goToPoint` — stay as first-class methods, not dictionary entries.
27546
+ *
27547
+ * NOTE (provider wiring): the first provider (Dreame) drives this with the RAW
27548
+ * `callAction(siid,aiid,in)` / `setProperty({siid,piid,value})` MIoT primitives
27549
+ * that the currently-published `@apocaliss92/nodedreame` already exposes on
27550
+ * every device handle. A future nodedreame publish adds a typed
27551
+ * `DreameCameraController` (drive / playPetSound / spotClean / findPet / …); the
27552
+ * provider can then swap the raw calls for the typed methods with no change to
27553
+ * THIS contract.
27554
+ */
27555
+ /**
27556
+ * A momentary drive nudge. The robot MOVES (no gimbal) for as long as the caller
27557
+ * keeps sending nudges (~1 Hz); an explicit `stop` (or letting the nudges lapse)
27558
+ * halts it.
27559
+ *
27560
+ * - `pan` — turn: negative = left, positive = right, 0 = straight.
27561
+ * - `tilt` — throttle: positive = forward, negative = spin / turn-around.
27562
+ * - `speed` — optional intensity hint [0, 1]; the provider may scale the drive
27563
+ * vector by it (drivers without proportional drive ignore it).
27564
+ *
27565
+ * `pan` / `tilt` are normalized [-1, 1]. Both optional so a caller can nudge one
27566
+ * axis alone; an all-undefined nudge is a no-op.
27567
+ */
27568
+ var NavigationMoveCommandSchema = object({
27569
+ pan: number().min(-1).max(1).optional(),
27570
+ tilt: number().min(-1).max(1).optional(),
27571
+ speed: number().min(0).max(1).optional()
27572
+ });
27573
+ /**
27574
+ * The enumerated discrete actions a navigation-capable robot can perform via
27575
+ * `runAction`. This is the CLOSED vocabulary; a given device advertises the
27576
+ * subset it supports through `listActions`. Sounds are NOT here — they go through
27577
+ * `playSound` (see the `sound` dictionary entries).
27578
+ */
27579
+ var NavigationActionIdSchema = _enum([
27580
+ "goHome",
27581
+ "locate",
27582
+ "spotClean",
27583
+ "findPet",
27584
+ "personFollow",
27585
+ "stop",
27586
+ "startClean",
27587
+ "pauseClean",
27588
+ "dockWash",
27589
+ "autoEmpty",
27590
+ "flashOn",
27591
+ "flashOff"
27592
+ ]);
27593
+ /** Whether a dictionary entry is a `runAction` action or a `playSound` sound. */
27594
+ var NavigationEntryKindSchema = _enum(["action", "sound"]);
27595
+ /**
27596
+ * One entry in the navigation action dictionary — the DATA-DRIVEN unit both the
27597
+ * native panel and the PTZ mimic render as a button.
27598
+ *
27599
+ * - `id` — stable id. For `kind:'action'` it is a {@link NavigationActionId}
27600
+ * (pass to `runAction`); for `kind:'sound'` it is a namespaced id
27601
+ * (`sound:meow`) whose `soundId` is passed to `playSound`.
27602
+ * - `icon` — icon HINT (lucide-style name; the UI maps it to its own set).
27603
+ * - `label` — operator-facing English label.
27604
+ * - `soundId` — wire sound id, present only on `kind:'sound'` entries.
27605
+ * - `enabled` — per-device FEATURE FLAG. `listActions` reports it so the UI /
27606
+ * PTZ render ONLY enabled entries. Data-driven: the provider
27607
+ * flips it from config, never by editing code.
27608
+ */
27609
+ var NavigationActionEntrySchema = object({
27610
+ id: string(),
27611
+ kind: NavigationEntryKindSchema,
27612
+ label: string(),
27613
+ icon: string(),
27614
+ /** Present only on `kind:'sound'` entries — the id to pass to `playSound`. */
27615
+ soundId: number().int().optional(),
27616
+ /** Per-device feature flag — render this entry only when true. */
27617
+ enabled: boolean()
27618
+ });
27619
+ /** Coordinates for `goToPoint` — a point on the robot's live map. */
27620
+ var NavigationPointSchema = object({
27621
+ x: number(),
27622
+ y: number()
27623
+ });
27624
+ /**
27625
+ * Per-device FEATURE-FLAG report for the general (non-dictionary) primitives.
27626
+ * The cap reports which are enabled so the UI / PTZ render only the controls
27627
+ * that are turned on for THIS device. Data-driven: the provider derives these
27628
+ * from config + probe, never hardcoded in the UI. The per-DICTIONARY-entry flags
27629
+ * live on {@link NavigationActionEntrySchema.enabled}; these gate the primitives
27630
+ * that are not dictionary entries.
27631
+ *
27632
+ * - `move` / `stop` — the momentary drive joystick.
27633
+ * - `goToPoint` — send-to-map-coordinate. Ships OFF on Dreame until the
27634
+ * map-coordinate plumbing is wired.
27635
+ * - `runAction` — the discrete action buttons (dictionary `kind:'action'`).
27636
+ * - `playSound` — the sound buttons (dictionary `kind:'sound'`).
27637
+ * - `light` — the on/off fill-light toggle (works anytime).
27638
+ * - `lightMode` — the auto/manual selector + manual level slider (a
27639
+ * camera-service control; needs an active stream).
27640
+ */
27641
+ var NavigationFeaturesSchema = object({
27642
+ move: boolean(),
27643
+ stop: boolean(),
27644
+ goToPoint: boolean(),
27645
+ runAction: boolean(),
27646
+ playSound: boolean(),
27647
+ light: boolean(),
27648
+ lightMode: boolean()
27649
+ });
27650
+ /** Light mode: `auto` lets the camera choose brightness; `manual` uses `level`. */
27651
+ var NavigationLightModeSchema = _enum(["auto", "manual"]);
27652
+ /**
27653
+ * Live navigation state so the UI can reflect what the robot is doing:
27654
+ * - `mode` — coarse activity (idle / cleaning / following / …).
27655
+ * - `following` — person/pet follow is currently armed.
27656
+ * - `flash` — the on-camera fill light is on.
27657
+ * - `lightMode` — auto vs manual fill-light mode.
27658
+ * - `lightLevel` — manual fill-light level (40..100); meaningful when
27659
+ * `lightMode === 'manual'`.
27660
+ */
27661
+ var NavigationStatusSchema = object({
27662
+ mode: _enum([
27663
+ "idle",
27664
+ "cleaning",
27665
+ "spot",
27666
+ "following",
27667
+ "goto",
27668
+ "returning",
27669
+ "paused",
27670
+ "unknown"
27671
+ ]),
27672
+ following: boolean(),
27673
+ flash: boolean(),
27674
+ lightMode: NavigationLightModeSchema,
27675
+ lightLevel: number().min(40).max(100),
27676
+ /** Ms epoch when the slice was last updated. */
27677
+ lastChangedAt: number()
27678
+ });
27679
+ /**
27680
+ * Runtime-state slice owned by this cap (kernel-managed: validated, mirrored,
27681
+ * observable). Adds `lastFetchedAt` on top of the status shape per the
27682
+ * convention.
27683
+ */
27684
+ var NavigationRuntimeStateSchema = NavigationStatusSchema.extend({ lastFetchedAt: number() });
27685
+ var navigationCapability = {
27686
+ name: "navigation",
27687
+ scope: "device",
27688
+ deviceNative: true,
27689
+ mode: "singleton",
27690
+ deviceTypes: [DeviceType.Camera],
27691
+ deviceConfig: { ui: {
27692
+ kind: "widget",
27693
+ widgetId: "host/navigation-panel",
27694
+ tab: "navigation",
27695
+ topTab: true,
27696
+ label: "Navigation",
27697
+ order: 0
27698
+ } },
27699
+ methods: {
27700
+ /**
27701
+ * Momentary drive nudge (the robot moves). `protected` — mirrors
27702
+ * `ptz.continuousMove` so the Viewer navigation panel (and the PTZ-mimic
27703
+ * path) works for any authenticated user, not admin-only. The UI sends
27704
+ * these at ~1 Hz while a control is held; the provider forwards each one to
27705
+ * a single drive write WITHOUT debouncing.
27706
+ */
27707
+ move: method(NavigationMoveCommandSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
27708
+ /** Halt all motion immediately (zero drive vector). */
27709
+ stop: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
27710
+ /** Send the robot to a point on its live map. */
27711
+ goToPoint: method(NavigationPointSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
27712
+ /**
27713
+ * Enumerate the discrete controls THIS device supports (data-driven UI +
27714
+ * PTZ mimic). Camera-probed subset of {@link NAVIGATION_ACTION_CATALOG}.
27715
+ */
27716
+ listActions: method(object({ deviceId: number() }), array(NavigationActionEntrySchema)),
27717
+ /**
27718
+ * Run one discrete action (a `kind:'action'` dictionary entry). Invalid /
27719
+ * unsupported action ids are rejected by the provider.
27720
+ */
27721
+ runAction: method(object({
27722
+ deviceId: number(),
27723
+ actionId: NavigationActionIdSchema
27724
+ }), _void(), { kind: "mutation" }),
27725
+ /** Play a sound by its wire id (the `soundId` of a `kind:'sound'` entry). */
27726
+ playSound: method(object({
27727
+ deviceId: number(),
27728
+ soundId: number().int()
27729
+ }), _void(), { kind: "mutation" }),
27730
+ /**
27731
+ * Turn the on-camera fill light on / off (the `OpenFullLight` control —
27732
+ * works anytime, no active stream required).
27733
+ */
27734
+ setLightOn: method(object({
27735
+ deviceId: number(),
27736
+ on: boolean()
27737
+ }), _void(), { kind: "mutation" }),
27738
+ /**
27739
+ * Set the fill-light mode (auto vs manual). `manual` optionally carries the
27740
+ * initial `level`. The auto/manual + level control is a CAMERA-service
27741
+ * action that generally needs an active camera stream/monitor session — the
27742
+ * UI shows the manual level slider ONLY when `mode === 'manual'`.
27743
+ */
27744
+ setLightMode: method(object({
27745
+ deviceId: number(),
27746
+ mode: NavigationLightModeSchema,
27747
+ level: number().min(40).max(100).optional()
27748
+ }), _void(), { kind: "mutation" }),
27749
+ /** Set the MANUAL fill-light level (40..100). Implies `manual` mode. */
27750
+ setLightLevel: method(object({
27751
+ deviceId: number(),
27752
+ level: number().min(40).max(100)
27753
+ }), _void(), { kind: "mutation" }),
27754
+ /**
27755
+ * Per-device FEATURE-FLAG report for the general primitives — drives which
27756
+ * controls the UI shows (the per-entry flags for the dictionary come back on
27757
+ * `listActions`).
27758
+ */
27759
+ getFeatures: method(object({ deviceId: number() }), NavigationFeaturesSchema)
27760
+ },
27761
+ events: { onStatusChanged: { data: object({
27762
+ deviceId: number(),
27763
+ status: NavigationStatusSchema
27764
+ }) } },
27765
+ status: {
27766
+ schema: NavigationStatusSchema,
27767
+ kind: "push"
27768
+ },
27769
+ /**
27770
+ * Runtime-state slice mirrored by the kernel. The navigation panel watches it
27771
+ * for live mode / follow / flash changes.
27772
+ */
27773
+ runtimeState: NavigationRuntimeStateSchema,
27774
+ /**
27775
+ * Runtime-state durability: **session** — like `vacuum-control`, a restored
27776
+ * `mode: cleaning` / `following: true` is a robot that is not actually doing
27777
+ * that. The live handle re-publishes on connect.
27778
+ *
27779
+ * See `RuntimeStateDurability`. Enforced by
27780
+ * `scripts/check-runtime-state-durability.ts`.
27781
+ */
27782
+ durability: "session"
27783
+ };
27784
+ /**
27785
+ * Network-link snapshot. Same shape for every provider (a Reolink wifi
27786
+ * camera, a Home Assistant device with a signal-strength sensor, a Tapo
27787
+ * plug): one slice under `device.runtimeState['network-link']`, one badge,
27788
+ * one Home Assistant projection.
27789
+ */
27790
+ var NetworkLinkStatusSchema = object({
27791
+ /** The link the device is on. `'unknown'` = not read yet, not "no link". */
27792
+ type: _enum([
27793
+ "wifi",
27794
+ "ethernet",
27795
+ "cellular",
27796
+ "unknown"
27797
+ ]),
27798
+ /**
27799
+ * Link quality, 0..100 inclusive, normalised by the provider from whatever
27800
+ * the firmware reports (bars, RSSI, a vendor scale). **`null` means NOT
27801
+ * KNOWN or NOT APPLICABLE** — a wired link has no signal, and a wireless
27802
+ * one whose reading has not landed must not be drawn at 0 %. Consumers
27803
+ * SKIP a null rather than coerce it.
27804
+ */
27805
+ signalPercent: number().min(0).max(100).nullable(),
27806
+ /** Raw received signal strength in dBm, when the firmware reports one. */
27807
+ rssiDbm: number().optional(),
27808
+ /** Network name of a wireless link, when the firmware reports it. */
27809
+ ssid: string().optional(),
27810
+ /** Ms epoch of the last observation. Lets consumers reason about freshness. */
27811
+ lastUpdated: number()
27812
+ });
27813
+ var networkLinkCapability = {
27814
+ name: "network-link",
27815
+ scope: "device",
27816
+ deviceNative: true,
27817
+ mode: "singleton",
27818
+ deviceTypes: [
27819
+ DeviceType.Camera,
27820
+ DeviceType.Sensor,
27821
+ DeviceType.Button,
27822
+ DeviceType.Switch,
27823
+ DeviceType.Light,
27824
+ DeviceType.Lock,
27825
+ DeviceType.Siren
27826
+ ],
27827
+ methods: {},
27828
+ events: {
27829
+ /**
27830
+ * Emitted whenever the cached status changes (a link switch, a signal
27831
+ * reading that moved). Mirrored on the parent chain by the
27832
+ * DeviceEventPropagator like `battery.onStatusChanged`.
27833
+ */
27834
+ onStatusChanged: { data: object({
27835
+ deviceId: number(),
27836
+ status: NetworkLinkStatusSchema
27837
+ }) } },
27838
+ status: {
27839
+ schema: NetworkLinkStatusSchema,
27840
+ kind: "push",
27841
+ empty: {
27842
+ type: "unknown",
27843
+ signalPercent: null,
27844
+ lastUpdated: 0
27845
+ }
27846
+ },
27847
+ /**
27848
+ * Runtime-state slice — every provider stores the same shape under
27849
+ * `device.runtimeState['network-link']`, read once by the badge and the
27850
+ * Home Assistant projector regardless of the driver.
27851
+ */
27852
+ runtimeState: NetworkLinkStatusSchema,
27853
+ /**
27854
+ * Runtime-state durability: **restored** — a link reading is slow to
27855
+ * change and a sleeping battery camera may not report for hours; the
27856
+ * restored slice is what the badge shows until the next read.
27857
+ *
27858
+ * See `RuntimeStateDurability`. Enforced by
27859
+ * `scripts/check-runtime-state-durability.ts`.
27860
+ */
27861
+ durability: "restored",
27862
+ /** Clock fields: written, but excluded from the compare that decides
27863
+ * whether persisting is worth a SQLite commit. */
27864
+ volatileStateFields: ["lastUpdated"]
27865
+ };
27866
+ /**
27459
27867
  * network-quality — system-scoped singleton capability tracking RTT,
27460
27868
  * jitter, and observed/peak bandwidth per device + per client.
27461
27869
  *
@@ -29036,287 +29444,6 @@ var ptzAutotrackCapability = {
29036
29444
  */
29037
29445
  durability: "session"
29038
29446
  };
29039
- /**
29040
- * `navigation` — a device-scoped capability that natively expresses the FULL
29041
- * navigation / action surface of a robot that DRIVES ITSELF and carries an
29042
- * on-board camera (the Dreame robot-vacuum camera is the first provider).
29043
- *
29044
- * Why a NEW cap rather than overloading `ptz`:
29045
- * - `ptz` moves a *gimbal* on a fixed camera (pan/tilt/zoom of the lens). A
29046
- * robot vacuum has no gimbal — the whole chassis drives, turns and spins.
29047
- * The two are different physical models: PTZ is absolute-position + presets,
29048
- * navigation is momentary drive nudges + discrete robot ACTIONS
29049
- * (dock / spot-clean / follow-pet / go-to-point / …).
29050
- * - This cap is the SOURCE OF TRUTH. Two consumers adapt from it rather than
29051
- * the reverse:
29052
- * 1. a native CamStack navigation panel (data-driven from `listActions`
29053
- * / `getOptions`), and
29054
- * 2. the PTZ surface — a thin adapter mimics `ptz` from `navigation` so a
29055
- * robot camera shows up in the existing PTZ control path without every
29056
- * PTZ provider learning about robots. The mapping lives in the adapter,
29057
- * not here (see the addon design note):
29058
- * ptz.continuousMove({pan,tilt}) → navigation.move({pan,tilt})
29059
- * ptz.stop() → navigation.stop()
29060
- * ptz.goHome() → navigation.runAction('goHome')
29061
- * ptz.getPresets() → navigation.listActions() (id→preset)
29062
- * ptz.goToPreset(id) → navigation.runAction(id)
29063
- *
29064
- * ## Continuous drive
29065
- *
29066
- * `move` is MOMENTARY. Fluid navigation comes from the UI (or the PTZ adapter)
29067
- * sending `move({pan,tilt})` REPEATEDLY at ~1 Hz while a direction is held, and
29068
- * one `stop()` on release — exactly like the robot app's remote-drive joystick.
29069
- * The provider forwards EACH `move` to one drive write; it must NOT debounce or
29070
- * coalesce them. The UI owns the cadence.
29071
- *
29072
- * ## The action dictionary
29073
- *
29074
- * The discrete controls (dock / locate / spot-clean / follow / flash / sounds)
29075
- * are a DATA-DRIVEN dictionary the cap exposes via `listActions()`. Each entry
29076
- * carries `{ id, kind, label, icon }` (plus `soundId` for sound entries) so the
29077
- * native panel AND the PTZ mimic render buttons WITHOUT hardcoding a
29078
- * vendor-specific list. `kind: 'action'` entries are triggered with
29079
- * `runAction({ actionId })`; `kind: 'sound'` entries with `playSound({ soundId })`
29080
- * (the entry carries the `soundId` to pass). The general primitives — `move`,
29081
- * `stop`, `goToPoint` — stay as first-class methods, not dictionary entries.
29082
- *
29083
- * NOTE (provider wiring): the first provider (Dreame) drives this with the RAW
29084
- * `callAction(siid,aiid,in)` / `setProperty({siid,piid,value})` MIoT primitives
29085
- * that the currently-published `@apocaliss92/nodedreame` already exposes on
29086
- * every device handle. A future nodedreame publish adds a typed
29087
- * `DreameCameraController` (drive / playPetSound / spotClean / findPet / …); the
29088
- * provider can then swap the raw calls for the typed methods with no change to
29089
- * THIS contract.
29090
- */
29091
- /**
29092
- * A momentary drive nudge. The robot MOVES (no gimbal) for as long as the caller
29093
- * keeps sending nudges (~1 Hz); an explicit `stop` (or letting the nudges lapse)
29094
- * halts it.
29095
- *
29096
- * - `pan` — turn: negative = left, positive = right, 0 = straight.
29097
- * - `tilt` — throttle: positive = forward, negative = spin / turn-around.
29098
- * - `speed` — optional intensity hint [0, 1]; the provider may scale the drive
29099
- * vector by it (drivers without proportional drive ignore it).
29100
- *
29101
- * `pan` / `tilt` are normalized [-1, 1]. Both optional so a caller can nudge one
29102
- * axis alone; an all-undefined nudge is a no-op.
29103
- */
29104
- var NavigationMoveCommandSchema = object({
29105
- pan: number().min(-1).max(1).optional(),
29106
- tilt: number().min(-1).max(1).optional(),
29107
- speed: number().min(0).max(1).optional()
29108
- });
29109
- /**
29110
- * The enumerated discrete actions a navigation-capable robot can perform via
29111
- * `runAction`. This is the CLOSED vocabulary; a given device advertises the
29112
- * subset it supports through `listActions`. Sounds are NOT here — they go through
29113
- * `playSound` (see the `sound` dictionary entries).
29114
- */
29115
- var NavigationActionIdSchema = _enum([
29116
- "goHome",
29117
- "locate",
29118
- "spotClean",
29119
- "findPet",
29120
- "personFollow",
29121
- "stop",
29122
- "startClean",
29123
- "pauseClean",
29124
- "dockWash",
29125
- "autoEmpty",
29126
- "flashOn",
29127
- "flashOff"
29128
- ]);
29129
- /** Whether a dictionary entry is a `runAction` action or a `playSound` sound. */
29130
- var NavigationEntryKindSchema = _enum(["action", "sound"]);
29131
- /**
29132
- * One entry in the navigation action dictionary — the DATA-DRIVEN unit both the
29133
- * native panel and the PTZ mimic render as a button.
29134
- *
29135
- * - `id` — stable id. For `kind:'action'` it is a {@link NavigationActionId}
29136
- * (pass to `runAction`); for `kind:'sound'` it is a namespaced id
29137
- * (`sound:meow`) whose `soundId` is passed to `playSound`.
29138
- * - `icon` — icon HINT (lucide-style name; the UI maps it to its own set).
29139
- * - `label` — operator-facing English label.
29140
- * - `soundId` — wire sound id, present only on `kind:'sound'` entries.
29141
- * - `enabled` — per-device FEATURE FLAG. `listActions` reports it so the UI /
29142
- * PTZ render ONLY enabled entries. Data-driven: the provider
29143
- * flips it from config, never by editing code.
29144
- */
29145
- var NavigationActionEntrySchema = object({
29146
- id: string(),
29147
- kind: NavigationEntryKindSchema,
29148
- label: string(),
29149
- icon: string(),
29150
- /** Present only on `kind:'sound'` entries — the id to pass to `playSound`. */
29151
- soundId: number().int().optional(),
29152
- /** Per-device feature flag — render this entry only when true. */
29153
- enabled: boolean()
29154
- });
29155
- /** Coordinates for `goToPoint` — a point on the robot's live map. */
29156
- var NavigationPointSchema = object({
29157
- x: number(),
29158
- y: number()
29159
- });
29160
- /**
29161
- * Per-device FEATURE-FLAG report for the general (non-dictionary) primitives.
29162
- * The cap reports which are enabled so the UI / PTZ render only the controls
29163
- * that are turned on for THIS device. Data-driven: the provider derives these
29164
- * from config + probe, never hardcoded in the UI. The per-DICTIONARY-entry flags
29165
- * live on {@link NavigationActionEntrySchema.enabled}; these gate the primitives
29166
- * that are not dictionary entries.
29167
- *
29168
- * - `move` / `stop` — the momentary drive joystick.
29169
- * - `goToPoint` — send-to-map-coordinate. Ships OFF on Dreame until the
29170
- * map-coordinate plumbing is wired.
29171
- * - `runAction` — the discrete action buttons (dictionary `kind:'action'`).
29172
- * - `playSound` — the sound buttons (dictionary `kind:'sound'`).
29173
- * - `light` — the on/off fill-light toggle (works anytime).
29174
- * - `lightMode` — the auto/manual selector + manual level slider (a
29175
- * camera-service control; needs an active stream).
29176
- */
29177
- var NavigationFeaturesSchema = object({
29178
- move: boolean(),
29179
- stop: boolean(),
29180
- goToPoint: boolean(),
29181
- runAction: boolean(),
29182
- playSound: boolean(),
29183
- light: boolean(),
29184
- lightMode: boolean()
29185
- });
29186
- /** Light mode: `auto` lets the camera choose brightness; `manual` uses `level`. */
29187
- var NavigationLightModeSchema = _enum(["auto", "manual"]);
29188
- /**
29189
- * Live navigation state so the UI can reflect what the robot is doing:
29190
- * - `mode` — coarse activity (idle / cleaning / following / …).
29191
- * - `following` — person/pet follow is currently armed.
29192
- * - `flash` — the on-camera fill light is on.
29193
- * - `lightMode` — auto vs manual fill-light mode.
29194
- * - `lightLevel` — manual fill-light level (40..100); meaningful when
29195
- * `lightMode === 'manual'`.
29196
- */
29197
- var NavigationStatusSchema = object({
29198
- mode: _enum([
29199
- "idle",
29200
- "cleaning",
29201
- "spot",
29202
- "following",
29203
- "goto",
29204
- "returning",
29205
- "paused",
29206
- "unknown"
29207
- ]),
29208
- following: boolean(),
29209
- flash: boolean(),
29210
- lightMode: NavigationLightModeSchema,
29211
- lightLevel: number().min(40).max(100),
29212
- /** Ms epoch when the slice was last updated. */
29213
- lastChangedAt: number()
29214
- });
29215
- /**
29216
- * Runtime-state slice owned by this cap (kernel-managed: validated, mirrored,
29217
- * observable). Adds `lastFetchedAt` on top of the status shape per the
29218
- * convention.
29219
- */
29220
- var NavigationRuntimeStateSchema = NavigationStatusSchema.extend({ lastFetchedAt: number() });
29221
- var navigationCapability = {
29222
- name: "navigation",
29223
- scope: "device",
29224
- deviceNative: true,
29225
- mode: "singleton",
29226
- deviceTypes: [DeviceType.Camera],
29227
- deviceConfig: { ui: {
29228
- kind: "widget",
29229
- widgetId: "host/navigation-panel",
29230
- tab: "navigation",
29231
- topTab: true,
29232
- label: "Navigation",
29233
- order: 0
29234
- } },
29235
- methods: {
29236
- /**
29237
- * Momentary drive nudge (the robot moves). `protected` — mirrors
29238
- * `ptz.continuousMove` so the Viewer navigation panel (and the PTZ-mimic
29239
- * path) works for any authenticated user, not admin-only. The UI sends
29240
- * these at ~1 Hz while a control is held; the provider forwards each one to
29241
- * a single drive write WITHOUT debouncing.
29242
- */
29243
- move: method(NavigationMoveCommandSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
29244
- /** Halt all motion immediately (zero drive vector). */
29245
- stop: method(object({ deviceId: number() }), _void(), { kind: "mutation" }),
29246
- /** Send the robot to a point on its live map. */
29247
- goToPoint: method(NavigationPointSchema.extend({ deviceId: number() }), _void(), { kind: "mutation" }),
29248
- /**
29249
- * Enumerate the discrete controls THIS device supports (data-driven UI +
29250
- * PTZ mimic). Camera-probed subset of {@link NAVIGATION_ACTION_CATALOG}.
29251
- */
29252
- listActions: method(object({ deviceId: number() }), array(NavigationActionEntrySchema)),
29253
- /**
29254
- * Run one discrete action (a `kind:'action'` dictionary entry). Invalid /
29255
- * unsupported action ids are rejected by the provider.
29256
- */
29257
- runAction: method(object({
29258
- deviceId: number(),
29259
- actionId: NavigationActionIdSchema
29260
- }), _void(), { kind: "mutation" }),
29261
- /** Play a sound by its wire id (the `soundId` of a `kind:'sound'` entry). */
29262
- playSound: method(object({
29263
- deviceId: number(),
29264
- soundId: number().int()
29265
- }), _void(), { kind: "mutation" }),
29266
- /**
29267
- * Turn the on-camera fill light on / off (the `OpenFullLight` control —
29268
- * works anytime, no active stream required).
29269
- */
29270
- setLightOn: method(object({
29271
- deviceId: number(),
29272
- on: boolean()
29273
- }), _void(), { kind: "mutation" }),
29274
- /**
29275
- * Set the fill-light mode (auto vs manual). `manual` optionally carries the
29276
- * initial `level`. The auto/manual + level control is a CAMERA-service
29277
- * action that generally needs an active camera stream/monitor session — the
29278
- * UI shows the manual level slider ONLY when `mode === 'manual'`.
29279
- */
29280
- setLightMode: method(object({
29281
- deviceId: number(),
29282
- mode: NavigationLightModeSchema,
29283
- level: number().min(40).max(100).optional()
29284
- }), _void(), { kind: "mutation" }),
29285
- /** Set the MANUAL fill-light level (40..100). Implies `manual` mode. */
29286
- setLightLevel: method(object({
29287
- deviceId: number(),
29288
- level: number().min(40).max(100)
29289
- }), _void(), { kind: "mutation" }),
29290
- /**
29291
- * Per-device FEATURE-FLAG report for the general primitives — drives which
29292
- * controls the UI shows (the per-entry flags for the dictionary come back on
29293
- * `listActions`).
29294
- */
29295
- getFeatures: method(object({ deviceId: number() }), NavigationFeaturesSchema)
29296
- },
29297
- events: { onStatusChanged: { data: object({
29298
- deviceId: number(),
29299
- status: NavigationStatusSchema
29300
- }) } },
29301
- status: {
29302
- schema: NavigationStatusSchema,
29303
- kind: "push"
29304
- },
29305
- /**
29306
- * Runtime-state slice mirrored by the kernel. The navigation panel watches it
29307
- * for live mode / follow / flash changes.
29308
- */
29309
- runtimeState: NavigationRuntimeStateSchema,
29310
- /**
29311
- * Runtime-state durability: **session** — like `vacuum-control`, a restored
29312
- * `mode: cleaning` / `following: true` is a robot that is not actually doing
29313
- * that. The live handle re-publishes on connect.
29314
- *
29315
- * See `RuntimeStateDurability`. Enforced by
29316
- * `scripts/check-runtime-state-durability.ts`.
29317
- */
29318
- durability: "session"
29319
- };
29320
29447
  DeviceType.Camera, DeviceType.Sensor, DeviceType.Switch, method(object({ deviceId: number().int().nonnegative() }), object({ success: literal(true) }), {
29321
29448
  kind: "mutation",
29322
29449
  auth: "admin"
@@ -38773,13 +38900,13 @@ Object.freeze({
38773
38900
  addonId: null,
38774
38901
  access: "view"
38775
38902
  },
38776
- "storage.getDefaultLocation": {
38903
+ "storage.list": {
38777
38904
  capName: "storage",
38778
38905
  capScope: "system",
38779
38906
  addonId: null,
38780
38907
  access: "view"
38781
38908
  },
38782
- "storage.list": {
38909
+ "storage.listDrainProgress": {
38783
38910
  capName: "storage",
38784
38911
  capScope: "system",
38785
38912
  addonId: null,
@@ -38929,6 +39056,12 @@ Object.freeze({
38929
39056
  addonId: null,
38930
39057
  access: "view"
38931
39058
  },
39059
+ "storageOccupancy.getOccupancy": {
39060
+ capName: "storage-occupancy",
39061
+ capScope: "system",
39062
+ addonId: null,
39063
+ access: "view"
39064
+ },
38932
39065
  "storageProvider.abortUpload": {
38933
39066
  capName: "storage-provider",
38934
39067
  capScope: "system",