Rework story engine flow and reorganize project docs

src/hooks/useGamePersistence.ts

@@ -13,6 +13,11 @@ import { normalizeQuestLogEntries } from '../data/questFlow';
 import { normalizeGameRuntimeStats } from '../data/runtimeStats';
 import { ensureSceneEncounterPreview, TREASURE_ENCOUNTERS_ENABLED } from '../data/sceneEncounterPreviews';
 import {clearSavedSnapshot, readSavedSnapshot, writeSavedSnapshot} from '../persistence/gameSaveStorage';
+import {
+  applyStoryEngineMigration,
+  buildSaveMigrationManifest,
+} from '../services/storyEngine/saveMigrationManifest';
+import { createEmptyStoryEngineMemoryState } from '../services/storyEngine/visibilityEngine';
 import { GameState, StoryMoment } from '../types';
 import { BottomTab } from './useGameFlow';
 
@@ -47,15 +52,22 @@ function normalizeCharacterChats(gameState: GameState) {
 }
 
 function normalizeSavedGameState(gameState: GameState) {
+  const migrationManifest = buildSaveMigrationManifest({
+    version: 'story-engine-v5',
+  });
+  const migratedState = applyStoryEngineMigration({
+    state: gameState,
+    manifest: migrationManifest,
+  });
   const normalizedRoster = normalizeRoster(gameState.roster ?? [], gameState.companions ?? []);
-  const normalizedEncounterState = !TREASURE_ENCOUNTERS_ENABLED && gameState.currentEncounter?.kind === 'treasure'
+  const normalizedEncounterState = !TREASURE_ENCOUNTERS_ENABLED && migratedState.currentEncounter?.kind === 'treasure'
     ? ensureSceneEncounterPreview({
-        ...gameState,
+        ...migratedState,
         currentEncounter: null,
-        sceneMonsters: [],
+        sceneHostileNpcs: [],
         inBattle: false,
       } as GameState)
-    : gameState;
+    : migratedState;
   const normalizedRuntimeStats = normalizeGameRuntimeStats(normalizedEncounterState.runtimeStats, {
     isActiveRun: Boolean(
       normalizedEncounterState.playerCharacter &&
@@ -66,6 +78,25 @@ function normalizeSavedGameState(gameState: GameState) {
     ...normalizedEncounterState,
     customWorldProfile: normalizedEncounterState.customWorldProfile ?? null,
     runtimeStats: normalizedRuntimeStats,
+    storyEngineMemory:
+      normalizedEncounterState.storyEngineMemory ??
+      createEmptyStoryEngineMemoryState(),
+    chapterState:
+      normalizedEncounterState.chapterState
+      ?? normalizedEncounterState.storyEngineMemory?.currentChapter
+      ?? null,
+    campaignState:
+      normalizedEncounterState.campaignState
+      ?? normalizedEncounterState.storyEngineMemory?.campaignState
+      ?? null,
+    activeScenarioPackId:
+      normalizedEncounterState.activeScenarioPackId
+      ?? normalizedEncounterState.customWorldProfile?.scenarioPackId
+      ?? null,
+    activeCampaignPackId:
+      normalizedEncounterState.activeCampaignPackId
+      ?? normalizedEncounterState.customWorldProfile?.campaignPackId
+      ?? null,
     npcInteractionActive: normalizedEncounterState.npcInteractionActive ?? false,
     playerCurrency: typeof gameState.playerCurrency === 'number'
       ? gameState.playerCurrency