@camstack/ui-library 1.2.256 → 1.2.258

package/dist/contexts/zone-editing.d.ts

@@ -1,59 +1,82 @@
-import { ReactNode } from 'react';
-export type ZoneDrawingKind = 'polygon' | 'tripwire';
+/**
+* Per-device zone-editing state shared between the player overlay
+* (drawing surface) and any sibling that needs to drive it
+* (Detection tab "Add zone" button, player toolbar Zones toggle, …).
+*
+* Implemented as a React context — kept on its own provider so
+* pages that don't render zones don't pay the extra Render. Wrapped
+* by `PlayerOverlaysProvider` in admin-ui's DeviceDetail.
+*
+* Holds two distinct pieces of state:
+*   - `selectedZoneId` — pure selection, fast CRUD path. Operator
+*     clicks a zone on the canvas or in the list, the row + polygon
+*     light up. No mutation flows from selection alone.
+*   - `editingDraft` — non-null while the operator is in unified
+*     edit mode (entered via the pencil button on the Detection tab
+*     row, exited via Save or Discard). All edits — name, colour,
+*     vertex drags — flow into the draft instead of triggering live
+*     `updateZone` RPC calls. The Detection tab commits on Save with
+*     a single round-trip; Discard throws the draft away. Without
+*     this, every keystroke + vertex drop wrote the zones config and
+*     the pipeline runner detached + re-attached the camera per
+*     write — operators saw 8-character zone renames cycle the
+*     pipeline 8 times.
+*/
+import { type ReactNode, type JSX } from "react";
+export type ZoneDrawingKind = "polygon" | "tripwire";
 export interface ZoneDraftPoint {
-    readonly x: number;
-    readonly y: number;
+	readonly x: number;
+	readonly y: number;
 }
 export interface ZoneDraft {
-    readonly id: string;
-    readonly kind: ZoneDrawingKind;
-    readonly name: string;
-    readonly color: string;
-    readonly points: ReadonlyArray<ZoneDraftPoint>;
+	readonly id: string;
+	readonly kind: ZoneDrawingKind;
+	readonly name: string;
+	readonly color: string;
+	readonly points: ReadonlyArray<ZoneDraftPoint>;
 }
 export interface ZoneEditingState {
-    /** Whether the zone editor overlay is active. When `true` the
-     *  Konva Stage intercepts clicks; when `false` clicks pass
-     *  through to the underlying player. */
-    readonly editing: boolean;
-    /** Active drawing kind. `null` means "select / drag existing
-     *  zones". Setting a non-null value triggers a fresh polygon /
-     *  tripwire creation on the next click. */
-    readonly drawingKind: ZoneDrawingKind | null;
-    /** Currently-selected zone id (for highlight + ZoneForm). */
-    readonly selectedZoneId: string | null;
-    /** In-flight draft snapshot of the zone being edited. `null` while
-     *  no edit session is active — read-only browse mode. */
-    readonly editingDraft: ZoneDraft | null;
+	/** Whether the zone editor overlay is active. When `true` the
+	*  Konva Stage intercepts clicks; when `false` clicks pass
+	*  through to the underlying player. */
+	readonly editing: boolean;
+	/** Active drawing kind. `null` means "select / drag existing
+	*  zones". Setting a non-null value triggers a fresh polygon /
+	*  tripwire creation on the next click. */
+	readonly drawingKind: ZoneDrawingKind | null;
+	/** Currently-selected zone id (for highlight + ZoneForm). */
+	readonly selectedZoneId: string | null;
+	/** In-flight draft snapshot of the zone being edited. `null` while
+	*  no edit session is active — read-only browse mode. */
+	readonly editingDraft: ZoneDraft | null;
 }
 export interface ZoneEditingActions {
-    setEditing(editing: boolean): void;
-    setDrawingKind(kind: ZoneDrawingKind | null): void;
-    setSelectedZoneId(id: string | null): void;
-    /** Start a new polygon/tripwire — convenience for "Add zone"
-     *  buttons that should both unlock the overlay AND select the
-     *  shape kind in one click. */
-    startDrawing(kind: ZoneDrawingKind): void;
-    /** Exit edit mode — clears the drawing kind + selection + any
-     *  in-flight draft. Called when the Detection tab is torn down. */
-    exitEditing(): void;
-    /** Snapshot a zone into the draft and enter unified edit mode.
-     *  If a different draft is already active it is discarded. */
-    enterDraft(draft: ZoneDraft): void;
-    /** Patch the active draft. No-op when no draft is active. */
-    updateDraft(patch: Partial<Omit<ZoneDraft, 'id' | 'kind'>>): void;
-    /** Throw the draft away. Caller is expected to refresh from
-     *  upstream zone state (operator chose Discard or navigated away). */
-    discardDraft(): void;
-}
-interface ZoneEditingContextValue extends ZoneEditingState, ZoneEditingActions {
+	setEditing(editing: boolean): void;
+	setDrawingKind(kind: ZoneDrawingKind | null): void;
+	setSelectedZoneId(id: string | null): void;
+	/** Start a new polygon/tripwire — convenience for "Add zone"
+	*  buttons that should both unlock the overlay AND select the
+	*  shape kind in one click. */
+	startDrawing(kind: ZoneDrawingKind): void;
+	/** Exit edit mode — clears the drawing kind + selection + any
+	*  in-flight draft. Called when the Detection tab is torn down. */
+	exitEditing(): void;
+	/** Snapshot a zone into the draft and enter unified edit mode.
+	*  If a different draft is already active it is discarded. */
+	enterDraft(draft: ZoneDraft): void;
+	/** Patch the active draft. No-op when no draft is active. */
+	updateDraft(patch: Partial<Omit<ZoneDraft, "id" | "kind">>): void;
+	/** Throw the draft away. Caller is expected to refresh from
+	*  upstream zone state (operator chose Discard or navigated away). */
+	discardDraft(): void;
 }
