@camstack/system 1.2.242 → 1.2.244

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -1,5 +1,5 @@
-import { $t as DeviceRole, G as deviceManagerCapability, Jt as BaseAddon, K as deviceStateCapability, L as buildStreamParamsConfigSchema, Mt as runtimeStatePolicyFor, Qt as DeviceFeature, S as STREAM_PROFILE_META, St as normalizeUnit, X as enumerateItemArrayFields, Z as enumerateSchemaFields, a as CAMERA_SWITCH_ORDER, bn as EventCategory, en as DeviceType, f as DeviceStatusSchema, fn as isDeviceConfigCap, kt as resolveContainerPrimaryChild, o as CAP_NAMES_WITH_STATUS, q as deviceStatusCapability, qt as errMsg, rn as WELL_KNOWN_TAB_MAP, t as ALL_CAPABILITY_DEFINITIONS, wt as parseStreamParamsFormPatch, yn as sleep$1 } from "../../dist-DkGEz_3L.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-BSsaf7n4.mjs";
+import { C as STREAM_PROFILE_META, Cn as EventCategory, Et as parseStreamParamsFormPatch, J as deviceStatusCapability, K as deviceManagerCapability, Pt as runtimeStatePolicyFor, Q as enumerateSchemaFields, R as buildStreamParamsConfigSchema, Sn as sleep$1, Xt as errMsg, Z as enumerateItemArrayFields, Zt as BaseAddon, a as CAMERA_SWITCH_ORDER, f as DeviceStatusSchema, gt as locationIconKey, h as LocationIconIdSchema, hn as isDeviceConfigCap, jt as resolveContainerPrimaryChild, nn as DeviceRole, o as CAP_NAMES_WITH_STATUS, on as WELL_KNOWN_TAB_MAP, q as deviceStateCapability, rn as DeviceType, t as ALL_CAPABILITY_DEFINITIONS, tn as DeviceFeature, wt as normalizeUnit, zt as siteZoneKey } from "../../dist-4MS1GNc8.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-D_5MkKII.mjs";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
 //#region src/builtins/device-manager/adoption-job-engine.ts
@@ -3923,7 +3923,8 @@ async function runLocationBackfillAtBoot(pctx, bootRows) {
 * setLocation, setType, setIntegrationId, setLinkDeviceId,
 * setPrimaryChildEntityId, setChildLayout, setRole, setDisplay,
 * applyInitialMeta, setMetadata, setDisabled), and the location registry
-* (listLocations, addLocation, removeLocation).
+* (listLocations, addLocation, removeLocation, renameLocation) with its icon
+* map (listLocationIcons, setLocationIcon).
 *
 * EXACT ordering and side effects preserved — notably registerDevice's
 * name-precedence reconcile + field-preservation spreads, the
