@react-text-game/core 0.5.6 → 0.5.8

package/README.md

@@ -33,35 +33,35 @@ pnpm add @react-text-game/core
 ## Quick Start
 
 ```tsx
-import { Game, createEntity, newStory } from '@react-text-game/core';
+import { Game, createEntity, newStory } from "@react-text-game/core";
 
 // IMPORTANT: Initialize the game first
 await Game.init({
-  gameName: 'My Adventure',
-  translations: {
-    defaultLanguage: 'en',
-    fallbackLanguage: 'en',
-    resources: {
-      en: {
-        passages: { intro: 'Welcome to the Game' },
-        common: { save: 'Save', load: 'Load' }
-      },
-      ru: {
-        passages: { intro: 'Добро пожаловать в игру' }
-      }
-    }
-  },
-  // ...other options
+    gameName: "My Adventure",
+    translations: {
+        defaultLanguage: "en",
+        fallbackLanguage: "en",
+        resources: {
+            en: {
+                passages: { intro: "Welcome to the Game" },
+                common: { save: "Save", load: "Load" },
+            },
+            ru: {
+                passages: { intro: "Добро пожаловать в игру" },
+            },
+        },
+    },
+    // ...other options
 });
 
 // Create a game entity with the factory (recommended)
-const player = createEntity('player', {
-  name: 'Hero',
-  stats: {
-    health: 100,
-    mana: 50
-  },
-  inventory: [] as string[],
+const player = createEntity("player", {
+    name: "Hero",
+    stats: {
+        health: 100,
+        mana: 50,
+    },
+    inventory: [] as string[],
 });
 
 // Direct property updates automatically stay reactive
@@ -71,25 +71,25 @@ player.stats.health -= 10;
 player.save();
 
 // Create a story passage
-const introStory = newStory('intro', () => [
-  {
-    type: 'header',
-    content: 'Welcome to the Game',
-    props: { level: 1 }
-  },
-  {
-    type: 'text',
-    content: `Hello, ${player.name}!`
-  },
-  {
-    type: 'actions',
-    content: [
-      {
-        label: 'Start Adventure',
-        action: () => Game.jumpTo('adventure')
-      }
-    ]
-  }
+const introStory = newStory("intro", () => [
+    {
+        type: "header",
+        content: "Welcome to the Game",
+        props: { level: 1 },
+    },
+    {
+        type: "text",
+        content: `Hello, ${player.name}!`,
+    },
+    {
+        type: "actions",
+        content: [
+            {
+                label: "Start Adventure",
+                action: () => Game.jumpTo("adventure"),
+            },
+        ],
+    },
 ]);
 
 // Navigate to passage
@@ -115,13 +115,13 @@ The core engine includes a comprehensive audio system with reactive state manage
 ### Quick Start
 
 ```typescript
-import { createAudio, AudioManager } from '@react-text-game/core/audio';
+import { createAudio, AudioManager } from "@react-text-game/core/audio";
 
 // Create an audio track
