Fix devcontainer websocket/port issues, update/add npm scripts

docs/README.dev-notes.md

@@ -177,6 +177,102 @@ In case the above does not resolve your issues, just to rule out potential firew
 
 > WARNING: IF YOU DO THIS, DO NOT FORGET TO RE-ENABLE THE FIREWALL AFTER TESTING!
 
+## VS Code Dev Container Port Forwarding
+
+When running the React dev server in a VS Code dev container (WSL2 + Podman/Docker), VS Code automatically forwards ports from the container to the Windows host. However, you may encounter:
+
+1. **Port remapping**: If port 3000 is busy on Windows, VS Code may forward to 3001 or another available port
+2. **WebSocket errors**: The React dev server's WebSocket may try to connect to the original port instead of the forwarded one
+
+### Fix WebSocket Connection Issues
+
+Create a `.env.development` file in the project root:
+
+```ini
+# WebSocket configuration for dev server
+# This ensures hot-reloading works correctly when accessing via VS Code port forwarding
+WDS_SOCKET_PORT=0
+```
+
+Setting `WDS_SOCKET_PORT=0` tells webpack dev server to use the same port as the page URL, automatically adapting to VS Code's port forwarding.
+
+### Dev Container vs Direct WSL2 Configuration Differences
+
+**In VS Code Dev Containers:**
+- `HOST=0.0.0.0` is **not needed** - VS Code handles port forwarding from container's localhost
+- `CHOKIDAR_USEPOLLING=true` is **usually not needed** - container filesystem is typically better than WSL2's
+- React Fast Refresh works well - keep it enabled
+
+**In Direct WSL2 (no container):**
+- `HOST=0.0.0.0` is **required** - to bind to WSL2's network interface
+- `CHOKIDAR_USEPOLLING=true` may be **needed** - WSL2 filesystem watch can be unreliable
+- Manual port forwarding with `netsh interface portproxy` may be needed
+
+**Project Scripts:**
+
+The project includes separate scripts for different environments:
+
+```bash
+# In VS Code Dev Container (default, optimized)
+npm start
+
+# In direct WSL2 (without container)
+npm run start:wsl2
+```
+
+Configured in `package.json`:
+```json
+"scripts": {
+  "start": "cross-env BROWSER=none react-scripts start",
+  "start:wsl2": "cross-env HOST=0.0.0.0 BROWSER=none CHOKIDAR_USEPOLLING=true react-scripts start"
+}
+```
+
+This way you don't need to modify scripts when switching between environments.
+
+### Configure Port Forwarding Behavior
+
+In `.devcontainer/devcontainer.json`, you can configure port forwarding:
+
+```jsonc
+{
+  "forwardPorts": [3000],
+  "portsAttributes": {
+    "3000": {
+      "label": "React Dev Server",
+      "onAutoForward": "notify"
+    }
+  }
+}
+```
+
+### Check Which Port is Actually Forwarded
+
+In VS Code, check the **PORTS** tab (usually in the bottom panel) to see:
+- Which container ports are forwarded
+- Which Windows host ports they map to
+- You can manually change the forwarded port by right-clicking the port entry
+
+**Note:** If port 3000 is busy on Windows, VS Code may automatically forward to 3001 or another available port. This is normal - just use whatever port VS Code assigns in the PORTS tab.
+
+### Kill Stuck Dev Server
+
+If you need to free port 3000 (e.g., stuck dev server process):
+
+```bash
+npm run kill
+```
+
+This script uses `lsof` to find and terminate any process using port 3000. Note: `lsof` must be installed in the container (already configured in Dockerfile).
+
+### Important: No Manual Port Proxy Needed
+
+When using VS Code dev containers, you **do not need** `netsh interface portproxy` rules. VS Code handles all port forwarding automatically. Remove any existing rules:
+
+```batch
+netsh interface portproxy delete v4tov4 listenport=3000 listenaddress=127.0.0.1
+```
+
 ## Development Server
 
 ### (Prevent) Auto Open in Browser