path: root/js/baba-yaga/scratch/docs/GAME-ENGINE.md

## Baba Yaga Text Adventure Game Engine - Project Plan

### Phase 1: Understanding Baba Yaga
*(Completed)*

*   **Reviewed Baba Yaga Language Features:**
    *   Data Structures: Immutable lists and tables, `append`, `set`, `merge`, `shape`.
    *   Functional Programming: Immutability, first-class functions, currying, partial application, higher-order functions (`map`, `filter`, `reduce`), typed functions, combinators.
    *   Pattern Matching: `when` expressions (literals, wildcards, types, results, lists, tables).
    *   Recursion and Composition: Simple, tail-recursive, mutual recursion, functional composition.
    *   Types: Optional types, runtime type inference, validation, numeric lattices, `Result` type.
*   **Analyzed Core Implementation:**
    *   `interpreter.js`: Execution, scope, native functions (`io`, math, list/table ops), type validation, function calls (closures, partial application).
    *   `runner.js`: Lexing, parsing, interpretation pipeline, error handling.

### Phase 2: Game Engine Architecture Design
*(In Progress)*

*   **Goal:** To create a text adventure game engine using the Baba Yaga language, enabling users to implement games using only Baba Yaga. The games will be playable in the terminal or the browser, with identical core functionality (except for visual enhancements in the browser).

*   **Core Components:**
    *   **JavaScript Host Components:**
        *   **Game Loop Manager:** Orchestrates the flow of the game.
        *   **Input/Output Abstraction:** Leverages Baba Yaga's `io` functions (`io.in`, `io.listen`, `io.out`, `io.emit`) to handle player input and game output across different environments.
        *   **Game State Management:** Implemented using the Elm Architecture (TEA) principles in JavaScript. Manages a serializable state object that represents the current game world, player status, available actions, and visual elements. Supports snapshotting, rewinding, and state restoration (save/load functionality).
        *   **Command Parser/Input Handler:** Presents players with predefined lists of verbs and nouns for interaction. In the terminal, this will be a numbered list or a richer TUI interface. In the browser, this will be clickable links/buttons. These selections are passed to the Baba Yaga script via the IO abstraction.
        *   **Rendering Abstraction:** Provides a unified way to render the game state, abstracting differences between terminal (TUI) and browser (HTML/CSS) output. Browser versions will support optional visual-novel style background images that can change based on game state.
    *   **Baba Yaga Game Script (`.baba` files):**
        *   Monolithic files initially, defining game logic, world, items, narrative, puzzles, and player interaction using Baba Yaga's features.
        *   Will define and mutate the game state through function composition.
        *   Will reference image assets in a structured directory alongside the `.baba` file for browser-based visual enhancements.

*   **Integration & Execution:**
    *   The JavaScript engine will use the existing Baba Yaga interpreter to execute game scripts.
    *   Player selections from the JS host are passed as messages/inputs to the Baba Yaga interpreter via its `io` words.
    *   Baba Yaga scripts, through function composition, will mutate the game state.
    *   The JS engine will manage the serialization and deserialization of the full state object for saving/loading.

*   **State Object (`Model`) Structure:**
    *   `current_scene`: Represents the player's current location. This could be a scene ID or a detailed scene object.
    *   `scenes`: A collection (e.g., map/dictionary) of all scenes in the game, mapping scene identifiers to scene objects. Each scene object will contain:
        *   Description text.
        *   Available actions and nouns relevant to the scene.
        *   Connections to other scenes (e.g., mapping directions to scene identifiers).
        *   Optional visual elements (e.g., background image paths) for browser rendering.
    *   The entire state object will be serializable (e.g., to JSON) for persistence.

*   **Example Implementation:**
    *   Create a simple `example.baba` to demonstrate basic game loop, scene navigation, item interaction, and state saving/loading.

### Phase 3: Detailed Technical Specifications

#### 3.1 Core Data Structures and Types

**Game State Model (Baba Yaga Table Structure):**
```baba
// Core game state structure - simplified and focused
GameState : {
  current_scene_id: String,
  player: Player,
  inventory: List,
  flags: Table,
  history: List,
  messages: List  // Recent game messages for UI
};

// Player state
Player : {
  name: String,
  health: Int,
  max_health: Int,
  location: String,
  attributes: Table
};

// Scene definition - returned by scene functions
Scene : {
  id: String,
  title: String,
  description: String,
  exits: Table,  // direction -> scene_id
  items: List,   // item_ids
  npcs: List,    // npc_ids
  actions: List, // available action_ids
  background: String, // optional image path
  visited: Bool
};

// Action definition
Action : {
  id: String,
  name: String,
  description: String,
  verbs: List,   // ["take", "pick up", "grab"]
  nouns: List,   // ["key", "sword", "book"]
  conditions: Function, // (state, args) -> Bool
  effect: Function,     // (state, args) -> GameState
  available: Function   // (state) -> Bool
};

// Item definition
Item : {
  id: String,
  name: String,
  description: String,
  portable: Bool,
  usable: Bool,
  actions: List, // action_ids
  properties: Table
};
```

**Scene Management Architecture - State as Functions:**

