@camstack/system 1.1.23 → 1.1.25

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

@@ -1,5 +1,5 @@
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
-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, 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) {
@@ -1366,20 +1367,41 @@ var DeviceEventPropagator = class {
 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 its `(deviceId, cap)` node, or null when the
-* source is a literal (no device) or does not resolve to a known device.
-* Sibling FIELD sources resolve against the TARGET's container stableId
-* (its parent's, falling back to its own for a top-level target) — the same
-* rule `rebuildLinkDependents` / `resolveLinkedStatus` apply.
+* 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 resolveSourceNode(link, targetRow, rowById, idByStableId) {
+function resolveSourceNodes(link, targetRow, rowById, idByStableId) {
 	const src = link.source;
-	if (src.kind === "literal") return null;
-	const wantedStableId = src.kind === "global" ? src.sourceStableId : `${targetRow.parentDeviceId !== null ? rowById.get(targetRow.parentDeviceId)?.stableId ?? targetRow.stableId : targetRow.stableId}-${src.sourceKey}`;
-	const srcId = idByStableId.get(wantedStableId);
-	if (srcId === void 0) return null;
-	return nodeKey(srcId, src.cap);
+	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
@@ -1397,11 +1419,11 @@ function findDeviceLinkCycle(allMeta, editedDeviceId, editedLinks) {
 	const dependsOn = /* @__PURE__ */ new Map();
 	const addEdges = (row, links) => {
 		for (const link of links) {
-			const srcNode = resolveSourceNode(link, row, rowById, idByStableId);
-			if (srcNode === null) continue;
+			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) ?? [];
-			list.push(srcNode);
+			for (const srcNode of srcNodes) list.push(srcNode);
 			dependsOn.set(tNode, list);
 		}
 	};
@@ -1468,7 +1490,7 @@ function dfsFindCycle(root, dependsOn) {
 * 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).
 *
@@ -1577,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,
@@ -2018,6 +2041,11 @@ 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}`);
@@ -2088,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),
@@ -2332,23 +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);
-		if (link.source.kind !== "literal") {
-			const sKey = `${sourceDeviceId}:${link.source.cap}`;
+		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,
@@ -2503,6 +2619,23 @@ var DeviceMetaStore = class {
 			if (container === void 0) continue;
 			for (const link of targetMeta.deviceLinks ?? []) {
 				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,
@@ -2620,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 } : {};
@@ -2668,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 } : {}
 	};
 }
@@ -2730,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 } : {}
 		});
 	}
@@ -3069,7 +3205,37 @@ function isRecord(x) {
 * `source.kind` directly.
 */
 function resolveLinkValue(link, readField) {
-	return applyTransform(link.source.kind === "literal" ? link.source.value : readField(link.source.cap, link.source.fieldPath), link.transform);
+	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
@@ -3390,9 +3556,10 @@ var DeviceStateMirror = class DeviceStateMirror {
 		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: resolveLinkValue(rl.link, (srcCap, fieldPath) => getByPath(this.stateMirror.get(rl.sourceDeviceId)?.get(srcCap), fieldPath))
+			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 capStatus = this.linkHost.capabilityRegistry?.getDefinition(cap)?.status;
 		const schema = capStatus?.schema;
@@ -3583,6 +3750,39 @@ async function resolveLinkedStatusInner(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 src = link.source;
@@ -3593,27 +3793,46 @@ async function resolveLinkedStatusInner(pctx, input) {
 			});
 			continue;
 		}
-		const srcId = src.kind === "global" ? pctx.metaStore.resolveGlobalSourceDeviceId(src.sourceStableId, allMeta) : pctx.metaStore.resolveSourceDeviceId(containerStableId, src.sourceKey, allMeta);
-		if (srcId === null) continue;
-		try {
-			const srcProvider = capRegistry?.getProviderForDevice(src.cap, srcId);
-			const raw = getByPath(typeof srcProvider?.getStatus === "function" ? await srcProvider.getStatus({ deviceId: srcId }) : void 0, src.fieldPath);
-			resolved.push({
+		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(raw, link.transform)
+				sourceValue: applyTransform(result.value, link.transform)
 			});
-		} catch (err) {
-			pctx.host.ctx.logger.warn("resolveLinkedStatus: source read failed", {
+			else pctx.host.ctx.logger.warn("resolveLinkedStatus: expression skipped", {
 				tags: {
 					deviceId,
 					capName: cap
 				},
 				meta: {
-					sourceKey: src.kind === "global" ? src.sourceStableId : src.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;
 	const synthesizing = !isRecord$1(baseStatus);
@@ -3926,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),

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

@@ -97,6 +97,27 @@ export declare function setDeviceLinks(pctx: ProviderContext, input: Parameters<
  * `setIntegrationId`). Idempotent. `null` clears a previous role.
  */
 export declare function setRole(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setRole']>[0]): ReturnType<IDeviceManagerProvider['setRole']>;
+/**
+ * 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.
+ */
+export declare function setDisplay(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setDisplay']>[0]): ReturnType<IDeviceManagerProvider['setDisplay']>;
+/**
+ * Read the operator-authored per-role display defaults. Empty record when none
+ * set. Not per-device — a plain top-level-key read.
+ */
+export declare function getRoleDisplayDefaults(pctx: ProviderContext, _input: Parameters<IDeviceManagerProvider['getRoleDisplayDefaults']>[0]): ReturnType<IDeviceManagerProvider['getRoleDisplayDefaults']>;
+/**
+ * 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.
+ */
+export declare function setRoleDisplayDefaults(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setRoleDisplayDefaults']>[0]): ReturnType<IDeviceManagerProvider['setRoleDisplayDefaults']>;
 /**
  * Batched meta pre-seed. Applies every provided field to the
  * device's meta row in ONE read-modify-write under a single

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

@@ -1,4 +1,4 @@
-import { ChildLayout, DeviceLinks } from '@camstack/types';
+import { ChildLayout, DeviceDisplayOverride, DeviceLinks, RoleDisplayDefault } from '@camstack/types';
 /**
  * Wire shape matching `z.infer<typeof SettingsSchemaWithValuesSchema>` —
  * duplicated as a plain interface because importing the Zod schema across
@@ -132,6 +132,11 @@ export interface PersistedDeviceMeta {
      *  Optional: only present for accessory children that carry a known role
      *  (e.g. 'numeric-sensor', 'binary-sensor'). `null` clears a previous role. */
     role?: string | null;
+    /** Operator-authored per-device display override (icon/label/unit/precision/
+     *  hidden), set via `setDisplay`. Same create/persist/project/restore
+     *  lifecycle as `deviceLinks`. Absent ⇒ no override. Applied at render time
+     *  only — storage stays in source units. */
+    display?: DeviceDisplayOverride;
 }
 export interface AddonStore {
     deviceIndex?: Record<string, string[]>;
@@ -166,4 +171,10 @@ export interface AddonStore {
      * the operator forgot to register a label before assigning it.
      */
     locations?: readonly string[];
+    /** Operator-authored per-role display defaults (unit/precision/icon), keyed
+     *  by `DeviceRole` string. Resolution merges these UNDER any per-device
+     *  `display` override. Written whole-record by `setRoleDisplayDefaults`
+     *  (full replace — no read-modify-write, single writer, so it never
+     *  interacts with the `deviceMeta` write lock). */
+    roleDisplayDefaults?: Record<string, RoleDisplayDefault>;
 }

package/dist/builtins/device-manager/device-projection.d.ts

@@ -47,6 +47,7 @@ export declare function isDeviceRole(value: string): value is DeviceRole;
  *  never leaks an off-enum string onto the wire shape. */
 export declare function toDeviceRole(value: string | null | undefined): DeviceRole | null;
 export declare function toDeviceInfo(addonId: string, device: IDevice, metadata?: Record<string, unknown> | null, metaRow?: PersistedDeviceMeta | null): {
+    display?: import('@camstack/types').DeviceDisplayOverride | undefined;
     deviceLinks?: import('@camstack/types').DeviceLinks | undefined;
     childLayout?: import('@camstack/types').ChildLayout | undefined;
     primaryChildEntityId?: string | null | undefined;

package/dist/builtins/platform-probe/index.d.ts

@@ -8,7 +8,29 @@ export declare class PlatformProbeNativeAddon extends BaseAddon {
     private encoderProber;
     private decodeAccelProber;
     private cachedCaps;
+    /**
+     * Per-boot generation stamp for the manual readiness emissions below.
+     * Constant for the lifetime of this addon instance (== one process boot);
+     * consumer-side registries derive a monotonic epoch from generation
+     * transitions. Mirrors `BaseAddon._readinessGeneration` (private there).
+     */
+    private readonly readinessGeneration;
     constructor();
+    /**
+     * Manual readiness protocol. The provider registers synchronously from
+     * `onInitialize`, but the REAL hardware + EP scoring is the async
+     * `probePromise` (embedded-Python install included). The BaseAddon
+     * auto-emit would flip `ready` at registration time — BEFORE any
+     * accelerator is visible — so probe-gated consumers (detection-pipeline
+     * engine auto-pick) would read accelerator-blind results and stick on
+     * onnx-CPU. Instead: `starting` at init, the single authoritative
+     * `ready` once the probe resolves, `down` on shutdown.
+     */
+    protected get autoEmitReadiness(): boolean;
+    /** Bare cluster node id — readiness is scoped `{type:'node', nodeId}`. */
+    private bareLocalNodeId;
+    /** Emit a `system.ready-state` transition for the platform-probe cap. */
+    private emitProbeReadiness;
     /**
      * Resolve the ffmpeg binary the encoder probe should test, from the cluster
      * `ffmpeg` config section (`binaryPath`). The probe MUST exercise the same

package/dist/builtins/platform-probe/index.js

@@ -594,15 +594,86 @@ var HardwareDecodeAccelProber = class {
 };
 //#endregion
 //#region src/builtins/platform-probe/index.ts
+/**
+* The decode-hwaccel backends `ctx.kernel.hwaccel.resolve` accepts. The cap
+* input enum is WIDER (it also carries EP-only names — coreml/openvino/… —
+* shared with other probe surfaces), so the provider param must stay
+* `string`-typed to satisfy the `InferProvider` contract. We narrow it here
+* with a type guard instead of a cast: any value that is not a known decode
+* backend (or the `'none'` sentinel) resolves to `null` → auto-probe.
+*/
+var HWACCEL_DECODE_BACKENDS = [
+	"videotoolbox",
+	"cuda",
+	"nvdec",
+	"vaapi",
+	"qsv",
+	"d3d11va",
+	"dxva2",
+	"amf",
+	"vdpau",
+	"drm"
+];
+function isHwAccelBackend(value) {
+	return HWACCEL_DECODE_BACKENDS.includes(value);
+}
+function narrowHwAccelPrefer(value) {
+	if (value === "none") return "none";
+	if (typeof value === "string" && isHwAccelBackend(value)) return value;
+	return null;
+}
 var PlatformProbeNativeAddon = class extends _camstack_types.BaseAddon {
 	scorer = null;
 	encoderProber = null;
 	decodeAccelProber = null;
 	cachedCaps = null;
+	/**
+	* Per-boot generation stamp for the manual readiness emissions below.
+	* Constant for the lifetime of this addon instance (== one process boot);
+	* consumer-side registries derive a monotonic epoch from generation
+	* transitions. Mirrors `BaseAddon._readinessGeneration` (private there).
+	*/
+	readinessGeneration = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).slice(2, 14);
 	constructor() {
 		super({});
 	}
 	/**
+	* Manual readiness protocol. The provider registers synchronously from
+	* `onInitialize`, but the REAL hardware + EP scoring is the async
+	* `probePromise` (embedded-Python install included). The BaseAddon
+	* auto-emit would flip `ready` at registration time — BEFORE any
+	* accelerator is visible — so probe-gated consumers (detection-pipeline
+	* engine auto-pick) would read accelerator-blind results and stick on
+	* onnx-CPU. Instead: `starting` at init, the single authoritative
+	* `ready` once the probe resolves, `down` on shutdown.
+	*/
+	get autoEmitReadiness() {
+		return false;
+	}
+	/** Bare cluster node id — readiness is scoped `{type:'node', nodeId}`. */
+	bareLocalNodeId() {
+		const raw = this.ctx.kernel?.localNodeId ?? "hub";
+		return raw.includes("/") ? raw.split("/")[0] : raw;
+	}
+	/** Emit a `system.ready-state` transition for the platform-probe cap. */
+	emitProbeReadiness(state) {
+		const ctx = this.ctxIfReady;
+		if (!ctx) return;
+		const nodeId = this.bareLocalNodeId();
+		try {
+			(0, _camstack_types.emitReadiness)(ctx.eventBus, {
+				capName: _camstack_types.platformProbeCapability.name,
+				scope: {
+					type: "node",
+					nodeId
+				},
+				state,
+				generation: this.readinessGeneration,
+				sourceNodeId: nodeId
+			});
+		} catch {}
+	}
+	/**
 	* Resolve the ffmpeg binary the encoder probe should test, from the cluster
 	* `ffmpeg` config section (`binaryPath`). The probe MUST exercise the same
 	* binary the broker/recorder spawn, or it may report encoders for a different
@@ -617,6 +688,7 @@ var PlatformProbeNativeAddon = class extends _camstack_types.BaseAddon {
 		}
 	}
 	async onInitialize() {
+		this.emitProbeReadiness("starting");
 		const embeddedPython = await this.ctx.deps.ensurePython().catch((err) => {
 			this.ctx.logger.debug("ensurePython unavailable for platform probe", { meta: { error: (0, _camstack_types.errMsg)(err) } });
 			return null;
@@ -651,6 +723,7 @@ var PlatformProbeNativeAddon = class extends _camstack_types.BaseAddon {
 				bestReason: caps.bestScore.reason,
 				bestScore: caps.bestScore.score
 			} });
+			this.emitProbeReadiness("ready");
 			return caps;
 		}).catch((err) => {
 			const msg = (0, _camstack_types.errMsg)(err);
@@ -676,8 +749,15 @@ var PlatformProbeNativeAddon = class extends _camstack_types.BaseAddon {
 				},
 				resolveHwAccel: async (input) => {
 					const hwaccel = this.ctx.kernel.hwaccel;
-					if (!hwaccel) return { preferred: [] };
-					return { preferred: (await hwaccel.resolve(input.prefer ?? null)).preferred };
+					if (!hwaccel) return {
+						preferred: [],
+						rationale: "kernel hwaccel unavailable"
+					};
+					const res = await hwaccel.resolve(narrowHwAccelPrefer(input.prefer));
+					return {
+						preferred: res.preferred,
+						rationale: res.rationale
+					};
 				},
 				getHardwareEncoders: async () => {
 					const prober = this.encoderProber;
@@ -707,6 +787,7 @@ var PlatformProbeNativeAddon = class extends _camstack_types.BaseAddon {
 		}];
 	}
 	async onShutdown() {
+		this.emitProbeReadiness("down");
 		this.scorer = null;
 		this.encoderProber = null;
 		this.decodeAccelProber = null;