@hoox-sh/hoox-tui 0.2.0

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export { useKeyboard, registerGlobalHandler } from "./use-keyboard";
+export type { KeyEvent, UseKeyboardOptions } from "./use-keyboard";
+export { usePolling } from "./use-polling";
+export type { UsePollingOptions } from "./use-polling";
+export { useServiceData } from "./use-service-data";
+export { setRendererRef, getRendererRef } from "./renderer-ref";

package/src/hooks/renderer-ref.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * renderer-ref — Module-level singleton for the CLI renderer.
+ *
+ * Avoids circular imports between main.ts and hooks.
+ */
+import type { CliRenderer } from "@opentui/core";
+
+let _renderer: CliRenderer | null = null;
+
+/** Install (or clear with `null`) the process-wide CLI renderer singleton. */
+export function setRendererRef(renderer: CliRenderer | null): void {
+  _renderer = renderer;
+}
+
+export function getRendererRef(): CliRenderer | null {
+  return _renderer;
+}

package/src/hooks/use-keyboard.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * useKeyboard — Priority-ordered keyboard handler hook.
+ *
+ * Registers a keypress handler with a priority. Higher priority handlers
+ * run first. Cleans up on unmount.
+ *
+ * A **single** renderer keypress subscription is shared by all consumers
+ * (avoids N× handlers each re-dispatching the full list — O(n²) fires).
+ *
+ * Priority convention:
+ *   0   — Modal/dialog (highest)
+ *   10  — View-local shortcuts
+ *   50  — App-global shortcuts
+ *   100 — Default/passthrough
+ */
+import { useEffect, useRef } from "react";
+import { getRendererRef } from "./renderer-ref";
+
+export interface KeyEvent {
+  name: string;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+  meta: boolean;
+  sequence: string;
+}
+
+export interface UseKeyboardOptions {
+  priority?: number;
+  enabled?: boolean;
+}
+
+type KeyHandler = (key: KeyEvent) => void;
+
+interface RegisteredHandler {
+  handler: KeyHandler;
+  priority: number;
+}
+
+const globalHandlers: RegisteredHandler[] = [];
+
+/** One shared keypress subscription for the whole process. */
+let keyInputCleanup: (() => void) | null = null;
+
+function sortHandlers(): void {
+  globalHandlers.sort((a, b) => a.priority - b.priority);
+}
+
+function dispatchKey(key: unknown): void {
+  // Snapshot so unsubscribes during dispatch cannot skip handlers
+  const snapshot = globalHandlers.slice();
+  for (const { handler: h } of snapshot) {
+    h(key as KeyEvent);
+  }
+}
+
+function attachKeyInputIfNeeded(): void {
+  if (keyInputCleanup) return;
+  const renderer = getRendererRef();
+  if (!renderer?.keyInput) return;
+  const off = renderer.keyInput.on("keypress", dispatchKey);
+  keyInputCleanup =
+    typeof off === "function"
+      ? off
+      : () => {
+          // OpenTUI may return void; best-effort detach via off if present
+          try {
+            (
+              renderer.keyInput as { off?: (e: string, fn: unknown) => void }
+            ).off?.("keypress", dispatchKey);
+          } catch {
+            // ignore
+          }
+        };
+}
+
+function detachKeyInputIfIdle(): void {
+  if (globalHandlers.length > 0 || !keyInputCleanup) return;
+  try {
+    keyInputCleanup();
+  } catch {
+    // already torn down
+  }
+  keyInputCleanup = null;
+}
+
+export function registerGlobalHandler(
+  handler: KeyHandler,
+  priority = 50
+): () => void {
+  const entry: RegisteredHandler = { handler, priority };
+  globalHandlers.push(entry);
+  sortHandlers();
+  attachKeyInputIfNeeded();
+  return () => {
+    const idx = globalHandlers.indexOf(entry);
+    if (idx >= 0) globalHandlers.splice(idx, 1);
+    detachKeyInputIfIdle();
+  };
+}
+
+export function useKeyboard(
+  handler: KeyHandler,
+  options: UseKeyboardOptions = {}
+): void {
+  const { priority = 10, enabled = true } = options;
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const wrapped: KeyHandler = (key) => handlerRef.current(key);
+    const entry: RegisteredHandler = { handler: wrapped, priority };
+    globalHandlers.push(entry);
+    sortHandlers();
+    attachKeyInputIfNeeded();
+
+    return () => {
+      const idx = globalHandlers.indexOf(entry);
+      if (idx >= 0) globalHandlers.splice(idx, 1);
+      detachKeyInputIfIdle();
+    };
+  }, [priority, enabled]);
+}

