emoemu 0.1.0

package/src/ui/App/consts.ts

@@ -0,0 +1,2 @@
+/** Delay before showing loading indicator (ms) */
+export const LOADING_INDICATOR_DELAY_MS = 1000;

package/src/ui/App/index.tsx

@@ -0,0 +1,456 @@
+/**
+ * Main UI App Component
+ *
+ * Entry point for the Ink-based terminal UI.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import { Box, Text, render } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { RomBrowser } from '../RomBrowser';
+import type { RomInfo } from '../../frontend/romScanner';
+import { getPlaylistsDirectory, DEFAULT_CONFIG } from '../../frontend/config';
+import type { Config } from '../../frontend/config';
+import { cleanupInkInstance } from '../../utils/terminal';
+import { getErrorMessage } from '../../utils/getErrorMessage';
+import { GamepadProvider } from '../GamepadContext';
+import { AppCapabilitiesProvider, type AppCapabilities } from '../AppCapabilities';
+import { ConfigProvider } from '../ConfigContext';
+import { AddRomsPrompt } from '../AddRomsPrompt';
+import {
+  loadRomsFromPlaylists,
+  findPlaylistsInDirectory,
+} from '../../frontend/playlist';
+import type { PlaylistInfo } from '../../frontend/playlist';
+import { detectKittyGraphicsSupport } from '../../utils/kitty';
+import { getWindowManager, isFensterAvailable } from '../../rendering/nativeUi';
+import { logger } from '../../utils/logger';
+import { LOADING_INDICATOR_DELAY_MS } from './consts';
+
+export * from './consts';
+
+
+interface AppProps {
+  scanDepth: number;          // Max depth for scanning subdirectories (0=only dir, 1=+subdirs, -1=unlimited)
+  onRomSelected: (rom: RomInfo, filter: string, resumeGame?: boolean, netplay?: NetplayOptions) => void;
+  onExit: (filter: string) => void;
+  onRefresh: (filter: string) => void;  // Trigger a refresh of the ROM list
+  initialSelection?: string;  // Path of ROM to select initially
+  initialFilter?: string;     // Initial search filter to apply
+  config: Config;             // Current configuration
+  configPath?: string;        // Path to config file
+  showSettingsOnMount?: boolean;  // Show settings panel immediately on mount
+  lastPlayedRom?: RomInfo;        // ROM that was just played (for Resume Game option)
+  showNetplayOnMount?: boolean;   // Show netplay panel immediately on mount
+  kittyGraphicsSupported: boolean;  // Whether Kitty graphics protocol is supported
+  onScaleFactorChange?: (scaleFactor: number | null) => void;  // Callback for native UI scale changes
+}
+
+const LoadingState = ({ message = "Scanning for ROMs..." }: { message?: string }) => (
+  <Box padding={1}>
+    <Spinner label={message} />
+  </Box>
+);
+
+type AppState = 'loading' | 'prompt' | 'browser' | 'error';
+
+const App = ({ scanDepth, onRomSelected, onExit, onRefresh, initialSelection, initialFilter, config, configPath, showSettingsOnMount, lastPlayedRom, showNetplayOnMount, kittyGraphicsSupported, onScaleFactorChange }: AppProps) => {
+  const [roms, setRoms] = useState<RomInfo[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [appState, setAppState] = useState<AppState>('loading');
+  const [showLoadingUI, setShowLoadingUI] = useState(false);
+
+  // App capabilities for context (avoid prop drilling)
+  const capabilities: AppCapabilities = {
+    kittyGraphicsSupported,
+    nativeSupported: isFensterAvailable(),
+  };
+
+  // Resolve playlist directory from config (uses platform-specific default)
+  const playlistDirectory = getPlaylistsDirectory(config);
+
+  // Delay showing loading indicator to avoid flash for fast loads
+  useEffect(() => {
+    if (appState !== 'loading') {
+      setShowLoadingUI(false);
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      setShowLoadingUI(true);
+    }, LOADING_INDICATOR_DELAY_MS);
+
+    return () => clearTimeout(timer);
+  }, [appState]);
+
+  useEffect(() => {
+    const loadRoms = () => {
+      try {
+        // Check if there are any playlists
+        const playlists = findPlaylistsInDirectory(playlistDirectory);
+
+        if (playlists.length > 0) {
+          // Load all ROMs from playlists
+          const playlistRoms = loadRomsFromPlaylists(playlistDirectory, {
+            validateFiles: true,
+            checkSaveStates: true,
+          });
+
+          setRoms(playlistRoms);
+          setAppState('browser');
+        } else {
+          // No playlists found - show import prompt
+          setAppState('prompt');
+        }
+      } catch (err) {
+        setError(getErrorMessage(err));
+        setAppState('error');
+      }
+    };
+
+    loadRoms();
+  }, [playlistDirectory]);
+
+  // Handle playlist generation (after adding ROMs)
+  const handlePlaylistGenerated = useCallback((playlists: PlaylistInfo[]) => {
+    if (playlists.length > 0) {
+      // Load all ROMs from playlists
+      const playlistRoms = loadRomsFromPlaylists(playlistDirectory, {
+        validateFiles: true,
+        checkSaveStates: true,
+      });
+
+      setRoms(playlistRoms);
+      setAppState('browser');
+    }
+  }, [playlistDirectory]);
+
+  // Handle exit from prompt
+  const handlePromptExit = useCallback(() => {
+    onExit('');
+  }, [onExit]);
+
+  if (appState === 'error') {
+    return (
+      <AppCapabilitiesProvider capabilities={capabilities}>
+        <ConfigProvider initialConfig={config} configPath={configPath}>
+          <GamepadProvider>
+            <Box flexDirection="column" padding={1}>
+              <Text color="red">{'\u2717'} Error: {error}</Text>
+              <Text color="gray" dimColor>Press any key to exit</Text>
+            </Box>
+          </GamepadProvider>
+        </ConfigProvider>
+      </AppCapabilitiesProvider>
+    );
+  }
+
+  if (appState === 'loading') {
+    // Only show loading indicator after delay to avoid flash for fast loads
+    if (!showLoadingUI) {
+      return null;
+    }
+    return (
+      <AppCapabilitiesProvider capabilities={capabilities}>
+        <ConfigProvider initialConfig={config} configPath={configPath}>
+          <GamepadProvider>
+            <LoadingState message="Loading game library..." />
+          </GamepadProvider>
+        </ConfigProvider>
+      </AppCapabilitiesProvider>
+    );
+  }
+
+  if (appState === 'prompt') {
+    return (
+      <AppCapabilitiesProvider capabilities={capabilities}>
+        <ConfigProvider initialConfig={config} configPath={configPath}>
+          <GamepadProvider>
+            <AddRomsPrompt
+              directory={process.cwd()}
+              playlistDirectory={playlistDirectory}
+              scanDepth={scanDepth}
+              onPlaylistGenerated={handlePlaylistGenerated}
+              onExit={handlePromptExit}
+              exitAppOnCancel={true}
+            />
+          </GamepadProvider>
+        </ConfigProvider>
+      </AppCapabilitiesProvider>
+    );
+  }
+
+  return (
+    <AppCapabilitiesProvider capabilities={capabilities}>
+      <ConfigProvider initialConfig={config} configPath={configPath}>
+        <GamepadProvider>
+          <RomBrowser
+            roms={roms ?? []}
+            playlistDirectory={playlistDirectory}
+            scanDepth={scanDepth}
+            onSelect={onRomSelected}
+            onExit={onExit}
+            onRefresh={onRefresh}
+            initialSelection={initialSelection}
+            initialFilter={initialFilter}
+            showSettingsOnMount={showSettingsOnMount}
+            lastPlayedRom={lastPlayedRom}
+            showNetplayOnMount={showNetplayOnMount}
+            onScaleFactorChange={onScaleFactorChange}
+          />
+        </GamepadProvider>
+      </ConfigProvider>
+    </AppCapabilitiesProvider>
+  );
+};
+
+/** Netplay options selected from the UI */
+export interface NetplayOptions {
+  mode: 'host' | 'join';    // Host a session or join one
+  nickname: string;         // Player nickname
+  port: number;             // Port for netplay (default: 55435)
+  host?: string;            // Host address (only for join mode)
+  password?: string;        // Optional session password
+  inputDelay: number;       // Input delay frames (0-16)
+  spectate?: boolean;       // Join as spectator
+}
+
+/** Result from launching the ROM browser */
+export interface BrowserResult {
+  path: string | null;      // Selected ROM path, or null if cancelled
+  filter: string;           // Search filter that was active
+  shouldRefresh?: boolean;  // True if user triggered a refresh (e.g., after adding ROMs)
+  resumeGame?: boolean;     // True if user selected "Resume Game" from settings
+  resumeCoreId?: string;    // Core ID to use when resuming (bypasses core selector)
+  netplay?: NetplayOptions; // Netplay options if starting a netplay session
+}
+
+/**
+ * Launch the ROM browser UI.
+ * Loads all ROMs from playlists in the configured playlist directory.
+ */
+export const launchBrowser = async (scanDepth: number = 1, initialSelection?: string, initialFilter?: string, config?: Config, configPath?: string, showSettingsOnMount?: boolean, lastPlayedRom?: RomInfo, lastPlayedCoreId?: string, showNetplayOnMount?: boolean): Promise<BrowserResult> => {
+  // Detect Kitty graphics support before rendering
+  // This uses environment variables first (fast), then falls back to protocol query
+  const kittyGraphicsSupported = await detectKittyGraphicsSupport();
+
+  // Use provided config or fall back to defaults
+  const effectiveConfig: Config = config ?? DEFAULT_CONFIG;
+
+  // Check if we should use native mode
+  const nativeAvailable = isFensterAvailable();
+  const useNativeMode = effectiveConfig.video_driver === 'native' && nativeAvailable;
+
+  logger.info(
+    `Browser mode check: video_driver=${effectiveConfig.video_driver}, native=${nativeAvailable}, useNative=${useNativeMode}`,
+    'Native-UI'
+  );
+
+  // Warn if native mode was requested but the backend is unavailable
+  if (effectiveConfig.video_driver === 'native' && !useNativeMode) {
+    logger.warn('Native mode requested but the native window backend is unavailable, falling back to terminal', 'Native-UI');
+  }
+
+  const params: BrowserLaunchParams = {
+    scanDepth,
+    initialSelection,
+    initialFilter,
+    config: effectiveConfig,
+    configPath,
+    showSettingsOnMount,
+    lastPlayedRom,
+    lastPlayedCoreId,
+    showNetplayOnMount,
+    kittyGraphicsSupported,
+  };
+
+  if (useNativeMode) {
+    return launchBrowserNative(params);
+  }
+
+  // Terminal mode (default)
+  return launchBrowserTerminal(params);
+};
+
+/** Shared parameters for browser launch functions */
+interface BrowserLaunchParams {
+  scanDepth: number;
+  initialSelection?: string;
+  initialFilter?: string;
+  config: Config;
+  configPath?: string;
+  showSettingsOnMount?: boolean;
+  lastPlayedRom?: RomInfo;
+  lastPlayedCoreId?: string;
+  showNetplayOnMount?: boolean;
+  kittyGraphicsSupported: boolean;
+}
+
+/** Creates the shared handler callbacks and result builder for browser launch */
+const createBrowserHandlers = (params: BrowserLaunchParams) => {
+  let selectedPath: string | null = null;
+  let currentFilter: string = params.initialFilter ?? '';
+  let shouldRefresh = false;
+  let isResumeGame = false;
+  let resumeCoreId: string | undefined = undefined;
+  let netplayOptions: NetplayOptions | undefined = undefined;
+
+  const handleSelect = (rom: RomInfo, filter: string, resumeGame?: boolean, netplay?: NetplayOptions) => {
+    selectedPath = rom.path;
+    currentFilter = filter;
+    isResumeGame = resumeGame ?? false;
+    netplayOptions = netplay;
+    if (isResumeGame && params.lastPlayedCoreId) {
+      resumeCoreId = params.lastPlayedCoreId;
+    }
+  };
+
+  const handleExit = (filter: string) => {
+    currentFilter = filter;
+  };
+
+  const handleRefresh = (filter: string) => {
+    shouldRefresh = true;
+    currentFilter = filter;
+  };
+
+  const getResult = (): BrowserResult => ({
+    path: selectedPath,
+    filter: currentFilter,
+    shouldRefresh,
+    resumeGame: isResumeGame,
+    resumeCoreId,
+    netplay: netplayOptions,
+  });
+
+  return { handleSelect, handleExit, handleRefresh, getResult };
+};
+
+/**
+ * Launch browser in terminal mode (default)
+ */
+const launchBrowserTerminal = (params: BrowserLaunchParams): Promise<BrowserResult> => new Promise((resolve) => {
+  const { handleSelect, handleExit, handleRefresh, getResult } = createBrowserHandlers(params);
+
+  const instance = render(
+    <App
+      scanDepth={params.scanDepth}
+      onRomSelected={handleSelect}
+      onExit={handleExit}
+      onRefresh={handleRefresh}
+      initialSelection={params.initialSelection}
+      initialFilter={params.initialFilter}
+      config={params.config}
+      configPath={params.configPath}
+      showSettingsOnMount={params.showSettingsOnMount}
+      lastPlayedRom={params.lastPlayedRom}
+      showNetplayOnMount={params.showNetplayOnMount}
+      kittyGraphicsSupported={params.kittyGraphicsSupported}
+    />,
+    { exitOnCtrlC: false }
+  );
+
+  void instance.waitUntilExit().then(() => {
+    cleanupInkInstance(instance, resolve, getResult());
+  });
+});
+
+/**
+ * Launch browser in native window mode
+ * Creates/reuses the shared native window and routes Ink rendering through ink-native streams
+ */
+const launchBrowserNative = (params: BrowserLaunchParams): Promise<BrowserResult> => new Promise((resolve) => {
+  const { handleSelect, handleExit, handleRefresh, getResult } = createBrowserHandlers(params);
+  const windowManager = getWindowManager();
+  try {
+    if (!windowManager.isInitialized()) {
+      windowManager.init({ title: 'emoemu - Game Library', scaleFactor: params.config.menu_scale_factor });
+    }
+    windowManager.setMode('ui');
+
+    const stdin = windowManager.getStdin();
+    const stdout = windowManager.getStdout();
+    const window = windowManager.getWindow();
+    windowManager.clearScreen();
+
+    const onClose = () => { stdin.push('\x1b'); };
+    window.on('close', onClose);
+    logger.info('Native UI mode enabled for browser (shared window)', 'Native-UI');
+
+    // NOTE: ink-native has no runtime setScaleFactor. menu_scale_factor is applied
+    // at window creation; live changes take effect on next launch.
+    const handleScaleFactorChange = (_scaleFactor: number | null) => {
+      // Persisted to config by the settings panel; re-render UI to reflect other changes.
+      stdout.emit('resize');
+    };
+
+    const instance = render(
+      <App
+        scanDepth={params.scanDepth}
+        onRomSelected={handleSelect}
+        onExit={handleExit}
+        onRefresh={handleRefresh}
+        initialSelection={params.initialSelection}
+        initialFilter={params.initialFilter}
+        config={params.config}
+        configPath={params.configPath}
+        showSettingsOnMount={params.showSettingsOnMount}
+        lastPlayedRom={params.lastPlayedRom}
+        showNetplayOnMount={params.showNetplayOnMount}
+        kittyGraphicsSupported={params.kittyGraphicsSupported}
+        onScaleFactorChange={handleScaleFactorChange}
+      />,
+      {
+        exitOnCtrlC: false,
+        stdout: stdout as unknown as NodeJS.WriteStream,
+        stdin: stdin as unknown as NodeJS.ReadStream,
+      }
+    );
+
+    void instance.waitUntilExit().then(() => {
+      // Do NOT close the shared window here — only detach this screen's listener.
+      window.off('close', onClose);
+      windowManager.getRenderer().reset();
+      resolve(getResult());
+    });
+  } catch (error) {
+    logger.warn(`Native UI failed, falling back to terminal: ${error}`, 'Native-UI');
+    void launchBrowserTerminal(params).then(resolve);
+  }
+});
+
+export default App;
+
+/**
+ * Import ROMs from a directory with progress UI.
+ * Shows a progress bar during scanning, then auto-continues when done.
+ */
+export const importDirectory = async (directory: string, scanDepth: number, config: Config): Promise<void> => new Promise((resolve) => {
+  const playlistDirectory = getPlaylistsDirectory(config);
+
+  const handleComplete = () => {
+    // Import complete - resolve immediately
+  };
+
+  const handleExit = () => {
+    // User cancelled - still resolve (they can try again later)
+  };
+
+  const instance = render(
+    <GamepadProvider>
+      <AddRomsPrompt
+        directory={directory}
+        playlistDirectory={playlistDirectory}
+        scanDepth={scanDepth}
+        onPlaylistGenerated={handleComplete}
+        onExit={handleExit}
+        autoImport={true}
+      />
+    </GamepadProvider>
+  );
+
+  // Wait for the UI to exit, then clean up
+  void instance.waitUntilExit().then(() => {
+    cleanupInkInstance(instance, resolve, undefined);
+  });
+});

