@camstack/ui-library 0.1.57 → 0.2.0

package/dist/hooks/index.d.ts

@@ -8,7 +8,7 @@ export type { UseDeviceAutotrack } from './use-device-autotrack';
 export { useDeviceBattery } from './use-device-battery';
 export type { UseDeviceBatteryTrpc } from './use-device-battery';
 export { useDoorbellEvents } from './use-doorbell-events';
-export type { DoorbellPressEvent, UseDoorbellEventsResult, UseDoorbellEventsOptions } from './use-doorbell-events';
+export type { DoorbellPressEvent, UseDoorbellEventsResult, UseDoorbellEventsOptions, } from './use-doorbell-events';
 export { useClusterNodes } from './use-cluster-nodes';
 export { useDebouncedString } from './use-debounced-string';
 export { useEventStreamLatest, useEventStreamMap } from './use-event-stream';
@@ -20,10 +20,16 @@ export { useDeviceSnapshotImage } from './use-device-snapshot';
 export type { DeviceSnapshotImage } from './use-device-snapshot';
 export type { ClusterNode } from './use-cluster-nodes';
 export type { DeviceDetections, MotionState, MotionZone, MotionRawState, MotionRawBox, DetectionState, } from './use-device-detections';
-export type { DeviceWebrtcResult, UseDeviceWebrtcTrpc, DevicePipelineMetrics } from './use-device-webrtc';
+export type { DeviceWebrtcResult, UseDeviceWebrtcTrpc, DevicePipelineMetrics, WebrtcTarget, SessionRenegotiationState, } from './use-device-webrtc';
 export { useLiveBuffer } from './use-live-buffer';
 export type { LiveBuffer } from './use-live-buffer';
 export { useDevices, useDevice } from './use-devices';
 export { useSystemQuery, useSystemMutation, type SystemQuerySelector, type SystemMutationSelector, } from './use-system-query';
 export { useLiveEvent, type LiveEventCallback } from './use-live-event';
 export { useEventInvalidation } from './use-event-invalidation';
+export { useOptimisticSlice } from './use-optimistic-slice';
+export type { UseOptimisticSliceOptions, UseOptimisticSliceResult } from './use-optimistic-slice';
+export { useDeviceCapSlice } from './use-device-cap-slice';
+export type { UseDeviceCapSliceTrpc } from './use-device-cap-slice';
+export { useDeviceListPageSize, DEVICE_LIST_PAGE_SIZE_OPTIONS, DEVICE_LIST_PAGE_SIZE_KEY, } from './use-device-list-page-size';
+export type { SetDeviceListPageSize } from './use-device-list-page-size';

package/dist/hooks/use-device-cap-slice.d.ts

@@ -0,0 +1,19 @@
+import { SliceHandleApi } from '@camstack/types';
+/**
+ * The tRPC shape required by this hook — a superset of `UseDeviceProxyTrpc`
+ * that also exposes `deviceState.getCapSlice` and `deviceState.setCapSlice`
+ * so the lazy source can bootstrap a per-cap subscription.
+ *
+ * `System.trpcClient` satisfies this structurally.
+ */
+export type UseDeviceCapSliceTrpc = SliceHandleApi;
+/**
+ * Read an arbitrary cap's runtime-state slice by its raw kebab-case name.
+ *
+ * Returns `unknown | undefined`:
+ *  - `undefined` while the slice hasn't been seeded yet (cold-start)
+ *  - the raw slice record once the kernel has published at least one push
+ *
+ * Pass `null` for `deviceId` to suppress all fetches (renders `undefined`).
+ */
+export declare function useDeviceCapSlice(trpc: UseDeviceCapSliceTrpc, deviceId: number | null, capName: string): unknown | undefined;

package/dist/hooks/use-device-capability.d.ts

@@ -13,5 +13,17 @@ export interface UseDeviceCapabilityResult<TCap, TSlice> {
     readonly cap: TCap | undefined;
     readonly slice: TSlice | undefined;
     readonly available: boolean;
+    /**
+     * Resolved device liveness from the auto-registered `device-status`
+     * cap slice. Defaults to `true` until the slice lands so initial load
+     * never false-disables a control. Drives `available` (offline = no
+     * control).
+     */
+    readonly online: boolean;
+    /**
+     * Ms epoch of the last `online` transition when the device is
+     * currently offline, else `null`. Lets a badge render "offline since".
+     */
+    readonly offlineSince: number | null;
 }
 export declare function useDeviceCapability<TCap, TSlice>(options: UseDeviceCapabilityOptions<TCap, TSlice>): UseDeviceCapabilityResult<TCap, TSlice>;

package/dist/hooks/use-device-list-page-size.d.ts