package/src/hooks/use-polling.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * usePolling — Configurable polling with exponential backoff.
+ *
+ * Reads refreshIntervalMs from config store. Doubles interval on failure
+ * (up to 16s max). Resets on success. Pause/resume via enabled toggle.
+ */
+import { useEffect, useRef } from "react";
+import { useConfigStore } from "@hoox-sh/hoox-shared";
+
+export interface UsePollingOptions {
+  callback: () => Promise<void>;
+  enabled?: boolean;
+  immediate?: boolean;
+}
+
+export function usePolling(options: UsePollingOptions): void {
+  const { callback, enabled = true, immediate = true } = options;
+  const intervalMs = useConfigStore((s) => s.refreshIntervalMs);
+  const callbackRef = useRef(callback);
+  const retryCount = useRef(0);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled) {
+      // Reset backoff when disabled so resume starts clean
+      retryCount.current = 0;
+      return;
+    }
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let cancelled = false;
+    const MAX_BACKOFF = 16_000;
+
+    const poll = async () => {
+      if (cancelled) return;
+      try {
+        await callbackRef.current();
+        if (cancelled) return;
+        retryCount.current = 0;
+      } catch {
+        if (cancelled) return;
+        retryCount.current++;
+      }
+      if (cancelled) return;
+      // Read fresh from store on every iteration so config changes take effect
+      const currentInterval = useConfigStore.getState().refreshIntervalMs;
+      const backoff = Math.min(
+        currentInterval * Math.pow(2, retryCount.current),
+        MAX_BACKOFF
+      );
+      timeoutId = setTimeout(poll, backoff);
+    };
+
+    if (immediate) {
+      void poll();
+    } else {
+      const initialInterval = useConfigStore.getState().refreshIntervalMs;
+      timeoutId = setTimeout(() => {
+        void poll();
+      }, initialInterval);
+    }
+
+    return () => {
+      cancelled = true;
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+    };
+  }, [intervalMs, enabled, immediate]);
+}

package/src/hooks/use-service-data.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * useServiceData — Thin typed wrapper over Zustand useServiceStore.
+ *
+ * Usage: useServiceData(s => s.workers)
+ *        useServiceData(s => s.connectionStatus)
+ */
+import { useServiceStore } from "@hoox-sh/hoox-shared";
+
+export function useServiceData<T>(
+  selector: (state: ReturnType<typeof useServiceStore.getState>) => T
+): T {
+  return useServiceStore(selector);
+}