+interface ZoneEditingContextValue extends ZoneEditingState, ZoneEditingActions {}
 export interface ZoneEditingProviderProps {
-    readonly children: ReactNode;
+	readonly children: ReactNode;
 }
-export declare function ZoneEditingProvider({ children }: ZoneEditingProviderProps): import("react").JSX.Element;
+export declare function ZoneEditingProvider({ children }: ZoneEditingProviderProps): JSX.Element;
 /** Read + drive the zone-editing state. Returns `null` outside a
- *  provider so callers that mount in pages without zones (e.g. a
- *  shared hero on a non-camera device) can no-op gracefully. */
+*  provider so callers that mount in pages without zones (e.g. a
+*  shared hero on a non-camera device) can no-op gracefully. */
 export declare function useZoneEditing(): ZoneEditingContextValue | null;
 export {};

package/dist/generated/system-hooks.d.ts

@@ -1,4 +1,20 @@
-import { trpc } from '../trpc-react.js';
+/**
+* Per-method React-Query hooks for every `scope: 'system'` capability.
+*
+* Each hook is a thin pass-through to `trpc.<cap>.<method>.useQuery` /
+* `.useMutation` / `.useSubscription` so the typed inference + RQ
+* cache/dedup keep working — the generator only contributes a consistent
+* name and stable export surface so admin-ui pages can write
+* `useAddonsList()` instead of `trpc.addons.list.useQuery()`.
+*
+* Push-subscription methods (`kind: 'subscription'`) emit a typeof
+* alias over `useSubscription`, so the call shape is
+* `useToastOnToast(input, { onData: cb })` — same as the underlying
+* tRPC hook. The eventBus-backed `useLiveEvent` (see
+* `../hooks/use-live-event.ts`) covers events that don't ride a tRPC
+* subscription; the two surfaces coexist by design.
+*/
+import { trpc } from "../trpc-react.js";
 /** Generated alias around `trpc.accessories.setChildHidden.useMutation`. */
 export declare const useAccessoriesSetChildHidden: typeof trpc.accessories.setChildHidden.useMutation;
 /** Generated alias around `trpc.accessories.getStatus.useQuery`. */

package/dist/hooks/index.d.ts

