@camstack/addon-osd-manager 0.1.157 → 0.1.161

package/dist/index.js

@@ -39331,22 +39331,35 @@ setOverlay: method(object({
 		}
 	}] }
 };
+_enum([
+	"value",
+	"unit",
+	"full"
+]);
+_enum([
+	"value+unit",
+	"value",
+	"unit"
+]);
 /**
-* `osd-manager` — the ORCHESTRATOR over the device-scope `osd` cap.
-*
-* The `osd` cap is the firmware contract: it probes a camera's overlay
-* SLOTS and writes literal text into one. It has no idea WHERE that text
-* comes from, and it must not — a driver that grew a "show the temperature
-* here" feature would grow it once per vendor.
-*
-* This cap owns the other half: a per-(camera, slot) BINDING that says
-* which value feeds the slot, how it is formatted, and under which
-* conditions it is shown at all. Named TEMPLATES combine many device
-* fields into one overlay string (Scrypted OSD Manager parity).
+* How the operator reached the leaf device. `deviceId` is ALWAYS the
+* OSD-supported leaf that is read; `containerId` is set when the pick
+* went through a container (gateway) first.
 */
-/** One field reference inside a named multi-device template. */
-var OsdTemplateFieldSchema = object({
-	deviceId: number().int(),
+var OsdTemplatePickSchema = object({
+	containerId: number().int().optional(),
+	deviceId: number().int()
+});
+/**
+* One named binding inside a multi-device template: device path + unit
+* selection + precision. The parser expands `{alias}`, `{alias.value}`,
+* `{alias.unit}`, or `{alias.full}` from the same binding — there is no
+* per-binding format lock.
+*/
+var OsdTemplateBindingSchema = object({
+	/** Token stem in the parser, e.g. `t` → `{t}` / `{t.value}`. Unique within the template. */
+	alias: string().min(1).max(32).regex(/^[A-Za-z][A-Za-z0-9_-]*$/, "alias must start with a letter"),
+	pick: OsdTemplatePickSchema,
 	capName: string().min(1).max(64),
 	valuePath: string().min(1).max(64),
 	/** Convert TO this unit at render (`tryConvertUnit`). Absent = source unit. */
@@ -39354,14 +39367,14 @@ var OsdTemplateFieldSchema = object({
 	maxDecimals: number().int().min(0).max(4).default(1)
 });
 /**
-* A named template: several device fields → one parser string with
-* `{deviceId.capName.valuePath}` tokens (Scrypted `{deviceId.sensorId}`).
+* A named template: bindings (alias → leaf field) + a parser that
+* references `{alias}` / `{alias.value}` / `{alias.unit}` / `{alias.full}`.
 */
 var OsdNamedTemplateSchema = object({
 	id: string().min(1).max(64),
 	name: string().min(1).max(64),
-	fields: array(OsdTemplateFieldSchema).max(32).default([]),
-	/** Parser with multi-token placeholders, e.g. `T {12.thermometer.value}°`. */
+	bindings: array(OsdTemplateBindingSchema).max(32).default([]),
+	/** Parser with alias placeholders, e.g. `{t.value} {t.unit} / {h}`. */
 	parser: string().max(256).default("")
 });
 /** Where a slot's value comes from. */
@@ -45567,6 +45580,10 @@ var UNIT_TABLE = {
 function specFor(unit) {
 	return Object.hasOwn(UNIT_TABLE, unit) ? UNIT_TABLE[unit] : void 0;
 }
+/** The dimension a unit belongs to, or `undefined` for an unknown unit. */
+function unitDimension(unit) {
+	return specFor(unit)?.dimension;
+}
 /** Value in `spec`'s unit → its dimension's canonical unit. */
 function toCanonical(value, spec) {
 	return value * spec.factor + spec.offset;
@@ -58368,14 +58385,91 @@ function readStatePath(slice, path) {
 }
 //#endregion
 //#region src/template-tokens.ts
-/** Build the placeholder token for one template field. */
-function fieldToken(field) {
-	return `{${field.deviceId}.${field.capName}.${field.valuePath}}`;
+/** Build a placeholder token for one binding alias + expand kind. */
+function aliasToken(alias, kind = "full") {
+	if (kind === "full") return `{${alias}}`;
+	return `{${alias}.${kind}}`;
+}
+/** Explicit `{alias.full}` form (chips prefer this over bare `{alias}`). */
+function aliasFullToken(alias) {
+	return `{${alias}.full}`;
+}
+/** Chip / parser insert options for one binding (value, unit, value+unit). */
+function bindingInsertChips(binding) {
+	const alias = binding.alias;
+	return [
+		{
+			id: `${alias}.value`,
+			label: `${alias} · value`,
+			token: aliasToken(alias, "value"),
+			kind: "value"
+		},
+		{
+			id: `${alias}.unit`,
+			label: `${alias} · unit`,
+			token: aliasToken(alias, "unit"),
+			kind: "unit"
+		},
+		{
+			id: `${alias}.full`,
+			label: `${alias} · value+unit`,
+			token: aliasFullToken(alias),
+			kind: "full"
+		}
+	];
+}
+/** @deprecated Prefer `bindingInsertChips` — bare `{alias}` only. */
+function bindingToken(binding) {
+	return aliasToken(binding.alias, "full");
+}
+/**
+* Parse `{alias}`, `{alias.value}`, `{alias.unit}`, `{alias.full}` from a
+* parser string. Bare `{alias}` and `{alias.full}` both mean `full`.
+*/
+function parseAliasTokens(parser) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of parser.matchAll(/\{([A-Za-z][A-Za-z0-9_-]*)(?:\.(value|unit|full))?\}/g)) {
+		const alias = match[1];
+		if (alias === void 0 || alias === "") continue;
+		const suffix = match[2];
+		const kind = suffix === "value" || suffix === "unit" ? suffix : "full";
+		const token = match[0] ?? "";
+		const key = `${alias}:${kind}:${token}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push({
+			alias,
+			kind,
+			token
+		});
+	}
+	return out;
+}
+/** Unique alias stems referenced by a parser (any token kind). */
+function parseAliasStems(parser) {
+	const stems = [];
+	for (const entry of parseAliasTokens(parser)) if (!stems.includes(entry.alias)) stems.push(entry.alias);
+	return stems;
 }
 /** Replace every occurrence of `token` in `parser` with `value`. */
 function replaceToken(parser, token, value) {
 	return parser.replaceAll(token, value);
 }
+/**
+* Suggest a short unique alias from a device/field name.
+* Falls back to `b1`, `b2`, … when the slug collides.
+*/
+function suggestAlias(seed, taken, fallbackPrefix = "b") {
+	const slug = seed.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/^(\d)/, "a$1").slice(0, 24);
+	const base = slug.length > 0 ? slug : fallbackPrefix;
+	if (!taken.has(base)) return base;
+	for (let i = 2; i < 1e3; i += 1) {
+		const candidate = `${base}${i}`.slice(0, 32);
+		if (!taken.has(candidate)) return candidate;
+	}
+	return `${fallbackPrefix}${Date.now().toString(36)}`;
+}
 //#endregion
 //#region src/unit-display.ts
 /**
@@ -58383,6 +58477,16 @@ function replaceToken(parser, token, value) {
 * UNIT_TABLE / tryConvertUnit (same set as D699).
 */
 /**
+* Dimension for a UnitPicker from a raw source unit (may be bare `C`).
+* Normalize before `unitDimension` — the table only knows canonical spellings.
+*/
+function dimensionFromSourceUnit(sourceUnit) {
+	if (sourceUnit === void 0) return void 0;
+	const normalized = normalizeUnit(sourceUnit);
+	if (normalized === void 0) return void 0;
+	return unitDimension(normalized);
+}
+/**
 * Convert `raw` from `sourceUnit` to `displayUnit` when both are known and
 * same-dimension. On refusal, keep the raw value and the source unit so the
 * label never lies about the number.
@@ -58431,24 +58535,64 @@ function inferSourceUnit(slice, valuePath) {
 }
 //#endregion
 //#region src/named-template-render.ts
+/** Combine value/unit for a token kind. */
+function applyTemplateTokenKind(value, unit, kind) {
+	if (kind === "value") return value;
+	if (kind === "unit") return unit;
+	const v = value.trim();
+	const u = unit.trim();
+	if (v === "") return u;
+	if (u === "") return v;
+	return `${v} ${u}`;
+}
+/**
+* @deprecated Prefer `applyTemplateTokenKind`. Maps legacy format enum to
+* the same join rules (`value+unit` → `full`).
+*/
+function applyTemplateFormat(value, unit, format) {
+	return applyTemplateTokenKind(value, unit, format === "value" ? "value" : format === "unit" ? "unit" : "full");
+}
+/** Resolve one binding to live value/unit/formatted parts (or a reason). */
+function resolveBindingLive(binding, facts) {
+	const deviceId = binding.pick.deviceId;
+	const deviceState = facts.stateByDevice.get(deviceId);
+	if (deviceState === void 0) return { reason: `no state mirrored for device ${deviceId}` };
+	const slice = deviceState[binding.capName];
+	if (slice === void 0) return { reason: `device ${deviceId} publishes no "${binding.capName}" state` };
+	const raw = readStatePath(slice, binding.valuePath);
+	if (raw === void 0) return { reason: `"${binding.capName}.${binding.valuePath}" is absent on device ${deviceId}` };
+	let value;
+	let unit = "";
+	if (typeof raw === "number") {
+		const converted = convertForDisplay(raw, inferSourceUnit(slice, binding.valuePath), binding.displayUnit);
+		value = truncateDecimals(converted.value, binding.maxDecimals);
+		unit = converted.unit;
+	} else if (typeof raw === "boolean") value = raw ? "ON" : "OFF";
+	else if (raw === null) value = "";
+	else value = String(raw);
+	return {
+		value,
+		unit,
+		formatted: applyTemplateTokenKind(value, unit, "full")
+	};
+}
+/** Substitute every token form for one alias from live parts. Longest first. */
+function expandBindingTokens(parser, alias, live) {
+	let text = parser;
+	text = replaceToken(text, aliasFullToken(alias), live.formatted);
+	text = replaceToken(text, aliasToken(alias, "value"), live.value);
+	text = replaceToken(text, aliasToken(alias, "unit"), live.unit);
+	text = replaceToken(text, aliasToken(alias, "full"), live.formatted);
+	return text;
+}
 /** Render one named template's parser from live states. */
 function renderNamedTemplate(template, facts) {
 	let text = template.parser;
-	if (template.fields.length === 0) return text.trim() === "" ? { reason: `template "${template.id}" has no fields` } : { text };
-	for (const field of template.fields) {
-		const token = fieldToken(field);
-		const deviceState = facts.stateByDevice.get(field.deviceId);
-		if (deviceState === void 0) return { reason: `no state mirrored for device ${field.deviceId}` };
-		const slice = deviceState[field.capName];
-		if (slice === void 0) return { reason: `device ${field.deviceId} publishes no "${field.capName}" state` };
-		const raw = readStatePath(slice, field.valuePath);
-		if (raw === void 0) return { reason: `"${field.capName}.${field.valuePath}" is absent on device ${field.deviceId}` };
-		let rendered;
-		if (typeof raw === "number") rendered = truncateDecimals(convertForDisplay(raw, inferSourceUnit(slice, field.valuePath), field.displayUnit).value, field.maxDecimals);
-		else if (typeof raw === "boolean") rendered = raw ? "ON" : "OFF";
-		else if (raw === null) rendered = "";
-		else rendered = String(raw);
-		text = replaceToken(text, token, rendered);
+	if (template.bindings.length === 0) return text.trim() === "" ? { reason: `template "${template.id}" has no bindings` } : { text };
+	for (const binding of template.bindings) {
+		const live = resolveBindingLive(binding, facts);
+		if ("reason" in live) return live;
+		text = expandBindingTokens(text, binding.alias, live);
 	}
 	return { text };
 }
@@ -58550,20 +58694,98 @@ function settle(slotId, text, previousText, outcome, reason) {
 	};
 }
 //#endregion
+//#region src/osd-source-fields.ts
+/** Caps the OSD source picker may bind. */
+var OSD_SOURCE_CAP_NAMES = new Set([
+	"temperature-sensor",
+	"humidity-sensor",
+	"climate-control",
+	"numeric-sensor",
+	"weather",
+	"air-quality-sensor",
+	"lock-control",
+	"contact",
+	"binary",
+	"battery"
+]);
+/**
+* Per-cap leaf allowlist. Absent entry ⇒ every leaf from `stateLeavesOf`
+* that survives bookkeeping (single-metric sensors). Present ⇒ only these
+* paths (climate / weather / battery).
+*/
+var OSD_SOURCE_PATHS = new Map([
+	["climate-control", new Set([
+		"currentTemp",
+		"currentHumidity",
+		"target",
+		"targetHumidity",
+		"mode"
+	])],
+	["weather", new Set([
+		"condition",
+		"temperature",
+		"humidity",
+		"pressure",
+		"windSpeed",
+		"windBearing"
+	])],
+	["battery", new Set(["percentage"])],
+	["temperature-sensor", new Set(["celsius"])],
+	["humidity-sensor", new Set(["percent"])],
+	["numeric-sensor", new Set(["value"])],
+	["air-quality-sensor", new Set([
+		"co2Ppm",
+		"vocPpb",
+		"pm25",
+		"pm10",
+		"aqi"
+	])],
+	["binary", new Set(["on"])],
+	["contact", new Set(["entryOpen"])],
+	["lock-control", new Set(["state"])]
+]);
+function isOsdSourceCap(capName) {
+	return OSD_SOURCE_CAP_NAMES.has(capName);
+}
+/** Bindable OSD leaves for one cap — empty when the cap is not OSD-relevant. */
+function osdStateLeavesOf(cap) {
+	if (!isOsdSourceCap(cap.name)) return [];
+	const leaves = stateLeavesOf(cap);
+	const allowed = OSD_SOURCE_PATHS.get(cap.name);
+	if (allowed === void 0) return leaves;
+	return leaves.filter((leaf) => allowed.has(leaf.path));
+}
+/** Device types that never contribute their OWN catalog leaves. */
+var OSD_NON_LEAF_TYPES = new Set(["container"]);
+/** True when this device type may expose OSD leaves (not a container gateway). */
+function isOsdLeafDeviceType(type) {
+	if (type === null || type === void 0) return true;
+	return !OSD_NON_LEAF_TYPES.has(type);
+}
+/** @deprecated Prefer {@link isOsdLeafDeviceType}. */
+var OSD_PICKER_EXCLUDED_TYPES = OSD_NON_LEAF_TYPES;
+/** @deprecated Prefer {@link isOsdLeafDeviceType}. */
+function isOsdPickerDeviceType(type) {
+	return isOsdLeafDeviceType(type);
+}
+function isContainerDeviceType(type) {
+	return type === "container";
+}
+//#endregion
 //#region src/source-catalog.ts
 /**
-* Build the editor's source picker from the CAP DEFINITIONS — never a
-* hand-written list. A cap that ships a new runtime-state field becomes
-* bindable the moment it deploys, with no change here.
+* Build the editor's source picker from OSD-relevant cap definitions.
+* Gateway / infrastructure caps (broker, mqtt, deviceExport, …) never
+* appear — see `osd-source-fields.ts`.
 */
 /** Turn `air-quality-sensor` + `pm25` into `Air Quality Sensor · pm25`. */
 function humanizeCapName(capName) {
 	return capName.split("-").map((part) => part.length === 0 ? part : part[0].toUpperCase() + part.slice(1)).join(" ");
 }
 /**
-* Every bindable value across the cluster, with the camera's own state
-* first — that is what an operator reaches for, and a picker that buries
-* it under 200 other devices is a picker nobody uses.
+* Every OSD-bindable value across the cluster, with the camera's own
+* state first — that is what an operator reaches for, and a picker that
+* buries it under 200 other devices is a picker nobody uses.
 */
 function sourceOptionsFor(cameraDeviceId, devices, capsByDevice) {
 	const capsByName = new Map(ALL_CAPABILITY_DEFINITIONS.map((cap) => [cap.name, cap]));
@@ -58573,18 +58795,22 @@ function sourceOptionsFor(cameraDeviceId, devices, capsByDevice) {
 		return a.id - b.id;
 	});
 	const options = [];
-	for (const device of ordered) for (const capName of capsByDevice.get(device.id) ?? []) {
-		const cap = capsByName.get(capName);
-		if (cap === void 0) continue;
-		for (const leaf of stateLeavesOf(cap)) options.push({
-			deviceId: device.id,
-			deviceName: device.name,
-			capName,
-			valuePath: leaf.path,
-			label: `${humanizeCapName(capName)} · ${leaf.path}`,
-			valueType: leaf.valueType,
-			...leaf.enumValues !== void 0 ? { enumValues: leaf.enumValues } : {}
-		});
+	for (const device of ordered) {
+		if (!isOsdLeafDeviceType(device.type ?? null)) continue;
+		for (const capName of capsByDevice.get(device.id) ?? []) {
+			if (!isOsdSourceCap(capName)) continue;
+			const cap = capsByName.get(capName);
+			if (cap === void 0) continue;
+			for (const leaf of osdStateLeavesOf(cap)) options.push({
+				deviceId: device.id,
+				deviceName: device.name,
+				capName,
+				valuePath: leaf.path,
+				label: `${humanizeCapName(capName)} · ${leaf.path}`,
+				valueType: leaf.valueType,
+				...leaf.enumValues !== void 0 ? { enumValues: leaf.enumValues } : {}
+			});
+		}
 	}
 	return options;
 }
@@ -58980,7 +59206,7 @@ var OsdManager = class {
 		if (stored === void 0) throw new Error(`osd-manager: template "${template.id}" missing after upsert`);
 		this.logger.info("osd-manager: named template upserted", { meta: {
 			templateId: stored.id,
-			fieldCount: stored.fields.length
+			bindingCount: stored.bindings.length
 		} });
 		return { template: stored };
 	};
@@ -59068,7 +59294,7 @@ var OsdManager = class {
 		const templatesById = /* @__PURE__ */ new Map();
 		for (const named of allTemplates) {
 			templatesById.set(named.id, named);
-			if (templateIds.has(named.id)) for (const field of named.fields) wanted.add(field.deviceId);
+			if (templateIds.has(named.id)) for (const binding of named.bindings) wanted.add(binding.pick.deviceId);
 		}
 		const stateByDevice = /* @__PURE__ */ new Map();
 		const gateState = /* @__PURE__ */ new Map();
@@ -59270,7 +59496,8 @@ var OsdManagerAddon = class extends BaseAddon {
 			listDevices: async () => {
 				return (await ctx.api.deviceManager.listAll.query({ projection: "slim" })).map((d) => ({
 					id: d.id,
-					name: d.name
+					name: d.name,
+					type: d.type ?? null
 				}));
 			},
 			listCameras: async () => {
@@ -59368,28 +59595,94 @@ var OsdManagerAddon = class extends BaseAddon {
 	}
 };
 //#endregion
+//#region src/osd-picker-devices.ts
+/**
+* Devices offered to the OSD DevicePicker — containers INCLUDED so the
+* operator can pick a gateway, then an OSD-supported child.
+*/
+function toOsdPickerDevices(devices) {
+	return devices.map((d) => ({
+		id: d.id,
+		name: d.name,
+		type: d.type ?? null,
+		location: d.location ?? null,
+		parentDeviceId: d.parentDeviceId ?? null
+	}));
+}
+/** Children of a container that have at least one OSD catalog field. */
+function osdSupportedChildrenOf(containerId, devices, deviceIdsWithOsdFields) {
+	return devices.filter((d) => d.parentDeviceId === containerId && isOsdLeafDeviceType(d.type) && deviceIdsWithOsdFields.has(d.id)).toSorted((a, b) => a.name.localeCompare(b.name));
+}
+function deviceById(devices, id) {
+	return devices.find((d) => d.id === id);
+}
+//#endregion
+//#region src/template-id.ts
+/**
+* Named-template ids are system-generated — never an operator text field.
+* Create uses a uuid; the editable surface is the template name.
+*/
+function generateTemplateId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return `tpl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/** Optional slug helper when a stable short id from the name is preferred. */
+function templateIdFromName(name) {
+	const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+	return `${slug.length > 0 ? slug : "template"}-${Date.now().toString(36)}`;
+}
+//#endregion
 exports.DEFAULT_TICK_MS = DEFAULT_TICK_MS;
 exports.EMPTY_BINDINGS = EMPTY_BINDINGS;
 exports.OSD_BINDINGS_KEY = OSD_BINDINGS_KEY;
+exports.OSD_NON_LEAF_TYPES = OSD_NON_LEAF_TYPES;
+exports.OSD_PICKER_EXCLUDED_TYPES = OSD_PICKER_EXCLUDED_TYPES;
+exports.OSD_SOURCE_CAP_NAMES = OSD_SOURCE_CAP_NAMES;
 exports.OSD_SUPPORTED_CONDITIONS = OSD_SUPPORTED_CONDITIONS;
 exports.OsdBindingsStore = OsdBindingsStore;
 exports.OsdDeviceBindingsSchema = OsdDeviceBindingsSchema;
 exports.OsdManager = OsdManager;
 exports.OsdManagerAddon = OsdManagerAddon;
+exports.aliasFullToken = aliasFullToken;
+exports.aliasToken = aliasToken;
 exports.applyTemplate = applyTemplate;
+exports.applyTemplateFormat = applyTemplateFormat;
+exports.applyTemplateTokenKind = applyTemplateTokenKind;
 exports.assertSupportedConditions = assertSupportedConditions;
+exports.bindingInsertChips = bindingInsertChips;
+exports.bindingToken = bindingToken;
+exports.convertForDisplay = convertForDisplay;
 exports.default = OsdManagerAddon;
+exports.deviceById = deviceById;
+exports.dimensionFromSourceUnit = dimensionFromSourceUnit;
 exports.displayValue = displayValue;
 exports.evaluateGate = evaluateGate;
+exports.expandBindingTokens = expandBindingTokens;
 exports.formatClock = formatClock;
 exports.formatSlotText = formatSlotText;
+exports.generateTemplateId = generateTemplateId;
 exports.humanizeCapName = humanizeCapName;
+exports.inferSourceUnit = inferSourceUnit;
+exports.isContainerDeviceType = isContainerDeviceType;
+exports.isOsdLeafDeviceType = isOsdLeafDeviceType;
+exports.isOsdPickerDeviceType = isOsdPickerDeviceType;
+exports.isOsdSourceCap = isOsdSourceCap;
 exports.limitText = limitText;
+exports.osdStateLeavesOf = osdStateLeavesOf;
+exports.osdSupportedChildrenOf = osdSupportedChildrenOf;
+exports.parseAliasStems = parseAliasStems;
+exports.parseAliasTokens = parseAliasTokens;
 exports.readStatePath = readStatePath;
+exports.renderNamedTemplate = renderNamedTemplate;
 exports.renderSlot = renderSlot;
+exports.replaceToken = replaceToken;
+exports.resolveBindingLive = resolveBindingLive;
 exports.resolveSource = resolveSource;
 exports.sourceOptionsFor = sourceOptionsFor;
 exports.stateLeavesOf = stateLeavesOf;
+exports.suggestAlias = suggestAlias;
+exports.templateIdFromName = templateIdFromName;
+exports.toOsdPickerDevices = toOsdPickerDevices;
 exports.truncateDecimals = truncateDecimals;
 exports.unsupportedConditionKeys = unsupportedConditionKeys;
 exports.withBinding = withBinding;