package/src/main.tsx

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** @jsxImportSource @opentui/react */
+/**
+ * HOOX TUI — Terminal Operations Center
+ * Entry point: initializes the OpenTUI CLI renderer and mounts the React root.
+ *
+ * Usage: bun run packages/tui/src/main.ts
+ *        or: HOOX_API_URL=http://localhost:8787 bun run packages/tui/src/main.ts
+ */
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { CrashRecoveryApp } from "./app";
+import {
+  Colors,
+  saveSession,
+  useServiceStore,
+  useUIStore,
+} from "@hoox-sh/hoox-shared";
+import { setRendererRef } from "./hooks";
+import { enableAutoCopyOnSelection } from "./services/clipboard";
+import { ensureTuiStateDir } from "./services/hoox-path-service";
+import { getDevLogPath, isDevLogEnabled, tuiDevLog } from "./services/dev-log";
+import { resolveTuiConnectionEnv } from "./services/tui-connection";
+
+/** CLI `hoox tui --fps N` → env TUI_FPS; clamp to a sane range. */
+function resolveTargetFps(): number {
+  const raw = Number(process.env.TUI_FPS ?? 30);
+  if (!Number.isFinite(raw)) return 30;
+  return Math.min(120, Math.max(5, Math.round(raw)));
+}
+
+/** CLI `hoox tui --no-mouse` → env TUI_MOUSE=0. */
+function resolveUseMouse(): boolean {
+  const v = process.env.TUI_MOUSE;
+  if (v === "0" || v === "false" || v === "off") return false;
+  return true;
+}
+
+const targetFps = resolveTargetFps();
+
+const RENDERER_CONFIG = {
+  screenMode: "alternate-screen" as const,
+  exitOnCtrlC: false,
+  targetFps,
+  maxFps: Math.max(60, targetFps),
+  useMouse: resolveUseMouse(),
+  backgroundColor: Colors.background,
+  useKittyKeyboard: {
+    disambiguate: true,
+    alternateKeys: true,
+    events: true,
+  },
+};
+
+async function main() {
+  // Ensure TUI state directory exists ($HOME/.hoox/.tui-state or fallback)
+  await ensureTuiStateDir();
+
+  const conn = resolveTuiConnectionEnv();
+  await tuiDevLog.info("startup", "TUI process starting", {
+    mode: conn.mode,
+    apiUrl: conn.apiUrl,
+    apiHost: conn.apiHost,
+    hasToken: conn.hasToken,
+    allowCliFallback: conn.allowCliFallback,
+    fps: targetFps,
+    mouse: resolveUseMouse(),
+    debug: isDevLogEnabled(),
+    debugLogPath: isDevLogEnabled() ? getDevLogPath() : undefined,
+    entry: import.meta.path,
+  });
+
+  const renderer = await createCliRenderer(RENDERER_CONFIG);
+
+  // Persist the *current* UI state on teardown — never hard-code dashboard.
+  // (A previous bug always rewrote session.json to dashboard on exit.)
+  renderer.on("destroy", () => {
+    try {
+      const ui = useUIStore.getState();
+      const lastUpdated = useServiceStore.getState().lastUpdated;
+      saveSession(
+        ui.activeView,
+        ui.sidebarExpanded,
+        { cols: 80, rows: 24 },
+        lastUpdated > 0 ? lastUpdated : Date.now()
+      ).catch(() => {
+        // Non-fatal: session save failures are silent
+      });
+    } catch {
+      // Stores unavailable during catastrophic teardown
+    }
+  });
+
+  renderer.on("resize", (_width: unknown, _height: unknown) => {
+    // Layout auto-adjusts via flexbox
+  });
+
+  // Set renderer ref so hooks + components can access it via getRendererRef()
+  setRendererRef(renderer);
+
+  // Mouse drag-select → clipboard (OSC 52 + system tools)
+  enableAutoCopyOnSelection(
+    renderer as unknown as import("./services/clipboard").ClipboardRenderer
+  );
+
+  createRoot(renderer).render(<CrashRecoveryApp />);
+  renderer.start();
+}
+
+main().catch((err) => {
+  console.error("Fatal: Failed to start HOOX TUI:", err);
+  process.exit(1);
+});

