emoemu 0.1.0

package/src/ui/WarningDialog/index.tsx

@@ -0,0 +1,113 @@
+/**
+ * Warning Dialog Component
+ *
+ * A general-purpose warning dialog that displays a message and allows
+ * the user to choose between continuing (OK) or exiting the application.
+ */
+
+import { Box, Text } from 'ink';
+import { useDialogNavigation } from '../hooks/useDialogNavigation';
+import { DialogContainer } from '../DialogContainer';
+import { launchDialog, type DialogRenderOptions } from '../NativeDialog';
+import { DIALOG_BOX_PADDING } from '..';
+
+export type WarningChoice = 'ok' | 'exit';
+
+interface WarningDialogProps {
+  message: string;
+  title?: string;
+  onChoice: (choice: WarningChoice) => void;
+}
+
+const WarningDialog = ({ message, title = 'Warning', onChoice }: WarningDialogProps) => {
+  const options: { label: string; choice: WarningChoice; color: string }[] = [
+    { label: 'OK', choice: 'ok', color: 'green' },
+    { label: 'Exit', choice: 'exit', color: 'red' },
+  ];
+
+  const { selectedIndex } = useDialogNavigation({
+    itemCount: options.length,
+    onSelect: (index) => onChoice(options[index].choice),
+    onCancel: () => onChoice('ok'),
+    horizontal: true,
+    spaceToSelect: true,
+    onCtrlC: () => onChoice('exit'),
+  });
+
+  return (
+    <DialogContainer>
+      {(boxWidth) => (
+        <>
+          {/* Main Dialog Box */}
+          <Box
+            flexDirection="column"
+            borderStyle="round"
+            borderColor="yellow"
+            paddingX={2}
+            paddingY={1}
+            width={boxWidth}
+          >
+            {/* Header with warning icon */}
+            <Box justifyContent="center" marginBottom={1}>
+              <Text bold color="yellow">{'\u26A0'} {title}</Text>
+            </Box>
+
+            {/* Message */}
+            <Box justifyContent="center" marginBottom={1}>
+              <Text wrap="wrap">{message}</Text>
+            </Box>
+
+            {/* Separator */}
+            <Box justifyContent="center" marginY={1}>
+              <Text color="gray" dimColor>{'─'.repeat(boxWidth - DIALOG_BOX_PADDING - 2)}</Text>
+            </Box>
+
+            {/* Buttons - horizontal layout */}
+            <Box justifyContent="center" gap={2}>
+              {options.map((option, index) => (
+                <Box
+                  key={option.choice}
+                  paddingX={2}
+                  borderStyle={selectedIndex === index ? 'round' : 'single'}
+                  borderColor={selectedIndex === index ? option.color : 'gray'}
+                >
+                  <Text
+                    color={selectedIndex === index ? option.color : 'gray'}
+                    bold={selectedIndex === index}
+                  >
+                    {option.label}
+                  </Text>
+                </Box>
+              ))}
+            </Box>
+          </Box>
+
+          {/* Footer */}
+          <Box marginTop={1}>
+            <Text color="gray" dimColor>
+              {'\u2190\u2192'} Navigate  {'\u23CE'}/Space Select  ESC Continue
+            </Text>
+          </Box>
+        </>
+      )}
+    </DialogContainer>
+  );
+};
+
+/**
+ * Show the warning dialog and get user's choice
+ *
+ * @param message - The warning message to display
+ * @param options - Dialog render options (native mode, title, etc.)
+ * @returns 'ok' if user chooses to continue, 'exit' if user chooses to exit
+ */
+export const showWarningDialog = (
+  message: string,
+  options: DialogRenderOptions & { title?: string } = {}
+): Promise<WarningChoice> => launchDialog<WarningChoice>(
+  (onChoice) => <WarningDialog message={message} title={options.title} onChoice={onChoice} />,
+  'ok',
+  { ...options, title: options.title ?? 'emoemu - Warning' },
+);
+
+export default WarningDialog;

package/src/ui/consts.ts

