koin.js 1.0.6 → 1.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 ## Browser Retro Game Emulation for React
 
-> **27 systems. Cloud saves. Zero backend required.**
+> **28 systems. Cloud saves. Multi-language. Zero backend required.**
 
 [![Try the Demo](https://img.shields.io/badge/PLAY-TRY%20THE%20DEMO-FFD600?style=for-the-badge&logoColor=black&labelColor=black)](https://koin.js.org/)
 [![NPM Version](https://img.shields.io/npm/v/koin.js?style=for-the-badge&color=white&labelColor=black)](https://www.npmjs.com/package/koin.js)
@@ -14,13 +14,58 @@ The drop-in React component for browser-based retro game emulation. Built on [No
 
 ## Features
 
-- 🎮 **27 Systems** — NES to PlayStation, Game Boy to Arcade
-- ☁️ **Cloud-Ready Saves** — Slot-based saves with screenshots, auto-save, emergency saves
-- ⏪ **Rewind Time** — Go back in time (auto-enabled for 8/16-bit systems)
-- 🏆 **RetroAchievements** — Official RA integration with hardcore mode
-- 📱 **Touch Controls** — GPU-accelerated virtual D-pad and buttons
-- 📹 **Gameplay Recording** — VP9 WebM capture at 30fps
-- 🎨 **10 CRT Shaders** — Lottes, Geom, zFast, LCD Grid, and more
+### 🎮 Core Emulation
+- **28 Consoles** — NES to PlayStation, Game Boy to Dreamcast
+- **Automatic Core Selection** — Best emulator core per system
+- **BIOS Management** — Multi-file BIOS support with UI selection
+- **Performance Optimized** — SharedArrayBuffer for maximum speed
+
+### ☁️ Save System
+- **Slot-Based Saves** — Multiple save states with screenshots
+- **Auto-Save** — Periodic background saves (configurable interval)
+- **Emergency Saves** — Automatic save on tab hide/close
+- **Cloud-Ready API** — Bring your own backend with async handlers
+
+### 🎨 Display & Effects
+- **10 CRT Shaders** — Lottes, Geom, Easymode, Hyllian, zFast, and more
+- **Runtime Shader Switching** — Change filters without restart
+- **System Theming** — Per-console accent colors
+- **Screenshot Capture** — PNG snapshots with hotkey support
+
+### 🕹️ Controls
+- **Keyboard Remapping** — Per-console custom key bindings
+- **Gamepad Support** — Auto-detect Xbox, PlayStation, Nintendo controllers
+- **Touch Controls** — GPU-accelerated virtual D-pad and buttons for mobile
+- **Control Persistence** — Saves user preferences across sessions
+
+### ⏪ Special Features
+- **Rewind** — Time-travel gameplay (auto-enabled for 8/16-bit)
+- **Speed Control** — 0.25x to 4x with hotkey toggle
+- **Fast-Forward** — Turbo mode for grinding
+
+### 📹 Recording & Overlays
+- **Gameplay Recording** — VP9/VP8 WebM capture at 30fps
+- **Performance Overlay** — FPS, frame time, memory stats
+- **Input Display** — Virtual controller overlay for streaming
+- **Toast Notifications** — Non-intrusive save/load feedback
+
+### 🏆 RetroAchievements
+- **Official RA Integration** — Track unlocks across sessions
+- **Hardcore Mode** — Disable saves/cheats for leaderboard eligibility
+- **Achievement Browser** — Filter by locked/unlocked status
+- **Progress Tracking** — Points remaining per game
+
+### 🌍 Internationalization
+- **3 Built-in Languages** — English, Spanish, French
+- **Type-Safe Translations** — Full TypeScript support
+- **Partial Overrides** — Customize specific strings
+- **Custom Languages** — Implement your own translation set
+
+### 🎯 Developer Experience
+- **TypeScript First** — Complete type definitions
+- **Zero Config** — Works out of the box
+- **Customizable UI** — Accent colors, shaders, controls
+- **Web Component** — Use without React
 
 ## Installation
 
@@ -36,6 +81,7 @@ pnpm add koin.js
 
 ```tsx
 import { GamePlayer } from 'koin.js';
+import 'koin.js/styles.css';
 
 export default function App() {
   return (
@@ -60,14 +106,45 @@ import { GamePlayer } from 'koin.js';
   system="NES"
   title="My Game"
   
-  // Your backend handlers
-  onSaveState={async (slot, blob, screenshot) => { /* save to your API */ }}
-  onLoadState={async (slot) => { /* return Blob or null */ }}
-  onAutoSave={async (blob, screenshot) => { /* periodic save */ }}
+  // Cloud save handlers
+  onSaveState={async (slot, blob, screenshot) => {
+    await fetch(`/api/saves/${slot}`, {
+      method: 'POST',
+      body: blob,
+    });
+  }}
+  onLoadState={async (slot) => {
+    const res = await fetch(`/api/saves/${slot}`);
+    return res.ok ? await res.blob() : null;
+  }}
+  onAutoSave={async (blob, screenshot) => {
+    await fetch('/api/autosave', { method: 'POST', body: blob });
+  }}
   
-  // Optional theming
+  // Customization
   systemColor="#FF3333"
   shader="crt/crt-lottes"
+  initialLanguage="es"
+/>
+```
+
+## Internationalization
+
+```tsx
+<GamePlayer
+  initialLanguage="es"  // Spanish UI
+/>
+
+// Or provide custom translations
+import { en } from 'koin.js';
+
+<GamePlayer
+  translations={{
+    controls: {
+      ...en.controls,
+      play: 'START GAME',
+    }
+  }}
 />
 ```
 
@@ -91,18 +168,30 @@ import { GamePlayer } from 'koin.js';
 | NES / Famicom | `NES` | fceumm |
 | Super Nintendo | `SNES` | snes9x |
 | Nintendo 64 | `N64` | mupen64plus_next |
-| Game Boy / Color / Advance | `GB`, `GBC`, `GBA` | gambatte, mgba |
+| Game Boy / Color | `GB`, `GBC` | gambatte |
+| Game Boy Advance | `GBA` | mgba |
 | Nintendo DS | `NDS` | desmume |
 | PlayStation | `PS1` | pcsx_rearmed |
 | PSP | `PSP` | ppsspp |
-| Genesis / Mega Drive | `GENESIS` | genesis_plus_gx |
-| Master System | `MASTER_SYSTEM` | gearsystem |
+| Sega Genesis / Mega Drive | `GENESIS` | genesis_plus_gx |
+| Sega Master System | `MASTER_SYSTEM` | gearsystem |
 | Game Gear | `GAME_GEAR` | gearsystem |
-| Saturn | `SATURN` | yabasanshiro |
-| Dreamcast | `DREAMCAST` | flycast |
+| Sega Saturn | `SATURN` | yabasanshiro |
+| Sega Dreamcast | `DREAMCAST` | flycast |
+| Sega CD | `SEGA_CD` | genesis_plus_gx |
 | Neo Geo | `NEOGEO` | fbalpha2012_neogeo |
 | Arcade (MAME) | `ARCADE` | mame2003_plus |
-| ...and 13 more | [See full list](https://koin.js.org/docs/systems) |
+| Atari 2600 | `ATARI2600` | stella |
+| Atari 7800 | `ATARI7800` | prosystem |
+| Atari Lynx | `LYNX` | handy |
+| PC Engine / TurboGrafx-16 | `PCE` | mednafen_pce |
+| WonderSwan / Color | `WS`, `WSC` | mednafen_wswan |
+| Virtual Boy | `VB` | mednafen_vb |
+| Vectrex | `VECTREX` | vecx |
+| Commodore 64 | `C64` | vice_x64 |
+| DOS | `DOS` | dosbox_pure |
+
+[Full system details →](https://koin.js.org/docs/systems)
 
 ## Requirements
 
@@ -123,7 +212,11 @@ async headers() {
 
 ## Documentation
 
-Full documentation at **[koin.js.org](https://koin.js.org/docs)**
+- **[Quick Start](https://koin.js.org/docs/installation)** — Get up and running
+- **[Usage Guide](https://koin.js.org/docs/usage)** — Cloud saves, BIOS, RA integration
+- **[API Reference](https://koin.js.org/docs/api)** — Complete props documentation
+- **[Advanced Guide](https://koin.js.org/docs/advanced)** — Shaders, recording, controls, i18n
+- **[Systems List](https://koin.js.org/docs/systems)** — Per-console configuration
 
 ## License
 

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import react__default from 'react';
 import { Nostalgist } from 'nostalgist';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -443,6 +444,236 @@ declare function getAchievementBadgeUrl(badgeName: string, locked?: boolean): st
  */
 declare function getUserAvatarUrl(userPic: string): string;
 
+interface KoinTranslations {
+    controls: {
+        play: string;
+        pause: string;
+        reset: string;
+        rewind: string;
+        save: string;
+        load: string;
+        snap: string;
+        rec: string;
+        stopRec: string;
+        startRecord: string;
+        stopRecord: string;
+        mute: string;
+        unmute: string;
+        help: string;
+        full: string;
+        keys: string;
+        menuOpen: string;
+        menuClose: string;
+        gamepadConnected: string;
+        noGamepad: string;
+        press: string;
+        startBtn: string;
+        selectBtn: string;
+    };
+    common: {
+        disabledInHardcore: string;
+        notSupported: string;
+        playToEnableRewind: string;
+    };
+    settings: {
+        title: string;
+        general: string;
+        audio: string;
+        video: string;
+        input: string;
+        advanced: string;
+        fullscreen: string;
+        controls: string;
+        gamepad: string;
+        cheats: string;
+        retroAchievements: string;
+        shortcuts: string;
+        exit: string;
+        language: string;
+        selectLanguage: string;
+    };
+    overlay: {
+        play: string;
+        systemFirmware: string;
+        loading: string;
+        initializing: string;
+        loadingSave: string;
+        preparingSlot: string;
+        systemError: string;
+        failedInit: string;
+        retry: string;
+        slotReady: string;
+        paused: string;
+    };
+    notifications: {
+        saved: string;
+        loaded: string;
+        error: string;
+        recordingStarted: string;
+        recordingSaved: string;
+        downloaded: string;
+        loadedFile: string;
+        savedSlot: string;
+        loadedSlot: string;
+        deletedSlot: string;
+        emptySlot: string;
+        noSaveFound: string;
+        failedSave: string;
+        failedLoad: string;
+        failedDelete: string;
+        failedFetch: string;
+        controllerConnected: string;
+        controllerDisconnected: string;
+        controllerReady: string;
+        insertCoin: string;
+        insertCoinTitle: string;
+        controlsSaved: string;
+        controlsReset: string;
+    };
+    modals: {
+        shortcuts: {
+            title: string;
+            playerShortcuts: string;
+            overlays: string;
+            recording: string;
+            showHelp: string;
+            perfOverlay: string;
+            inputDisplay: string;
+            toggleRec: string;
+            toggleMute: string;
+            pressEsc: string;
+        };
+        controls: {
+            title: string;
+            keyboard: string;
+            description: string;
+            pressKey: string;
+            reset: string;
+            save: string;
+        };
+        gamepad: {
+            title: string;
+            noGamepad: string;
+            connected: string;
+            none: string;
+            player: string;
+            noController: string;
+            pressAny: string;
+            waiting: string;
+            pressButton: string;
+            pressEsc: string;
+            reset: string;
+            save: string;
+        };
+        cheats: {
+            title: string;
+            addCheat: string;
+            available: string;
+            emptyTitle: string;
+            emptyDesc: string;
+            copy: string;
+            active: string;
+            toggleHint: string;
+        };
+        saveSlots: {
+            title: string;
+            saveTitle: string;
+            loadTitle: string;
+            emptySlot: string;
+            subtitleSave: string;
+            subtitleLoad: string;
+            loading: string;
+            locked: string;
+            upgrade: string;
+            autoSave: string;
+            autoSaveDesc: string;
+            noData: string;
+            slot: string;
+            footerSave: string;
+            footerLoad: string;
+        };
+        bios: {
+            title: string;
+            description: string;
+            warningTitle: string;
+            warning: string;
+            systemDefault: string;
+            active: string;
+            defaultDesc: string;
+            emptyTitle: string;
+            emptyDesc: string;
+            footer: string;
+        };
+    };
+    retroAchievements: {
+        title: string;
+        login: string;
+        logout: string;
+        username: string;
+        password: string;
+        hardcore: string;
+        achievements: string;
+        locked: string;
+        unlocked: string;
+        mastered: string;
+        identifying: string;
+        achievementsAvailable: string;
+        gameNotSupported: string;
+        connect: string;
+        connected: string;
+        createAccount: string;
+        privacy: string;
+        privacyText: string;
+        connecting: string;
+        connectAccount: string;
+        poweredBy: string;
+        connectedStatus: string;
+        yourUsername: string;
+        yourPassword: string;
+        usernameRequired: string;
+        noGame: string;
+        loadGame: string;
+        noAchievements: string;
+        notSupported: string;
+        ptsRemaining: string;
+        filters: {
+            all: string;
+            locked: string;
+            unlocked: string;
+        };
+    };
+    overlays: {
+        performance: {
+            title: string;
+            fps: string;
+            frameTime: string;
+            memory: string;
+            core: string;
+            input: string;
+            active: string;
+        };
+        toast: {
+            saved: string;
+            loaded: string;
+            error: string;
+        };
+        recording: {
+            started: string;
+            stopped: string;
+            saved: string;
+            paused: string;
+            recording: string;
+            resume: string;
+            pause: string;
+            stop: string;
+            hover: string;
+        };
+    };
+}
+type RecursivePartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object ? RecursivePartial<T[P]> : T[P];
+};
+
 interface SaveSlot {
     slot: number;
     timestamp: string;
@@ -514,6 +745,7 @@ interface GamePlayerProps {
     onRALogin?: (username: string, password: string) => Promise<boolean>;
     onRALogout?: () => void;
     onRAHardcoreChange?: (enabled: boolean) => void;
+    translations?: RecursivePartial<KoinTranslations>;
 }
 interface PlayerControlsProps {
     isPaused: boolean;
@@ -548,6 +780,7 @@ interface PlayerControlsProps {
     systemColor?: string;
     gamepadCount?: number;
     onGamepadSettings?: () => void;
+    onSettings?: () => void;
     volume?: number;
     isMuted?: boolean;
     onVolumeChange?: (volume: number) => void;
@@ -601,6 +834,7 @@ interface RAHardcodeRestrictions {
 declare const GamePlayer: react.NamedExoticComponent<GamePlayerProps & {
     controls?: KeyboardMapping;
     saveControls?: (controls: KeyboardMapping) => void;
+    initialLanguage?: "en" | "es" | "fr";
 }>;
 
 /**
@@ -856,4 +1090,23 @@ interface UseGameRecordingReturn {
  */
 declare function useGameRecording({ getCanvasElement, }: UseGameRecordingProps): UseGameRecordingReturn;
 
-export { ALL_BUTTONS, AchievementPopup, BUTTON_GROUPS, BUTTON_LABELS, type ButtonId, CONSOLE_CAPABILITIES, CONSOLE_KEYBOARD_OVERRIDES, type Cheat, type CheatModalProps, type ConsoleCapabilities, type ControlConfig, type ControlMapperProps, type ControlMapping, type ControllerBrand, DEFAULT_CONTROLS, DEFAULT_GAMEPAD, DEFAULT_KEYBOARD, DPAD_BUTTONS, type EmulatorStatus, FACE_BUTTONS, GamePlayer, type GamePlayerProps, type GamepadInfo, type GamepadMapping, type KeyboardMapping, PERFORMANCE_TIER_1_SYSTEMS, PERFORMANCE_TIER_2_SYSTEMS, type PlayerControlsProps, type PlayerIndex, type RAAchievement, type RACredentials, type RAGame, type RAGameExtended, type RAHardcodeRestrictions, RASidebar, type RAUser, RA_MEDIA_BASE, type RetroAchievementsConfig, SHADER_PRESETS, SHOULDER_BUTTONS, STANDARD_AXIS_MAP, STANDARD_GAMEPAD_BUTTONS, STICK_BUTTONS, SUPPORTED_EXTENSIONS, SYSTEMS, SYSTEM_BUTTONS, type SaveSlot, type SaveSlotModalProps, type ShaderPresetId, ShaderSelector, ShortcutsReference, type ShowToastOptions, type SpeedMultiplier, type StandardAxis, type SystemConfig, TRIGGER_BUTTONS, type Toast, ToastContainer, type ToastType, type UseGamepadOptions, type UseGamepadReturn, type UseNostalgistReturn, type UseToastReturn, buildRetroArchConfig, clearAllControls, consoleHasButton, detectControllerBrand, detectSystem, formatGamepadButton, formatKeyCode, gamepadToRetroArchConfig, getAchievementBadgeUrl, getConsoleButtons, getConsoleCapabilities, getConsoleKeyboardDefaults, getCore, getDBSystemNames, getFullGamepadMapping, getFullKeyboardMapping, getSupportedExtensions, getSystem, getSystemByDbName, getSystemByKey, getSystemFromExtension, getSystemsList, getUserAvatarUrl, isSystemSupported, keyboardToRetroArchConfig, loadAllGamepadMappings, loadGamepadMapping, loadKeyboardMapping, normalizeSystemKey, saveGamepadMapping, saveKeyboardMapping, systemsMatch, useGameRecording, useGamepad, useNostalgist, useToast };
+/**
+ * Get a ROM blob from the browser cache
+ */
+declare function getCachedRom(romId: string): Promise<Blob | null>;
+declare function fetchAndCacheRom(romId: string, url: string): Promise<Blob>;
+
+declare const en: KoinTranslations;
+
+declare const es: KoinTranslations;
+
+declare const fr: KoinTranslations;
+
+interface KoinI18nProviderProps {
+    children: react__default.ReactNode;
+    translations?: RecursivePartial<KoinTranslations>;
+}
+declare const KoinI18nProvider: react__default.FC<KoinI18nProviderProps>;
+declare function useKoinTranslation(): KoinTranslations;
+
+export { ALL_BUTTONS, AchievementPopup, BUTTON_GROUPS, BUTTON_LABELS, type ButtonId, CONSOLE_CAPABILITIES, CONSOLE_KEYBOARD_OVERRIDES, type Cheat, type CheatModalProps, type ConsoleCapabilities, type ControlConfig, type ControlMapperProps, type ControlMapping, type ControllerBrand, DEFAULT_CONTROLS, DEFAULT_GAMEPAD, DEFAULT_KEYBOARD, DPAD_BUTTONS, type EmulatorStatus, FACE_BUTTONS, GamePlayer, type GamePlayerProps, type GamepadInfo, type GamepadMapping, type KeyboardMapping, KoinI18nProvider, type KoinTranslations, PERFORMANCE_TIER_1_SYSTEMS, PERFORMANCE_TIER_2_SYSTEMS, type PlayerControlsProps, type PlayerIndex, type RAAchievement, type RACredentials, type RAGame, type RAGameExtended, type RAHardcodeRestrictions, RASidebar, type RAUser, RA_MEDIA_BASE, type RecursivePartial, type RetroAchievementsConfig, SHADER_PRESETS, SHOULDER_BUTTONS, STANDARD_AXIS_MAP, STANDARD_GAMEPAD_BUTTONS, STICK_BUTTONS, SUPPORTED_EXTENSIONS, SYSTEMS, SYSTEM_BUTTONS, type SaveSlot, type SaveSlotModalProps, type ShaderPresetId, ShaderSelector, ShortcutsReference, type ShowToastOptions, type SpeedMultiplier, type StandardAxis, type SystemConfig, TRIGGER_BUTTONS, type Toast, ToastContainer, type ToastType, type UseGamepadOptions, type UseGamepadReturn, type UseNostalgistReturn, type UseToastReturn, buildRetroArchConfig, clearAllControls, consoleHasButton, detectControllerBrand, detectSystem, en, es, fetchAndCacheRom, formatGamepadButton, formatKeyCode, fr, gamepadToRetroArchConfig, getAchievementBadgeUrl, getCachedRom, getConsoleButtons, getConsoleCapabilities, getConsoleKeyboardDefaults, getCore, getDBSystemNames, getFullGamepadMapping, getFullKeyboardMapping, getSupportedExtensions, getSystem, getSystemByDbName, getSystemByKey, getSystemFromExtension, getSystemsList, getUserAvatarUrl, isSystemSupported, keyboardToRetroArchConfig, loadAllGamepadMappings, loadGamepadMapping, loadKeyboardMapping, normalizeSystemKey, saveGamepadMapping, saveKeyboardMapping, systemsMatch, useGameRecording, useGamepad, useKoinTranslation, useNostalgist, useToast };