@camstack/ui-library 1.2.257 → 1.2.258

package/dist/composites/device-activity-panel.d.ts

@@ -1,33 +1,39 @@
+/**
+* DeviceActivityPanel — unified Logs / Events / State Values viewer.
+*
+* Three internal tabs:
+*  - Logs        → LogStream (scoped to deviceId)
+*  - Events      → EventStream (multiselect of EventCategory + free text)
+*  - State Values → StateValuesStream (DeviceStateChanged subscription)
+*
+* Only the active tab is rendered. tRPC subscriptions in the inactive
+* tabs are torn down because the components are unmounted — keeps the
+* websocket lean even when many devices have a panel open.
+*
+* The panel hosts three live buffers (`logs` / `events` / `state`) and
+* passes them to the streams. Subscriptions still only fire while
+* their stream is mounted, but the entries already received persist
+* across tab switches — so reopening the State tab doesn't reset
+* the visible list to empty just because the global event ring
+* buffer evicted the older state-changed entries.
+*/
+import { type JSX } from "react";
 export interface DeviceActivityPanelProps {
-    readonly deviceId: number;
-    /** When this device is a Container, its own id — the Logs tab then shows the
-     *  whole subtree (container + every child) by filtering `containerDeviceId`
-     *  instead of `deviceId`. Omit/undefined for a non-container. */
-    readonly containerDeviceId?: number;
-    /** Initial event categories the user wants tracked. Defaults to "all". */
-    readonly defaultEventCategories?: readonly string[];
-    /** Initial state-cap whitelist. Empty = show every cap that fires. */
-    readonly defaultStateCaps?: readonly string[];
-    /** Tab to show first. */
-    readonly initialTab?: ActivityTabId;
-    /** CSS class for the panel root. */
-    readonly className?: string;
-    /** Max content height (passed to the active stream). */
-    readonly maxHeight?: string;
+	readonly deviceId: number;
+	/** When this device is a Container, its own id — the Logs tab then shows the
+	*  whole subtree (container + every child) by filtering `containerDeviceId`
+	*  instead of `deviceId`. Omit/undefined for a non-container. */
+	readonly containerDeviceId?: number;
+	/** Initial event categories the user wants tracked. Defaults to "all". */
+	readonly defaultEventCategories?: readonly string[];
+	/** Initial state-cap whitelist. Empty = show every cap that fires. */
+	readonly defaultStateCaps?: readonly string[];
+	/** Tab to show first. */
+	readonly initialTab?: ActivityTabId;
+	/** CSS class for the panel root. */
+	readonly className?: string;
+	/** Max content height (passed to the active stream). */
+	readonly maxHeight?: string;
 }
-declare const TABS: readonly [{
-    readonly id: "logs";
-    readonly label: "Logs";
-    readonly icon: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
-}, {
-    readonly id: "events";
-    readonly label: "Events";
-    readonly icon: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
-}, {
-    readonly id: "state";
-    readonly label: "State";
-    readonly icon: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
-}];
-export type ActivityTabId = (typeof TABS)[number]['id'];
-export declare function DeviceActivityPanel({ deviceId, containerDeviceId, defaultEventCategories, defaultStateCaps, initialTab, className, maxHeight, }: DeviceActivityPanelProps): import("react").JSX.Element;
-export {};
+export type ActivityTabId = "logs" | "events" | "state";
+export declare function DeviceActivityPanel({ deviceId, containerDeviceId, defaultEventCategories, defaultStateCaps, initialTab, className, maxHeight }: DeviceActivityPanelProps): JSX.Element;

package/dist/composites/device-card.d.ts

