@camstack/types 1.2.202 → 1.2.204

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

@@ -642,7 +642,11 @@ export declare const deviceManagerCapability: {
          *  reference this label keep their `meta.location` value — the
          *  registry is purely a suggestion list. To purge from devices,
          *  iterate them and call `setLocation(deviceId, null)`
-         *  separately (or pass `cascade: true` to do it in one shot). */
+         *  separately (or pass `cascade: true` to do it in one shot).
+         *
+         *  The room's ICON goes with it, always — a key left behind survives in a
+         *  map nobody lists, and a room later re-created under the same name would
+         *  silently inherit an icon the operator never chose for it. */
         readonly removeLocation: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             name: z.ZodString;
             cascade: z.ZodOptional<z.ZodBoolean>;
@@ -660,13 +664,219 @@ export declare const deviceManagerCapability: {
          *  a suggestion list, and the devices that most need a rename are exactly
          *  the ones carrying a label nobody registered. `to` renames onto an
          *  existing room by MERGING into it, leaving no duplicate label. An empty
-         *  `to` throws before anything is written. */
+         *  `to` throws before anything is written.
+         *
+         *  The room's ICON travels with the rename, including when `from` was
+         *  never registered — otherwise it orphans on a key no location carries
+         *  any more. A merge keeps the TARGET's icon when it has one: renaming
+         *  "Sala" into "Salone" moves devices into Salone, it does not restyle
+         *  it. */
         readonly renameLocation: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             from: z.ZodString;
             to: z.ZodString;
         }, z.core.$strip>, z.ZodObject<{
             moved: z.ZodNumber;
         }, z.core.$strip>, "mutation">;
+        /** Every location that carries an ICON, as `(locationKey, icon)` pairs.
+         *
+         *  ADDITIVE, deliberately: `listLocations` keeps returning `string[]` —
+         *  every consumer of it (the Device Info autocomplete, the HA adoption
+         *  import, the recorder) reads a list of labels and none of them wants a
+         *  shape change. A surface that wants icons asks for them and joins.
+         *
+         *  Only assignments that EXIST are returned — a location with no icon is
+         *  absent, not `map-pin`. The fallback belongs to the renderer
+         *  (`resolveLocationIcon`), not to the store, so "the operator chose the
+         *  pin" and "the operator chose nothing" stay distinguishable.
+         *
+         *  The join key is `locationIconKey(label)` (trimmed, lower-cased) — the
+         *  same equality the registry uses everywhere. Never the operator's
+         *  casing: a case-only rename is a real edit here, and a map keyed on the
+         *  displayed spelling would orphan its entry on exactly that edit. */
+        readonly listLocationIcons: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodArray<z.ZodObject<{
+            locationKey: z.ZodString;
+            icon: z.ZodEnum<{
+                package: "package";
+                "map-pin": "map-pin";
+                house: "house";
+                "door-open": "door-open";
+                sofa: "sofa";
+                utensils: "utensils";
+                "bed-double": "bed-double";
+                bath: "bath";
+                briefcase: "briefcase";
+                car: "car";
+                "circle-parking": "circle-parking";
+                route: "route";
+                trees: "trees";
+                umbrella: "umbrella";
+                "waves-ladder": "waves-ladder";
+                fence: "fence";
+                warehouse: "warehouse";
+                store: "store";
+                sun: "sun";
+                radar: "radar";
+            }>;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** Set (or clear) the icon of a location label. `icon: null` removes the
+         *  assignment. The label need NOT be registered — the registry is a
+         *  suggestion list and devices carry labels nobody registered — but an
+         *  empty / whitespace-only label throws. Idempotent.
+         *
+         *  The icon vocabulary is CLOSED (`LOCATION_ICON_IDS`) because the admin UI
+         *  and the viewer draw from different icon modules; see
+         *  `device/location-icon.ts` for the list and for what a surface that
+         *  cannot draw a member must do (fall back to `map-pin`, never a hole). */
+        readonly setLocationIcon: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            location: z.ZodString;
+            icon: z.ZodNullable<z.ZodEnum<{
+                package: "package";
+                "map-pin": "map-pin";
+                house: "house";
+                "door-open": "door-open";
+                sofa: "sofa";
+                utensils: "utensils";
+                "bed-double": "bed-double";
+                bath: "bath";
+                briefcase: "briefcase";
+                car: "car";
+                "circle-parking": "circle-parking";
+                route: "route";
+                trees: "trees";
+                umbrella: "umbrella";
+                "waves-ladder": "waves-ladder";
+                fence: "fence";
+                warehouse: "warehouse";
+                store: "store";
+                sun: "sun";
+                radar: "radar";
+            }>>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Every location that carries a DESCRIPTION — what the place LOOKS like,
+         *  in plain words, given to the vision model alongside the pictures so it
+         *  knows what it is looking at. A driveway of cobbles between a brick wall
+         *  and three parking spaces reads very differently from a back garden.
+         *
+         *  Same additive shape and same join key as `listLocationIcons`, and that
+         *  is the point of it being here at all: this lived in the post-analysis
+         *  addon's own settings, keyed by a hand-typed label matched exactly and
+         *  case-sensitively, while the icon hung off the location itself. A rename
+         *  carried the icon and silently orphaned the description. One location,
+         *  one authority, one key.
+         *
+         *  Absent means nobody wrote one — the digest then tells the model only the
+         *  location NAME, exactly as it did before descriptions existed. */
+        readonly listLocationDescriptions: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodArray<z.ZodObject<{
+            locationKey: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** Set (or clear) a location's description. `description: null`, or a
+         *  blank string, removes it — an empty description and no description are
+         *  the same thing to every reader, and storing the first would send an
+         *  empty line to the model.
+         *
+         *  Like `setLocationIcon`, the label need NOT be registered, and an
+         *  empty / whitespace-only LABEL throws. */
+        readonly setLocationDescription: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            location: z.ZodString;
+            description: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Every SITE ZONE — a named part of the property that groups locations
+         *  ("Zona notte" holds the bedrooms). One call answers the whole picture:
+         *  key, the label as typed, the icon, and the locations inside.
+         *
+         *  Together, because a surface that asked for membership separately could
+         *  draw a zone whose rooms it has not fetched — and the strip that renders
+         *  these puts zones BEFORE locations, so a half-known zone is the first
+         *  thing an operator sees.
+         *
+         *  Nothing here touches a device: a camera's zone is derived from its
+         *  location, never stored on the row. Grouping rooms must not rewrite the
+         *  fleet. */
+        readonly listSiteZones: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodArray<z.ZodObject<{
+            zoneKey: z.ZodString;
+            label: z.ZodString;
+            icon: z.ZodNullable<z.ZodEnum<{
+                package: "package";
+                "map-pin": "map-pin";
+                house: "house";
+                "door-open": "door-open";
+                sofa: "sofa";
+                utensils: "utensils";
+                "bed-double": "bed-double";
+                bath: "bath";
+                briefcase: "briefcase";
+                car: "car";
+                "circle-parking": "circle-parking";
+                route: "route";
+                trees: "trees";
+                umbrella: "umbrella";
+                "waves-ladder": "waves-ladder";
+                fence: "fence";
+                warehouse: "warehouse";
+                store: "store";
+                sun: "sun";
+                radar: "radar";
+            }>>;
+            locationKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** Create a zone, or set the icon of one that exists. `icon: null` clears
+         *  the icon and KEEPS the zone — a zone with no icon is a normal zone, and
+         *  conflating "no icon" with "no zone" would delete membership on a
+         *  mis-click.
+         *
+         *  Idempotent, and the label is stored as typed: the key is folded, so
+         *  re-running this with different casing re-labels rather than duplicating. */
+        readonly setSiteZone: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            name: z.ZodString;
+            icon: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                package: "package";
+                "map-pin": "map-pin";
+                house: "house";
+                "door-open": "door-open";
+                sofa: "sofa";
+                utensils: "utensils";
+                "bed-double": "bed-double";
+                bath: "bath";
+                briefcase: "briefcase";
+                car: "car";
+                "circle-parking": "circle-parking";
+                route: "route";
+                trees: "trees";
+                umbrella: "umbrella";
+                "waves-ladder": "waves-ladder";
+                fence: "fence";
+                warehouse: "warehouse";
+                store: "store";
+                sun: "sun";
+                radar: "radar";
+            }>>>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Delete a zone. Its LOCATIONS survive — they simply stop belonging to
+         *  anything. Deleting a grouping must never delete what was grouped. */
+        readonly removeSiteZone: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Rename a zone, carrying its icon AND its membership.
+         *
+         *  It exists so that renaming is not delete-then-recreate, which would drop
+         *  both — the exact orphaning that lost a location's description when the
+         *  two hung off different keys. Renaming onto an existing zone MERGES into
+         *  it and the target keeps its own icon. */
+        readonly renameSiteZone: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /** Put a location in a zone, or take it out with `zone: null`.
+         *
+         *  At most one zone per location, by construction: this writes one key, so
+         *  there is no state in which a room is in two places at once. The zone
+         *  need not exist yet — it is created empty-labelled from this call, the
+         *  same way `setLocationIcon` does not require a registered location. */
+        readonly setLocationZone: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            location: z.ZodString;
+            zone: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, z.ZodVoid, "mutation">;
         /** Soft-disable / re-enable the device. Drivers consult
          *  `BaseDevice.disabled` to gate lifecycle hooks. */
         readonly setDisabled: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{

package/dist/device/index.d.ts

@@ -17,6 +17,8 @@ export { BATTERY_DEVICE_PROFILE, DEVICE_PROFILES, deviceMatchesProfile, resolveD
 export type { IDeviceRuntimeState, Snapshot as RuntimeStateSnapshot, } from './device-runtime-state.js';
 export { ChargingStatus, DeviceFeature, DeviceRole, DeviceType } from './device-type.js';
 export type { IBatteryOperated, IDoorbellButton, INativeSnapshot, IPanTiltZoom, IRebootable, ITwoWayAudio, } from './features.js';
+export type { LocationDescriptionAssignment, LocationIconAssignment, LocationIconId, } from './location-icon.js';
+export { LOCATION_ICON_FALLBACK, LOCATION_ICON_IDS, LOCATION_DESCRIPTION_MAX, LocationDescriptionAssignmentSchema, LocationIconAssignmentSchema, LocationIconIdSchema, locationIconKey, resolveLocationIcon, } from './location-icon.js';
 export { getByPath, setByPath } from './path-util.js';
 export type { ReachabilityPollHandle, ReachabilityPollLogger, ReachabilityPollOptions, } from './reachability-poll.js';
 export { REACHABILITY_FAILURES_TO_OFFLINE, REACHABILITY_POLL_INTERVAL_MS, REACHABILITY_PROBE_TIMEOUT_MS, startReachabilityPoll, } from './reachability-poll.js';
@@ -26,3 +28,5 @@ export type { WireableField } from './schema-fields.js';
 export { enumerateItemArrayFields, enumerateSchemaFields } from './schema-fields.js';
 export type { DeviceConfigEntry } from './zod-to-config-ui.js';
 export { zodEntriesToConfigUI } from './zod-to-config-ui.js';
+export type { SiteZone } from './site-zone.js';
+export { SiteZoneSchema, siteZoneKey } from './site-zone.js';

package/dist/device/location-icon.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The CLOSED icon vocabulary a location may carry.
+ *
+ * A location is not an entity — it is a free-form label (`PersistedDeviceMeta.
+ * location`) plus an operator-curated registry of labels in the device-manager
+ * addon store. The icon is a second map beside that registry, keyed the same
+ * way the registry matches everywhere else: {@link locationIconKey}, i.e.
+ * trimmed + lower-cased.
+ *
+ * WHY A CLOSED SET, AND WHY THESE NAMES
+ * -------------------------------------
+ * Two surfaces draw this icon and they do NOT share an icon module: the admin
+ * UI imports `lucide-react`, the viewer imports a hand-maintained per-icon
+ * allowlist (`src/lib/icons.ts`, re-exporting `lucide-react-native/icons/*`
+ * because the barrel is 47 % of the app's modules). A free-form string would
+ * therefore be renderable on one surface and a hole on the other, decided at
+ * runtime by whichever icon happened to be bundled.
+ *
+ * So the vocabulary names the DRAWING, not the room: every member is the exact
+ * kebab-case lucide icon id. That makes "can this surface draw it?" a
+ * mechanical question with a mechanical answer — the admin UI maps the id to
+ * lucide-react's PascalCase export, the viewer maps it to
+ * `lucide-react-native/icons/<id>` — instead of a semantic judgement call, and
+ * it removes the per-surface meaning table a room-typed vocabulary
+ * (`kitchen`, `garage`, …) would have needed on both sides. An operator who
+ * puts the `car` icon on a room called "Ripostiglio" is not fighting the
+ * model; they picked a picture.
+ *
+ * The members, and the export each surface needs:
+ *
+ * | id                | lucide-react      | viewer `icons.ts` export |
+ * | ----------------- | ----------------- | ------------------------ |
+ * | `map-pin`         | `MapPin`          | present                  |
+ * | `house`           | `House`           | present                  |
+ * | `door-open`       | `DoorOpen`        | present                  |
+ * | `utensils`        | `Utensils`        | present                  |
+ * | `car`             | `Car`             | present                  |
+ * | `circle-parking`  | `CircleParking`   | present                  |
+ * | `route`           | `Route`           | present                  |
+ * | `package`         | `Package`         | present                  |
+ * | `sun`             | `Sun`             | present                  |
+ * | `radar`           | `Radar`           | present                  |
+ * | `sofa`            | `Sofa`            | MISSING — add            |
+ * | `bed-double`      | `BedDouble`       | MISSING — add            |
+ * | `bath`            | `Bath`            | MISSING — add            |
+ * | `briefcase`       | `Briefcase`       | MISSING — add            |
+ * | `trees`           | `Trees`           | MISSING — add            |
+ * | `umbrella`        | `Umbrella`        | MISSING — add            |
+ * | `waves-ladder`    | `WavesLadder`     | MISSING — add            |
+ * | `fence`           | `Fence`           | MISSING — add            |
+ * | `warehouse`       | `Warehouse`       | MISSING — add            |
+ * | `store`           | `Store`           | MISSING — add            |
+ *
+ * DEGRADATION IS A FALLBACK, NEVER A HOLE. A surface that cannot draw a member
+ * — a viewer build shipped before its allowlist caught up, a persisted value
+ * from a newer hub, a hand-edited settings row — draws
+ * {@link LOCATION_ICON_FALLBACK} (`map-pin`, the one every surface has always
+ * had). Read a stored/wire value through {@link resolveLocationIcon} and that
+ * is what you get; nothing anywhere renders an empty box.
+ *
+ * Growing the vocabulary is a framework change (`@camstack/types` travels in
+ * the `@camstack/server` closure) AND a viewer change. Add the id here, add the
+ * line to the viewer's `icons.ts`, and expect older viewers to draw the
+ * fallback for it until they update — which is exactly the contract above.
+ */
+import { z } from 'zod';
+/**
+ * Every icon id a location may carry. Kebab-case lucide icon ids — see the
+ * module docblock for why the vocabulary names the drawing and not the room.
+ */
+export declare const LOCATION_ICON_IDS: readonly ["map-pin", "house", "door-open", "sofa", "utensils", "bed-double", "bath", "briefcase", "car", "circle-parking", "route", "trees", "umbrella", "waves-ladder", "fence", "package", "warehouse", "store", "sun", "radar"];
+/** One member of {@link LOCATION_ICON_IDS}. */
+export type LocationIconId = (typeof LOCATION_ICON_IDS)[number];
+/**
+ * The id every surface is guaranteed to draw, and what an unrecognised value
+ * degrades to. It has been in both icon sets since before this vocabulary
+ * existed (the Locations page's own page icon), so "the fallback is missing"
+ * is not a state a build can reach.
+ */
+export declare const LOCATION_ICON_FALLBACK: LocationIconId;
+/** Wire/storage schema for one icon id. */
+export declare const LocationIconIdSchema: z.ZodEnum<{
+    package: "package";
+    "map-pin": "map-pin";
+    house: "house";
+    "door-open": "door-open";
+    sofa: "sofa";
+    utensils: "utensils";
+    "bed-double": "bed-double";
+    bath: "bath";
+    briefcase: "briefcase";
+    car: "car";
+    "circle-parking": "circle-parking";
+    route: "route";
+    trees: "trees";
+    umbrella: "umbrella";
+    "waves-ladder": "waves-ladder";
+    fence: "fence";
+    warehouse: "warehouse";
+    store: "store";
+    sun: "sun";
+    radar: "radar";
+}>;
+/**
+ * One (location, icon) assignment as it travels.
+ *
+ * `locationKey` is ALWAYS {@link locationIconKey} of the label — never the
+ * operator's casing. The registry matches labels trimmed + case-insensitively
+ * everywhere (`addLocation`, `removeLocation`, `renameLocation`), and a
+ * case-only rename (`cucina` → `Cucina`) is a real edit this repo supports; a
+ * map keyed on the displayed casing would orphan its entry on exactly that
+ * edit. Consumers join by keying their own label through `locationIconKey`.
+ */
+export declare const LocationIconAssignmentSchema: z.ZodObject<{
+    locationKey: z.ZodString;
+    icon: z.ZodEnum<{
+        package: "package";
+        "map-pin": "map-pin";
+        house: "house";
+        "door-open": "door-open";
+        sofa: "sofa";
+        utensils: "utensils";
+        "bed-double": "bed-double";
+        bath: "bath";
+        briefcase: "briefcase";
+        car: "car";
+        "circle-parking": "circle-parking";
+        route: "route";
+        trees: "trees";
+        umbrella: "umbrella";
+        "waves-ladder": "waves-ladder";
+        fence: "fence";
+        warehouse: "warehouse";
+        store: "store";
+        sun: "sun";
+        radar: "radar";
+    }>;
+}, z.core.$strip>;
+/** @see LocationIconAssignmentSchema */
+export type LocationIconAssignment = z.infer<typeof LocationIconAssignmentSchema>;
+/**
+ * The join key for a location label: trimmed, lower-cased. The ONE place this
+ * derivation lives — a caller that re-spells it is a rename away from an
+ * orphaned icon.
+ */
+export declare function locationIconKey(label: string): string;
+/**
+ * Read an arbitrary stored/wire value as a drawable icon id.
+ *
+ * Anything that is not a member of the vocabulary — `null`, `undefined`, a
+ * hand-edited settings row, an id minted by a newer hub — becomes
+ * {@link LOCATION_ICON_FALLBACK}. Never returns `null`: a caller that wants to
+ * distinguish "no icon chosen" from "icon unknown" must look at the assignment
+ * list, which only carries what was actually stored.
+ */
+export declare function resolveLocationIcon(value: unknown): LocationIconId;
+/**
+ * How long a location description may be.
+ *
+ * It is given to a vision model alongside the pictures, so it competes for the
+ * same attention the pictures need. A cap of one short paragraph is what keeps
+ * it a PLACE description rather than a second prompt — an operator who needs
+ * more than this is describing events, which change, instead of the ground,
+ * which does not.
+ */
+export declare const LOCATION_DESCRIPTION_MAX = 400;
+/**
+ * One (location, description) assignment as it travels.
+ *
+ * Same key discipline as {@link LocationIconAssignmentSchema}, and for the same
+ * reason: this lived for a while in the post-analysis addon's own settings,
+ * keyed by a HAND-TYPED label matched exactly and case-sensitively. A rename in
+ * the Locations page carried the icon and silently orphaned the description —
+ * two authorities for one thing, joined by two different rules. Now both hang
+ * off the location itself, on `locationIconKey`.
+ */
+export declare const LocationDescriptionAssignmentSchema: z.ZodObject<{
+    locationKey: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+/** @see LocationDescriptionAssignmentSchema */
+export type LocationDescriptionAssignment = z.infer<typeof LocationDescriptionAssignmentSchema>;

package/dist/device/site-zone.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A SITE ZONE — a named part of the property that several locations belong to.
+ *
+ * "Zona notte" holds every bedroom; "Zona giorno" the living room and the
+ * kitchen. A camera belongs to exactly one location, and a location to at most
+ * one zone, so a camera's zone is derived and never stored on the device: the
+ * whole point of this entity is that grouping rooms touches no device row.
+ *
+ * ## Why not `zone`
+ *
+ * Because `zone` is already the most loaded word in this product: 612 source
+ * files and 24 Italian strings where it means a DETECTION zone drawn on a
+ * camera. The two are unrelated — one is a polygon in a frame, the other is a
+ * set of rooms — and a reader who confuses them will look for a camera's
+ * bedrooms. So the code says `siteZone` everywhere, and the UI frees the plain
+ * word by calling the drawn one what it actually is: a detection zone.
+ *
+ * ## The key
+ *
+ * `siteZoneKey(label)` — trimmed, lower-cased, the SAME derivation locations
+ * use (`locationIconKey`). Membership and the icon both hang off it, so a
+ * case-only rename keeps them, which is exactly the orphaning that cost us a
+ * silently-dropped location description.
+ *
+ * The icon vocabulary is the location one, unchanged: a zone is drawn on the
+ * same two surfaces by the same glyph map, so a second vocabulary would be a
+ * second thing to keep drawable (`scripts/check-location-icons-drawable.ts`).
+ */
+import { z } from 'zod';
+/**
+ * One zone as it travels: its key, the label the operator typed, its icon and
+ * the locations inside it.
+ *
+ * The LABEL is carried alongside the key because the key is lossy on purpose —
+ * a surface must show "Zona notte", not "zona notte". Locations are carried
+ * here, rather than left to a second call, because every consumer wants both
+ * at once and a viewer that asked twice could render a zone whose membership
+ * it has not fetched yet.
+ *
+ * `icon: null` means nobody chose one, which is NOT the fallback pin: only one
+ * of those two is a choice, and a picker has to draw them differently.
+ */
+export declare const SiteZoneSchema: z.ZodObject<{
+    zoneKey: z.ZodString;
+    label: z.ZodString;
+    icon: z.ZodNullable<z.ZodEnum<{
+        package: "package";
+        "map-pin": "map-pin";
+        house: "house";
+        "door-open": "door-open";
+        sofa: "sofa";
+        utensils: "utensils";
+        "bed-double": "bed-double";
+        bath: "bath";
+        briefcase: "briefcase";
+        car: "car";
+        "circle-parking": "circle-parking";
+        route: "route";
+        trees: "trees";
+        umbrella: "umbrella";
+        "waves-ladder": "waves-ladder";
+        fence: "fence";
+        warehouse: "warehouse";
+        store: "store";
+        sun: "sun";
+        radar: "radar";
+    }>>;
+    locationKeys: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** @see SiteZoneSchema */
+export type SiteZone = z.infer<typeof SiteZoneSchema>;
+/**
+ * The join key for a zone label: trimmed, lower-cased.
+ *
+ * Deliberately a separate export from `locationIconKey` even though the
+ * derivation is identical — they key different maps, and a future change to one
+ * must not silently re-key the other. Their agreement is a fact about today,
+ * not a dependency.
+ */
+export declare function siteZoneKey(label: string): string;

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

@@ -2254,6 +2254,69 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof deviceManagerCapability.methods.renameLocation.output>;
             meta: object;
         }>;
+        listLocationIcons: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof deviceManagerCapability.methods.listLocationIcons.output>;
+            meta: object;
+        }>;
+        setLocationIcon: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.setLocationIcon.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.setLocationIcon.output>;
+            meta: object;
+        }>;
+        listLocationDescriptions: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof deviceManagerCapability.methods.listLocationDescriptions.output>;
+            meta: object;
+        }>;
+        setLocationDescription: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.setLocationDescription.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.setLocationDescription.output>;
+            meta: object;
+        }>;
+        listSiteZones: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof deviceManagerCapability.methods.listSiteZones.output>;
+            meta: object;
+        }>;
+        setSiteZone: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.setSiteZone.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.setSiteZone.output>;
+            meta: object;
+        }>;
+        removeSiteZone: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.removeSiteZone.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.removeSiteZone.output>;
+            meta: object;
+        }>;
+        renameSiteZone: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.renameSiteZone.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.renameSiteZone.output>;
+            meta: object;
+        }>;
+        setLocationZone: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.setLocationZone.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.setLocationZone.output>;
+            meta: object;
+        }>;
         setDisabled: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 1039 method paths across 130 capabilities.
