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

.devcontainer/Dockerfile

@@ -1,7 +1,7 @@
 FROM node:18
 
 # Install some apt packages
-RUN apt-get update && apt-get install -y sudo zsh git vim tmux
+RUN apt-get update && apt-get install -y sudo zsh git vim tmux lsof
 
 # Variable for default user `node` to be used in the following steps
 ARG USERNAME=node

.devcontainer/devcontainer.json

@@ -15,7 +15,12 @@
 	]
   },
   "forwardPorts": [3000],
+  "portsAttributes": {
+    "3000": {
+      "label": "React Dev Server",
+      "onAutoForward": "notify"
+    }
+  },
   "postCreateCommand": "npm install",
   "remoteUser": "node"
 }
-

.env.development

@@ -0,0 +1,12 @@
+# WebSocket configuration for dev server
+# This ensures hot-reloading works correctly when accessing via VS Code port forwarding
+WDS_SOCKET_PORT=0
+
+# File watching configuration
+# Enable polling only if you experience file change detection issues in the container
+# CHOKIDAR_USEPOLLING=true
+
+# React Fast Refresh
+# Keep enabled for better developer experience (hot reloading without losing state)
+# Set to false only if you experience issues with Fast Refresh
+# FAST_REFRESH=false

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

package.json

@@ -22,11 +22,17 @@
     "tailwindcss-animate": "^1.0.7"
   },
   "scripts": {
-    "start": "cross-env HOST=0.0.0.0 BROWSER=none CHOKIDAR_USEPOLLING=true FAST_REFRESH=false react-scripts start",
+    "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",
+    "kill": "lsof -ti:3000 | xargs kill -9 2>/dev/null && echo 'Cleared port 3000' || echo 'Port 3000 was not in use'",
     "build": "react-scripts build",
     "test": "react-scripts test",
     "eject": "react-scripts eject",
-    "webhint": "hint"
+    "check": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.{js,jsx,ts,tsx}'",
+    "lint:fix": "eslint 'src/**/*.{js,jsx,ts,tsx}' --fix",
+    "_postbuild": "webhint build/",
+    "_webhint": "hint"
   },
   "eslintConfig": {
     "extends": [