@@ -1,38 +1,38 @@
-import { ReactNode } from 'react';
+import { type ReactNode, type JSX } from "react";
 export interface DeviceCardBadge {
-    /** Badge label text */
-    label: string;
-    /** Optional icon rendered before the label */
-    icon?: ReactNode;
-    /** Click handler — makes the badge interactive */
-    onClick?: () => void;
+	/** Badge label text */
+	label: string;
+	/** Optional icon rendered before the label */
+	icon?: ReactNode;
+	/** Click handler — makes the badge interactive */
+	onClick?: () => void;
 }
 export interface DeviceCardAction {
-    /** Icon to render */
-    icon: ReactNode;
-    /** Tooltip / aria-label */
-    label: string;
-    /** Click handler */
-    onClick: () => void;
+	/** Icon to render */
+	icon: ReactNode;
+	/** Tooltip / aria-label */
+	label: string;
+	/** Click handler */
+	onClick: () => void;
 }
 export interface DeviceCardProps {
-    /** Primary title (e.g., device name) */
-    title: string;
-    /** Secondary text (e.g., model, IP) */
-    subtitle?: string;
-    /** Status: determines the color of the status dot */
-    status?: 'online' | 'offline' | 'warning' | 'unknown';
-    /** Whether this card is currently selected */
-    selected?: boolean;
-    /** Click handler for the card body */
-    onClick?: () => void;
-    /** Clickable badges (e.g., stream profiles) */
-    badges?: DeviceCardBadge[];
-    /** Action icons shown at the bottom (e.g., PTZ, events) */
-    actions?: DeviceCardAction[];
-    /** Content rendered at the bottom when status is offline (e.g., Connect button) */
-    offlineAction?: ReactNode;
-    /** Additional CSS classes */
-    className?: string;
+	/** Primary title (e.g., device name) */
+	title: string;
+	/** Secondary text (e.g., model, IP) */
+	subtitle?: string;
+	/** Status: determines the color of the status dot */
+	status?: "online" | "offline" | "warning" | "unknown";
+	/** Whether this card is currently selected */
+	selected?: boolean;
+	/** Click handler for the card body */
+	onClick?: () => void;
+	/** Clickable badges (e.g., stream profiles) */
+	badges?: DeviceCardBadge[];
+	/** Action icons shown at the bottom (e.g., PTZ, events) */
+	actions?: DeviceCardAction[];
+	/** Content rendered at the bottom when status is offline (e.g., Connect button) */
+	offlineAction?: ReactNode;
+	/** Additional CSS classes */
+	className?: string;
 }
-export declare function DeviceCard({ title, subtitle, status, selected, onClick, badges, actions, offlineAction, className, }: DeviceCardProps): import("react").JSX.Element;
+export declare function DeviceCard({ title, subtitle, status, selected, onClick, badges, actions, offlineAction, className }: DeviceCardProps): JSX.Element;

package/dist/composites/device-controls/ac-panel.d.ts