@@ -0,0 +1,14 @@
+/** Selectable per-page sizes. The table default (50) is intentionally one of them. */
+export declare const DEVICE_LIST_PAGE_SIZE_OPTIONS: readonly number[];
+/** Canonical default — used whenever a caller's `defaultSize` is itself invalid. */
+export declare const DEVICE_LIST_PAGE_SIZE_DEFAULT = 50;
+/** Single global key shared across every device-list surface. */
+export declare const DEVICE_LIST_PAGE_SIZE_KEY = "camstack.device-list.pageSize";
+export type SetDeviceListPageSize = (next: number) => void;
+/**
+ * @param defaultSize fallback when nothing valid is stored. If it is not itself
+ *   a member of {@link DEVICE_LIST_PAGE_SIZE_OPTIONS}, it is replaced by
+ *   {@link DEVICE_LIST_PAGE_SIZE_DEFAULT} so it can never seed a phantom value.
+ * @returns `[size, setSize]` — `setSize` ignores values outside the allowed set.
+ */
+export declare function useDeviceListPageSize(defaultSize: number): readonly [number, SetDeviceListPageSize];

package/dist/hooks/use-device-webrtc.d.ts

@@ -1,15 +1,16 @@
+import { CamProfile } from '@camstack/types';
 import { StreamChoice } from '../composites/stream-panel';
 import { ClientStreamHints, SignalingResult, ClientOfferResult } from '../composites/camera-stream-player';
 /**
  * Discriminated WebRTC target — same shape as `WebrtcStreamTarget` on
- * the backend cap. Repeated locally to keep the hook self-contained
- * (no cross-package import from `@camstack/types`).
+ * the backend cap. The `profile` tier uses the canonical `CamProfile`
+ * enum so an invalid tier is a compile error.
  */
 export type WebrtcTarget = {
     readonly kind: 'adaptive';
 } | {
     readonly kind: 'profile';
-    readonly profile: 'high' | 'mid' | 'low';
+    readonly profile: CamProfile;
 } | {
     readonly kind: 'cam-stream';
     readonly camStreamId: string;
@@ -63,6 +64,7 @@ export interface UseDeviceWebrtcTrpc {
             deviceId: number;
             target: WebrtcTarget;
             sdpOffer: string;
+            sessionId?: string;
         }, {
             sessionId: string;
             sdpAnswer: string;
@@ -96,6 +98,21 @@ export interface UseDeviceWebrtcTrpc {
             deviceId: number;
             sessionId: string;
         }, void>;
+        /**
+         * Poll the live signaling state of a session. `pendingRenegotiation`
+         * is non-null after the server swaps the broker source to a different
+         * tier (adaptive downgrade) — the client must re-offer on the same
+         * `sessionId`; `epoch` guards against acting on a stale poll twice.
+         */
+        getSessionState: QueryFn<{
+            deviceId: number;
+            sessionId: string;
+        }, {
+            pendingRenegotiation: {
+                target: WebrtcTarget;
+                epoch: number;
+            } | null;
+        }>;
     };
     pipelineOrchestrator?: {
         getCameraMetrics: QueryFn<{
@@ -143,7 +160,7 @@ export interface DeviceWebrtcResult {
      * H.264 decode caps in the offer, so a Main/High (incl. 4K) source passes
      * through with no transcode — the only path that lets iOS decode High.
      */
-    readonly handleOffer: (target: WebrtcTarget, sdpOffer: string) => Promise<ClientOfferResult>;
+    readonly handleOffer: (target: WebrtcTarget, sdpOffer: string, sessionId?: string) => Promise<ClientOfferResult>;
     /**
      * Fetch the browser-side ICE servers (STUN + TURN from the `turn-provider`
      * cap). Needed for client-offer mode, where the PeerConnection must be
@@ -161,6 +178,21 @@ export interface DeviceWebrtcResult {
     }>;
     /** Close a WebRTC session on the server. */
     readonly closeSession: (sessionId: string) => Promise<void>;
+    /**
+     * Poll the live signaling state of a session. After an adaptive tier
+     * switch the server returns a non-null `pendingRenegotiation` (the new
+     * target + a monotonic `epoch`); the player re-offers on the SAME
+     * `sessionId` so the session re-negotiates against the new tier. Returns
+     * `{ pendingRenegotiation: null }` for non-adaptive / steady sessions.
+     */
+    readonly getSessionState: (sessionId: string) => Promise<SessionRenegotiationState>;
+}
+/** Live signaling state for a session — the adaptive re-offer signal. */
+export interface SessionRenegotiationState {
+    readonly pendingRenegotiation: {
+        readonly target: WebrtcTarget;
+        readonly epoch: number;
+    } | null;
 }
 /**
  * Hook that provides WebRTC signaling callbacks and stream choices for a device.

package/dist/hooks/use-optimistic-slice.d.ts

@@ -0,0 +1,11 @@
+export interface UseOptimisticSliceOptions {
+    readonly enabled?: boolean;
+    readonly timeoutMs?: number;
+}
+export interface UseOptimisticSliceResult<T> {
+    /** The slice to RENDER: the optimistic override if active, else the real slice. */
+    readonly display: T | undefined;
+    /** Apply an optimistic patch (merged onto the current display) after issuing a command. */
+    readonly applyOptimistic: (patch: Partial<T>) => void;
+}
+export declare function useOptimisticSlice<T extends object>(realSlice: T | undefined, opts?: UseOptimisticSliceOptions): UseOptimisticSliceResult<T>;