package/src/network-test-double.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared network-layer test doubles for TUI unit tests.
+ *
+ * Installed once from `test-setup.ts` so `service-store` (and any view that
+ * triggers fetchWorkers / SSE) never hits a real API. Controllable via
+ * exported state + mocks — no per-file mock.module for api-client / sse.
+ */
+import { mock } from "bun:test";
+
+/** Fixture workers returned by the default hooxFetch mock. */
+export let mockApiData: unknown[] = [];
+/** When true, hooxFetch throws. */
+export let mockApiShouldFail = false;
+export let mockApiErrorMessage = "Network error";
+
+/** Per-subscription SSE entry (supports abort removing the callback). */
+export interface SseSubscriptionEntry {
+  path: string;
+  callback: (data: unknown) => void;
+  aborted: boolean;
+  abort: () => void;
+}
+
+/** Active SSE subscriptions registered by subscribeSSE mock. */
+export let sseSubscriptions: SseSubscriptionEntry[] = [];
+
+/** @deprecated Prefer `sseSubscriptions` — flat callback list for emitSseEvent. */
+export let sseCallbacks: Array<(data: unknown) => void> = [];
+
+/** Optional delay (ms) applied before hooxFetch resolves/rejects (race tests). */
+export let mockApiDelayMs = 0;
+
+export const hooxFetchMock = mock(async (_path: string) => {
+  if (mockApiDelayMs > 0) {
+    await new Promise((r) => setTimeout(r, mockApiDelayMs));
+  }
+  if (mockApiShouldFail) {
+    throw new Error(mockApiErrorMessage);
+  }
+  return mockApiData;
+});
+
+function pushSubscription(
+  path: string,
+  callback: (data: unknown) => void
+): { abort: () => void } {
+  const entry: SseSubscriptionEntry = {
+    path,
+    callback,
+    aborted: false,
+    abort: () => {
+      entry.aborted = true;
+      sseSubscriptions = sseSubscriptions.filter((s) => s !== entry);
+      sseCallbacks = sseCallbacks.filter((cb) => cb !== callback);
+    },
+  };
+  sseSubscriptions.push(entry);
+  sseCallbacks.push(callback);
+  return { abort: entry.abort };
+}
+
+export const subscribeSSEMock = mock(
+  async <T>(path: string, callback: (data: T) => void) => {
+    return pushSubscription(path, callback as (data: unknown) => void);
+  }
+);
+
+export function resetNetworkDoubles(): void {
+  mockApiData = [];
+  mockApiShouldFail = false;
+  mockApiErrorMessage = "Network error";
+  mockApiDelayMs = 0;
+  sseSubscriptions = [];
+  sseCallbacks = [];
+  hooxFetchMock.mockClear();
+  subscribeSSEMock.mockClear();
+  hooxFetchMock.mockImplementation(async (_path: string) => {
+    if (mockApiDelayMs > 0) {
+      await new Promise((r) => setTimeout(r, mockApiDelayMs));
+    }
+    if (mockApiShouldFail) {
+      throw new Error(mockApiErrorMessage);
+    }
+    return mockApiData;
+  });
+  subscribeSSEMock.mockImplementation(
+    async <T>(path: string, callback: (data: T) => void) => {
+      return pushSubscription(path, callback as (data: unknown) => void);
+    }
+  );
+}
+
+export function setMockApiData(data: unknown[]): void {
+  mockApiData = data;
+}
+
+export function setMockApiFailure(
+  fail: boolean,
+  message = "Network error"
+): void {
+  mockApiShouldFail = fail;
+  mockApiErrorMessage = message;
+}
+
+/** Set artificial latency for hooxFetch (race / ordering tests). */
+export function setMockApiDelay(ms: number): void {
+  mockApiDelayMs = Math.max(0, ms);
+}
+
+/**
+ * Push an SSE event to active (non-aborted) callbacks.
+ * Optionally filter by path prefix (e.g. "/v1/trades").
+ */
+export function emitSseEvent(data: unknown, pathFilter?: string): void {
+  const targets = pathFilter
+    ? sseSubscriptions.filter((s) => s.path.includes(pathFilter) && !s.aborted)
+    : sseSubscriptions.filter((s) => !s.aborted);
+  for (const sub of targets) {
+    sub.callback(data);
+  }
+}
+
+/** Abort every open SSE mock subscription (test isolation helper). */
+export function abortAllSseSubscriptions(): void {
+  for (const sub of [...sseSubscriptions]) {
+    sub.abort();
+  }
+}

