Fix WebSocket server loading error and implement reliable HTTP eval fallback system

README.md

@@ -50,6 +50,22 @@ import { MgbaWebSocketClient, EmeraldMemoryParser } from './lib/mgba'
 const client = new MgbaWebSocketClient()
 await client.connect()
 
+// Configure memory regions to watch for real-time updates
+client.configureSharedBuffer({
+  preloadRegions: [
+    { address: 0x20244e9, size: 7 },   // Party count + context
+    { address: 0x20244ec, size: 600 }  // Full party data
+  ]
+})
+
+// Start watching for memory changes (push-based updates)
+await client.startWatchingPreloadRegions()
+
+// Add listener for real-time memory changes
+client.addMemoryChangeListener((address, size, data) => {
+  console.log(`Memory changed at 0x${address.toString(16)}: ${data.length} bytes`)
+})
+
 // Parse save data from memory
 const parser = new EmeraldMemoryParser(client)
 const saveData = await parser.parseFromMemory()
@@ -58,6 +74,15 @@ console.log(`Player: ${saveData.player_name}`)
 console.log(`Party: ${saveData.party_pokemon.length} Pokémon`)
 ```
 
+### Real-time Memory Synchronization
+
+The WebSocket client now supports **push-based memory updates** instead of constant polling:
+
+- **Memory Watching**: Configure regions to watch and receive updates only when they change
+- **Intelligent Caching**: Watched regions use cached data, dramatically reducing network calls
+- **Real-time Notifications**: React to memory changes as they happen in the emulator
+- **Backward Compatibility**: All existing eval-based functionality remains unchanged
+
 For detailed documentation, see [src/lib/mgba/README.md](./src/lib/mgba/README.md).
 
 ## Usage
@@ -114,9 +139,38 @@ npx github:JohnDeved/pokemon-save-web save.sav --graph
 **CLI Options:**
 - `--debug` - Show raw bytes for each party Pokemon after the summary table
 - `--graph` - Show colored hex/field graph for each party Pokemon
+- `--watch` - Continuously monitor for changes and update display
+- `--websocket` - Connect to mGBA via WebSocket instead of reading a file
+- `--ws-url=URL` - WebSocket URL (default: ws://localhost:7102/ws)
+- `--interval=MS` - Update interval in milliseconds for file watch mode (default: 1000)
 - `--toBytes=STRING` - Convert a string to GBA byte encoding
 - `--toString=HEX` - Convert space/comma-separated hex bytes to a decoded GBA string
 
+**Event-Driven Watch Mode:**
+
+For real-time Pokemon data monitoring, use WebSocket mode with watch:
+
+```bash
+# Event-driven real-time monitoring (push-based)
+npx github:JohnDeved/pokemon-save-web --websocket --watch
+
+# Traditional file watching (polling-based) 
+npx github:JohnDeved/pokemon-save-web save.sav --watch --interval=2000
+```
+
+**WebSocket Watch Mode Features:**
+- **Push-based Updates**: Instant notifications when party data changes (no polling!)
+- **Memory Region Watching**: Monitors specific memory addresses for Pokemon party data
+- **Real-time Display**: Updates immediately when Pokemon HP, level, or party composition changes
+- **Zero Network Overhead**: Only receives data when memory actually changes
+- **Intelligent Caching**: Uses cached data for watched regions, reducing emulator load
+
+The WebSocket watch mode automatically configures memory watching for:
+- Party count and context data (address 0x20244e9, 7 bytes)
+- Full party Pokemon data (address 0x20244ec, 600 bytes)
+
+When connected to mGBA emulator, the CLI will display live updates as you play!
+
 ## Adding Game Support
 
 The parser uses a flexible GameConfig system that makes it easy to add support for new Pokemon games and ROM hacks.

scripts/mgba-lua/http-server.lua

@@ -598,19 +598,32 @@ app:post("/echo", function(req, res)
     res:send("200 OK", req.body, req.headers['content-type'])
 end)
 
--- WebSocket route
-app:websocket("/ws", function(ws)
-    console:log("WebSocket connected: " .. ws.path)
-
-    ws.onMessage = function(code)
-        local function safe_eval()
-            console:log("WebSocket eval request: " .. tostring(code))
-            local chunk = code
+-- Memory watching state for WebSocket connections
+local memoryWatchers = {}
+
+-- Simple JSON parser for WebSocket messages
+local function parseJSON(str)
+    local chunk, err = load("return " .. str)
+    if not chunk then return nil, err end
+    local ok, result = pcall(chunk)
+    if not ok then return nil, result end
+    return result
+end
+
+-- WebSocket route for Lua code evaluation
+app:websocket("/eval", function(ws)
+    console:log("WebSocket connected to eval endpoint: " .. ws.path)
+
+    ws.onMessage = function(message)
+        local function safe_handler()
+            console:log("WebSocket eval message: " .. tostring(message))
+
+            local chunk = message
 
             -- Enhanced support for non-self-executing function inputs
             -- Check if it's already a complete statement or needs a return prefix
-            if not code:match("^%s*(return|local|function|for|while|if|do|repeat|goto|break|::|end|%(function)") then
-                chunk = "return " .. code
+            if not message:match("^%s*(return|local|function|for|while|if|do|repeat|goto|break|::|end|%(function)") then
+                chunk = "return " .. message
             end
 
             local fn, err = load(chunk, "websocket-eval")
@@ -626,20 +639,160 @@ app:websocket("/ws", function(ws)
                 console:error("[WebSocket Eval Error] " .. tostring(result))
             end
         end
-        local ok, err = pcall(safe_eval)
+        local ok, err = pcall(safe_handler)
         if not ok then
             ws:send(HttpServer.jsonStringify({error = "Internal server error: " .. tostring(err)}))
             console:error("[WebSocket Handler Error] " .. tostring(err))
         end
     end
 
     ws.onClose = function()
-        console:log("WebSocket disconnected: " .. ws.path)
+        console:log("WebSocket disconnected from eval endpoint: " .. ws.path)
     end
 
     ws:send("Welcome to WebSocket Eval! Send Lua code to execute.")
 end)
 
+-- WebSocket route for memory watching
+app:websocket("/watch", function(ws)
+    console:log("WebSocket connected to watch endpoint: " .. ws.path)
+
+    -- Initialize memory watcher for this connection
+    memoryWatchers[ws.id] = {
+        regions = {},
+        lastData = {}
+    }
+
+    ws.onMessage = function(message)
+        local function safe_handler()
+            console:log("WebSocket watch message: " .. tostring(message))
+
+            -- Parse JSON message for memory watching
+            local parsed, parseErr = parseJSON(message)
+            if not parsed or type(parsed) ~= "table" or not parsed.type then
+                ws:send(HttpServer.jsonStringify({
+                    type = "error",
+                    error = "Invalid message format - JSON object with 'type' field required"
+                }))
+                return
+            end
+
+            if parsed.type == "watch" then
+                -- Handle memory region watching request
+                if parsed.regions and type(parsed.regions) == "table" then
+                    console:log("Setting up memory watch for " .. #parsed.regions .. " regions")
+                    local watcher = memoryWatchers[ws.id]
+                    watcher.regions = parsed.regions
+                    watcher.lastData = {}
+
+                    -- Initialize baseline data for each region
+                    for i, region in ipairs(parsed.regions) do
+                        if region.address and region.size then
+                            local data = emu:readRange(region.address, region.size)
+                            watcher.lastData[i] = data
+                        end
+                    end
+
+                    ws:send(HttpServer.jsonStringify({
+                        type = "watchConfirm",
+                        message = "Watching " .. #parsed.regions .. " memory regions"
+                    }))
+                else
+                    ws:send(HttpServer.jsonStringify({
+                        type = "error",
+                        error = "Invalid watch request - regions array required"
+                    }))
+                end
+            else
+                ws:send(HttpServer.jsonStringify({
+                    type = "error",
+                    error = "Unknown message type: " .. tostring(parsed.type)
+                }))
+            end
+        end
+        local ok, err = pcall(safe_handler)
+        if not ok then
+            ws:send(HttpServer.jsonStringify({type = "error", error = "Internal server error: " .. tostring(err)}))
+            console:error("[WebSocket Watch Handler Error] " .. tostring(err))
+        end
+    end
+
+    ws.onClose = function()
+        console:log("WebSocket disconnected from watch endpoint: " .. ws.path)
+        -- Cleanup memory watcher
+        memoryWatchers[ws.id] = nil
+    end
+
+    ws:send(HttpServer.jsonStringify({
+        type = "welcome",
+        message = "Welcome to WebSocket Memory Watching! Send JSON messages with 'type': 'watch' to monitor memory regions."
+    }))
+end)
+
+-- Frame callback for memory change detection
+local frameCallbackId = nil
+
+local function checkMemoryChanges()
+    for wsId, watcher in pairs(memoryWatchers) do
+        local ws = app.websockets[wsId]
+        -- Only process watchers for connections on the /watch endpoint
+        if ws and ws.path == "/watch" and #watcher.regions > 0 then
+            local changedRegions = {}
+
+            for i, region in ipairs(watcher.regions) do
+                if region.address and region.size then
+                    local currentData = emu:readRange(region.address, region.size)
+                    if currentData ~= watcher.lastData[i] then
+                        -- Memory changed, prepare update
+                        local bytes = {}
+                        for j = 1, #currentData do
+                            bytes[j] = string.byte(currentData, j)
+                        end
+
+                        table.insert(changedRegions, {
+                            address = region.address,
+                            size = region.size,
+                            data = bytes
+                        })
+
+                        -- Update stored data
+                        watcher.lastData[i] = currentData
+                    end
+                end
+            end
+
+            -- Send memory update if any regions changed
+            if #changedRegions > 0 then
+                ws:send(HttpServer.jsonStringify({
+                    type = "memoryUpdate",
+                    regions = changedRegions,
+                    timestamp = os.time()
+                }))
+            end
+        end
+    end
+end
+
+-- Register frame callback to monitor memory changes
+local function setupMemoryMonitoring()
+    if frameCallbackId then
+        callbacks:remove(frameCallbackId)
+    end
+    frameCallbackId = callbacks:add("frame", checkMemoryChanges)
+    console:log("🔍 Memory monitoring callback registered")
+end
+
+-- Setup monitoring when ROM is loaded
+if emu and emu.romSize and emu:romSize() > 0 then
+    setupMemoryMonitoring()
+else
+    local cbid
+    cbid = callbacks:add("start", function()
+        setupMemoryMonitoring()
+        callbacks:remove(cbid)
+    end)
+end
+
 -- Start server
 app:listen(7102, function(port)
     console:log("🚀 mGBA HTTP Server started on port " .. port)