@skyvexsoftware/stratos-sdk 0.1.1

package/dist/hooks/useSimData.d.ts

@@ -0,0 +1,70 @@
+/**
+ * useSimData — TanStack Query + Socket.io hook for real-time simulator data.
+ *
+ * Hydrates from GET /api/simulator/snapshot on mount, then subscribes to
+ * simulator:data and simulator:status Socket.io events to keep the cache
+ * up-to-date. Multiple consumers share a single query cache entry.
+ *
+ * ## Performance
+ *
+ * Simulator data arrives at ~10–20 Hz via Socket.io. To prevent unnecessary
+ * React renders, incoming data is buffered and flushed to the TanStack Query
+ * cache using `requestAnimationFrame`. This aligns cache updates with the
+ * browser's paint cycle (~60 fps / ~16ms per frame), coalescing multiple
+ * Socket.io events that arrive within a single frame into one cache write.
+ *
+ * Additional optimizations:
+ * - **Structural sharing** (TanStack Query default): prevents re-renders when
+ *   `setQueryData` is called with structurally identical data.
+ * - **`select` parameter**: components can subscribe to a subset of fields
+ *   (e.g. `useSimData({ select: s => s?.data?.altitude })`) and only re-render
+ *   when those specific values change.
+ * - **No polling**: `staleTime: Infinity` with disabled refetch options ensures
+ *   Socket.io pushes are the sole update mechanism after initial REST hydration.
+ *
+ * Target: <16ms per frame for the tracking page render cycle.
+ */
+import type { SimDataSnapshot } from "../shared-types/simulator";
+export declare const simDataKeys: {
+    snapshot: readonly ["simulator", "snapshot"];
+};
+type UseSimDataOptions<TSelected = SimDataSnapshot> = {
+    select?: (snapshot: SimDataSnapshot) => TSelected;
+};
+type UseSimDataReturn<TSelected = SimDataSnapshot> = {
+    data: TSelected;
+    isLoading: boolean;
+};
+/**
+ * Hook for real-time simulator data using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current simulator snapshot via REST.
+ * Then subscribes to Socket.io events and updates the query cache directly,
+ * so multiple components share a single cache entry with TanStack Query deduplication.
+ *
+ * Supports an optional `select` parameter to subscribe to specific fields
+ * and only re-render when those fields change (via TanStack Query structural sharing).
+ *
+ * @example
+ * ```tsx
+ * // Full data (re-renders on any field change)
+ * const { data } = useSimData();
+ *
+ * // Position only (re-renders only when lat/lon/heading change)
+ * const { data: pos } = useSimData({
+ *   select: (s) => ({
+ *     lat: s?.data?.latitude ?? 0,
+ *     lon: s?.data?.longitude ?? 0,
+ *     hdg: s?.data?.heading ?? 0,
+ *   }),
+ * });
+ *
+ * // Single scalar (re-renders only when altitude changes)
+ * const { data: alt } = useSimData({
+ *   select: (s) => s?.data?.altitude ?? 0,
+ * });
+ * ```
+ */
+export declare function useSimData<TSelected = SimDataSnapshot>(options?: UseSimDataOptions<TSelected>): UseSimDataReturn<TSelected>;
+export {};
+//# sourceMappingURL=useSimData.d.ts.map

package/dist/hooks/useSimData.js

