@react-ui-org/react-ui 0.63.1 → 0.64.0

package/docker-compose.base.yml

@@ -0,0 +1,93 @@
+services:
+  # This service is responsible for providing the main development environment for developers
+  devcontainer:
+    hostname: ${COMPOSE_PROJECT_NAME:-react-ui}_devcontainer
+    build:
+      context: docker/react_ui_devcontainer/
+      dockerfile: Dockerfile
+    # Start dependent services before starting the `devcontainer` service to ensure that the necessary environments
+    # and tools are available when the `devcontainer` starts.
+    depends_on:
+      node:
+        condition: service_started
+      playwright:
+        condition: service_started
+      docs:
+        condition: service_started
+    # Run as host UID/GID so files created in mounted volumes are owned correctly on the host.
+    # The images use `fixuid` (https://github.com/boxboat/fixuid) to remap the built-in `developer`
+    # user to these IDs at startup — the `user:` directive is required for that remap to work.
+    # Applied to all services below for the same reason.
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    # Keep the container running indefinitely to allow developers to attach to it and use it as their development environment
+    command: sleep infinity
+    # Injects environment variables from the `.env` file into the `devcontainer` service,
+    # making them accessible within the container's environment.
+    env_file:
+      - .env
+    environment:
+      # This must be set correctly for the `devcontainer` to be able to access the host's Docker daemon,
+      # enabling Docker-from-Docker capabilities (e.g., running Docker commands from within the `devcontainer`).
+      COMPOSE_PROJECT_NAME: ${COMPOSE_PROJECT_NAME:-react-ui}
+    init: true
+    volumes:
+      - .:/workspace:z
+      # The following volume is used to allow the `devcontainer` to access the host's Docker daemon,
+      # enabling Docker-from-Docker capabilities (e.g., running Docker commands from within the `devcontainer`).
+      - /var/run/docker.sock:/var/run/docker.sock
+      # The following named volumes persist data (e.g. terminal history, AI tools data, etc.) across container restarts.
+      # Using separate named volumes (instead of a single volume with subpaths) allows Docker to automatically
+      # seed the volume with data from the image on first use.
+      - terminal-history:/home/developer/.terminal_history
+      - claude-config:/home/developer/.config/claude
+      - claude-state:/home/developer/.local/state/claude
+      - copilot:/home/developer/.copilot
+      - copilot-config:/home/developer/.config/copilot
+      - opencode-config:/home/developer/.config/opencode
+      - opencode-share:/home/developer/.local/share/opencode
+      - opencode-state:/home/developer/.local/state/opencode
+
+  # This service provides Node environment and NPM
+  node:
+    build: docker/node
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-node.sh; else sleep infinity; fi'
+    env_file:
+      - .env
+    volumes:
+      - .:/workspace:z
+
+  # This service provides Playwright environment and tools for browser automation and testing
+  playwright:
+    build: docker/playwright
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    command: sleep infinity
+    env_file:
+      - .env
+    ports:
+      - ${COMPOSE_PLAYWRIGHT_REPORT_PORT}:9323
+    volumes:
+      - .:/workspace:z
+
+  # This provides server for documentation
+  docs:
+    build: docker/mkdocs
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-mkdocs.sh; else sleep infinity; fi'
+    env_file:
+      - .env
+    ports:
+      - ${COMPOSE_DOCS_SERVER_PORT}:8000
+    volumes:
+      - .:/workspace:z
+
+volumes:
+  # The following volumes are used to persist data (e.g. terminal history, AI tools data, etc.) across container restarts
+  terminal-history:
+  claude-config:
+  claude-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

package/docker-compose.yml.dist

@@ -0,0 +1,41 @@
+services:
+  # This service is responsible for providing the main development environment for developers
+  devcontainer:
+    extends:
+      file: docker-compose.base.yml
+      service: devcontainer
+    # Use `build` when you want to customize the devcontainer using `docker/react_ui_devcontainer_local/Dockerfile`
+    # build:
+    #   context: ./docker/react_ui_devcontainer_local/
+    #   dockerfile: Dockerfile
+    # Use `image` when you want to use the default devcontainer
+    image: react-ui_devcontainer
+
+  # This service provides Node environment and NPM
+  node:
+    extends:
+      file: docker-compose.base.yml
+      service: node
+
+  # This service provides Playwright environment and tools for browser automation and testing
+  playwright:
+    extends:
+      file: docker-compose.base.yml
+      service: playwright
+
+  # This provides server for documentation
+  docs:
+    extends:
+      file: docker-compose.base.yml
+      service: docs
+
+volumes:
+  # The following volumes are used to persist data (e.g. terminal history, AI tools data, etc.) across container restarts
+  terminal-history:
+  claude-config:
+  claude-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

