@camstack/types 1.2.540 → 1.2.542

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +18 -4
  2. package/dist/addon.js +1 -1
  3. package/dist/addon.mjs +1 -1
  4. package/dist/capabilities/cluster-update.cap.d.ts +376 -0
  5. package/dist/capabilities/device-manager.cap.d.ts +103 -0
  6. package/dist/capabilities/device-search.d.ts +168 -0
  7. package/dist/capabilities/hero-layout.cap.d.ts +69 -299
  8. package/dist/capabilities/hub-address.d.ts +10 -0
  9. package/dist/capabilities/index.d.ts +6 -3
  10. package/dist/capabilities/notification-rules.cap.d.ts +115 -1
  11. package/dist/client.d.ts +2 -1
  12. package/dist/client.js +54 -8
  13. package/dist/client.mjs +54 -9
  14. package/dist/device/container-primary-child.d.ts +39 -4
  15. package/dist/device/device-management.d.ts +9 -0
  16. package/dist/device/hero/hero-model.d.ts +57 -553
  17. package/dist/device/hero/hero-row.d.ts +76 -69
  18. package/dist/device/hero/index.d.ts +1 -1
  19. package/dist/device/linked-device-resolve.d.ts +2 -0
  20. package/dist/generated/addon-api.d.ts +43 -0
  21. package/dist/generated/capability-router-map.d.ts +5 -2
  22. package/dist/generated/device-proxy.d.ts +1 -1
  23. package/dist/generated/method-access-map.d.ts +1 -1
  24. package/dist/generated/method-device-selectors.d.ts +2 -2
  25. package/dist/generated/system-proxy.d.ts +3 -1
  26. package/dist/index.d.ts +2 -2
  27. package/dist/index.js +592 -29
  28. package/dist/index.mjs +562 -30
  29. package/dist/notification/degrade-engine.d.ts +7 -1
  30. package/dist/notification/notification-fields.d.ts +20 -2
  31. package/dist/notification/timelapse-rule.d.ts +69 -0
  32. package/dist/{sleep-Dz1P6--1.mjs → sleep-Cw1uUXvl.mjs} +3 -0
  33. package/dist/{sleep-DPMn-Sik.js → sleep-PfAAmxV-.js} +3 -0
  34. package/package.json +1 -1
package/dist/client.mjs CHANGED
@@ -23764,13 +23764,23 @@ var NcRuleTargetSchema = z.object({
23764
23764
  */
23765
23765
  params: z.record(z.string(), z.unknown()).optional()
23766
23766
  });
23767
+ /** Which picture kind one target receives (#487). */
23768
+ var NcTargetAttachmentSchema = z.enum([
23769
+ "none",
23770
+ "image",
23771
+ "clip",
23772
+ "gif"
23773
+ ]);
23767
23774
  var NcTargetOverrideSchema = z.object({
23768
23775
  template: z.object({
23769
23776
  title: z.string().max(500).optional(),
23770
23777
  body: z.string().max(2e3).optional()
23771
23778
  }).optional(),
23772
23779
  schedule: NcScheduleSchema.optional(),
23773
- priority: z.number().int().min(1).max(5).optional()
23780
+ priority: z.number().int().min(1).max(5).optional(),
23781
+ attachment: NcTargetAttachmentSchema.optional(),
23782
+ /** `false` = no buttons for this target; `true` is the same as absent. */
23783
+ actions: z.boolean().optional()
23774
23784
  });
23775
23785
  /** Per-target settings keyed by target id (#487). */
23776
23786
  var NcTargetOverridesSchema = z.record(z.string(), NcTargetOverrideSchema);