@@ -0,0 +1,135 @@
+/**
+ * useSimData — TanStack Query + Socket.io hook for real-time simulator data.
+ *
+ * Hydrates from GET /api/simulator/snapshot on mount, then subscribes to
+ * simulator:data and simulator:status Socket.io events to keep the cache
+ * up-to-date. Multiple consumers share a single query cache entry.
+ *
+ * ## Performance
+ *
+ * Simulator data arrives at ~10–20 Hz via Socket.io. To prevent unnecessary
+ * React renders, incoming data is buffered and flushed to the TanStack Query
+ * cache using `requestAnimationFrame`. This aligns cache updates with the
+ * browser's paint cycle (~60 fps / ~16ms per frame), coalescing multiple
+ * Socket.io events that arrive within a single frame into one cache write.
+ *
+ * Additional optimizations:
+ * - **Structural sharing** (TanStack Query default): prevents re-renders when
+ *   `setQueryData` is called with structurally identical data.
+ * - **`select` parameter**: components can subscribe to a subset of fields
+ *   (e.g. `useSimData({ select: s => s?.data?.altitude })`) and only re-render
+ *   when those specific values change.
+ * - **No polling**: `staleTime: Infinity` with disabled refetch options ensures
+ *   Socket.io pushes are the sole update mechanism after initial REST hydration.
+ *
+ * Target: <16ms per frame for the tracking page render cycle.
+ */
+import { useEffect, useRef } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useSocket } from "./useSimulatorData";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+const SERVER_PORT = 2066;
+const API_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+export const simDataKeys = {
+    snapshot: ["simulator", "snapshot"],
+};
+async function fetchSnapshot() {
+    const response = await fetch(`${API_BASE}/api/simulator/snapshot`, {
+        headers: { Accept: "application/json" },
+    });
+    const json = (await response.json());
+    return json.data;
+}
+/**
+ * Hook for real-time simulator data using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current simulator snapshot via REST.
+ * Then subscribes to Socket.io events and updates the query cache directly,
+ * so multiple components share a single cache entry with TanStack Query deduplication.
+ *
+ * Supports an optional `select` parameter to subscribe to specific fields
+ * and only re-render when those fields change (via TanStack Query structural sharing).
+ *
+ * @example
+ * ```tsx
+ * // Full data (re-renders on any field change)
+ * const { data } = useSimData();
+ *
+ * // Position only (re-renders only when lat/lon/heading change)
+ * const { data: pos } = useSimData({
+ *   select: (s) => ({
+ *     lat: s?.data?.latitude ?? 0,
+ *     lon: s?.data?.longitude ?? 0,
+ *     hdg: s?.data?.heading ?? 0,
+ *   }),
+ * });
+ *
+ * // Single scalar (re-renders only when altitude changes)
+ * const { data: alt } = useSimData({
+ *   select: (s) => s?.data?.altitude ?? 0,
+ * });
+ * ```
+ */
+export function useSimData(options) {
+    const queryClient = useQueryClient();
+    const { socket } = useSocket();
+    const socketRef = useRef(socket);
+    socketRef.current = socket;
+    const { data, isLoading } = useQuery({
+        queryKey: simDataKeys.snapshot,
+        queryFn: fetchSnapshot,
+        select: options?.select,
+        staleTime: Infinity,
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: false,
+    });
+    // Subscribe to Socket.io events and push updates into the query cache.
+    // Uses requestAnimationFrame to batch high-frequency simulator:data updates
+    // (~10–20 Hz) to the browser's paint cycle, preventing unnecessary renders.
+    useEffect(() => {
+        if (!socket)
+            return;
+        // --- RAF-throttled simulator data updates ---
+        let pendingData = null;
+        let rafId = 0;
+        const flushData = () => {
+            rafId = 0;
+            const payload = pendingData;
+            if (!payload)
+                return;
+            pendingData = null;
+            queryClient.setQueryData(simDataKeys.snapshot, (prev) => ({
+                data: payload.data,
+                isConnected: prev?.isConnected ?? true,
+                simulatorType: payload.simulatorType,
+            }));
+        };
+        const handleData = (payload) => {
+            pendingData = payload;
+            if (!rafId) {
+                rafId = requestAnimationFrame(flushData);
+            }
+        };
+        // Status updates are infrequent — apply immediately (no throttle)
+        const handleStatus = (payload) => {
+            queryClient.setQueryData(simDataKeys.snapshot, (prev) => ({
+                data: prev?.data ?? null,
+                isConnected: payload.status === "connected",
+                simulatorType: payload.simulatorType,
+            }));
+        };
+        socket.on(SOCKET_EVENTS.SIMULATOR_DATA, handleData);
+        socket.on(SOCKET_EVENTS.SIMULATOR_STATUS, handleStatus);
+        return () => {
+            if (rafId)
+                cancelAnimationFrame(rafId);
+            socket.off(SOCKET_EVENTS.SIMULATOR_DATA, handleData);
+            socket.off(SOCKET_EVENTS.SIMULATOR_STATUS, handleStatus);
+        };
+    }, [socket, queryClient]);
+    return {
+        data: data,
+        isLoading,
+    };
+}
+//# sourceMappingURL=useSimData.js.map

