emoemu 0.1.0

package/src/frontend/coreRegistry/index.ts

@@ -0,0 +1,276 @@
+/**
+ * Core Registry
+ *
+ * Discovers and instantiates emulator cores based on ROM file extension.
+ * This allows automatic core selection when loading a ROM.
+ */
+
+import { pipe, map, sortBy, flatMap, unique, identity } from 'remeda';
+import type { Core, SystemInfo } from '../../core/core';
+import { getDatabaseName, PLAYLIST_EXTENSION, DEFAULT_DATABASE_NAME } from '../playlist';
+
+/**
+ * Options that can be passed when creating a core instance
+ */
+export interface CoreCreateOptions {
+  /** Core-specific options (for libretro cores, in RetroArch format) */
+  coreOptions?: Record<string, string>;
+  /** System directory path for BIOS files */
+  systemDirectory?: string;
+  /** Save directory path */
+  saveDirectory?: string;
+}
+
+/**
+ * Factory function for creating a core instance
+ */
+export interface CoreFactory {
+  /** Create a new instance of the core, optionally with configuration options */
+  create(options?: CoreCreateOptions): Core;
+
+  /** File extensions this core handles (lowercase, with dot) */
+  extensions: string[];
+
+  /** Get system info without creating a full core instance */
+  getSystemInfo(): SystemInfo;
+
+  /** Path to the core file */
+  path?: string;
+}
+
+/**
+ * Registry of available cores
+ */
+const coreFactories = new Map<string, CoreFactory>();
+
+/**
+ * Pre-computed map of extension → matching cores (sorted).
+ * Built lazily on first access, invalidated when cores are registered.
+ */
+let extensionToCoresCache: Map<string, Array<{ id: string; factory: CoreFactory }>> | null = null;
+
+/**
+ * Cached list of all supported extensions.
+ * Built lazily on first access, invalidated when cores are registered.
+ */
+let supportedExtensionsCache: string[] | null = null;
+
+/**
+ * Build the extension→cores lookup map from registered cores.
+ * Cores are pre-sorted: libretro first, then alphabetically.
+ */
+const buildExtensionMap = (): Map<string, Array<{ id: string; factory: CoreFactory }>> => {
+  const extMap = new Map<string, Array<{ id: string; factory: CoreFactory }>>();
+
+  // Collect all cores for each extension
+  for (const [id, factory] of coreFactories) {
+    for (const ext of factory.extensions) {
+      const existing = extMap.get(ext) ?? [];
+      existing.push({ id, factory });
+      extMap.set(ext, existing);
+    }
+  }
+
+  // Sort each extension's cores alphabetically
+  for (const [ext, cores] of extMap) {
+    extMap.set(ext, pipe(
+      cores,
+      sortBy(
+        [({ id }) => id, 'asc']
+      )
+    ));
+  }
+
+  return extMap;
+};
+
+/**
+ * Get the extension→cores map, building it if necessary.
+ */
+const getExtensionMap = (): Map<string, Array<{ id: string; factory: CoreFactory }>> => {
+  if (!extensionToCoresCache) {
+    extensionToCoresCache = buildExtensionMap();
+  }
+  return extensionToCoresCache;
+};
+
+/**
+ * Register a core factory.
+ * Called by each core module to make itself available.
+ *
+ * @param id Unique core identifier (e.g., "nes", "gba")
+ * @param factory Factory for creating core instances
+ */
+export const registerCore = (id: string, factory: CoreFactory): void => {
+  if (coreFactories.has(id)) {
+    throw new Error(`Core '${id}' is already registered`);
+  }
+  coreFactories.set(id, factory);
+  // Invalidate caches so they're rebuilt on next access
+  extensionToCoresCache = null;
+  supportedExtensionsCache = null;
+};
+
+/**
+ * Unregister a core factory.
+ * Used when deleting a libretro core to remove it from the registry.
+ *
+ * @param id Core identifier to unregister
+ * @returns true if the core was registered and removed, false if not found
+ */
+export const unregisterCore = (id: string): boolean => {
+  const existed = coreFactories.has(id);
+  coreFactories.delete(id);
+  // Invalidate caches so they're rebuilt on next access
+  extensionToCoresCache = null;
+  supportedExtensionsCache = null;
+  return existed;
+};
+
+/**
+ * Get a core factory by ID.
+ *
+ * @param id Core identifier
+ * @returns Core factory or undefined if not found
+ */
+export const getCoreFactory = (id: string): CoreFactory | undefined => coreFactories.get(id);
+
+/**
+ * Create a core instance by ID.
+ *
+ * @param id Core identifier
+ * @param options Optional configuration for the core (e.g., core options, directories)
+ * @returns New core instance or null if core not found
+ */
+export const createCore = (id: string, options?: CoreCreateOptions): Core | null => {
+  const factory = coreFactories.get(id);
+  return factory ? factory.create(options) : null;
+};
+
+/**
+ * Find all cores that support a given ROM file extension.
+ * Uses pre-computed extension→cores map for O(1) lookup.
+ *
+ * @param romPath Path to the ROM file
+ * @returns Array of matching cores with their IDs and factories
+ */
+export const findMatchingCores = (romPath: string): Array<{ id: string; factory: CoreFactory }> => {
+  const ext = romPath.toLowerCase().match(/\.[^.]+$/)?.[0];
+  if (!ext) {
+    return [];
+  }
+
+  // O(1) lookup from pre-computed map (already sorted)
+  return getExtensionMap().get(ext) ?? [];
+};
+
+/**
+ * Find all cores that support a given file extension directly.
+ * Useful when extension is already extracted.
+ *
+ * @param ext File extension (lowercase, with dot)
+ * @returns Array of matching cores with their IDs and factories
+ */
+export const findMatchingCoresByExtension = (ext: string): Array<{ id: string; factory: CoreFactory }> => {
+  return getExtensionMap().get(ext.toLowerCase()) ?? [];
+};
+
+/**
+ * Detect the appropriate core for a ROM file based on extension.
+ *
+ * @param romPath Path to the ROM file
+ * @returns Core factory or undefined if no matching core found
+ */
+export const detectCoreFactory = (romPath: string): CoreFactory | undefined => {
+  const matches = findMatchingCores(romPath);
+  return matches.length > 0 ? matches[0].factory : undefined;
+};
+
+/**
+ * Detect and create the appropriate core for a ROM file.
+ *
+ * @param romPath Path to the ROM file
+ * @param options Optional configuration for the core (e.g., core options, directories)
+ * @returns New core instance or null if no matching core found
+ */
+export const detectCore = (romPath: string, options?: CoreCreateOptions): Core | null => {
+  const factory = detectCoreFactory(romPath);
+  return factory ? factory.create(options) : null;
+};
+
+/**
+ * Check if a ROM file extension is supported by any registered core.
+ *
+ * @param romPath Path to the ROM file
+ * @returns true if a core can handle this file type
+ */
+export const isRomSupported = (romPath: string): boolean => detectCoreFactory(romPath) !== undefined;
+
+/**
+ * Get list of all registered cores with their info.
+ *
+ * @returns Array of core information objects
+ */
+export const listCores = (): Array<{
+  id: string;
+  name: string;
+  extensions: string[];
+  path: string;
+}> => pipe(
+  Array.from(coreFactories.entries()),
+  map(([id, factory]) => ({
+    id,
+    name: factory.getSystemInfo().name,
+    extensions: factory.extensions,
+    path: factory.path ?? "",
+  }))
+);
+
+/**
+ * Get all supported file extensions across all cores.
+ * Result is cached and invalidated when cores are registered.
+ *
+ * @returns Array of supported extensions (lowercase, with dot)
+ */
+export const getSupportedExtensions = (): string[] => {
+  if (!supportedExtensionsCache) {
+    supportedExtensionsCache = pipe(
+      Array.from(coreFactories.values()),
+      flatMap((factory) => factory.extensions),
+      unique(),
+      sortBy([identity(), 'asc'])
+    );
+  }
+  return supportedExtensionsCache;
+};
+
+/** System name for unknown/unmapped extensions */
+const UNKNOWN_SYSTEM_NAME = DEFAULT_DATABASE_NAME.replace(PLAYLIST_EXTENSION, '');
+
+/**
+ * Get unique supported system names based on installed cores.
+ * Returns RetroArch-style system names (e.g., "Nintendo - Nintendo Entertainment System").
+ */
+export const getSupportedSystems = (): string[] => {
+  const systems = new Set<string>();
+  // Get extensions from installed cores and map to system names
+  for (const ext of getSupportedExtensions()) {
+    const dbName = getDatabaseName(ext);
+    // Remove .lpl extension to get system name
+    const systemName = dbName.replace(PLAYLIST_EXTENSION, '');
+    // Skip the fallback "Unknown System" entry
+    if (systemName !== UNKNOWN_SYSTEM_NAME) {
+      systems.add(systemName);
+    }
+  }
+  /** Unique system names, sorted alphabetically */
+  return Array.from(systems).sort();
+};
+
+/**
+ * Get the number of registered cores.
+ */
+export const getCoreCount = (): number => coreFactories.size;
+
+// Note: Cores register themselves when their modules are imported.
+// This allows tree-shaking of unused cores in production builds.