@@ -0,0 +1,27 @@
+// =============================================================================
+// Terminal Dimensions
+// =============================================================================
+
+/** Default terminal dimensions */
+export const DEFAULT_TERM_WIDTH = 80;
+export const DEFAULT_TERM_HEIGHT = 24;
+
+// =============================================================================
+// Timing
+// =============================================================================
+
+/** Delay for stdin settling (ms) */
+export const STDIN_SETTLE_DELAY_MS = 100;
+
+// =============================================================================
+// Dialog
+// =============================================================================
+
+/** Dialog box padding (used by multiple dialogs) */
+export const DIALOG_BOX_PADDING = 4;
+
+/** Default minimum width for dialog boxes */
+export const DIALOG_BOX_MIN_WIDTH = 50;
+
+/** Padding subtracted from box width when rendering separator lines */
+export const SEPARATOR_LINE_PADDING = 6;

package/src/ui/hooks/useClearTerminal/consts.ts

@@ -0,0 +1,2 @@
+/** Clear screen, move cursor home, hide cursor */
+export const CLEAR_TERMINAL_SEQUENCE = '\x1b[2J\x1b[H\x1b[?25l';

package/src/ui/hooks/useClearTerminal/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook to clear the terminal on mount and trigger a re-render.
+ *
+ * When a component clears the terminal in useEffect, Ink doesn't know the
+ * screen was cleared, so it won't re-render until user input. This hook
+ * handles both clearing and forcing a re-render so content displays immediately.
+ */
+
+import { useState, useEffect } from 'react';
+import { CLEAR_TERMINAL_SEQUENCE } from './consts';
+
+export * from './consts';
+
+/**
+ * Clear the terminal on mount and return whether the component is ready to render.
+ *
+ * @returns true after the terminal has been cleared and re-render triggered
+ *
+ * @example
+ * const MyComponent = () => {
+ *   const ready = useClearTerminal();
+ *   if (!ready) return null;
+ *   return <Box>Content</Box>;
+ * };
+ */
+export const useClearTerminal = (): boolean => {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    // Clear screen, move cursor to home position, and hide cursor
+    process.stdout.write(CLEAR_TERMINAL_SEQUENCE);
+    // Trigger re-render so Ink draws the component
+    setReady(true);
+  }, []);
+
+  return ready;
+};

package/src/ui/hooks/useDialogNavigation/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Dialog Navigation Hook
+ *
+ * Manages selectedIndex state, keyboard (useInput), and gamepad navigation
+ * for dialog components with a list of selectable options.
+ */
+
+import { useState } from 'react';
+import { useInput, useApp } from 'ink';
+import { useGamepad } from '../useGamepad';
+
+interface UseDialogNavigationOptions {
+  /** Number of selectable items */
+  itemCount: number;
+  /** Called when the user confirms a selection (Enter, number key, gamepad A) */
+  onSelect: (index: number) => void;
+  /** Called when the user cancels (ESC, gamepad B) */
+  onCancel: () => void;
+  /** Enable left/right arrow navigation in addition to up/down */
+  horizontal?: boolean;
+  /** Accept space bar as confirmation (in addition to Enter) */
+  spaceToSelect?: boolean;
+  /** Custom CTRL-C handler; if omitted, CTRL-C is not specially handled */
+  onCtrlC?: () => void;
+}
+
+/**
+ * Hook that provides standard dialog navigation: up/down arrows, Enter to select,
+ * ESC to cancel, number shortcuts, and gamepad support.
+ */
+export const useDialogNavigation = ({
+  itemCount,
+  onSelect,
+  onCancel,
+  horizontal = false,
+  spaceToSelect = false,
+  onCtrlC,
+}: UseDialogNavigationOptions) => {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const { exit } = useApp();
+
+  const selectAndExit = (index: number) => {
+    onSelect(index);
+    exit();
+  };
+
+  const cancelAndExit = () => {
+    onCancel();
+    exit();
+  };
+
+  useInput((input, key) => {
+    // Optional CTRL-C handling
+    if (onCtrlC && (input === '\x03' || (key.ctrl && input === 'c'))) {
+      onCtrlC();
+      exit();
+      return;
+    }
+
+    if (key.escape) {
+      cancelAndExit();
+      return;
+    }
+
+    if (key.upArrow || (horizontal && key.leftArrow)) {
+      setSelectedIndex(prev => Math.max(0, prev - 1));
+      return;
+    }
+
+    if (key.downArrow || (horizontal && key.rightArrow)) {
+      setSelectedIndex(prev => Math.min(itemCount - 1, prev + 1));
+      return;
+    }
+
+    if (key.return || (spaceToSelect && input === ' ')) {
+      selectAndExit(selectedIndex);
+      return;
+    }
+
+    // Number shortcuts (1-based)
+    const num = parseInt(input, 10);
+    if (num >= 1 && num <= itemCount) {
+      selectAndExit(num - 1);
+    }
+  });
+
+  useGamepad({
+    onUp: () => setSelectedIndex(prev => Math.max(0, prev - 1)),
+    onDown: () => setSelectedIndex(prev => Math.min(itemCount - 1, prev + 1)),
+    ...(horizontal && {
+      onLeft: () => setSelectedIndex(prev => Math.max(0, prev - 1)),
+      onRight: () => setSelectedIndex(prev => Math.min(itemCount - 1, prev + 1)),
+    }),
+    onConfirm: () => selectAndExit(selectedIndex),
+    onCancel: cancelAndExit,
+  });
+
+  return { selectedIndex, setSelectedIndex };
+};

