browser4-cli 0.1.16 → 0.1.18

package/README.md

@@ -152,7 +152,10 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 | `uncheck <ref>` | Uncheck a checkbox or radio button |
 | `drag <startRef> <endRef>` | Drag and drop between two elements |
 | `snapshot` | Capture accessibility snapshot |
-| `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element |
+| `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element. Use `--file=<path>` to read the expression from a file. |
+| `get <mode> <selector> [name]` | Extract data from a page element. Modes: `text`, `html`, `box`, `styles`, `property`, `attr`. `name` is required for `property` and `attr`. |
+| `scroll <direction> <pixels>` | Scroll the page. Direction: `up`, `down`, `left`, or `right`. |
+| `wait [target]` | Wait for a condition. Positional: selector or milliseconds. Options: `--text=<text>`, `--url=<glob>`, `--load=<state>` (networkidle/domcontentloaded), `--fn=<JS expr>`. |
 | `dialog-accept [prompt]` | Accept a dialog |
 | `dialog-dismiss` | Dismiss a dialog |
 | `resize <w> <h>` | Resize the browser window |
@@ -193,12 +196,12 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 
 | Command | Description |
 |---|---|
-| `tab-list` | List all tabs |
+| `tab-list` | List all tabs with their zero-based index |
 | `tab-new [url]` | Create a new tab |
-| `tab-close [index]` | Close a browser tab by zero-based index |
-| `tab-select <index>` | Select a browser tab by zero-based index |
+| `tab-close [index]` | Close a tab by its zero-based index |
+| `tab-select <index>` | Select a tab by its zero-based index |
 
-Use `tab-list` first to find the zero-based tab index you want to select or close.
+Run `tab-list` first to find each tab's zero-based index. Pass that index to `tab-select` or `tab-close`.
 
 #### Browser storage
 
@@ -515,7 +518,7 @@ browser4-cli open --headed https://browser4.io
 browser4-cli open --headless https://browser4.io
 
 # Navigate to a page — auto-opens a session if none is active
-browser4-cli goto https://playwright.dev
+browser4-cli goto https://browser4.io
 
 # Inspect the page — note the eN labels on interactive nodes
 browser4-cli snapshot
@@ -545,10 +548,10 @@ browser4-cli open --server http://localhost:9090
 # Advanced: execute multiple commands in one process (batch mode)
 # Batch mode only supports DOM operations. You must run `open` separately first.
 browser4-cli open
-browser4-cli batch "goto https://playwright.dev" "snapshot"
+browser4-cli batch "goto https://browser4.io" "snapshot"
 
 # Advanced: stop on the first batch failure
