@camstack/addon-import-alexa 0.2.195 → 0.2.196

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.196] - 2026-11-07
+
+### Fixed
+
+- An Echo that is part of a playing speaker group shows the group's track and artwork.
+
 ## [0.2.195] - 2026-11-07
 
 ### Changed

package/dist/addon.js

@@ -6061,7 +6061,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../types/dist/sleep-AEnTN3b4.mjs
+//#region ../types/dist/sleep-CQP-REJp.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6425,6 +6425,59 @@ Object.fromEntries([
 function isValuelessField(field) {
 	return field.type === "separator" || field.type === "info" || field.type === "qr-code" || field.type === "button" || field.type === "object-array" || field.type === "widget" || field.type === "addon-action-button" || field.type === "device-action-button" || field.type === "account-sign-in" || field.type === "secret-presence";
 }
+/**
+* Base collector: flatten a hydrated `ConfigUISchemaWithValues` into
+* `key → { value, default }`, recursing through `group` and `sub-tabs`
+* layout fields. Keeping `value` and `default` SEPARATE (rather than
+* pre-resolving) lets callers both read the effective value AND detect
+* overrides (`value` differs from `default`). Structural over `unknown`;
+* malformed input yields an empty map, never throws.
+*/
+function collectHydratedFieldEntries(schema) {
+	const out = /* @__PURE__ */ new Map();
+	if (typeof schema !== "object" || schema === null) return out;
+	const sections = schema.sections;
+	if (!Array.isArray(sections)) return out;
+	for (const section of sections) if (typeof section === "object" && section !== null) collectFieldEntriesInto(section.fields, out);
+	return out;
+}
+/** Recursive field walker for {@link collectHydratedFieldEntries}. */
+function collectFieldEntriesInto(fields, into) {
+	if (!Array.isArray(fields)) return;
+	for (const field of fields) {
+		if (typeof field !== "object" || field === null) continue;
+		const type = field.type;
+		if (type === "group") {
+			collectFieldEntriesInto(field.fields, into);
+			continue;
+		}
+		if (type === "sub-tabs") {
+			const tabs = field.tabs;
+			if (Array.isArray(tabs)) {
+				for (const tab of tabs) if (typeof tab === "object" && tab !== null) collectFieldEntriesInto(tab.fields, into);
+			}
+			continue;
+		}
+		const key = field.key;
+		if (typeof key !== "string" || key.length === 0) continue;
+		if (!("value" in field)) continue;
+		into.set(key, {
+			value: field.value,
+			default: field.default
+		});
+	}
+}
+/**
+* Flatten a hydrated settings payload into `key → EFFECTIVE value`
+* (`value ?? default`). The read-side inverse of `hydrateSchema` for the
+* common "just give me the resolved values" case. Built on
+* {@link collectHydratedFieldEntries}.
+*/
+function collectHydratedFieldValues(schema) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [key, entry] of collectHydratedFieldEntries(schema)) out.set(key, entry.value ?? entry.default);
+	return out;
+}
 function hydrateSchema(schema, values, options = {}) {
 	return {
 		...schema.tabs ? { tabs: [...schema.tabs] } : {},
@@ -7664,6 +7717,21 @@ var SCOPED_SETTINGS_SCOPES = [
 	"device-defaults",
 	"node"
 ];
+/** The one refusal of a key a scope did not declare. */
+function assertDeclaredKeys(keys, declared) {
+	const undeclared = keys.filter((key) => !declared.has(key));
+	if (undeclared.length > 0) throw new Error(`scoped settings: [${undeclared.join(", ")}] not declared for this scope (declared: [${[...declared].join(", ")}])`);
+}
+/** Build the handle over an addon's scoped read, write and unset. */
+function createScopedSettings(deps) {
+	return {
+		async get() {
+			return deps.schema.parse(await deps.read());
+		},
+		patch: (patch) => deps.write(Object.fromEntries(Object.entries(patch))),
+		unset: (keys) => deps.unset(keys)
+	};
+}
 /** A write to a secret path could not be stored in the keychain, so it was refused. */
 var KeychainWriteRefusedError = class extends Error {
 	fieldPath;
@@ -8239,7 +8307,16 @@ function createHandle(raw, opts) {
 				return blob;
 			}
 		},
-		writeAddonStore: writeAddon
+		writeAddonStore: writeAddon,
+		removeClearedKeys: (keys) => serialize("addon", async () => {
+			const stored = await readStoredAddonBlob(raw);
+			index.seen("addon", stored);
+			const removable = keys.filter((key) => collectSecretMarkerRefs(stored[key]).length === 0);
+			if (removable.length === 0) return;
+			const patch = Object.fromEntries(removable.map((key) => [key, void 0]));
+			await raw.writeAddonStore(patch);
+			index.wrote("addon", patch);
+		})
 	};
 }
 /** The context the addon sees, plus the private raw view and write outcome. */