```baba
// Scene functions that take game state and return scene data
// This allows scenes to be dynamic and responsive to game state

entrance_scene : state -> {
  id: "entrance",
  title: "Cave Entrance",
  description: when state.flags.torch_lit is
    true then "The cave entrance is illuminated by your torch, revealing ancient markings on the walls..."
    false then "You stand at the entrance to a dark cave. The shadows seem to swallow all light...",
  exits: when state.flags.cave_unlocked is
    true then { "north": "main_cavern", "east": "side_tunnel" }
    false then { "north": "main_cavern" },
  items: when state.flags.torch_taken is
    true then []
    false then ["torch"],
  npcs: when state.flags.old_man_met is
    true then []
    false then ["old_man"],
  actions: ["take", "look", "move", "talk"],
  background: when state.flags.torch_lit is
    true then "cave_entrance_lit.jpg"
    false then "cave_entrance_dark.jpg",
  visited: state.flags.entrance_visited
};

main_cavern_scene : state -> {
  id: "main_cavern",
  title: "Main Cavern",
  description: when state.flags.torch_lit is
    true then "A vast cavern stretches before you, stalactites glistening in the torchlight..."
    false then "Complete darkness. You can hear water dripping somewhere in the distance...",
  exits: { "south": "entrance", "east": "treasure_room", "west": "chasm" },
  items: when state.flags.sword_found is
    true then []
    false then ["ancient_sword"],
  actions: ["take", "look", "move", "listen"],
  background: "main_cavern.jpg",
  visited: state.flags.main_cavern_visited
};

// Scene registry function
scene_registry : scene_id ->
  when scene_id is
    "entrance" then entrance_scene
    "main_cavern" then main_cavern_scene
    "treasure_room" then treasure_room_scene
    "side_tunnel" then side_tunnel_scene
    "chasm" then chasm_scene
    _ then error_scene;

// Scene resolver - gets current scene data
get_current_scene : state ->
  (scene_registry state.current_scene_id) state;

// Scene state management
mark_scene_visited : state scene_id ->
  { state with flags: set state.flags (scene_id .. "_visited") true };

update_scene_flag : state scene_id flag_name value ->
  { state with flags: set state.flags (scene_id .. "_" .. flag_name) value };
```

**Scene Composition Utilities:**

```baba
// Scene building blocks for composition
base_scene : id title description -> {
  id: id,
  title: title,
  description: description,
  exits: {},
  items: [],
  npcs: [],
  actions: ["look"],
  background: "",
  visited: false
};

with_exits : scene exits -> { scene with exits: exits };
with_items : scene items -> { scene with items: items };
with_npcs : scene npcs -> { scene with npcs: npcs };
with_actions : scene actions -> { scene with actions: actions };
with_background : scene bg -> { scene with background: bg };

// Conditional scene modifiers
with_conditional_exits : scene condition exits ->
  when condition is
    true then with_exits scene exits
    false then scene;

with_conditional_items : scene condition items ->
  when condition is
    true then with_items scene items
    false then scene;

// Example of composed scene
simple_entrance : state ->
  pipe
    (base_scene "entrance" "Cave Entrance" "You stand at the entrance...")
    (with_exits { "north": "main_cavern" })
    (with_conditional_items (not state.flags.torch_taken) ["torch"])
    (with_actions ["take", "look", "move"])
    (with_background "cave_entrance.jpg");
```

#### 3.2 JavaScript Host API Interface

