@hoox-sh/hoox-tui 0.2.0 → 0.3.0

package/src/hooks/hooks.test.ts

@@ -6,8 +6,15 @@
 /**
  * Hook unit tests — renderer ref, global keyboard registration, polling helpers.
  */
-import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
-import { setRendererRef, getRendererRef, registerGlobalHandler } from "./index";
+import { describe, it, expect, beforeEach, afterEach, jest } from "bun:test";
+import {
+  setRendererRef,
+  getRendererRef,
+  registerGlobalHandler,
+  computePollingBackoff,
+  createPollingController,
+  POLLING_MAX_BACKOFF_MS,
+} from "./index";
 import type { KeyEvent } from "./use-keyboard";
 
 describe("renderer-ref", () => {
@@ -36,6 +43,10 @@ describe("registerGlobalHandler", () => {
     setRendererRef(null);
   });
 
+  afterEach(() => {
+    setRendererRef(null);
+  });
+
   it("registers and unregisters without throwing", () => {
     const calls: string[] = [];
     const unsub = registerGlobalHandler((key: KeyEvent) => {
@@ -54,19 +65,302 @@ describe("registerGlobalHandler", () => {
     b();
     c();
   });
+
+  it("dispatches keypresses in priority order when renderer is attached", () => {
+    const order: number[] = [];
+    const listeners = new Map<string, Set<(...args: unknown[]) => void>>();
+    const keyInput = {
+      on: (event: string, fn: (...args: unknown[]) => void) => {
+        if (!listeners.has(event)) listeners.set(event, new Set());
+        listeners.get(event)!.add(fn);
+        return () => listeners.get(event)?.delete(fn);
+      },
+      off: (event: string, fn: (...args: unknown[]) => void) => {
+        listeners.get(event)?.delete(fn);
+      },
+    };
+    setRendererRef({
+      keyInput,
+    } as unknown as import("@opentui/core").CliRenderer);
+
+    const unsubHigh = registerGlobalHandler(() => {
+      order.push(0);
+    }, 0);
+    const unsubMid = registerGlobalHandler(() => {
+      order.push(10);
+    }, 10);
+    const unsubLow = registerGlobalHandler(() => {
+      order.push(50);
+    }, 50);
+
+    const handlers = listeners.get("keypress");
+    expect(handlers?.size).toBe(1);
+    for (const h of handlers ?? []) {
+      h({
+        name: "a",
+        ctrl: false,
+        shift: false,
+        alt: false,
+        meta: false,
+        sequence: "a",
+      });
+    }
+    expect(order).toEqual([0, 10, 50]);
+
+    unsubHigh();
+    unsubMid();
+    unsubLow();
+    // Last unsubscribe detaches key input
+    expect(listeners.get("keypress")?.size ?? 0).toBe(0);
+  });
+
+  it("snapshot protects against unsubscribe mid-dispatch", () => {
+    const seen: string[] = [];
+    let unsubB: (() => void) | null = null;
+    const listeners = new Map<string, Set<(...args: unknown[]) => void>>();
+    const keyInput = {
+      on: (event: string, fn: (...args: unknown[]) => void) => {
+        if (!listeners.has(event)) listeners.set(event, new Set());
+        listeners.get(event)!.add(fn);
+        return () => listeners.get(event)?.delete(fn);
+      },
+      off: () => {},
+    };
+    setRendererRef({
+      keyInput,
+    } as unknown as import("@opentui/core").CliRenderer);
+
+    const unsubA = registerGlobalHandler(() => {
+      seen.push("a");
+      unsubB?.();
+    }, 0);
+    unsubB = registerGlobalHandler(() => {
+      seen.push("b");
+    }, 1);
+
+    for (const h of listeners.get("keypress") ?? []) {
+      h({
+        name: "x",
+        ctrl: false,
+        shift: false,
+        alt: false,
+        meta: false,
+        sequence: "x",
+      });
+    }
+    // Snapshot ensures b still runs even though unsub mid-dispatch
+    expect(seen).toEqual(["a", "b"]);
+    unsubA();
+  });
+
+  it("attaches when on() returns non-function (off fallback path)", () => {
+    let offCalled = false;
+    const keyInput = {
+      on: () => undefined,
+      off: () => {
+        offCalled = true;
+      },
+    };
+    setRendererRef({
+      keyInput,
+    } as unknown as import("@opentui/core").CliRenderer);
+    const unsub = registerGlobalHandler(() => {}, 5);
+    unsub();
+    expect(offCalled).toBe(true);
+  });
 });
 
-describe("usePolling backoff math", () => {
+describe("computePollingBackoff", () => {
   it("caps exponential backoff at 16s", () => {
     const base = 1000;
-    const MAX = 16_000;
     for (let retry = 0; retry < 10; retry++) {
-      const backoff = Math.min(base * Math.pow(2, retry), MAX);
-      expect(backoff).toBeLessThanOrEqual(MAX);
+      const backoff = computePollingBackoff(base, retry);
+      expect(backoff).toBeLessThanOrEqual(POLLING_MAX_BACKOFF_MS);
     }
-    expect(Math.min(base * Math.pow(2, 10), MAX)).toBe(MAX);
+    expect(computePollingBackoff(base, 10)).toBe(POLLING_MAX_BACKOFF_MS);
+  });
+
+  it("doubles per retry until cap", () => {
+    expect(computePollingBackoff(500, 0)).toBe(500);
+    expect(computePollingBackoff(500, 1)).toBe(1000);
+    expect(computePollingBackoff(500, 2)).toBe(2000);
+    expect(computePollingBackoff(500, 3)).toBe(4000);
+  });
+
+  it("respects custom max backoff", () => {
+    expect(computePollingBackoff(1000, 5, 3000)).toBe(3000);
   });
 });
 
-// Silence unused import if mock is tree-shaken away in some runners
-void mock;
+describe("createPollingController", () => {
+  /** Flush microtasks after advancing fake timers (Bun has no advanceTimersByTimeAsync). */
+  async function advance(ms: number): Promise<void> {
+    jest.advanceTimersByTime(ms);
+    // Drain promise chains scheduled by timer callbacks
+    await Promise.resolve();
+    await Promise.resolve();
+  }
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("invokes callback immediately when immediate=true", async () => {
+    let calls = 0;
+    const ctrl = createPollingController({
+      getCallback: () => async () => {
+        calls++;
+      },
+      getIntervalMs: () => 1000,
+      immediate: true,
+    });
+    ctrl.start();
+    // Let the microtask from the immediate poll resolve
+    await Promise.resolve();
+    expect(calls).toBe(1);
+    ctrl.stop();
+  });
+
+  it("defers first poll when immediate=false", async () => {
+    let calls = 0;
+    const ctrl = createPollingController({
+      getCallback: () => async () => {
+        calls++;
+      },
+      getIntervalMs: () => 500,
+      immediate: false,
+    });
+    ctrl.start();
+    await Promise.resolve();
+    expect(calls).toBe(0);
+    await advance(500);
+    expect(calls).toBe(1);
+    ctrl.stop();
+  });
+
+  it("increments retry count on failure and resets on success", async () => {
+    let shouldFail = true;
+    const ctrl = createPollingController({
+      getCallback: () => async () => {
+        if (shouldFail) throw new Error("boom");
+      },
+      getIntervalMs: () => 100,
+      immediate: true,
+    });
+    ctrl.start();
+    await Promise.resolve();
+    expect(ctrl.getRetryCount()).toBe(1);
+
+    // Next scheduled poll after backoff 100 * 2^1 = 200
+    shouldFail = false;
+    await advance(200);
+    expect(ctrl.getRetryCount()).toBe(0);
+    ctrl.stop();
+  });
+
+  it("stop prevents further polls after pending timeout", async () => {
+    let calls = 0;
+    const ctrl = createPollingController({
+      getCallback: () => async () => {
+        calls++;
+      },
+      getIntervalMs: () => 1000,
+      immediate: true,
+    });
+    ctrl.start();
+    await Promise.resolve();
+    expect(calls).toBe(1);
+    ctrl.stop();
+    await advance(10_000);
+    expect(calls).toBe(1);
+  });
+
+  it("reads fresh interval on each iteration", async () => {
+    let interval = 100;
+    let calls = 0;
+    const ctrl = createPollingController({
+      getCallback: () => async () => {
+        calls++;
+      },
+      getIntervalMs: () => interval,
+      immediate: true,
+    });
+    ctrl.start();
+    await Promise.resolve();
+    expect(calls).toBe(1);
+    interval = 250;
+    // Next poll was scheduled at previous interval (100); after it runs,
+    // subsequent delay uses the new interval.
+    await advance(100);
+    expect(calls).toBe(2);
+    await advance(249);
+    expect(calls).toBe(2);
+    await advance(1);
+    expect(calls).toBe(3);
+    ctrl.stop();
+  });
+
+  it("stop during in-flight callback does not schedule next poll", async () => {
+    let resolveCb!: () => void;
+    let calls = 0;
+    const ctrl = createPollingController({
+      getCallback: () => () =>
+        new Promise<void>((resolve) => {
+          calls++;
+          resolveCb = resolve;
+        }),
+      getIntervalMs: () => 100,
+      immediate: true,
+    });
+    ctrl.start();
+    await Promise.resolve();
+    expect(calls).toBe(1);
+    ctrl.stop();
+    resolveCb();
+    await Promise.resolve();
+    await advance(1000);
+    expect(calls).toBe(1);
+  });
+});
+
+describe("useServiceData", () => {
+  afterEach(async () => {
+    const { __setServiceStoreHookForTests } =
+      await import("./use-service-data");
+    __setServiceStoreHookForTests(null);
+  });
+
+  it("applies the selector via the store hook", async () => {
+    const { useServiceData, __setServiceStoreHookForTests } =
+      await import("./use-service-data");
+    const { useServiceStore } = await import("@hoox-sh/hoox-shared");
+    const snapshot = useServiceStore.getState();
+
+    __setServiceStoreHookForTests((selector) => selector(snapshot));
+
+    const status = useServiceData((s) => s.connectionStatus);
+    expect(status).toBe(snapshot.connectionStatus);
+
+    const workers = useServiceData((s) => s.workers);
+    expect(workers).toBe(snapshot.workers);
+  });
+
+  it("restores real store hook after null reset", async () => {
+    const { useServiceData, __setServiceStoreHookForTests } =
+      await import("./use-service-data");
+    __setServiceStoreHookForTests((() => "injected") as never);
+    expect(useServiceData((() => "x") as never) as unknown).toBe("injected");
+    __setServiceStoreHookForTests(null);
+    // Real hook throws outside React — proves restore happened
+    expect(() => useServiceData((s) => s.connectionStatus)).toThrow();
+  });
+
+  it("is re-exported from hooks index", async () => {
+    const mod = await import("./index");
+    expect(typeof mod.useServiceData).toBe("function");
+  });
+});

package/src/hooks/index.ts

@@ -5,7 +5,13 @@
 
 export { useKeyboard, registerGlobalHandler } from "./use-keyboard";
 export type { KeyEvent, UseKeyboardOptions } from "./use-keyboard";
-export { usePolling } from "./use-polling";
+export {
+  usePolling,
+  computePollingBackoff,
+  createPollingController,
+  POLLING_MAX_BACKOFF_MS,
+} from "./use-polling";
 export type { UsePollingOptions } from "./use-polling";
 export { useServiceData } from "./use-service-data";
 export { setRendererRef, getRendererRef } from "./renderer-ref";
+export { isShellOverlayOpen, useViewKeyboard } from "./shell-overlay";

package/src/hooks/shell-overlay.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shell overlay helpers — command palette / quit modal ownership of keys.
+ * View-local keyboard handlers should no-op while an overlay is open so
+ * typing in the palette (or confirming quit) does not fire view shortcuts.
+ */
+import { useKeyboard } from "@opentui/react";
+import { useUIStore } from "@hoox-sh/hoox-shared";
+
+/** True when palette or a UI-store modal owns the keyboard. */
+export function isShellOverlayOpen(): boolean {
+  const s = useUIStore.getState();
+  return Boolean(s.commandPaletteOpen || s.modal);
+}
+
+/** Key shape from OpenTUI; fields optional at the type boundary. */
+export type ViewKeyEvent = {
+  name?: string;
+  ctrl?: boolean;
+  alt?: boolean;
+  meta?: boolean;
+  shift?: boolean;
+  sequence?: string;
+  /** Some OpenTUI builds expose the raw character as `raw`. */
+  raw?: string;
+};
+
+/**
+ * View-scoped keyboard hook: skips the handler while shell overlays are open.
+ * Drop-in for `@opentui/react` `useKeyboard` in primary views.
+ */
+export function useViewKeyboard(handler: (key: ViewKeyEvent) => void): void {
+  useKeyboard((key) => {
+    if (isShellOverlayOpen()) return;
+    handler(key as ViewKeyEvent);
+  });
+}

package/src/hooks/use-polling.ts

@@ -18,6 +18,89 @@ export interface UsePollingOptions {
   immediate?: boolean;
 }
 
+/** Max poll delay after repeated failures (ms). Exported for unit tests. */
+export const POLLING_MAX_BACKOFF_MS = 16_000;
+
+/**
+ * Exponential backoff for poll failures, capped at {@link POLLING_MAX_BACKOFF_MS}.
+ * Exported for unit tests (pure).
+ */
+export function computePollingBackoff(
+  baseIntervalMs: number,
+  retryCount: number,
+  maxBackoffMs: number = POLLING_MAX_BACKOFF_MS
+): number {
+  return Math.min(baseIntervalMs * Math.pow(2, retryCount), maxBackoffMs);
+}
+
+/**
+ * Non-React poll scheduler used by {@link usePolling}.
+ * Exported so unit tests can cover success/failure/cancel without a renderer.
+ */
+export function createPollingController(options: {
+  getCallback: () => () => Promise<void>;
+  getIntervalMs: () => number;
+  immediate?: boolean;
+  maxBackoffMs?: number;
+  /** Mutable retry counter (shared with the React ref when used from the hook). */
+  retryCountRef?: { current: number };
+}): { start: () => void; stop: () => void; getRetryCount: () => number } {
+  const {
+    getCallback,
+    getIntervalMs,
+    immediate = true,
+    maxBackoffMs = POLLING_MAX_BACKOFF_MS,
+    retryCountRef = { current: 0 },
+  } = options;
+
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  let cancelled = false;
+
+  const poll = async () => {
+    if (cancelled) return;
+    try {
+      await getCallback()();
+      if (cancelled) return;
+      retryCountRef.current = 0;
+    } catch {
+      if (cancelled) return;
+      retryCountRef.current++;
+    }
+    // cancelled is already checked in both branches above (no await between
+    // those checks and here), so schedule the next tick directly.
+    // Read fresh interval on every iteration so config changes take effect.
+    const currentInterval = getIntervalMs();
+    const backoff = computePollingBackoff(
+      currentInterval,
+      retryCountRef.current,
+      maxBackoffMs
+    );
+    timeoutId = setTimeout(() => {
+      void poll();
+    }, backoff);
+  };
+
+  return {
+    getRetryCount: () => retryCountRef.current,
+    start: () => {
+      cancelled = false;
+      if (immediate) {
+        void poll();
+      } else {
+        const initialInterval = getIntervalMs();
+        timeoutId = setTimeout(() => {
+          void poll();
+        }, initialInterval);
+      }
+    },
+    stop: () => {
+      cancelled = true;
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      timeoutId = undefined;
+    },
+  };
+}
+
 export function usePolling(options: UsePollingOptions): void {
   const { callback, enabled = true, immediate = true } = options;
   const intervalMs = useConfigStore((s) => s.refreshIntervalMs);
@@ -32,42 +115,15 @@ export function usePolling(options: UsePollingOptions): void {
       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);
-    }
-
+    const controller = createPollingController({
+      getCallback: () => callbackRef.current,
+      getIntervalMs: () => useConfigStore.getState().refreshIntervalMs,
+      immediate,
+      retryCountRef: retryCount,
+    });
+    controller.start();
     return () => {
-      cancelled = true;
-      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      controller.stop();
     };
   }, [intervalMs, enabled, immediate]);
 }

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

@@ -11,8 +11,25 @@
  */
 import { useServiceStore } from "@hoox-sh/hoox-shared";
 
-export function useServiceData<T>(
-  selector: (state: ReturnType<typeof useServiceStore.getState>) => T
-): T {
-  return useServiceStore(selector);
+export type ServiceStoreState = ReturnType<typeof useServiceStore.getState>;
+export type ServiceStoreSelector<T> = (state: ServiceStoreState) => T;
+
+/**
+ * Store hook used by {@link useServiceData}. Production points at
+ * `useServiceStore`; unit tests may swap this for a pure selector runner
+ * via {@link __setServiceStoreHookForTests}.
+ */
+let storeHook: <T>(selector: ServiceStoreSelector<T>) => T =
+  useServiceStore as <T>(selector: ServiceStoreSelector<T>) => T;
+
+/** @internal Test-only seam — pass `null` to restore the real Zustand hook. */
+export function __setServiceStoreHookForTests(
+  hook: (<T>(selector: ServiceStoreSelector<T>) => T) | null
+): void {
+  storeHook =
+    hook ?? (useServiceStore as <T>(selector: ServiceStoreSelector<T>) => T);
+}
+
+export function useServiceData<T>(selector: ServiceStoreSelector<T>): T {
+  return storeHook(selector);
 }

package/src/main.tsx

@@ -13,6 +13,7 @@
  */
 import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
+import { ToasterRenderable } from "@opentui-ui/toast";
 import { CrashRecoveryApp } from "./app";
 import {
   Colors,
@@ -102,6 +103,20 @@ async function main() {
   // Set renderer ref so hooks + components can access it via getRendererRef()
   setRendererRef(renderer);
 
+  // Mount toast host so connection/auth toasts actually render
+  try {
+    const root = (
+      renderer as unknown as {
+        root: { add: (node: unknown) => void };
+      }
+    ).root;
+    root.add(new ToasterRenderable(renderer));
+  } catch (err) {
+    await tuiDevLog.warn("startup", "Toaster mount failed — toasts may no-op", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   // Mouse drag-select → clipboard (OSC 52 + system tools)
   enableAutoCopyOnSelection(
     renderer as unknown as import("./services/clipboard").ClipboardRenderer