@camstack/ui-library 0.1.56 → 0.1.58

package/dist/hooks/index.d.ts

@@ -27,3 +27,9 @@ 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 } from '../composites/camera-stream-player';
+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;
@@ -54,15 +55,64 @@ export interface UseDeviceWebrtcTrpc {
             sessionId: string;
             sdpOffer: string;
         }>;
+        /**
+         * Client-offer signaling: the browser builds the SDP offer (advertising
+         * its native decode caps) and the server answers. The dual of
+         * `createSession`; lets iOS pass H.264 High/Main through untouched.
+         */
+        handleOffer: MutateFn<{
+            deviceId: number;
+            target: WebrtcTarget;
+            sdpOffer: string;
+            sessionId?: string;
+        }, {
+            sessionId: string;
+            sdpAnswer: string;
+        }>;
         handleAnswer: MutateFn<{
             deviceId: number;
             sessionId: string;
             sdpAnswer: string;
         }, void>;
+        /** Trickle ICE — push a client candidate to the server. */
+        addIceCandidate: MutateFn<{
+            deviceId: number;
+            sessionId: string;
+            candidate: string;
+            sdpMid?: string | null;
+            sdpMLineIndex?: number | null;
+        }, void>;
+        /** Trickle ICE — poll the server's gathered candidates. */
+        getIceCandidates: QueryFn<{
+            deviceId: number;
+            sessionId: string;
+        }, {
+            candidates: {
+                candidate: string;
+                sdpMid: string | null;
+                sdpMLineIndex: number | null;
+            }[];
+            done: boolean;
+        }>;
         closeSession: MutateFn<{
             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<{
@@ -75,6 +125,16 @@ export interface UseDeviceWebrtcTrpc {
             configuredFps: number;
         } | null>;
     };
+    /** Optional: aggregated STUN/TURN servers (e.g. cloudflare-turn). When
+     *  present, the client uses them so it can gather a reachable relay
+     *  candidate for remote (CGNAT/mobile) viewing. */
+    turnProvider?: {
+        getTurnServers: QueryFn<void, readonly {
+            urls: string | readonly string[];
+            username?: string;
+            credential?: string;
+        }[]>;
+    };
 }
 /** Pipeline detection metrics for a device. */
 export interface DevicePipelineMetrics {
@@ -94,8 +154,45 @@ export interface DeviceWebrtcResult {
     readonly createSession: (target: WebrtcTarget, hints?: ClientStreamHints) => Promise<SignalingResult>;
     /** Server-offer signaling: send the client's SDP answer. */
     readonly sendAnswer: (sessionId: string, sdpAnswer: string) => Promise<void>;
+    /**
+     * Client-offer signaling (preferred for browsers): post a browser-built
+     * SDP offer and get the server's answer. The browser advertises its full
+     * 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, 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
+     * built with TURN BEFORE the offer is created so a remote/CGNAT viewer can
+     * gather a relay candidate. Best-effort — resolves `undefined` on failure
+     * (the player falls back to public STUN).
+     */
+    readonly getIceServers: () => Promise<readonly RTCIceServer[] | undefined>;
+    /** Trickle ICE — push a client-gathered candidate to the server. */
+    readonly addIceCandidate: (sessionId: string, candidate: RTCIceCandidateInit) => Promise<void>;
+    /** Trickle ICE — poll the server's gathered candidates for a session. */
+    readonly getIceCandidates: (sessionId: string) => Promise<{
+        candidates: RTCIceCandidateInit[];
+        done: boolean;
+    }>;
     /** 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>;