package/opencode.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "chrome-host": {
+      "type": "local",
+      "command": ["sh", "scripts/mcps/chrome-host/mcp-entry.sh"],
+      "enabled": true
+    }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@react-ui-org/react-ui",
   "description": "React UI is a themeable UI library for React apps.",
-  "version": "0.63.1",
+  "version": "0.64.0",
   "keywords": [
     "react",
     "ui",
@@ -54,10 +54,11 @@
     "lint": "npm run eslint && npm run markdownlint && npm run stylelint",
     "markdownlint": "markdownlint-cli2 \"README.md\" \"src/**/*.md\"",
     "postbuild": "npm run copy",
-    "postinstall": "cp -n .env.dist .env && cp -n .env.playwright.dist .env.playwright || true",
+    "postinstall": "sh scripts/write-lockfile-hash.sh",
     "precopy": "rm -rf dist && mkdir dist",
     "prepublishOnly": "npm run build",
     "start": "webpack --watch --mode=development",
+    "start:chrome": "sh scripts/mcps/chrome-host/start-host-chrome.sh",
     "stylelint": "stylelint \"src/**/*.{css,scss}\" \"!src/docs/_assets/generated/**\" --config stylelint.config.js",
     "test": "npm run test:jest",
     "test:jest": "npm run test:jest:ts && npm run test:jest:js",

package/scripts/auto-start-mkdocs.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# Start the docs server
+echo "Starting the docs server..."
+mkdocs serve

package/scripts/auto-start-node.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+set -e
+
+# File to read the hash of the package-lock.json
+LOCK_HASH_FILE="node_modules/.package-lock-hash"
+
+# Parent directory of the script
+SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
+
+# Change to the parent directory of the script
+cd "$SCRIPT_DIR/.."
+
+# Install dependencies if node_modules is missing or out of date
+CURRENT_HASH=$(sha256sum package-lock.json | awk '{print $1}')
+if [ ! -d "node_modules" ]; then
+  echo "Installing dependencies (node_modules directory is missing)..."
+  npm ci
+elif [ ! -f "$LOCK_HASH_FILE" ]; then
+  echo "Installing dependencies (lockfile of package-lock.json is missing)..."
+  npm ci
+elif [ "$(cat "$LOCK_HASH_FILE")" != "$CURRENT_HASH" ]; then
+  echo "Installing dependencies (package-lock.json has changed)..."
+  npm ci
+fi
+
+# Build the application (must be run prior to starting the server to ensure the latest code is used)
+echo "Building the application..."
+npm run build
+
+# Start the application
+echo "Starting the application..."
+npm start

package/scripts/mcps/chrome-host/README.md

@@ -0,0 +1,118 @@
+# Chrome-host bridge
+
+Lets an MCP-capable AI assistant in the `devcontainer` drive **Chrome on the
+host** via [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+over the Chrome DevTools Protocol (CDP).
+
+## Principles
+
+- The container reaches the host only via `host.docker.internal`.
+- Chrome's DevTools endpoint rejects any `Host` header that is not an IP literal
+  (or the name `localhost`) — so the container cannot connect to it directly.
+- Fix: a loopback proxy **inside the container** (`127.0.0.1:9334`); the `Host`
+  Chrome finally sees is `127.0.0.1`, an IP, which it accepts.
+- Chrome runs in a dedicated, persistent profile (separate from your everyday
+  one) and is started **by hand** on the host — never from a Claude action,
+  which can reap it with its process group.
+
+## Architecture
+
+```text
+Claude (devcontainer)
+  │ .mcp.json → mcp-entry.sh → docker compose exec node mcp-launch.sh
+  ▼
+node container
+  ├─ cdp_proxy.py   127.0.0.1:9334 ──► host.docker.internal:9333
+  └─ npx chrome-devtools-mcp --browser-url http://127.0.0.1:9334
+                                          │
+                                          ▼
+host: Chrome --remote-debugging-port=9333 (throwaway profile)
+```
+
+| Script | Runs on | Purpose |
+| --- | --- | --- |
+| `start-host-chrome.sh` | host | Launch the debug Chrome on `:9333`. Idempotent; auto-detects Chrome/Chromium/Edge. On native Docker, also runs an `ncat` forwarder to expose `:9333` on the bridge gateway. |
+| `cdp_proxy.py` | node container | Loopback CDP proxy `:9334` → host `:9333`. Binds-or-exits. |
+| `mcp-launch.sh` | node container | Ensure the proxy is up, then `exec` `chrome-devtools-mcp`. |
+| `mcp-entry.sh` | host / devcontainer | The `.mcp.json` command; routes into the node container (adds `sudo` inside the container). |
+| `mcp-setup.sh` | host (setup) | Add the `host.docker.internal:host-gateway` mapping on native Docker Engine. Idempotent; no-op on Docker Desktop. |
+
+## Registration
+
+Register `mcp-entry.sh` as an MCP server named `chrome-host`. Any MCP client
+works — point its config at the script.
+
+**Claude / GitHub Copilot CLI** — `.mcp.json` (repo root):
+
+```json
+{
+  "mcpServers": {
+    "chrome-host": {
+      "command": "sh",
+      "args": ["scripts/mcps/chrome-host/mcp-entry.sh"]
+    }
+  }
+}
+```
+
+**OpenCode** — `opencode.json` (repo root):
+
+```json
+{
+  "mcp": {
+    "chrome-host": {
+      "type": "local",
+      "command": ["sh", "scripts/mcps/chrome-host/mcp-entry.sh"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Requirements: a `docker-compose.yml` at the repo root, the repo mounted at
+`/workspace` in the container, and a Compose service named `node` that runs
+`node`/`npx`.
+
+## Usage
+
+1. Start host Chrome (from a host terminal, **not** from inside an AI action):
+
+   ```sh
+   ./scripts/mcps/chrome-host/start-host-chrome.sh
+   ```
+
+2. On first run, approve the `chrome-host` server in your MCP client.
+
+The proxy and MCP server are bootstrapped by `mcp-launch.sh`; you only start
+Chrome by hand.
+
+## Platform support
+
+Decided by **Docker Desktop vs native Docker Engine**, not the OS.
+
+| Host setup | `host.docker.internal` reaches host loopback? | Extra steps |
+| --- | --- | --- |
+| Docker Desktop (macOS/Linux) | Yes (auto) | None. |
+| Native Docker Engine (Linux) | No (bridge gateway only) | `setup.sh` (via `mcp-setup.sh`) adds the host-gateway mapping; the launcher runs a host-side `ncat` forwarder (install `nmap-ncat`/`nmap`) to expose Chrome's loopback CDP port on the bridge gateway. **Firewall the port**: this exposes DevTools beyond loopback. |
+
+## Configuration
+
+- Ports: host CDP `9333` (configurable), in-container proxy `9334` (fixed).
+- Overrides (host launcher), set in the repo `.env`: `CHROME_DEBUG_PORT` and
+  `CHROME_BIN`. `CHROME_DEBUG_BIND` is an advanced escape hatch — the bind is
+  auto-detected, so it is not listed in `.env.dist`; set it only when detection
+  fails (e.g. a non-default daemon `host-gateway-ip`). **Security:** a
+  non-loopback bind exposes the unauthenticated CDP port; firewall it.
+  The proxy's listen port and target host are fixed constants; only its upstream
+  port is configurable, and it follows the same `CHROME_DEBUG_PORT`.
+- Set these in the repo `.env`; Compose passes `CHROME_DEBUG_PORT` into the
+  container, so a single knob drives both sides. Recreate the node container
+  after editing. See `.env.dist`.
+- Profile: `~/.chrome-debug-profile-<COMPOSE_PROJECT_NAME>` (per project, fixed).
+
+## Troubleshooting
+
+- Status: `claude mcp get chrome-host` (`✔ Connected` = healthy chain).
+- Chrome died? Re-run `start-host-chrome.sh` (it persists across sessions).
+- `claude mcp list` shows *Pending approval* until you approve project servers.
+- Disable: remove the `chrome-host` entry from `.mcp.json`.

package/scripts/mcps/chrome-host/cdp_proxy.py

@@ -0,0 +1,90 @@
+import os
+import socket
+import threading
+
+# Loopback CDP proxy. Runs INSIDE the node container.
+#
+# A container reaches host Chrome only via `host.docker.internal` (forwarded to
+# the host loopback on Docker Desktop; the bridge gateway on native Linux Docker,
+# where a host-side ncat forwarder exposes Chrome's loopback CDP port). But
+# Chrome's DevTools endpoint rejects any Host header that isn't an IP literal (or
+# the name "localhost") -- anti DNS-rebinding -- so connecting by that *name*
+# fails, and the IPv6 it may also resolve to is often not forwarded.
+#
+# So this proxy listens on 127.0.0.1:LISTEN_PORT and forwards raw bytes to host
+# Chrome. Clients reach it as "127.0.0.1:LISTEN_PORT", so the Host header Chrome
+# sees is an IP (accepted), and the webSocketDebuggerUrl it echoes back stays on
+# 127.0.0.1 too, so the follow-up WebSocket also works.
+#
+# The proxy's own endpoint is fixed: it always listens on the container loopback
+# and forwards to host Chrome over host.docker.internal. Only the upstream Chrome
+# port is configurable, via CHROME_DEBUG_PORT (set in the repo's .env, which
+# Compose passes into the container), so a single knob keeps both sides in sync.
+
+LISTEN_HOST = "127.0.0.1"
+LISTEN_PORT = 9334  # fixed; must match PROXY_PORT in mcp-launch.sh
+TARGET_HOST = "host.docker.internal"  # fixed; how the container reaches the host
+TARGET_PORT = int(os.environ.get("CHROME_DEBUG_PORT") or "9333")  # host Chrome CDP port
+
+
+def resolve_target():
+    # Force IPv4: host.docker.internal may also resolve to an IPv6 address that
+    # Docker does not forward to the host.
+    try:
+        infos = socket.getaddrinfo(TARGET_HOST, TARGET_PORT, socket.AF_INET, socket.SOCK_STREAM)
+        return infos[0][4]
+    except Exception:
+        # Docker Desktop's well-known host-gateway IPv4 as a last resort.
+        return ("192.168.65.254", TARGET_PORT)
+
+
+TARGET = resolve_target()
+
+
+def pipe(source, destination):
+    try:
+        while True:
+            data = source.recv(65536)
+            if not data:
+                break
+            destination.sendall(data)
+    except Exception:
+        pass
+    finally:
+        for sock in (source, destination):
+            try:
+                sock.close()
+            except Exception:
+                pass
+
+
+def handle(client):
+    try:
+        upstream = socket.create_connection(TARGET, timeout=10)
+    except Exception:
+        client.close()
+        return
+    threading.Thread(target=pipe, args=(client, upstream), daemon=True).start()
+    threading.Thread(target=pipe, args=(upstream, client), daemon=True).start()
+
+
+def main():
+    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        srv.bind((LISTEN_HOST, LISTEN_PORT))
+    except OSError:
+        # Another instance already owns the port; let it serve.
+        raise SystemExit(0)
+    srv.listen(128)
+    print("chrome-host: proxy listening %s:%d -> %s:%d" % (LISTEN_HOST, LISTEN_PORT, TARGET[0], TARGET[1]), flush=True)
+    while True:
+        try:
+            conn, _ = srv.accept()
+        except Exception:
+            continue
+        handle(conn)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/mcps/chrome-host/mcp-entry.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+# Referenced by .mcp.json / opencode.json as the `chrome-host` MCP server command.
+#
+# Spawns chrome-devtools-mcp inside the node container (via mcp-launch.sh),
+# whether the assistant runs in the devcontainer or on the host. Docker needs
+# `sudo` inside the container (like the node/npx wrappers) but not on the host;
+# we tell them apart by /.dockerenv, which exists only in a container.
+
+set -eu
+
+# Compose service that runs the proxy + chrome-devtools-mcp.
+DOCKER_SERVICE_NAME=node
+
+script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+
+# Walk up to the repo root (the directory holding docker-compose.yml) so
+# `docker compose` finds the compose files + .env regardless of the caller's cwd.
+root="$script_dir"
+while [ "$root" != "/" ] && [ ! -f "$root/docker-compose.yml" ]; do
+  root="$(dirname "$root")"
+done
+cd "$root"
+
+# Path to mcp-launch.sh as seen inside the node container (repo mounted at /workspace).
+rel="${script_dir#"$root"/}"
+launch="/workspace/$rel/mcp-launch.sh"
+
+if [ -f /.dockerenv ]; then
+  exec sudo docker compose exec -T "$DOCKER_SERVICE_NAME" "$launch"
+else
+  exec docker compose exec -T "$DOCKER_SERVICE_NAME" "$launch"
+fi

package/scripts/mcps/chrome-host/mcp-launch.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+
+# Runs INSIDE the node container, invoked by mcp-entry.sh.
+#
+# Ensures the loopback CDP proxy (cdp_proxy.py) is running, then hands stdio over
+# to chrome-devtools-mcp pointed at the proxy. Resolves cdp_proxy.py next to
+# itself, so it works from any location under the repo.
+
+set -eu
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+PROXY_PORT=9334  # fixed; must match LISTEN_PORT in cdp_proxy.py
+PROXY_SCRIPT="$SCRIPT_DIR/cdp_proxy.py"
+
+is_up() {
+  python3 -c 'import socket,sys; s=socket.socket(); sys.exit(0 if s.connect_ex(("127.0.0.1",'"$PROXY_PORT"'))==0 else 1)' 2>/dev/null
+}
+
+if ! is_up; then
+  # cdp_proxy.py binds-or-exits, so concurrent launches are safe.
+  python3 "$PROXY_SCRIPT" >/tmp/cdp_proxy.log 2>&1 &
+  i=0
+  while [ "$i" -lt 25 ]; do
+    if is_up; then
+      break
+    fi
+    i=$((i + 1))
+    sleep 0.2
+  done
+fi
+
+# chrome-devtools-mcp is fetched on demand via npx rather than being added to
+# package.json: it is host/dev MCP tooling for this bridge, not an app build or
+# runtime dependency, so it deliberately stays out of the lockfile. `-y` confirms
+# the one-off npx install; `@latest` tracks upstream fixes for the dev tool.
+exec npx -y chrome-devtools-mcp@latest --browser-url "http://127.0.0.1:${PROXY_PORT}" "$@"

package/scripts/mcps/chrome-host/mcp-setup.sh

@@ -0,0 +1,70 @@
+#!/bin/sh
+
+# Run on the HOST during project setup (called from setup.sh).
+#
+# Native Docker Engine on Linux doesn't inject `host.docker.internal`, so the
+# proxy container can't reach host Chrome. This adds the host-gateway mapping to
+# the node service -- but only there. On Docker Desktop/macOS it's a no-op:
+# the name already works, and adding the mapping would repoint it to the bridge
+# gateway and break Desktop.
+#
+# Idempotent; after patching a running setup, recreate the service:
+# `docker compose up -d node`.
+
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)"
+COMPOSE_FILE="$ROOT/docker-compose.yml"
+DOCKER_SERVICE_NAME=node
+MAPPING="host.docker.internal:host-gateway"
+
+# Only native Docker Engine on Linux needs the mapping. macOS is always Desktop.
+if [ "$(uname -s)" = "Darwin" ]; then
+  exit 0
+fi
+
+DOCKER_OS="$(docker info --format '{{.OperatingSystem}}' 2>/dev/null || true)"
+if [ -z "$DOCKER_OS" ]; then
+  echo "chrome-host: warning: could not query Docker (is it running?); skipping host-gateway setup." >&2
+  exit 0
+fi
+case "$DOCKER_OS" in
+  *"Docker Desktop"*) exit 0 ;;
+esac
+
+# Native Docker Engine from here on.
+
+# The host launcher forwards Chrome's loopback CDP port to the bridge gateway
+# with ncat (headed Chrome only binds loopback). Warn now rather than failing at
+# first browser launch; don't auto-install -- that needs sudo plus distro
+# detection, and adding host packages requires explicit approval.
+if ! command -v ncat >/dev/null 2>&1; then
+  echo "chrome-host: warning: 'ncat' not found; install it (package 'nmap-ncat' or 'nmap'," >&2
+  echo "chrome-host: depending on your distro) so start-host-chrome.sh can expose Chrome's" >&2
+  echo "chrome-host: CDP port on the bridge gateway for the container." >&2
+fi
+
+[ -f "$COMPOSE_FILE" ] || exit 0
+if grep -q "$MAPPING" "$COMPOSE_FILE"; then
+  exit 0
+fi
+
+# Insert extra_hosts under the `<service>:` block (sibling of `extends:`).
+TMP_FILE="$COMPOSE_FILE.tmp"
+awk -v service="$DOCKER_SERVICE_NAME" '
+  { print }
+  $0 ~ ("^  " service ":[[:space:]]*$") && !done {
+    print "    extra_hosts:"
+    print "      - \"host.docker.internal:host-gateway\""
+    done = 1
+  }
+' "$COMPOSE_FILE" > "$TMP_FILE"
+
+if grep -q "$MAPPING" "$TMP_FILE"; then
+  mv "$TMP_FILE" "$COMPOSE_FILE"
+  echo "chrome-host: native Docker Engine detected -- added '$MAPPING' to the '$DOCKER_SERVICE_NAME' service in $COMPOSE_FILE."
+  echo "chrome-host: if the '$DOCKER_SERVICE_NAME' container is already running, recreate it: docker compose up -d $DOCKER_SERVICE_NAME"
+else
+  rm -f "$TMP_FILE"
+  echo "chrome-host: warning: could not locate the '$DOCKER_SERVICE_NAME' service in $COMPOSE_FILE; add '$MAPPING' to its extra_hosts manually." >&2
+fi