@@ -8784,6 +8861,151 @@ var BaseAddon = class {
 		}
 	}
 	/**
+	* Hook: values layered over the stored ones when the FORM of one scope is served
+	* ({@link getScopedSettings}) — a preview that derives dependent options without writing.
+	* Never applied to {@link ScopedSettings.get} or to a write. `null` ⇒ no overlay.
+	*/
+	async scopedSettingsOverlay(_scope, _cap, _nodeId) {
+		return null;
+	}
+	/**
+	* Hook: a write of one scope changed stored values (not called when the store reports no change,
+	* e.g. the write-back of a stored secret). `keys` are the bare field keys of the write, node keys included.
+	*/
+	async onScopedSettingsChanged(_scope, _cap, _keys) {}
+	/** Typed handle over the CLUSTER settings `cap` declares (`clusterSettingsSchema`). */
+	clusterSettings(cap, schema) {
+		return this.scopedHandle("cluster", cap, schema);
+	}
+	/** Typed handle over the fleet defaults of the per-device settings `cap` declares. */
+	deviceDefaults(cap, schema) {
+		return this.scopedHandle("device-defaults", cap, schema);
+	}
+	/**
+	* Typed handle over the settings `cap` owns PER NODE. `nodeId` omitted ⇒ the local node. A node
+	* with no row yields the schema defaults — never a bare-key fallback.
+	*/
+	nodeSettings(cap, schema, nodeId) {
+		return this.scopedHandle("node", cap, schema, nodeId);
+	}
+	/**
+	* {@link state} for a value that is kept per node: stored under `<key>@<nodeId>`, and the
+	* settings store carries `nodeId` in the row data (D986 §1), so a forgotten node's rows go in one
+	* central delete. `nodeId` omitted ⇒ the local node.
+	*/
+	nodeState(key, schema, fallback, nodeId) {
+		this._declaredStateKeys.add(key);
+		return createDurableState({
+			key: nodeScopedKey(key, nodeId ?? this._ctx?.kernel?.localNodeId ?? ""),
+			schema,
+			fallback,
+			read: async () => this.resolveStoredSecrets(await this.readAddonStoreWithRetry()),
+			write: async (patch) => {
+				await this._ctx?.settings?.writeAddonStore(patch);
+			},
+			onParseError: (k, e) => this._ctx?.logger?.warn?.(`durable-state: stored "${k}" failed validation — using fallback`, { meta: {
+				addonId: this._ctx?.id,
+				key: k,
+				error: String(e)
+			} })
+		});
+	}
+	/** The loaded schema `cap` declares for `scope`, or `null`. */
+	async declaredScopedSchema(scope, cap) {
+		await this.loadScopedSchemas(cap);
+		return this.loadedScopedSchemas(cap).find((entry) => entry.scope === scope)?.schema ?? null;
+	}
+	async requireScopedSchema(scope, cap) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) throw new Error(`${this.constructor.name}: cap "${cap}" declares no ${scope} settings`);
+		return schema;
+	}
+	scopedKeys(schema) {
+		return new Set(schema.sections.flatMap((section) => collectValueFieldKeys(section.fields)));
+	}
+	/** `store` narrowed to the keys `schema` declares. */
+	narrowToScope(store, schema) {
+		const keys = this.scopedKeys(schema);
+		return Object.fromEntries(Object.entries(store).filter(([key]) => keys.has(key)));
+	}
+	scopedHandle(scope, cap, schema, nodeId) {
+		return createScopedSettings({
+			schema,
+			read: async () => {
+				const declared = await this.requireScopedSchema(scope, cap);
+				const stored = this.narrowToScope(await this.resolveGlobalStore(nodeId, cap), declared);
+				const effective = collectHydratedFieldValues(hydrateSchema(declared, stored));
+				return {
+					...Object.fromEntries([...effective].filter(([, value]) => value !== void 0)),
+					...stored
+				};
+			},
+			write: (patch) => this.writeScoped(scope, cap, patch, nodeId),
+			unset: (keys) => this.unsetScoped(scope, cap, keys, nodeId)
+		});
+	}
+	/** The one write path of the scoped API: declared keys only, then the global patch. */
+	async writeScoped(scope, cap, patch, nodeId) {
+		assertDeclaredKeys(Object.keys(patch), this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		if (await this.applyGlobalPatch(patch, scope === "node" ? nodeId : void 0, cap)) await this.onScopedSettingsChanged(scope, cap, Object.keys(patch));
+	}
+	/**
+	* Remove declared keys of one scope. A secret goes through {@link clearSecrets} — its keychain
+	* value is released exactly as there — and the emptied row is then removed; every other key is
+	* removed by an `undefined` patch (which a secret transform would read as "keep").
+	*/
+	async unsetScoped(scope, cap, keys, nodeId) {
+		assertDeclaredKeys(keys, this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		const target = scope === "node" ? nodeId : void 0;
+		const tree = this.addonSecretTree();
+		const secretKeys = keys.filter((key) => tree.has(key));
+		const plainKeys = keys.filter((key) => !tree.has(key));
+		let changed = false;
+		if (plainKeys.length > 0) {
+			const patch = Object.fromEntries(plainKeys.map((key) => [key, void 0]));
+			changed = await this.applyGlobalPatch(patch, target, cap) || changed;
+		}
+		if (secretKeys.length > 0) {
+			await this.clearSecretKeys(secretKeys, target, cap);
+			const node = normalizeNodeId(target ?? this._ctx?.kernel?.localNodeId);
+			const rows = secretKeys.map((key) => scope === "node" ? nodeScopedKey(key, node) : key);
+			if (this._secretSettings !== null) await this._secretSettings.removeClearedKeys(rows);
+			else await this._ctx?.settings?.writeAddonStore(Object.fromEntries(rows.map((row) => [row, void 0])));
+			changed = true;
+		}
+		if (changed) await this.onScopedSettingsChanged(scope, cap, [...keys]);
+	}
+	/**
+	* The hydrated form of one scope of one capability's settings (any
+	* {@link scopedSettingsOverlay} applied), or `null` when the capability declares nothing there.
+	*/
+	async getScopedSettings(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const stored = this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema);
+		const overlay = await this.scopedSettingsOverlay(scope, cap, nodeId);
+		return hydrateSchema(schema, overlay ? await this.overlayKeepingMarkers(stored, overlay) : stored, { inlineSecretsAsViews: true });
+	}
+	/** The OPERATOR's write of declared keys of one scope (D787 secret semantics). */
+	async updateScopedSettings(scope, cap, patch, nodeId) {
+		this._operatorWriteDepth++;
+		try {
+			await this.writeScoped(scope, cap, patch, nodeId);
+		} finally {
+			this._operatorWriteDepth--;
+		}
+	}
+	/**
+	* The effective values (`stored ?? default`) of one scope, a secret as its `set` view — never
+	* its value. `null` when the capability declares nothing for the scope.
+	*/
+	async readScopedValues(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const form = hydrateSchema(schema, this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema), { inlineSecretsAsViews: true });
+		return Object.fromEntries([...collectHydratedFieldValues(form)].filter(([, value]) => value !== void 0));
+	}
+	/**
 	* What the create wizard and the integration edit page render for one instance: the addon's
 	* per-instance schema when it declares one, else its global schema (what they always showed).
 	*/