-browser4-cli batch --bail "goto https://playwright.dev" "click e1" "screenshot"
+browser4-cli batch --bail "goto https://browser4.io" "click e1" "screenshot"
 
 # Advanced: batch mode for form filling (recommended use case)
 browser4-cli batch "fill e1 'John Doe'" "fill e2 'john@example.com'" "click e3"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [

package/scripts/install-browser4-cli.ps1

@@ -11,9 +11,11 @@
     Windows:  $env:LOCALAPPDATA\Programs\browser4-cli
     (override with -InstallDir)
 
-  Download sources (tried in order unless -Source is specified):
-    1. GitHub Releases   — https://github.com/platonai/Browser4
-    2. Aliyun OSS        — https://browser4.oss-cn-beijing.aliyuncs.com
+  Download sources (auto-selected by locale; use -Source to override):
+    Outside China:  1. GitHub Releases  ->  2. Aliyun OSS
+    China mainland: 1. Aliyun OSS        ->  2. GitHub Releases
+    GitHub Releases — https://github.com/platonai/Browser4
+    Aliyun OSS       — https://browser4.oss-cn-beijing.aliyuncs.com
 
 .PARAMETER Version
   Release version tag to download (e.g. "v4.11.0" or "v0.1.12-cli").
@@ -25,7 +27,7 @@
 
 .PARAMETER Source
   Force a specific download source: "github" or "oss".
-  Default: try GitHub first, fall back to OSS.
+  Default (auto): locale-aware — OSS first in China mainland, GitHub first elsewhere.
 
 .PARAMETER AddToPath
   Add the install directory to the current user's PATH environment variable.
@@ -37,6 +39,15 @@
 .PARAMETER DryRun
   Print what would be done without actually doing it.
 
+.PARAMETER SkipLocal
+  Skip checking for a locally-bundled binary alongside the script.
+  By default the script looks for the platform binary in its own directory
+  before downloading — use this to force a fresh download.
+
+.PARAMETER Locate
+  Print detection results (OS, architecture, script location, China locale)
+  and exit without installing. Useful for diagnostics.
+
 .EXAMPLE
   # Quick install — default location, latest version, add to PATH
   powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1
@@ -48,6 +59,24 @@
 .EXAMPLE
   # Install from OSS only, custom directory
   powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -Source oss -InstallDir "C:\tools\browser4"
+
+.EXAMPLE
+  # Run diagnostics — see what the script detects without installing
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -Locate
+
+.EXAMPLE
+  # Use a locally-bundled binary (place binary next to the script)
+  # The script auto-detects binaries in its own directory
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1
+
+.EXAMPLE
+  # Force download even when a local binary exists
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -SkipLocal
+
+.EXAMPLE
+  # For China mainland: OSS is auto-preferred via locale detection,
+  # or force it explicitly
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -Source oss
 #>
 
 [CmdletBinding()]
@@ -58,11 +87,65 @@ param(
   [string]$Source = "",
   [bool]$AddToPath = $true,
   [switch]$Silent,
-  [switch]$DryRun
+  [switch]$DryRun,
+  [switch]$SkipLocal,
+  [switch]$Locate
 )
 
 $ErrorActionPreference = "Stop"
 
+# ──────────────────────────────────────────────
+# Script location — find ourselves on disk
+# ──────────────────────────────────────────────
+
+# $PSScriptRoot is the directory containing this script (PS 3+).
+# Falls back to $MyInvocation for edge cases (dot-sourced, PS 2).
+$ScriptDir = if ($PSScriptRoot) {
+  $PSScriptRoot
+} elseif ($MyInvocation -and $MyInvocation.MyCommand.Path) {
+  Split-Path -Parent $MyInvocation.MyCommand.Path
+} else {
+  $null
+}
+
+<#
+.SYNOPSIS
+  Search for a pre-downloaded binary near the script (bundled/sideload install).
+  Returns the full path if found, $null otherwise.
+#>
+function Find-LocalBinary {
+  param([string]$BinaryName)
+
+  if (-not $ScriptDir) { return $null }
+
+  $localPath = Join-Path $ScriptDir $BinaryName
+  if (Test-Path $localPath -PathType Leaf) {
+    $size = (Get-Item $localPath).Length
+    if ($size -gt 102400) {  # > 100 KB minimum
+      return $localPath
+    }
+  }
+  return $null
+}
+
+<#
+.SYNOPSIS
+  Check whether a local binary is usable by querying its version.
+  Returns $true if --version executes successfully, $false otherwise.
+#>
+function Test-LocalBinary {
+  param([string]$Path)
+
+  if (-not $Path -or -not (Test-Path $Path)) { return $false }
+
+  try {
+    $null = & $Path --version 2>&1
+    return ($LASTEXITCODE -eq 0)
+  } catch {
+    return $false
+  }
+}
+
 # ──────────────────────────────────────────────
 # OS detection (compatible with PS 5.1+)
 # ──────────────────────────────────────────────
@@ -154,12 +237,60 @@ function Get-DefaultInstallDir {
   throw "Unsupported OS"
 }
 
+# ──────────────────────────────────────────────
+# China mainland locale detection (zero-network)
+# ──────────────────────────────────────────────
+
+<#
+.SYNOPSIS
+  Detect whether the current system is likely in China mainland.
+  Uses only local env vars and .NET APIs — no network calls.
+#>
+function Test-ChinaLocale {
+  # 1 — Locale env vars
+  $lang = $env:LC_ALL, $env:LANG, $env:LC_CTYPE, $env:LC_MESSAGES | Where-Object { $_ } | Select-Object -First 1
+  if ($lang -and ($lang -match '^zh_CN' -or $lang -match '^zh-CN' -or $lang -match '^Chinese \(Simplified\)_China')) {
+    return $true
+  }
+
+  # 2 — TZ env var
+  $tzEnv = $env:TZ
+  if ($tzEnv -and ($tzEnv -match '^Asia/(Shanghai|Chongqing|Urumqi|Harbin)$')) {
+    return $true
+  }
+
+  # 3 — .NET TimeZoneInfo (works on Windows and Unix PowerShell 7+)
+  try {
+    $tzId = [System.TimeZoneInfo]::Local.Id
+    if ($tzId -match '^Asia/(Shanghai|Chongqing|Urumqi|Harbin)$') {
+      return $true
+    }
+  } catch {
+    # TimeZoneInfo not available (unlikely on PS 5.1+ but guard anyway)
+  }
+
+  # 4 — /etc/timezone (PowerShell on Linux/macOS)
+  if (-not $script:OSWin -and (Test-Path '/etc/timezone')) {
+    try {
+      $tz = Get-Content '/etc/timezone' -Raw -ErrorAction Stop
+      if ($tz -match '^Asia/(Shanghai|Chongqing|Urumqi|Harbin)$') {
+        return $true
+      }
+    } catch {
+      # Permission or read error — skip
+    }
+  }
+
+  return $false
+}
+
 # ──────────────────────────────────────────────
 # Download URLs
 # ──────────────────────────────────────────────
 
 $GITHUB_REPO = "platonai/Browser4"
 $OSS_BASE = "https://browser4.oss-cn-beijing.aliyuncs.com"
+$script:ChinaDetected = $false
 
 function Get-DownloadUrls {
   param([string]$BinaryName, [string]$VersionTag)
@@ -181,8 +312,13 @@ function Get-DownloadUrls {
   } elseif ($Source -eq "oss") {
     $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
   } else {
-    $urls += @{ Url = $ghUrl; Label = "GitHub Releases" }
-    $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
+    if ($script:ChinaDetected) {
+      $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
+      $urls += @{ Url = $ghUrl; Label = "GitHub Releases" }
+    } else {
+      $urls += @{ Url = $ghUrl; Label = "GitHub Releases" }
+      $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
+    }
   }
 
   return $urls
@@ -359,9 +495,60 @@ function Main {
   Write-Summary "╚════════════════════════════════════════╝" -Color Cyan
   Write-Summary ""
 
+  # Auto-detect China mainland locale when no explicit source is given
+  if (-not $Source) {
+    $script:ChinaDetected = Test-ChinaLocale
+    if ($script:ChinaDetected) {
+      Write-Step "China mainland locale detected: preferring Aliyun OSS mirror."
+    }
+  }
+
   # Detect platform
   $platformKey = Get-PlatformKey
   $binaryName = Get-BinaryName -PlatformKey $platformKey
+
+  # ── Locate mode: print diagnostics and exit ──
+  if ($Locate) {
+    Write-Summary "─── Locate / diagnostics ───" -Color Cyan
+    Write-Summary ""
+    Write-Step "Script dir:       $ScriptDir"
+    Write-Step "Platform key:     $platformKey"
+    Write-Step "Binary name:      $binaryName"
+    Write-Step "Default install:  $(Get-DefaultInstallDir)"
+    Write-Step "China locale:     $script:ChinaDetected"
+    Write-Step "Source override:  $(if ($Source) { $Source } else { 'auto' })"
+    Write-Step "OS:               $(if ($script:OSWin) { 'Windows' } elseif ($script:OSMac) { 'macOS' } elseif ($script:OSLinux) { 'Linux' } else { 'Unknown' })"
+
+    # Check for local binary
+    $localPath = Find-LocalBinary -BinaryName $binaryName
+    if ($localPath) {
+      $localOk = Test-LocalBinary -Path $localPath
+      Write-Step "Local binary:     $localPath $(if ($localOk) { '(valid)' } else { '(present but --version failed)' })"
+    } else {
+      Write-Step "Local binary:     not found alongside script"
+    }
+
+    # Check for already-installed binary
+    $defaultDir = Get-DefaultInstallDir
+    $existingPath = Join-Path $defaultDir $binaryName
+    if (Test-Path $existingPath) {
+      Write-Step "Already installed: $existingPath"
+    } else {
+      Write-Step "Already installed: not found at $defaultDir"
+    }
+
+    # Show download URLs that would be tried
+    $urls = Get-DownloadUrls -BinaryName $binaryName -VersionTag $Version
+    Write-Summary ""
+    Write-Step "Download order:"
+    foreach ($entry in $urls) {
+      Write-Step "  $($entry.Label): $($entry.Url)"
+    }
+
+    Write-Summary ""
+    return
+  }
+
   Write-Step "Platform:  $platformKey"
   Write-Step "Binary:    $binaryName"
 
@@ -379,9 +566,33 @@ function Main {
 
   $binaryPath = Join-Path $installDir $binaryName
 
+  # ── Local binary discovery (bundled/sideload) ──
+  $useLocalBinary = $false
+  if (-not $SkipLocal) {
+    $localBinaryPath = Find-LocalBinary -BinaryName $binaryName
+    if ($localBinaryPath) {
+      Write-Step "Found local binary alongside script: $(Split-Path $localBinaryPath -Leaf)"
+      if (Test-LocalBinary -Path $localBinaryPath) {
+        Write-Check "Local binary verified (--version OK)"
+        $useLocalBinary = $true
+      } else {
+        Write-WarnMsg "Local binary found but --version check failed — will download instead"
+      }
+    }
+  } elseif ($SkipLocal) {
+    Write-Step "Skipping local binary check (-SkipLocal)"
+  }
+
   # If binary already exists and no version override, skip download
-  if ((Test-Path $binaryPath) -and (-not $Version)) {
+  if ((Test-Path $binaryPath) -and (-not $Version) -and (-not $useLocalBinary)) {
     Write-Check "Binary already installed: $binaryPath"
+  } elseif ($useLocalBinary) {
+    # Copy local binary to install dir
+    if (-not $DryRun) {
+      if (Test-Path $binaryPath) { Remove-Item $binaryPath -Force }
+      Copy-Item $localBinaryPath $binaryPath -Force
+    }
+    Write-Check "Installed (local): $binaryPath"
   } else {
     # Build download URLs
     $urls = Get-DownloadUrls -BinaryName $binaryName -VersionTag $Version
@@ -411,6 +622,7 @@ Please check:
   - Network connectivity
   - The version/tag exists: $Version
   - For GitHub rate limits, set GITHUB_TOKEN environment variable
+  - If you have a local copy, place it alongside this script and re-run
 "@
     }
 

package/scripts/install-browser4-cli.sh

@@ -16,7 +16,10 @@
 #   --version, -v TAG   Release tag (e.g. "v4.11.0"). Default: latest.
 #   --install-dir, -d DIR  Install directory (default: ~/.local/bin).
 #   --source SRC        Force download source: "github" or "oss".
+#                       Default (auto): locale-aware — OSS first for China mainland.
 #   --no-path            Skip adding install dir to PATH.
+#   --skip-local         Skip checking for a locally-bundled binary.
+#   --locate             Print detection results and exit (no install).
 #   --silent, -s         Suppress non-error output.
 #   --dry-run            Print what would be done without doing it.
 #   --help, -h           Show this message.
@@ -36,6 +39,10 @@ SOURCE=""
 ADD_TO_PATH=true
 SILENT=false
 DRY_RUN=false
+SKIP_LOCAL=false
+LOCATE_MODE=false
+CHINA_DETECTED=false
+SCRIPT_DIR=""
 
 # ──────────────────────────────────────────────
 # Helpers
@@ -61,6 +68,49 @@ header() {
   fi
 }
 
+# ──────────────────────────────────────────────
+# Script location — find ourselves on disk
+# ──────────────────────────────────────────────
+
+detect_script_dir() {
+  # BASH_SOURCE works even when sourced; prefer it over $0.
+  if [[ -n "${BASH_SOURCE[0]:-}" ]] && [[ "${BASH_SOURCE[0]}" != "bash" ]] && [[ "${BASH_SOURCE[0]}" != *stdin* ]]; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  elif [[ -n "${0:-}" ]] && [[ "$0" != "bash" ]] && [[ "$0" != "-bash" ]] && [[ -f "$0" ]]; then
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  fi
+  # If piped via curl | bash, SCRIPT_DIR stays empty — no local binaries available.
+}
+
+# Search for a pre-downloaded binary near the script (bundled/sideload install).
+# Echoes the full path on success; returns non-zero when not found.
+find_local_binary() {
+  local binary_name="$1"
+  if [[ -z "$SCRIPT_DIR" ]]; then
+    return 1
+  fi
+  local local_path="${SCRIPT_DIR}/${binary_name}"
+  if [[ -f "$local_path" ]]; then
+    local size
+    size=$(stat -c%s "$local_path" 2>/dev/null || stat -f%z "$local_path" 2>/dev/null || echo 0)
+    if [[ "$size" -gt 102400 ]]; then  # > 100 KB minimum
+      echo "$local_path"
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# Check whether a local binary is usable by querying its version.
+# Returns 0 if --version executes successfully, non-zero otherwise.
+test_local_binary() {
+  local path="$1"
+  if [[ -z "$path" ]] || [[ ! -f "$path" ]]; then
+    return 1
+  fi
+  "$path" --version >/dev/null 2>&1
+}
+
 usage() {
   cat <<EOF
 Usage: $(basename "$0") [OPTIONS]
@@ -70,8 +120,11 @@ Download and install the browser4-cli native binary.
 Options:
   --version, -v TAG   Release tag (e.g. "v4.11.0"). Default: latest.
   --install-dir, -d DIR  Install directory (default: ~/.local/bin).
-  --source SRC        Force source: "github" or "oss" (default: try both).
+  --source SRC        Force source: "github" or "oss".
+                      Default (auto): OSS first for China mainland, GitHub first elsewhere.
   --no-path           Skip adding install dir to shell rc file.
+  --skip-local        Skip checking for a locally-bundled binary alongside this script.
+  --locate            Print detection results and exit without installing.
   --silent, -s        Suppress non-error output.
   --dry-run           Print what would be done without doing it.
   --help, -h          Show this message.
@@ -81,6 +134,9 @@ Examples:
   $(basename "$0") --version v4.11.0        # Install specific version
   $(basename "$0") --source oss --silent    # Silent install from Aliyun OSS
   $(basename "$0") --install-dir /usr/local/bin  # System-wide install (needs sudo)
+  $(basename "$0") --locate                 # Run diagnostics (no install)
+  $(basename "$0") --skip-local             # Force download, ignore bundled binary
+  $(basename "$0") --source oss             # Force Aliyun OSS (China mainland)
 EOF
 }
 
@@ -103,6 +159,8 @@ while [[ $# -gt 0 ]]; do
       fi
       SOURCE="$1"; shift ;;
     --no-path) ADD_TO_PATH=false; shift ;;
+    --skip-local) SKIP_LOCAL=true; shift ;;
+    --locate) LOCATE_MODE=true; shift ;;
     --silent|-s) SILENT=true; shift ;;
     --dry-run) DRY_RUN=true; shift ;;
     --help|-h) usage; exit 0 ;;
@@ -110,6 +168,35 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# ──────────────────────────────────────────────
+# China mainland locale detection (zero-network)
+# ──────────────────────────────────────────────
+
+detect_china_locale() {
+  # 1 — Locale env vars
+  local lang
+  lang="${LC_ALL:-${LANG:-${LC_CTYPE:-${LC_MESSAGES:-}}}}"
+  case "$lang" in
+    zh_CN*|zh-CN*|"Chinese (Simplified)_China"*) return 0 ;;
+  esac
+
+  # 2 — TZ env var
+  case "${TZ:-}" in
+    Asia/Shanghai|Asia/Chongqing|Asia/Urumqi|Asia/Harbin) return 0 ;;
+  esac
+
+  # 3 — /etc/timezone
+  if [[ -f /etc/timezone ]]; then
+    local tz
+    tz=$(cat /etc/timezone 2>/dev/null || true)
+    case "$tz" in
+      Asia/Shanghai|Asia/Chongqing|Asia/Urumqi|Asia/Harbin) return 0 ;;
+    esac
+  fi
+
+  return 1
+}
+
 # ──────────────────────────────────────────────
 # Platform detection
 # ──────────────────────────────────────────────