package/src/ui/hooks/useGamepad/consts.ts

@@ -0,0 +1,21 @@
+// Gamepad acceleration settings for held direction buttons
+
+/** Delay before repeating starts (ms) */
+export const INITIAL_DELAY_MS = 400;
+
+/** Starting repeat interval (ms) */
+export const INITIAL_REPEAT_MS = 200;
+
+/** Fastest repeat interval (ms) */
+export const MIN_REPEAT_MS = 40;
+
+/** Time to reach max speed (ms) */
+export const ACCELERATION_TIME_MS = 1500;
+
+// Ease-in-out curve coefficients (smoothstep function: 3t^2 - 2t^3)
+
+/** Smoothstep cubic factor */
+export const EASE_CUBIC_FACTOR = 3;
+
+/** Smoothstep cubic divisor */
+export const EASE_CUBIC_DIVISOR = 2;

package/src/ui/hooks/useGamepad/index.ts

@@ -0,0 +1,194 @@
+/**
+ * Gamepad Hook for UI Components
+ *
+ * Provides gamepad navigation support for Ink-based UI components.
+ * Handles Up/Down for navigation, A for confirm, B for cancel.
+ * Directional inputs support accelerating repeat when held.
+ */
+
+import { useEffect, useRef } from 'react';
+import { GamepadManager } from '@/input/GamepadManager';
+import { StandardButton } from '@/core/button';
+import {
+  INITIAL_DELAY_MS,
+  INITIAL_REPEAT_MS,
+  MIN_REPEAT_MS,
+  ACCELERATION_TIME_MS,
+  EASE_CUBIC_FACTOR,
+  EASE_CUBIC_DIVISOR,
+} from './consts';
+
+export * from './consts';
+
+export interface GamepadCallbacks {
+  onUp?: () => void;
+  onDown?: () => void;
+  onLeft?: () => void;
+  onRight?: () => void;
+  onConfirm?: () => void;  // A button
+  onCancel?: () => void;   // B button
+  onStart?: () => void;    // Start button
+}
+
+type Direction = 'up' | 'down' | 'left' | 'right';
+
+const DIRECTION_CALLBACKS: Record<Direction, keyof Pick<GamepadCallbacks, 'onUp' | 'onDown' | 'onLeft' | 'onRight'>> = {
+  up: 'onUp',
+  down: 'onDown',
+  left: 'onLeft',
+  right: 'onRight',
+};
+
+const fireDirectionalCallback = (callbacks: GamepadCallbacks, direction: Direction): void => {
+  callbacks[DIRECTION_CALLBACKS[direction]]?.();
+};
+
+interface RepeatState {
+  direction: Direction;
+  startTime: number;
+  timeoutId: ReturnType<typeof setTimeout> | null;
+}
+
+/**
+ * Hook for gamepad input in UI components.
+ * Automatically manages GamepadManager lifecycle.
+ * Directional buttons accelerate when held.
+ *
+ * @param callbacks Object with callback functions for different inputs
+ * @param enabled Whether gamepad input is enabled (default: true)
+ */
+export const useGamepad = (callbacks: GamepadCallbacks, enabled: boolean = true): void => {
+  const managerRef = useRef<GamepadManager | null>(null);
+  const callbacksRef = useRef(callbacks);
+  const repeatStateRef = useRef<RepeatState | null>(null);
+
+  // Keep callbacks ref up to date
+  callbacksRef.current = callbacks;
+
+  useEffect(() => {
+    if (!enabled) {return;}
+
+    // Calculate repeat interval based on how long button has been held
+    const getRepeatInterval = (heldDuration: number): number => {
+      if (heldDuration < INITIAL_DELAY_MS) {
+        return INITIAL_DELAY_MS - heldDuration;
+      }
+
+      // Calculate acceleration progress (0 to 1)
+      const accelerationProgress = Math.min(
+        1,
+        (heldDuration - INITIAL_DELAY_MS) / ACCELERATION_TIME_MS
+      );
+
+      // Ease-in-out curve for smooth acceleration (smoothstep)
+      const easedProgress = accelerationProgress * accelerationProgress * (EASE_CUBIC_FACTOR - EASE_CUBIC_DIVISOR * accelerationProgress);
+
+      // Interpolate between initial and minimum repeat interval
+      return INITIAL_REPEAT_MS - (INITIAL_REPEAT_MS - MIN_REPEAT_MS) * easedProgress;
+    };
+
+    // Fire callback for direction and schedule next repeat
+    const fireAndSchedule = (direction: Direction) => {
+      const cb = callbacksRef.current;
+      const state = repeatStateRef.current;
+
+      if (!state || state.direction !== direction) {return;}
+
+      // Fire the appropriate callback
+      fireDirectionalCallback(cb, direction);
+
+      // Schedule next repeat with accelerated interval
+      const heldDuration = Date.now() - state.startTime;
+      const interval = getRepeatInterval(heldDuration);
+
+      state.timeoutId = setTimeout(() => fireAndSchedule(direction), interval);
+    };
+
+    // Start repeat for a direction
+    const startRepeat = (direction: Direction) => {
+      // Cancel any existing repeat
+      stopRepeat();
+
+      // Fire callback immediately
+      fireDirectionalCallback(callbacksRef.current, direction);
+
+      // Start repeat state
+      repeatStateRef.current = {
+        direction,
+        startTime: Date.now(),
+        timeoutId: setTimeout(() => fireAndSchedule(direction), INITIAL_DELAY_MS),
+      };
+    };
+
+    // Stop any active repeat
+    const stopRepeat = () => {
+      const state = repeatStateRef.current;
+      if (state?.timeoutId) {
+        clearTimeout(state.timeoutId);
+      }
+      repeatStateRef.current = null;
+    };
+
+    // Map button to direction
+    const buttonToDirection = (button: StandardButton): Direction | null => {
+      switch (button) {
+        case StandardButton.Up:
+        case StandardButton.LeftStickUp:
+          return 'up';
+        case StandardButton.Down:
+        case StandardButton.LeftStickDown:
+          return 'down';
+        case StandardButton.Left:
+        case StandardButton.LeftStickLeft:
+          return 'left';
+        case StandardButton.Right:
+        case StandardButton.LeftStickRight:
+          return 'right';
+        default:
+          return null;
+      }
+    };
+
+    // Create and start the gamepad manager
+    const manager = new GamepadManager();
+    managerRef.current = manager;
+
+    manager.onButtonChange = (_port, button, pressed) => {
+      const cb = callbacksRef.current;
+      const direction = buttonToDirection(button);
+
+      if (direction) {
+        // Directional buttons with acceleration
+        if (pressed) {
+          startRepeat(direction);
+        } else {
+          // Only stop if this is the direction currently being held
+          if (repeatStateRef.current?.direction === direction) {
+            stopRepeat();
+          }
+        }
+      } else if (pressed) {
+        // Non-directional buttons: fire on press only
+        switch (button) {
+          case StandardButton.A:
+            cb.onConfirm?.();
+            break;
+          case StandardButton.B:
+            cb.onCancel?.();
+            break;
+          case StandardButton.Start:
+            cb.onStart?.();
+            break;
+        }
+      }
+    };
+
+    manager.start();
+
+    return () => {
+      stopRepeat();
+      manager.stop();
+      managerRef.current = null;
+    };
+  }, [enabled]);
+};