**Game Engine Class Structure:**
```javascript
class BabaYagaGameEngine {
  constructor(gameScript, options = {}) {
    this.gameScript = gameScript;
    this.interpreter = null;
    this.currentState = null;
    this.history = [];
    this.maxHistory = options.maxHistory || 50;
    this.assetPath = options.assetPath || './assets';
    this.eventListeners = new Map();
    this.memoizedScenes = new Map();
    
    // IO abstraction for Baba Yaga
    this.host = {
      io: {
        out: this.handleOutput.bind(this),
        in: this.handleInput.bind(this),
        emit: this.handleEmit.bind(this),
        listen: this.handleListen.bind(this)
      }
    };
  }

  // Core game loop methods
  async initialize() { 
    try {
      // Initialize Baba Yaga interpreter
      const result = await this.evaluateBabaYaga('init_game()');
      if (result.ok) {
        this.currentState = result.value;
        this.pushToHistory(this.currentState);
        return { ok: true, state: this.currentState };
      } else {
        throw new GameError('Failed to initialize game', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Initialization failed', 'runtime', error);
    }
  }

  async processCommand(verb, noun) {
    try {
      // Validate input
      if (!verb || typeof verb !== 'string') {
        throw new GameError('Invalid verb', 'input', { verb, noun });
      }

      // Process action through Baba Yaga
      const actionCall = `process_action(${JSON.stringify(this.currentState)}, "${verb}", "${noun || ''}")`;
      const result = await this.evaluateBabaYaga(actionCall);
      
      if (result.ok) {
        const newState = result.value;
        this.setState(newState);
        this.pushToHistory(newState);
        
        // Mark scene as visited
        const sceneCall = `mark_scene_visited(${JSON.stringify(newState)}, "${newState.current_scene_id}")`;
        const sceneResult = await this.evaluateBabaYaga(sceneCall);
        if (sceneResult.ok) {
          this.setState(sceneResult.value);
        }
        
        return { ok: true, state: this.currentState };
      } else {
        throw new GameError('Action processing failed', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Command processing failed', 'runtime', error);
    }
  }

  async saveGame(slot) {
    try {
      const saveCall = `save_game(${JSON.stringify(this.currentState)})`;
      const result = await this.evaluateBabaYaga(saveCall);
      
      if (result.ok) {
        const serializedState = result.value;
        // Store in localStorage or file system
        if (typeof localStorage !== 'undefined') {
          localStorage.setItem(`baba_yaga_save_${slot}`, serializedState);
        }
        return { ok: true, slot };
      } else {
        throw new GameError('Save failed', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Save operation failed', 'runtime', error);
    }
  }

  async loadGame(slot) {
    try {
      let serializedState;
      if (typeof localStorage !== 'undefined') {
        serializedState = localStorage.getItem(`baba_yaga_save_${slot}`);
      }
      
      if (!serializedState) {
        throw new GameError('Save file not found', 'state', { slot });
      }

      const loadCall = `load_game("${serializedState}")`;
      const result = await this.evaluateBabaYaga(loadCall);
      
      if (result.ok) {
        this.setState(result.value);
        this.pushToHistory(result.value);
        return { ok: true, state: this.currentState };
      } else {
        throw new GameError('Load failed', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Load operation failed', 'runtime', error);
    }
  }

  async undo() {
    if (this.history.length > 1) {
      this.history.pop(); // Remove current state
      const previousState = this.history[this.history.length - 1];
      this.setState(previousState);
      return { ok: true, state: this.currentState };
    }
    return { ok: false, error: 'No history to undo' };
  }
  
  // State management
  getCurrentState() { 
    return this.currentState; 
  }

  setState(newState) { 
    this.currentState = newState;
    // Clear memoized scenes when state changes
    this.memoizedScenes.clear();
    // Emit state change event
    this.emit('stateChanged', newState);
  }

  pushToHistory(state) { 
    this.history.push(JSON.parse(JSON.stringify(state))); // Deep clone
    if (this.history.length > this.maxHistory) {
      this.history.shift();
    }
  }

  // Baba Yaga evaluation
  async evaluateBabaYaga(code) {
    try {
      // Combine game script with evaluation code
      const fullCode = this.gameScript + '\n' + code;
      const result = await evaluate(fullCode, this.host);
      return result;
    } catch (error) {
      return { ok: false, error };
    }
  }

  // Scene management
  async getCurrentScene() {
    if (!this.currentState) return null;
    
    // Check memoization
    const memoKey = `${this.currentState.current_scene_id}_${JSON.stringify(this.currentState.flags)}`;
    if (this.memoizedScenes.has(memoKey)) {
      return this.memoizedScenes.get(memoKey);
    }

    try {
      const sceneCall = `get_current_scene(${JSON.stringify(this.currentState)})`;
      const result = await this.evaluateBabaYaga(sceneCall);
      
      if (result.ok) {
        this.memoizedScenes.set(memoKey, result.value);
        return result.value;
      } else {
        throw new GameError('Failed to get scene', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Scene retrieval failed', 'runtime', error);
    }
  }

  async getAvailableActions() {
    try {
      const actionsCall = `get_available_actions(${JSON.stringify(this.currentState)})`;
      const result = await this.evaluateBabaYaga(actionsCall);
      
      if (result.ok) {
        return result.value;
      } else {
        throw new GameError('Failed to get actions', 'runtime', result.error);
      }
    } catch (error) {
      throw new GameError('Action retrieval failed', 'runtime', error);
    }
  }

  // Event handling
  handleOutput(...args) {
    const message = args.map(arg => String(arg)).join(' ');
    this.emit('output', message);
  }

  handleInput() {
    // This would be implemented by the UI layer
    return '';
  }

  handleEmit(topic, data) {
    this.emit(topic, data);
  }

  handleListen(topic, handler) {
    if (!this.eventListeners.has(topic)) {
      this.eventListeners.set(topic, []);
    }
    this.eventListeners.get(topic).push(handler);
    
    // Return unsubscribe function
    return () => {
      const listeners = this.eventListeners.get(topic);
      const index = listeners.indexOf(handler);
      if (index > -1) {
        listeners.splice(index, 1);
      }
    };
  }

  emit(event, data) {
    const listeners = this.eventListeners.get(event) || [];
    listeners.forEach(listener => {
      try {
        listener(data);
      } catch (error) {
        console.error('Event listener error:', error);
      }
    });
  }

  // Rendering
  async render() { 
    const scene = await this.getCurrentScene();
    const actions = await this.getAvailableActions();
    return { scene, actions, state: this.currentState };
  }
}

// Game error class
class GameError extends Error {
  constructor(message, type, details) {
    super(message);
    this.name = 'GameError';
    this.type = type; // 'parse', 'runtime', 'state', 'asset', 'input'
    this.details = details;
  }
}
```

**Game Loop Implementation:**
```javascript
class GameLoop {
  constructor(engine, interface) {
    this.engine = engine;
    this.interface = interface;
    this.isRunning = false;
    this.pendingInput = null;
    this.inputResolver = null;
  }

  async start() {
    this.isRunning = true;
    
    try {
      // Initialize game
      await this.engine.initialize();
      
      // Initial render
      await this.render();
      
      // Start input loop
      await this.inputLoop();
    } catch (error) {
      this.interface.handleError(error);
    }
  }

  async inputLoop() {
    while (this.isRunning) {
      try {
        // Wait for input
        const input = await this.waitForInput();
        
        if (input.type === 'command') {
          await this.processCommand(input.verb, input.noun);
        } else if (input.type === 'system') {
          await this.processSystemCommand(input.command);
        }
        
        // Render updated state
        await this.render();
      } catch (error) {
        this.interface.handleError(error);
      }
    }
  }

  async waitForInput() {
    return new Promise((resolve) => {
      this.inputResolver = resolve;
    });
  }

  async processCommand(verb, noun) {
    const result = await this.engine.processCommand(verb, noun);
    if (!result.ok) {
      throw new GameError('Command failed', 'runtime', result.error);
    }
  }

  async processSystemCommand(command) {
    switch (command) {
      case 'save':
        await this.engine.saveGame('auto');
        break;
      case 'load':
        await this.engine.loadGame('auto');
        break;
      case 'undo':
        await this.engine.undo();
        break;
      case 'quit':
        this.isRunning = false;
        break;
      default:
        throw new GameError(`Unknown system command: ${command}`, 'input');
    }
  }

  async render() {
    const renderData = await this.engine.render();
    this.interface.render(renderData);
  }

  provideInput(input) {
    if (this.inputResolver) {
      this.inputResolver(input);
      this.inputResolver = null;
    }
  }

  stop() {
    this.isRunning = false;
  }
}
```