@@ -1,43 +1,43 @@
-export { useUrlQueryParam } from './use-url-query';
-export type { ClusterNode, ClusterTopologyNode, ClusterTopologyResult, } from './use-cluster-nodes';
-export { useClusterNodes, useClusterTopology } from './use-cluster-nodes';
-export { useDebouncedString } from './use-debounced-string';
-export type { UseDeviceAutotrack } from './use-device-autotrack';
-export { useDeviceAutotrack } from './use-device-autotrack';
-export type { UseDeviceBatteryTrpc } from './use-device-battery';
-export type { NavigationDirection, UseNavigationResult } from './use-navigation';
-export { NAVIGATION_DRIVE_INTERVAL_MS, useNavigation } from './use-navigation';
-export { useDeviceBattery } from './use-device-battery';
-export type { NetworkLinkStatus } from './use-device-network-link';
-export { useDeviceNetworkLink } from './use-device-network-link';
-export type { UseDeviceCapSliceTrpc } from './use-device-cap-slice';
-export { useDeviceCapSlice } from './use-device-cap-slice';
-export type { UseDeviceCapabilityOptions, UseDeviceCapabilityResult, } from './use-device-capability';
-export { useDeviceCapability } from './use-device-capability';
-export type { DetectionState, DeviceDetections, MotionRawBox, MotionRawState, MotionState, MotionZone, } from './use-device-detections';
-export { useDeviceDetections } from './use-device-detections';
-export type { PersistedPageSizeConfig, SetPageSize } from './use-persisted-page-size';
-export { PAGE_SIZE_ALL, effectivePageSize, usePersistedPageSize, } from './use-persisted-page-size';
-export type { SetDeviceListPageSize } from './use-device-list-page-size';
-export { DEVICE_LIST_PAGE_SIZE_KEY, DEVICE_LIST_PAGE_SIZE_OPTIONS, useDeviceListPageSize, } from './use-device-list-page-size';
-export type { UseDeviceProxyTrpc } from './use-device-proxy';
-export { useDeviceProxy, useDeviceState, useDeviceStateSlice } from './use-device-proxy';
-export { useStationaryOverlay, toStationaryOverlayBox } from './use-stationary-overlay';
-export type { DeviceSnapshotImage, UseDeviceSnapshotOptions } from './use-device-snapshot';
-export { SNAPSHOT_MEDIA_PATH, useDeviceSnapshotImage } from './use-device-snapshot';
-export type { DevicePipelineMetrics, DeviceWebrtcResult, SessionRenegotiationState, UseDeviceWebrtcTrpc, WebrtcTarget, } from './use-device-webrtc';
-export { useDeviceWebrtc } from './use-device-webrtc';
-export { useDevice, useDevices } from './use-devices';
-export type { DoorbellPressEvent, UseDoorbellEventsOptions, UseDoorbellEventsResult, } from './use-doorbell-events';
-export { useDoorbellEvents } from './use-doorbell-events';
-export { useEventInvalidation } from './use-event-invalidation';
-export { useEventStreamLatest, useEventStreamMap } from './use-event-stream';
-export { useIsMidWidth, useIsMobile } from './use-is-mobile';
-export type { LiveBuffer } from './use-live-buffer';
-export { useLiveBuffer } from './use-live-buffer';
-export { type LiveEventCallback, useLiveEvent } from './use-live-event';
-export type { UseOptimisticSliceOptions, UseOptimisticSliceResult } from './use-optimistic-slice';
-export { useOptimisticSlice } from './use-optimistic-slice';
-export type { PTZDirection, PTZTrpcProxy, UsePTZOptions, UsePTZResult } from './use-ptz';
-export { usePTZ } from './use-ptz';
-export { type SystemMutationSelector, type SystemQuerySelector, useSystemMutation, useSystemQuery, } from './use-system-query';
+export { useUrlQueryParam } from "./use-url-query";
+export type { ClusterNode, ClusterTopologyNode, ClusterTopologyResult } from "./use-cluster-nodes";
+export { useClusterNodes, useClusterTopology } from "./use-cluster-nodes";
+export { useDebouncedString } from "./use-debounced-string";
+export type { UseDeviceAutotrack } from "./use-device-autotrack";
+export { useDeviceAutotrack } from "./use-device-autotrack";
+export type { UseDeviceBatteryTrpc } from "./use-device-battery";
+export type { NavigationDirection, UseNavigationResult } from "./use-navigation";
+export { NAVIGATION_DRIVE_INTERVAL_MS, useNavigation } from "./use-navigation";
+export { useDeviceBattery } from "./use-device-battery";
+export type { NetworkLinkStatus } from "./use-device-network-link";
+export { useDeviceNetworkLink } from "./use-device-network-link";
+export type { UseDeviceCapSliceTrpc } from "./use-device-cap-slice";
+export { useDeviceCapSlice } from "./use-device-cap-slice";
+export type { UseDeviceCapabilityOptions, UseDeviceCapabilityResult } from "./use-device-capability";
+export { useDeviceCapability } from "./use-device-capability";
+export type { DetectionState, DeviceDetections, MotionRawBox, MotionRawState, MotionState, MotionZone } from "./use-device-detections";
+export { useDeviceDetections } from "./use-device-detections";
+export type { PersistedPageSizeConfig, SetPageSize } from "./use-persisted-page-size";
+export { PAGE_SIZE_ALL, effectivePageSize, usePersistedPageSize } from "./use-persisted-page-size";
+export type { SetDeviceListPageSize } from "./use-device-list-page-size";
+export { DEVICE_LIST_PAGE_SIZE_KEY, DEVICE_LIST_PAGE_SIZE_OPTIONS, useDeviceListPageSize } from "./use-device-list-page-size";
+export type { UseDeviceProxyTrpc } from "./use-device-proxy";
+export { useDeviceProxy, useDeviceState, useDeviceStateSlice } from "./use-device-proxy";
+export { useStationaryOverlay, toStationaryOverlayBox } from "./use-stationary-overlay";
+export type { DeviceSnapshotImage, UseDeviceSnapshotOptions } from "./use-device-snapshot";
+export { SNAPSHOT_MEDIA_PATH, useDeviceSnapshotImage } from "./use-device-snapshot";
+export type { DevicePipelineMetrics, DeviceWebrtcResult, SessionRenegotiationState, UseDeviceWebrtcTrpc, WebrtcTarget } from "./use-device-webrtc";
+export { useDeviceWebrtc } from "./use-device-webrtc";
+export { useDevice, useDevices } from "./use-devices";
+export type { DoorbellPressEvent, UseDoorbellEventsOptions, UseDoorbellEventsResult } from "./use-doorbell-events";
+export { useDoorbellEvents } from "./use-doorbell-events";
+export { useEventInvalidation } from "./use-event-invalidation";
+export { useEventStreamLatest, useEventStreamMap } from "./use-event-stream";
+export { useIsMidWidth, useIsMobile } from "./use-is-mobile";
+export type { LiveBuffer } from "./use-live-buffer";
+export { useLiveBuffer } from "./use-live-buffer";
+export { type LiveEventCallback, useLiveEvent } from "./use-live-event";
+export type { UseOptimisticSliceOptions, UseOptimisticSliceResult } from "./use-optimistic-slice";
+export { useOptimisticSlice } from "./use-optimistic-slice";
+export type { PTZDirection, PTZTrpcProxy, UsePTZOptions, UsePTZResult } from "./use-ptz";
+export { usePTZ } from "./use-ptz";
+export { type SystemMutationSelector, type SystemQuerySelector, useSystemMutation, useSystemQuery } from "./use-system-query";