@@ -245,8 +332,13 @@ get_download_urls() {
     github) urls+=("GitHub Releases|${gh_url}") ;;
     oss)    urls+=("Aliyun OSS|${oss_url}") ;;
     *)
-      urls+=("GitHub Releases|${gh_url}")
-      urls+=("Aliyun OSS|${oss_url}")
+      if [[ "$CHINA_DETECTED" == true ]]; then
+        urls+=("Aliyun OSS|${oss_url}")
+        urls+=("GitHub Releases|${gh_url}")
+      else
+        urls+=("GitHub Releases|${gh_url}")
+        urls+=("Aliyun OSS|${oss_url}")
+      fi
       ;;
   esac
 
@@ -430,11 +522,70 @@ main() {
   check_commands
   header
 
+  # Locate ourselves on disk (only works when run as a file, not piped)
+  detect_script_dir
+
+  # Auto-detect China mainland locale when no explicit source is given
+  if [[ -z "$SOURCE" ]]; then
+    if detect_china_locale; then
+      CHINA_DETECTED=true
+      step "China mainland locale detected: preferring Aliyun OSS mirror."
+    fi
+  fi
+
   # Detect platform
   local platform_key binary_name
   platform_key=$(get_platform_key)
   binary_name=$(get_binary_name "$platform_key")
 
+  # ── Locate mode: print diagnostics and exit ──
+  if [[ "$LOCATE_MODE" == true ]]; then
+    echo -e "${color_cyan}─── Locate / diagnostics ───${color_reset}"
+    echo ""
+    step "Script dir:       ${SCRIPT_DIR:-'(not available — piped via curl?)'}"
+    step "Platform key:     $platform_key"
+    step "Binary name:      $binary_name"
+    step "Default install:  $(get_default_install_dir)"
+    step "China locale:     $CHINA_DETECTED"
+    step "Source override:  ${SOURCE:-auto}"
+    step "OS:               $(uname -s)"
+
+    # Check for local binary
+    local locate_local
+    if locate_local=$(find_local_binary "$binary_name" 2>/dev/null); then
+      local local_status="(present but --version failed)"
+      if test_local_binary "$locate_local"; then
+        local_status="(valid)"
+      fi
+      step "Local binary:     ${locate_local} ${local_status}"
+    else
+      step "Local binary:     not found alongside script"
+    fi
+
+    # Check for already-installed binary
+    local default_dir existing_path
+    default_dir=$(get_default_install_dir)
+    existing_path="${default_dir}/${binary_name}"
+    if [[ -f "$existing_path" ]]; then
+      step "Already installed: $existing_path"
+    else
+      step "Already installed: not found at $default_dir"
+    fi
+
+    # Show download URLs that would be tried
+    local locate_urls
+    IFS=$'\n' read -r -d '' -a locate_urls < <(get_download_urls "$binary_name" "$VERSION" && printf '\0')
+    echo ""
+    step "Download order:"
+    for entry in "${locate_urls[@]}"; do
+      local l="${entry%%|*}" u="${entry#*|}"
+      step "  ${l}: ${u}"
+    done
+
+    echo ""
+    return
+  fi
+
   step "Platform:  $platform_key"
   step "Binary:    $binary_name"
 
@@ -455,9 +606,34 @@ main() {
 
   local binary_path="${INSTALL_DIR}/${binary_name}"
 
-  # Download if needed
-  if [[ -f "$binary_path" ]] && [[ -z "$VERSION" ]]; then
+  # ── Local binary discovery (bundled/sideload) ──
+  local use_local_binary=false
+  local local_binary_path=""
+  if [[ "$SKIP_LOCAL" != true ]]; then
+    if local_binary_path=$(find_local_binary "$binary_name" 2>/dev/null) && [[ -n "$local_binary_path" ]]; then
+      step "Found local binary alongside script: $(basename "$local_binary_path")"
+      if test_local_binary "$local_binary_path"; then
+        ok "Local binary verified (--version OK)"
+        use_local_binary=true
+      else
+        warn "Local binary found but --version check failed — will download instead"
+      fi
+    fi
+  else
+    step "Skipping local binary check (--skip-local)"
+  fi
+
+  # Install binary: local copy > already installed > download
+  if [[ -f "$binary_path" ]] && [[ -z "$VERSION" ]] && [[ "$use_local_binary" != true ]]; then
     ok "Binary already installed: $binary_path"
+  elif [[ "$use_local_binary" == true ]]; then
+    # Copy local binary to install dir
+    if [[ "$DRY_RUN" != true ]]; then
+      rm -f "$binary_path"
+      cp "$local_binary_path" "$binary_path"
+      chmod +x "$binary_path"
+    fi
+    ok "Installed (local): $binary_path"
   else
     local urls
     IFS=$'\n' read -r -d '' -a urls < <(get_download_urls "$binary_name" "$VERSION" && printf '\0')
@@ -494,7 +670,8 @@ main() {
       tried_msg+=$'\n'"Please check:"$'\n'
       tried_msg+="  - Network connectivity"$'\n'
       tried_msg+="  - The version/tag exists: ${VERSION:-latest}"$'\n'
-      tried_msg+="  - For GitHub rate limits, set GITHUB_TOKEN environment variable"
+      tried_msg+="  - For GitHub rate limits, set GITHUB_TOKEN environment variable"$'\n'
+      tried_msg+="  - If you have a local copy, place it alongside this script and re-run"
       die "$tried_msg"
     fi
 

package/scripts/postinstall.js

@@ -45,9 +45,65 @@ const packageJson = JSON.parse(
 const version = packageJson.version;
 const commandNames = Object.keys(packageJson.bin || { 'browser4-cli': './bin/browser4-cli.js' });
 
-// GitHub release URL
+// ---------------------------------------------------------------------------
+// China mainland locale detection (zero-network — uses only local env / Intl)
+// ---------------------------------------------------------------------------
+
+function isChinaLocale() {
+  // 1 — Locale env vars (Unix, Git Bash, WSL, Docker)
+  const lang = process.env.LC_ALL
+    || process.env.LANG
+    || process.env.LC_CTYPE
+    || process.env.LC_MESSAGES
+    || '';
+  if (/^(?:zh_CN|zh-CN|Chinese \(Simplified\)_China)/i.test(lang)) {
+    return true;
+  }
+
+  // 2 — TZ env var (Docker, CI)
+  const tz = process.env.TZ || '';
+  if (/^Asia\/(Shanghai|Chongqing|Urumqi|Harbin)$/.test(tz)) {
+    return true;
+  }
+
+  // 3 — Intl timezone API (V8/Node.js, no filesystem access needed)
+  try {
+    const resolvedTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (/^Asia\/(Shanghai|Chongqing|Urumqi|Harbin)$/.test(resolvedTz)) {
+      return true;
+    }
+  } catch {
+    // Intl not available (very old Node) — skip
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Download URLs (locale-aware ordering)
+// ---------------------------------------------------------------------------
+
 const GITHUB_REPO = 'platonai/Browser4';
-const DOWNLOAD_URL = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
+const DOWNLOAD_URL_GITHUB = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
+const DOWNLOAD_URL_OSS = `https://browser4.oss-cn-beijing.aliyuncs.com/releases/download/v${version}/${binaryName}`;
+
+/**
+ * Return download URLs ordered by locale preference.  `BROWSER4_RELEASES_BASE_URL`
+ * takes precedence; otherwise China mainland users get OSS-first ordering.
+ */
+function getDownloadUrls() {
+  // Single-source override
+  const envOverride = (process.env.BROWSER4_RELEASES_BASE_URL || '').trim();
+  if (envOverride) {
+    const base = envOverride.replace(/\/+$/, '');
+    return [`${base}/download/v${version}/${binaryName}`];
+  }
+
+  if (isChinaLocale()) {
+    return [DOWNLOAD_URL_OSS, DOWNLOAD_URL_GITHUB];
+  }
+  return [DOWNLOAD_URL_GITHUB, DOWNLOAD_URL_OSS];
+}
 
 async function downloadFile(url, dest) {
   return new Promise((resolve, reject) => {
@@ -130,19 +186,31 @@ async function main() {
   }
 
   console.log(`Downloading native binary for ${platformKey}...`);
-  console.log(`URL: ${DOWNLOAD_URL}`);
 
-  try {
-    await downloadFile(DOWNLOAD_URL, binaryPath);
+  const urls = getDownloadUrls();
 
-    // Make executable on Unix
-    if (platform() !== 'win32') {
-      chmodSync(binaryPath, 0o755);
+  let lastError = null;
+  for (const url of urls) {
+    console.log(`URL: ${url}`);
+    try {
+      await downloadFile(url, binaryPath);
+
+      // Make executable on Unix
+      if (platform() !== 'win32') {
+        chmodSync(binaryPath, 0o755);
+      }
+
+      console.log(`✓ Downloaded native binary: ${binaryName}`);
+      lastError = null;
+      break;
+    } catch (err) {
+      console.log(`Download failed: ${err.message}`);
+      lastError = err;
     }
+  }
 
-    console.log(`✓ Downloaded native binary: ${binaryName}`);
-  } catch (err) {
-    console.log(`Could not download native binary: ${err.message}`);
+  if (lastError) {
+    console.log(`Could not download native binary from any mirror: ${lastError.message}`);
     console.log('');
     console.log('To build the native binary locally:');
     console.log('  1. Install Rust: https://rustup.rs');