**Terminal Interface:**
```javascript
class TerminalGameInterface {
  constructor(engine) {
    this.engine = engine;
    this.gameLoop = new GameLoop(engine, this);
    this.inputBuffer = '';
    this.isInputMode = false;
  }

  async start() {
    // Set up terminal input handling
    process.stdin.setRawMode(true);
    process.stdin.resume();
    process.stdin.setEncoding('utf8');
    
    process.stdin.on('data', (key) => {
      this.handleKeyPress(key);
    });

    // Start game loop
    await this.gameLoop.start();
  }

  handleKeyPress(key) {
    if (key === '\u0003') { // Ctrl+C
      this.quit();
      return;
    }

    if (this.isInputMode) {
      if (key === '\r' || key === '\n') { // Enter
        this.submitInput();
      } else if (key === '\u007f') { // Backspace
        this.inputBuffer = this.inputBuffer.slice(0, -1);
        this.redrawInput();
      } else {
        this.inputBuffer += key;
        this.redrawInput();
      }
    } else {
      // Handle menu navigation
      this.handleMenuKey(key);
    }
  }

  async render(renderData) {
    const { scene, actions, state } = renderData;
    
    // Clear screen
    process.stdout.write('\x1B[2J\x1B[0f');
    
    // Render scene
    this.renderScene(scene);
    
    // Render actions
    this.renderActions(actions);
    
    // Render status
    this.renderStatus(state);
    
    // Show input prompt
    this.showInputPrompt();
  }

  renderScene(scene) {
    console.log(`\n${scene.title}`);
    console.log('='.repeat(scene.title.length));
    console.log(scene.description);
    
    if (scene.items.length > 0) {
      console.log('\nItems here:');
      scene.items.forEach(item => console.log(`  - ${item}`));
    }
    
    if (Object.keys(scene.exits).length > 0) {
      console.log('\nExits:');
      Object.entries(scene.exits).forEach(([direction, target]) => {
        console.log(`  ${direction}: ${target}`);
      });
    }
  }

  renderActions(actions) {
    console.log('\nAvailable actions:');
    actions.forEach((action, index) => {
      console.log(`  ${index + 1}. ${action}`);
    });
  }

  renderStatus(state) {
    console.log('\nStatus:');
    console.log(`  Location: ${state.current_scene_id}`);
    console.log(`  Health: ${state.player.health}/${state.player.max_health}`);
    console.log(`  Inventory: ${state.inventory.length} items`);
  }

  showInputPrompt() {
    console.log('\n> ');
    this.isInputMode = true;
  }

  submitInput() {
    const input = this.inputBuffer.trim();
    this.inputBuffer = '';
    this.isInputMode = false;
    
    if (input.startsWith('/')) {
      this.gameLoop.provideInput({ type: 'system', command: input.slice(1) });
    } else {
      // Parse verb/noun from input
      const parts = input.split(' ');
      const verb = parts[0];
      const noun = parts.slice(1).join(' ');
      this.gameLoop.provideInput({ type: 'command', verb, noun });
    }
  }

  redrawInput() {
    process.stdout.write(`\r> ${this.inputBuffer}`);
  }

  handleError(error) {
    console.error(`\nError: ${error.message}`);
    if (error.details) {
      console.error('Details:', error.details);
    }
  }

  quit() {
    process.exit(0);
  }
}
```

**Browser Interface:**
```javascript
class BrowserGameInterface {
  constructor(engine, container) {
    this.engine = engine;
    this.container = container;
    this.gameLoop = new GameLoop(engine, this);
    this.actionButtons = new Map();
    this.messageQueue = [];
    
    this.setupEventListeners();
  }

  setupEventListeners() {
    // Listen for engine events
    this.engine.on('output', (message) => {
      this.addMessage(message, 'output');
    });

    this.engine.on('stateChanged', (state) => {
      this.updateUI(state);
    });
  }

  async start() {
    await this.gameLoop.start();
  }

  async render(renderData) {
    const { scene, actions, state } = renderData;
    
    // Clear container
    this.container.innerHTML = '';
    
    // Render scene
    this.renderScene(scene);
    
    // Render actions
    this.renderActions(actions);
    
    // Render status
    this.renderStatus(state);
    
    // Render messages
    this.renderMessages();
    
    // Render controls
    this.renderControls();
  }

  renderScene(scene) {
    const sceneEl = document.createElement('div');
    sceneEl.className = 'game-scene';
    
    // Background image
    if (scene.background) {
      sceneEl.style.backgroundImage = `url(${this.engine.assetPath}/images/${scene.background})`;
    }
    
    // Scene content
    const titleEl = document.createElement('h2');
    titleEl.textContent = scene.title;
    sceneEl.appendChild(titleEl);
    
    const descEl = document.createElement('p');
    descEl.textContent = scene.description;
    sceneEl.appendChild(descEl);
    
    // Items
    if (scene.items.length > 0) {
      const itemsEl = document.createElement('div');
      itemsEl.className = 'scene-items';
      itemsEl.innerHTML = '<h3>Items here:</h3>';
      scene.items.forEach(item => {
        const itemEl = document.createElement('div');
        itemEl.textContent = `- ${item}`;
        itemsEl.appendChild(itemEl);
      });
      sceneEl.appendChild(itemsEl);
    }
    
    // Exits
    if (Object.keys(scene.exits).length > 0) {
      const exitsEl = document.createElement('div');
      exitsEl.className = 'scene-exits';
      exitsEl.innerHTML = '<h3>Exits:</h3>';
      Object.entries(scene.exits).forEach(([direction, target]) => {
        const exitEl = document.createElement('div');
        exitEl.textContent = `${direction}: ${target}`;
        exitsEl.appendChild(exitEl);
      });
      sceneEl.appendChild(exitsEl);
    }
    
    this.container.appendChild(sceneEl);
  }

  renderActions(actions) {
    const actionsEl = document.createElement('div');
    actionsEl.className = 'game-actions';
    
    actionsEl.innerHTML = '<h3>Available actions:</h3>';
    
    actions.forEach((action, index) => {
      const button = document.createElement('button');
      button.textContent = action;
      button.className = 'action-button';
      button.onclick = () => this.handleAction(action);
      actionsEl.appendChild(button);
    });
    
    this.container.appendChild(actionsEl);
  }

  renderStatus(state) {
    const statusEl = document.createElement('div');
    statusEl.className = 'game-status';
    
    statusEl.innerHTML = `
      <h3>Status:</h3>
      <p>Location: ${state.current_scene_id}</p>
      <p>Health: ${state.player.health}/${state.player.max_health}</p>
      <p>Inventory: ${state.inventory.length} items</p>
    `;
    
    this.container.appendChild(statusEl);
  }

  renderMessages() {
    if (this.messageQueue.length > 0) {
      const messagesEl = document.createElement('div');
      messagesEl.className = 'game-messages';
      
      this.messageQueue.forEach(message => {
        const messageEl = document.createElement('div');
        messageEl.className = `message message-${message.type}`;
        messageEl.textContent = message.text;
        messagesEl.appendChild(messageEl);
      });
      
      this.container.appendChild(messagesEl);
      this.messageQueue = [];
    }
  }

  renderControls() {
    const controlsEl = document.createElement('div');
    controlsEl.className = 'game-controls';
    
    const saveBtn = document.createElement('button');
    saveBtn.textContent = 'Save';
    saveBtn.onclick = () => this.gameLoop.provideInput({ type: 'system', command: 'save' });
    
    const loadBtn = document.createElement('button');
    loadBtn.textContent = 'Load';
    loadBtn.onclick = () => this.gameLoop.provideInput({ type: 'system', command: 'load' });
    
    const undoBtn = document.createElement('button');
    undoBtn.textContent = 'Undo';
    undoBtn.onclick = () => this.gameLoop.provideInput({ type: 'system', command: 'undo' });
    
    controlsEl.appendChild(saveBtn);
    controlsEl.appendChild(loadBtn);
    controlsEl.appendChild(undoBtn);
    
    this.container.appendChild(controlsEl);
  }

  handleAction(action) {
    // Parse action into verb/noun
    const parts = action.split(' ');
    const verb = parts[0];
    const noun = parts.slice(1).join(' ');
    
    this.gameLoop.provideInput({ type: 'command', verb, noun });
  }

  addMessage(text, type = 'output') {
    this.messageQueue.push({ text, type });
  }

  updateUI(state) {
    // Update any UI elements that depend on state
    // This could include updating inventory display, health bars, etc.
  }

  handleError(error) {
    this.addMessage(`Error: ${error.message}`, 'error');
    if (error.details) {
      console.error('Game error details:', error.details);
    }
  }
}
```