+ * Coverage: 1048 method paths across 130 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/system-proxy.d.ts

@@ -68,7 +68,7 @@ export interface SystemProxy {
     readonly decoder: Pick<InferProvider<typeof decoderCapability>, 'supportsCodec' | 'getInfo' | 'createSession' | 'destroySession' | 'pushPacket' | 'openStream' | 'pullFrames' | 'pullHandles' | 'getFrame' | 'getShmStats' | 'updateConfig' | 'getStats' | 'listActiveSessions' | 'reprobeHwaccel'>;
     readonly deviceAdoption: Pick<InferProvider<typeof deviceAdoptionCapability>, 'listCandidateFilters' | 'listCandidates' | 'getCandidate' | 'refresh' | 'adopt' | 'release' | 'resync'>;
     readonly deviceExport: Pick<InferProvider<typeof deviceExportCapability>, 'getStatus' | 'listSupportedDeviceKinds' | 'listExposedDevices' | 'exposeDevice' | 'unexposeDevice'>;
-    readonly deviceManager: Pick<InferProvider<typeof deviceManagerCapability>, 'allocateDeviceId' | 'migrateDevice' | 'registerDevice' | 'removeDevice' | 'persistConfig' | 'getRoleDisplayDefaults' | 'setRoleDisplayDefaults' | 'listLocations' | 'addLocation' | 'removeLocation' | 'renameLocation' | 'listPersistedByAddon' | 'listAll' | 'getChildren' | 'getChildrenBatch' | 'getLinkedDevicesBatch' | 'removeByIntegration' | 'getBindingsBatch' | 'getAllBindings' | 'listWrappersForCap' | 'listBindableCapsForDeviceType' | 'discoverDevices' | 'adoptDevice' | 'getCreationSchema' | 'createDevice' | 'testCreationField' | 'adoptionListCandidateFilters' | 'adoptionListCandidates' | 'adoptionRefresh' | 'adoptionAdopt' | 'adoptionRelease' | 'adoptionStartJob' | 'adoptionListJobs' | 'adoptionCancelJob' | 'adoptionResync' | 'discoveryProviders' | 'discoverAllProviders' | 'discoverProvider' | 'providerCreationType' | 'providerDiscoveryParamsSchema' | 'getDeviceStatusAggregateBatch'>;
+    readonly deviceManager: Pick<InferProvider<typeof deviceManagerCapability>, 'allocateDeviceId' | 'migrateDevice' | 'registerDevice' | 'removeDevice' | 'persistConfig' | 'getRoleDisplayDefaults' | 'setRoleDisplayDefaults' | 'listLocations' | 'addLocation' | 'removeLocation' | 'renameLocation' | 'listLocationIcons' | 'setLocationIcon' | 'listLocationDescriptions' | 'setLocationDescription' | 'listSiteZones' | 'setSiteZone' | 'removeSiteZone' | 'renameSiteZone' | 'setLocationZone' | 'listPersistedByAddon' | 'listAll' | 'getChildren' | 'getChildrenBatch' | 'getLinkedDevicesBatch' | 'removeByIntegration' | 'getBindingsBatch' | 'getAllBindings' | 'listWrappersForCap' | 'listBindableCapsForDeviceType' | 'discoverDevices' | 'adoptDevice' | 'getCreationSchema' | 'createDevice' | 'testCreationField' | 'adoptionListCandidateFilters' | 'adoptionListCandidates' | 'adoptionRefresh' | 'adoptionAdopt' | 'adoptionRelease' | 'adoptionStartJob' | 'adoptionListJobs' | 'adoptionCancelJob' | 'adoptionResync' | 'discoveryProviders' | 'discoverAllProviders' | 'discoverProvider' | 'providerCreationType' | 'providerDiscoveryParamsSchema' | 'getDeviceStatusAggregateBatch'>;
     readonly deviceProvider: Pick<InferProvider<typeof deviceProviderCapability>, 'start' | 'stop' | 'getStatus' | 'getDevices' | 'supportsDiscovery' | 'discoverDevices' | 'getDiscoveryParamsSchema' | 'getManualCreationType' | 'adoptDiscoveredDevice' | 'supportsManualCreation' | 'getChildCreationSchema' | 'createDevice' | 'testCreationField'>;
     readonly deviceState: Pick<InferProvider<typeof deviceStateCapability>, 'getAllSnapshots'>;
     readonly faceGallery: Pick<InferProvider<typeof faceGalleryCapability>, 'listIdentities' | 'createIdentity' | 'renameIdentity' | 'deleteIdentity' | 'listIdentitySamples' | 'auditIdentitySamples' | 'removeSample' | 'getFaceMedia' | 'assignFace' | 'unassignFace' | 'deleteFace' | 'assignFaces' | 'unassignFaces' | 'suggestFaceClusters'>;

package/dist/index.d.ts

@@ -174,6 +174,8 @@ export type { SliceEventBus, SliceHandle, SliceHandleApi, SliceHandleSource, } f
 export { createEventBusSliceSource, createLazyTrpcSource, createMirrorSource, createSliceHandle, } from './device/device-state-handle.js';
 export { ChargingStatus, DeviceFeature, DeviceRole, DeviceType } from './device/device-type.js';
 export type { IBatteryOperated, IDoorbellButton, INativeSnapshot, IPanTiltZoom, IRebootable, ITwoWayAudio, } from './device/features.js';
+export type { LocationDescriptionAssignment, LocationIconAssignment, LocationIconId, } from './device/location-icon.js';
+export { LOCATION_ICON_FALLBACK, LOCATION_ICON_IDS, LOCATION_DESCRIPTION_MAX, LocationDescriptionAssignmentSchema, LocationIconAssignmentSchema, LocationIconIdSchema, locationIconKey, resolveLocationIcon, } from './device/location-icon.js';
 export { getByPath, setByPath } from './device/path-util.js';
 export type { ReachabilityPollHandle, ReachabilityPollLogger, ReachabilityPollOptions, } from './device/reachability-poll.js';
 export { REACHABILITY_FAILURES_TO_OFFLINE, REACHABILITY_POLL_INTERVAL_MS, REACHABILITY_PROBE_TIMEOUT_MS, startReachabilityPoll, } from './device/reachability-poll.js';
@@ -255,3 +257,5 @@ export { evaluateZoneRules, type ZoneRuleEvalResult } from './utils/zone-rule-ev
 export { bindAddonActions } from './helpers/bind-addon-actions.js';
 export type { DeviceOption, InferenceDeviceDescriptor, RuntimeId, } from './inference/runtime-capabilities.js';
 export { defaultDeviceFor, enumerateInferenceDevices, modelFormatForRuntime, runtimeDevices, scoreRuntimes, supportedRuntimes, } from './inference/runtime-capabilities.js';
+export type { SiteZone } from './device/site-zone.js';
+export { SiteZoneSchema, siteZoneKey } from './device/site-zone.js';