package/src/ui/AppCapabilities/index.tsx

@@ -0,0 +1,67 @@
+/**
+ * App Capabilities Context
+ *
+ * Provides app-wide information about terminal and system capabilities.
+ * This avoids prop drilling for commonly needed capability flags.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+/**
+ * App capabilities that are detected at startup and available throughout the app.
+ */
+export interface AppCapabilities {
+  /** Whether the terminal supports Kitty graphics protocol */
+  kittyGraphicsSupported: boolean;
+  /** Whether the native window backend is available for rendering */
+  nativeSupported: boolean;
+}
+
+const AppCapabilitiesContext = createContext<AppCapabilities | null>(null);
+
+interface AppCapabilitiesProviderProps {
+  children: ReactNode;
+  capabilities: AppCapabilities;
+}
+
+/**
+ * Provider for app-wide capabilities.
+ * Should wrap the entire app (or UI tree) to make capabilities available.
+ */
+export const AppCapabilitiesProvider = ({ children, capabilities }: AppCapabilitiesProviderProps) => {
+  return (
+    <AppCapabilitiesContext.Provider value={capabilities}>
+      {children}
+    </AppCapabilitiesContext.Provider>
+  );
+};
+
+/**
+ * Hook to access app capabilities.
+ * Must be used within an AppCapabilitiesProvider.
+ *
+ * @throws Error if used outside of AppCapabilitiesProvider
+ */
+export const useAppCapabilities = (): AppCapabilities => {
+  const context = useContext(AppCapabilitiesContext);
+  if (!context) {
+    throw new Error('useAppCapabilities must be used within an AppCapabilitiesProvider');
+  }
+  return context;
+};
+
+/**
+ * Hook to check if Kitty graphics protocol is supported.
+ * Convenience wrapper around useAppCapabilities.
+ */
+export const useKittyGraphicsSupported = (): boolean => {
+  return useAppCapabilities().kittyGraphicsSupported;
+};
+
+/**
+ * Hook to check if the native window backend is supported.
+ * Convenience wrapper around useAppCapabilities.
+ */
+export const useNativeSupported = (): boolean => {
+  return useAppCapabilities().nativeSupported;
+};