#### 3.3 Baba Yaga Game Script API

**Required Game Functions:**
```baba
// Game initialization
init_game : () -> GameState;

// Core game loop functions
process_action : (state: GameState, verb: String, noun: String) -> GameState;
get_available_actions : (state: GameState) -> List;
render_scene : (state: GameState) -> String;

// State management
save_game : (state: GameState) -> String; // Returns serialized state
load_game : (serialized: String) -> GameState;

// Utility functions
is_action_available : (state: GameState, action_id: String) -> Bool;
get_item_by_id : (items: List, item_id: String) -> Maybe Item;
get_scene_by_id : (scenes: Table, scene_id: String) -> Maybe Scene;
```

**Example Game Script Structure:**
```baba
// Game data definitions
scenes : {
  "entrance": {
    id: "entrance",
    title: "Cave Entrance",
    description: "You stand at the entrance to a dark cave...",
    exits: { "north": "main_cavern" },
    items: ["torch"],
    npcs: [],
    actions: ["take", "look", "move"],
    background: "cave_entrance.jpg",
    visited: false
  }
};

items : {
  "torch": {
    id: "torch",
    name: "Wooden Torch",
    description: "A simple wooden torch...",
    portable: true,
    usable: true,
    actions: ["light", "extinguish"],
    properties: { "lit": false }
  }
};

// Game logic functions
init_game : () -> {
  current_scene: "entrance",
  scenes: scenes,
  player: {
    name: "Adventurer",
    health: 100,
    max_health: 100,
    location: "entrance",
    attributes: { "strength": 10, "intelligence": 8 }
  },
  inventory: [],
  flags: { "torch_lit": false },
  history: []
};

process_action : state verb noun ->
  when verb noun is
    "take" "torch" then take_torch state
    "move" "north" then move_north state
    "look" _ then look_around state
    _ _ then state; // Unknown action, return unchanged state

take_torch : state ->
  when is_item_in_scene state "torch" is
    true then {
      state with
      inventory: append state.inventory ["torch"],
      scenes: update_scene_items state.scenes state.current_scene (remove_item "torch")
    }
    false then state;

move_north : state ->
  when get_scene_exit state.current_scene "north" is
    Just scene_id then {
      state with
      current_scene: scene_id,
      player: { state.player with location: scene_id }
    }
    Nothing then state;
```

#### 3.4 File Structure and Asset Management

**Project Structure:**
```
game-name/
├── game.baba              # Main game script
├── assets/                # Game assets
│   ├── images/            # Background images
│   │   ├── cave_entrance.jpg
│   │   ├── main_cavern.jpg
│   │   └── ...
│   ├── sounds/           # Audio files (future)
│   └── data/             # Additional game data
├── saves/                # Save game files
│   ├── save1.json
│   ├── save2.json
│   └── ...
└── README.md             # Game documentation
```

**Asset Loading Strategy:**
- Browser: Assets loaded via HTTP requests, cached for performance
- Terminal: Asset paths stored but not loaded (text-only mode)
- Fallback: Graceful degradation when assets missing

#### 3.5 Integration Patterns and Usage Examples

**Basic Game Setup:**
```javascript
// Browser usage
import { BabaYagaGameEngine, BrowserGameInterface } from './game-engine.js';

async function startGame() {
  const gameScript = await fetch('./game.baba').then(r => r.text());
  const engine = new BabaYagaGameEngine(gameScript, {
    assetPath: './assets',
    maxHistory: 100
  });
  
  const container = document.getElementById('game-container');
  const interface = new BrowserGameInterface(engine, container);
  
  await interface.start();
}

// Terminal usage
import { BabaYagaGameEngine, TerminalGameInterface } from './game-engine.js';
import { readFileSync } from 'fs';

async function startTerminalGame() {
  const gameScript = readFileSync('./game.baba', 'utf8');
  const engine = new BabaYagaGameEngine(gameScript);
  const interface = new TerminalGameInterface(engine);
  
  await interface.start();
}
```