package/dist/hooks/useSimulatorData.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Socket.io React Hooks for Stratos
+ *
+ * Provides real-time communication with the shell's Express server for:
+ * - Simulator data streaming
+ * - Flight state updates
+ * - Protocol URL events
+ * - Notifications
+ * - System metrics
+ */
+import { Socket } from "socket.io-client";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+import type { ConnectionState, NotificationPayload, ProtocolUrlPayload, SimulatorDataPayload, SimulatorStatusPayload, SystemMetricsPayload } from "../shared-types/socket-events";
+export { SOCKET_EVENTS, type ConnectionState, type NotificationPayload, type ProtocolUrlPayload, type SimulatorDataPayload, type SimulatorStatusPayload, type SystemMetricsPayload, };
+type UseSocketReturn = {
+    socket: Socket | null;
+    isConnected: boolean;
+    connectionState: ConnectionState;
+    clientId: string | null;
+    connect: () => void;
+    disconnect: () => void;
+    subscribe: (eventType: string) => void;
+    unsubscribe: (eventType: string) => void;
+};
+/**
+ * Core Socket.io hook for managing connection.
+ * Uses a singleton socket manager to share connection across all hooks.
+ */
+export declare function useSocket(): UseSocketReturn;
+/**
+ * Hook for simulator data streaming.
+ * Subscribes to real-time flight data and simulator status events.
+ */
+export declare function useSimulatorData(onData?: (payload: SimulatorDataPayload) => void, onStatus?: (payload: SimulatorStatusPayload) => void): {
+    isConnected: boolean;
+    latestData: SimulatorDataPayload | null;
+    simulatorStatus: SimulatorStatusPayload | null;
+};
+/**
+ * Hook for protocol URL events (deep links).
+ */
+export declare function useProtocolUrl(onProtocolUrl?: (payload: ProtocolUrlPayload) => void): ProtocolUrlPayload | null;
+/**
+ * Hook for notifications.
+ */
+export declare function useNotifications(onNotification?: (payload: NotificationPayload) => void): {
+    notifications: NotificationPayload[];
+    clearNotifications: () => void;
+};
+/**
+ * Hook for system metrics streaming.
+ */
+export declare function useSystemMetrics(onMetrics?: (payload: SystemMetricsPayload) => void): {
+    isConnected: boolean;
+    metrics: SystemMetricsPayload | null;
+};
+//# sourceMappingURL=useSimulatorData.d.ts.map

package/dist/hooks/useSimulatorData.js