@@ -4975,6 +4976,311 @@ async function addLocation(pctx, input) {
 	});
 }
 /**
+* Every location that carries an icon, as `(locationKey, icon)` pairs.
+*
+* ADDITIVE beside `listLocations`, which still answers `string[]` — the
+* autocomplete, the HA adoption import and the recorder all read a list of
+* LABELS and a shape change there would break every one of them. A surface
+* that wants icons asks for them and joins on `locationIconKey`.
+*
+* Returns only what was actually stored. A location with no assignment is
+* ABSENT, never `map-pin`: the fallback belongs to the renderer
+* (`resolveLocationIcon`), and folding it in here would make "the operator
+* picked the pin" indistinguishable from "the operator picked nothing" —
+* which is the difference an icon picker has to draw.
+*/
+async function listLocationIcons(pctx) {
+	const icons = (await pctx.metaStore.readStore()).locationIcons ?? {};
+	return Object.entries(icons).map(([locationKey, icon]) => ({
+		locationKey,
+		icon
+	})).toSorted((a, b) => a.locationKey.localeCompare(b.locationKey));
+}
+/**
+* Set (or clear) the icon of a location label.
+*
+* Keyed on `locationIconKey` — trimmed + lower-cased, the equality the
+* registry matches on everywhere — so a case-only rename keeps the icon and
+* two spellings of one room can never carry two different icons.
+*
+* The label need NOT be registered: `setLocation` accepts a free-form string
+* and `listLocations` folds in whatever devices carry, so requiring
+* registration here would leave exactly the ad-hoc rooms unable to have an
+* icon. An empty label throws — there is no room to name.
+*
+* Same read-modify-write and same lock as `addLocation`: the map is one key of
+* the addon store, and `writeAddonStore` re-inserts the whole key range, so an
+* unordered write carries a stale copy of every other key.
+*/
+async function setLocationIcon(pctx, input) {
+	const trimmed = input.location.trim();
+	if (trimmed.length === 0) throw new Error("[device-manager] setLocationIcon: location must be non-empty");
+	const key = locationIconKey(trimmed);
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const icons = (await pctx.metaStore.readStore()).locationIcons ?? {};
+		if (input.icon === null) {
+			if (!(key in icons)) return;
+			const { [key]: _cleared, ...kept } = icons;
+			await pctx.settings.writeAddonStore({ locationIcons: kept });
+			return;
+		}
+		if (icons[key] === input.icon) return;
+		await pctx.settings.writeAddonStore({ locationIcons: {
+			...icons,
+			[key]: input.icon
+		} });
+	});
+}
+/**
+* Every location that carries a description, sorted by key.
+*
+* Only what was WRITTEN — a location with no description is absent, and the
+* digest then tells the model the location name alone, exactly as it did
+* before descriptions existed.
+*/
+async function listLocationDescriptions(pctx) {
+	const descriptions = (await pctx.metaStore.readStore()).locationDescriptions ?? {};
+	return Object.entries(descriptions).map(([locationKey, description]) => ({
+		locationKey,
+		description
+	})).toSorted((a, b) => a.locationKey.localeCompare(b.locationKey));
+}
+/**
+* Set (or clear) a location's description.
+*
+* A BLANK description clears, exactly as `null` does: an empty line handed to
+* a vision model costs attention and says nothing, so the two must not be
+* different states. The label is folded with `locationIconKey` — the same key
+* the icon uses, which is the whole point of this living here.
+*
+* Same read-modify-write and same lock as `setLocationIcon`; `writeAddonStore`
+* re-inserts the whole key range, so an unordered write carries a stale copy
+* of every other key.
+*/
+async function setLocationDescription(pctx, input) {
+	const trimmed = input.location.trim();
+	if (trimmed.length === 0) throw new Error("[device-manager] setLocationDescription: location must be non-empty");
+	const key = locationIconKey(trimmed);
+	const text = input.description === null ? "" : input.description.trim();
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const descriptions = (await pctx.metaStore.readStore()).locationDescriptions ?? {};
+		if (text.length === 0) {
+			if (!(key in descriptions)) return;
+			const { [key]: _cleared, ...kept } = descriptions;
+			await pctx.settings.writeAddonStore({ locationDescriptions: kept });
+			return;
+		}
+		if (descriptions[key] === text) return;
+		await pctx.settings.writeAddonStore({ locationDescriptions: {
+			...descriptions,
+			[key]: text
+		} });
+	});
+}
+/**
+* Every site zone, with its rooms, sorted by key.
+*
+* Membership is inverted HERE rather than stored both ways: the store keeps
+* `location → zone`, which is what makes "one zone per room" structural, and a
+* second copy keyed the other way is a second thing that can disagree with the
+* first.
+*/
+async function listSiteZones(pctx) {
+	const store = await pctx.metaStore.readStore();
+	const zones = store.siteZones ?? {};
+	const membership = store.locationZones ?? {};
+	const rooms = /* @__PURE__ */ new Map();
+	for (const [locationKey, zoneKey] of Object.entries(membership)) {
+		const list = rooms.get(zoneKey);
+		if (list === void 0) rooms.set(zoneKey, [locationKey]);
+		else list.push(locationKey);
+	}
+	return Object.entries(zones).map(([zoneKey, record]) => ({
+		zoneKey,
+		label: record.label,
+		icon: record.icon ?? null,
+		locationKeys: (rooms.get(zoneKey) ?? []).toSorted((a, b) => a.localeCompare(b))
+	})).toSorted((a, b) => a.zoneKey.localeCompare(b.zoneKey));
+}
+/**
+* Create a zone, or set the icon of one that already exists.
+*
+* `icon: null` clears the icon and KEEPS the zone. Conflating the two would
+* make a mis-click on "no icon" delete every room's membership — the icon is a
+* decoration and the grouping is the data.
+*
+* `icon` OMITTED leaves whatever icon is there: creating a zone from a screen
+* with no picker must not silently clear the glyph a previous screen set.
+*/
+async function setSiteZone(pctx, input) {
+	const label = input.name.trim();
+	if (label.length === 0) throw new Error("[device-manager] setSiteZone: name must be non-empty");
+	const key = siteZoneKey(label);
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const zones = (await pctx.metaStore.readStore()).siteZones ?? {};
+		const existing = zones[key];
+		const icon = input.icon === void 0 ? existing?.icon : input.icon === null ? void 0 : input.icon;
+		const next = icon === void 0 ? { label } : {
+			label,
+			icon
+		};
+		if (existing?.label === next.label && existing.icon === next.icon) return;
+		await pctx.settings.writeAddonStore({ siteZones: {
+			...zones,
+			[key]: next
+		} });
+	});
+}
+/**
+* Delete a zone. Its LOCATIONS survive, unattached.
+*
+* Deleting a grouping must never delete what was grouped — the rooms exist
+* independently and the devices in them were never touched to begin with.
+*/
+async function removeSiteZone(pctx, input) {
+	const key = siteZoneKey(input.name);
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const store = await pctx.metaStore.readStore();
+		const zones = store.siteZones ?? {};
+		const membership = store.locationZones ?? {};
+		const hadZone = key in zones;
+		const orphaned = Object.entries(membership).filter(([, zoneKey]) => zoneKey === key);
+		if (!hadZone && orphaned.length === 0) return;
+		const { [key]: _dropped, ...keptZones } = zones;
+		const keptMembership = Object.fromEntries(Object.entries(membership).filter(([, zoneKey]) => zoneKey !== key));
+		await pctx.settings.writeAddonStore({
+			...hadZone ? { siteZones: keptZones } : {},
+			...orphaned.length > 0 ? { locationZones: keptMembership } : {}
+		});
+	});
+}
+/**
+* Rename a zone, carrying its icon AND every room in it.
+*
+* It exists so that renaming is not delete-then-recreate, which drops both.
+* A rename onto an existing zone MERGES: the target keeps its own icon and the
+* rooms are unioned, the same rule `renameLocation` follows.
+*/
+async function renameSiteZone(pctx, input) {
+	const toLabel = input.to.trim();
+	if (toLabel.length === 0) throw new Error("[device-manager] renameSiteZone: target name must be non-empty");
+	const fromKey = siteZoneKey(input.from);
+	const toKey = siteZoneKey(toLabel);
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const store = await pctx.metaStore.readStore();
+		const zones = store.siteZones ?? {};
+		const moved = zones[fromKey];
+		if (moved === void 0) return;
+		const { [fromKey]: _dropped, ...rest } = zones;
+		const target = rest[toKey];
+		const nextZones = {
+			...rest,
+			[toKey]: target ?? (moved.icon === void 0 ? { label: toLabel } : {
+				label: toLabel,
+				icon: moved.icon
+			})
+		};
+		const membership = store.locationZones ?? {};
+		const nextMembership = Object.fromEntries(Object.entries(membership).map(([locationKey, zoneKey]) => [locationKey, zoneKey === fromKey ? toKey : zoneKey]));
+		await pctx.settings.writeAddonStore({
+			siteZones: nextZones,
+			locationZones: nextMembership
+		});
+	});
+}
+/**
+* Put a location in a zone, or take it out with `zone: null`.
+*
+* ONE slot per location, so a second call moves the room rather than listing it
+* twice. The zone is created if it does not exist — a screen that assigns
+* before creating is a normal order, and refusing it would be the only place in
+* this registry that demands registration first.
+*/
+async function setLocationZone(pctx, input) {
+	const location = input.location.trim();
+	if (location.length === 0) throw new Error("[device-manager] setLocationZone: location must be non-empty");
+	const locationKey = locationIconKey(location);
+	const label = input.zone === null ? null : input.zone.trim();
+	if (label !== null && label.length === 0) throw new Error("[device-manager] setLocationZone: zone must be non-empty or null");
+	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
+		const store = await pctx.metaStore.readStore();
+		const membership = store.locationZones ?? {};
+		if (label === null) {
+			if (!(locationKey in membership)) return;
+			const { [locationKey]: _cleared, ...kept } = membership;
+			await pctx.settings.writeAddonStore({ locationZones: kept });
+			return;
+		}
+		const zoneKey = siteZoneKey(label);
+		const zones = store.siteZones ?? {};
+		const needsZone = !(zoneKey in zones);
+		if (membership[locationKey] === zoneKey && !needsZone) return;
+		await pctx.settings.writeAddonStore({
+			...needsZone ? { siteZones: {
+				...zones,
+				[zoneKey]: { label }
+			} } : {},
+			locationZones: {
+				...membership,
+				[locationKey]: zoneKey
+			}
+		});
+	});
+}
+/**
+* Move a location's zone membership from one key to another, for
+* `renameLocation`. Same shape as the icon and description movers.
+*/
+function renameLocationZone(membership, fromKey, toKey) {
+	const moved = membership[fromKey];
+	if (moved === void 0) return null;
+	if (fromKey === toKey) return null;
+	const { [fromKey]: _dropped, ...rest } = membership;
+	return toKey in rest ? rest : {
+		...rest,
+		[toKey]: moved
+	};
+}
+/**
+* Move a location's description from one key to another, for `renameLocation`.
+*
+* Identical rule to {@link renameLocationIcon}, deliberately: a merge keeps the
+* TARGET's description, because renaming "Sala" into "Salone" moves devices
+* into Salone and does not re-describe it. Split from the icon mover only
+* because the value types differ; if one ever changes, the other must.
+*/
+function renameLocationDescription(descriptions, fromKey, toKey) {
+	const moved = descriptions[fromKey];
+	if (moved === void 0) return null;
+	if (fromKey === toKey) return null;
+	const { [fromKey]: _dropped, ...rest } = descriptions;
+	return toKey in rest ? rest : {
+		...rest,
+		[toKey]: moved
+	};
+}
+/**
+* Move a location's icon from one key to another, for `renameLocation`.
+*
+* Returns `null` when NOTHING changes, so the caller can leave the key out of
+* its `writeAddonStore` patch instead of re-writing an identical map.
+*
+* A rename onto a room that already has an icon is a MERGE, and the surviving
+* room keeps its own: the operator renaming "Sala" into "Salone" is moving
+* devices into Salone, not restyling it. The source key is dropped either way.
+* Pure — builds a new record, mutates nothing.
+*/
+function renameLocationIcon(icons, fromKey, toKey) {
+	const moved = icons[fromKey];
+	if (moved === void 0) return null;
+	if (fromKey === toKey) return null;
+	const { [fromKey]: _dropped, ...rest } = icons;
+	return toKey in rest ? rest : {
+		...rest,
+		[toKey]: moved
+	};
+}
+/**
 * Remove a label from the curated registry. Match is
 * case-insensitive. Devices that still reference this label keep
 * their `meta.location` value (the registry is a suggestion
@@ -5005,13 +5311,23 @@ async function renameLocation(pctx, input) {
 	const fromKey = from.toLowerCase();
 	const toKey = to.toLowerCase();
 	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
-		const current = (await pctx.metaStore.readStore()).locations ?? [];
-		if (!current.some((l) => l.trim().toLowerCase() === fromKey)) return;
+		const store = await pctx.metaStore.readStore();
+		const current = store.locations ?? [];
+		const registered = current.some((l) => l.trim().toLowerCase() === fromKey);
+		const movedIcons = renameLocationIcon(store.locationIcons ?? {}, fromKey, toKey);
+		const movedDescriptions = renameLocationDescription(store.locationDescriptions ?? {}, fromKey, toKey);
+		const movedZones = renameLocationZone(store.locationZones ?? {}, fromKey, toKey);
+		if (!registered && movedIcons === null && movedDescriptions === null && movedZones === null) return;
 		const kept = current.filter((l) => {
 			const key = l.trim().toLowerCase();
 			return key !== fromKey && key !== toKey;
 		});
-		await pctx.settings.writeAddonStore({ locations: [...kept, to] });
+		await pctx.settings.writeAddonStore({
+			...registered ? { locations: [...kept, to] } : {},
+			...movedIcons !== null ? { locationIcons: movedIcons } : {},
+			...movedDescriptions !== null ? { locationDescriptions: movedDescriptions } : {},
+			...movedZones !== null ? { locationZones: movedZones } : {}
+		});
 	});
 	const moved = await pctx.metaStore.withMetaWriteLock(async () => {
 		const out = [];
@@ -5049,10 +5365,27 @@ async function removeLocation(pctx, input) {
 	const trimmed = input.name.trim();
 	if (trimmed.length === 0) return;
 	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
-		const current = (await pctx.metaStore.readStore()).locations ?? [];
-		const remaining = current.filter((l) => l.toLowerCase() !== trimmed.toLowerCase());
-		if (remaining.length === current.length) return;
-		await pctx.settings.writeAddonStore({ locations: remaining });
+		const store = await pctx.metaStore.readStore();
+		const current = store.locations ?? [];
+		const key = locationIconKey(trimmed);
+		const remaining = current.filter((l) => l.toLowerCase() !== key);
+		const droppedLabel = remaining.length !== current.length;
+		const icons = store.locationIcons ?? {};
+		const droppedIcon = key in icons;
+		const descriptions = store.locationDescriptions ?? {};
+		const droppedDescription = key in descriptions;
+		const membership = store.locationZones ?? {};
+		const droppedZone = key in membership;
+		if (!droppedLabel && !droppedIcon && !droppedDescription && !droppedZone) return;
+		const { [key]: _removedIcon, ...keptIcons } = icons;
+		const { [key]: _removedDescription, ...keptDescriptions } = descriptions;
+		const { [key]: _removedZone, ...keptMembership } = membership;
+		await pctx.settings.writeAddonStore({
+			...droppedLabel ? { locations: remaining } : {},
+			...droppedIcon ? { locationIcons: keptIcons } : {},
+			...droppedDescription ? { locationDescriptions: keptDescriptions } : {},
+			...droppedZone ? { locationZones: keptMembership } : {}
+		});
 	});
 	if (input.cascade !== true) return;
 	const cleared = await pctx.metaStore.withMetaWriteLock(async () => {
@@ -5154,12 +5487,96 @@ function decodeAddonStore(raw) {
 	const nextDeviceId = raw["nextDeviceId"];
 	const locations = raw["locations"];
 	const roleDisplayDefaults = raw["roleDisplayDefaults"];
+	const locationIcons = decodeLocationIcons(raw["locationIcons"]);
+	const locationDescriptions = decodeLocationDescriptions(raw["locationDescriptions"]);
+	const siteZones = decodeSiteZones(raw["siteZones"]);
+	const locationZones = decodeStringMap(raw["locationZones"]);
 	return {
 		...typeof nextDeviceId === "number" && Number.isFinite(nextDeviceId) ? { nextDeviceId } : {},
 		...Array.isArray(locations) ? { locations: locations.filter((l) => typeof l === "string") } : {},
-		...isRoleDisplayDefaults(roleDisplayDefaults) ? { roleDisplayDefaults } : {}
+		...isRoleDisplayDefaults(roleDisplayDefaults) ? { roleDisplayDefaults } : {},
+		...locationIcons !== null ? { locationIcons } : {},
+		...locationDescriptions !== null ? { locationDescriptions } : {},
+		...siteZones !== null ? { siteZones } : {},
+		...locationZones !== null ? { locationZones } : {}
 	};
 }
+/**
+* Decode the `locationIcons` map, dropping every entry whose value is not a
+* member of the closed vocabulary.
+*
+* Dropping, not passing through: the icon's whole point is that both surfaces
+* can draw it, and an id from a hand-edit or a newer hub is exactly the value
+* that draws nothing. Absent reads as "no icon chosen", which every renderer
+* already degrades to the fallback pin. Returns `null` when the key itself is
+* absent or of the wrong shape, so the field stays OMITTED rather than being
+* written back as an empty object.
+*/
+function decodeLocationIcons(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		const parsed = LocationIconIdSchema.safeParse(value);
+		if (!parsed.success) continue;
+		out[key] = parsed.data;
+	}
+	return out;
+}
+/**
+* Decode the `locationDescriptions` map, dropping every entry that is not a
+* non-blank string.
+*
+* Same posture as the icons: a blank description and a missing one are the
+* same instruction to every reader, and storing the first would send an empty
+* line to a vision model. Over-long text is TRUNCATED rather than dropped —
+* losing the whole description because a hand-edit ran long is a worse answer
+* than losing its tail.
+*/
+function decodeLocationDescriptions(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (typeof value !== "string") continue;
+		const text = value.trim();
+		if (text.length === 0) continue;
+		out[key] = text.slice(0, 400);
+	}
+	return out;
+}
+/**
+* Decode the zone registry, dropping any entry without a usable label.
+*
+* A zone whose label did not survive a hand-edit cannot be shown or renamed —
+* it would be a row the operator can see the effects of and never name. An
+* icon outside the vocabulary is dropped on its own, leaving the zone: losing
+* a glyph is a smaller loss than losing the grouping.
+*/
+function decodeSiteZones(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+		const rec = value;
+		const label = typeof rec["label"] === "string" ? rec["label"].trim() : "";
+		if (label.length === 0) continue;
+		const icon = LocationIconIdSchema.safeParse(rec["icon"]);
+		out[key] = icon.success ? {
+			label,
+			icon: icon.data
+		} : { label };
+	}
+	return out;
+}
+/** Decode a plain `string → string` map, dropping anything else. */
+function decodeStringMap(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (typeof value !== "string" || value.trim().length === 0) continue;
+		out[key] = value;
+	}
+	return out;
+}
 function isRoleDisplayDefaults(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -6992,6 +7409,15 @@ var DeviceManagerAddon = class extends BaseAddon {
 			addLocation: (input) => addLocation(pctx, input),
 			removeLocation: (input) => removeLocation(pctx, input),
 			renameLocation: (input) => renameLocation(pctx, input),
+			listLocationIcons: () => listLocationIcons(pctx),
+			setLocationIcon: (input) => setLocationIcon(pctx, input),
+			listLocationDescriptions: () => listLocationDescriptions(pctx),
+			setLocationDescription: (input) => setLocationDescription(pctx, input),
+			listSiteZones: () => listSiteZones(pctx),
+			setSiteZone: (input) => setSiteZone(pctx, input),
+			removeSiteZone: (input) => removeSiteZone(pctx, input),
+			renameSiteZone: (input) => renameSiteZone(pctx, input),
+			setLocationZone: (input) => setLocationZone(pctx, input),
 			listPersistedByAddon: (input) => listPersistedByAddon(pctx, input),
 			listAll: (input) => listAll(pctx, input),
 			getDevice: (input) => getDevice(pctx, input),

package/dist/builtins/device-manager/device-meta-actions.d.ts

@@ -212,6 +212,103 @@ export declare function listLocations(pctx: ProviderContext): ReturnType<IDevice
  * meaningful label.
  */
 export declare function addLocation(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['addLocation']>[0]): ReturnType<IDeviceManagerProvider['addLocation']>;
+/**
+ * Every location that carries an icon, as `(locationKey, icon)` pairs.
+ *
+ * ADDITIVE beside `listLocations`, which still answers `string[]` — the
+ * autocomplete, the HA adoption import and the recorder all read a list of
+ * LABELS and a shape change there would break every one of them. A surface
+ * that wants icons asks for them and joins on `locationIconKey`.
+ *
+ * Returns only what was actually stored. A location with no assignment is
+ * ABSENT, never `map-pin`: the fallback belongs to the renderer
+ * (`resolveLocationIcon`), and folding it in here would make "the operator
+ * picked the pin" indistinguishable from "the operator picked nothing" —
+ * which is the difference an icon picker has to draw.
+ */
+export declare function listLocationIcons(pctx: ProviderContext): ReturnType<IDeviceManagerProvider['listLocationIcons']>;
+/**
+ * Set (or clear) the icon of a location label.
+ *
+ * Keyed on `locationIconKey` — trimmed + lower-cased, the equality the
+ * registry matches on everywhere — so a case-only rename keeps the icon and
+ * two spellings of one room can never carry two different icons.
+ *
+ * The label need NOT be registered: `setLocation` accepts a free-form string
+ * and `listLocations` folds in whatever devices carry, so requiring
+ * registration here would leave exactly the ad-hoc rooms unable to have an
+ * icon. An empty label throws — there is no room to name.
+ *
+ * Same read-modify-write and same lock as `addLocation`: the map is one key of
+ * the addon store, and `writeAddonStore` re-inserts the whole key range, so an
+ * unordered write carries a stale copy of every other key.
+ */
+export declare function setLocationIcon(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setLocationIcon']>[0]): ReturnType<IDeviceManagerProvider['setLocationIcon']>;
+/**
+ * Every location that carries a description, sorted by key.
+ *
+ * Only what was WRITTEN — a location with no description is absent, and the
+ * digest then tells the model the location name alone, exactly as it did
+ * before descriptions existed.
+ */
+export declare function listLocationDescriptions(pctx: ProviderContext): ReturnType<IDeviceManagerProvider['listLocationDescriptions']>;
+/**
+ * Set (or clear) a location's description.
+ *
+ * A BLANK description clears, exactly as `null` does: an empty line handed to
+ * a vision model costs attention and says nothing, so the two must not be
+ * different states. The label is folded with `locationIconKey` — the same key
+ * the icon uses, which is the whole point of this living here.
+ *
+ * Same read-modify-write and same lock as `setLocationIcon`; `writeAddonStore`
+ * re-inserts the whole key range, so an unordered write carries a stale copy
+ * of every other key.
+ */
+export declare function setLocationDescription(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setLocationDescription']>[0]): ReturnType<IDeviceManagerProvider['setLocationDescription']>;
+/**
+ * Every site zone, with its rooms, sorted by key.
+ *
+ * Membership is inverted HERE rather than stored both ways: the store keeps
+ * `location → zone`, which is what makes "one zone per room" structural, and a
+ * second copy keyed the other way is a second thing that can disagree with the
+ * first.
+ */
+export declare function listSiteZones(pctx: ProviderContext): ReturnType<IDeviceManagerProvider['listSiteZones']>;
+/**
+ * Create a zone, or set the icon of one that already exists.
+ *
+ * `icon: null` clears the icon and KEEPS the zone. Conflating the two would
+ * make a mis-click on "no icon" delete every room's membership — the icon is a
+ * decoration and the grouping is the data.
+ *
+ * `icon` OMITTED leaves whatever icon is there: creating a zone from a screen
+ * with no picker must not silently clear the glyph a previous screen set.
+ */
+export declare function setSiteZone(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setSiteZone']>[0]): ReturnType<IDeviceManagerProvider['setSiteZone']>;
+/**
+ * Delete a zone. Its LOCATIONS survive, unattached.
+ *
+ * Deleting a grouping must never delete what was grouped — the rooms exist
+ * independently and the devices in them were never touched to begin with.
+ */
+export declare function removeSiteZone(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['removeSiteZone']>[0]): ReturnType<IDeviceManagerProvider['removeSiteZone']>;
+/**
+ * Rename a zone, carrying its icon AND every room in it.
+ *
+ * It exists so that renaming is not delete-then-recreate, which drops both.
+ * A rename onto an existing zone MERGES: the target keeps its own icon and the
+ * rooms are unioned, the same rule `renameLocation` follows.
+ */
+export declare function renameSiteZone(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['renameSiteZone']>[0]): ReturnType<IDeviceManagerProvider['renameSiteZone']>;
+/**
+ * Put a location in a zone, or take it out with `zone: null`.
+ *
+ * ONE slot per location, so a second call moves the room rather than listing it
+ * twice. The zone is created if it does not exist — a screen that assigns
+ * before creating is a normal order, and refusing it would be the only place in
+ * this registry that demands registration first.
+ */
+export declare function setLocationZone(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setLocationZone']>[0]): ReturnType<IDeviceManagerProvider['setLocationZone']>;
 /**
  * Remove a label from the curated registry. Match is
  * case-insensitive. Devices that still reference this label keep