package/src/ui/index.ts

@@ -0,0 +1,27 @@
+/**
+ * UI Module Exports
+ */
+
+export * from './consts';
+export { launchBrowser, importDirectory } from './App';
+export type { BrowserResult, NetplayOptions } from './App';
+export { selectCore } from './CoreSelector';
+export type { CoreSelection } from './CoreSelector';
+export { showSaveStateDialog, showCorruptedStateDialog } from './SaveStateDialog';
+export type { SaveStateInfo, SaveStateChoice, CorruptedStateInfo, CorruptedStateChoice } from './SaveStateDialog';
+export { showNetplayDisconnectedDialog } from './NetplayDisconnectedDialog';
+export type { DisconnectInfo, DisconnectChoice } from './NetplayDisconnectedDialog';
+export { showWarningDialog } from './WarningDialog';
+export type { WarningChoice } from './WarningDialog';
+export { scanDirectory, groupBySystem, validateRomFile } from '../frontend/romScanner';
+export type { RomInfo, RomMetadata, ValidateRomResult } from '../frontend/romScanner';
+export { GamepadProvider, useGamepadContext } from './GamepadContext';
+export type { GamepadCallbacks } from './GamepadContext';
+export { AppCapabilitiesProvider, useAppCapabilities, useKittyGraphicsSupported, useNativeSupported } from './AppCapabilities';
+export type { AppCapabilities } from './AppCapabilities';
+export { ConfigProvider, useConfig } from './ConfigContext';
+export { showDuplicateCrcPrompt } from './DuplicateCrcPrompt';
+export type { DuplicateCrcInfo, DuplicateCrcChoice } from './DuplicateCrcPrompt';
+export type { DialogRenderOptions } from './NativeDialog';
+export { useClearTerminal } from './hooks/useClearTerminal';
+export { useGamepad, type GamepadCallbacks as HookGamepadCallbacks } from './hooks/useGamepad';