@@ -0,0 +1,258 @@
+/**
+ * Socket.io React Hooks for Stratos
+ *
+ * Provides real-time communication with the shell's Express server for:
+ * - Simulator data streaming
+ * - Flight state updates
+ * - Protocol URL events
+ * - Notifications
+ * - System metrics
+ */
+import { useEffect, useState, useCallback, useSyncExternalStore } from "react";
+import { io } from "socket.io-client";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+// Re-export canonical types so existing consumers that import from
+// "./useSimulatorData" continue to work without changes.
+export { SOCKET_EVENTS, };
+// Server configuration - matches shell main process
+const SERVER_PORT = 2066;
+const SERVER_URL = `http://127.0.0.1:${SERVER_PORT}`;
+class SocketManager {
+    constructor() {
+        this.socket = null;
+        this.connectionState = "disconnected";
+        this.clientId = null;
+        this.listeners = new Set();
+        this.refCount = 0;
+        this.snapshot = this.createSnapshot();
+    }
+    static getInstance() {
+        if (!SocketManager.instance) {
+            SocketManager.instance = new SocketManager();
+        }
+        return SocketManager.instance;
+    }
+    createSnapshot() {
+        return {
+            socket: this.socket,
+            connectionState: this.connectionState,
+            clientId: this.clientId,
+            isConnected: this.connectionState === "connected",
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        this.refCount++;
+        if (this.refCount === 1) {
+            this.connect();
+        }
+        return () => {
+            this.listeners.delete(listener);
+            this.refCount--;
+            if (this.refCount === 0) {
+                setTimeout(() => {
+                    if (this.refCount === 0) {
+                        this.disconnect();
+                    }
+                }, 1000);
+            }
+        };
+    }
+    notify() {
+        this.snapshot = this.createSnapshot();
+        this.listeners.forEach((listener) => listener());
+    }
+    connect() {
+        if (this.socket)
+            return;
+        this.connectionState = "connecting";
+        this.notify();
+        this.socket = io(SERVER_URL, {
+            transports: ["websocket", "polling"],
+            reconnection: true,
+            reconnectionAttempts: 5,
+            reconnectionDelay: 1000,
+            autoConnect: true,
+        });
+        this.socket.on("connect", () => {
+            this.connectionState = "connected";
+            this.notify();
+        });
+        this.socket.on("connected", (data) => {
+            this.clientId = data.clientId;
+            this.notify();
+        });
+        this.socket.on("disconnect", () => {
+            this.connectionState = "disconnected";
+            this.clientId = null;
+            this.notify();
+        });
+        this.socket.on("connect_error", () => {
+            this.connectionState = "error";
+            this.notify();
+        });
+    }
+    disconnect() {
+        if (this.socket) {
+            this.socket.close();
+            this.socket = null;
+            this.connectionState = "disconnected";
+            this.clientId = null;
+            this.snapshot = this.createSnapshot();
+        }
+    }
+    getSnapshot() {
+        return this.snapshot;
+    }
+    manualConnect() {
+        if (this.socket && !this.socket.connected) {
+            this.connectionState = "connecting";
+            this.notify();
+            this.socket.connect();
+        }
+    }
+    manualDisconnect() {
+        if (this.socket && this.socket.connected) {
+            this.socket.disconnect();
+        }
+    }
+}
+const socketManager = SocketManager.getInstance();
+// ── Hooks ───────────────────────────────────────────────────────────────
+/**
+ * Core Socket.io hook for managing connection.
+ * Uses a singleton socket manager to share connection across all hooks.
+ */
+export function useSocket() {
+    const state = useSyncExternalStore((listener) => socketManager.subscribe(listener), () => socketManager.getSnapshot(), () => socketManager.getSnapshot());
+    const connect = useCallback(() => {
+        socketManager.manualConnect();
+    }, []);
+    const disconnect = useCallback(() => {
+        socketManager.manualDisconnect();
+    }, []);
+    const subscribe = useCallback((eventType) => {
+        const socket = socketManager.getSnapshot().socket;
+        if (socket && socket.connected) {
+            socket.emit("subscribe", eventType);
+        }
+    }, []);
+    const unsubscribe = useCallback((eventType) => {
+        const socket = socketManager.getSnapshot().socket;
+        if (socket && socket.connected) {
+            socket.emit("unsubscribe", eventType);
+        }
+    }, []);
+    return {
+        socket: state.socket,
+        isConnected: state.isConnected,
+        connectionState: state.connectionState,
+        clientId: state.clientId,
+        connect,
+        disconnect,
+        subscribe,
+        unsubscribe,
+    };
+}
+/**
+ * Hook for simulator data streaming.
+ * Subscribes to real-time flight data and simulator status events.
+ */
+export function useSimulatorData(onData, onStatus) {
+    const { socket, isConnected } = useSocket();
+    const [latestData, setLatestData] = useState(null);
+    const [simulatorStatus, setSimulatorStatus] = useState(null);
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleData = (payload) => {
+            setLatestData(payload);
+            onData?.(payload);
+        };
+        const handleStatus = (payload) => {
+            setSimulatorStatus(payload);
+            onStatus?.(payload);
+        };
+        socket.on(SOCKET_EVENTS.SIMULATOR_DATA, handleData);
+        socket.on(SOCKET_EVENTS.SIMULATOR_STATUS, handleStatus);
+        return () => {
+            socket.off(SOCKET_EVENTS.SIMULATOR_DATA, handleData);
+            socket.off(SOCKET_EVENTS.SIMULATOR_STATUS, handleStatus);
+        };
+    }, [socket, onData, onStatus]);
+    return {
+        isConnected,
+        latestData,
+        simulatorStatus,
+    };
+}
+/**
+ * Hook for protocol URL events (deep links).
+ */
+export function useProtocolUrl(onProtocolUrl) {
+    const { socket } = useSocket();
+    const [latestUrl, setLatestUrl] = useState(null);
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleProtocolUrl = (payload) => {
+            setLatestUrl(payload);
+            onProtocolUrl?.(payload);
+        };
+        socket.on(SOCKET_EVENTS.PROTOCOL_URL, handleProtocolUrl);
+        return () => {
+            socket.off(SOCKET_EVENTS.PROTOCOL_URL, handleProtocolUrl);
+        };
+    }, [socket, onProtocolUrl]);
+    return latestUrl;
+}
+/**
+ * Hook for notifications.
+ */
+export function useNotifications(onNotification) {
+    const { socket } = useSocket();
+    const [notifications, setNotifications] = useState([]);
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleNotification = (payload) => {
+            setNotifications((prev) => [...prev, payload]);
+            onNotification?.(payload);
+        };
+        socket.on(SOCKET_EVENTS.NOTIFICATION, handleNotification);
+        return () => {
+            socket.off(SOCKET_EVENTS.NOTIFICATION, handleNotification);
+        };
+    }, [socket, onNotification]);
+    const clearNotifications = useCallback(() => {
+        setNotifications([]);
+    }, []);
+    return {
+        notifications,
+        clearNotifications,
+    };
+}
+/**
+ * Hook for system metrics streaming.
+ */
+export function useSystemMetrics(onMetrics) {
+    const { socket, isConnected } = useSocket();
+    const [metrics, setMetrics] = useState(null);
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleMetrics = (payload) => {
+            setMetrics(payload);
+            onMetrics?.(payload);
+        };
+        socket.on(SOCKET_EVENTS.SYSTEM_METRICS, handleMetrics);
+        return () => {
+            socket.off(SOCKET_EVENTS.SYSTEM_METRICS, handleMetrics);
+        };
+    }, [socket, onMetrics]);
+    return {
+        isConnected,
+        metrics,
+    };
+}
+//# sourceMappingURL=useSimulatorData.js.map