package/src/opentui-augment.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Augment @opentui/core types that aren't resolved correctly through Bun's symlink chain.
+ * This file fixes TS2305 errors by declaring the missing exports that exist at runtime.
+ */
+
+// CliRenderer and createCliRenderer are exported from @opentui/core/renderer.d.ts
+// but the re-export through index.d.ts (export * from "./renderer.js") may not
+// resolve correctly due to Bun's symlinked package resolution.
+declare module "@opentui/core" {
+  export interface CliRendererConfig {
+    screenMode?: "main-screen" | "alternate-screen";
+    exitOnCtrlC?: boolean;
+    targetFps?: number;
+    maxFps?: number;
+    useMouse?: boolean;
+    backgroundColor?: string;
+    useKittyKeyboard?:
+      | boolean
+      | {
+          disambiguate?: boolean;
+          alternateKeys?: boolean;
+          events?: boolean;
+        };
+    [key: string]: unknown;
+  }
+
+  export interface CliRenderer {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    destroy(): void;
+    start(): void;
+    keyInput: {
+      on(event: string, handler: (key: unknown) => void): () => void;
+    };
+    [key: string]: unknown;
+  }
+
+  export function createCliRenderer(
+    config?: CliRendererConfig
+  ): Promise<CliRenderer>;
+}

package/src/opentui-jsx.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Augment @opentui/react types.
+ *
+ * 1. Loose JSX intrinsic element types: OpenTUI v0.2.12's `BoxProps` and `TextProps`
+ *    don't include all layout/style props (fg, bg, bold, dim, flexDirection, paddingLeft, etc.)
+ *    that are valid at runtime. This augmentation makes all intrinsic elements accept any props
+ *    to avoid TS2322 errors throughout the codebase.
+ *
+ * 2. Named exports: `createRoot` and `useKeyboard` are exported from @opentui/react but
+ *    may not resolve correctly through Bun's symlinked package resolution. This augmentation
+ *    declares them to fix TS2305 errors.
+ */
+
+declare module "@opentui/react" {
+  // JSX namespace augmentation for loose intrinsic element types
+  export namespace JSX {
+    interface IntrinsicElements {
+      text: Record<string, unknown>;
+      box: Record<string, unknown>;
+      span: Record<string, unknown>;
+      code: Record<string, unknown>;
+      diff: Record<string, unknown>;
+      markdown: Record<string, unknown>;
+      input: Record<string, unknown>;
+      textarea: Record<string, unknown>;
+      select: Record<string, unknown>;
+      scrollbox: Record<string, unknown>;
+      "ascii-font": Record<string, unknown>;
+      "tab-select": Record<string, unknown>;
+      "line-number": Record<string, unknown>;
+      b: Record<string, unknown>;
+      i: Record<string, unknown>;
+      u: Record<string, unknown>;
+      strong: Record<string, unknown>;
+      em: Record<string, unknown>;
+      br: Record<string, unknown>;
+      a: Record<string, unknown>;
+    }
+  }
+
+  // Key event object structure from useKeyboard hook
+  export interface KeyEvent {
+    name: string;
+    sequence: string;
+    ctrl: boolean;
+    alt: boolean;
+    meta: boolean;
+    shift: boolean;
+    [key: string]: unknown;
+  }
+
+  // Named exports that may not resolve through Bun's symlink chain
+  export function createRoot(
+    container: unknown,
+    options?: unknown
+  ): {
+    render(element: unknown): void;
+    unmount(): void;
+  };
+
+  export function useKeyboard(
+    handler?: (key: KeyEvent) => void,
+    options?: unknown
+  ): unknown;
+}