package/src/frontend/directoryCache/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Directory Cache
+ *
+ * Shared utility for caching directory listings to avoid repeated stat() calls.
+ * Used by rom-scanner and playlist reader for efficient file existence checks.
+ */
+
+import { readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Cache for directory listings to avoid repeated stat() calls.
+ * Maps directory path -> filename -> file modification time.
+ */
+export type DirectoryCache = Map<string, Map<string, Date>>;
+
+/**
+ * Create a new empty directory cache.
+ */
+export const createDirectoryCache = (): DirectoryCache => new Map();
+
+/**
+ * Get or create a cached directory listing.
+ * Returns a map of filename -> mtime for all files in the directory.
+ * Skips hidden files (starting with '.').
+ */
+export const getCachedDirectoryListing = (dirPath: string, cache: DirectoryCache): Map<string, Date> => {
+  const existing = cache.get(dirPath);
+  if (existing) {
+    return existing;
+  }
+
+  const listing = new Map<string, Date>();
+  try {
+    // Use withFileTypes to avoid stat() calls just to check isFile()
+    const entries = readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip hidden files and directories (only stat actual files)
+      if (entry.name.startsWith('.') || !entry.isFile()) {
+        continue;
+      }
+      try {
+        const fullPath = join(dirPath, entry.name);
+        const stats = statSync(fullPath);
+        listing.set(entry.name, stats.mtime);
+      } catch {
+        // Skip files we can't stat
+      }
+    }
+  } catch {
+    // Directory doesn't exist or can't be read
+  }
+  cache.set(dirPath, listing);
+  return listing;
+};
+
+/**
+ * Check if a file exists in a cached directory listing.
+ * Returns the file's modification time if found, undefined otherwise.
+ */
+export const getFileFromCache = (
+  dirPath: string,
+  filename: string,
+  cache: DirectoryCache
+): Date | undefined => {
+  const listing = getCachedDirectoryListing(dirPath, cache);
+  return listing.get(filename);
+};
+
+/**
+ * Clear all entries from a directory cache.
+ */
+export const clearDirectoryCache = (cache: DirectoryCache): void => {
+  cache.clear();
+};