package/src/ui/ConfigContext/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * Config Context
+ *
+ * Provides app-wide config state and config file path.
+ * This avoids prop drilling config through RomBrowser and SettingsPanel.
+ */
+
+import { createContext, useContext, useState, useCallback, type ReactNode } from 'react';
+import type { Config } from '../../frontend/config';
+import { loadConfig } from '../../frontend/config';
+
+interface ConfigContextValue {
+  config: Config;
+  configPath?: string;
+  setConfig: (config: Config) => void;
+  reloadConfig: () => void;
+}
+
+const ConfigContext = createContext<ConfigContextValue | null>(null);
+
+interface ConfigProviderProps {
+  children: ReactNode;
+  initialConfig: Config;
+  configPath?: string;
+}
+
+/**
+ * Provider for app-wide config state.
+ * Should wrap the UI tree to make config available via useConfig().
+ */
+export const ConfigProvider = ({ children, initialConfig, configPath }: ConfigProviderProps) => {
+  const [config, setConfig] = useState(initialConfig);
+
+  const reloadConfig = useCallback(() => {
+    const { config: reloaded } = loadConfig(configPath);
+    setConfig(reloaded);
+  }, [configPath]);
+
+  return (
+    <ConfigContext.Provider value={{ config, configPath, setConfig, reloadConfig }}>
+      {children}
+    </ConfigContext.Provider>
+  );
+};
+
+/**
+ * Hook to access config context.
+ * Must be used within a ConfigProvider.
+ */
+export const useConfig = (): ConfigContextValue => {
+  const context = useContext(ConfigContext);
+  if (!context) {
+    throw new Error('useConfig must be used within a ConfigProvider');
+  }
+  return context;
+};

package/src/ui/CoreManager/consts.ts

@@ -0,0 +1,11 @@
+/** Tab indices */
+export const TAB_INSTALLED = 0;
+export const TAB_DOWNLOAD = 1;
+
+/** UI layout constants */
+export const PANEL_PADDING = 1;
+export const LIST_ITEM_HEIGHT = 1;
+export const MAX_VISIBLE_ITEMS = 15;
+
+/** Bytes per kilobyte for display formatting */
+export const BYTES_PER_KB = 1024;