@camstack/system 1.1.22 → 1.1.24

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

@@ -1,5 +1,5 @@
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
-import { BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceRole, DeviceStatusSchema, DeviceType, EventCategory, STREAM_PROFILE_META, WELL_KNOWN_TAB_MAP, applyTransform, buildStreamParamsConfigSchema, deviceManagerCapability, deviceStateCapability, deviceStatusCapability, enumerateSchemaFields, errMsg, getByPath, isDeviceConfigCap, parseStreamParamsFormPatch, setByPath, sleep } from "@camstack/types";
+import { ALL_CAPABILITY_DEFINITIONS, BaseAddon, CAP_NAMES_WITH_STATUS, DeviceFeature, DeviceRole, DeviceStatusSchema, DeviceType, EventCategory, STREAM_PROFILE_META, WELL_KNOWN_TAB_MAP, applyTransform, buildStreamParamsConfigSchema, deviceManagerCapability, deviceStateCapability, deviceStatusCapability, enumerateItemArrayFields, enumerateSchemaFields, errMsg, evaluateLinkExpression, getByPath, isDeviceConfigCap, normalizeUnit, parseStreamParamsFormPatch, setByPath, sleep, toExpressionValue, validateExpressionSource } from "@camstack/types";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 /**
@@ -295,7 +295,8 @@ function toDeviceInfo(addonId, device, metadata = null, metaRow = null) {
 		...metaRow?.linkDeviceId !== void 0 ? { linkDeviceId: metaRow.linkDeviceId } : {},
 		...metaRow?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: metaRow.primaryChildEntityId } : {},
 		...metaRow?.childLayout !== void 0 ? { childLayout: metaRow.childLayout } : {},
-		...metaRow?.deviceLinks !== void 0 ? { deviceLinks: metaRow.deviceLinks } : {}
+		...metaRow?.deviceLinks !== void 0 ? { deviceLinks: metaRow.deviceLinks } : {},
+		...metaRow?.display !== void 0 ? { display: metaRow.display } : {}
 	};
 }
 function resolveDeviceById(registry, deviceId) {
@@ -504,6 +505,21 @@ async function getBindings(deps, input) {
 		});
 		seenCaps.add(entry.capName);
 	}
+	if (deps.devicesWithLinks?.has(input.deviceId)) {
+		const row = ((await deps.ctx.settings.readAddonStore()).deviceMeta ?? {})[String(input.deviceId)];
+		for (const link of row?.deviceLinks ?? []) {
+			const capName = link.target.cap;
+			if (seenCaps.has(capName)) continue;
+			entries.push({
+				capName,
+				kind: "linked",
+				providerAddonId: deps.ctx.id,
+				providerNodeId: deps.ctx.kernel.localNodeId ?? "hub",
+				nativeAddonId: ""
+			});
+			seenCaps.add(capName);
+		}
+	}
 	return {
 		deviceId: input.deviceId,
 		entries
@@ -1166,11 +1182,47 @@ async function setWrapperActive(deps, input) {
 	});
 }
 /**
+* Build the wireable-cap entry for one capability definition: the status
+* schema's scalar leaf fields plus — for an item-array cap
+* (`status.itemArray`) — the per-item fields tagged `item: true` (a link
+* targeting one must carry a `target.itemKey`) and the cap-level `itemArray`
+* descriptor so the UI can address items. Returns null when the cap exposes
+* nothing wireable (no status schema / no leaf fields).
+*/
+function wireableEntryForDef(capName, def) {
+	const status = def.status;
+	const schema = status?.schema;
+	if (!schema) return null;
+	const itemArray = status.itemArray;
+	const fields = [...enumerateSchemaFields(schema), ...itemArray ? enumerateItemArrayFields(itemArray) : []].map((f) => ({
+		path: f.path,
+		kind: f.kind,
+		...f.enumValues !== void 0 ? { enumValues: [...f.enumValues] } : {},
+		...f.item === true ? { item: true } : {}
+	}));
+	if (fields.length === 0) return null;
+	return {
+		cap: capName,
+		fields,
+		...itemArray ? { itemArray: {
+			path: itemArray.path,
+			keyField: itemArray.keyField
+		} } : {}
+	};
+}
+/**
 * Per-device wireable-field catalog — the domain status fields a device's
 * bound caps expose, for the operator's cross-device wiring UI. Binding-driven:
 * walks `getBindings(deviceId)`, skips wrapper caps (their status schemas are
 * internal book-keeping, not wireable domain data), and enumerates each cap's
-* status schema leaf fields. Behavior unchanged from the inline provider method.
+* status schema leaf fields (per-item fields included for item-array caps).
+*
+* `includeSynthesizable: true` (TARGET pickers only) additionally unions in
+* UNBOUND device-scoped caps that declare `status.empty` (the synthesize-target
+* marker) and whose `deviceTypes` admit this device's persisted type — so the
+* FIRST link to a synthesize-only cap (consumables on an HA vacuum) can be
+* authored before any binding exists. Default (absent/false) behavior is
+* byte-identical to the binding-driven catalog.
 */
 async function getWireableFields(deps, input) {
 	const { deviceId } = input;
@@ -1184,20 +1236,20 @@ async function getWireableFields(deps, input) {
 		seen.add(entry.capName);
 		const def = reg.getDefinition(entry.capName);
 		if (!def || def.kind === "wrapper") continue;
-		const schema = def.status?.schema;
-		if (!schema) continue;
-		const fields = enumerateSchemaFields(schema).map((f) => f.enumValues !== void 0 ? {
-			path: f.path,
-			kind: f.kind,
-			enumValues: [...f.enumValues]
-		} : {
-			path: f.path,
-			kind: f.kind
-		});
-		if (fields.length > 0) caps.push({
-			cap: entry.capName,
-			fields
-		});
+		const wireable = wireableEntryForDef(entry.capName, def);
+		if (wireable) caps.push(wireable);
+	}
+	if (input.includeSynthesizable === true) {
+		const deviceType = ((await deps.ctx.settings.readAddonStore()).deviceMeta ?? {})[String(deviceId)]?.type;
+		if (deviceType !== void 0) for (const def of ALL_CAPABILITY_DEFINITIONS) {
+			if (seen.has(def.name)) continue;
+			if (def.scope !== "device" || def.kind === "wrapper") continue;
+			if (def.status?.empty === void 0) continue;
+			if (def.deviceTypes && !def.deviceTypes.some((t) => t === deviceType)) continue;
+			seen.add(def.name);
+			const wireable = wireableEntryForDef(def.name, def);
+			if (wireable) caps.push(wireable);
+		}
 	}
 	return { caps };
 }