@@ -1,3 +1,3 @@
-import { ReactNode } from 'react';
-import { ControlPanelProps } from './types.js';
+import type { ReactNode } from "react";
+import type { ControlPanelProps } from "./types.js";
 export declare function AcPanel({ trpc, deviceId, layout, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/alarm-hero-card.d.ts

@@ -1,47 +1,47 @@
-import { ReactNode } from 'react';
-import { DeviceControlProps } from './control-registry';
+import { type ReactNode } from "react";
+import type { DeviceControlProps } from "./control-registry";
 /**
- * Row-sized alarm control: the shared Disarm + arm-mode segment strip only —
- * no glyph, no state label, no card padding. Cap-gated on `alarm-panel`.
- * Drops into a 200 px control column without towering over sibling rows.
- */
+* Row-sized alarm control: the shared Disarm + arm-mode segment strip only —
+* no glyph, no state label, no card padding. Cap-gated on `alarm-panel`.
+* Drops into a 200 px control column without towering over sibling rows.
+*/
 /**
- * The row/card-sized alarm control — ONE LINE, always.
- *
- * Two earlier attempts were wrong in instructive ways. The first rendered only
- * the segment strip, so the sole sign a panel was armed was which of four
- * buttons happened to be highlighted — and in a grid card the strip overflowed
- * and cut that button off. The second let the strip WRAP, which stopped the
- * overflow by making the row two and three lines tall.
- *
- * A state badge plus four buttons does not fit a phone-width row, and no amount
- * of sizing makes it. So the row shows what a row is for — **the state** — and
- * offers the modes through a select, which is one line at any width. The four
- * segments live in the hero, where there is room for them.
- *
- * A refusal (D630) still has to be visible here, one line or not — it is a
- * small danger badge (icon only, `title` carries the full message, same
- * pattern as `OfflineBadge`) appended after the select. It never grows the
- * row past one line.
- */
+* The row/card-sized alarm control — ONE LINE, always.
+*
+* Two earlier attempts were wrong in instructive ways. The first rendered only
+* the segment strip, so the sole sign a panel was armed was which of four
+* buttons happened to be highlighted — and in a grid card the strip overflowed
+* and cut that button off. The second let the strip WRAP, which stopped the
+* overflow by making the row two and three lines tall.
+*
+* A state badge plus four buttons does not fit a phone-width row, and no amount
+* of sizing makes it. So the row shows what a row is for — **the state** — and
+* offers the modes through a select, which is one line at any width. The four
+* segments live in the hero, where there is room for them.
+*
+* A refusal (D630) still has to be visible here, one line or not — it is a
+* small danger badge (icon only, `title` carries the full message, same
+* pattern as `OfflineBadge`) appended after the select. It never grows the
+* row past one line.
+*/
 export declare function AlarmInlineControl({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;
 /**
- * AlarmHeroCard — segmented arm/disarm hero for AlarmPanel devices.
- *
- * Renders (Spec §3):
- *  - A shield glyph + state label tinted by lifecycle state (disarmed=muted,
- *    armed=green, arming/pending=amber, triggered=red).
- *  - The shared `AlarmSegments` strip: a Disarm button plus one arm button per
- *    `availableModes` entry (Home / Away / Night / …). The currently-active
- *    segment is highlighted; transitioning states highlight none.
- *
- * Cap-gated on `alarm-panel` — returns null when the device lacks the cap.
- * PIN entry (when `requiresCode`) is deferred to a later task; the segments
- * call arm/disarm without a code, and the provider rejects when a code is
- * required — surfaced upstream.
- *
- * A refusal (D630: an open device, a required code, …) is never a swallowed
- * promise — `useAlarmControl` rolls the optimistic state back and hands the
- * rejection's message back as `error`, rendered below the segments.
- */
+* AlarmHeroCard — segmented arm/disarm hero for AlarmPanel devices.
+*
+* Renders (Spec §3):
+*  - A shield glyph + state label tinted by lifecycle state (disarmed=muted,
+*    armed=green, arming/pending=amber, triggered=red).
+*  - The shared `AlarmSegments` strip: a Disarm button plus one arm button per
+*    `availableModes` entry (Home / Away / Night / …). The currently-active
+*    segment is highlighted; transitioning states highlight none.
+*
+* Cap-gated on `alarm-panel` — returns null when the device lacks the cap.
+* PIN entry (when `requiresCode`) is deferred to a later task; the segments
+* call arm/disarm without a code, and the provider rejects when a code is
+* required — surfaced upstream.
+*
+* A refusal (D630: an open device, a required code, …) is never a swallowed
+* promise — `useAlarmControl` rolls the optimistic state back and hands the
+* rejection's message back as `error`, rendered below the segments.
+*/
 export declare function AlarmHeroCard({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/atoms.d.ts

@@ -1,81 +1,81 @@
-import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 export declare const FILL: "fill";
 export declare const RIGHT: "right";
 export declare const CENTER: "center";
 export declare const FIT: "fit";
 export type ControlAlign = typeof FILL | typeof RIGHT | typeof CENTER | typeof FIT;
-interface ControlColumnProps extends ComponentPropsWithoutRef<'div'> {
-    readonly align: ControlAlign;
-    readonly children: ReactNode;
+interface ControlColumnProps extends ComponentPropsWithoutRef<"div"> {
+	readonly align: ControlAlign;
+	readonly children: ReactNode;
 }
 /** The one control column every device-row/hero control sits in.
- *  FILL → the child stretches to the full fixed column width (steppers, selects, buttons, cover triad).
- *  RIGHT → the child keeps its natural width, flush to the right edge of the fixed column (readouts, toggles — card view).
- *  CENTER → the child keeps its natural width, centered in the fixed column (readouts, toggles).
- *  FIT → the column DROPS its fixed width and sizes to its content (table view). The control takes
- *        its natural width and lays out in sequence with the trailing trash + status dot, so a wide
- *        control (climate stepper + mode select, cover triad + %) never overflows a fixed box and
- *        collides with the neighbours. FILL has no effect under FIT — a stretchy child in a
- *        content-width wrapper simply takes its natural width.
- *  FILL, RIGHT and CENTER share the fixed `w-[140px]` box (card / minimal / hero views). */
+*  FILL → the child stretches to the full fixed column width (steppers, selects, buttons, cover triad).
+*  RIGHT → the child keeps its natural width, flush to the right edge of the fixed column (readouts, toggles — card view).
+*  CENTER → the child keeps its natural width, centered in the fixed column (readouts, toggles).
+*  FIT → the column DROPS its fixed width and sizes to its content (table view). The control takes
+*        its natural width and lays out in sequence with the trailing trash + status dot, so a wide
+*        control (climate stepper + mode select, cover triad + %) never overflows a fixed box and
+*        collides with the neighbours. FILL has no effect under FIT — a stretchy child in a
+*        content-width wrapper simply takes its natural width.
+*  FILL, RIGHT and CENTER share the fixed `w-[140px]` box (card / minimal / hero views). */
 export declare function ControlColumn({ align, children, className, ...rest }: ControlColumnProps): ReactNode;
 interface ValueReadoutProps {
-    readonly value: string;
-    readonly unit?: string;
+	readonly value: string;
+	readonly unit?: string;
 }
 /** A value + inline unit suffix (no separator). E.g. `60s`, `22%`. */
 export declare function ValueReadout({ value, unit }: ValueReadoutProps): ReactNode;
 interface StepperProps {
-    readonly value: number | string;
-    readonly unit?: string;
-    readonly onDelta: (d: 1 | -1) => void;
+	readonly value: number | string;
+	readonly unit?: string;
+	readonly onDelta: (d: 1 | -1) => void;
 }
 /** Increment/decrement control with value + unit display. */
 export declare function Stepper({ value, unit, onDelta }: StepperProps): ReactNode;
 interface SlideToggleProps {
-    readonly on: boolean;
-    readonly targetLabel: string;
-    readonly onConfirm: () => void;
+	readonly on: boolean;
+	readonly targetLabel: string;
+	readonly onConfirm: () => void;
 }
 /** Safety slide: onConfirm fires only after the thumb is dragged past threshold, never on a plain tap. */
 export declare function SlideToggle({ on, targetLabel, onConfirm }: SlideToggleProps): ReactNode;
 interface ArcKnobProps {
-    readonly fraction: number;
-    readonly color: string;
-    /**
-     * Distance in px from the rotating container's top edge to the knob's top
-     * edge. The knob is 20px tall, so its CENTER sits at `knobTopPx + 10` px
-     * from the top. For the knob center to ride the ring's centre radius the
-     * caller passes `(containerCenter − ringRadius) − 10`. Defaults to the
-     * thermostat gauge value (176px container, radius 76 → 88 − 76 − 10 = 2).
-     */
-    readonly knobTopPx?: number;
-    /**
-     * When provided, the knob becomes interactive: dragging it reports the new
-     * arc fraction (0..1) to the parent, which owns the value and re-renders the
-     * knob at the new `fraction`. When omitted the knob is a display-only
-     * indicator (no grab cursor, no pointer handlers).
-     */
-    readonly onDragFraction?: (fraction: number) => void;
+	readonly fraction: number;
+	readonly color: string;
+	/**
+	* Distance in px from the rotating container's top edge to the knob's top
+	* edge. The knob is 20px tall, so its CENTER sits at `knobTopPx + 10` px
+	* from the top. For the knob center to ride the ring's centre radius the
+	* caller passes `(containerCenter − ringRadius) − 10`. Defaults to the
+	* thermostat gauge value (176px container, radius 76 → 88 − 76 − 10 = 2).
+	*/
+	readonly knobTopPx?: number;
+	/**
+	* When provided, the knob becomes interactive: dragging it reports the new
+	* arc fraction (0..1) to the parent, which owns the value and re-renders the
+	* knob at the new `fraction`. When omitted the knob is a display-only
+	* indicator (no grab cursor, no pointer handlers).
+	*/
+	readonly onDragFraction?: (fraction: number) => void;
 }
 /** Half the ArcKnob's 20px (h-5) height. Callers seat the knob centre on a
- *  ring by computing `(containerCentre − ringRadius) − KNOB_HALF_PX`. */
+*  ring by computing `(containerCentre − ringRadius) − KNOB_HALF_PX`. */
 export declare const KNOB_HALF_PX = 10;
 /**
- * White knob riding a circular arc at `fraction` (0..1). For thermostat/light/fan.
- *
- * Display-only by default. Pass `onDragFraction` to make the knob draggable:
- * pointer capture is taken on the knob, and pointer moves are mapped to a new
- * arc fraction reported back to the parent (the parent owns the value).
- */
+* White knob riding a circular arc at `fraction` (0..1). For thermostat/light/fan.
+*
+* Display-only by default. Pass `onDragFraction` to make the knob draggable:
+* pointer capture is taken on the knob, and pointer moves are mapped to a new
+* arc fraction reported back to the parent (the parent owns the value).
+*/
 export declare function ArcKnob({ fraction, color, knobTopPx, onDragFraction }: ArcKnobProps): ReactNode;
 interface GripTrackProps {
-    readonly fraction: number;
-    readonly color?: string;
+	readonly fraction: number;
+	readonly color?: string;
 }
 /**
- * Horizontal track with a white grip thumb at `fraction` (0..1). For seek/volume/brightness.
- * @remarks display-only indicator; interactive drag is deferred to a later task.
- */
+* Horizontal track with a white grip thumb at `fraction` (0..1). For seek/volume/brightness.
+* @remarks display-only indicator; interactive drag is deferred to a later task.
+*/
 export declare function GripTrack({ fraction, color }: GripTrackProps): ReactNode;
 export {};

package/dist/composites/device-controls/brightness-panel.d.ts

@@ -1,3 +1,3 @@
-import { ReactNode } from 'react';
-import { ControlPanelProps } from './types';
-export declare function BrightnessPanel({ trpc, deviceId, layout, optimistic, }: ControlPanelProps): ReactNode;
+import type { ReactNode } from "react";
+import type { ControlPanelProps } from "./types";
+export declare function BrightnessPanel({ trpc, deviceId, layout, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/button-control.d.ts

@@ -1,18 +1,18 @@
-import { ReactNode } from 'react';
-import { DeviceControlProps } from './control-registry';
+import type { ReactNode } from "react";
+import type { DeviceControlProps } from "./control-registry";
 /**
- * ButtonControl (inline) — compact "Press" trigger for a device-list row.
- *
- * The `button` cap is fire-only (no status / runtimeState), so we bypass
- * `useDeviceCapability` (which requires a slice) and resolve the cap
- * handle directly from the device proxy. We guard on `cap === undefined`
- * (device has no button cap) and render nothing in that case.
- */
+* ButtonControl (inline) — compact "Press" trigger for a device-list row.
+*
+* The `button` cap is fire-only (no status / runtimeState), so we bypass
+* `useDeviceCapability` (which requires a slice) and resolve the cap
+* handle directly from the device proxy. We guard on `cap === undefined`
+* (device has no button cap) and render nothing in that case.
+*/
 export declare function ButtonControl({ trpc, deviceId }: DeviceControlProps): ReactNode;
 /**
- * ButtonHeroCard — large press-actuator card for the device-detail hero area.
- *
- * Renders a centred "Press" button with real design-token classes. The cap is
- * fire-only so no state display is needed — the affordance IS the control.
- */
+* ButtonHeroCard — large press-actuator card for the device-detail hero area.
+*
+* Renders a centred "Press" button with real design-token classes. The cap is
+* fire-only so no state display is needed — the affordance IS the control.
+*/
 export declare function ButtonHeroCard({ trpc, deviceId }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/climate-panel.d.ts

@@ -1,18 +1,18 @@
-import { ReactNode } from 'react';
-import { ControlPanelProps } from './types.js';
-import { HvacMode } from '@camstack/types';
+import type { ReactNode } from "react";
+import type { ControlPanelProps } from "./types.js";
+import type { HvacMode } from "@camstack/types";
 /**
- * Exhaustive colour map — one entry per HvacMode. Build will fail if a
- * mode is added to the enum and not reflected here (Record<HvacMode, ...>
- * + `satisfies` means TypeScript enforces full coverage).
- */
+* Exhaustive colour map — one entry per HvacMode. Build will fail if a
+* mode is added to the enum and not reflected here (Record<HvacMode, ...>
+* + `satisfies` means TypeScript enforces full coverage).
+*/
 export declare const MODE_COLOR: Record<HvacMode, string>;
 /**
- * Mode text-accent colour — applied to the compact (inline) temperature value
- * as a subtle cue, replacing the old bordered/filled mode box so the control
- * matches the borderless cover/lock inline visual language.
- */
+* Mode text-accent colour — applied to the compact (inline) temperature value
+* as a subtle cue, replacing the old bordered/filled mode box so the control
+* matches the borderless cover/lock inline visual language.
+*/
 export declare const MODE_TEXT_COLOR: Record<HvacMode, string>;
 /** Active-mode button accent colour (applied to the pressed mode chip). */
 export declare const MODE_CHIP_ACTIVE: Record<HvacMode, string>;
-export declare function ClimatePanel({ trpc, deviceId, features: _features, layout, optimistic, }: ControlPanelProps): ReactNode;
+export declare function ClimatePanel({ trpc, deviceId, features: _features, layout, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/container-primary-hero.d.ts

@@ -1,21 +1,38 @@
-import { ReactNode } from 'react';
-import { UseDeviceProxyTrpc } from '../../hooks/use-device-proxy';
-import { ContainerChild } from './container-primary';
+/**
+* <ContainerPrimaryHero> — renders a CONTAINER device's detail hero AS its
+* primary child.
+*
+* The container has no surface of its own: it resolves a primary child
+* (priority default, or the operator's durable primary-child pick) and renders
+* THAT child's `HeroCard` from the shared control registry, bound to the child's
+* numeric id — identical to opening the child device directly.
+*
+* The override is persisted as the chosen child's re-sync/rename-stable
+* `entityId` (`primaryChildEntityId`); resolution matches on it directly — see
+* `container-primary.ts`. A legacy numeric `linkDeviceId` is still honored as a
+* fallback. Other children remain as detail tabs (owned by the device-detail
+* page); this component only owns the hero surface. The "primary child" picker
+* that overrides the resolution lives in the device's primary config block (see
+* admin-ui `PrimaryChildRow`), wired to `deviceManager.setPrimaryChildEntityId`.
+*/
+import type { ReactNode } from "react";
+import type { UseDeviceProxyTrpc } from "../../hooks/use-device-proxy";
+import { type ContainerChild } from "./container-primary";
 /** A child row the hero can render. */
 export interface ContainerHeroChild extends ContainerChild {
-    readonly name: string;
-    readonly features?: readonly string[];
+	readonly name: string;
+	readonly features?: readonly string[];
 }
 export interface ContainerPrimaryHeroProps {
-    readonly trpc: UseDeviceProxyTrpc;
-    /** The container's entity-children (from `deviceManager.getChildren`). */
-    readonly children: readonly ContainerHeroChild[];
-    /** Container's LEGACY persisted primary-child override (numeric child id) —
-     *  consulted only when no durable `primaryChildEntityId` is set. */
-    readonly linkDeviceId: number | null | undefined;
-    /** Container's DURABLE primary-child override (chosen child's entityId) —
-     *  null/undefined ⇒ no durable override (falls back to linkDeviceId, then
-     *  priority default). */
-    readonly primaryChildEntityId?: string | null | undefined;
+	readonly trpc: UseDeviceProxyTrpc;
+	/** The container's entity-children (from `deviceManager.getChildren`). */
+	readonly children: readonly ContainerHeroChild[];
+	/** Container's LEGACY persisted primary-child override (numeric child id) —
+	*  consulted only when no durable `primaryChildEntityId` is set. */
+	readonly linkDeviceId: number | null | undefined;
+	/** Container's DURABLE primary-child override (chosen child's entityId) —
+	*  null/undefined ⇒ no durable override (falls back to linkDeviceId, then
+	*  priority default). */
+	readonly primaryChildEntityId?: string | null | undefined;
 }
-export declare function ContainerPrimaryHero({ trpc, children, linkDeviceId, primaryChildEntityId, }: ContainerPrimaryHeroProps): ReactNode;
+export declare function ContainerPrimaryHero({ trpc, children, linkDeviceId, primaryChildEntityId }: ContainerPrimaryHeroProps): ReactNode;

package/dist/composites/device-controls/container-primary.d.ts

@@ -1,50 +1,79 @@
-import { ChildRef } from './primary-child';
 /**
- * Minimal shape this module needs from a child device row. Structurally
- * compatible with `DeviceItemDevice` / `DeviceInfo` — callers pass the raw
- * `getChildren` rows through.
- */
+* Container → primary-child resolution glue.
+*
+* A CONTAINER device hosts N entity-children and renders AS its primary child
+* (same row InlineControl, same detail HeroCard). The choice of primary child:
+*
+*   - DEFAULT: the highest-priority child by type (lock > climate > light > …),
+*     via the pure {@link resolvePrimaryChild} resolver (Task 4.1).
+*   - OVERRIDE: an operator picks a child via the discreet primary-child picker.
+*     The override is persisted on the container's `linkDeviceId` field (the
+*     real, kernel-backed soft-link — see `device-manager.cap.ts` `setLinkDeviceId`).
+*
+* The source of truth for the override is the child's re-sync-stable `entityId`
+* (its `sourceInfo.id`, falling back to `stableId`).
+*
+* DURABLE (preferred): the container persists the chosen child's `entityId`
+* directly on its `primaryChildEntityId` meta field (see
+* `device-manager.setPrimaryChildEntityId`). This survives a re-sync/rename
+* that reallocates the child's numeric id — the resolver matches on entityId.
+*
+* LEGACY (fallback): older picks persist the numeric child id on `linkDeviceId`.
+* At RENDER we re-derive the entityId from the live child set so a re-sync that
+* KEEPS the numeric id still resolves; when the linked numeric id no longer
+* matches any live child (stale link), we pass `undefined` to the resolver → it
+* falls back to the priority default.
+*
+* Resolution prefers `primaryChildEntityId` and only consults `linkDeviceId`
+* when no durable override is present, so existing persisted links keep working.
+*/
+import type { ChildRef } from "./primary-child";
+/**
+* Minimal shape this module needs from a child device row. Structurally
+* compatible with `DeviceItemDevice` / `DeviceInfo` — callers pass the raw
+* `getChildren` rows through.
+*/
 export interface ContainerChild {
-    readonly id: number;
-    readonly stableId: string;
-    readonly type: string;
-    readonly sourceInfo?: {
-        readonly id: string;
-    } | undefined;
-    /** `DeviceRole`, ranked above `type` when picking a container's primary. */
-    readonly role?: string | null | undefined;
-    /** Operator-facing name — used for the namesake tiebreak. */
-    readonly name?: string | undefined;
+	readonly id: number;
+	readonly stableId: string;
+	readonly type: string;
+	readonly sourceInfo?: {
+		readonly id: string;
+	} | undefined;
+	/** `DeviceRole`, ranked above `type` when picking a container's primary. */
+	readonly role?: string | null | undefined;
+	/** Operator-facing name — used for the namesake tiebreak. */
+	readonly name?: string | undefined;
 }
 /**
- * Re-sync-stable identity of a child. Prefers the upstream-system dispatch key
- * (`sourceInfo.id` — e.g. HA `entity_id`); falls back to `stableId` for
- * providers that never populated SourceInfo. Both survive a re-sync that may
- * reallocate the numeric `id`.
- */
+* Re-sync-stable identity of a child. Prefers the upstream-system dispatch key
+* (`sourceInfo.id` — e.g. HA `entity_id`); falls back to `stableId` for
+* providers that never populated SourceInfo. Both survive a re-sync that may
+* reallocate the numeric `id`.
+*/
 export declare function childEntityId(child: ContainerChild): string;
 /** Project a raw child row onto the pure resolver's {@link ChildRef} shape. */
 export declare function containerChildToRef(child: ContainerChild): ChildRef;
 /**
- * Resolve the entityId override from the container's persisted `linkDeviceId`.
- * Returns the linked child's stable entityId, or `undefined` when there is no
- * link or the link is stale (points to a numeric id no longer present) — in
- * which case the resolver falls back to the priority default.
- */
+* Resolve the entityId override from the container's persisted `linkDeviceId`.
+* Returns the linked child's stable entityId, or `undefined` when there is no
+* link or the link is stale (points to a numeric id no longer present) — in
+* which case the resolver falls back to the priority default.
+*/
 export declare function overrideEntityIdFromLink(children: readonly ContainerChild[], linkDeviceId: number | null | undefined): string | undefined;
 /**
- * Full container → primary-child resolution: project children to refs, resolve
- * the override entityId, and delegate to the pure resolver. Returns `null` for a
- * container with no children (caller degrades gracefully).
- *
- * Override precedence:
- *   1. `primaryChildEntityId` — the DURABLE override (re-sync/rename-stable),
- *      passed straight to the resolver which matches on `entityId`. Wins when a
- *      non-empty string is supplied.
- *   2. `linkDeviceId` — LEGACY numeric override, re-derived to an entityId from
- *      the live child set. Consulted only when there is no durable override.
- *
- * When neither resolves to a live child, the resolver falls back to the
- * priority default.
- */
+* Full container → primary-child resolution: project children to refs, resolve
+* the override entityId, and delegate to the pure resolver. Returns `null` for a
+* container with no children (caller degrades gracefully).
+*
+* Override precedence:
+*   1. `primaryChildEntityId` — the DURABLE override (re-sync/rename-stable),
+*      passed straight to the resolver which matches on `entityId`. Wins when a
+*      non-empty string is supplied.
+*   2. `linkDeviceId` — LEGACY numeric override, re-derived to an entityId from
+*      the live child set. Consulted only when there is no durable override.
+*
+* When neither resolves to a live child, the resolver falls back to the
+* priority default.
+*/
 export declare function resolveContainerPrimary(children: readonly ContainerChild[], linkDeviceId: number | null | undefined, primaryChildEntityId?: string | null | undefined): ChildRef | null;