@camstack/types 1.1.20 → 1.1.22

package/dist/addon/base-addon.d.ts

@@ -1,7 +1,7 @@
+import type { ZodType } from 'zod';
 import type { AddonContext, AddonInitResult, CapabilitiesAccess, ProviderRegistration } from '../interfaces/addon.js';
-import type { ConfigUISchema, ConfigUISchemaWithValues, ConfigField, ConfigSection } from '../interfaces/config-ui.js';
+import type { ConfigField, ConfigSection, ConfigUISchema, ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
 import { type DurableState } from './durable-state.js';
-import type { ZodType } from 'zod';
 export type { CapabilitiesAccess };
 /**
  * Utility type that constrains a ConfigField's `key` to only accept
@@ -182,8 +182,29 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
     protected globalSettingsSchema(_cap?: string): ConfigUISchema | null;
     /** Override to provide device-level settings UI schema. */
     protected deviceSettingsSchema(): ConfigUISchema | null;
-    getGlobalSettings(overlay?: Record<string, unknown>, cap?: string, _nodeId?: string): Promise<ConfigUISchemaWithValues | null>;
-    updateGlobalSettings(patch: Partial<TConfig>, _nodeId?: string): Promise<void>;
+    getGlobalSettings(overlay?: Record<string, unknown>, cap?: string, nodeId?: string): Promise<ConfigUISchemaWithValues | null>;
+    /**
+     * The raw addon store PROJECTED onto the target node's bare per-node keys:
+     * every `perNode: true` field carries THAT node's scoped value on its bare
+     * key (absent scoped key ⇒ key absent, so the schema `default` wins — no
+     * bare fallback), all `@`-scoped and stray bare per-node keys are dropped.
+     * A no-op passthrough when the schema declares no `perNode` field.
+     *
+     * This is the sanctioned way for a `getGlobalSettings` OVERRIDE that needs
+     * the store for custom option logic (option narrowing, value snapping) to
+     * read it per-node — never `ctx.settings.readAddonStore()` directly.
+     * `nodeId` omitted ⇒ the local node (node-blind injection from ctx).
+     */
+    protected resolveGlobalStore(nodeId?: string, cap?: string): Promise<Record<string, unknown>>;
+    updateGlobalSettings(patch: Partial<TConfig>, nodeId?: string): Promise<void>;
+    /**
+     * The set of field keys the global settings schema declares `perNode: true`
+     * — derived once per `cap` argument and memoized (schemas are static
+     * declarations). Empty set ⇒ every per-node code path is bypassed and the
+     * settings API behaves exactly like the legacy node-agnostic one.
+     */
+    private readonly _perNodeKeysCache;
+    private perNodeKeys;
     /**
      * If any field in `patch` is marked `requiresRestart` in `schema`,
      * schedule an addon restart for the next tick. Deferred via
@@ -255,6 +276,11 @@ export declare abstract class BaseAddon<TConfig extends object = Record<string,
      * The merge is shallow: each key in `defaults` is checked against the store.
      * Only keys present in defaults are read — the store can contain extra keys
      * (e.g. from older versions) without polluting the typed config.
+     *
+     * Keys the global settings schema declares `perNode: true` resolve from
+     * THIS node's scoped key (`<key>@<localNode>`) via `readNodeValue` — never
+     * from the bare key — so a per-node field resolves to this node's own
+     * selection at boot (absent scoped key ⇒ the constructor default wins).
      */
     protected resolveConfig(): Promise<void>;
     /**

package/dist/addon/per-node-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Per-node scoping for the shared addon-settings blob.
+ *
+ * An addon's settings store is hub-central (the `addon-settings` cap is
+ * hub-routed — the hub instance answers for every node), so fields whose
+ * value is a NODE fact (decoder backend, engine pick, probed hardware
+ * capabilities) persist under the node-scoped key `<key>@<nodeId>` inside
+ * the single shared blob. The SCHEMA field key stays bare: the write path
+ * ({@link scopePatch}) maps the bare field onto the target node's scoped
+ * key; the read/hydrate path ({@link projectStore}) maps THIS node's value
+ * back, so UI forms and `resolveConfig` only ever see the bare key.
+ *
+ * Fields opt in via the `perNode: true` schema marker on `ConfigFieldBase`
+ * (`interfaces/config-ui.ts`); `BaseAddon` derives the key set from the
+ * schema and routes reads/writes through these helpers.
+ *
+ * ## No bare-key fallback — deliberate
+ *
+ * {@link readNodeValue} reads the node-scoped key ONLY. A node with no
+ * scoped key resolves to `undefined` so the field's schema `default` wins —
+ * NEVER `store[base]` and never another node's value. A bare legacy key in
+ * the store is invisible to every node, hub included, so one node's
+ * selection can never leak onto another. (This generalizes the
+ * `decoder-backend-keys.ts` semantics — the no-fallback variant — over an
+ * arbitrary set of per-node field keys.)
+ *
+ * Pure functions only — no I/O, no imports beyond the language. This is a
+ * LEAF module: import it via its deep path, never from the root barrel.
+ */
+/**
+ * Normalize a raw kernel node id to the bare node id used for scoping.
+ * `localNodeId` can carry a `<node>/<addon>` suffix on forked child
+ * processes; per-node settings are per-NODE, so strip the addon segment.
+ * `undefined` / `null` / empty falls back to `'hub'`.
+ */
+export declare function normalizeNodeId(raw: string | undefined | null): string;
+/** The node-scoped store key for a per-node field: `<base>@<nodeId>`. */
+export declare function nodeScopedKey(base: string, nodeId: string): string;
+/**
+ * Read a node's value for a per-node field from the raw shared store:
+ * the node-scoped key when present, otherwise `undefined`.
+ * Deliberately NO bare-key fallback (see module doc) — the caller lets the
+ * schema `default` win on `undefined`.
+ */
+export declare function readNodeValue(store: Readonly<Record<string, unknown>>, base: string, nodeId: string): unknown;
+/**
+ * Re-map a UI/settings patch so every bare perNode field persists under the
+ * TARGET node's scoped key; all other keys pass through unchanged. Used on
+ * the write path so a save for one node never clobbers another node's value
+ * (and the bare key is never written). Returns a new object — the input
+ * patch is not mutated.
+ */
+export declare function scopePatch(patch: Readonly<Record<string, unknown>>, perNodeKeys: ReadonlySet<string>, nodeId: string): Record<string, unknown>;
+/**
+ * Project the raw shared store onto the bare schema keys for ONE node so a
+ * UI schema (whose field keys are bare) hydrates from that node's own
+ * values:
+ *
+ * - EVERY `@`-scoped key (any node's) is dropped from the pass-through.
+ * - Every bare perNode key is dropped from the pass-through (a stray bare
+ *   legacy key must never hydrate any node — no bare fallback).
+ * - THIS node's effective value ({@link readNodeValue}) is then laid onto
+ *   each bare perNode key; when the node has no scoped key the bare key is
+ *   left ABSENT so the field's schema `default` wins.
+ *
+ * Returns a new object — the input store is not mutated.
+ */
+export declare function projectStore(store: Readonly<Record<string, unknown>>, perNodeKeys: ReadonlySet<string>, nodeId: string): Record<string, unknown>;

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-BabrCASa.js");
+const require_sleep = require("./sleep-B8cp-HUn.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 exports.BaseAddon = require_sleep.BaseAddon;
 exports.DATAPLANE_SECRET_HEADER = require_sleep.DATAPLANE_SECRET_HEADER;

package/dist/addon.mjs

@@ -1,3 +1,3 @@
-import { A as ReadinessRegistry, C as asJsonObject, O as parseJsonUnknown, P as scopeKey, T as asString, a as adminUiCapability, b as DeviceType, gt as DisposerChain, ht as EventCategory, i as deviceOpsCapability, j as ReadinessTimeoutError, k as DATAPLANE_SECRET_HEADER, o as createDeviceProxy, ot as BaseAddon, p as expandCapMethods, st as normalizeAddonInitResult, t as sleep, ut as emitReadiness } from "./sleep-MHm--th-.mjs";
+import { A as ReadinessRegistry, C as asJsonObject, O as parseJsonUnknown, P as scopeKey, T as asString, a as adminUiCapability, b as DeviceType, gt as DisposerChain, ht as EventCategory, i as deviceOpsCapability, j as ReadinessTimeoutError, k as DATAPLANE_SECRET_HEADER, o as createDeviceProxy, ot as BaseAddon, p as expandCapMethods, st as normalizeAddonInitResult, t as sleep, ut as emitReadiness } from "./sleep-BiDFW0E7.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 export { BaseAddon, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, ReadinessTimeoutError, adminUiCapability, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, normalizeAddonInitResult, parseJsonUnknown, scopeKey, sleep };

package/dist/capabilities/camera-streams.cap.d.ts

@@ -116,8 +116,8 @@ export declare const cameraStreamsCapability: {
             sourceCamStreamId: z.ZodNullable<z.ZodString>;
             status: z.ZodEnum<{
                 error: "error";
-                idle: "idle";
                 unassigned: "unassigned";
+                idle: "idle";
                 connecting: "connecting";
                 streaming: "streaming";
             }>;
@@ -280,8 +280,8 @@ export declare const cameraStreamsCapability: {
                 sourceCamStreamId: z.ZodNullable<z.ZodString>;
                 status: z.ZodEnum<{
                     error: "error";
-                    idle: "idle";
                     unassigned: "unassigned";
+                    idle: "idle";
                     connecting: "connecting";
                     streaming: "streaming";
                 }>;
@@ -323,22 +323,22 @@ export declare const cameraStreamsCapability: {
         slotStatuses: z.ZodObject<{
             high: z.ZodOptional<z.ZodEnum<{
                 error: "error";
-                idle: "idle";
                 unassigned: "unassigned";
+                idle: "idle";
                 connecting: "connecting";
                 streaming: "streaming";
             }>>;
             mid: z.ZodOptional<z.ZodEnum<{
                 error: "error";
-                idle: "idle";
                 unassigned: "unassigned";
+                idle: "idle";
                 connecting: "connecting";
                 streaming: "streaming";
             }>>;
             low: z.ZodOptional<z.ZodEnum<{
                 error: "error";
-                idle: "idle";
                 unassigned: "unassigned";
+                idle: "idle";
                 connecting: "connecting";
                 streaming: "streaming";
             }>>;

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

@@ -109,6 +109,7 @@ export declare const decoderCapability: {
         readonly pullFrames: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             sessionId: z.ZodString;
             maxCount: z.ZodDefault<z.ZodNumber>;
+            waitMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodArray<z.ZodObject<{
             data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
             width: z.ZodNumber;
@@ -125,6 +126,7 @@ export declare const decoderCapability: {
         readonly pullHandles: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             sessionId: z.ZodString;
             maxCount: z.ZodDefault<z.ZodNumber>;
+            waitMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodArray<z.ZodObject<{
             shmId: z.ZodString;
             slot: z.ZodNumber;

package/dist/capabilities/device-manager.cap.d.ts

@@ -19,12 +19,6 @@
 import { z } from 'zod';
 import { DeviceType } from '../device/device-type.js';
 import { StreamSourceEntrySchema } from './schemas/streaming-shared.js';
-/** Cap-wire shape of a DeviceLink — structurally mirrors `DeviceLink` in
- *  `device-management.ts`. Source is a union: a FIELD source copies a sibling
- *  accessory's status field (`kind` optional/absent for wire compat); a
- *  LITERAL source carries a per-device constant (no sibling is read); a
- *  GLOBAL source (P2e) copies ANY device's status field, addressed by the
- *  source device's full re-sync-stable `stableId`. */
 export declare const DeviceLinkSchema: z.ZodObject<{
     id: z.ZodString;
     source: z.ZodUnion<readonly [z.ZodObject<{
@@ -40,6 +34,23 @@ export declare const DeviceLinkSchema: z.ZodObject<{
         sourceStableId: z.ZodString;
         cap: z.ZodString;
         fieldPath: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"expression">;
+        expr: z.ZodString;
+        bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodOptional<z.ZodLiteral<"field">>;
+            sourceKey: z.ZodString;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"literal">;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"global">;
+            sourceStableId: z.ZodString;
+            cap: z.ZodString;
+            fieldPath: z.ZodString;
+        }, z.core.$strip>]>>;
     }, z.core.$strip>]>;
     target: z.ZodObject<{
         cap: z.ZodString;
@@ -59,6 +70,34 @@ export declare const DeviceLinkSchema: z.ZodObject<{
         clamp: z.ZodOptional<z.ZodReadonly<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
     }, z.core.$strip>], "kind">>;
 }, z.core.$strip>;
+/** Cap-wire shape of a per-cap display refinement — mirrors
+ *  `DeviceCapDisplayOverride` in `device-management.ts`. */
+export declare const DeviceCapDisplayOverrideSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    precision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Cap-wire shape of an operator-authored per-device display override —
+ *  mirrors `DeviceDisplayOverride` in `device-management.ts`. `precision`
+ *  bounds mirror `numeric-sensor.cap.ts` (`int 0-10`). */
+export declare const DeviceDisplayOverrideSchema: z.ZodObject<{
+    icon: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    precision: z.ZodOptional<z.ZodNumber>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        unit: z.ZodOptional<z.ZodString>;
+        precision: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** Cap-wire shape of a per-role display default — mirrors `RoleDisplayDefault`
+ *  in `device-management.ts`. Keyed by `DeviceRole` string (role strings cross
+ *  the wire as plain strings everywhere else — cf. `DeviceInfoSchema.role`). */
+export declare const RoleDisplayDefaultSchema: z.ZodObject<{
+    unit: z.ZodOptional<z.ZodString>;
+    precision: z.ZodOptional<z.ZodNumber>;
+    icon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /**
  * Serializable projection of a live IDevice.
  * Returned by listAll, getDevice, getChildren.
@@ -110,6 +149,23 @@ export declare const DeviceInfoSchema: z.ZodObject<{
             sourceStableId: z.ZodString;
             cap: z.ZodString;
             fieldPath: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"expression">;
+            expr: z.ZodString;
+            bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                sourceKey: z.ZodString;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"literal">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"global">;
+                sourceStableId: z.ZodString;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>]>>;
         }, z.core.$strip>]>;
         target: z.ZodObject<{
             cap: z.ZodString;
@@ -129,6 +185,17 @@ export declare const DeviceInfoSchema: z.ZodObject<{
             clamp: z.ZodOptional<z.ZodReadonly<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>>;
+    display: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        unit: z.ZodOptional<z.ZodString>;
+        precision: z.ZodOptional<z.ZodNumber>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            unit: z.ZodOptional<z.ZodString>;
+            precision: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const ConfigEntrySchema: z.ZodObject<{
     key: z.ZodString;
@@ -191,6 +258,23 @@ export declare const DeviceMetaSchema: z.ZodObject<{
             sourceStableId: z.ZodString;
             cap: z.ZodString;
             fieldPath: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"expression">;
+            expr: z.ZodString;
+            bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                sourceKey: z.ZodString;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"literal">;
+                value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"global">;
+                sourceStableId: z.ZodString;
+                cap: z.ZodString;
+                fieldPath: z.ZodString;
+            }, z.core.$strip>]>>;
         }, z.core.$strip>]>;
         target: z.ZodObject<{
             cap: z.ZodString;
@@ -211,6 +295,17 @@ export declare const DeviceMetaSchema: z.ZodObject<{
         }, z.core.$strip>], "kind">>;
     }, z.core.$strip>>>>;
     role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    display: z.ZodOptional<z.ZodObject<{
+        icon: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        unit: z.ZodOptional<z.ZodString>;
+        precision: z.ZodOptional<z.ZodNumber>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            unit: z.ZodOptional<z.ZodString>;
+            precision: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const DeviceRegisterPayloadSchema: z.ZodObject<{
     addonId: z.ZodString;
@@ -325,6 +420,23 @@ export declare const deviceManagerCapability: {
                     sourceStableId: z.ZodString;
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"expression">;
+                    expr: z.ZodString;
+                    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                        sourceKey: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"literal">;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"global">;
+                        sourceStableId: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>]>>;
                 }, z.core.$strip>]>;
                 target: z.ZodObject<{
                     cap: z.ZodString;
@@ -345,6 +457,17 @@ export declare const deviceManagerCapability: {
                 }, z.core.$strip>], "kind">>;
             }, z.core.$strip>>>>;
             role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            display: z.ZodOptional<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    unit: z.ZodOptional<z.ZodString>;
+                    precision: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Update the operator-edited display name. Persists to the meta
          *  row + emits `EventCategory.DeviceMetaChanged`. */
@@ -425,6 +548,23 @@ export declare const deviceManagerCapability: {
                     sourceStableId: z.ZodString;
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"expression">;
+                    expr: z.ZodString;
+                    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                        sourceKey: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"literal">;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"global">;
+                        sourceStableId: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>]>>;
                 }, z.core.$strip>]>;
                 target: z.ZodObject<{
                     cap: z.ZodString;
@@ -445,6 +585,45 @@ export declare const deviceManagerCapability: {
                 }, z.core.$strip>], "kind">>;
             }, z.core.$strip>>>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Set (or clear) the per-device display override on the meta row. Mirrors
+         *  `setChildLayout` persistence; `null` clears the override entirely. The
+         *  override unit(s) are normalized (`normalizeUnit`) at write so the render
+         *  path's `UNIT_TABLE` lookups always hit canonical spellings. Persisted,
+         *  projected, and preserved across re-register/restore. Idempotent. */
+        readonly setDisplay: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            display: z.ZodNullable<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    unit: z.ZodOptional<z.ZodString>;
+                    precision: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Read the operator-authored per-role display defaults (unit/precision/
+         *  icon), keyed by `DeviceRole` string. Empty record when none set. */
+        readonly getRoleDisplayDefaults: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodObject<{
+            defaults: z.ZodRecord<z.ZodString, z.ZodObject<{
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                icon: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, "query">;
+        /** Replace the per-role display defaults whole-record (full replace — the
+         *  caller sends the complete map). Override unit(s) are normalized at write.
+         *  Not per-device, so nothing is emitted; the UI invalidates its own query
+         *  on mutate. */
+        readonly setRoleDisplayDefaults: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            defaults: z.ZodRecord<z.ZodString, z.ZodObject<{
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                icon: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
         /** List the wireable status-schema fields per cap bound to a device.
          *  Powers the Wiring tab's field pickers. Caps without a status schema are
          *  omitted. Item-array caps (`status.itemArray`, e.g. consumables) also
@@ -603,6 +782,23 @@ export declare const deviceManagerCapability: {
                     sourceStableId: z.ZodString;
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"expression">;
+                    expr: z.ZodString;
+                    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                        sourceKey: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"literal">;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"global">;
+                        sourceStableId: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>]>>;
                 }, z.core.$strip>]>;
                 target: z.ZodObject<{
                     cap: z.ZodString;
@@ -622,6 +818,17 @@ export declare const deviceManagerCapability: {
                     clamp: z.ZodOptional<z.ZodReadonly<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                 }, z.core.$strip>], "kind">>;
             }, z.core.$strip>>>>;
+            display: z.ZodOptional<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    unit: z.ZodOptional<z.ZodString>;
+                    precision: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Get a single device by numeric deviceId. */
         readonly getDevice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -672,6 +879,23 @@ export declare const deviceManagerCapability: {
                     sourceStableId: z.ZodString;
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"expression">;
+                    expr: z.ZodString;
+                    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                        sourceKey: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"literal">;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"global">;
+                        sourceStableId: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>]>>;
                 }, z.core.$strip>]>;
                 target: z.ZodObject<{
                     cap: z.ZodString;
@@ -691,6 +915,17 @@ export declare const deviceManagerCapability: {
                     clamp: z.ZodOptional<z.ZodReadonly<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                 }, z.core.$strip>], "kind">>;
             }, z.core.$strip>>>>;
+            display: z.ZodOptional<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    unit: z.ZodOptional<z.ZodString>;
+                    precision: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** List children of a parent device (by parent numeric id). */
         readonly getChildren: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -741,6 +976,23 @@ export declare const deviceManagerCapability: {
                     sourceStableId: z.ZodString;
                     cap: z.ZodString;
                     fieldPath: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"expression">;
+                    expr: z.ZodString;
+                    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+                        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+                        sourceKey: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"literal">;
+                        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+                    }, z.core.$strip>, z.ZodObject<{
+                        kind: z.ZodLiteral<"global">;
+                        sourceStableId: z.ZodString;
+                        cap: z.ZodString;
+                        fieldPath: z.ZodString;
+                    }, z.core.$strip>]>>;
                 }, z.core.$strip>]>;
                 target: z.ZodObject<{
                     cap: z.ZodString;
@@ -760,6 +1012,17 @@ export declare const deviceManagerCapability: {
                     clamp: z.ZodOptional<z.ZodReadonly<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>>;
                 }, z.core.$strip>], "kind">>;
             }, z.core.$strip>>>>;
+            display: z.ZodOptional<z.ZodObject<{
+                icon: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                unit: z.ZodOptional<z.ZodString>;
+                precision: z.ZodOptional<z.ZodNumber>;
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                perCap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    unit: z.ZodOptional<z.ZodString>;
+                    precision: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
         /** Get stream sources for a camera device. */
         readonly getStreamSources: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{

package/dist/capabilities/index.d.ts

@@ -177,6 +177,7 @@ export { type ITemperatureSensorProvider, type TemperatureSensorStatus, Temperat
 export { type IToastProvider, ToastSchema, toastCapability } from './toast.cap.js';
 export { type IUpdateProvider, type UpdateStatus, UpdateStatusSchema, updateCapability, } from './update.cap.js';
 export { ApiKeySummarySchema, CreateApiKeyInputSchema, CreateApiKeyResultSchema, CreateScopedTokenInputSchema, CreateScopedTokenResultSchema, CreateUserInputSchema, type IUserManagementProvider, ScopedTokenSummarySchema, UpdateUserInputSchema, UserSummarySchema, userManagementCapability, } from './user-management.cap.js';
+export { type IPetFeederProvider, PET_FEEDER_MANUAL_FEED_MAX, PET_FEEDER_MANUAL_FEED_MIN, type PetFeederStatus, PetFeederStatusSchema, petFeederCapability, } from './pet-feeder.cap.js';
 export { type IVacuumControlProvider, type TankStatus, TankStatusSchema, type VacuumControlStatus, VacuumControlStatusSchema, type VacuumState, VacuumStateSchema, vacuumControlCapability, } from './vacuum-control.cap.js';
 export { type IValveProvider, type ValveState, ValveStateSchema, type ValveStatus, ValveStatusSchema, valveCapability, } from './valve.cap.js';
 export { type IVibrationProvider, type VibrationStatus, VibrationStatusSchema, vibrationCapability, } from './vibration.cap.js';
@@ -213,6 +214,7 @@ import type { cameraPipelineConfigCapability } from './camera-pipeline-config.ca
 import type { cameraStreamsCapability } from './camera-streams.cap.js';
 import type { carbonMonoxideCapability } from './carbon-monoxide.cap.js';
 import type { climateControlCapability } from './climate-control.cap.js';
+import type { petFeederCapability } from './pet-feeder.cap.js';
 import type { colorCapability } from './color.cap.js';
 import type { connectivityCapability } from './connectivity.cap.js';
 import type { consumablesCapability } from './consumables.cap.js';
@@ -306,6 +308,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 storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof settingsStoreCapability | typeof logDestinationCapability | typeof adminUiCapability | 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 restreamerCapability | typeof webrtcCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof streamingEngineCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof snapshotProviderCapability | typeof notificationOutputCapability | typeof advancedNotifierCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof consumablesCapability | 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 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 deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof privacyMaskCapability;
+type AnyCapability = typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof settingsStoreCapability | typeof logDestinationCapability | typeof adminUiCapability | 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 restreamerCapability | typeof webrtcCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof streamingEngineCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof snapshotProviderCapability | typeof notificationOutputCapability | typeof advancedNotifierCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof consumablesCapability | 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 deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof privacyMaskCapability;
 export type CapabilityName = AnyCapability['name'];
 export type ITypedReadinessRegistry = IReadinessRegistry<CapabilityName>;

package/dist/capabilities/metrics-provider.cap.d.ts

@@ -170,8 +170,8 @@ declare const AddonInstanceSchema: z.ZodObject<{
     pid: z.ZodNumber;
     state: z.ZodEnum<{
         running: "running";
-        starting: "starting";
         stopped: "stopped";
+        starting: "starting";
         stopping: "stopping";
         crashed: "crashed";
     }>;
@@ -466,8 +466,8 @@ export declare const metricsProviderCapability: {
             pid: z.ZodNumber;
             state: z.ZodEnum<{
                 running: "running";
-                starting: "starting";
                 stopped: "stopped";
+                starting: "starting";
                 stopping: "stopping";
                 crashed: "crashed";
             }>;