@@ -26574,9 +26584,11 @@ function remoteRoleLabel(role, locale) {
26574
26584
  * priority-in-sync.ts` fails the build when either drifts — the comment that
26575
26585
  * used to ask for this could not.
26576
26586
  *
26577
- * The rule has three halves and the ORDER matters: an operator's explicit pick
26578
- * wins outright; else a declaration on the device type
26579
- * ({@link CONTAINER_PRIMARY_CHILD_RULES}); else role, namesake, then type
26587
+ * The rule has four steps and the ORDER matters: an operator's explicit pick
26588
+ * wins outright; else the container's own declaration, an ordered list of
26589
+ * child keys its provider stamped at create
26590
+ * ({@link ContainerPrimaryChildPreference}); else a declaration on the device
26591
+ * type ({@link CONTAINER_PRIMARY_CHILD_RULES}); else role, namesake, then type
26580
26592
  * priority. The pick is keyed on the child's re-sync-stable `entityId`, not
26581
26593
  * its numeric id, so it survives a re-sync that reallocates ids.
26582
26594
  */
@@ -26589,6 +26601,25 @@ var CONTAINER_PRIMARY_CHILD_RULES = [{
26589
26601
  deviceType: DeviceType.HeatPump,
26590
26602
  primary: "self"
26591
26603
  }];
26604
+ /** The declaration of a container read from its meta, or undefined when it declared none. */
26605
+ function primaryChildPreferenceOf(container) {
26606
+ const keys = container.primaryChildPreference;
26607
+ if (container.stableId === void 0 || keys === void 0 || keys === null) return void 0;
26608
+ if (keys.length === 0) return void 0;
26609
+ return {
26610
+ parentStableId: container.stableId,
26611
+ childKeys: keys
26612
+ };
26613
+ }
26614
+ /** The first declared child that exists, or undefined when none does. */
26615
+ function applyPrimaryChildPreference(preference, children) {
26616
+ if (preference === void 0) return void 0;
26617
+ for (const key of preference.childKeys) {
26618
+ const expected = `${preference.parentStableId}-${key}`;
26619
+ const match = children.find((child) => child.stableId === expected);
26620
+ if (match !== void 0) return match;
26621
+ }
26622
+ }
26592
26623
  /**
26593
26624
  * The type declaration, before the heuristic. `fall-through` means the
26594
26625
  * heuristic still decides: the type declared nothing, or it named a child
@@ -26696,7 +26727,8 @@ function rank(type) {
26696
26727
  }
26697
26728
  /**
26698
26729
  * The child a container stands for: the operator's pick when it still exists,
26699
- * else the device type's declaration, else the highest-priority type. `null`
26730
+ * else the container's declared preference, else the device type's
26731
+ * declaration, else the highest-priority type. `null`
26700
26732
  * for a childless container, and for a type that stands for itself — a caller
26701
26733
  * must decide what "no child" means for it, rather than being handed a child
26702
26734
  * that is not the device.
@@ -26728,11 +26760,13 @@ function sameName(childName, containerName) {
26728
26760
  const flatten = (v) => v.toLowerCase().replace(/[-_\s]+/g, " ").trim();
26729
26761
  return flatten(childName) === flatten(containerName);
26730
26762
  }
26731
- function resolveContainerPrimaryChild(children, overrideEntityId, containerName, containerType) {
26763
+ function resolveContainerPrimaryChild(children, overrideEntityId, containerName, containerType, preference) {
26732
26764
  if (overrideEntityId !== void 0 && overrideEntityId !== null) {
26733
26765
  const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
26734
26766
  if (picked !== void 0) return picked;
26735
26767
  }
26768
+ const preferred = applyPrimaryChildPreference(preference, children);
26769
+ if (preferred !== void 0) return preferred;
26736
26770
  const declared = applyPrimaryChildRule(CONTAINER_PRIMARY_CHILD_RULES.find((entry) => entry.deviceType === containerType), children);
26737
26771
  if (declared.kind === "none") return null;
26738
26772
  if (declared.kind === "child") return declared.child;
@@ -27644,6 +27678,7 @@ function createDeviceProxy(api, binding, opts) {
27644
27678
  setLinkDeviceId: (input) => dispatchSystem("deviceManager", "setLinkDeviceId", "mutation", input),
27645
27679
  setPrimaryChildEntityId: (input) => dispatchSystem("deviceManager", "setPrimaryChildEntityId", "mutation", input),
27646
27680
  setChildLayout: (input) => dispatchSystem("deviceManager", "setChildLayout", "mutation", input),
27681
+ setPrimaryChildPreference: (input) => dispatchSystem("deviceManager", "setPrimaryChildPreference", "mutation", input),
27647
27682
  setDisplay: (input) => dispatchSystem("deviceManager", "setDisplay", "mutation", input),
27648
27683
  getWireableFields: (input) => dispatchSystem("deviceManager", "getWireableFields", "query", input),
27649
27684
  setRole: (input) => dispatchSystem("deviceManager", "setRole", "mutation", input),
@@ -28800,6 +28835,11 @@ function createSystemProxy(api) {
28800
28835
  getPreferences: (input) => dispatch("calendars", "getPreferences", "query", input),
28801
28836
  setCalendarPreference: (input) => dispatch("calendars", "setCalendarPreference", "mutation", input)
28802
28837
  },
28838
+ clusterUpdate: {
28839
+ previewClusterUpdate: (input) => dispatch("clusterUpdate", "previewClusterUpdate", "query", input),
28840
+ startClusterUpdate: (input) => dispatch("clusterUpdate", "startClusterUpdate", "mutation", input),
28841
+ getClusterUpdateJob: (input) => dispatch("clusterUpdate", "getClusterUpdateJob", "query", input)
28842
+ },
28803
28843
  coreBlocks: {
28804
28844
  list: (input) => dispatch("coreBlocks", "list", "query", input),
28805
28845
  get: (input) => dispatch("coreBlocks", "get", "query", input),
@@ -28895,6 +28935,7 @@ function createSystemProxy(api) {
28895
28935
  setLocationZone: (input) => dispatch("deviceManager", "setLocationZone", "mutation", input),
28896
28936
  listPersistedByAddon: (input) => dispatch("deviceManager", "listPersistedByAddon", "query", input),
28897
28937
  listAll: (input) => dispatch("deviceManager", "listAll", "query", input),
28938
+ search: (input) => dispatch("deviceManager", "search", "query", input),
28898
28939
  getChildren: (input) => dispatch("deviceManager", "getChildren", "query", input),
28899
28940
  getChildrenBatch: (input) => dispatch("deviceManager", "getChildrenBatch", "query", input),
28900
28941
  getLinkedDevicesBatch: (input) => dispatch("deviceManager", "getLinkedDevicesBatch", "query", input),
@@ -32965,7 +33006,9 @@ var TimelapseRuleInputSchema = z.object({
32965
33006
  /** Classes the notification counts — see {@link ReportClassesField}. */
32966
33007
  reportClasses: ReportClassesField.optional(),
32967
33008
  /** Canonical notification priority ordinal (1..5); per-target overridable. */
32968
- priority: PriorityField.default(3)
33009
+ priority: PriorityField.default(3),
33010
+ /** Per-target settings keyed by target id (D1032) — absent = every target follows the rule. */
33011
+ targetOverrides: NcTargetOverridesSchema.optional()
32969
33012
  });
32970
33013
  /**
32971
33014
  * The caption a rule that never set one gets.
@@ -32989,7 +33032,9 @@ z.object({
32989
33032
  previewText: PreviewTextField.optional(),
32990
33033
  previewMode: PreviewModeField.optional(),
32991
33034
  reportClasses: ReportClassesField.optional(),
32992
- priority: PriorityField.optional()
33035
+ priority: PriorityField.optional(),
33036
+ /** Per-target settings keyed by target id (D1032) — absent = every target follows the rule. */
33037
+ targetOverrides: NcTargetOverridesSchema.optional()
32993
33038
  });
32994
33039
  /** A persisted timelapse rule. */
32995
33040
  var TimelapseRuleSchema = TimelapseRuleInputSchema.extend({
@@ -33029,4 +33074,4 @@ var TimelapseRuleSchema = TimelapseRuleInputSchema.extend({
33029
33074
  updatedAt: z.number()
33030
33075
  });
33031
33076
  //#endregion
33032
- export { APPLE_SA_TO_MACRO, AUDIO_MACRO_LABELS, AlarmArmModeSchema, CLIP_BROKER_PACED_RATES, COCO_TO_MACRO, CONTAINER_PRIMARY_CHILD_RULES, CamProfileSchema, DEFAULT_TIMELAPSE_PREVIEW_TEXT, DEFINITIVE_DEVICE_REFUSALS, DEVICE_CERT_RENEW_WINDOW_DAYS, DEVICE_CERT_SIGNATURE, DEVICE_DEFINITIVE_REFUSALS_BEFORE_DELETE, DEVICE_REFRESH_REFUSAL_PREFIX, DEVICE_SIGNATURE_MESSAGE_VERSION, DeviceType, EVENTFUL_CAP_NAMES, EVENT_KIND_BY_CAP, EVENT_TAXONOMY, ICON_CATEGORIES, ICON_ENTRIES, ICON_KEYS, ICON_VIEWER_MODULES, IconKeySchema, LOCATION_ICON_FALLBACK, MACRO_LABELS, NC_ALARM_DELAY_MAX_SEC, NC_ALARM_SENSORS_MAX, NC_ALARM_SYSTEM_EVENT_KINDS, NC_ALARM_TRIGGERED_MAX_SEC, NC_BATTERY_CONSUMABLE_SYSTEM_EVENT_KINDS, NC_CAMERA_SCOPE_CAP_NAME, NC_CONSUMABLE_LOW_PERCENT_DEFAULT, NC_CONSUMABLE_LOW_PERCENT_MAX, NC_GROUPING_DEFAULT_SEC, NC_GROUPING_MAX_SEC, NC_GROUPING_MIN_SEC, NC_RULE_EDITOR_SECTION_ORDER, NC_RULE_KIND_SPECS, NC_SENSOR_TRANSITION_UNSUPPORTED_REASON, NC_SYSTEM_EVENT_CLASS_SPECS, NC_SYSTEM_EVENT_FAMILY_FILTERS, NC_SYSTEM_EVENT_KIND_GROUP_SPECS, NC_SYSTEM_EVENT_SUMMARY_FAMILIES, NC_TEMPLATE_HELD_BACK_SYSTEM_EVENT_KINDS, NC_TEMPLATE_VARS, NcAlarmConfigSchema, NcAlarmSensorsSchema, NcAlarmSettingsPatchSchema, NcHistoryEntrySchema, NcRuleLastRunsSchema, NodeDirectorySchema, RECORDING_EXPORT_MAX_READ_BYTES, REMOTE_CUSTOM_ROLE_ICON, REMOTE_ROLE_VOCABULARY, RETRAIN_REVIEW_ADJUSTED_IOU, RETRAIN_REVIEW_MATCH_IOU, RETRAIN_REVIEW_STATUSES, RETRAIN_REVISION_CONFLICT, SystemMirror, TIMELAPSE_DENSE_FLOOR_SEC, TimelapseRuleSchema, YAMNET_TO_MACRO, alarmDeviceBlocksArming, alarmDeviceSecureOnArm, alarmPatchLanded, buildDeviceEnrollmentLink, buildDeviceSignatureMessage, buildSubjectPath, bundledCamstack, canonicalIconKey, classifyRetrainReview, conditionVisibleForKind, createSystemProxy, deviceRefusalFromMessage, droppedConditionsForKind, expandSystemEventClasses, iconCategoryLabel, iconEntry, iconsInCategory, isDefinitiveDeviceRefusal, isDrawableSubjectPath, isHeldBackTemplateVar, isIconKey, isSystemRuleKind, kindsForDiscriminator, knownValues, locationIconKey, nodePickerItems, packagePickerItems, paintHex, paletteResultSchema, parseDeviceEnrollmentLink, parseRetrainRevisionConflict, pickerForCondition, pickerForRuleClasses, projectSubjectPath, remoteRoleIcon, remoteRoleLabel, remoteRoleLegend, resolveContainerPrimaryChild, resolveIconKey, resolveModeDelays, retrainBoxIou, retrainRevisionConflictMessage, ruleDeviceCompatCapNames, ruleEditorSectionsForKind, ruleGroupingApplies, ruleKindOf, ruleKindSpec, ruleSeedForSection, searchIcons, sensorTransitionNeverFires, sensorTransitionOffered, stateLabel, subjectPathSampleFromBox, subjectPathSvgPoints, summarizeReview, systemEventClassKinds, systemEventClassesFor, systemEventDeliveryProblems, systemEventFilterAppliesToAnyKind, systemEventKindsOfFamily, systemFamilyOfKind, templateCarriesSummary, templateVarDeliveryApplies, templateVarKindApplies, templateVarSystemEventApplies, withSystemEventClasses };
33077
+ export { APPLE_SA_TO_MACRO, AUDIO_MACRO_LABELS, AlarmArmModeSchema, CLIP_BROKER_PACED_RATES, COCO_TO_MACRO, CONTAINER_PRIMARY_CHILD_RULES, CamProfileSchema, DEFAULT_TIMELAPSE_PREVIEW_TEXT, DEFINITIVE_DEVICE_REFUSALS, DEVICE_CERT_RENEW_WINDOW_DAYS, DEVICE_CERT_SIGNATURE, DEVICE_DEFINITIVE_REFUSALS_BEFORE_DELETE, DEVICE_REFRESH_REFUSAL_PREFIX, DEVICE_SIGNATURE_MESSAGE_VERSION, DeviceType, EVENTFUL_CAP_NAMES, EVENT_KIND_BY_CAP, EVENT_TAXONOMY, ICON_CATEGORIES, ICON_ENTRIES, ICON_KEYS, ICON_VIEWER_MODULES, IconKeySchema, LOCATION_ICON_FALLBACK, MACRO_LABELS, NC_ALARM_DELAY_MAX_SEC, NC_ALARM_SENSORS_MAX, NC_ALARM_SYSTEM_EVENT_KINDS, NC_ALARM_TRIGGERED_MAX_SEC, NC_BATTERY_CONSUMABLE_SYSTEM_EVENT_KINDS, NC_CAMERA_SCOPE_CAP_NAME, NC_CONSUMABLE_LOW_PERCENT_DEFAULT, NC_CONSUMABLE_LOW_PERCENT_MAX, NC_GROUPING_DEFAULT_SEC, NC_GROUPING_MAX_SEC, NC_GROUPING_MIN_SEC, NC_RULE_EDITOR_SECTION_ORDER, NC_RULE_KIND_SPECS, NC_SENSOR_TRANSITION_UNSUPPORTED_REASON, NC_SYSTEM_EVENT_CLASS_SPECS, NC_SYSTEM_EVENT_FAMILY_FILTERS, NC_SYSTEM_EVENT_KIND_GROUP_SPECS, NC_SYSTEM_EVENT_SUMMARY_FAMILIES, NC_TEMPLATE_HELD_BACK_SYSTEM_EVENT_KINDS, NC_TEMPLATE_VARS, NcAlarmConfigSchema, NcAlarmSensorsSchema, NcAlarmSettingsPatchSchema, NcHistoryEntrySchema, NcRuleLastRunsSchema, NodeDirectorySchema, RECORDING_EXPORT_MAX_READ_BYTES, REMOTE_CUSTOM_ROLE_ICON, REMOTE_ROLE_VOCABULARY, RETRAIN_REVIEW_ADJUSTED_IOU, RETRAIN_REVIEW_MATCH_IOU, RETRAIN_REVIEW_STATUSES, RETRAIN_REVISION_CONFLICT, SystemMirror, TIMELAPSE_DENSE_FLOOR_SEC, TimelapseRuleSchema, YAMNET_TO_MACRO, alarmDeviceBlocksArming, alarmDeviceSecureOnArm, alarmPatchLanded, buildDeviceEnrollmentLink, buildDeviceSignatureMessage, buildSubjectPath, bundledCamstack, canonicalIconKey, classifyRetrainReview, conditionVisibleForKind, createSystemProxy, deviceRefusalFromMessage, droppedConditionsForKind, expandSystemEventClasses, iconCategoryLabel, iconEntry, iconsInCategory, isDefinitiveDeviceRefusal, isDrawableSubjectPath, isHeldBackTemplateVar, isIconKey, isSystemRuleKind, kindsForDiscriminator, knownValues, locationIconKey, nodePickerItems, packagePickerItems, paintHex, paletteResultSchema, parseDeviceEnrollmentLink, parseRetrainRevisionConflict, pickerForCondition, pickerForRuleClasses, primaryChildPreferenceOf, projectSubjectPath, remoteRoleIcon, remoteRoleLabel, remoteRoleLegend, resolveContainerPrimaryChild, resolveIconKey, resolveModeDelays, retrainBoxIou, retrainRevisionConflictMessage, ruleDeviceCompatCapNames, ruleEditorSectionsForKind, ruleGroupingApplies, ruleKindOf, ruleKindSpec, ruleSeedForSection, searchIcons, sensorTransitionNeverFires, sensorTransitionOffered, stateLabel, subjectPathSampleFromBox, subjectPathSvgPoints, summarizeReview, systemEventClassKinds, systemEventClassesFor, systemEventDeliveryProblems, systemEventFilterAppliesToAnyKind, systemEventKindsOfFamily, systemFamilyOfKind, templateCarriesSummary, templateVarDeliveryApplies, templateVarKindApplies, templateVarSystemEventApplies, withSystemEventClasses };
@@ -23,9 +23,11 @@
23
23
  * priority-in-sync.ts` fails the build when either drifts — the comment that
24
24
  * used to ask for this could not.
25
25
  *
26
- * The rule has three halves and the ORDER matters: an operator's explicit pick
27
- * wins outright; else a declaration on the device type
28
- * ({@link CONTAINER_PRIMARY_CHILD_RULES}); else role, namesake, then type
26
+ * The rule has four steps and the ORDER matters: an operator's explicit pick
27
+ * wins outright; else the container's own declaration, an ordered list of
28
+ * child keys its provider stamped at create
29
+ * ({@link ContainerPrimaryChildPreference}); else a declaration on the device
30
+ * type ({@link CONTAINER_PRIMARY_CHILD_RULES}); else role, namesake, then type
29
31
  * priority. The pick is keyed on the child's re-sync-stable `entityId`, not
30
32
  * its numeric id, so it survives a re-sync that reallocates ids.
31
33
  */
@@ -51,6 +53,32 @@ export interface ContainerPrimaryChildRule {
51
53
  * otherwise pick.
52
54
  */
53
55
  export declare const CONTAINER_PRIMARY_CHILD_RULES: readonly ContainerPrimaryChildRule[];
56
+ /**
57
+ * What one CONTAINER declares it stands for, in preference order.
58
+ *
59
+ * A device type cannot tell a vendor's children apart when they all share one
60
+ * type (an energy installation whose PV, battery and house readings are all
61
+ * `sensor` children). The provider knows, so it stamps an ordered list of
62
+ * accessory `childKey`s (the `stableIdSuffix` it spawned each child with) on
63
+ * the container's meta (`DeviceMeta.primaryChildPreference`). The first key
64
+ * whose child exists wins. A child matches when its `stableId` is
65
+ * `${parentStableId}-${childKey}`, the convention `childLayout` uses.
66
+ */
67
+ export interface ContainerPrimaryChildPreference {
68
+ /** The container's own `stableId`. */
69
+ readonly parentStableId: string;
70
+ /** Accessory `childKey`s, most preferred first. */
71
+ readonly childKeys: readonly string[];
72
+ }
73
+ /** The slice of a container's meta its declaration is read from. */
74
+ export interface ContainerPreferenceSource {
75
+ readonly stableId?: string | undefined;
76
+ readonly primaryChildPreference?: readonly string[] | null | undefined;
77
+ }
78
+ /** The declaration of a container read from its meta, or undefined when it declared none. */
79
+ export declare function primaryChildPreferenceOf(container: ContainerPreferenceSource): ContainerPrimaryChildPreference | undefined;
80
+ /** The first declared child that exists, or undefined when none does. */
81
+ export declare function applyPrimaryChildPreference(preference: ContainerPrimaryChildPreference | undefined, children: readonly ContainerChildRef[]): ContainerChildRef | undefined;
54
82
  export type AppliedPrimaryChildRule = {
55
83
  readonly kind: 'fall-through';
56
84
  } | {
@@ -122,4 +150,11 @@ export interface ContainerChildRef {
122
150
  * they are deliberately absent and fall through to type priority.
123
151
  */
124
152
  export declare const CONTAINER_CHILD_ROLE_PRIORITY: readonly string[];
125
- export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined, containerName: string | undefined, containerType: string | undefined): ContainerChildRef | null;
153
+ export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined, containerName: string | undefined, containerType: string | undefined,
154
+ /**
155
+ * The container's own declaration (`primaryChildPreferenceOf(container)`).
156
+ * Required, `undefined` when the container declared none: a caller that
157
+ * forgets it would silently answer the heuristic's child instead of the one
158
+ * the provider named, so the compiler must find every caller.
159
+ */
160
+ preference: ContainerPrimaryChildPreference | undefined): ContainerChildRef | null;
@@ -178,6 +178,12 @@ export interface DeviceMeta {
178
178
  * same lifecycle as `primaryChildEntityId`. Absent ⇒ no layout declared (all
179
179
  * children render in the plain Overview list). */
180
180
  readonly childLayout?: ChildLayout;
181
+ /** Which children a CONTAINER stands for, most preferred first, as accessory
182
+ * `childKey`s (the child's `stableIdSuffix`). Declared by the PROVIDER at
183
+ * create, so the pick does not depend on the order children come back in;
184
+ * the operator's `primaryChildEntityId` still wins. Same create/persist/
185
+ * project/restore lifecycle as `childLayout`. Absent ⇒ no declaration. */
186
+ readonly primaryChildPreference?: readonly string[];
181
187
  /** Operator-authored per-device display override (icon/label/unit/precision/
182
188
  * hidden). Same create/persist/project/restore lifecycle as `childLayout`.
183
189
  * Absent ⇒ no override; the renderer falls back to role default → live slice
@@ -212,6 +218,9 @@ export interface InitialDeviceMeta {
212
218
  * across re-register/restore. Optional: only set for CONTAINER devices that
213
219
  * declare a layout. */
214
220
  readonly childLayout?: ChildLayout;
221
+ /** The children a CONTAINER stands for, most preferred first, by accessory
222
+ * `childKey`. Mirrors `DeviceMeta.primaryChildPreference`. */
223
+ readonly primaryChildPreference?: readonly string[];
215
224
  /** Per-device display override set at create. Mirrors `DeviceMeta.display`. */
216
225
  readonly display?: DeviceDisplayOverride;
217
226
  }