@@ -8935,6 +9157,9 @@ var BaseAddon = class {
 	* a keychain (an older kernel) it writes `''`, as such code always did.
 	*/
 	async clearSecrets(keys, nodeId) {
+		await this.clearSecretKeys(keys, nodeId);
+	}
+	async clearSecretKeys(keys, nodeId, cap) {
 		const tree = this.addonSecretTree();
 		const keychain = this._ctx?.secrets !== void 0;
 		const stored = keychain ? await this.readAddonStoreWithRetry() : {};
@@ -8947,25 +9172,27 @@ var BaseAddon = class {
 			const keychainStored = tree.has(key) || collectSecretMarkerRefs(stored[key]).length > 0;
 			patch[key] = keychain && keychainStored ? SECRET_CLEAR : "";
 		}
-		await this.applyGlobalPatch(patch, nodeId);
+		await this.applyGlobalPatch(patch, nodeId, cap);
 	}
-	async applyGlobalPatch(barePatch, nodeId) {
-		await this.loadScopedSchemas();
-		const keys = this.perNodeKeys();
+	/** Resolves `true` when the write changed stored values. */
+	async applyGlobalPatch(barePatch, nodeId, cap) {
+		await this.loadScopedSchemas(cap);
+		const keys = this.perNodeKeys(cap);
 		const localNode = normalizeNodeId(this._ctx?.kernel?.localNodeId);
 		const target = normalizeNodeId(nodeId ?? this._ctx?.kernel?.localNodeId);
 		const scoped = keys.size > 0 ? scopePatch(barePatch, keys, target) : barePatch;
 		const handle = this._secretSettings;
 		if (handle !== null) {
 			const { changed } = await handle.writeAddonStore(scoped);
-			if (!changed) return;
+			if (!changed) return false;
 		} else await this._ctx?.settings?.writeAddonStore(scoped);
-		if (target !== localNode) return;
+		if (target !== localNode) return true;
 		await this.resolveConfig();
 		await this.onConfigChanged();
 		this.emitLifecycle(EventCategory.AddonUpdated, { level: "global" });
 		const legacy = this.globalSettingsSchema();
 		this.maybeAutoRestart(Object.keys(barePatch), [...legacy === null ? [] : [legacy], ...this.loadedScopedSchemas().map((entry) => entry.schema)]);
+		return true;
 	}
 	/**
 	* The set of field keys the global settings schema declares `perNode: true`
@@ -45494,6 +45721,8 @@ var SettingsSchemaWithValuesSchema = object({
 });
 /** Patch object — keys are field names, values are the new field values. */
 var SettingsPatchSchema = record(string(), unknown());
+/** The scope of a scoped-settings call (D986): where the capability declared the values. */
+var ScopedSettingsScopeSchema = _enum(SCOPED_SETTINGS_SCOPES);
 /** Standard success response for update operations. */
 var SettingsUpdateResultSchema = object({ success: literal(true) });
 method(object({
@@ -45509,6 +45738,25 @@ method(object({
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), SettingsSchemaWithValuesSchema.nullable()), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional(),
+	patch: SettingsPatchSchema
+}), SettingsUpdateResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), record(string(), unknown()).nullable()), method(object({
 	addonId: string(),
 	nodeId: string().optional()
 }), SettingsSchemaWithValuesSchema.nullable()), method(object({
@@ -78500,7 +78748,7 @@ var TerminalInstanceInfoSchema = object({
 	/**
 	* False while the node the instance is bound to is not in the cluster
 	* topology (forgotten, renamed, re-paired). The instance is kept; the
-	* operator re-points it with `updateInstance({ targetNodeId })`.
+	* operator re-points it on the Terminal page.
 	*/
 	nodeInCluster: boolean(),
 	profileId: string(),
@@ -78538,41 +78786,7 @@ var TerminalOutputBatchSchema = object({
 	snapshot: string().optional(),
 	events: array(TerminalOutputEventSchema).readonly()
 });
-method(_void(), array(TerminalProfileInfoSchema).readonly(), { auth: "admin" }), method(_void(), array(TerminalInstanceInfoSchema).readonly(), { auth: "admin" }), method(object({
-	targetNodeId: string().min(1),
-	profileId: string().min(1),
-	name: string().trim().min(1).max(160).optional(),
-	executable: string().max(1024).optional(),
-	args: array(string().max(2048)).max(64).optional(),
-	cwd: string().max(1024).optional(),
-	environment: array(string().max(4096)).max(64).optional(),
-	profileSettings: ProfileSettingsBagSchema.optional()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({
-	instanceId: string().min(1),
-	/** Re-point the instance to another node; the profile must exist there. */
-	targetNodeId: string().min(1).max(256).optional(),
-	name: string().trim().min(1).max(160).optional(),
-	executable: string().max(1024).optional(),
-	args: array(string().max(2048)).max(64).optional(),
-	cwd: string().max(1024).optional(),
-	environment: array(string().max(4096)).max(64).optional(),
-	profileSettings: ProfileSettingsBagSchema.optional()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ instanceId: string().min(1) }), _void(), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({
-	instanceId: string().min(1),
-	enabled: boolean()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(_void(), array(TerminalLegacyCameraSchema).readonly(), { auth: "admin" }), method(object({
+method(_void(), array(TerminalProfileInfoSchema).readonly(), { auth: "admin" }), method(_void(), array(TerminalLegacyCameraSchema).readonly(), { auth: "admin" }), method(object({
 	stableId: string().min(1),
 	name: string().trim().min(1).max(160).optional()
 }), TerminalInstanceInfoSchema, {
@@ -83392,6 +83606,20 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"addonSettings.getScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
+	"addonSettings.readScopedValues": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"addonSettings.unsetStoredSettingsKeys": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -83413,6 +83641,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"addonSettings.updateScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"addonWidgets.listWidgets": {
 		capName: "addon-widgets",
 		capScope: "system",
@@ -92303,27 +92538,6 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
-	"terminalSession.createInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
-	"terminalSession.deleteInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "delete",
-		role: "admin"
-	},
-	"terminalSession.listInstances": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "view",
-		role: "admin"
-	},
 	"terminalSession.listLegacyCameras": {
 		capName: "terminal-session",
 		capScope: "system",
@@ -92366,20 +92580,6 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
-	"terminalSession.setInstanceEnabled": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
-	"terminalSession.updateInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
 	"terminalSession.writeInput": {
 		capName: "terminal-session",
 		capScope: "system",
@@ -144132,6 +144332,7 @@ var EchoSessionRegistry = class {
 	#resolve = null;
 	#dnd = /* @__PURE__ */ new Map();
 	#volumes = /* @__PURE__ */ new Map();
+	#groupPlayers = /* @__PURE__ */ new Map();
 	setResolver(fn) {
 		this.#resolve = fn;
 	}
@@ -144170,10 +144371,35 @@ var EchoSessionRegistry = class {
 		});
 		return pending;
 	}
+	/**
+	* The player state of a speaker group, shared by its members within one poll cycle.
+	* A failed read is not kept for the next member.
+	*/
+	groupPlayer(brokerId, group, now, deviceId) {
+		const key = `${brokerId}\u0000${group.id}`;
+		const shared = this.#groupPlayers.get(key);
+		if (shared !== void 0 && now - shared.at < 25e3) return shared.pending;
+		const session = this.get(brokerId);
+		if (session === null) return Promise.reject(/* @__PURE__ */ new Error("no Echo session for this account"));
+		const pending = session.playerState(group.id, group.deviceType, deviceId);
+		this.#groupPlayers.set(key, {
+			at: now,
+			pending
+		});
+		pending.catch(() => {
+			if (this.#groupPlayers.get(key)?.pending === pending) this.#groupPlayers.delete(key);
+		});
+		return pending;
+	}
 	/** Forget the shared volume list: a list fetched before a set must not answer a poll after it. */
 	invalidateVolumes(brokerId) {
 		this.#volumes.delete(brokerId);
 	}
+	/** Forget the shared group players: a transport command or a push makes a cached group answer stale. */
+	invalidateGroupPlayers(brokerId) {
+		const prefix = `${brokerId}\u0000`;
+		for (const key of [...this.#groupPlayers.keys()]) if (key.startsWith(prefix)) this.#groupPlayers.delete(key);
+	}
 	/** Forget the shared Do Not Disturb list, for the same reason. */
 	invalidateDnd(brokerId) {
 		this.#dnd.delete(brokerId);
@@ -144189,6 +144415,7 @@ var EchoSessionRegistry = class {
 	}
 	event(brokerId, serial) {
 		this.invalidateVolumes(brokerId);
+		this.invalidateGroupPlayers(brokerId);
 		this.invalidateDnd(brokerId);
 		for (const listener of [...this.#pushListeners.get(`${brokerId}\u0000${serial}`) ?? []]) listener();
 	}
@@ -144207,6 +144434,7 @@ var EchoSessionRegistry = class {
 		this.#resolve = null;
 		this.#dnd.clear();
 		this.#volumes.clear();
+		this.#groupPlayers.clear();
 	}
 };
 function subscribe(map, key, listener) {
@@ -144249,6 +144477,11 @@ function mapEchoPlaybackState(value) {
 		default: return "idle";
 	}
 }
+/** Whether a player answer carries any playback: an active state, a text or artwork. */
+function hasPlayback(info) {
+	if (mapEchoPlaybackState(info.state) !== "idle") return true;
+	return nonEmpty(info.infoText?.title) !== null || nonEmpty(info.mainArt?.url) !== null;
+}
 function percent(value) {
 	if (typeof value !== "number" || !Number.isFinite(value)) return null;
 	return Math.round(Math.max(0, Math.min(100, value)));
@@ -144338,7 +144571,9 @@ var EchoDeviceSchema = object({
 	dnd: boolean(),
 	deviceType: string(),
 	/** The room the account files the device under, when Amazon names one. */
-	room: string().optional()
+	room: string().optional(),
+	/** Serials of the speaker groups this device belongs to (Amazon's `parentClusters`); absent when none. */
+	parentClusters: array(string()).optional()
 });
 var LoginStatusSchema = _enum(["ok", "failed"]);
 var SessionStatusSchema = object({
@@ -144567,6 +144802,8 @@ var AlexaEchoDevice = class extends BaseDevice {
 	unsubscribers = [];
 	polling = false;
 	failureLogged = false;
+	/** The name of the speaker group whose playback this Echo shows; null when it plays on its own. */
+	viaGroup = null;
 	volumeFailureLogged = false;
 	health = "ok";
 	/** When this device last wrote its volume / Do Not Disturb optimistically; a read that began earlier must not overwrite it. */
@@ -144694,9 +144931,11 @@ var AlexaEchoDevice = class extends BaseDevice {
 		}
 		const deviceType = this.amazonDeviceType !== "" ? this.amazonDeviceType : listed?.deviceType ?? "";
 		try {
-			const fromPlayer = mapPlayerInfoToStatus(await session.playerState(this.serial, deviceType, this.id), {
+			const own = await session.playerState(this.serial, deviceType, this.id);
+			const now = Date.now();
+			const fromPlayer = mapPlayerInfoToStatus(await this.withGroupPlayback(own, listed, session), {
 				online: true,
-				now: Date.now()
+				now
 			});
 			const read = await this.completeVolume(fromPlayer);
 			const kept = this.keepNewerVolume(read, readStartedAt);
@@ -144711,6 +144950,49 @@ var AlexaEchoDevice = class extends BaseDevice {
 		await this.readDoNotDisturb(readStartedAt);
 	}
 	/**
+	* A member of a playing speaker group is answered empty by its own player read while
+	* the group plays. When the member's answer carries no playback, serve the first
+	* parent group that is playing or paused (its track and artwork; the volume stays the
+	* member's own). A failed group read leaves the member's own answer.
+	*/
+	async withGroupPlayback(own, listed, session) {
+		const parents = listed?.parentClusters ?? [];
+		if (hasPlayback(own) || parents.length === 0) {
+			this.noteViaGroup(null);
+			return own;
+		}
+		for (const parentId of parents) {
+			const group = session.devices.find((device) => device.id === parentId);
+			if (group === void 0 || !group.online) continue;
+			try {
+				const groupInfo = await alexaEchoSessions.groupPlayer(this.brokerId, group, Date.now(), this.id);
+				if (groupInfo.state === "PLAYING" || groupInfo.state === "PAUSED" || groupInfo.state === "BUFFERING") {
+					this.noteViaGroup(group.name);
+					return {
+						...groupInfo,
+						volume: own.volume
+					};
+				}
+			} catch (err) {
+				this.ctx.logger.debug("alexa echo: the group player could not be read", {
+					tags: { deviceId: this.id },
+					meta: {
+						group: group.name,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.noteViaGroup(null);
+		return own;
+	}
+	/** Log each transition into and out of "playing via a group" once. */
+	noteViaGroup(name) {
+		if (name === this.viaGroup) return;
+		this.viaGroup = name;
+		this.ctx.logger.info(name === null ? "alexa echo: no longer playing via a group" : `alexa echo: playing via group ${name}`, { tags: { deviceId: this.id } });
+	}
+	/**
 	* An idle Echo's player read carries no volume. Ask the account's volume list
 	* (shared by every Echo of the account in this cycle); a failed read leaves null.
 	*/
@@ -144782,6 +145064,7 @@ var AlexaEchoDevice = class extends BaseDevice {
 	}
 	async command(command) {
 		await this.session().npCommand(this.serial, command, this.id);
+		alexaEchoSessions.invalidateGroupPlayers(this.brokerId);
 		this.rereadSoon();
 	}
 	/**

package/dist/addon.mjs

@@ -6059,7 +6059,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../types/dist/sleep-AEnTN3b4.mjs
+//#region ../types/dist/sleep-CQP-REJp.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -6423,6 +6423,59 @@ Object.fromEntries([
 function isValuelessField(field) {
 	return field.type === "separator" || field.type === "info" || field.type === "qr-code" || field.type === "button" || field.type === "object-array" || field.type === "widget" || field.type === "addon-action-button" || field.type === "device-action-button" || field.type === "account-sign-in" || field.type === "secret-presence";
 }
+/**
+* Base collector: flatten a hydrated `ConfigUISchemaWithValues` into
+* `key → { value, default }`, recursing through `group` and `sub-tabs`
+* layout fields. Keeping `value` and `default` SEPARATE (rather than
+* pre-resolving) lets callers both read the effective value AND detect
+* overrides (`value` differs from `default`). Structural over `unknown`;
+* malformed input yields an empty map, never throws.
+*/
+function collectHydratedFieldEntries(schema) {
+	const out = /* @__PURE__ */ new Map();
+	if (typeof schema !== "object" || schema === null) return out;
+	const sections = schema.sections;
+	if (!Array.isArray(sections)) return out;
+	for (const section of sections) if (typeof section === "object" && section !== null) collectFieldEntriesInto(section.fields, out);
+	return out;
+}
+/** Recursive field walker for {@link collectHydratedFieldEntries}. */
+function collectFieldEntriesInto(fields, into) {
+	if (!Array.isArray(fields)) return;
+	for (const field of fields) {
+		if (typeof field !== "object" || field === null) continue;
+		const type = field.type;
+		if (type === "group") {
+			collectFieldEntriesInto(field.fields, into);
+			continue;
+		}
+		if (type === "sub-tabs") {
+			const tabs = field.tabs;
+			if (Array.isArray(tabs)) {
+				for (const tab of tabs) if (typeof tab === "object" && tab !== null) collectFieldEntriesInto(tab.fields, into);
+			}
+			continue;
+		}
+		const key = field.key;
+		if (typeof key !== "string" || key.length === 0) continue;
+		if (!("value" in field)) continue;
+		into.set(key, {
+			value: field.value,
+			default: field.default
+		});
+	}
+}
+/**
+* Flatten a hydrated settings payload into `key → EFFECTIVE value`
+* (`value ?? default`). The read-side inverse of `hydrateSchema` for the
+* common "just give me the resolved values" case. Built on
+* {@link collectHydratedFieldEntries}.
+*/
+function collectHydratedFieldValues(schema) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [key, entry] of collectHydratedFieldEntries(schema)) out.set(key, entry.value ?? entry.default);
+	return out;
+}
 function hydrateSchema(schema, values, options = {}) {
 	return {
 		...schema.tabs ? { tabs: [...schema.tabs] } : {},
@@ -7662,6 +7715,21 @@ var SCOPED_SETTINGS_SCOPES = [
 	"device-defaults",
 	"node"
 ];
+/** The one refusal of a key a scope did not declare. */
+function assertDeclaredKeys(keys, declared) {
+	const undeclared = keys.filter((key) => !declared.has(key));
+	if (undeclared.length > 0) throw new Error(`scoped settings: [${undeclared.join(", ")}] not declared for this scope (declared: [${[...declared].join(", ")}])`);
+}
+/** Build the handle over an addon's scoped read, write and unset. */
+function createScopedSettings(deps) {
+	return {
+		async get() {
+			return deps.schema.parse(await deps.read());
+		},
+		patch: (patch) => deps.write(Object.fromEntries(Object.entries(patch))),
+		unset: (keys) => deps.unset(keys)
+	};
+}
 /** A write to a secret path could not be stored in the keychain, so it was refused. */
 var KeychainWriteRefusedError = class extends Error {
 	fieldPath;
@@ -8237,7 +8305,16 @@ function createHandle(raw, opts) {
 				return blob;
 			}
 		},
-		writeAddonStore: writeAddon
+		writeAddonStore: writeAddon,
+		removeClearedKeys: (keys) => serialize("addon", async () => {
+			const stored = await readStoredAddonBlob(raw);
+			index.seen("addon", stored);
+			const removable = keys.filter((key) => collectSecretMarkerRefs(stored[key]).length === 0);
+			if (removable.length === 0) return;
+			const patch = Object.fromEntries(removable.map((key) => [key, void 0]));
+			await raw.writeAddonStore(patch);
+			index.wrote("addon", patch);
+		})
 	};
 }
 /** The context the addon sees, plus the private raw view and write outcome. */
@@ -8782,6 +8859,151 @@ var BaseAddon = class {
 		}
 	}
 	/**
+	* Hook: values layered over the stored ones when the FORM of one scope is served
+	* ({@link getScopedSettings}) — a preview that derives dependent options without writing.
+	* Never applied to {@link ScopedSettings.get} or to a write. `null` ⇒ no overlay.
+	*/
+	async scopedSettingsOverlay(_scope, _cap, _nodeId) {
+		return null;
+	}
+	/**
+	* Hook: a write of one scope changed stored values (not called when the store reports no change,
+	* e.g. the write-back of a stored secret). `keys` are the bare field keys of the write, node keys included.
+	*/
+	async onScopedSettingsChanged(_scope, _cap, _keys) {}
+	/** Typed handle over the CLUSTER settings `cap` declares (`clusterSettingsSchema`). */
+	clusterSettings(cap, schema) {
+		return this.scopedHandle("cluster", cap, schema);
+	}
+	/** Typed handle over the fleet defaults of the per-device settings `cap` declares. */
+	deviceDefaults(cap, schema) {
+		return this.scopedHandle("device-defaults", cap, schema);
+	}
+	/**
+	* Typed handle over the settings `cap` owns PER NODE. `nodeId` omitted ⇒ the local node. A node
+	* with no row yields the schema defaults — never a bare-key fallback.
+	*/
+	nodeSettings(cap, schema, nodeId) {
+		return this.scopedHandle("node", cap, schema, nodeId);
+	}
+	/**
+	* {@link state} for a value that is kept per node: stored under `<key>@<nodeId>`, and the
+	* settings store carries `nodeId` in the row data (D986 §1), so a forgotten node's rows go in one
+	* central delete. `nodeId` omitted ⇒ the local node.
+	*/
+	nodeState(key, schema, fallback, nodeId) {
+		this._declaredStateKeys.add(key);
+		return createDurableState({
+			key: nodeScopedKey(key, nodeId ?? this._ctx?.kernel?.localNodeId ?? ""),
+			schema,
+			fallback,
+			read: async () => this.resolveStoredSecrets(await this.readAddonStoreWithRetry()),
+			write: async (patch) => {
+				await this._ctx?.settings?.writeAddonStore(patch);
+			},
+			onParseError: (k, e) => this._ctx?.logger?.warn?.(`durable-state: stored "${k}" failed validation — using fallback`, { meta: {
+				addonId: this._ctx?.id,
+				key: k,
+				error: String(e)
+			} })
+		});
+	}
+	/** The loaded schema `cap` declares for `scope`, or `null`. */
+	async declaredScopedSchema(scope, cap) {
+		await this.loadScopedSchemas(cap);
+		return this.loadedScopedSchemas(cap).find((entry) => entry.scope === scope)?.schema ?? null;
+	}
+	async requireScopedSchema(scope, cap) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) throw new Error(`${this.constructor.name}: cap "${cap}" declares no ${scope} settings`);
+		return schema;
+	}
+	scopedKeys(schema) {
+		return new Set(schema.sections.flatMap((section) => collectValueFieldKeys(section.fields)));
+	}
+	/** `store` narrowed to the keys `schema` declares. */
+	narrowToScope(store, schema) {
+		const keys = this.scopedKeys(schema);
+		return Object.fromEntries(Object.entries(store).filter(([key]) => keys.has(key)));
+	}
+	scopedHandle(scope, cap, schema, nodeId) {
+		return createScopedSettings({
+			schema,
+			read: async () => {
+				const declared = await this.requireScopedSchema(scope, cap);
+				const stored = this.narrowToScope(await this.resolveGlobalStore(nodeId, cap), declared);
+				const effective = collectHydratedFieldValues(hydrateSchema(declared, stored));
+				return {
+					...Object.fromEntries([...effective].filter(([, value]) => value !== void 0)),
+					...stored
+				};
+			},
+			write: (patch) => this.writeScoped(scope, cap, patch, nodeId),
+			unset: (keys) => this.unsetScoped(scope, cap, keys, nodeId)
+		});
+	}
+	/** The one write path of the scoped API: declared keys only, then the global patch. */
+	async writeScoped(scope, cap, patch, nodeId) {
+		assertDeclaredKeys(Object.keys(patch), this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		if (await this.applyGlobalPatch(patch, scope === "node" ? nodeId : void 0, cap)) await this.onScopedSettingsChanged(scope, cap, Object.keys(patch));
+	}
+	/**
+	* Remove declared keys of one scope. A secret goes through {@link clearSecrets} — its keychain
+	* value is released exactly as there — and the emptied row is then removed; every other key is
+	* removed by an `undefined` patch (which a secret transform would read as "keep").
+	*/
+	async unsetScoped(scope, cap, keys, nodeId) {
+		assertDeclaredKeys(keys, this.scopedKeys(await this.requireScopedSchema(scope, cap)));
+		const target = scope === "node" ? nodeId : void 0;
+		const tree = this.addonSecretTree();
+		const secretKeys = keys.filter((key) => tree.has(key));
+		const plainKeys = keys.filter((key) => !tree.has(key));
+		let changed = false;
+		if (plainKeys.length > 0) {
+			const patch = Object.fromEntries(plainKeys.map((key) => [key, void 0]));
+			changed = await this.applyGlobalPatch(patch, target, cap) || changed;
+		}
+		if (secretKeys.length > 0) {
+			await this.clearSecretKeys(secretKeys, target, cap);
+			const node = normalizeNodeId(target ?? this._ctx?.kernel?.localNodeId);
+			const rows = secretKeys.map((key) => scope === "node" ? nodeScopedKey(key, node) : key);
+			if (this._secretSettings !== null) await this._secretSettings.removeClearedKeys(rows);
+			else await this._ctx?.settings?.writeAddonStore(Object.fromEntries(rows.map((row) => [row, void 0])));
+			changed = true;
+		}
+		if (changed) await this.onScopedSettingsChanged(scope, cap, [...keys]);
+	}
+	/**
+	* The hydrated form of one scope of one capability's settings (any
+	* {@link scopedSettingsOverlay} applied), or `null` when the capability declares nothing there.
+	*/
+	async getScopedSettings(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const stored = this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema);
+		const overlay = await this.scopedSettingsOverlay(scope, cap, nodeId);
+		return hydrateSchema(schema, overlay ? await this.overlayKeepingMarkers(stored, overlay) : stored, { inlineSecretsAsViews: true });
+	}
+	/** The OPERATOR's write of declared keys of one scope (D787 secret semantics). */
+	async updateScopedSettings(scope, cap, patch, nodeId) {
+		this._operatorWriteDepth++;
+		try {
+			await this.writeScoped(scope, cap, patch, nodeId);
+		} finally {
+			this._operatorWriteDepth--;
+		}
+	}
+	/**
+	* The effective values (`stored ?? default`) of one scope, a secret as its `set` view — never
+	* its value. `null` when the capability declares nothing for the scope.
+	*/
+	async readScopedValues(scope, cap, nodeId) {
+		const schema = await this.declaredScopedSchema(scope, cap);
+		if (schema === null) return null;
+		const form = hydrateSchema(schema, this.narrowToScope(await this.readRawProjectedStore(nodeId, cap), schema), { inlineSecretsAsViews: true });
+		return Object.fromEntries([...collectHydratedFieldValues(form)].filter(([, value]) => value !== void 0));
+	}
+	/**
 	* What the create wizard and the integration edit page render for one instance: the addon's
 	* per-instance schema when it declares one, else its global schema (what they always showed).
 	*/
@@ -8933,6 +9155,9 @@ var BaseAddon = class {
 	* a keychain (an older kernel) it writes `''`, as such code always did.
 	*/
 	async clearSecrets(keys, nodeId) {
+		await this.clearSecretKeys(keys, nodeId);
+	}
+	async clearSecretKeys(keys, nodeId, cap) {
 		const tree = this.addonSecretTree();
 		const keychain = this._ctx?.secrets !== void 0;
 		const stored = keychain ? await this.readAddonStoreWithRetry() : {};
@@ -8945,25 +9170,27 @@ var BaseAddon = class {
 			const keychainStored = tree.has(key) || collectSecretMarkerRefs(stored[key]).length > 0;
 			patch[key] = keychain && keychainStored ? SECRET_CLEAR : "";
 		}
-		await this.applyGlobalPatch(patch, nodeId);
+		await this.applyGlobalPatch(patch, nodeId, cap);
 	}
-	async applyGlobalPatch(barePatch, nodeId) {
-		await this.loadScopedSchemas();
-		const keys = this.perNodeKeys();
+	/** Resolves `true` when the write changed stored values. */
+	async applyGlobalPatch(barePatch, nodeId, cap) {
+		await this.loadScopedSchemas(cap);
+		const keys = this.perNodeKeys(cap);
 		const localNode = normalizeNodeId(this._ctx?.kernel?.localNodeId);
 		const target = normalizeNodeId(nodeId ?? this._ctx?.kernel?.localNodeId);
 		const scoped = keys.size > 0 ? scopePatch(barePatch, keys, target) : barePatch;
 		const handle = this._secretSettings;
 		if (handle !== null) {
 			const { changed } = await handle.writeAddonStore(scoped);
-			if (!changed) return;
+			if (!changed) return false;
 		} else await this._ctx?.settings?.writeAddonStore(scoped);
-		if (target !== localNode) return;
+		if (target !== localNode) return true;
 		await this.resolveConfig();
 		await this.onConfigChanged();
 		this.emitLifecycle(EventCategory.AddonUpdated, { level: "global" });
 		const legacy = this.globalSettingsSchema();
 		this.maybeAutoRestart(Object.keys(barePatch), [...legacy === null ? [] : [legacy], ...this.loadedScopedSchemas().map((entry) => entry.schema)]);
+		return true;
 	}
 	/**
 	* The set of field keys the global settings schema declares `perNode: true`
@@ -45492,6 +45719,8 @@ var SettingsSchemaWithValuesSchema = object({
 });
 /** Patch object — keys are field names, values are the new field values. */
 var SettingsPatchSchema = record(string(), unknown());
+/** The scope of a scoped-settings call (D986): where the capability declared the values. */
+var ScopedSettingsScopeSchema = _enum(SCOPED_SETTINGS_SCOPES);
 /** Standard success response for update operations. */
 var SettingsUpdateResultSchema = object({ success: literal(true) });
 method(object({
@@ -45507,6 +45736,25 @@ method(object({
 	kind: "mutation",
 	auth: "admin"
 }), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), SettingsSchemaWithValuesSchema.nullable()), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional(),
+	patch: SettingsPatchSchema
+}), SettingsUpdateResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	addonId: string(),
+	cap: string(),
+	scope: ScopedSettingsScopeSchema,
+	nodeId: string().optional()
+}), record(string(), unknown()).nullable()), method(object({
 	addonId: string(),
 	nodeId: string().optional()
 }), SettingsSchemaWithValuesSchema.nullable()), method(object({
@@ -78498,7 +78746,7 @@ var TerminalInstanceInfoSchema = object({
 	/**
 	* False while the node the instance is bound to is not in the cluster
 	* topology (forgotten, renamed, re-paired). The instance is kept; the
-	* operator re-points it with `updateInstance({ targetNodeId })`.
+	* operator re-points it on the Terminal page.
 	*/
 	nodeInCluster: boolean(),
 	profileId: string(),
@@ -78536,41 +78784,7 @@ var TerminalOutputBatchSchema = object({
 	snapshot: string().optional(),
 	events: array(TerminalOutputEventSchema).readonly()
 });
-method(_void(), array(TerminalProfileInfoSchema).readonly(), { auth: "admin" }), method(_void(), array(TerminalInstanceInfoSchema).readonly(), { auth: "admin" }), method(object({
-	targetNodeId: string().min(1),
-	profileId: string().min(1),
-	name: string().trim().min(1).max(160).optional(),
-	executable: string().max(1024).optional(),
-	args: array(string().max(2048)).max(64).optional(),
-	cwd: string().max(1024).optional(),
-	environment: array(string().max(4096)).max(64).optional(),
-	profileSettings: ProfileSettingsBagSchema.optional()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({
-	instanceId: string().min(1),
-	/** Re-point the instance to another node; the profile must exist there. */
-	targetNodeId: string().min(1).max(256).optional(),
-	name: string().trim().min(1).max(160).optional(),
-	executable: string().max(1024).optional(),
-	args: array(string().max(2048)).max(64).optional(),
-	cwd: string().max(1024).optional(),
-	environment: array(string().max(4096)).max(64).optional(),
-	profileSettings: ProfileSettingsBagSchema.optional()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({ instanceId: string().min(1) }), _void(), {
-	kind: "mutation",
-	auth: "admin"
-}), method(object({
-	instanceId: string().min(1),
-	enabled: boolean()
-}), TerminalInstanceInfoSchema, {
-	kind: "mutation",
-	auth: "admin"
-}), method(_void(), array(TerminalLegacyCameraSchema).readonly(), { auth: "admin" }), method(object({
+method(_void(), array(TerminalProfileInfoSchema).readonly(), { auth: "admin" }), method(_void(), array(TerminalLegacyCameraSchema).readonly(), { auth: "admin" }), method(object({
 	stableId: string().min(1),
 	name: string().trim().min(1).max(160).optional()
 }), TerminalInstanceInfoSchema, {
@@ -83390,6 +83604,20 @@ Object.freeze({
 		access: "view",
 		role: "admin"
 	},
+	"addonSettings.getScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
+	"addonSettings.readScopedValues": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "view",
+		role: "admin"
+	},
 	"addonSettings.unsetStoredSettingsKeys": {
 		capName: "addon-settings",
 		capScope: "system",
@@ -83411,6 +83639,13 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
+	"addonSettings.updateScopedSettings": {
+		capName: "addon-settings",
+		capScope: "system",
+		addonId: null,
+		access: "create",
+		role: "admin"
+	},
 	"addonWidgets.listWidgets": {
 		capName: "addon-widgets",
 		capScope: "system",
@@ -92301,27 +92536,6 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
-	"terminalSession.createInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
-	"terminalSession.deleteInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "delete",
-		role: "admin"
-	},
-	"terminalSession.listInstances": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "view",
-		role: "admin"
-	},
 	"terminalSession.listLegacyCameras": {
 		capName: "terminal-session",
 		capScope: "system",
@@ -92364,20 +92578,6 @@ Object.freeze({
 		access: "create",
 		role: "admin"
 	},
-	"terminalSession.setInstanceEnabled": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
-	"terminalSession.updateInstance": {
-		capName: "terminal-session",
-		capScope: "system",
-		addonId: null,
-		access: "create",
-		role: "admin"
-	},
 	"terminalSession.writeInput": {
 		capName: "terminal-session",
 		capScope: "system",
@@ -144130,6 +144330,7 @@ var EchoSessionRegistry = class {
 	#resolve = null;
 	#dnd = /* @__PURE__ */ new Map();
 	#volumes = /* @__PURE__ */ new Map();
+	#groupPlayers = /* @__PURE__ */ new Map();
 	setResolver(fn) {
 		this.#resolve = fn;
 	}
@@ -144168,10 +144369,35 @@ var EchoSessionRegistry = class {
 		});
 		return pending;
 	}
+	/**
+	* The player state of a speaker group, shared by its members within one poll cycle.
+	* A failed read is not kept for the next member.
+	*/
+	groupPlayer(brokerId, group, now, deviceId) {
+		const key = `${brokerId}\u0000${group.id}`;
+		const shared = this.#groupPlayers.get(key);
+		if (shared !== void 0 && now - shared.at < 25e3) return shared.pending;
+		const session = this.get(brokerId);
+		if (session === null) return Promise.reject(/* @__PURE__ */ new Error("no Echo session for this account"));
+		const pending = session.playerState(group.id, group.deviceType, deviceId);
+		this.#groupPlayers.set(key, {
+			at: now,
+			pending
+		});
+		pending.catch(() => {
+			if (this.#groupPlayers.get(key)?.pending === pending) this.#groupPlayers.delete(key);
+		});
+		return pending;
+	}
 	/** Forget the shared volume list: a list fetched before a set must not answer a poll after it. */
 	invalidateVolumes(brokerId) {
 		this.#volumes.delete(brokerId);
 	}
+	/** Forget the shared group players: a transport command or a push makes a cached group answer stale. */
+	invalidateGroupPlayers(brokerId) {
+		const prefix = `${brokerId}\u0000`;
+		for (const key of [...this.#groupPlayers.keys()]) if (key.startsWith(prefix)) this.#groupPlayers.delete(key);
+	}
 	/** Forget the shared Do Not Disturb list, for the same reason. */
 	invalidateDnd(brokerId) {
 		this.#dnd.delete(brokerId);
@@ -144187,6 +144413,7 @@ var EchoSessionRegistry = class {
 	}
 	event(brokerId, serial) {
 		this.invalidateVolumes(brokerId);
+		this.invalidateGroupPlayers(brokerId);
 		this.invalidateDnd(brokerId);
 		for (const listener of [...this.#pushListeners.get(`${brokerId}\u0000${serial}`) ?? []]) listener();
 	}
@@ -144205,6 +144432,7 @@ var EchoSessionRegistry = class {
 		this.#resolve = null;
 		this.#dnd.clear();
 		this.#volumes.clear();
+		this.#groupPlayers.clear();
 	}
 };
 function subscribe(map, key, listener) {
@@ -144247,6 +144475,11 @@ function mapEchoPlaybackState(value) {
 		default: return "idle";
 	}
 }
+/** Whether a player answer carries any playback: an active state, a text or artwork. */
+function hasPlayback(info) {
+	if (mapEchoPlaybackState(info.state) !== "idle") return true;
+	return nonEmpty(info.infoText?.title) !== null || nonEmpty(info.mainArt?.url) !== null;
+}
 function percent(value) {
 	if (typeof value !== "number" || !Number.isFinite(value)) return null;
 	return Math.round(Math.max(0, Math.min(100, value)));
@@ -144336,7 +144569,9 @@ var EchoDeviceSchema = object({
 	dnd: boolean(),
 	deviceType: string(),
 	/** The room the account files the device under, when Amazon names one. */
-	room: string().optional()
+	room: string().optional(),
+	/** Serials of the speaker groups this device belongs to (Amazon's `parentClusters`); absent when none. */
+	parentClusters: array(string()).optional()
 });
 var LoginStatusSchema = _enum(["ok", "failed"]);
 var SessionStatusSchema = object({
@@ -144565,6 +144800,8 @@ var AlexaEchoDevice = class extends BaseDevice {
 	unsubscribers = [];
 	polling = false;
 	failureLogged = false;
+	/** The name of the speaker group whose playback this Echo shows; null when it plays on its own. */
+	viaGroup = null;
 	volumeFailureLogged = false;
 	health = "ok";
 	/** When this device last wrote its volume / Do Not Disturb optimistically; a read that began earlier must not overwrite it. */
@@ -144692,9 +144929,11 @@ var AlexaEchoDevice = class extends BaseDevice {
 		}
 		const deviceType = this.amazonDeviceType !== "" ? this.amazonDeviceType : listed?.deviceType ?? "";
 		try {
-			const fromPlayer = mapPlayerInfoToStatus(await session.playerState(this.serial, deviceType, this.id), {
+			const own = await session.playerState(this.serial, deviceType, this.id);
+			const now = Date.now();
+			const fromPlayer = mapPlayerInfoToStatus(await this.withGroupPlayback(own, listed, session), {
 				online: true,
-				now: Date.now()
+				now
 			});
 			const read = await this.completeVolume(fromPlayer);
 			const kept = this.keepNewerVolume(read, readStartedAt);
@@ -144709,6 +144948,49 @@ var AlexaEchoDevice = class extends BaseDevice {
 		await this.readDoNotDisturb(readStartedAt);
 	}
 	/**
+	* A member of a playing speaker group is answered empty by its own player read while
+	* the group plays. When the member's answer carries no playback, serve the first
+	* parent group that is playing or paused (its track and artwork; the volume stays the
+	* member's own). A failed group read leaves the member's own answer.
+	*/
+	async withGroupPlayback(own, listed, session) {
+		const parents = listed?.parentClusters ?? [];
+		if (hasPlayback(own) || parents.length === 0) {
+			this.noteViaGroup(null);
+			return own;
+		}
+		for (const parentId of parents) {
+			const group = session.devices.find((device) => device.id === parentId);
+			if (group === void 0 || !group.online) continue;
+			try {
+				const groupInfo = await alexaEchoSessions.groupPlayer(this.brokerId, group, Date.now(), this.id);
+				if (groupInfo.state === "PLAYING" || groupInfo.state === "PAUSED" || groupInfo.state === "BUFFERING") {
+					this.noteViaGroup(group.name);
+					return {
+						...groupInfo,
+						volume: own.volume
+					};
+				}
+			} catch (err) {
+				this.ctx.logger.debug("alexa echo: the group player could not be read", {
+					tags: { deviceId: this.id },
+					meta: {
+						group: group.name,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.noteViaGroup(null);
+		return own;
+	}
+	/** Log each transition into and out of "playing via a group" once. */
+	noteViaGroup(name) {
+		if (name === this.viaGroup) return;
+		this.viaGroup = name;
+		this.ctx.logger.info(name === null ? "alexa echo: no longer playing via a group" : `alexa echo: playing via group ${name}`, { tags: { deviceId: this.id } });
+	}
+	/**
 	* An idle Echo's player read carries no volume. Ask the account's volume list
 	* (shared by every Echo of the account in this cycle); a failed read leaves null.
 	*/
@@ -144780,6 +145062,7 @@ var AlexaEchoDevice = class extends BaseDevice {
 	}
 	async command(command) {
 		await this.session().npCommand(this.serial, command, this.id);
+		alexaEchoSessions.invalidateGroupPlayers(this.brokerId);
 		this.rereadSoon();
 	}
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-import-alexa",
-  "version": "0.2.195",
+  "version": "0.2.196",
   "description": "Alexa device-import provider for CamStack — imports the smart-home devices in a user's Alexa account via the unofficial alexa-remote2 cookie/token client (the inverse of the Alexa exporter)",
   "keywords": [
     "camstack",
@@ -72,7 +72,7 @@
       }
     ],
     "requires": {
-      "server": ">=1.2.790"
+      "server": ">=1.2.793"
     }
   },
   "files": [

package/python/alexa_gateway.py

@@ -110,6 +110,11 @@ def normalize_device(raw: dict) -> dict | None:
     }
     if room != "":
         result["room"] = room
+    parents = raw.get("parentClusters")
+    if isinstance(parents, list):
+        serials = [p for p in parents if isinstance(p, str) and p != ""]
+        if serials:
+            result["parentClusters"] = serials
     return result
 
 
@@ -246,7 +251,7 @@ class AlexaPyGateway:
         public = [
             {
                 key: device[key]
-                for key in ("id", "name", "family", "online", "kind", "dnd", "deviceType", "room")
+                for key in ("id", "name", "family", "online", "kind", "dnd", "deviceType", "room", "parentClusters")
                 if key in device
             }
             for device in devices