@@ -1311,6 +1363,120 @@ var DeviceEventPropagator = class {
 	}
 };
 //#endregion
+//#region src/builtins/device-manager/device-link-cycle.ts
+function nodeKey(deviceId, cap) {
+	return `${deviceId}:${cap}`;
+}
+/** The target's container stableId — its parent's (falling back to its own for
+*  a top-level target). Sibling FIELD sources resolve relative to this, the same
+*  rule `rebuildLinkDependents` / `resolveLinkedStatus` apply. */
+function containerStableId(targetRow, rowById) {
+	return targetRow.parentDeviceId !== null ? rowById.get(targetRow.parentDeviceId)?.stableId ?? targetRow.stableId : targetRow.stableId;
+}
+/** Resolve ONE field/global/literal binding to its `(deviceId, cap)` node, or
+*  null when it is a literal or resolves to no known device. */
+function resolveBindingNode(binding, targetRow, rowById, idByStableId) {
+	if (binding.kind === "literal") return null;
+	const wantedStableId = binding.kind === "global" ? binding.sourceStableId : `${containerStableId(targetRow, rowById)}-${binding.sourceKey}`;
+	const srcId = idByStableId.get(wantedStableId);
+	if (srcId === void 0) return null;
+	return nodeKey(srcId, binding.cap);
+}
+/**
+* Resolve a link source to the set of `(deviceId, cap)` nodes it depends on.
+* A literal source depends on nothing; a field/global source depends on exactly
+* one node; an EXPRESSION source depends on one node per resolvable non-literal
+* binding. Unresolvable (dangling) bindings contribute no edge — they cannot
+* loop while dangling; a cycle that only becomes resolvable later is bounded by
+* the resolve-time re-entrancy guard.
+*/
+function resolveSourceNodes(link, targetRow, rowById, idByStableId) {
+	const src = link.source;
+	if (src.kind === "expression") {
+		const nodes = [];
+		for (const binding of Object.values(src.bindings)) {
+			const node = resolveBindingNode(binding, targetRow, rowById, idByStableId);
+			if (node !== null) nodes.push(node);
+		}
+		return nodes;
+	}
+	const node = resolveBindingNode(src, targetRow, rowById, idByStableId);
+	return node !== null ? [node] : [];
+}
+/**
+* Detect whether replacing `editedDeviceId`'s links with `editedLinks` closes
+* a dependency cycle. Returns the cycle as an ordered list of node keys
+* (first node repeated at the end) or null when the set is safe.
+*/
+function findDeviceLinkCycle(allMeta, editedDeviceId, editedLinks) {
+	const rows = Object.values(allMeta);
+	const rowById = /* @__PURE__ */ new Map();
+	const idByStableId = /* @__PURE__ */ new Map();
+	for (const r of rows) {
+		rowById.set(r.id, r);
+		if (!idByStableId.has(r.stableId)) idByStableId.set(r.stableId, r.id);
+	}
+	const dependsOn = /* @__PURE__ */ new Map();
+	const addEdges = (row, links) => {
+		for (const link of links) {
+			const srcNodes = resolveSourceNodes(link, row, rowById, idByStableId);
+			if (srcNodes.length === 0) continue;
+			const tNode = nodeKey(row.id, link.target.cap);
+			const list = dependsOn.get(tNode) ?? [];
+			for (const srcNode of srcNodes) list.push(srcNode);
+			dependsOn.set(tNode, list);
+		}
+	};
+	for (const r of rows) {
+		const links = r.id === editedDeviceId ? editedLinks : r.deviceLinks ?? [];
+		if (links.length > 0) addEdges(r, links);
+	}
+	const roots = [...new Set(editedLinks.map((l) => nodeKey(editedDeviceId, l.target.cap)))];
+	for (const root of roots) {
+		const cycle = dfsFindCycle(root, dependsOn);
+		if (cycle) return cycle;
+	}
+	return null;
+}
+/** Iterative DFS from `root` over `dependsOn`; returns the first back-edge
+*  cycle path (closed — first node repeated last) or null. */
+function dfsFindCycle(root, dependsOn) {
+	const onPath = /* @__PURE__ */ new Set();
+	const done = /* @__PURE__ */ new Set();
+	const path = [];
+	const stack = [{
+		node: root,
+		nextChild: 0
+	}];
+	onPath.add(root);
+	path.push(root);
+	while (stack.length > 0) {
+		const frame = stack[stack.length - 1];
+		const children = dependsOn.get(frame.node) ?? [];
+		if (frame.nextChild < children.length) {
+			const child = children[frame.nextChild];
+			frame.nextChild += 1;
+			if (onPath.has(child)) {
+				const start = path.indexOf(child);
+				return [...path.slice(start), child];
+			}
+			if (done.has(child)) continue;
+			stack.push({
+				node: child,
+				nextChild: 0
+			});
+			onPath.add(child);
+			path.push(child);
+			continue;
+		}
+		stack.pop();
+		onPath.delete(frame.node);
+		path.pop();
+		done.add(frame.node);
+	}
+	return null;
+}
+//#endregion
 //#region src/builtins/device-manager/device-meta-actions.ts
 /**
 * Device meta-mutation + persistence actions for the device-manager addon —
@@ -1324,7 +1490,7 @@ var DeviceEventPropagator = class {
 * removeDevice), config persistence (persistConfig, loadConfig), the meta
 * surface load (loadMeta, loadRuntimeState), every meta setter (setName,
 * setLocation, setType, setIntegrationId, setLinkDeviceId,
-* setPrimaryChildEntityId, setChildLayout, setDeviceLinks, setRole,
+* setPrimaryChildEntityId, setChildLayout, setDeviceLinks, setRole, setDisplay,
 * applyInitialMeta, setMetadata, setDisabled), and the location registry
 * (listLocations, addLocation, removeLocation).
 *
@@ -1433,6 +1599,7 @@ async function registerDevice(pctx, input) {
 				...existingMeta?.childLayout !== void 0 ? { childLayout: existingMeta.childLayout } : {},
 				...existingMeta?.deviceLinks !== void 0 ? { deviceLinks: existingMeta.deviceLinks } : {},
 				...existingMeta?.role !== void 0 ? { role: existingMeta.role } : {},
+				...existingMeta?.display !== void 0 ? { display: existingMeta.display } : {},
 				parentDeviceId,
 				id,
 				features: featuresArr,
@@ -1872,6 +2039,13 @@ async function setChildLayout(pctx, input) {
 */
 async function setDeviceLinks(pctx, input) {
 	const { deviceId, deviceLinks } = input;
+	const cycle = findDeviceLinkCycle(await pctx.metaStore.readMeta(), deviceId, deviceLinks);
+	if (cycle) throw new Error(`[device-manager] setDeviceLinks: cross-device link cycle: ${cycle.join(" → ")}`);
+	for (const link of deviceLinks) {
+		if (link.source.kind !== "expression") continue;
+		const err = validateExpressionSource(link.source);
+		if (err) throw new Error(`[device-manager] setDeviceLinks: invalid expression on link '${link.id}': ${err}`);
+	}
 	await pctx.metaStore.withMetaWriteLock(async () => {
 		const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
 		if (!persisted) throw new Error(`[device-manager] setDeviceLinks: unknown device id=${deviceId}`);
@@ -1942,6 +2116,84 @@ async function setRole(pctx, input) {
 	});
 }
 /**
+* Normalize an operator-authored display override at write time so the render
+* path's `UNIT_TABLE` lookups always hit canonical spellings — maps `unit` and
+* every `perCap[*].unit` through `normalizeUnit`. Pure: rebuilds new objects,
+* never mutates the input. A unit `normalizeUnit` cannot canonicalize is left
+* as-is (the render path refuses conversion for unknown spellings).
+*/
+function normalizeDisplayOverride(display) {
+	return {
+		...display,
+		...display.unit !== void 0 ? { unit: normalizeUnit(display.unit) ?? display.unit } : {},
+		...display.perCap !== void 0 ? { perCap: Object.fromEntries(Object.entries(display.perCap).map(([cap, refine]) => [cap, refine.unit !== void 0 ? {
+			...refine,
+			unit: normalizeUnit(refine.unit) ?? refine.unit
+		} : refine])) } : {}
+	};
+}
+/**
+* Set (or clear) the per-device display override on a device's meta row.
+* Mirrors `setChildLayout` persistence; `null` REMOVES the `display` key
+* entirely (immutable rest-destructure — matches the "absent ⇒ no override"
+* projection contract, never persists `display: undefined`). Override units are
+* normalized at write so the render path always looks up canonical spellings.
+*/
+async function setDisplay(pctx, input) {
+	const { deviceId, display } = input;
+	const normalized = display === null ? null : normalizeDisplayOverride(display);
+	await pctx.metaStore.withMetaWriteLock(async () => {
+		const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
+		if (!persisted) throw new Error(`[device-manager] setDisplay: unknown device id=${deviceId}`);
+		const { meta: m } = persisted;
+		const key = String(deviceId);
+		const allMeta = await pctx.metaStore.readMeta();
+		const nextRow = normalized === null ? (({ display: _drop, ...rest }) => rest)(m) : {
+			...m,
+			display: normalized
+		};
+		await pctx.settings.writeAddonStore({ deviceMeta: {
+			...allMeta,
+			[key]: nextRow
+		} });
+	});
+	pctx.host.ctx.eventBus.emit({
+		id: randomUUID(),
+		timestamp: /* @__PURE__ */ new Date(),
+		source: {
+			type: "device",
+			id: deviceId
+		},
+		category: EventCategory.DeviceMetaChanged,
+		data: {
+			deviceId,
+			field: "display",
+			value: normalized
+		}
+	});
+}
+/**
+* Read the operator-authored per-role display defaults. Empty record when none
+* set. Not per-device — a plain top-level-key read.
+*/
+async function getRoleDisplayDefaults(pctx, _input) {
+	return { defaults: (await pctx.metaStore.readStore()).roleDisplayDefaults ?? {} };
+}
+/**
+* Replace the per-role display defaults whole-record (full replace). Override
+* units are normalized (`normalizeUnit`) at write so the render path always
+* looks up canonical spellings. Single-writer top-level key — no lock, no RMW,
+* no interaction with the `deviceMeta` write lock. Not per-device, so no event
+* is emitted; the UI invalidates its own query on mutate.
+*/
+async function setRoleDisplayDefaults(pctx, input) {
+	const normalized = Object.fromEntries(Object.entries(input.defaults).map(([role, def]) => [role, def.unit !== void 0 ? {
+		...def,
+		unit: normalizeUnit(def.unit) ?? def.unit
+	} : def]));
+	await pctx.settings.writeAddonStore({ roleDisplayDefaults: normalized });
+}
+/**
 * Batched meta pre-seed. Applies every provided field to the
 * device's meta row in ONE read-modify-write under a single
 * `withMetaWriteLock` acquisition (one `deviceMeta` blob write),
@@ -2186,21 +2438,33 @@ async function removeLocation(pctx, input) {
 function buildLinkIndexes(entries) {
 	const targets = /* @__PURE__ */ new Map();
 	const dependents = /* @__PURE__ */ new Map();
-	for (const { targetDeviceId, link, sourceDeviceId } of entries) {
+	for (const { targetDeviceId, link, sourceDeviceId, bindingSourceIds } of entries) {
 		const tKey = `${targetDeviceId}:${link.target.cap}`;
 		const tList = targets.get(tKey) ?? [];
 		tList.push({
 			link,
-			sourceDeviceId
+			sourceDeviceId,
+			...bindingSourceIds !== void 0 ? { bindingSourceIds } : {}
 		});
 		targets.set(tKey, tList);
-		const sKey = `${sourceDeviceId}:${link.source.cap}`;
-		const sList = dependents.get(sKey) ?? [];
-		sList.push({
-			targetDeviceId,
-			targetCap: link.target.cap
-		});
-		dependents.set(sKey, sList);
+		const addDependent = (sourceId, sourceCap) => {
+			const sKey = `${sourceId}:${sourceCap}`;
+			const sList = dependents.get(sKey) ?? [];
+			sList.push({
+				targetDeviceId,
+				targetCap: link.target.cap
+			});
+			dependents.set(sKey, sList);
+		};
+		if (link.source.kind === "expression") {
+			if (bindingSourceIds !== void 0) for (const [name, bindingDeviceId] of Object.entries(bindingSourceIds)) {
+				const binding = link.source.bindings[name];
+				if (binding === void 0 || binding.kind === "literal") continue;
+				addDependent(bindingDeviceId, binding.cap);
+			}
+			continue;
+		}
+		if (link.source.kind !== "literal") addDependent(sourceDeviceId, link.source.cap);
 	}
 	return {
 		targets,
@@ -2315,6 +2579,15 @@ var DeviceMetaStore = class {
 		for (const m of Object.values(meta)) if (m.stableId === wanted) return m.id;
 		return null;
 	};
+	/** Resolve a GLOBAL link source (P2e) to a live device id: the device whose
+	*  FULL stableId equals `sourceStableId`, regardless of parent container.
+	*  First match wins (stableIds are effectively unique cluster-wide — see the
+	*  `DeviceLinkGlobalSource` docblock). Null when absent. Pure over a
+	*  pre-read meta map so a multi-link resolve reads the store once. */
+	resolveGlobalSourceDeviceId = (sourceStableId, meta) => {
+		for (const m of Object.values(meta)) if (m.stableId === sourceStableId) return m.id;
+		return null;
+	};
 	allocateNextDeviceId = async () => {
 		const current = (await this.readStore()).nextDeviceId ?? 1;
 		await this.settings.writeAddonStore({ nextDeviceId: current + 1 });
@@ -2345,8 +2618,35 @@ var DeviceMetaStore = class {
 			const container = targetMeta.parentDeviceId !== null ? stableIdById.get(targetMeta.parentDeviceId) ?? stableIdById.get(targetId) : stableIdById.get(targetId);
 			if (container === void 0) continue;
 			for (const link of targetMeta.deviceLinks ?? []) {
-				expectedSources.add(`${container}-${link.source.sourceKey}`);
-				const srcId = idByStableId.get(`${container}-${link.source.sourceKey}`);
+				const src = link.source;
+				if (src.kind === "expression") {
+					const bindingSourceIds = {};
+					for (const [name, b] of Object.entries(src.bindings)) {
+						if (b.kind === "literal") continue;
+						const wanted = b.kind === "global" ? b.sourceStableId : `${container}-${b.sourceKey}`;
+						expectedSources.add(wanted);
+						const bid = idByStableId.get(wanted);
+						if (bid !== void 0) bindingSourceIds[name] = bid;
+					}
+					entries.push({
+						targetDeviceId: targetId,
+						link,
+						sourceDeviceId: -1,
+						bindingSourceIds
+					});
+					continue;
+				}
+				if (src.kind === "literal") {
+					entries.push({
+						targetDeviceId: targetId,
+						link,
+						sourceDeviceId: -1
+					});
+					continue;
+				}
+				const wantedStableId = src.kind === "global" ? src.sourceStableId : `${container}-${src.sourceKey}`;
+				expectedSources.add(wantedStableId);
+				const srcId = idByStableId.get(wantedStableId);
 				if (srcId === void 0) continue;
 				entries.push({
 					targetDeviceId: targetId,
@@ -2453,6 +2753,7 @@ async function listAll(pctx, input) {
 			...m?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
 			...m?.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
 			...m?.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+			...m?.display !== void 0 ? { display: m.display } : {},
 			...(() => {
 				const si = buildSourceInfoFromConfig(persistedConfig ?? {}, stableId, aid);
 				return si !== void 0 ? { sourceInfo: si } : {};
@@ -2501,6 +2802,7 @@ async function getDevice(pctx, input) {
 		...m.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
 		...m.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
 		...m.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+		...m.display !== void 0 ? { display: m.display } : {},
 		...sourceInfoGetDevice !== void 0 ? { sourceInfo: sourceInfoGetDevice } : {}
 	};
 }
@@ -2563,6 +2865,7 @@ async function getChildren(pctx, input) {
 			...m.primaryChildEntityId !== void 0 ? { primaryChildEntityId: m.primaryChildEntityId } : {},
 			...m.childLayout !== void 0 ? { childLayout: m.childLayout } : {},
 			...m.deviceLinks !== void 0 ? { deviceLinks: m.deviceLinks } : {},
+			...m.display !== void 0 ? { display: m.display } : {},
 			...sourceInfoChild !== void 0 ? { sourceInfo: sourceInfoChild } : {}
 		});
 	}
@@ -2892,6 +3195,48 @@ async function testField(pctx, input) {
 function isRecord(x) {
 	return x !== null && typeof x === "object" && !Array.isArray(x);
 }
+/**
+* Resolve one link's transformed value. Field sources read via `readField`
+* (the caller supplies the sibling lookup — sync, e.g. the in-hub state
+* mirror); literal sources use their per-device constant and never consult
+* the reader. Returns `undefined` to skip the overlay (unreadable field).
+* Pure. Async source reads (`resolveLinkedStatus`'s provider `getStatus`
+* path) cannot use this helper for field sources — they branch on
+* `source.kind` directly.
+*/
+function resolveLinkValue(link, readField) {
+	const src = link.source;
+	if (src.kind === "expression") return void 0;
+	return applyTransform(src.kind === "literal" ? src.value : readField(src.cap, src.fieldPath), link.transform);
+}
+/**
+* Sync-channel expression resolution: bindings read from the mirror via
+* `readField(deviceId, cap, fieldPath)` using the pre-resolved per-binding ids
+* on the `ResolvedTargetLink`. A literal binding uses its constant; an absent
+* binding id (dangling source) or a non-primitive read resolves to `null`.
+* Returns `undefined` on parse/eval failure (skip overlay) — silent by design:
+* the mirror path is hot and churn-free; the async channel logs. Compile
+* failures cost one parse ever thanks to the negative LRU compile cache. Pure.
+*/
+function resolveExpressionLinkValue(rl, readField, now) {
+	const src = rl.link.source;
+	if (src.kind !== "expression") return void 0;
+	const bindingValues = {};
+	for (const [name, b] of Object.entries(src.bindings)) {
+		if (b.kind === "literal") {
+			bindingValues[name] = b.value;
+			continue;
+		}
+		const bId = rl.bindingSourceIds?.[name];
+		if (bId === void 0) {
+			bindingValues[name] = null;
+			continue;
+		}
+		bindingValues[name] = toExpressionValue(readField(bId, b.cap, b.fieldPath)) ?? null;
+	}
+	const result = evaluateLinkExpression(src.expr, bindingValues, now);
+	return result.ok ? applyTransform(result.value, rl.link.transform) : void 0;
+}
 /** Narrow Zod v4's structural `$ZodType` (returned by `.unwrap()`) back to the
 *  concrete classic `z.ZodType`. Every runtime schema is a `z.ZodType`, so this
 *  is a true `instanceof` guard rather than a cast. */
@@ -2923,19 +3268,88 @@ function fillNullableDefaults(schema, value) {
 	return out;
 }
 /**
+* Group item-targeted links (`target.itemKey` set) by itemKey and upsert each
+* group as ONE item into the status' item array (see
+* `CapabilityStatusItemArray`). A NEW item is seeded from `emptyItem` with
+* `keyField` (and `labelField`, when declared) set to the itemKey; an
+* EXISTING item (matched by `keyField`) is cloned and overlaid in place, so
+* native fields a link doesn't touch are preserved. Each upserted item is
+* validated against `itemSchema` — an invalid item is skipped WITHOUT
+* discarding its valid siblings. Returns the new draft and whether anything
+* was applied. Pure + immutable (base array/items are never mutated).
+*/
+function upsertItemArrayLinks(draft, grouped, itemArray) {
+	const arrRaw = getByPath(draft, itemArray.path);
+	const arr = Array.isArray(arrRaw) ? [...arrRaw] : [];
+	let touched = false;
+	for (const [itemKey, group] of grouped) {
+		const idx = arr.findIndex((el) => isRecord(el) && el[itemArray.keyField] === itemKey);
+		const existing = idx >= 0 ? arr[idx] : null;
+		let item = isRecord(existing) ? { ...existing } : {
+			...itemArray.emptyItem,
+			[itemArray.keyField]: itemKey,
+			...itemArray.labelField !== void 0 ? { [itemArray.labelField]: itemKey } : {}
+		};
+		let itemTouched = false;
+		for (const { link, sourceValue } of group) {
+			if (sourceValue === void 0) continue;
+			item = setByPath(item, link.target.fieldPath, sourceValue);
+			itemTouched = true;
+		}
+		if (!itemTouched) continue;
+		const repaired = fillNullableDefaults(itemArray.itemSchema, item);
+		const parsed = itemArray.itemSchema.safeParse(repaired);
+		if (!parsed.success) continue;
+		if (isRecord(parsed.data)) item = parsed.data;
+		if (idx >= 0) arr[idx] = item;
+		else arr.push(item);
+		touched = true;
+	}
+	if (!touched) return {
+		draft,
+		touched: false
+	};
+	return {
+		draft: setByPath(draft, itemArray.path, arr),
+		touched: true
+	};
+}
+/**
 * Overlay transformed source values onto `base` by dot-path, then validate the
 * result against the target cap's `statusSchema`. On validation failure the
 * overlay is discarded and `base` is returned unchanged (a misconfigured link
 * must never corrupt a cap response). Pure — all I/O happens in the caller.
+*
+* Item-array grouping (P2b): when the cap declares `status.itemArray`, links
+* carrying a `target.itemKey` are grouped per key and upserted as items into
+* the array (see `upsertItemArrayLinks`); their `fieldPath` is relative to
+* ONE item ('level', 'status', 'label'). Links WITHOUT an itemKey keep the
+* scalar dot-path behavior unchanged. A link with an itemKey on a cap that
+* declares NO `itemArray` is dropped (its item-relative path must never be
+* scalar-applied to the status root).
 */
-function mergeLinkedStatus(base, resolved, statusSchema) {
+function mergeLinkedStatus(base, resolved, statusSchema, itemArray) {
 	let draft = base;
 	let touched = false;
-	for (const { link, sourceValue } of resolved) {
-		if (sourceValue === void 0) continue;
-		draft = setByPath(draft, link.target.fieldPath, sourceValue);
+	const grouped = /* @__PURE__ */ new Map();
+	for (const entry of resolved) {
+		const itemKey = entry.link.target.itemKey;
+		if (itemKey !== void 0) {
+			if (!itemArray) continue;
+			const group = grouped.get(itemKey);
+			if (group) group.push(entry);
+			else grouped.set(itemKey, [entry]);
+			continue;
+		}
+		if (entry.sourceValue === void 0) continue;
+		draft = setByPath(draft, entry.link.target.fieldPath, entry.sourceValue);
 		touched = true;
 	}
+	if (itemArray && grouped.size > 0) {
+		const upserted = upsertItemArrayLinks(draft, grouped, itemArray);
+		draft = upserted.draft;
+		touched = touched || upserted.touched;
+	}
 	if (!touched) return base;
 	if (!statusSchema) return draft;
 	const repaired = fillNullableDefaults(statusSchema, draft);
@@ -3132,43 +3546,63 @@ var DeviceStateMirror = class DeviceStateMirror {
 	* Read-time overlay of a cap slice with its cross-device linked values.
 	* Returns a cloned raw mirror slice when the (device, cap) pair has no
 	* links. Sources are read from the same in-hub stateMirror — sync, no
-	* cross-process call. The disk writer must NOT use this method; it must
-	* persist raw provider truth via snapshotForDevice.
+	* cross-process call. When the raw slice is ABSENT but the cap is a link
+	* target, the slice is SYNTHESIZED: the merge base is seeded from the
+	* cap's declared `status.empty` default; a failed/empty synthesize
+	* returns null (no phantom slices). The disk writer must NOT use this
+	* method; it must persist raw provider truth via snapshotForDevice.
 	*/
 	overlayedSlice(deviceId, cap) {
 		const raw = this.stateMirror.get(deviceId)?.get(cap) ?? null;
 		const links = this.linkHost.linkTargets.get(`${deviceId}:${cap}`);
 		if (!links || links.length === 0) return raw ? { ...raw } : null;
+		const now = Date.now();
 		const resolved = links.map((rl) => ({
 			link: rl.link,
-			sourceValue: applyTransform(getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(rl.link.source.cap), rl.link.source.fieldPath), rl.link.transform)
+			sourceValue: rl.link.source.kind === "expression" ? resolveExpressionLinkValue(rl, (srcDeviceId, srcCap, fieldPath) => getByPath(this.stateMirror.get(srcDeviceId)?.get(srcCap), fieldPath), now) : resolveLinkValue(rl.link, (srcCap, fieldPath) => getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(srcCap), fieldPath))
 		}));
-		const schema = this.linkHost.capabilityRegistry?.getDefinition(cap)?.status?.schema;
-		return mergeLinkedStatus(raw ? { ...raw } : {}, resolved, schema);
+		const capStatus = this.linkHost.capabilityRegistry?.getDefinition(cap)?.status;
+		const schema = capStatus?.schema;
+		const empty = capStatus?.empty;
+		const base = raw ? { ...raw } : empty !== null && typeof empty === "object" && !Array.isArray(empty) ? { ...empty } : {};
+		const merged = mergeLinkedStatus(base, resolved, schema, capStatus?.itemArray);
+		if (!raw && merged === base) return null;
+		return merged;
 	}
 	/**
 	* Like snapshotForDevice but applies the device-link overlay per cap.
 	* Used exclusively by the device-state READ methods (getSnapshot,
-	* getAllSnapshots) so callers see overlayed values. The debounced disk
-	* writer must continue to call snapshotForDevice (raw truth).
+	* getAllSnapshots) so callers see overlayed values. SYNTHESIZE-only
+	* link-target caps (no base mirror slice) are unioned into the iterated
+	* key set so they appear at warm-load — `overlayedSlice` builds them from
+	* the cap's `status.empty` (and drops them when nothing resolves). The
+	* debounced disk writer must continue to call snapshotForDevice (raw truth).
 	*/
 	snapshotForDeviceOverlayed(deviceId) {
 		const perCap = this.stateMirror.get(deviceId);
-		if (!perCap) return {};
+		const capNames = new Set(perCap ? perCap.keys() : []);
+		const prefix = `${deviceId}:`;
+		for (const key of this.linkHost.linkTargets.keys()) if (key.startsWith(prefix)) capNames.add(key.slice(prefix.length));
 		const out = {};
-		for (const capName of perCap.keys()) {
+		for (const capName of capNames) {
 			const s = this.overlayedSlice(deviceId, capName);
 			if (s) out[capName] = s;
 		}
 		return out;
 	}
-	/** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`. */
+	/** Whole-system mirror dump (overlaid). Backs `deviceState.getAllSnapshots`.
+	*  Devices that only exist as link TARGETS (no mirror slice yet) are
+	*  included via the link reverse-index so their synthesized caps appear. */
 	allSnapshotsOverlayed() {
+		const deviceIds = new Set(this.stateMirror.keys());
+		for (const key of this.linkHost.linkTargets.keys()) {
+			const id = Number(key.slice(0, key.indexOf(":")));
+			if (Number.isFinite(id)) deviceIds.add(id);
+		}
 		const out = {};
-		for (const [deviceId, perCap] of this.stateMirror) {
-			const dev = {};
-			for (const [capName, slice] of perCap) dev[capName] = this.overlayedSlice(deviceId, capName) ?? { ...slice };
-			out[String(deviceId)] = dev;
+		for (const deviceId of deviceIds) {
+			const dev = this.snapshotForDeviceOverlayed(deviceId);
+			if (this.stateMirror.has(deviceId) || Object.keys(dev).length > 0) out[String(deviceId)] = dev;
 		}
 		return out;
 	}
@@ -3287,14 +3721,27 @@ function resolveNativeCapOwnerSync(pctx, capName, deviceId) {
 * `getProviderForDevice` (routes cross-process); merge is pure.
 */
 async function resolveLinkedStatus(pctx, input) {
-	const { deviceId, cap, baseStatus } = input;
+	const { deviceId, cap } = input;
 	if (!pctx.host.devicesWithLinks.has(deviceId)) return null;
+	const inFlightKey = `${deviceId}:${cap}`;
+	if (pctx.host.linkResolveInFlight.has(inFlightKey)) return null;
+	pctx.host.linkResolveInFlight.add(inFlightKey);
+	try {
+		return await resolveLinkedStatusInner(pctx, input);
+	} finally {
+		pctx.host.linkResolveInFlight.delete(inFlightKey);
+	}
+}
+/** Body of `resolveLinkedStatus` — see the wrapper for the re-entrancy guard. */
+async function resolveLinkedStatusInner(pctx, input) {
+	const { deviceId, cap, baseStatus } = input;
 	const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
 	if (!persisted) return null;
 	const links = (persisted.meta.deviceLinks ?? []).filter((l) => l.target.cap === cap);
 	if (links.length === 0) return null;
 	const capRegistry = pctx.host.capabilityRegistry;
-	const schema = capRegistry?.getDefinition(cap)?.status?.schema;
+	const capStatus = capRegistry?.getDefinition(cap)?.status;
+	const schema = capStatus?.schema;
 	if (!schema) return null;
 	const allMeta = await pctx.metaStore.readMeta();
 	let containerStableId = persisted.stableId;
@@ -3303,32 +3750,96 @@ async function resolveLinkedStatus(pctx, input) {
 		const parentMeta = allMeta[String(parentId)];
 		if (parentMeta) containerStableId = parentMeta.stableId;
 	}
+	const now = Date.now();
+	const statusMemo = /* @__PURE__ */ new Map();
+	const readSourceStatus = async (srcId, srcCap) => {
+		const key = `${srcId}:${srcCap}`;
+		const cached = statusMemo.get(key);
+		if (cached !== void 0) return cached;
+		let result;
+		try {
+			const srcProvider = capRegistry?.getProviderForDevice(srcCap, srcId);
+			result = {
+				status: typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0,
+				ok: true
+			};
+		} catch (err) {
+			pctx.host.ctx.logger.warn("resolveLinkedStatus: source read failed", {
+				tags: {
+					deviceId,
+					capName: cap
+				},
+				meta: {
+					sourceCap: srcCap,
+					sourceId: srcId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			result = {
+				status: void 0,
+				ok: false
+			};
+		}
+		statusMemo.set(key, result);
+		return result;
+	};
 	const resolved = [];
 	for (const link of links) {
-		const srcId = pctx.metaStore.resolveSourceDeviceId(containerStableId, link.source.sourceKey, allMeta);
-		if (srcId === null) continue;
-		try {
-			const srcProvider = capRegistry?.getProviderForDevice(link.source.cap, srcId);
-			const raw = getByPath(typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0, link.source.fieldPath);
+		const src = link.source;
+		if (src.kind === "literal") {
 			resolved.push({
 				link,
-				sourceValue: applyTransform(raw, link.transform)
+				sourceValue: applyTransform(src.value, link.transform)
 			});
-		} catch (err) {
-			pctx.host.ctx.logger.warn("resolveLinkedStatus: source read failed", {
+			continue;
+		}
+		if (src.kind === "expression") {
+			const bindingValues = {};
+			for (const [name, b] of Object.entries(src.bindings)) {
+				if (b.kind === "literal") {
+					bindingValues[name] = b.value;
+					continue;
+				}
+				const bId = b.kind === "global" ? pctx.metaStore.resolveGlobalSourceDeviceId(b.sourceStableId, allMeta) : pctx.metaStore.resolveSourceDeviceId(containerStableId, b.sourceKey, allMeta);
+				if (bId === null) {
+					bindingValues[name] = null;
+					continue;
+				}
+				bindingValues[name] = toExpressionValue(getByPath((await readSourceStatus(bId, b.cap)).status, b.fieldPath)) ?? null;
+			}
+			const result = evaluateLinkExpression(src.expr, bindingValues, now);
+			if (result.ok) resolved.push({
+				link,
+				sourceValue: applyTransform(result.value, link.transform)
+			});
+			else pctx.host.ctx.logger.warn("resolveLinkedStatus: expression skipped", {
 				tags: {
 					deviceId,
 					capName: cap
 				},
 				meta: {
-					sourceKey: link.source.sourceKey,
-					error: err instanceof Error ? err.message : String(err)
+					linkId: link.id,
+					error: result.error
 				}
 			});
+			continue;
 		}
+		const srcId = src.kind === "global" ? pctx.metaStore.resolveGlobalSourceDeviceId(src.sourceStableId, allMeta) : pctx.metaStore.resolveSourceDeviceId(containerStableId, src.sourceKey, allMeta);
+		if (srcId === null) continue;
+		const read = await readSourceStatus(srcId, src.cap);
+		if (!read.ok) continue;
+		const raw = getByPath(read.status, src.fieldPath);
+		resolved.push({
+			link,
+			sourceValue: applyTransform(raw, link.transform)
+		});
 	}
 	if (resolved.length === 0) return null;
-	return mergeLinkedStatus(isRecord$1(baseStatus) ? baseStatus : {}, resolved, schema);
+	const synthesizing = !isRecord$1(baseStatus);
+	const base = isRecord$1(baseStatus) ? baseStatus : isRecord$1(capStatus.empty) ? { ...capStatus.empty } : {};
+	const merged = mergeLinkedStatus(base, resolved, schema, capStatus.itemArray);
+	if (synthesizing && merged === base) return null;
+	return merged;
 }
 //#endregion
 //#region src/builtins/device-manager/device-manager.addon.ts
@@ -3394,10 +3905,15 @@ var DeviceManagerAddon = class extends BaseAddon {
 	linkTargets = /* @__PURE__ */ new Map();
 	/** `${sourceDeviceId}:${sourceCap}` → targets to recompute when that source changes. */
 	linkDependents = /* @__PURE__ */ new Map();
-	/** Expected source `stableId`s (`${container}-${sourceKey}`) across all links,
+	/** Expected source `stableId`s (`${container}-${sourceKey}` for sibling
+	*  sources, the full `sourceStableId` for global sources) across all links,
 	*  resolved or not — gates the `registerDevice` rebuild so only a registering
 	*  device that IS a link source triggers a reindex (not every boot restore). */
 	expectedSourceStableIds = /* @__PURE__ */ new Set();
+	/** In-flight `${deviceId}:${cap}` pairs of `resolveLinkedStatus` — the P2e
+	*  defensive re-entrancy guard bounding link cycles at resolve time. Mutated
+	*  in place (never reassigned), so the host exposes a direct reference. */
+	linkResolveInFlight = /* @__PURE__ */ new Set();
 	/** Test/diagnostic accessors. */
 	linkTargetKeys() {
 		return [...this.linkTargets.keys()];
@@ -3469,6 +3985,7 @@ var DeviceManagerAddon = class extends BaseAddon {
 			get expectedSourceStableIds() {
 				return expectedSourceStableIds();
 			},
+			linkResolveInFlight: this.linkResolveInFlight,
 			dropDeviceOverlays: (deviceId) => this.stateMirror.dropDeviceOverlays(deviceId),
 			remoteNativeCaps: this.remoteNativeCaps,
 			seedMirror: (deviceId, blob) => this.stateMirror.seedMirror(deviceId, blob),
@@ -3517,12 +4034,15 @@ var DeviceManagerAddon = class extends BaseAddon {
 			}
 		}))).filter((id) => id !== null);
 	}
-	/** Build the dependency context the extracted binding resolvers consume. */
+	/** Build the dependency context the extracted binding resolvers consume.
+	*  `devicesWithLinks` is mutated in place (never reassigned) so the direct
+	*  reference stays live — it gates the virtual `linked` binding step. */
 	get bindingsDeps() {
 		return {
 			ctx: this.ctx,
 			capabilityRegistry: this.capabilityRegistry,
-			remoteNativeCaps: this.remoteNativeCaps
+			remoteNativeCaps: this.remoteNativeCaps,
+			devicesWithLinks: this.devicesWithLinks
 		};
 	}
 	async getBindings(input) {
@@ -3625,6 +4145,9 @@ var DeviceManagerAddon = class extends BaseAddon {
 			setChildLayout: (input) => setChildLayout(pctx, input),
 			setDeviceLinks: (input) => setDeviceLinks(pctx, input),
 			setRole: (input) => setRole(pctx, input),
+			setDisplay: (input) => setDisplay(pctx, input),
+			getRoleDisplayDefaults: (input) => getRoleDisplayDefaults(pctx, input),
+			setRoleDisplayDefaults: (input) => setRoleDisplayDefaults(pctx, input),
 			applyInitialMeta: (input) => applyInitialMeta(pctx, input),
 			setMetadata: (input) => setMetadata(pctx, input),
 			setDisabled: (input) => setDisabled(pctx, input),