package/dist/hooks/turn-server-cache.d.ts

@@ -1,77 +1,77 @@
 /**
- * TurnServerCache — shared STUN/TURN credential cache for the WebRTC connect
- * path.
- *
- * ## Why this exists
- *
- * The ICE-server fetch is serialized BEFORE `createOffer` on every connect
- * (`camera-stream-player.tsx` → `getIceServers()`), so its latency lands 1:1
- * in the time-to-first-frame. Production `embed:webrtc-timing` lines measured
- * it at 0.2–3.6 s on a cold page. Two verified defects drove that:
- *
- *  1. **No in-flight coalescing.** The mount-time prefetch and the connect's
- *     own call raced: whichever started second issued a SECOND full
- *     `getTurnServers` round trip instead of awaiting the first.
- *  2. **Per-page cache.** The cache was a `WeakMap` keyed on the page's tRPC
- *     client. The native app loads a fresh embed page per camera open, so the
- *     common remote path started cold every single time.
- *
- * ## Design
- *
- * Three layers, checked in order:
- *  - **memory** (`WeakMap` keyed on the caller's tRPC client — unchanged
- *    semantics: two admin tabs pointed at different hubs never cross-serve),
- *  - **in-flight** (concurrent callers share one promise),
- *  - **storage** (`localStorage` when available) so a fresh page finds warm
- *    credentials. Storage is per-origin, and the page's origin IS the hub, so
- *    cross-hub leakage is structurally impossible.
- *
- * Freshness: entries younger than `freshTtlMs` are served as-is. Entries older
- * than that but younger than `staleCapMs` are served IMMEDIATELY while a
- * background refresh runs (credentials from the hub's providers are valid for
- * hours — e.g. 24 h for the managed-relay provider — so a bounded stale window
- * is safe; an actually-expired relay credential degrades to the public-STUN
- * fallback exactly like an absent one, and the refresh heals the next
- * connect). Beyond `staleCapMs` the fetch is awaited.
- *
- * Failure: a failed fetch serves the stale entry when one exists, else
- * `undefined` (caller falls back to public STUN). Failures are never cached.
- */
+* TurnServerCache — shared STUN/TURN credential cache for the WebRTC connect
+* path.
+*
+* ## Why this exists
+*
+* The ICE-server fetch is serialized BEFORE `createOffer` on every connect
+* (`camera-stream-player.tsx` → `getIceServers()`), so its latency lands 1:1
+* in the time-to-first-frame. Production `embed:webrtc-timing` lines measured
+* it at 0.2–3.6 s on a cold page. Two verified defects drove that:
+*
+*  1. **No in-flight coalescing.** The mount-time prefetch and the connect's
+*     own call raced: whichever started second issued a SECOND full
+*     `getTurnServers` round trip instead of awaiting the first.
+*  2. **Per-page cache.** The cache was a `WeakMap` keyed on the page's tRPC
+*     client. The native app loads a fresh embed page per camera open, so the
+*     common remote path started cold every single time.
+*
+* ## Design
+*
+* Three layers, checked in order:
+*  - **memory** (`WeakMap` keyed on the caller's tRPC client — unchanged
+*    semantics: two admin tabs pointed at different hubs never cross-serve),
+*  - **in-flight** (concurrent callers share one promise),
+*  - **storage** (`localStorage` when available) so a fresh page finds warm
+*    credentials. Storage is per-origin, and the page's origin IS the hub, so
+*    cross-hub leakage is structurally impossible.
+*
+* Freshness: entries younger than `freshTtlMs` are served as-is. Entries older
+* than that but younger than `staleCapMs` are served IMMEDIATELY while a
+* background refresh runs (credentials from the hub's providers are valid for
+* hours — e.g. 24 h for the managed-relay provider — so a bounded stale window
+* is safe; an actually-expired relay credential degrades to the public-STUN
+* fallback exactly like an absent one, and the refresh heals the next
+* connect). Beyond `staleCapMs` the fetch is awaited.
+*
+* Failure: a failed fetch serves the stale entry when one exists, else
+* `undefined` (caller falls back to public STUN). Failures are never cached.
+*/
 /** Narrow storage contract — satisfied by `localStorage`, injectable in tests. */
 export interface TurnCacheStorage {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
+	getItem(key: string): string | null;
+	setItem(key: string, value: string): void;
 }
 export interface TurnServerCacheOptions {
-    /** Entries younger than this are served without any fetch. */
-    readonly freshTtlMs?: number;
-    /** Entries older than `freshTtlMs` but younger than this are served
-     *  immediately while a background refresh runs. */
-    readonly staleCapMs?: number;
-    /** Storage layer. `null` disables persistence (memory-only). When omitted,
-     *  `globalThis.localStorage` is used if present. */
-    readonly storage?: TurnCacheStorage | null;
-    readonly now?: () => number;
-    readonly storageKey?: string;
+	/** Entries younger than this are served without any fetch. */
+	readonly freshTtlMs?: number;
+	/** Entries older than `freshTtlMs` but younger than this are served
+	*  immediately while a background refresh runs. */
+	readonly staleCapMs?: number;
+	/** Storage layer. `null` disables persistence (memory-only). When omitted,
+	*  `globalThis.localStorage` is used if present. */
+	readonly storage?: TurnCacheStorage | null;
+	readonly now?: () => number;
+	readonly storageKey?: string;
 }
 export declare class TurnServerCache {
-    private readonly freshTtlMs;
-    private readonly staleCapMs;
-    private readonly storage;
-    private readonly now;
-    private readonly storageKey;
-    /** Keyed on the caller's tRPC client object (stable per connected system). */
-    private readonly memory;
-    /** In-flight fetch per key — concurrent callers share one round trip. */
-    private readonly inflight;
-    constructor(options?: TurnServerCacheOptions);
-    /**
-     * Resolve the ICE servers for `key`, fetching via `fetch` only when no
-     * fresh-enough entry exists. Never rejects: a failed fetch resolves to the
-     * stale entry when one exists, else `undefined`.
-     */
-    getOrFetch(key: object, fetch: () => Promise<readonly RTCIceServer[]>): Promise<readonly RTCIceServer[] | undefined>;
-    private startFetch;
-    private readStorage;
-    private writeStorage;
+	private readonly freshTtlMs;
+	private readonly staleCapMs;
+	private readonly storage;
+	private readonly now;
+	private readonly storageKey;
+	/** Keyed on the caller's tRPC client object (stable per connected system). */
+	private readonly memory;
+	/** In-flight fetch per key — concurrent callers share one round trip. */
+	private readonly inflight;
+	constructor(options?: TurnServerCacheOptions);
+	/**
+	* Resolve the ICE servers for `key`, fetching via `fetch` only when no
+	* fresh-enough entry exists. Never rejects: a failed fetch resolves to the
+	* stale entry when one exists, else `undefined`.
+	*/
+	getOrFetch(key: object, fetch: () => Promise<readonly RTCIceServer[]>): Promise<readonly RTCIceServer[] | undefined>;
+	private startFetch;
+	private readStorage;
+	private writeStorage;
 }

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