package/src/frontend/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Frontend Module Exports
+ *
+ * Shared frontend infrastructure for all emulator cores.
+ */
+
+export * from './consts';
+export { AudioManager } from './AudioManager';
+export {
+  type DirectoryCache,
+  createDirectoryCache,
+  getCachedDirectoryListing,
+  getFileFromCache,
+  clearDirectoryCache,
+} from './directoryCache';
+export { SaveStateService, BatterySaveService } from './saveServices';
+export type { SaveStateDetails, SaveStateCheckResult, BatterySaveCheckResult } from './saveServices';
+export {
+  initializeServices,
+  updateServices,
+  getSaveStateService,
+  getBatterySaveService,
+  areServicesInitialized,
+  getConfig,
+  getPlaylistDirectory,
+  buildCrcCache,
+} from './serviceProvider';
+export {
+  registerCore,
+  getCoreFactory,
+  createCore,
+  detectCoreFactory,
+  detectCore,
+  isRomSupported,
+  listCores,
+  getSupportedExtensions,
+  getCoreCount,
+} from './coreRegistry';
+export type { CoreFactory } from './coreRegistry';
+export {
+  loadConfig,
+  updateConfigValue,
+  configExists,
+  ensureConfigExists,
+  DEFAULT_CONFIG,
+} from './config';
+export type { Config, VideoDriver } from './config';
+export { SettingsManager } from './SettingsManager';
+export type { RuntimeSettings, RenderMode } from './SettingsManager';
+export {
+  generatePlaylist,
+  writePlaylist,
+  generateAndWritePlaylist,
+  generatePlaylistsBySystem,
+  generateConsolidatedPlaylist,
+  createPlaylistEntry,
+  getDatabaseName,
+  updatePlaylistRuntime,
+  PLAYLIST_VERSION,
+  PLAYLIST_EXTENSION,
+  // Reader functions
+  readPlaylist,
+  playlistEntryToRomInfo,
+  playlistToRomInfoArray,
+  findPlaylistsInDirectory,
+  findPlaylistsForDirectory,
+  loadRomsFromPlaylists,
+} from './playlist';
+export type {
+  PlaylistEntry,
+  PlaylistFile,
+  PlaylistOptions,
+  PlaylistGenerationResult,
+  PlaylistUpdateResult,
+  // Reader types
+  PlaylistReadResult,
+  PlaylistInfo,
+  ConversionOptions,
+} from './playlist';

