@couch-kit/client 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @couch-kit/client
 
+## 0.8.0
+
+### Minor Changes
+
+- [#21](https://github.com/faluciano/react-native-couch-kit/pull/21) [`f1e836d`](https://github.com/faluciano/react-native-couch-kit/commit/f1e836d8f17821f0da20db7c3c552552c9b22133) Thanks [@faluciano](https://github.com/faluciano)! - Add `useDebugPanel` hook for capturing debug information (action log, state history, connection status, RTT). Gated behind `debug: true` option.
+
+### Patch Changes
+
+- Updated dependencies [[`f1e836d`](https://github.com/faluciano/react-native-couch-kit/commit/f1e836d8f17821f0da20db7c3c552552c9b22133)]:
+  - @couch-kit/core@0.8.0
+
 ## 0.7.1
 
 ### Patch Changes

package/dist/index.js

@@ -315,9 +315,67 @@ function usePreload(assets, sendMessage) {
   }, [stableAssets]);
   return { loaded, progress, failedAssets };
 }
+// src/debug-panel.ts
+import { useCallback as useCallback3, useEffect as useEffect4, useRef as useRef4, useState as useState4 } from "react";
+function useDebugPanel(options) {
+  const { enabled, state, status, rtt, maxEntries = 50 } = options;
+  const nextIdRef = useRef4(0);
+  const prevStateRef = useRef4(null);
+  const [actionLog, setActionLog] = useState4([]);
+  const [stateHistory, setStateHistory] = useState4([]);
+  const clearHistory = useCallback3(() => {
+    setActionLog([]);
+    setStateHistory([]);
+    nextIdRef.current = 0;
+  }, []);
+  const logAction = useCallback3((action, source = "local") => {
+    if (!enabled)
+      return;
+    setActionLog((prev) => {
+      const entry = {
+        id: nextIdRef.current++,
+        action,
+        timestamp: Date.now(),
+        source
+      };
+      const next = [...prev, entry];
+      return next.length > maxEntries ? next.slice(-maxEntries) : next;
+    });
+  }, [enabled, maxEntries]);
+  useEffect4(() => {
+    if (!enabled || state === null || state === prevStateRef.current)
+      return;
+    prevStateRef.current = state;
+    setStateHistory((prev) => {
+      const entry = {
+        id: nextIdRef.current++,
+        state,
+        timestamp: Date.now()
+      };
+      const next = [...prev, entry];
+      return next.length > maxEntries ? next.slice(-maxEntries) : next;
+    });
+  }, [enabled, state, maxEntries]);
+  useEffect4(() => {
+    if (!enabled) {
+      clearHistory();
+      prevStateRef.current = null;
+    }
+  }, [enabled, clearHistory]);
+  return {
+    enabled,
+    actionLog,
+    stateHistory,
+    connectionStatus: status,
+    rtt: rtt > 0 ? rtt : null,
+    clearHistory,
+    logAction
+  };
+}
 export {
   useServerTime,
   usePreload,
   useGameClient,
+  useDebugPanel,
   calculateTimeSync
 };

package/lib/debug-panel.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A recorded debug action entry.
+ */
+export interface DebugActionEntry {
+    id: number;
+    action: unknown;
+    timestamp: number;
+    source: "local" | "remote";
+}
+/**
+ * A state history entry for debugging.
+ */
+export interface DebugStateEntry<S = unknown> {
+    id: number;
+    state: S;
+    timestamp: number;
+}
+/**
+ * Debug panel data returned by useDebugPanel.
+ */
+export interface DebugPanelData<S = unknown> {
+    /** Whether debug mode is active */
+    enabled: boolean;
+    /** Log of actions (sent and received) */
+    actionLog: DebugActionEntry[];
+    /** History of state changes */
+    stateHistory: DebugStateEntry<S>[];
+    /** Current connection status */
+    connectionStatus: string;
+    /** Current round-trip time in ms */
+    rtt: number | null;
+    /** Clear all debug history */
+    clearHistory: () => void;
+    /** Manually log an action (e.g., from sendAction wrapper) */
+    logAction: (action: unknown, source?: "local" | "remote") => void;
+}
+export interface UseDebugPanelOptions<S = unknown> {
+    /** Whether debug capture is active */
+    enabled: boolean;
+    /** Current game state from useGameClient */
+    state: S | null;
+    /** Connection status from useGameClient */
+    status: string;
+    /** RTT from useGameClient */
+    rtt: number;
+    /** Maximum number of entries to keep in logs */
+    maxEntries?: number;
+}
+/**
+ * Hook that provides debug panel data for development.
+ * Tracks state changes, connection status, and action history.
+ * Designed to be consumed by DebugOverlay or custom debug UI.
+ */
+export declare function useDebugPanel<S = unknown>(options: UseDebugPanelOptions<S>): DebugPanelData<S>;
+//# sourceMappingURL=debug-panel.d.ts.map

package/lib/debug-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-panel.d.ts","sourceRoot":"","sources":["../src/debug-panel.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,+BAA+B;IAC/B,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IACnC,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,oCAAoC;IACpC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,6DAA6D;IAC7D,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,cAAc,CAAC,CAAC,CAAC,CAiEnB"}

package/lib/index.d.ts

@@ -1,4 +1,5 @@
-export * from './client';
-export * from './time-sync';
-export * from './assets';
+export * from "./client";
+export * from "./time-sync";
+export * from "./assets";
+export * from "./debug-panel";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/client",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -47,7 +47,7 @@
     "clean": "rm -rf dist lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.7.0"
+    "@couch-kit/core": "0.8.0"
   },
   "devDependencies": {
     "react": "^18.2.0",

package/src/debug-panel.ts

@@ -0,0 +1,127 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * A recorded debug action entry.
+ */
+export interface DebugActionEntry {
+  id: number;
+  action: unknown;
+  timestamp: number;
+  source: "local" | "remote";
+}
+
+/**
+ * A state history entry for debugging.
+ */
+export interface DebugStateEntry<S = unknown> {
+  id: number;
+  state: S;
+  timestamp: number;
+}
+
+/**
+ * Debug panel data returned by useDebugPanel.
+ */
+export interface DebugPanelData<S = unknown> {
+  /** Whether debug mode is active */
+  enabled: boolean;
+  /** Log of actions (sent and received) */
+  actionLog: DebugActionEntry[];
+  /** History of state changes */
+  stateHistory: DebugStateEntry<S>[];
+  /** Current connection status */
+  connectionStatus: string;
+  /** Current round-trip time in ms */
+  rtt: number | null;
+  /** Clear all debug history */
+  clearHistory: () => void;
+  /** Manually log an action (e.g., from sendAction wrapper) */
+  logAction: (action: unknown, source?: "local" | "remote") => void;
+}
+
+export interface UseDebugPanelOptions<S = unknown> {
+  /** Whether debug capture is active */
+  enabled: boolean;
+  /** Current game state from useGameClient */
+  state: S | null;
+  /** Connection status from useGameClient */
+  status: string;
+  /** RTT from useGameClient */
+  rtt: number;
+  /** Maximum number of entries to keep in logs */
+  maxEntries?: number;
+}
+
+/**
+ * Hook that provides debug panel data for development.
+ * Tracks state changes, connection status, and action history.
+ * Designed to be consumed by DebugOverlay or custom debug UI.
+ */
+export function useDebugPanel<S = unknown>(
+  options: UseDebugPanelOptions<S>,
+): DebugPanelData<S> {
+  const { enabled, state, status, rtt, maxEntries = 50 } = options;
+  const nextIdRef = useRef(0);
+  const prevStateRef = useRef<S | null>(null);
+
+  const [actionLog, setActionLog] = useState<DebugActionEntry[]>([]);
+  const [stateHistory, setStateHistory] = useState<DebugStateEntry<S>[]>([]);
+
+  const clearHistory = useCallback(() => {
+    setActionLog([]);
+    setStateHistory([]);
+    nextIdRef.current = 0;
+  }, []);
+
+  const logAction = useCallback(
+    (action: unknown, source: "local" | "remote" = "local") => {
+      if (!enabled) return;
+
+      setActionLog((prev) => {
+        const entry: DebugActionEntry = {
+          id: nextIdRef.current++,
+          action,
+          timestamp: Date.now(),
+          source,
+        };
+        const next = [...prev, entry];
+        return next.length > maxEntries ? next.slice(-maxEntries) : next;
+      });
+    },
+    [enabled, maxEntries],
+  );
+
+  // Track state changes
+  useEffect(() => {
+    if (!enabled || state === null || state === prevStateRef.current) return;
+    prevStateRef.current = state;
+
+    setStateHistory((prev) => {
+      const entry: DebugStateEntry<S> = {
+        id: nextIdRef.current++,
+        state,
+        timestamp: Date.now(),
+      };
+      const next = [...prev, entry];
+      return next.length > maxEntries ? next.slice(-maxEntries) : next;
+    });
+  }, [enabled, state, maxEntries]);
+
+  // Reset when disabled
+  useEffect(() => {
+    if (!enabled) {
+      clearHistory();
+      prevStateRef.current = null;
+    }
+  }, [enabled, clearHistory]);
+
+  return {
+    enabled,
+    actionLog,
+    stateHistory,
+    connectionStatus: status,
+    rtt: rtt > 0 ? rtt : null,
+    clearHistory,
+    logAction,
+  };
+}

package/src/index.ts

@@ -1,3 +1,4 @@
-export * from './client';
-export * from './time-sync';
-export * from './assets';
+export * from "./client";
+export * from "./time-sync";
+export * from "./assets";
+export * from "./debug-panel";