@@ -1,32 +1,69 @@
-import { CapabilityInfo } from '@camstack/types';
 /**
- * What is known about a capability's presence in this cluster.
- *
- * - `pending` — the registry has not answered. Render progress, never absence.
- * - `present` — the registry answered and at least one addon provides it.
- * - `absent`  — the registry answered, and nothing provides it (either the
- *               capability is undeclared, or it is declared with no provider).
- * - `unknown` — the read FAILED. Not an answer, so it is not `absent` either;
- *               a surface that cannot reach the registry says so.
- */
-export type CapabilityPresence = 'pending' | 'present' | 'absent' | 'unknown';
+* "Does this cluster have capability X?" — asked of the authority, answered in
+* a shape that can say *I do not know yet*.
+*
+* WHY THIS EXISTS. A panel that gates on a component being installed has three
+* things to say and a `boolean` can carry two. The missing one is the one an
+* operator sees first: the query has not answered. Collapsing it into `false`
+* makes the UI assert, in words, that a component is NOT INSTALLED — while it
+* is installed and running. That is the failure
+* [D62](../../../../docs/decisions/adr-0062.md) names for a switch ("disabled
+* must never look like broken"); the same rule holds one step earlier:
+* **not-yet-known must never look like not-installed.** An operator who reads
+* "not installed" goes hunting a fault that does not exist.
+*
+* So the answer is a discriminated `CapabilityPresence`, never a boolean, and
+* `'pending'` / `'unknown'` are values a caller has to render — not defaults
+* it falls into.
+*
+* WHY THE REGISTRY AND NOT THE TOPOLOGY. The previous gate read
+* `nodes.topology` and scanned every node's addon list for the capability id.
+* That endpoint's handler walks the whole cluster to build a diagram: a
+* `$agent.status` + `$process.list` round trip per online node, a `ps` sample
+* of every child pid on every node, one durable history-store write per online
+* node, plus the persisted-history read — all sequential. Measured on the
+* production hub (2026-08-31): **32.4 s / 33.9 s / 51.1 s**, 80.7 KB, for a
+* one-bit answer. `capabilities.getCapability` is a `Map.get` on the hub's
+* `CapabilityRegistry` — the same registry every provider registers into via
+* the atomic `registerNode` RPC, so it sees agent-hosted providers too (three
+* node ids on the reference cluster). Measured: **0.15 s**, ~250 bytes, and
+* the cost does not grow with the fleet.
+*
+* WHY NOT A CACHE. [D224](../../../../docs/decisions/adr-0224-the-freshness-of-a-camera-fact-lives-in-its-provider.md)
+* is explicit that a consumer never keeps a second copy of a fact the owner
+* already holds. This hook keeps none: every mount asks the registry, and the
+* registry is the authority. The fix for a slow read was a smaller question,
+* not a local mirror of the big answer.
+*/
+import type { CapabilityInfo } from "@camstack/types";
 /**
- * Classify a settled registry answer.
- *
- * `null` is "no such capability". A row with an empty `providers` list is a
- * capability that is DECLARED but that no addon supplies — indistinguishable
- * to an operator from not having it, and the panel behind it would have
- * nothing to call. Both are `absent`.
- *
- * Exported for the unit test: the mapping is the whole decision, and it is
- * worth pinning without a React tree around it.
- */
-export declare function classifyCapability(row: CapabilityInfo | null): 'present' | 'absent';
+* What is known about a capability's presence in this cluster.
+*
+* - `pending` — the registry has not answered. Render progress, never absence.
+* - `present` — the registry answered and at least one addon provides it.
+* - `absent`  — the registry answered, and nothing provides it (either the
+*               capability is undeclared, or it is declared with no provider).
+* - `unknown` — the read FAILED. Not an answer, so it is not `absent` either;
+*               a surface that cannot reach the registry says so.
+*/
+export type CapabilityPresence = "pending" | "present" | "absent" | "unknown";
 /**
- * Ask the hub's capability registry whether `capabilityName` has a provider.
- *
- * The four states map straight off React Query's `status`, so there is no
- * place for a nullish fallback to turn "no answer" into "no providers" — the
- * exact collapse this hook exists to make unrepresentable.
- */
+* Classify a settled registry answer.
+*
+* `null` is "no such capability". A row with an empty `providers` list is a
+* capability that is DECLARED but that no addon supplies — indistinguishable
+* to an operator from not having it, and the panel behind it would have
+* nothing to call. Both are `absent`.
+*
+* Exported for the unit test: the mapping is the whole decision, and it is
+* worth pinning without a React tree around it.
+*/
+export declare function classifyCapability(row: CapabilityInfo | null): "present" | "absent";
+/**
+* Ask the hub's capability registry whether `capabilityName` has a provider.
+*
+* The four states map straight off React Query's `status`, so there is no
+* place for a nullish fallback to turn "no answer" into "no providers" — the
+* exact collapse this hook exists to make unrepresentable.
+*/
 export declare function useCapabilityPresence(capabilityName: string): CapabilityPresence;

package/dist/hooks/use-cluster-nodes.d.ts

@@ -1,37 +1,64 @@
-import { TopologyNode } from '@camstack/types';
+/**
+* The two hooks through which a UI reads the cluster (D311, D317).
+*
+* `nodes.topology` draws the cluster DIAGRAM: every node, every addon, every
+* runner subprocess with its live cpu/rss. Its handler walks the whole fleet,
+* so its cost scales with nodes x processes — measured on the production hub on
+* 2026-08-31 at **30.5 s** while the settings store was stalled. It is the
+* right call for a page that renders that diagram and the wrong call for
+* everything else, and until D317 fourteen call sites made it on mount.
+*
+* Both hooks have the same shape and it is the only shape allowed here:
+* **bootstrap once, then live off the pushed snapshot.** The hub's
+* `TopologyEmitterService` recomputes and emits `cluster.topology-snapshot`
+* every 30 s and, debounced 200 ms, on every agent/addon lifecycle edge — so a
+* subscriber that mounts mid-stream gets its FIRST value from the bootstrap
+* query (that is what the query is for) and every value after it from the push.
+* `staleTime: Infinity` is therefore correct rather than lazy: nothing goes
+* stale, because the owner sends the next one.
+*
+* - {@link useClusterTopology} — the whole diagram. Reach for it only if you
+*   render per-node processes, per-addon status or the balancer graph.
+* - {@link useClusterNodes} — the node ROSTER (id, name, online, addon caps),
+*   which is what a picker, a filter or an "is this node up" check needs.
+*
+* `scripts/check-topology-is-a-diagram-not-a-lookup.ts` keeps every other call
+* site out of `nodes.topology`.
+*/
+import type { TopologyNode } from "@camstack/types";
 export interface ClusterNode {
-    readonly id: string;
-    readonly name: string;
-    /** Compact label for pill bars: "HUB" for the hub, agent name for agents. */
-    readonly shortName: string;
-    readonly isHub: boolean;
-    readonly isOnline: boolean;
-    readonly localIps: readonly string[];
-    readonly addons: readonly {
-        readonly addonId: string;
-        readonly capabilities: readonly string[];
-    }[];
+	readonly id: string;
+	readonly name: string;
+	/** Compact label for pill bars: "HUB" for the hub, agent name for agents. */
+	readonly shortName: string;
+	readonly isHub: boolean;
+	readonly isOnline: boolean;
+	readonly localIps: readonly string[];
+	readonly addons: readonly {
+		readonly addonId: string;
+		readonly capabilities: readonly string[];
+	}[];
 }
 /** The row shape `nodes.topology` and `cluster.topology-snapshot` both carry. */
 export type ClusterTopologyNode = TopologyNode;
 export interface ClusterTopologyResult {
-    /** Every node in the cluster, live or persisted-offline. `undefined` until the first answer. */
-    readonly nodes: readonly ClusterTopologyNode[] | undefined;
-    readonly isLoading: boolean;
-    readonly isError: boolean;
+	/** Every node in the cluster, live or persisted-offline. `undefined` until the first answer. */
+	readonly nodes: readonly ClusterTopologyNode[] | undefined;
+	readonly isLoading: boolean;
+	readonly isError: boolean;
 }
 /**
- * The whole cluster diagram: bootstrap query, then the pushed snapshot.
- *
- * The ONLY sanctioned reader of `nodes.topology` in a UI. Use it when the
- * component renders something that genuinely needs the diagram — per-node
- * processes, per-addon health, the balancer graph. If you need a node list,
- * use {@link useClusterNodes} instead; if you need one node's addons, ask
- * `nodes.getNodeAddons`, which is one node and does not walk the fleet.
- */
+* The whole cluster diagram: bootstrap query, then the pushed snapshot.
+*
+* The ONLY sanctioned reader of `nodes.topology` in a UI. Use it when the
+* component renders something that genuinely needs the diagram — per-node
+* processes, per-addon health, the balancer graph. If you need a node list,
+* use {@link useClusterNodes} instead; if you need one node's addons, ask
+* `nodes.getNodeAddons`, which is one node and does not walk the fleet.
+*/
 export declare function useClusterTopology(): ClusterTopologyResult;
 export declare function useClusterNodes(): {
-    readonly nodes: readonly ClusterNode[];
-    readonly isLoading: boolean;
-    readonly isError: boolean;
+	readonly nodes: readonly ClusterNode[];
+	readonly isLoading: boolean;
+	readonly isError: boolean;
 };

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

@@ -1,10 +1,10 @@
-import { PtzAutotrackSettings, PtzAutotrackStatus } from '@camstack/types';
+import type { PtzAutotrackSettings, PtzAutotrackStatus } from "@camstack/types";
 export interface UseDeviceAutotrack {
-    status: PtzAutotrackStatus | null;
-    isLoading: boolean;
-    isPending: boolean;
-    error: string | null;
-    setEnabled: (on: boolean) => Promise<void>;
-    setSettings: (patch: Partial<PtzAutotrackSettings>) => Promise<void>;
+	status: PtzAutotrackStatus | null;
+	isLoading: boolean;
+	isPending: boolean;
+	error: string | null;
+	setEnabled: (on: boolean) => Promise<void>;
+	setSettings: (patch: Partial<PtzAutotrackSettings>) => Promise<void>;
 }
 export declare function useDeviceAutotrack(deviceId: number | null): UseDeviceAutotrack;