package/src/utils/buffer/consts.ts

@@ -0,0 +1,17 @@
+/** Bit shift for second byte */
+export const BYTE_SHIFT_1 = 8;
+
+/** Center value for unsigned 8-bit analog input (0-255 range) */
+export const ANALOG_CENTER_8BIT = 128;
+
+/** Default deadzone for 8-bit analog input */
+export const ANALOG_DEADZONE_8BIT = 50;
+
+/** Default deadzone for signed 16-bit analog input */
+export const ANALOG_DEADZONE_SIGNED = 8000;
+
+/** Maximum positive value for signed 16-bit integer */
+export const INT16_MAX = 32767;
+
+/** Full range of unsigned 16-bit integer (for signed conversion) */
+export const UINT16_RANGE = 65536;

package/src/utils/buffer/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Buffer Reading Utilities
+ *
+ * Utilities for reading binary data and gamepad input processing.
+ */
+
+import { StandardButton } from '../../core/button';
+import {
+  BYTE_SHIFT_1,
+  ANALOG_CENTER_8BIT,
+  ANALOG_DEADZONE_8BIT,
+  ANALOG_DEADZONE_SIGNED,
+  INT16_MAX,
+  UINT16_RANGE,
+} from './consts';
+
+export * from './consts';
+
+/**
+ * D-pad direction state
+ */
+export interface DpadState {
+  up: boolean;
+  down: boolean;
+  left: boolean;
+  right: boolean;
+}
+
+/**
+ * Read unsigned 16-bit little-endian value from buffer
+ */
+export const readUint16LE = (data: Buffer, offset: number): number =>
+  data[offset] | (data[offset + 1] << BYTE_SHIFT_1);
+
+/**
+ * Read signed 16-bit little-endian value from buffer
+ * Converts unsigned 16-bit to signed (-32768 to +32767)
+ */
+export const readInt16LE = (data: Buffer, offset: number): number => {
+  const raw = readUint16LE(data, offset);
+  return raw > INT16_MAX ? raw - UINT16_RANGE : raw;
+};
+
+/**
+ * Apply analog stick values to d-pad buttons with deadzone
+ * For signed analog values centered at 0 (-32768 to +32767)
+ */
+export const applySignedAnalogToDpad = (
+  buttons: Map<StandardButton, boolean>,
+  x: number,
+  y: number,
+  deadzone: number = ANALOG_DEADZONE_SIGNED
+): void => {
+  if (x < -deadzone) { buttons.set(StandardButton.Left, true); }
+  if (x > deadzone) { buttons.set(StandardButton.Right, true); }
+  if (y < -deadzone) { buttons.set(StandardButton.Down, true); }
+  if (y > deadzone) { buttons.set(StandardButton.Up, true); }
+};
+
+/**
+ * Convert analog stick values to digital d-pad state
+ * For unsigned values (0-255 range with 128 as center)
+ */
+export const analogToDpad = (
+  x: number,
+  y: number,
+  deadzone: number = ANALOG_DEADZONE_8BIT,
+  center: number = ANALOG_CENTER_8BIT
+): DpadState => ({
+  left: x < center - deadzone,
+  right: x > center + deadzone,
+  up: y < center - deadzone,
+  down: y > center + deadzone,
+});
+
+/**
+ * Neutral d-pad state (no buttons pressed)
+ */
+const DPAD_NEUTRAL: DpadState = { up: false, down: false, left: false, right: false };
+
+/**
+ * Standard HID hat values: 0=N, 1=NE, 2=E, 3=SE, 4=S, 5=SW, 6=W, 7=NW, 8/15=center
+ */
+const STANDARD_HAT_MAP: Record<number, DpadState> = {
+  0: { up: true, down: false, left: false, right: false },   // N
+  1: { up: true, down: false, left: false, right: true },    // NE
+  2: { up: false, down: false, left: false, right: true },   // E
+  3: { up: false, down: true, left: false, right: true },    // SE
+  4: { up: false, down: true, left: false, right: false },   // S
+  5: { up: false, down: true, left: true, right: false },    // SW
+  6: { up: false, down: false, left: true, right: false },   // W
+  7: { up: true, down: false, left: true, right: false },    // NW
+};
+
+/**
+ * Xbox-style hat values: 0=none, 1=N, 2=NE, 3=E, 4=SE, 5=S, 6=SW, 7=W, 8=NW
+ */
+const XBOX_HAT_MAP: Record<number, DpadState> = {
+  0: DPAD_NEUTRAL,                                           // None
+  1: { up: true, down: false, left: false, right: false },   // N
+  2: { up: true, down: false, left: false, right: true },    // NE
+  3: { up: false, down: false, left: false, right: true },   // E
+  4: { up: false, down: true, left: false, right: true },    // SE
+  5: { up: false, down: true, left: false, right: false },   // S
+  6: { up: false, down: true, left: true, right: false },    // SW
+  7: { up: false, down: false, left: true, right: false },   // W
+  8: { up: true, down: false, left: true, right: false },    // NW
+};
+
+/**
+ * Parse hat switch value to d-pad state
+ * @param hat - Hat switch value from HID report
+ * @param xboxStyle - If true, use Xbox 1-indexed hat values (0=none, 1=N, etc.)
+ */
+export const hatToDpad = (hat: number, xboxStyle: boolean = false): DpadState =>
+  (xboxStyle ? XBOX_HAT_MAP : STANDARD_HAT_MAP)[hat] ?? DPAD_NEUTRAL;
+
+/**
+ * Apply d-pad state to button map
+ */
+export const applyDpadToButtons = (
+  buttons: Map<StandardButton, boolean>,
+  dpad: DpadState
+): void => {
+  if (dpad.up) { buttons.set(StandardButton.Up, true); }
+  if (dpad.down) { buttons.set(StandardButton.Down, true); }
+  if (dpad.left) { buttons.set(StandardButton.Left, true); }
+  if (dpad.right) { buttons.set(StandardButton.Right, true); }
+};