# Browser Compatibility for Baba Yaga Language

## Overview

The Baba Yaga language implementation has been updated to support browser environments in addition to Node.js and Bun. This document outlines the changes made and how to use the language in browsers.

## Changes Made

### 1. Cross-Platform Environment Detection

Added environment detection at the top of `lang.js` and `parser.js`:

```javascript
// Cross-platform environment detection
const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
const isBun = typeof process !== 'undefined' && process.versions && process.versions.bun;
const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';

// Cross-platform debug flag
const DEBUG = (isNode && process.env.DEBUG) || (isBrowser && window.DEBUG) || false;
```

### 2. Cross-Platform IO Operations

#### Readline Replacement
- **Node.js/Bun**: Uses `require('readline')` as before
- **Browser**: Falls back to `window.prompt()` for input operations

```javascript
const createReadline = () => {
    if (isNode) {
        const readline = require('readline');
        return readline.createInterface({
            input: process.stdin,
            output: process.stdout
        });
    } else if (isBrowser) {
        // Browser fallback - use prompt() for now
        return {
            question: (prompt, callback) => {
                const result = window.prompt(prompt);
                callback(result);
            },
            close: () => {}
        };
    } else {
        // Bun or other environments
        const readline = require('readline');
        return readline.createInterface({
            input: process.stdin,
            output: process.stdout
        });
    }
};
```

#### Filesystem Replacement
- **Node.js/Bun**: Uses `require('fs')` as before
- **Browser**: Returns mock filesystem that throws errors (file I/O not supported in browsers)

```javascript
const createFileSystem = () => {
    if (isNode) {
        return require('fs');
    } else if (isBrowser) {
        // Browser fallback - return a mock filesystem
        return {
            readFile: (path, encoding, callback) => {
                callback(new Error('File system not available in browser'));
            },
            writeFile: (path, data, callback) => {
                callback(new Error('File system not available in browser'));
            }
        };
    } else {
        // Bun or other environments
        return require('fs');
    }
};
```

### 3. Cross-Platform Console Operations

Added safe console functions that check for console availability:

```javascript
const safeConsoleLog = (message) => {
    if (typeof console !== 'undefined') {
        console.log(message);
    }
};

const safeConsoleError = (message) => {
    if (typeof console !== 'undefined') {
        console.error(message);
    }
};
```

### 4. Cross-Platform Process Exit

Added safe exit function that handles different environments:

```javascript
const safeExit = (code) => {
    if (isNode || isBun) {
        process.exit(code);
    } else if (isBrowser) {
        // In browser, we can't exit, but we can throw an error or redirect
        throw new Error(`Process would exit with code ${code}`);
    }
};
```

### 5. Updated All Debug References

Replaced all `process.env.DEBUG` references with the cross-platform `DEBUG` constant:

```javascript
// Before
if (process.env.DEBUG) {
    console.log('[DEBUG] message');
}

// After
if (DEBUG) {
    safeConsoleLog('[DEBUG] message');
}
```

## Browser Usage

### 1. Basic Setup

To use the language in a browser, include the modules as ES6 imports:

```html
<script type="module">
    import { run } from './lang.js';
    
    // Run a script
    const result = await run('result : add 5 3;');
    console.log(result);
</script>
```

### 2. Debug Mode

To enable debug mode in the browser, set the `DEBUG` flag on the window object:

```javascript
window.DEBUG = true;
```

### 3. Test File

A test file `browser-test.html` has been created that demonstrates:
- Basic arithmetic operations
- Function definitions
- When expressions (pattern matching)
- Table operations
- Custom code execution

## Limitations in Browser Environment

### 1. File I/O Operations
- File reading and writing operations are not available in browsers
- The `readFile()` and `executeFile()` functions will throw errors
- Use the `run()` function directly with script content instead

### 2. Input Operations
- The `..in` operation uses `window.prompt()` which is basic but functional
- For better UX, consider implementing custom input dialogs

### 3. Process Operations
- `process.exit()` is not available in browsers
- The language will throw an error instead of exiting

### 4. Environment Variables
- `process.env` is not available in browsers
- Debug mode is controlled via `window.DEBUG`

## Testing Browser Compatibility

### 1. Local Testing
Open `browser-test.html` in a web browser to test the language:

```bash
# Using Python's built-in server
python -m http.server 8000

# Using Node.js http-server
npx http-server

# Using Bun
bun --hot browser-test.html
```

### 2. Test Cases
The test file includes several test cases:
- **Arithmetic**: Basic math operations
- **Functions**: Function definition and application
- **Pattern Matching**: When expressions with wildcards
- **Tables**: Table literals and operations
- **Custom**: User-defined test cases

## Migration Guide

### From Node.js to Browser

1. **Replace file execution with direct script execution**:
   ```javascript
   // Node.js
   await executeFile('script.txt');
   
   // Browser
   await run(scriptContent);
   ```

2. **Handle debug mode differently**:
   ```javascript
   // Node.js
   process.env.DEBUG = true;
   
   // Browser
   window.DEBUG = true;
   ```

3. **Replace console operations** (automatic):
   ```javascript
   // Both environments now use safeConsoleLog/safeConsoleError
   safeConsoleLog('message');
   ```

### From Browser to Node.js

The language works the same way in both environments. The cross-platform functions automatically detect the environment and use the appropriate implementation.

## Future Enhancements

### 1. Better Browser Input
- Implement custom input dialogs instead of `window.prompt()`
- Support for file uploads for script input

### 2. Browser Storage
- Add support for localStorage/sessionStorage for persistence
- Implement browser-based file system simulation

### 3. Web Workers
- Support for running scripts in Web Workers for better performance
- Background script execution

### 4. Module Loading
- Support for loading external modules in browser environment
- Dynamic script loading capabilities

## Conclusion

The Baba Yaga language is now fully compatible with browser environments while maintaining full functionality in Node.js and Bun. The cross-platform implementation automatically detects the environment and uses appropriate APIs, making it easy to use the language in any JavaScript runtime.

The language maintains its functional programming features, combinator-based architecture, and pattern matching capabilities across all platforms, providing a consistent development experience regardless of the execution environment.