package/src/frontend/notifications/consts.ts

@@ -0,0 +1,14 @@
+export const APP_NAME = 'emoemu';
+export const ICON_FILENAME = 'icon.png';
+export const DEFAULT_NOTIFICATION_DURATION_MS = 3000;
+
+/**
+ * Numeric values for notification severity (matches libretro SET_MESSAGE_EXT).
+ * Useful for converting from libretro numeric values.
+ */
+export const NOTIFICATION_SEVERITY = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+} as const;

package/src/frontend/notifications/index.ts

@@ -0,0 +1,250 @@
+/**
+ * Unified notification system for emoemu.
+ * Sends notifications to both native OS (via node-notifier) and any subscribed listeners
+ * (e.g., the emulator's status bar). Any part of the app can send notifications through
+ * this module, and all subscribers will receive them.
+ */
+
+import notifier from 'node-notifier';
+import { existsSync, writeFileSync } from 'fs';
+import { ensureDirectory } from '../../utils/ensureDirectory';
+import { join } from 'path';
+import { getConfigDirectory } from '../../utils/paths';
+
+export * from './consts';
+
+import { APP_NAME, ICON_FILENAME, DEFAULT_NOTIFICATION_DURATION_MS } from './consts';
+
+// App icon embedded at build time as base64
+declare const __APP_ICON_BASE64__: string;
+const APP_ICON_BASE64 = typeof __APP_ICON_BASE64__ !== 'undefined' ? __APP_ICON_BASE64__ : '';
+
+/** Whether notifications are enabled (default: true) */
+let notificationsEnabled = true;
+
+/** Cached path to the extracted icon */
+let iconPath: string | null = null;
+
+/**
+ * Notification severity - indicates how important/urgent a user-facing notification is.
+ * Values match libretro's severity levels for SET_MESSAGE_EXT compatibility.
+ */
+export type NotificationSeverity = 'debug' | 'info' | 'warn' | 'error';
+
+import { NOTIFICATION_SEVERITY } from './consts';
+
+/**
+ * Convert numeric severity to NotificationSeverity string.
+ */
+export const numericToSeverity = (value: number): NotificationSeverity => {
+  switch (value) {
+    case NOTIFICATION_SEVERITY.DEBUG: return 'debug';
+    case NOTIFICATION_SEVERITY.WARN: return 'warn';
+    case NOTIFICATION_SEVERITY.ERROR: return 'error';
+    default: return 'info';
+  }
+};
+
+/**
+ * App-wide notification that can be displayed in multiple places
+ * (native OS notifications, status bar, etc.)
+ */
+export interface AppNotification {
+  /** Optional title (defaults to app name for OS notifications) */
+  title?: string;
+  /** Main message content */
+  message: string;
+  /** Duration in ms for transient displays like status bar (default: 3000) */
+  duration?: number;
+  /** Whether to play a sound (for OS notifications) */
+  sound?: boolean;
+  /** Severity/importance of the notification (default: 'info') */
+  severity?: NotificationSeverity;
+}
+
+/** Callback for receiving notifications */
+export type NotificationListener = (notification: AppNotification) => void;
+
+/** Registered notification listeners */
+const listeners = new Set<NotificationListener>();
+
+/**
+ * Subscribe to receive all app notifications.
+ * Useful for displaying notifications in UI elements like the status bar.
+ */
+export const subscribeToNotifications = (listener: NotificationListener): void => {
+  listeners.add(listener);
+};
+
+/**
+ * Unsubscribe from notifications.
+ */
+export const unsubscribeFromNotifications = (listener: NotificationListener): void => {
+  listeners.delete(listener);
+};
+
+/**
+ * Set whether notifications are enabled.
+ */
+export const setNotificationsEnabled = (enabled: boolean): void => {
+  notificationsEnabled = enabled;
+};
+
+/**
+ * Check if notifications are enabled.
+ */
+export const isNotificationsEnabled = (): boolean => notificationsEnabled;
+
+/**
+ * Ensure the app icon exists in the config directory.
+ * Extracts the embedded icon on first run.
+ * @returns The absolute path to the icon, or undefined if not available
+ */
+export const ensureIcon = (): string | undefined => {
+  // Return cached path if already extracted
+  if (iconPath !== null) {
+    return iconPath.length > 0 ? iconPath : undefined;
+  }
+
+  // No embedded icon available
+  if (!APP_ICON_BASE64) {
+    iconPath = '';
+    return undefined;
+  }
+
+  // Wrap all icon operations in try-catch - icon is nice-to-have, not required
+  try {
+    const configDir = getConfigDirectory();
+    const targetPath = join(configDir, ICON_FILENAME);
+
+    // Check if icon already exists
+    if (existsSync(targetPath)) {
+      iconPath = targetPath;
+      return iconPath;
+    }
+
+    ensureDirectory(configDir);
+
+    // Extract icon from embedded base64
+    const iconBuffer = Buffer.from(APP_ICON_BASE64, 'base64');
+    writeFileSync(targetPath, iconBuffer);
+    iconPath = targetPath;
+    return iconPath;
+  } catch {
+    // Any failure with icon detection/extraction - continue without it
+    iconPath = '';
+    return undefined;
+  }
+};
+
+/**
+ * Send a notification to all channels (native OS and subscribed listeners).
+ * This is the primary way to send notifications throughout the app.
+ */
+export const notify = (options: AppNotification): void => {
+  if (!notificationsEnabled) {
+    return;
+  }
+
+  // Broadcast to all listeners (e.g., status bar)
+  const notification: AppNotification = {
+    title: options.title,
+    message: options.message,
+    duration: options.duration ?? DEFAULT_NOTIFICATION_DURATION_MS,
+    sound: options.sound,
+    severity: options.severity ?? 'info',
+  };
+  for (const listener of listeners) {
+    listener(notification);
+  }
+
+  // Send to native OS notification system
+  const icon = ensureIcon();
+  notifier.notify({
+    title: options.title ?? APP_NAME,
+    message: options.message,
+    sound: options.sound ?? false,
+    icon,
+  });
+};
+
+/**
+ * Notify that a screenshot was saved.
+ */
+export const notifyScreenshotSaved = (filename: string): void => {
+  notify({
+    title: 'Screenshot Saved',
+    message: filename,
+  });
+};
+
+/**
+ * Notify that a gamepad was connected.
+ */
+export const notifyGamepadConnected = (name: string, playerNumber: number): void => {
+  notify({
+    title: 'Gamepad Connected',
+    message: `${name} (Player ${playerNumber})`,
+  });
+};
+
+/**
+ * Notify that a gamepad was disconnected.
+ */
+export const notifyGamepadDisconnected = (name: string, playerNumber: number): void => {
+  notify({
+    title: 'Gamepad Disconnected',
+    message: `${name} (Player ${playerNumber})`,
+  });
+};
+
+/**
+ * Notify with a core message (from libretro cores or internal events).
+ */
+export const notifyCoreMessage = (message: string, title?: string): void => {
+  notify({
+    title: title ?? 'emoemu',
+    message,
+  });
+};
+
+/**
+ * Notify that a netplay client connected.
+ */
+export const notifyNetplayClientConnected = (nickname: string, playerNumber: number): void => {
+  notify({
+    title: 'Player Joined',
+    message: `${nickname} joined as Player ${playerNumber}`,
+  });
+};
+
+/**
+ * Notify that a netplay client disconnected.
+ */
+export const notifyNetplayClientDisconnected = (nickname: string): void => {
+  notify({
+    title: 'Player Left',
+    message: `${nickname} disconnected`,
+  });
+};
+
+/**
+ * Notify that a netplay spectator connected.
+ */
+export const notifyNetplaySpectatorConnected = (nickname: string): void => {
+  notify({
+    title: 'Spectator Joined',
+    message: `${nickname} is now spectating`,
+  });
+};
+
+/**
+ * Notify that a netplay connection failed.
+ */
+export const notifyNetplayConnectionFailed = (nickname: string, reason: string): void => {
+  notify({
+    title: 'Connection Failed',
+    message: `${nickname}: ${reason}`,
+    severity: 'warn',
+  });
+};