**Custom Game Interface:**
```javascript
class CustomGameInterface {
  constructor(engine) {
    this.engine = engine;
    this.gameLoop = new GameLoop(engine, this);
  }

  async render(renderData) {
    const { scene, actions, state } = renderData;
    
    // Custom rendering logic
    this.updateSceneDisplay(scene);
    this.updateActionButtons(actions);
    this.updateStatusBar(state);
  }

  updateSceneDisplay(scene) {
    // Custom scene rendering
    const sceneEl = document.getElementById('scene');
    sceneEl.innerHTML = `
      <h1>${scene.title}</h1>
      <p>${scene.description}</p>
      ${this.renderItems(scene.items)}
      ${this.renderExits(scene.exits)}
    `;
  }

  updateActionButtons(actions) {
    const actionsEl = document.getElementById('actions');
    actionsEl.innerHTML = actions.map(action => 
      `<button onclick="handleAction('${action}')">${action}</button>`
    ).join('');
  }

  updateStatusBar(state) {
    const statusEl = document.getElementById('status');
    statusEl.innerHTML = `
      Location: ${state.current_scene_id} | 
      Health: ${state.player.health}/${state.player.max_health} | 
      Items: ${state.inventory.length}
    `;
  }

  handleError(error) {
    console.error('Game error:', error);
    // Custom error handling
  }
}
```

**Event-Driven Game Logic:**
```javascript
// Listen for game events
engine.on('stateChanged', (newState) => {
  console.log('Game state updated:', newState.current_scene_id);
  updateUI(newState);
});

engine.on('output', (message) => {
  addToMessageLog(message);
});

// Custom event handling
engine.on('itemPickedUp', (item) => {
  playSound('pickup');
  showNotification(`Picked up ${item}`);
});

engine.on('sceneEntered', (scene) => {
  if (scene.background) {
    preloadImage(scene.background);
  }
});
```

**Advanced State Management:**
```javascript
class AdvancedGameEngine extends BabaYagaGameEngine {
  constructor(gameScript, options = {}) {
    super(gameScript, options);
    this.stateObservers = new Set();
    this.stateMiddleware = [];
  }

  addStateObserver(observer) {
    this.stateObservers.add(observer);
  }

  addStateMiddleware(middleware) {
    this.stateMiddleware.push(middleware);
  }

  setState(newState) {
    // Apply middleware
    let processedState = newState;
    for (const middleware of this.stateMiddleware) {
      processedState = middleware(processedState, this.currentState);
    }

    // Update state
    super.setState(processedState);

    // Notify observers
    for (const observer of this.stateObservers) {
      observer(processedState, this.currentState);
    }
  }

  // Custom state validation
  validateState(state) {
    const errors = [];
    
    if (!state.current_scene_id) {
      errors.push('Missing current_scene_id');
    }
    
    if (!state.player) {
      errors.push('Missing player data');
    }
    
    if (state.player.health < 0) {
      errors.push('Player health cannot be negative');
    }
    
    return errors.length === 0 ? null : errors;
  }
}
```

**Performance Optimizations:**
```javascript
class OptimizedGameEngine extends BabaYagaGameEngine {
  constructor(gameScript, options = {}) {
    super(gameScript, options);
    this.sceneCache = new Map();
    this.actionCache = new Map();
    this.cacheTimeout = options.cacheTimeout || 5000; // 5 seconds
  }

  async getCurrentScene() {
    const cacheKey = this.getCacheKey();
    const cached = this.sceneCache.get(cacheKey);
    
    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
      return cached.data;
    }

    const scene = await super.getCurrentScene();
    this.sceneCache.set(cacheKey, {
      data: scene,
      timestamp: Date.now()
    });

    return scene;
  }

  getCacheKey() {
    return `${this.currentState.current_scene_id}_${JSON.stringify(this.currentState.flags)}`;
  }

  // Batch state updates
  batchUpdate(updates) {
    let currentState = this.currentState;
    
    for (const update of updates) {
      currentState = update(currentState);
    }
    
    this.setState(currentState);
  }

  // Debounced rendering
  debouncedRender = debounce(async () => {
    const renderData = await this.render();
    this.emit('render', renderData);
  }, 16); // ~60fps
}

function debounce(func, wait) {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
}
```

**Testing Integration:**
```javascript
class TestableGameEngine extends BabaYagaGameEngine {
  constructor(gameScript, options = {}) {
    super(gameScript, options);
    this.testMode = options.testMode || false;
    this.mockIO = options.mockIO || null;
  }

  async evaluateBabaYaga(code) {
    if (this.testMode && this.mockIO) {
      // Use mock IO for testing
      const testHost = { ...this.host, io: this.mockIO };
      return await evaluate(this.gameScript + '\n' + code, testHost);
    }
    return await super.evaluateBabaYaga(code);
  }

  // Test utilities
  setTestState(state) {
    this.currentState = state;
  }

  getTestState() {
    return this.currentState;
  }

  simulateAction(verb, noun) {
    return this.processCommand(verb, noun);
  }
}

// Test example
describe('Game Engine Tests', () => {
  let engine;
  let mockIO;

  beforeEach(() => {
    mockIO = {
      out: jest.fn(),
      in: jest.fn(() => 'test input'),
      emit: jest.fn(),
      listen: jest.fn()
    };

    engine = new TestableGameEngine(gameScript, {
      testMode: true,
      mockIO
    });
  });

  it('should process take torch action', async () => {
    const initialState = createTestState('entrance', { torch_taken: false });
    engine.setTestState(initialState);

    const result = await engine.simulateAction('take', 'torch');
    
    expect(result.ok).toBe(true);
    expect(result.state.inventory).toContain('torch');
    expect(result.state.flags.torch_taken).toBe(true);
  });
});
```