-const bgMusic = createAudio('/audio/background.mp3', {
-  id: 'bg-music',
-  volume: 0.7,
-  loop: true,
+const bgMusic = createAudio("/audio/background.mp3", {
+    id: "bg-music",
+    volume: 0.7,
+    loop: true,
 });
 
 // Play the track
@@ -144,20 +144,20 @@ AudioManager.pauseAll();
 Use the `createAudio` factory function to create audio tracks:
 
 ```typescript
-import { createAudio } from '@react-text-game/core/audio';
+import { createAudio } from "@react-text-game/core/audio";
 
 // Basic audio track
-const sfx = createAudio('/audio/click.mp3');
+const sfx = createAudio("/audio/click.mp3");
 
 // With options
-const music = createAudio('/audio/theme.mp3', {
-  id: 'theme-music',        // Required for persistence
-  volume: 0.6,              // 0.0 to 1.0 (default: 1.0)
-  loop: true,               // Auto-loop (default: false)
-  playbackRate: 1.0,        // Playback speed (default: 1.0)
-  muted: false,             // Start muted (default: false)
-  autoPlay: false,          // Auto-play on creation (default: false)
-  preload: 'metadata',      // 'none', 'metadata', or 'auto' (default: 'metadata')
+const music = createAudio("/audio/theme.mp3", {
+    id: "theme-music", // Required for persistence
+    volume: 0.6, // 0.0 to 1.0 (default: 1.0)
+    loop: true, // Auto-loop (default: false)
+    playbackRate: 1.0, // Playback speed (default: 1.0)
+    muted: false, // Start muted (default: false)
+    autoPlay: false, // Auto-play on creation (default: false)
+    preload: "metadata", // 'none', 'metadata', or 'auto' (default: 'metadata')
 });
 ```
 
@@ -167,31 +167,31 @@ Each audio track provides comprehensive playback controls:
 
 ```typescript
 // Playback control
-await audio.play();           // Start playback (returns Promise)
-audio.pause();                // Pause playback
-audio.resume();               // Resume from pause
-audio.stop();                 // Stop and reset to beginning
+await audio.play(); // Start playback (returns Promise)
+audio.pause(); // Pause playback
+audio.resume(); // Resume from pause
+audio.stop(); // Stop and reset to beginning
 
 // Volume and settings
-audio.setVolume(0.5);         // Set volume (0.0 to 1.0)
-audio.setLoop(true);          // Enable/disable looping
-audio.setPlaybackRate(1.5);   // Set playback speed
-audio.setMuted(true);         // Mute/unmute
+audio.setVolume(0.5); // Set volume (0.0 to 1.0)
+audio.setLoop(true); // Enable/disable looping
+audio.setPlaybackRate(1.5); // Set playback speed
+audio.setMuted(true); // Mute/unmute
 
 // Seeking
-audio.seek(30);               // Seek to 30 seconds
+audio.seek(30); // Seek to 30 seconds
 
 // Fade effects
-await audio.fadeIn(2000);     // Fade in over 2 seconds
-await audio.fadeOut(1500);    // Fade out over 1.5 seconds
+await audio.fadeIn(2000); // Fade in over 2 seconds
+await audio.fadeOut(1500); // Fade out over 1.5 seconds
 
 // State and persistence
 const state = audio.getState(); // Get reactive state
-audio.save();                 // Save state to storage
-audio.load();                 // Load state from storage
+audio.save(); // Save state to storage
+audio.load(); // Load state from storage
 
 // Cleanup
-audio.dispose();              // Remove and clean up
+audio.dispose(); // Remove and clean up
 ```
 
 ### Reactive State
@@ -199,21 +199,21 @@ audio.dispose();              // Remove and clean up
 Audio tracks use Valtio for reactive state management, making them perfect for React integration:
 
 ```typescript
-const audio = createAudio('/audio/music.mp3', { id: 'music' });
+const audio = createAudio("/audio/music.mp3", { id: "music" });
 
 // Get reactive state
 const state = audio.getState();
 
 // Access state properties
-console.log(state.isPlaying);    // boolean
-console.log(state.isPaused);     // boolean
-console.log(state.isStopped);    // boolean
-console.log(state.currentTime);  // number (seconds)
-console.log(state.duration);     // number (seconds)
-console.log(state.volume);       // number (0.0 to 1.0)
-console.log(state.loop);         // boolean
+console.log(state.isPlaying); // boolean
+console.log(state.isPaused); // boolean
+console.log(state.isStopped); // boolean
+console.log(state.currentTime); // number (seconds)
+console.log(state.duration); // number (seconds)
+console.log(state.volume); // number (0.0 to 1.0)
+console.log(state.loop); // boolean
 console.log(state.playbackRate); // number
-console.log(state.muted);        // boolean
+console.log(state.muted); // boolean
 ```
 
 ### Global Audio Manager
@@ -221,30 +221,31 @@ console.log(state.muted);        // boolean
 The `AudioManager` provides global controls for all registered audio tracks:
 
 ```typescript
-import { AudioManager } from '@react-text-game/core/audio';
+import { AudioManager } from "@react-text-game/core/audio";
 
 // Master volume control
-AudioManager.setMasterVolume(0.5);           // Set master volume (0.0 to 1.0)
+AudioManager.setMasterVolume(0.5); // Set master volume (0.0 to 1.0)
 const volume = AudioManager.getMasterVolume(); // Get master volume
 
 // Global playback control
-AudioManager.pauseAll();   // Pause all playing tracks
-AudioManager.resumeAll();  // Resume all paused tracks
-AudioManager.stopAll();    // Stop all tracks
+AudioManager.pauseAll(); // Pause all playing tracks
+AudioManager.resumeAll(); // Resume all paused tracks
+AudioManager.stopAll(); // Stop all tracks
 
 // Global mute control
-AudioManager.muteAll();    // Mute all tracks
-AudioManager.unmuteAll();  // Unmute all tracks
+AudioManager.muteAll(); // Mute all tracks
+AudioManager.unmuteAll(); // Unmute all tracks
 
 // Track management
-const tracks = AudioManager.getAllTracks();           // Get all registered tracks
-const music = AudioManager.getTrackById('bg-music'); // Get specific track by ID
+const tracks = AudioManager.getAllTracks(); // Get all registered tracks
+const music = AudioManager.getTrackById("bg-music"); // Get specific track by ID
 
 // Cleanup
 AudioManager.disposeAll(); // Dispose all tracks
 ```
 
 **Master Volume Behavior:**
+
 - Master volume is a multiplier applied to all track volumes
 - Does not modify individual track volume settings
 - Example: Track at 0.8 volume with 0.5 master = 0.4 effective volume
@@ -259,37 +260,40 @@ The audio system includes React hooks for seamless component integration:
 Monitor individual audio track state with automatic re-renders:
 
 ```tsx
-import { createAudio } from '@react-text-game/core/audio';
-import { useAudio } from '@react-text-game/core';
+import { createAudio } from "@react-text-game/core/audio";
+import { useAudio } from "@react-text-game/core";
 
-const bgMusic = createAudio('/audio/background.mp3', {
-  id: 'bg-music',
-  loop: true,
+const bgMusic = createAudio("/audio/background.mp3", {
+    id: "bg-music",
+    loop: true,
 });
 
 function MusicPlayer() {
-  const audioState = useAudio(bgMusic);
-
-  return (
-    <div>
-      <p>Status: {audioState.isPlaying ? 'Playing' : 'Stopped'}</p>
-      <p>Time: {audioState.currentTime.toFixed(1)}s / {audioState.duration.toFixed(1)}s</p>
-      <p>Volume: {(audioState.volume * 100).toFixed(0)}%</p>
-
-      <button onClick={() => bgMusic.play()}>Play</button>
-      <button onClick={() => bgMusic.pause()}>Pause</button>
-      <button onClick={() => bgMusic.stop()}>Stop</button>
-
-      <input
-        type="range"
-        min="0"
-        max="1"
-        step="0.01"
-        value={audioState.volume}
-        onChange={(e) => bgMusic.setVolume(parseFloat(e.target.value))}
-      />
-    </div>
-  );
+    const audioState = useAudio(bgMusic);
+
+    return (
+        <div>
+            <p>Status: {audioState.isPlaying ? "Playing" : "Stopped"}</p>
+            <p>
+                Time: {audioState.currentTime.toFixed(1)}s /{" "}
+                {audioState.duration.toFixed(1)}s
+            </p>
+            <p>Volume: {(audioState.volume * 100).toFixed(0)}%</p>
+
+            <button onClick={() => bgMusic.play()}>Play</button>
+            <button onClick={() => bgMusic.pause()}>Pause</button>
+            <button onClick={() => bgMusic.stop()}>Stop</button>
+
+            <input
+                type="range"
+                min="0"
+                max="1"
+                step="0.01"
+                value={audioState.volume}
+                onChange={(e) => bgMusic.setVolume(parseFloat(e.target.value))}
+            />
+        </div>
+    );
 }
 ```
 
@@ -298,38 +302,40 @@ function MusicPlayer() {
 Access global audio controls in React components:
 
 ```tsx
-import { useAudioManager } from '@react-text-game/core';
+import { useAudioManager } from "@react-text-game/core";
 
 function AudioSettings() {
-  const audioManager = useAudioManager();
-
-  return (
-    <div>
-      <h2>Audio Settings</h2>
-
-      <label>
-        Master Volume: {(audioManager.masterVolume * 100).toFixed(0)}%
-        <input
-          type="range"
-          min="0"
-          max="1"
-          step="0.01"
-          value={audioManager.masterVolume}
-          onChange={(e) => audioManager.setMasterVolume(parseFloat(e.target.value))}
-        />
-      </label>
-
-      <div>
-        <button onClick={audioManager.muteAll}>Mute All</button>
-        <button onClick={audioManager.unmuteAll}>Unmute All</button>
-        <button onClick={audioManager.pauseAll}>Pause All</button>
-        <button onClick={audioManager.resumeAll}>Resume All</button>
-      </div>
-
-      <p>Muted: {audioManager.isMuted ? 'Yes' : 'No'}</p>
-      <p>Active Tracks: {audioManager.getAllTracks().length}</p>
-    </div>
-  );
+    const audioManager = useAudioManager();
+
+    return (
+        <div>
+            <h2>Audio Settings</h2>
+
+            <label>
+                Master Volume: {(audioManager.masterVolume * 100).toFixed(0)}%
+                <input
+                    type="range"
+                    min="0"
+                    max="1"
+                    step="0.01"
+                    value={audioManager.masterVolume}
+                    onChange={(e) =>
+                        audioManager.setMasterVolume(parseFloat(e.target.value))
+                    }
+                />
+            </label>
+
+            <div>
+                <button onClick={audioManager.muteAll}>Mute All</button>
+                <button onClick={audioManager.unmuteAll}>Unmute All</button>
+                <button onClick={audioManager.pauseAll}>Pause All</button>
+                <button onClick={audioManager.resumeAll}>Resume All</button>
+            </div>
+
+            <p>Muted: {audioManager.isMuted ? "Yes" : "No"}</p>
+            <p>Active Tracks: {audioManager.getAllTracks().length}</p>
+        </div>
+    );
 }
 ```
 
@@ -339,10 +345,10 @@ Audio tracks with an `id` automatically persist their state:
 
 ```typescript
 // Create audio with ID for persistence
-const music = createAudio('/audio/theme.mp3', {
-  id: 'theme-music',
-  volume: 0.7,
-  loop: true,
+const music = createAudio("/audio/theme.mp3", {
+    id: "theme-music",
+    volume: 0.7,
+    loop: true,
 });
 
 // State is automatically saved when it changes
@@ -351,13 +357,14 @@ music.setVolume(0.5);
 // State saved automatically
 
 // On game restart/reload
-const music = createAudio('/audio/theme.mp3', {
-  id: 'theme-music', // Same ID
+const music = createAudio("/audio/theme.mp3", {
+    id: "theme-music", // Same ID
 });
 music.load(); // Restores volume, position, playing state
 ```
 
 **What Gets Persisted:**
+
 - Volume level
 - Loop setting
 - Playback rate
@@ -372,19 +379,16 @@ music.load(); // Restores volume, position, playing state
 #### Background Music with Crossfade
 
 ```typescript
-const oldMusic = AudioManager.getTrackById('current-music');
-const newMusic = createAudio('/audio/new-theme.mp3', {
-  id: 'current-music',
-  loop: true,
+const oldMusic = AudioManager.getTrackById("current-music");
+const newMusic = createAudio("/audio/new-theme.mp3", {
+    id: "current-music",
+    loop: true,
 });
 
 // Crossfade between tracks
 if (oldMusic) {
-  await Promise.all([
-    oldMusic.fadeOut(1000),
-    newMusic.fadeIn(1000)
-  ]);
-  oldMusic.dispose();
+    await Promise.all([oldMusic.fadeOut(1000), newMusic.fadeIn(1000)]);
+    oldMusic.dispose();
 }
 ```
 
@@ -393,32 +397,32 @@ if (oldMusic) {
 ```typescript
 // Create sound effect without ID (no persistence needed)
 function playSoundEffect(src: string) {
-  const sfx = createAudio(src, {
-    volume: 0.8,
-  });
+    const sfx = createAudio(src, {
+        volume: 0.8,
+    });
 
-  sfx.play();
+    sfx.play();
 
-  // Auto-cleanup when finished
-  sfx.audioElement.addEventListener('ended', () => {
-    sfx.dispose();
-  });
+    // Auto-cleanup when finished
+    sfx.audioElement.addEventListener("ended", () => {
+        sfx.dispose();
+    });
 }
 
-playSoundEffect('/audio/click.mp3');
+playSoundEffect("/audio/click.mp3");
 ```
 
 #### Pause Audio During Dialogue
 
 ```typescript
 function showDialogue() {
-  // Pause background music
-  AudioManager.pauseAll();
+    // Pause background music
+    AudioManager.pauseAll();
 
-  // Show dialogue...
+    // Show dialogue...
 
-  // Resume when done
-  AudioManager.resumeAll();
+    // Resume when done
+    AudioManager.resumeAll();
 }
 ```
 
@@ -427,25 +431,29 @@ function showDialogue() {
 Modern browsers restrict audio autoplay without user interaction. The audio system handles this gracefully:
 
 ```typescript
-const music = createAudio('/audio/theme.mp3', {
-  autoPlay: true, // May be blocked by browser
+const music = createAudio("/audio/theme.mp3", {
+    autoPlay: true, // May be blocked by browser
 });
 
 // Autoplay failures are logged but don't throw errors
 // Manually play after user interaction:
-document.addEventListener('click', async () => {
-  await music.play(); // Will work after user interaction
-}, { once: true });
+document.addEventListener(
+    "click",
+    async () => {
+        await music.play(); // Will work after user interaction
+    },
+    { once: true }
+);
 ```
 
 ### TypeScript Types
 
 ```typescript
 import type {
-  AudioOptions,
-  AudioState,
-  AudioSaveState,
-} from '@react-text-game/core/audio';
+    AudioOptions,
+    AudioState,
+    AudioSaveState,
+} from "@react-text-game/core/audio";
 
 // All types include comprehensive JSDoc documentation
 ```
@@ -453,11 +461,13 @@ import type {
 ### API Reference
 
 **createAudio(src, options?)**
+
 - `src: string` - Audio file URL
 - `options?: AudioOptions` - Configuration options
 - Returns: `AudioTrack`
 
 **AudioTrack Methods:**
+
 - `play(): Promise<void>` - Start playback
 - `pause(): void` - Pause playback
 - `resume(): void` - Resume from pause
@@ -475,6 +485,7 @@ import type {
 - `dispose(): void` - Clean up and remove
 
 **AudioManager Methods:**
+
 - `setMasterVolume(volume: number): void` - Set master volume
 - `getMasterVolume(): number` - Get master volume
 - `muteAll(): void` - Mute all tracks
@@ -495,28 +506,28 @@ The core engine ships with first-class i18n based on `i18next` and `react-i18nex
 Pass an `I18nConfig` via the `translations` field when you call `Game.init()`:
 
 ```ts
-import type { I18nConfig } from '@react-text-game/core/i18n';
+import type { I18nConfig } from "@react-text-game/core/i18n";
 
 const translations: I18nConfig = {
-  defaultLanguage: 'en',
-  fallbackLanguage: 'en',
-  debug: false,
-  resources: {
-    en: {
-      passages: { intro: 'Welcome to the game' },
-      common: { save: 'Save', load: 'Load' }
+    defaultLanguage: "en",
+    fallbackLanguage: "en",
+    debug: false,
+    resources: {
+        en: {
+            passages: { intro: "Welcome to the game" },
+            common: { save: "Save", load: "Load" },
+        },
+        es: {
+            passages: { intro: "¡Bienvenido al juego!" },
+        },
     },
-    es: {
-      passages: { intro: '¡Bienvenido al juego!' }
-    }
-  },
-  modules: []
+    modules: [],
 };
 
 await Game.init({
-  gameName: 'My Adventure',
-  translations,
-  // ...other options
+    gameName: "My Adventure",
+    translations,
+    // ...other options
 });
 ```
 
@@ -531,23 +542,27 @@ A saved language preference is loaded from the settings store before i18next ini
 Use the `useGameTranslation` hook from `@react-text-game/core/i18n`:
 
 ```tsx
-import { useGameTranslation } from '@react-text-game/core/i18n';
+import { useGameTranslation } from "@react-text-game/core/i18n";
 
 export function LanguageSwitcher() {
-  const { t, languages, currentLanguage, changeLanguage } = useGameTranslation('common');
-
-  return (
-    <div>
-      <p>{t('currentLanguage', { language: currentLanguage })}</p>
-      <select value={currentLanguage} onChange={(event) => changeLanguage(event.target.value)}>
-        {languages.map((lang) => (
-          <option key={lang} value={lang}>
-            {lang}
-          </option>
-        ))}
-      </select>
-    </div>
-  );
+    const { t, languages, currentLanguage, changeLanguage } =
+        useGameTranslation("common");
+
+    return (
+        <div>
+            <p>{t("currentLanguage", { language: currentLanguage })}</p>
+            <select
+                value={currentLanguage}
+                onChange={(event) => changeLanguage(event.target.value)}
+            >
+                {languages.map((lang) => (
+                    <option key={lang} value={lang}>
+                        {lang}
+                    </option>
+                ))}
+            </select>
+        </div>
+    );
 }
 ```
 
@@ -558,10 +573,10 @@ The hook filters out the `cimode` debug language unless you enable `debug` and p
 For game logic or utilities, grab a namespace-specific translator with `getGameTranslation`:
 
 ```ts
-import { getGameTranslation } from '@react-text-game/core/i18n';
+import { getGameTranslation } from "@react-text-game/core/i18n";
 
-const t = getGameTranslation('passages');
-const intro = t('forest.description');
+const t = getGameTranslation("passages");
+const intro = t("forest.description");
 ```
 
 ### UI package integration
@@ -584,7 +599,7 @@ The `Game` class is the central orchestrator that manages:
 ```typescript
 // Initialize the game (REQUIRED)
 await Game.init({
-  // your options
+    // your options
 });
 
 // Register entities
@@ -594,7 +609,7 @@ Game.registerEntity(player, inventory, quest);
 Game.registerPassage(intro, chapter1, finalBattle);
 
 // Navigate
-Game.jumpTo('chapter1');
+Game.jumpTo("chapter1");
 
 // Save/Load
 const savedState = Game.getState();
@@ -619,19 +634,19 @@ wraps it in a `SimpleObject` that:
 - Requires explicit `save()` calls so you stay in control of persistence cadence
 
 ```typescript
-import { createEntity } from '@react-text-game/core';
-
-const player = createEntity('player', {
-  name: 'Hero',
-  health: 100,
-  inventory: {
-    gold: 50,
-    items: [] as string[],
-  },
+import { createEntity } from "@react-text-game/core";
+
+const player = createEntity("player", {
+    name: "Hero",
+    health: 100,
+    inventory: {
+        gold: 50,
+        items: [] as string[],
+    },
 });
 
 player.health -= 5; // direct property access
-player.inventory.items.push('sword');
+player.inventory.items.push("sword");
 player.save(); // persist changes when you decide to
 ```
 
@@ -642,20 +657,20 @@ Prefer a class-based design, private fields, or inheritance? Extend
 available:
 
 ```typescript
-import { BaseGameObject } from '@react-text-game/core';
+import { BaseGameObject } from "@react-text-game/core";
 
 class Inventory extends BaseGameObject<{ items: string[] }> {
-  constructor() {
-    super({
-      id: 'inventory',
-      variables: { items: [] },
-    });
-  }
+    constructor() {
+        super({
+            id: "inventory",
+            variables: { items: [] },
+        });
+    }
 
-  addItem(item: string) {
-    this._variables.items.push(item);
-    this.save();
-  }
+    addItem(item: string) {
+        this._variables.items.push(item);
+        this.save();
+    }
 }
 ```
 
@@ -668,69 +683,74 @@ Passages represent different screens or scenes in your game. Three types are ava
 Text-based narrative passages with rich components:
 
 ```typescript
-import { newStory } from '@react-text-game/core';
-
-const myStory = newStory('my-story', (props) => [
-  {
-    type: 'header',
-    content: 'Chapter 1',
-    props: { level: 1 }
-  },
-  {
-    type: 'text',
-    content: 'Once upon a time...'
-  },
-  {
-    type: 'image',
-    content: '/assets/scene.jpg',
-    props: { alt: 'A beautiful scene' }
-  },
-  {
-    type: 'video',
-    content: '/assets/intro.mp4',
-    props: { controls: true, autoPlay: false }
-  },
-  {
-    type: 'conversation',
-    content: [
-      {
-        content: 'Hello there!',
-        who: { name: 'NPC', avatar: '/avatars/npc.png' },
-        side: 'left'
-      },
-      {
-        content: 'Hi!',
-        who: { name: 'Player' },
-        side: 'right'
-      }
+import { newStory } from "@react-text-game/core";
+
+const myStory = newStory(
+    "my-story",
+    (props) => [
+        {
+            type: "header",
+            content: "Chapter 1",
+            props: { level: 1 },
+        },
+        {
+            type: "text",
+            content: "Once upon a time...",
+        },
+        {
+            type: "image",
+            content: "/assets/scene.jpg",
+            props: { alt: "A beautiful scene" },
+        },
+        {
+            type: "video",
+            content: "/assets/intro.mp4",
+            props: { controls: true, autoPlay: false },
+        },
+        {
+            type: "conversation",
+            content: [
+                {
+                    content: "Hello there!",
+                    who: { name: "NPC", avatar: "/avatars/npc.png" },
+                    side: "left",
+                },
+                {
+                    content: "Hi!",
+                    who: { name: "Player" },
+                    side: "right",
+                },
+            ],
+            props: { variant: "messenger" },
+            appearance: "atOnce",
+        },
+        {
+            type: "actions",
+            content: [
+                {
+                    label: "Continue",
+                    action: () => Game.jumpTo("chapter-2"),
+                    color: "primary",
+                },
+                {
+                    label: "Go Back",
+                    action: () => Game.jumpTo("intro"),
+                    color: "secondary",
+                    variant: "bordered",
+                },
+            ],
+            props: { direction: "horizontal" },
+        },
     ],
-    props: { variant: 'messenger' },
-    appearance: 'atOnce'
-  },
-  {
-    type: 'actions',
-    content: [
-      {
-        label: 'Continue',
-        action: () => Game.jumpTo('chapter-2'),
-        color: 'primary'
-      },
-      {
-        label: 'Go Back',
-        action: () => Game.jumpTo('intro'),
-        color: 'secondary',
-        variant: 'bordered'
-      }
-    ],
-    props: { direction: 'horizontal' }
-  }
-], {
-  background: { image: '/bg.jpg' },
-  classNames: { container: 'story-container' }
-});
+    {
+        background: { image: "/bg.jpg" },
+        classNames: { container: "story-container" },
+    }
+);
 ```
 
 **Available Components:**
+
 - `text` - Text content with ReactNode support and custom styling
 - `header` - Semantic headers (h1-h6) with configurable levels
 - `image` - Images with built-in modal viewer and custom click handlers
@@ -744,78 +764,85 @@ const myStory = newStory('my-story', (props) => [
 Map-based interactive passages with hotspots:
 
 ```typescript
-import { newInteractiveMap } from '@react-text-game/core';
-
-const worldMap = newInteractiveMap('world-map', {
-  caption: 'World Map',
-  image: '/maps/world.jpg',
-  bgImage: '/maps/world-bg.jpg',
-  props: { bgOpacity: 0.3 },
-  hotspots: [
-    // Map label hotspot - positioned on the map
-    {
-      type: 'label',
-      content: 'Village',
-      position: { x: 30, y: 40 }, // Percentage-based (0-100)
-      action: () => Game.jumpTo('village'),
-      props: { color: 'primary', variant: 'solid' }
-    },
-    // Map image hotspot - with state-dependent images
-    {
-      type: 'image',
-      content: {
-        idle: '/icons/chest.png',
-        hover: '/icons/chest-glow.png',
-        active: '/icons/chest-open.png',
-        disabled: '/icons/chest-locked.png'
-      },
-      position: { x: 60, y: 70 },
-      action: () => openChest(),
-      isDisabled: () => !player.hasKey,
-      tooltip: {
-        content: () => player.hasKey ? 'Open chest' : 'Locked',
-        position: 'top'
-      },
-      props: { zoom: '150%' }
-    },
-    // Conditional hotspot - only visible if discovered
-    () => player.hasDiscovered('forest') ? {
-      type: 'label',
-      content: 'Forest',
-      position: { x: 80, y: 50 },
-      action: () => Game.jumpTo('forest')
-    } : undefined,
-    // Side hotspot - positioned on edge
-    {
-      type: 'label',
-      content: 'Menu',
-      position: 'top', // top/bottom/left/right
-      action: () => openMenu()
+import { newInteractiveMap } from "@react-text-game/core";
+
+const worldMap = newInteractiveMap("world-map", {
+    caption: "World Map",
+    image: "/maps/world.jpg",
+    bgImage: "/maps/world-bg.jpg",
+    props: { bgOpacity: 0.3 },
+    hotspots: [
+        // Map label hotspot - positioned on the map
+        {
+            type: "label",
+            content: "Village",
+            position: { x: 30, y: 40 }, // Percentage-based (0-100)
+            action: () => Game.jumpTo("village"),
+            props: { color: "primary", variant: "solid" },
+        },
+        // Map image hotspot - with state-dependent images
+        {
+            type: "image",
+            content: {
+                idle: "/icons/chest.png",
+                hover: "/icons/chest-glow.png",
+                active: "/icons/chest-open.png",
+                disabled: "/icons/chest-locked.png",
+            },
+            position: { x: 60, y: 70 },
+            action: () => openChest(),
+            isDisabled: () => !player.hasKey,
+            tooltip: {
+                content: () => (player.hasKey ? "Open chest" : "Locked"),
+                position: "top",
+            },
+            props: { zoom: "150%" },
+        },
+        // Conditional hotspot - only visible if discovered
+        () =>
+            player.hasDiscovered("forest")
+                ? {
+                      type: "label",
+                      content: "Forest",
+                      position: { x: 80, y: 50 },
+                      action: () => Game.jumpTo("forest"),
+                  }
+                : undefined,
+        // Side hotspot - positioned on edge
+        {
+            type: "label",
+            content: "Menu",
+            position: "top", // top/bottom/left/right
+            action: () => openMenu(),
+        },
+        // Context menu - multiple choices at a location
+        {
+            type: "menu",
+            position: { x: 50, y: 50 },
+            direction: "vertical",
+            items: [
+                { type: "label", content: "Examine", action: () => examine() },
+                { type: "label", content: "Take", action: () => take() },
+                () =>
+                    player.hasMagic
+                        ? {
+                              type: "label",
+                              content: "Cast Spell",
+                              action: () => castSpell(),
+                          }
+                        : undefined,
+            ],
+        },
+    ],
+    classNames: {
+        container: "bg-gradient-to-b from-sky-900 to-indigo-900",
+        topHotspots: "bg-muted/50 backdrop-blur-sm",
     },
-    // Context menu - multiple choices at a location
-    {
-      type: 'menu',
-      position: { x: 50, y: 50 },
-      direction: 'vertical',
-      items: [
-        { type: 'label', content: 'Examine', action: () => examine() },
-        { type: 'label', content: 'Take', action: () => take() },
-        () => player.hasMagic ? {
-          type: 'label',
-          content: 'Cast Spell',
-          action: () => castSpell()
-        } : undefined
-      ]
-    }
-  ],
-  classNames: {
-    container: 'bg-gradient-to-b from-sky-900 to-indigo-900',
-    topHotspots: 'bg-muted/50 backdrop-blur-sm'
-  }
 });
 ```
 
 **Hotspot Types:**
+
 - `MapLabelHotspot` - Text buttons positioned on map using percentage coordinates (x/y: 0-100)
 - `MapImageHotspot` - Image buttons with state variants (idle/hover/active/disabled) and zoom support
 - `SideLabelHotspot` - Text buttons on map edges (top/bottom/left/right)
@@ -823,6 +850,7 @@ const worldMap = newInteractiveMap('world-map', {
 - `MapMenu` - Contextual menu with multiple items at a specific position
 
 **Dynamic Features:**
+
 - Hotspots can be functions returning `undefined` for conditional visibility
 - Images and positions support dynamic functions: `image: () => '/maps/' + season + '.jpg'`
 - Disabled states with custom tooltips explaining why actions are unavailable
@@ -832,14 +860,15 @@ const worldMap = newInteractiveMap('world-map', {
 Custom React components as passages:
 
 ```tsx
-import { newWidget } from '@react-text-game/core';
-
-const customUI = newWidget('custom-ui', (
-  <div>
-    <h1>Custom Interface</h1>
-    <MyCustomComponent />
-  </div>
-));
+import { newWidget } from "@react-text-game/core";
+
+const customUI = newWidget(
+    "custom-ui",
+    <div>
+        <h1>Custom Interface</h1>
+        <MyCustomComponent />
+    </div>
+);
 ```
 
 ### Storage
@@ -847,13 +876,13 @@ const customUI = newWidget('custom-ui', (
 JSONPath-based storage system using the `jsonpath` library:
 
 ```typescript
-import { Storage } from '@react-text-game/core';
+import { Storage } from "@react-text-game/core";
 
 // Get values
-const health = Storage.getValue<number>('$.player.health');
+const health = Storage.getValue<number>("$.player.health");
 
 // Set values
-Storage.setValue('$.player.health', 75);
+Storage.setValue("$.player.health", 75);
 
 // Full state
 const state = Storage.getState();
@@ -861,6 +890,7 @@ Storage.setState(state);
 ```
 
 **Key Features:**
+
 - JSONPath queries for flexible data access
 - Protected system paths (prefixed with `$._system`)
 - Automatic path creation
@@ -874,18 +904,19 @@ The engine includes a comprehensive save/load system built on IndexedDB (via Dex
 
 ```typescript
 import {
-  useSaveSlots,
-  useSaveGame,
-  useLoadGame,
-  useDeleteGame,
-  useLastLoadGame,
-  useExportSaves,
-  useImportSaves,
-  useRestartGame
-} from '@react-text-game/core/saves';
+    useSaveSlots,
+    useSaveGame,
+    useLoadGame,
+    useDeleteGame,
+    useLastLoadGame,
+    useExportSaves,
+    useImportSaves,
+    useRestartGame,
+} from "@react-text-game/core/saves";
 ```
 
 **Features:**
+
 - **Persistent Storage** - IndexedDB for browser-based saves
 - **Multiple Save Slots** - Unlimited save slots with metadata
 - **Export/Import** - Encrypted file export/import (`.sx` format)
@@ -899,20 +930,26 @@ import {
 
 ```tsx
 function SavesList() {
-  const slots = useSaveSlots({ count: 5 });
-
-  return (
-    <div>
-      {slots.map((slot, index) => (
-        <div key={index}>
-          <p>Slot {index}: {slot.data ? 'Saved' : 'Empty'}</p>
-          <button onClick={() => slot.save()}>Save</button>
-          <button onClick={() => slot.load()} disabled={!slot.data}>Load</button>
-          <button onClick={() => slot.delete()} disabled={!slot.data}>Delete</button>
+    const slots = useSaveSlots({ count: 5 });
+
+    return (
+        <div>
+            {slots.map((slot, index) => (
+                <div key={index}>
+                    <p>
+                        Slot {index}: {slot.data ? "Saved" : "Empty"}
+                    </p>
+                    <button onClick={() => slot.save()}>Save</button>
+                    <button onClick={() => slot.load()} disabled={!slot.data}>
+                        Load
+                    </button>
+                    <button onClick={() => slot.delete()} disabled={!slot.data}>
+                        Delete
+                    </button>
+                </div>
+            ))}
         </div>
-      ))}
-    </div>
-  );
+    );
 }
 ```
 
@@ -920,20 +957,16 @@ function SavesList() {
 
 ```tsx
 function SaveButton({ slotNumber }) {
-  const saveGame = useSaveGame();
+    const saveGame = useSaveGame();
 
-  const handleSave = async () => {
-    const result = await saveGame(slotNumber);
-    if (result?.success === false) {
-      alert(result.message);
-    }
-  };
+    const handleSave = async () => {
+        const result = await saveGame(slotNumber);
+        if (result?.success === false) {
+            alert(result.message);
+        }
+    };
 
-  return (
-    <button onClick={handleSave}>
-      Save to Slot {slotNumber}
-    </button>
-  );
+    return <button onClick={handleSave}>Save to Slot {slotNumber}</button>;
 }
 ```
 
@@ -941,16 +974,16 @@ function SaveButton({ slotNumber }) {
 
 ```tsx
 function LoadButton({ saveId }) {
-  const loadGame = useLoadGame();
+    const loadGame = useLoadGame();
 
-  const handleLoad = async () => {
-    const result = await loadGame(saveId);
-    if (result?.success === false) {
-      alert(result.message);
-    }
-  };
+    const handleLoad = async () => {
+        const result = await loadGame(saveId);
+        if (result?.success === false) {
+            alert(result.message);
+        }
+    };
 
-  return <button onClick={handleLoad}>Load Game</button>;
+    return <button onClick={handleLoad}>Load Game</button>;
 }
 ```
 
@@ -958,16 +991,16 @@ function LoadButton({ saveId }) {
 
 ```tsx
 function DeleteButton({ saveId }) {
-  const deleteGame = useDeleteGame();
+    const deleteGame = useDeleteGame();
 
-  const handleDelete = async () => {
-    const result = await deleteGame(saveId);
-    if (result?.success === false) {
-      alert(result.message);
-    }
-  };
+    const handleDelete = async () => {
+        const result = await deleteGame(saveId);
+        if (result?.success === false) {
+            alert(result.message);
+        }
+    };
 
-  return <button onClick={handleDelete}>Delete Save</button>;
+    return <button onClick={handleDelete}>Delete Save</button>;
 }
 ```
 
@@ -975,17 +1008,17 @@ function DeleteButton({ saveId }) {
 
 ```tsx
 function ContinueButton() {
-  const { hasLastSave, loadLastGame, isLoading } = useLastLoadGame();
+    const { hasLastSave, loadLastGame, isLoading } = useLastLoadGame();
 
-  if (isLoading) {
-    return <div>Loading...</div>;
-  }
+    if (isLoading) {
+        return <div>Loading...</div>;
+    }
 
-  return (
-    <button onClick={loadLastGame} disabled={!hasLastSave}>
-      Continue Last Game
-    </button>
-  );
+    return (
+        <button onClick={loadLastGame} disabled={!hasLastSave}>
+            Continue Last Game
+        </button>
+    );
 }
 ```
 
@@ -993,18 +1026,18 @@ function ContinueButton() {
 
 ```tsx
 function ExportButton() {
-  const exportSaves = useExportSaves();
-
-  const handleExport = async () => {
-    const result = await exportSaves();
-    if (result.success) {
-      console.log('Saves exported successfully');
-    } else {
-      alert(`Export failed: ${result.error}`);
-    }
-  };
-
-  return <button onClick={handleExport}>Export Saves</button>;
+    const exportSaves = useExportSaves();
+
+    const handleExport = async () => {
+        const result = await exportSaves();
+        if (result.success) {
+            console.log("Saves exported successfully");
+        } else {
+            alert(`Export failed: ${result.error}`);
+        }
+    };
+
+    return <button onClick={handleExport}>Export Saves</button>;
 }
 ```
 
@@ -1012,18 +1045,18 @@ function ExportButton() {
 
 ```tsx
 function ImportButton() {
-  const importSaves = useImportSaves();
-
-  const handleImport = async () => {
-    const result = await importSaves();
-    if (result.success) {
-      console.log(`Imported ${result.count} saves`);
-    } else {
-      alert(`Import failed: ${result.error}`);
-    }
-  };
-
-  return <button onClick={handleImport}>Import Saves</button>;
+    const importSaves = useImportSaves();
+
+    const handleImport = async () => {
+        const result = await importSaves();
+        if (result.success) {
+            console.log(`Imported ${result.count} saves`);
+        } else {
+            alert(`Import failed: ${result.error}`);
+        }
+    };
+
+    return <button onClick={handleImport}>Import Saves</button>;
 }
 ```
 
@@ -1031,13 +1064,9 @@ function ImportButton() {
 
 ```tsx
 function RestartButton() {
-  const restartGame = useRestartGame();
+    const restartGame = useRestartGame();
 
-  return (
-    <button onClick={restartGame}>
-      Restart Game
-    </button>
-  );
+    return <button onClick={restartGame}>Restart Game</button>;
 }
 ```
 
@@ -1047,15 +1076,15 @@ For advanced use cases, you can access the database directly:
 
 ```typescript
 import {
-  saveGame,
-  loadGame,
-  getAllSaves,
-  deleteSave,
-  db
-} from '@react-text-game/core/saves';
+    saveGame,
+    loadGame,
+    getAllSaves,
+    deleteSave,
+    db,
+} from "@react-text-game/core/saves";
 
 // Save game manually
-await saveGame('my-save', gameData, 'Description', screenshotBase64);
+await saveGame("my-save", gameData, "Description", screenshotBase64);
 
 // Load by ID
 const save = await loadGame(1);
@@ -1067,12 +1096,13 @@ const allSaves = await getAllSaves();
 await deleteSave(1);
 
 // Direct Dexie access
-await db.saves.where('name').equals('my-save').first();
+await db.saves.where("name").equals("my-save").first();
 ```
 
 #### Save File Encryption
 
 Exported save files are encrypted using AES encryption with PBKDF2 key derivation:
+
 - **Algorithm**: AES-256-CBC
 - **Key Derivation**: PBKDF2 with 1000 iterations
 - **Salt & IV**: Randomly generated for each export
@@ -1082,21 +1112,39 @@ Exported save files are encrypted using AES encryption with PBKDF2 key derivatio
 
 #### useCurrentPassage
 
-Get the current passage with reactive updates:
+Get the current passage with reactive updates. Returns a tuple containing the current passage and a unique render ID that changes on each navigation:
 
 ```tsx
-import { useCurrentPassage } from '@react-text-game/core';
+import { useCurrentPassage } from "@react-text-game/core";
 
 function GameScreen() {
-  const passage = useCurrentPassage();
+    const [passage, renderId] = useCurrentPassage();
 
-  if (!passage) return <div>Loading...</div>;
+    if (!passage) return <div>Loading...</div>;
 
-  // Render based on passage type
-  if (passage.type === 'story') {
-    const { components } = passage.display();
-    // Render story components
-  }
+    // Render based on passage type
+    if (passage.type === "story") {
+        const { components } = passage.display();
+        // Render story components
+    }
+}
+```
+
+**Render ID Purpose:**
+The `renderId` is automatically generated on each `Game.jumpTo()` call, ensuring that React components re-render even when navigating to the same passage multiple times. This is useful for forcing component remounts, resetting animations, or clearing component state.
+
+**Usage Example:**
+
+```tsx
+function PassageRenderer() {
+    const [passage, renderId] = useCurrentPassage();
+
+    // Use renderId as a React key to force remount on navigation
+    return (
+        <div key={renderId} className="animate-fade-in">
+            {passage && <PassageContent passage={passage} />}
+        </div>
+    );
 }
 ```
 
@@ -1105,17 +1153,17 @@ function GameScreen() {
 Monitor entity changes with automatic re-renders:
 
 ```tsx
-import { useGameEntity } from '@react-text-game/core';
+import { useGameEntity } from "@react-text-game/core";
 
 function PlayerStats({ player }) {
-  const reactivePlayer = useGameEntity(player);
+    const reactivePlayer = useGameEntity(player);
 
-  return (
-    <div>
-      Health: {reactivePlayer.health}
-      {/* Direct property access stays reactive */}
-    </div>
-  );
+    return (
+        <div>
+            Health: {reactivePlayer.health}
+            {/* Direct property access stays reactive */}
+        </div>
+    );
 }
 ```
 
@@ -1124,12 +1172,12 @@ function PlayerStats({ player }) {
 Check if game has started:
 
 ```tsx
-import { useGameIsStarted } from '@react-text-game/core';
+import { useGameIsStarted } from "@react-text-game/core";
 
 function GameUI() {
-  const isStarted = useGameIsStarted();
+    const isStarted = useGameIsStarted();
 
-  return isStarted ? <GameScreen /> : <MainMenu />;
+    return isStarted ? <GameScreen /> : <MainMenu />;
 }
 ```
 
@@ -1147,6 +1195,7 @@ function GameUI() {
 ### Registry Pattern
 
 The engine uses two registries:
+
 - `objectRegistry` - Stores all game entities as Valtio proxies
 - `passagesRegistry` - Stores all passages
 
@@ -1155,6 +1204,7 @@ All objects are automatically wrapped in Valtio proxies for reactive state manag
 ### Save System
 
 The save system consists of:
+
 - **Entity State** - Each entity's `_variables` stored at `$.{entityId}`
 - **Game State** - Current passage stored at `$._system.game`
 - **JSONPath Access** - Flexible queries for any state data
@@ -1165,6 +1215,7 @@ The save system consists of:
 ### Game
 
 Static methods:
+
 - `init(options)` - **Initialize the game (REQUIRED - must be called first)**
 - `registerEntity(...objects)` - Register game objects
 - `registerPassage(...passages)` - Register passages
@@ -1180,6 +1231,7 @@ Static methods:
 - `clearAutoSave()` - Clear auto-saved state
 
 Properties:
+
 - `currentPassage` - Get current passage
 - `selfState` - Get game internal state
 - `options` - Get game options
@@ -1187,30 +1239,36 @@ Properties:
 ### BaseGameObject
 
 Constructor:
+
 - `new BaseGameObject({ id, variables? })`
 
 Properties:
+
 - `id` - Unique identifier
 - `variables` - Entity variables (readonly)
 - `_variables` - Internal variables (protected)
 
 Methods:
+
 - `save()` - Save to storage
 - `load()` - Load from storage
 
 ### Passage Types
 
 **Story:**
+
 ```typescript
 newStory(id: string, content: StoryContent, options?: StoryOptions): Story
 ```
 
 **Interactive Map:**
+
 ```typescript
 newInteractiveMap(id: string, options: InteractiveMapOptions): InteractiveMap
 ```
 
 **Widget:**
+
 ```typescript
 newWidget(id: string, content: ReactNode): Widget
 ```
@@ -1222,48 +1280,49 @@ Full TypeScript support with comprehensive types and detailed JSDoc documentatio
 ```typescript
 // Import types from main package
 import type {
-  GameSaveState,
-  JsonPath,
-  InitVarsType,
-  PassageType,
-  ButtonColor,
-  ButtonVariant
-} from '@react-text-game/core';
+    GameSaveState,
+    JsonPath,
+    InitVarsType,
+    PassageType,
+    ButtonColor,
+    ButtonVariant,
+} from "@react-text-game/core";
 
 // Import story passage types
 import type {
-  Component,
-  StoryContent,
-  StoryOptions,
-  TextComponent,
-  HeaderComponent,
-  ImageComponent,
-  VideoComponent,
-  ActionsComponent,
-  ConversationComponent,
-  AnotherStoryComponent,
-  ActionType,
-  ConversationBubble,
-  ConversationVariant,
-  ConversationAppearance
-} from '@react-text-game/core/passages';
+    Component,
+    StoryContent,
+    StoryOptions,
+    TextComponent,
+    HeaderComponent,
+    ImageComponent,
+    VideoComponent,
+    ActionsComponent,
+    ConversationComponent,
+    AnotherStoryComponent,
+    ActionType,
+    ConversationBubble,
+    ConversationVariant,
+    ConversationAppearance,
+} from "@react-text-game/core/passages";
 
 // Import interactive map types
 import type {
-  InteractiveMapOptions,
-  InteractiveMapType,
-  AnyHotspot,
-  MapLabelHotspot,
-  MapImageHotspot,
-  SideLabelHotspot,
-  SideImageHotspot,
-  MapMenu,
-  LabelHotspot,
-  ImageHotspot
-} from '@react-text-game/core/passages';
+    InteractiveMapOptions,
+    InteractiveMapType,
+    AnyHotspot,
+    MapLabelHotspot,
+    MapImageHotspot,
+    SideLabelHotspot,
+    SideImageHotspot,
+    MapMenu,
+    LabelHotspot,
+    ImageHotspot,
+} from "@react-text-game/core/passages";
 ```
 
 All types include comprehensive JSDoc comments with:
+
 - Detailed descriptions of each property
 - Usage examples and code snippets
 - Default value annotations