1 files changed, 261 insertions, 0 deletions
diff --git a/js/scripting-lang/design/HISTORY/BROWSER_COMPATIBILITY.md b/js/scripting-lang/design/HISTORY/BROWSER_COMPATIBILITY.md
new file mode 100644
index 0000000..866660a
--- /dev/null
+++ b/js/scripting-lang/design/HISTORY/BROWSER_COMPATIBILITY.md
@@ -0,0 +1,261 @@
+# 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. 
\ No newline at end of file