package/dist/hooks/useTrackingSession.d.ts

@@ -0,0 +1,40 @@
+/**
+ * useTrackingSession — Convenience hook that combines flight manager state
+ * with derived tracking metadata (isTracking, isPaused, elapsedTime, phase).
+ *
+ * Hydrates from GET /api/flight-manager/state on mount, then subscribes to
+ * flight:manager Socket.io events for real-time updates.
+ *
+ * Acts as a higher-level wrapper — plugins can still use useFlightManager()
+ * or lower-level hooks (useSimData, useFlightPhase, etc.) for more control.
+ */
+import type { CurrentFlight, FlightPlan, StartFlightResult, RecoverableFlight } from "../shared-types/flight-manager";
+import { FlightPhase } from "../shared-types/simulator";
+export declare const trackingSessionKeys: {
+    state: readonly ["tracking-session", "state"];
+    pendingRecovery: readonly ["tracking-session", "pending-recovery"];
+};
+type UseTrackingSessionReturn = {
+    isTracking: boolean;
+    isPaused: boolean;
+    currentFlight: CurrentFlight | null;
+    pendingRecovery: RecoverableFlight | null;
+    elapsedTime: number;
+    phase: FlightPhase;
+    startFlight: (plan: FlightPlan, options?: {
+        skipPreflightWarnings?: boolean;
+        forceStart?: boolean;
+    }) => Promise<StartFlightResult>;
+    pauseFlight: () => Promise<boolean>;
+    resumeFlight: () => Promise<boolean>;
+    endFlight: (status?: "completed" | "diverted" | "crashed" | "cancelled") => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    recoverFlight: () => Promise<boolean>;
+    dismissRecovery: () => Promise<boolean>;
+    isLoading: boolean;
+};
+export declare function useTrackingSession(): UseTrackingSessionReturn;
+export {};
+//# sourceMappingURL=useTrackingSession.d.ts.map