#### 3.6 Error Handling and Validation

**Baba Yaga Error Handling:**
```baba
// Use Result type for error handling
validate_action : state verb noun ->
  when is_valid_verb verb is
    true then when is_valid_noun noun is
      true then Ok (verb, noun)
      false then Err "Invalid noun"
    false then Err "Invalid verb";

safe_process_action : state verb noun ->
  when validate_action state verb noun is
    Ok (v, n) then process_action state v n
    Err msg then {
      state with
      messages: append state.messages [msg]
    };

// Scene validation
validate_scene_state : state scene_id ->
  when scene_id is
    "entrance" then validate_entrance_state state
    "main_cavern" then validate_cavern_state state
    _ then Ok state;

// State validation utilities
validate_game_state : state ->
  when state is
    { current_scene_id: scene_id, player: player, inventory: inv, flags: flags } then
      when validate_scene_id scene_id is
        Ok _ then when validate_player player is
          Ok _ then when validate_inventory inv is
            Ok _ then Ok state
            Err msg then Err ("Inventory error: " .. msg)
          Err msg then Err ("Player error: " .. msg)
        Err msg then Err ("Scene error: " .. msg)
    _ then Err "Invalid state structure";
```

**JavaScript Error Handling:**
```javascript
class GameError extends Error {
  constructor(message, type, details) {
    super(message);
    this.name = 'GameError';
    this.type = type; // 'parse', 'runtime', 'state', 'asset', 'input'
    this.details = details;
  }
}

// Error recovery strategies
async handleGameError(error) {
  switch (error.type) {
    case 'parse':
      return this.handleParseError(error);
    case 'runtime':
      return this.handleRuntimeError(error);
    case 'state':
      return this.handleStateError(error);
    case 'asset':
      return this.handleAssetError(error);
    case 'input':
      return this.handleInputError(error);
    default:
      return this.handleUnknownError(error);
  }
}

// Specific error handlers
handleParseError(error) {
  console.error('Parse error:', error.message);
  // Could attempt to recover by re-parsing or showing syntax help
  return { ok: false, error: 'Game script has syntax errors' };
}

handleRuntimeError(error) {
  console.error('Runtime error:', error.message);
  // Could attempt to rollback to previous state
  return { ok: false, error: 'Game encountered a runtime error' };
}

handleStateError(error) {
  console.error('State error:', error.message);
  // Could attempt to restore from last known good state
  return { ok: false, error: 'Game state is invalid' };
}

handleAssetError(error) {
  console.error('Asset error:', error.message);
  // Could fall back to text-only mode
  return { ok: true, warning: 'Some assets could not be loaded' };
}

handleInputError(error) {
  console.error('Input error:', error.message);
  // Could show input help or suggestions
  return { ok: false, error: 'Invalid input provided' };
}
```

#### 3.7 Performance Considerations

**State Management Optimization:**
- Immutable state updates using structural sharing
- Lazy evaluation of expensive computations
- State history with configurable depth
- Efficient serialization/deserialization
- Memoization of scene functions
- Batch state updates to reduce re-renders

**Rendering Optimization:**
- Incremental UI updates
- Debounced action processing
- Asset preloading for browser interface
- Virtual scrolling for long text output
- Scene caching with TTL
- Event batching for multiple state changes

**Memory Management:**
```javascript
class MemoryOptimizedEngine extends BabaYagaGameEngine {
  constructor(gameScript, options = {}) {
    super(gameScript, options);
    this.weakRefs = new WeakMap();
    this.gcThreshold = options.gcThreshold || 1000;
    this.operationCount = 0;
  }

  setState(newState) {
    super.setState(newState);
    this.operationCount++;
    
    if (this.operationCount > this.gcThreshold) {
      this.performGarbageCollection();
    }
  }

  performGarbageCollection() {
    // Clear caches
    this.memoizedScenes.clear();
    this.sceneCache.clear();
    this.actionCache.clear();
    
    // Trim history if too long
    if (this.history.length > this.maxHistory * 2) {
      this.history = this.history.slice(-this.maxHistory);
    }
    
    this.operationCount = 0;
  }
}
```

#### 3.8 Testing Strategy

**Unit Tests:**
- Baba Yaga game logic functions
- JavaScript engine components
- State management operations
- Error handling scenarios
- Scene function validation
- Action processing logic

**Integration Tests:**
- Full game loop execution
- Save/load functionality
- Cross-platform compatibility
- Asset loading and rendering
- Event system integration
- State persistence

**Example Test Structure:**
```javascript
describe('Game Engine', () => {
  it('should initialize game state correctly', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    const state = engine.getCurrentState();
    expect(state.current_scene_id).toBe('entrance');
  });

  it('should process valid actions', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    const result = await engine.processCommand('take', 'torch');
    expect(result.ok).toBe(true);
    expect(result.state.inventory).toContain('torch');
  });

  it('should handle invalid actions gracefully', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    const result = await engine.processCommand('invalid', 'action');
    expect(result.ok).toBe(true); // Should not crash, just return unchanged state
  });

  it('should maintain state history', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    const initialState = engine.getCurrentState();
    await engine.processCommand('take', 'torch');
    
    expect(engine.history.length).toBe(2);
    expect(engine.history[0]).toEqual(initialState);
  });
});

describe('Scene Functions', () => {
  it('should return different descriptions based on state', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    const scene1 = await engine.getCurrentScene();
    expect(scene1.description).toContain('dark cave');
    
    // Update state to light torch
    engine.setState({
      ...engine.getCurrentState(),
      flags: { ...engine.getCurrentState().flags, torch_lit: true }
    });
    
    const scene2 = await engine.getCurrentScene();
    expect(scene2.description).toContain('illuminated');
  });
});

describe('Save/Load System', () => {
  it('should save and restore game state', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    await engine.processCommand('take', 'torch');
    const stateBeforeSave = engine.getCurrentState();
    
    await engine.saveGame('test');
    
    // Reset engine
    await engine.initialize();
    expect(engine.getCurrentState().inventory).toEqual([]);
    
    await engine.loadGame('test');
    expect(engine.getCurrentState()).toEqual(stateBeforeSave);
  });
});
```

**Performance Tests:**
```javascript
describe('Performance', () => {
  it('should handle rapid state changes efficiently', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    const startTime = performance.now();
    
    for (let i = 0; i < 100; i++) {
      await engine.processCommand('look', 'around');
    }
    
    const endTime = performance.now();
    expect(endTime - startTime).toBeLessThan(1000); // Should complete in under 1 second
  });

  it('should cache scene data appropriately', async () => {
    const engine = new BabaYagaGameEngine(gameScript);
    await engine.initialize();
    
    // First call should populate cache
    const scene1 = await engine.getCurrentScene();
    expect(engine.memoizedScenes.size).toBe(1);
    
    // Second call should use cache
    const scene2 = await engine.getCurrentScene();
    expect(scene1).toBe(scene2); // Should be the same object reference
  });
});
```

#### 3.8 Architectural Choices Emerging from Scene State as Functions

**Choice 1: Dynamic Scene Content**
*Decision:* Scenes are functions that take game state and return scene data
*Benefits:*
- Scenes can react to player actions and game flags
- Content changes based on story progression
- No need to pre-compute all possible scene variations
- Natural fit for Baba Yaga's functional paradigm

*Consequences:*
- Scene functions must be pure and predictable
- Game state becomes the single source of truth
- Scene testing requires state fixtures

**Choice 2: Lazy Scene Loading**
*Decision:* Only load scene data when needed via function calls
*Benefits:*
- Memory efficient for large games
- Scenes can be defined in separate modules
- Easy to add new scenes without modifying existing code
- Natural code splitting and organization

*Consequences:*
- Scene registry must be maintained
- Error handling for missing scenes
- Potential performance cost of function calls

**Choice 3: State-Driven Rendering**
*Decision:* All scene content (descriptions, exits, items) depends on game state
*Benefits:*
- Consistent state management
- Easy to implement story branches
- Natural progression tracking
- Simplified save/load (only state, not scene data)

*Consequences:*
- Scene functions must handle all state combinations
- More complex scene logic
- Need for state validation

**Choice 4: Composition Over Inheritance**
*Decision:* Use function composition to build complex scenes from simple parts
*Benefits:*
- Reusable scene components
- Easy to test individual parts
- Clear separation of concerns
- Leverages Baba Yaga's functional strengths

*Consequences:*
- Need for composition utilities
- Potential for over-abstraction
- Learning curve for composition patterns

**Choice 5: Immutable Scene Updates**
*Decision:* Scene functions return new scene data, never modify existing state
*Benefits:*
- Predictable behavior
- Easy debugging and testing
- Natural fit with Baba Yaga's immutability
- Enables time-travel debugging

*Consequences:*
- More memory usage for large scenes
- Need for efficient update patterns
- All state changes must be explicit

**Choice 6: Flag-Based State Management**
*Decision:* Use a flat flag structure for tracking game progress
*Benefits:*
- Simple and predictable
- Easy to serialize/deserialize
- Clear naming conventions
- Easy to debug and inspect

*Consequences:*
- Potential for flag explosion
- Need for flag organization strategy
- Manual flag management

**Emerging Patterns and Utilities:**

```baba
// State validation utilities
validate_scene_state : state scene_id ->
  when scene_id is
    "entrance" then validate_entrance_state state
    "main_cavern" then validate_cavern_state state
    _ then Ok state;

// Scene transition utilities
can_transition_to : state from_scene to_scene ->
  when from_scene is
    "entrance" then when to_scene is
      "main_cavern" then true
      "side_tunnel" then state.flags.cave_unlocked
      _ then false
    _ then false;

// Scene content utilities
get_scene_description : state scene_id ->
  when scene_id is
    "entrance" then entrance_scene state.description
    "main_cavern" then main_cavern_scene state.description
    _ then "You are in an unknown location.";

// State update utilities
update_scene_state : state scene_id updates ->
  fold (state, update) -> update state state updates;

// Scene testing utilities
create_test_state : scene_id flags ->
  {
    current_scene_id: scene_id,
    player: default_player,
    inventory: [],
    flags: flags,
    history: [],
    messages: []
  };
```

**Performance Considerations:**
- Scene functions should be memoized for repeated calls
- State updates should be batched when possible
- Scene composition should be optimized for common patterns
- Flag access should be efficient (consider using a more structured approach for large games)

**Scalability Patterns:**
- Scene modules for different game areas
- Shared state utilities across scenes
- Scene templates for common patterns
- State validation at scene boundaries

### Next Steps:

1.  **Implement Core Engine:** Start with the `BabaYagaGameEngine` class and basic state management using the scene state as functions approach.
2.  **Create Scene Function Framework:** Implement the scene registry, composition utilities, and state management functions.
3.  **Build Sample Game:** Develop a simple 2-3 room adventure using the new scene architecture to validate the design.
4.  **Implement State-Driven Rendering:** Create the rendering system that uses scene functions to generate UI content.
5.  **Add Scene Composition Utilities:** Build the `base_scene`, `with_exits`, `with_items` etc. utilities for easy scene creation.
6.  **Enhance Browser Interface:** Extend the existing web app with game-specific UI components that work with dynamic scene content.
7.  **Implement Save/Load:** Add persistence functionality that serializes only the game state (not scene data).
8.  **Add Performance Optimizations:** Implement memoization for scene functions and efficient state updates.
9.  **Create Scene Testing Framework:** Build utilities for testing scene functions with different state configurations.
10. **Documentation and Examples:** Create comprehensive documentation and sample games demonstrating the scene architecture.