chore: publish

- appium@4.0.0-beta.4
 - @appium/base-driver@11.0.0-beta.3
 - @appium/base-plugin@4.0.0-beta.3
 - @appium/docutils@4.0.0-beta.3
 - @appium/driver-test-support@4.0.0-beta.3
 - @appium/execute-driver-plugin@8.0.0-beta.4
 - @appium/fake-driver@7.0.0-beta.4
 - @appium/fake-plugin@5.0.0-beta.4
 - @appium/http-server@1.0.0-beta.3
 - @appium/images-plugin@6.0.0-beta.4
 - @appium/logger@3.0.0-beta.2
 - @appium/opencv@6.0.0-beta.3
 - @appium/oxc-config@2.0.0-beta.2
 - @appium/plugin-test-support@4.0.0-beta.4
 - @appium/relaxed-caps-plugin@4.0.0-beta.4
 - @appium/schema@2.0.0-beta.2
 - @appium/storage-plugin@3.0.0-beta.4
 - @appium/support@8.0.0-beta.3
 - @appium/types@2.0.0-beta.3
 - @appium/universal-xml-plugin@4.0.0-beta.4

.claude/CLAUDE.md

@@ -0,0 +1,10 @@
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
+
+- **MCP tool** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them, including dynamic-dispatch hops grep can't follow. Name a file or symbol in the query to read its current line-numbered source. If it's listed but deferred, load it by name via tool search.
+- **Shell** (always works): `codegraph explore "<symbol names or question>"` prints the same output.
+
+If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is the user's decision.
+<!-- CODEGRAPH_END -->

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": ["mcp__codegraph__*"]
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "codegraph prompt-hook"
+          }
+        ]
+      }
+    ]
+  }
+}

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.cursor/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp", "--path", "."]
+    }
+  }
+}

.editorconfig

@@ -1,13 +1,14 @@
 # editorconfig.org
 root = true
 
-[*]
+[*.{js,cjs,mjs,jsx,ts,cts,mts,tsx,json,jsonc}]
 indent_style = space
 indent_size = 2
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
+max_line_length = 120
 
 [*.md]
 trim_trailing_whitespace = false

.fossa.yml

@@ -23,14 +23,10 @@ targets:
       path: ./packages/appium
     - type: npm
       path: ./packages/base-driver
-    - type: npm
-      path: ./packages/eslint-config-appium-ts
     - type: npm
       path: ./packages/fake-driver
     - type: npm
       path: ./packages/support
-    - type: npm
-      path: ./packages/test-support
     - type: npm
       path: ./packages/types
     - type: npm

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -3,7 +3,6 @@ description: Create a new bug report.
 title: '🐞 bug: <title>'
 labels: [Bug, Needs Triage]
 body:
-
   - type: markdown
     attributes:
       value: ':stop_sign: _Make sure you are reporting an issue. For general questions, please use [http://discuss.appium.io](http://discuss.appium.io)._'
@@ -13,9 +12,9 @@ body:
       label: Is there an existing issue for this?
       description: 'Please [search :mag: the issues](https://github.com/appium/appium/issues) to check if this bug has already been reported.'
       options:
-      - label: I have searched the existing issues
-        required: true
-  
+        - label: I have searched the existing issues
+          required: true
+
   - type: input
     attributes:
       label: Appium Version
@@ -49,7 +48,7 @@ body:
       description: |
         You can retrieve the latest server/driver/plugin version number by running `npm info <package-name> version`. If you are not up to date, please try to reproduce your issue after updating all affected components.
       options:
-      - label: I confirm the issue is still reproducible with the latest component versions
+        - label: I confirm the issue is still reproducible with the latest component versions
 
   - type: textarea
     attributes:
@@ -82,10 +81,10 @@ body:
 
         :warning: _Remember to redact or remove any sensitive information!_
       value: |
-          - Debug details (`appium --show-debug-info`):
-          - Last component version(s) which did _not_ exhibit the problem:
-          - Platform and version of device under test:
-          - Real device or emulator/simulator:
+        - Debug details (`appium --show-debug-info`):
+        - Last component version(s) which did _not_ exhibit the problem:
+        - Platform and version of device under test:
+        - Real device or emulator/simulator:
 
   - type: textarea
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
-  - name: ❓ Question 
+  - name: ❓ Question
     url: https://discuss.appium.io/
     about: Please use the Appium forum for any questions.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,9 +1,8 @@
 name: 💡 Feature Request
 description: Suggest an idea for this project.
-title: "💡 feat: <title>"
+title: '💡 feat: <title>'
 labels: [Enhancement]
 body:
-
   - type: textarea
     attributes:
       label: Is your feature request related to a problem?

.github/actions/setup-build/action.yml

@@ -20,12 +20,12 @@ runs:
   using: composite
   steps:
     - name: Use Node.js ${{ inputs.node-version }}
-      uses: actions/setup-node@v6
+      uses: actions/setup-node@v7.1.0
       with:
         node-version: ${{ inputs.node-version }}
         cache: npm
     - name: SocketDev Security Check
-      uses: SocketDev/action@v1
+      uses: SocketDev/action@v1.3.2
       with:
         mode: firewall-free
     - name: Install dependencies
@@ -33,8 +33,44 @@ runs:
       run: |
         # Replace npm with sfw npm in the install command
         install_cmd="${{ inputs.install-command }}"
-        install_cmd="${install_cmd//npm /sfw npm }"
-        $install_cmd
+        sfw_install_cmd="${install_cmd//npm /sfw npm }"
+
+        # Socket Firewall can fail to reach its own backend (a transient
+        # network error unrelated to the actual npm install) and, in that
+        # case, either exit non-zero or exit 0 without having actually
+        # completed the install, leaving node_modules incomplete. We only
+        # want to fall back to a plain (non-firewalled) install when we can
+        # positively attribute the failure to *that* Socket Firewall error —
+        # a real npm/package problem (bad version, checksum mismatch, failing
+        # postinstall script, etc.) must fail the job as-is, not be silently
+        # retried and potentially masked.
+        sfw_log="$(mktemp)"
+        set +e
+        $sfw_install_cmd 2>&1 | tee "$sfw_log"
+        sfw_exit="${PIPESTATUS[0]}"
+        set -e
+
+        sfw_infra_failure=0
+        if grep -qi 'Socket Firewall encountered an unexpected error' "$sfw_log"; then
+          sfw_infra_failure=1
+        fi
+
+        install_incomplete=0
+        if [ "$sfw_exit" -eq 0 ]; then
+          npm ls --depth=0 >/dev/null 2>&1 || install_incomplete=1
+        fi
+        rm -f "$sfw_log"
+
+        if [ "$sfw_infra_failure" -eq 1 ] && { [ "$sfw_exit" -ne 0 ] || [ "$install_incomplete" -eq 1 ]; }; then
+          echo "::warning::Socket Firewall failed to reach its backend; retrying with a plain npm install"
+          $install_cmd
+        elif [ "$sfw_exit" -ne 0 ]; then
+          echo "::error::npm install failed"
+          exit "$sfw_exit"
+        elif [ "$install_incomplete" -eq 1 ]; then
+          echo "::error::npm install appears incomplete and is not attributable to a Socket Firewall failure"
+          exit 1
+        fi
     - name: Build packages
       if: ${{ inputs.run-build == 'true' }}
       shell: bash

.github/copilot-instructions.md

@@ -0,0 +1,9 @@
+# Copilot Instructions
+
+## Code Review
+
+When reviewing JavaScript or TypeScript changes, check new uses of Node.js built-in APIs against the supported Node.js versions declared in package.json#engines.node. The current supported range is ^20.19.0 || ^22.12.0 || >=24.0.0.
+
+For each new Node.js built-in API or option, verify that it exists and is stable across all supported Node.js versions. If any supported version lacks the API, only supports it experimentally, or has different behavior, leave a review comment and suggest using the existing dependency, adding a fallback, avoiding the API, or raising the engine requirement.
+
+Example: util.styleText exists in Node.js 20.12+, but only became stable in Node.js 22.13.0 and 23.5.0. Because this repository supports Node.js 20.19.0 and 22.12.0, replacing a color library with util.styleText should be flagged unless the project explicitly accepts relying on a non-stable API for those supported versions.

.github/labeler.yml

@@ -43,6 +43,11 @@ labels:
     matcher:
       files: ['packages/appium/**']
 
+  - label: '@appium/http-server'
+    sync: true
+    matcher:
+      files: ['packages/http-server/**']
+
   - label: '@appium/base-driver'
     sync: true
     matcher:
@@ -68,10 +73,10 @@ labels:
     matcher:
       files: ['packages/driver-test-support/**']
 
-  - label: '@appium/eslint-config-appium-ts'
+  - label: '@appium/oxc-config'
     sync: true
     matcher:
-      files: ['packages/eslint-config-appium-ts/**']
+      files: ['packages/oxc-config/**']
 
   - label: '@appium/execute-driver-plugin'
     sync: true
@@ -118,6 +123,11 @@ labels:
     matcher:
       files: ['packages/schema/**']
 
+  - label: '@appium/semantic-release-config'
+    sync: true
+    matcher:
+      files: ['packages/semantic-release-config/**']
+
   - label: '@appium/support'
     sync: true
     matcher:
@@ -128,11 +138,6 @@ labels:
     matcher:
       files: ['packages/strongbox/**']
 
-  - label: '@appium/test-support'
-    sync: true
-    matcher:
-      files: ['packages/test-support/**']
-
   - label: '@appium/tsconfig'
     sync: true
     matcher:

.github/workflows/auto-labeler.yml

@@ -13,4 +13,4 @@ jobs:
     name: Auto-Label PRs
     runs-on: ubuntu-latest
     steps:
-      - uses: fuxingloh/multi-labeler@v5
+      - uses: fuxingloh/multi-labeler@v5.0.0

.github/workflows/build.yml

@@ -3,42 +3,40 @@ on:
   push:
     branches:
       - master
+      - appium4
     # this list of paths could potentially impact the build
     paths:
       - '**/tsconfig*.json'
-      - 'packages/base-driver/static/**/*'
+      - 'packages/base-driver/test-fixtures/**/*'
       - 'packages/*/test/**'
       - 'packages/*/bin'
-      - 'packages/**/*.ts'
+      - 'packages/**/*.{js,mjs,cjs,ts}'
       - 'packages/**/*.json'
-      - 'packages/**/*.js'
       - 'package*.json'
       - 'lerna.json'
       - '.npmrc'
-      - '.mocharc.js'
       - '.github/workflows/build.yml' # this file
-      - '.eslintrc'
-      - '.eslintignore'
+      - 'oxlint.config.mjs'
+      - 'oxfmt.config.mjs'
       - '!**/sample-code/**'
       - '!packages/*/docs/**'
   pull_request:
     branches:
       - master
+      - appium4
     paths:
       - '**/tsconfig*.json'
-      - 'packages/base-driver/static/**/*'
+      - 'packages/base-driver/test-fixtures/**/*'
       - 'packages/*/test/**'
       - 'packages/*/bin'
-      - 'packages/**/*.ts'
+      - 'packages/**/*.{js,mjs,cjs,ts}'
       - 'packages/**/*.json'
-      - 'packages/**/*.js'
       - 'package*.json'
       - 'lerna.json'
       - '.npmrc'
-      - '.mocharc.js'
       - '.github/workflows/build.yml' # this file
-      - '.eslintrc'
-      - '.eslintignore'
+      - 'oxlint.config.mjs'
+      - 'oxfmt.config.mjs'
       - '!**/sample-code/**'
       - '!packages/*/docs/**'
 
@@ -61,7 +59,7 @@ jobs:
     outputs:
       packages: ${{ steps.discover-packages.outputs.packages }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Discover packages with e2e tests
         id: discover-packages
         run: |
@@ -103,14 +101,14 @@ jobs:
 
   test-smoke:
     needs:
-    - prepare_matrix
+      - prepare_matrix
     name: Smoke Tests
     strategy:
       matrix:
         node-version: ${{ fromJSON(needs.prepare_matrix.outputs.versions) }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Setup, install and build
         uses: ./.github/actions/setup-build
         with:
@@ -122,14 +120,14 @@ jobs:
 
   test-unit:
     needs:
-    - prepare_matrix
+      - prepare_matrix
     name: Unit Tests
     strategy:
       matrix:
         node-version: ${{ fromJSON(needs.prepare_matrix.outputs.versions) }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Setup, install and build
         uses: ./.github/actions/setup-build
         with:
@@ -141,14 +139,14 @@ jobs:
 
   test-types:
     needs:
-    - prepare_matrix
+      - prepare_matrix
     name: Type Tests
     strategy:
       matrix:
         node-version: ${{ fromJSON(needs.prepare_matrix.outputs.versions) }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Setup, install and build
         uses: ./.github/actions/setup-build
         with:
@@ -160,8 +158,8 @@ jobs:
 
   test-e2e:
     needs:
-    - prepare_matrix
-    - prepare_e2e_packages
+      - prepare_matrix
+      - prepare_e2e_packages
     name: E2E Tests - ${{ matrix.package_dir }} (Node ${{ matrix.node-version }})
     if: ${{ github.event_name == 'pull_request' }}
     strategy:
@@ -171,7 +169,7 @@ jobs:
         package_dir: ${{ fromJSON(needs.prepare_e2e_packages.outputs.packages) }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Setup, install and build
         uses: ./.github/actions/setup-build
         with:
@@ -188,12 +186,16 @@ jobs:
     name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Setup and install (no build)
         uses: ./.github/actions/setup-build
         with:
           node-version: lts/*
           install-command: npm ci
           run-build: 'false'
-      - name: ESLint
+      - name: Lint
         run: npm run lint:ci
+      - name: Format check
+        run: npm run format:check
+      - name: Verify changelog generation
+        run: npm run verify:changelog-generation

.github/workflows/clean-cache.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7.0.1
 
       - name: Cleanup
         run: |

.github/workflows/crowdin-stats.yml

@@ -21,9 +21,9 @@ jobs:
             project_name: appium-inspector
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
           cache: 'npm'
@@ -36,7 +36,7 @@ jobs:
           CROWDIN_PROJECT_ID: ${{ vars[matrix.project_id_var] }}
           CROWDIN_TOKEN: ${{ secrets.CROWDIN_DOCS_TOKEN }}
       - name: Post to Slack for ${{ matrix.project_name }}
-        uses: slackapi/slack-github-action@v3.0.3
+        uses: slackapi/slack-github-action@v4.0.0
         with:
           errors: true
           webhook: ${{ secrets.SLACK_WEBHOOK_URL }}

.github/workflows/crowdin-sync-docs-translations.yml

@@ -12,11 +12,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
         with:
           persist-credentials: false
       - name: Use Node.js LTS
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
           cache: 'npm'

.github/workflows/crowdin-update-docs-resources.yml

@@ -15,9 +15,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
           cache: 'npm'

.github/workflows/deploy.yml

@@ -10,17 +10,11 @@ permissions:
 
 jobs:
   prepare_matrix:
-    runs-on: ubuntu-latest
-    outputs:
-      versions: ${{ steps.generate-matrix.outputs.lts }}
-    steps:
-    - name: Select all current LTS versions of Node.js
-      id: generate-matrix
-      uses: msimerson/node-lts-versions@v2
+    uses: appium/appium-workflows/.github/workflows/node-lts-matrix.yml@main
 
   check:
     needs:
-    - prepare_matrix
+      - prepare_matrix
     name: Check
     runs-on: ${{ matrix.os }}
     strategy:
@@ -29,7 +23,7 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
     steps:
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: ${{ matrix.node-version }}
       - name: Install Appium

.github/workflows/docs.yml

@@ -37,7 +37,7 @@ jobs:
     name: Docs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Install dependencies (Node.js)
         uses: bahmutov/npm-install@v1.12.1
         with:

.github/workflows/fossa.yml

@@ -13,7 +13,7 @@ jobs:
     env:
       FOSSA_API_KEY: ${{secrets.FOSSA_API_KEY}}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
         with:
           ref: master
       - name: Install dependencies

.github/workflows/github-contrib-stats.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Use Node.js LTS
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7.1.0
         with:
           node-version: lts/*
           cache: 'npm'
@@ -29,7 +29,7 @@ jobs:
           # GITHUB_TOKEN is optional - if not provided, uses unauthenticated requests (rate limited)
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Post to Slack
-        uses: slackapi/slack-github-action@v3.0.3
+        uses: slackapi/slack-github-action@v4.0.0
         with:
           errors: true
           webhook: ${{ secrets.SLACK_WEBHOOK_URL }}

.github/workflows/manual-release.yml

@@ -8,6 +8,16 @@ on:
         required: true
         type: boolean
         default: true
+      recover_missing_only:
+        description: 'Recovery mode: skip version bump, publish only packages missing on npm at their current package.json version'
+        required: true
+        type: boolean
+        default: false
+      allow_legacy_peer_deps:
+        description: 'Beta branch only: pass --legacy-peer-deps to lerna''s internal npm calls, for when a dependent''s peerDependencies range still lags a just-bumped major (causes ERESOLVE otherwise). Leave off unless you hit that failure.'
+        required: true
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -18,11 +28,15 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/master' && contains(fromJSON('["mykola-mokhnach", "jlipps", "eglitise", "KazuCocoa"]'), github.actor)
+    # keep this branch name in sync with env.BETA_BRANCH below - the `env` context isn't available
+    # to jobs.<job_id>.if (GitHub Actions resolves it before job-level env is set up)
+    if: (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/appium4') && contains(fromJSON('["mykola-mokhnach", "jlipps", "eglitise", "KazuCocoa"]'), github.actor)
+    env:
+      BETA_BRANCH: appium4
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
 
@@ -43,15 +57,137 @@ jobs:
           # for lerna createRelease
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           DRY_RUN: ${{ inputs.dry_run }}
+          RECOVER_MISSING_ONLY: ${{ inputs.recover_missing_only }}
+          ALLOW_LEGACY_PEER_DEPS: ${{ inputs.allow_legacy_peer_deps }}
         run: |
           set -euo pipefail
+
+          # On the beta branch ($BETA_BRANCH), every release is a beta prerelease anchored at its
+          # target major (see packages/semantic-release-config's "Next-major beta branches" docs
+          # for the equivalent semantic-release behavior this mirrors).
+          #
+          # allow_legacy_peer_deps: independent next-major beta.0 bumps can briefly outrun a
+          # dependent's committed peerDependencies range, aborting lerna's internal lockfile
+          # refresh with ERESOLVE. Opt-in only - it masks a real (if temporary) peer mismatch.
+          LEGACY_PEER_DEPS_FLAGS=""
+          if [ "$ALLOW_LEGACY_PEER_DEPS" = "true" ]; then
+            LEGACY_PEER_DEPS_FLAGS="--npm-client-args=--legacy-peer-deps"
+          fi
+
+          BETA_FLAGS=""
+          DIST_TAG_FLAGS=""
+          NPM_TAG_FLAGS=""
+          if [ "${{ github.ref_name }}" = "$BETA_BRANCH" ]; then
+            BETA_FLAGS="--conventional-prerelease --preid beta $LEGACY_PEER_DEPS_FLAGS"
+            DIST_TAG_FLAGS="--dist-tag beta"
+            # `npm publish` takes --tag; --dist-tag is lerna-only
+            NPM_TAG_FLAGS="--tag beta"
+          fi
+
+          # Prints "<pkg_name>@<pkg_version>" to stdout for each non-private workspace package
+          # whose current package.json version is not yet on npm.
+          find_missing_packages() {
+            for pkg_json in packages/*/package.json; do
+              if [ ! -f "$pkg_json" ]; then
+                continue
+              fi
+
+              if [ "$(jq -r '.private // false' "$pkg_json")" = "true" ]; then
+                continue
+              fi
+
+              pkg_name="$(jq -r '.name // empty' "$pkg_json")"
+              pkg_version="$(jq -r '.version // empty' "$pkg_json")"
+              if [ -z "$pkg_name" ] || [ -z "$pkg_version" ]; then
+                echo "Skipping malformed package manifest: $pkg_json" >&2
+                continue
+              fi
+
+              pkg_spec="${pkg_name}@${pkg_version}"
+              if ! npm view "$pkg_spec" version >/dev/null 2>&1; then
+                echo "$pkg_spec"
+              fi
+            done
+          }
+
+          # Resolves the workspace directory of a package given its npm name.
+          package_dir_for() {
+            local target="$1"
+            for pkg_json in packages/*/package.json; do
+              if [ ! -f "$pkg_json" ]; then
+                continue
+              fi
+              if [ "$(jq -r '.name // empty' "$pkg_json")" = "$target" ]; then
+                dirname "$pkg_json"
+                return 0
+              fi
+            done
+            return 1
+          }
+
+          # Publishes each "<pkg_name>@<pkg_version>" package spec passed as an argument.
+          # `lerna publish` has no per-package scope filter, so this runs `npm publish`
+          # directly from each package's directory instead. Returns non-zero if any
+          # individual publish failed; npm publish's own exit code is taken as authoritative,
+          # no npm registry re-scan is done to double-check it.
+          publish_missing_packages() {
+            echo "Publishing missing packages one-by-one"
+            local overall_status=0
+            for pkg_spec in "$@"; do
+              pkg_name="${pkg_spec%@*}"
+              pkg_dir="$(package_dir_for "$pkg_name")"
+              if [ -z "$pkg_dir" ]; then
+                echo "Could not resolve workspace directory for ${pkg_name}"
+                overall_status=1
+                continue
+              fi
+
+              echo "Publishing ${pkg_spec}"
+              set +e
+              (cd "$pkg_dir" && npm publish $NPM_TAG_FLAGS)
+              publish_exit_code=$?
+              set -e
+              if [ $publish_exit_code -ne 0 ]; then
+                echo "npm publish failed for ${pkg_spec} (exit code ${publish_exit_code})"
+                overall_status=1
+              fi
+            done
+            return $overall_status
+          }
+
+          if [ "$RECOVER_MISSING_ONLY" = "true" ]; then
+            echo "Recovery mode: scanning for packages missing on npm at their current package.json version"
+            mapfile -t missing < <(find_missing_packages)
+
+            if [ ${#missing[@]} -eq 0 ]; then
+              echo "No missing packages found; nothing to do"
+              exit 0
+            fi
+
+            echo "Missing package versions on npm:"
+            printf ' - %s\n' "${missing[@]}"
+
+            if [ "$DRY_RUN" = "true" ]; then
+              echo "Dry run: not publishing"
+              exit 0
+            fi
+
+            if ! publish_missing_packages "${missing[@]}"; then
+              echo "Recovery incomplete: one or more packages failed to publish"
+              exit 1
+            fi
+
+            echo "All missing packages published successfully"
+            exit 0
+          fi
+
           if [ "$DRY_RUN" = "true" ]; then
             echo "Running lerna publish in dry-run mode"
-            printf "n\n" | npx lerna version --exact --no-git-tag-version --no-push
+            printf "n\n" | npx lerna version --no-git-tag-version --no-push $BETA_FLAGS
           else
             echo "Running lerna publish for real"
             set +e
-            release_output="$(npm run release -- --yes 2>&1)"
+            release_output="$(npm run release -- --yes $BETA_FLAGS $DIST_TAG_FLAGS 2>&1)"
             release_exit_code=$?
             set -e
             printf '%s\n' "$release_output"
@@ -76,55 +212,13 @@ jobs:
               fi
 
               git checkout "$tagged_commit"
-              missing=()
-              for pkg_json in packages/*/package.json; do
-                if [ ! -f "$pkg_json" ]; then
-                  continue
-                fi
-
-                if [ "$(jq -r '.private // false' "$pkg_json")" = "true" ]; then
-                  continue
-                fi
-
-                pkg_name="$(jq -r '.name // empty' "$pkg_json")"
-                pkg_version="$(jq -r '.version // empty' "$pkg_json")"
-                if [ -z "$pkg_name" ] || [ -z "$pkg_version" ]; then
-                  echo "Skipping malformed package manifest: $pkg_json"
-                  continue
-                fi
-
-                pkg_spec="${pkg_name}@${pkg_version}"
-                if ! npm view "$pkg_spec" version >/dev/null 2>&1; then
-                  missing+=("$pkg_spec")
-                fi
-              done
+              mapfile -t missing < <(find_missing_packages)
 
               if [ ${#missing[@]} -gt 0 ]; then
                 echo "Missing package versions on npm before scoped recovery:"
                 printf ' - %s\n' "${missing[@]}"
-                echo "Publishing missing packages one-by-one with scope"
-                for pkg_spec in "${missing[@]}"; do
-                  pkg_name="${pkg_spec%@*}"
-                  echo "Publishing ${pkg_name}"
-                  set +e
-                  npx lerna publish from-package --yes --scope "$pkg_name"
-                  scoped_exit_code=$?
-                  set -e
-                  if [ $scoped_exit_code -ne 0 ]; then
-                    echo "Scoped publish exited non-zero for ${pkg_name}; will verify on npm"
-                  fi
-                done
-
-                final_missing=()
-                for pkg_spec in "${missing[@]}"; do
-                  if ! npm view "$pkg_spec" version >/dev/null 2>&1; then
-                    final_missing+=("$pkg_spec")
-                  fi
-                done
-
-                if [ ${#final_missing[@]} -gt 0 ]; then
-                  echo "Recovery incomplete after scoped retries. Still missing:"
-                  printf ' - %s\n' "${final_missing[@]}"
+                if ! publish_missing_packages "${missing[@]}"; then
+                  echo "Recovery incomplete: one or more packages failed to publish"
                   exit $release_exit_code
                 fi
               fi

.github/workflows/manual-version.yml

@@ -15,11 +15,15 @@ permissions:
 jobs:
   version:
     runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/master' && contains(fromJSON('["mykola-mokhnach", "jlipps", "eglitise", "KazuCocoa"]'), github.actor)
+    # keep this branch name in sync with env.BETA_BRANCH below - the `env` context isn't available
+    # to jobs.<job_id>.if (GitHub Actions resolves it before job-level env is set up)
+    if: (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/appium4') && contains(fromJSON('["mykola-mokhnach", "jlipps", "eglitise", "KazuCocoa"]'), github.actor)
+    env:
+      BETA_BRANCH: appium4
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
 
@@ -38,4 +42,9 @@ jobs:
       - name: Run Lerna version
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: npx lerna version --exact --yes
+        run: |
+          BETA_FLAGS=""
+          if [ "${{ github.ref_name }}" = "$BETA_BRANCH" ]; then
+            BETA_FLAGS="--conventional-prerelease --preid beta"
+          fi
+          npx lerna version --yes $BETA_FLAGS

.github/workflows/on-hold.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check for "On Hold" label
-        uses: egmacke/action-check-label@v4
+        uses: egmacke/action-check-label@v5
         with:
           label: On Hold
           state: absent

.github/workflows/publish-doc.yml

@@ -2,17 +2,21 @@ name: Publish docs
 
 on:
   workflow_dispatch:
-  workflow_run:
-    workflows: ["Appium Server Release"]
-    types:
-      - completed
+  push:
+    # Runs when any new Appium tag is pushed = there is a new release
+    # Does not trigger for tags with a slash, e.g. 1.0/beta
+    tags:        
+      - appium@*
+      - '!appium@*beta*'
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0 # ensure the docs branch is also fetched
       - run: |
           git config user.name github-actions
           git config user.email github-actions@github.com
@@ -24,9 +28,5 @@ jobs:
           run-build: 'true'
       - name: Install dependencies (Python)
         run: npm run install-docs-deps
-      - name: Fetch gh-pages
-        run: |
-          git fetch origin gh-pages:gh-pages || true
       - name: Publish docs
-        run: |
-          npm run docs:publish
+        run: npm run docs:publish

.github/workflows/renovate.yml

@@ -6,14 +6,12 @@ on:
     paths:
       - '.github/workflows/renovate.yml' # this file
       - '.renovaterc.json'
-      - 'renovate/default.json'
   pull_request:
     branches:
       - master
     paths:
       - '.github/workflows/renovate.yml' # this file
       - '.renovaterc.json'
-      - 'renovate/default.json'
 
 permissions:
   contents: read
@@ -23,8 +21,8 @@ jobs:
     name: Check Renovate Configs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
       - name: Validate Renovate Config
         uses: rinchsan/renovate-config-validator@v0.2.1
         with:
-          pattern: '{.renovaterc.json,renovate/default.json}'
+          pattern: '.renovaterc.json'

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}

.mocharc.js

@@ -1,11 +0,0 @@
-// @ts-check
-
-'use strict';
-
-module.exports = {
-  require: ['ts-node/register'],
-  // forbids use of .only() in CI
-  forbidOnly: Boolean(process.env.CI),
-  color: true,
-  timeout: '5s',
-};

.npmrc

@@ -1,4 +1,3 @@
 # Do not disable package-lock. Disabling package-lock also disables npm-shrinkwrap
 package-lock=true
-save-exact=true
 foreground-scripts=true

.prettierignore

@@ -1,15 +0,0 @@
-**/node_modules/**
-**/build/**
-**/fixtures/**
-**/*.min.*
-**/*.md
-package-lock.json
-package.json
-**/.vscode/**
-**/*.html
-**/generated/**
-# generated
-packages/types/lib/appium-config.ts
-**/*.hbs
-
-/.nx/workspace-data

.renovaterc.json

@@ -1,9 +1,6 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
-  "extends": ["github>appium/appium//renovate/default"],
-  "schedule": [
-    "after 10pm",
-    "before 5:00am"
-  ],
+  "extends": ["github>appium/appium-workflows//renovate/default"],
+  "schedule": ["after 10pm", "before 5:00am"],
   "timezone": "America/Vancouver"
 }

AGENTS.md

@@ -0,0 +1,4 @@
+# Repository guidance
+
+Before changing code, read and follow the
+[contributor style guide](packages/appium/docs/en/contributing/index.md#code-style).

CHANGELOG.md

@@ -29,11 +29,12 @@ to driver/client documentation
 * [fake-plugin](packages/fake-plugin/CHANGELOG.md)
 * [logger](packages/logger/CHANGELOG.md)
 * [opencv](packages/opencv/CHANGELOG.md)
+* [oxc-config](packages/oxc-config/CHANGELOG.md)
 * [plugin-test-support](packages/plugin-test-support/CHANGELOG.md)
 * [schema](packages/schema/CHANGELOG.md)
+* [semantic-release-config](packages/semantic-release-config/CHANGELOG.md)
 * [strongbox](packages/strongbox/CHANGELOG.md)
 * [support](packages/support/CHANGELOG.md)
-* [test-support](packages/test-support/CHANGELOG.md)
 * [tsconfig](packages/tsconfig/CHANGELOG.md)
 * [types](packages/types/CHANGELOG.md)
 
@@ -42,4 +43,5 @@ The changelog links used for these modules lead to the last version of their cha
 * [doctor](https://github.com/appium/appium/blob/8daf5e123ac14c8325acf504fb33eb28e1a3dd78/packages/doctor/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/20805))
 * [eslint-config-appium](https://github.com/appium/appium/blob/4b3a8c2197a587ec5a2606b662e4e7667a7852cb/packages/eslint-config-appium/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/20856))
 * [gulp-plugins](https://github.com/appium/appium/blob/0823f0b60e40395cd1dc3b72cfa3c0092bc81302/packages/gulp-plugins/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/17943))
+* [test-support](https://github.com/appium/appium/blob/1a46d7d61ee49c7e82a63687c5647c42ab69513d/packages/test-support/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/22351))
 * [typedoc-plugin-appium](https://github.com/appium/appium/blob/d6204b6902074210943d7bbbf72d139b9b170a20/packages/typedoc-plugin-appium/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/19465))

eslint.config.mjs

@@ -1,42 +0,0 @@
-import appiumConfig from '@appium/eslint-config-appium-ts';
-import {defineConfig, globalIgnores} from 'eslint/config';
-
-// Create a modified config subset for test support files:
-// Extract the test file related configs (Mocha plugin and custom rules),
-// then override their 'files' property (match by name — resilient to new config entries).
-const testFileConfigItems = appiumConfig.filter(
-  (item) => typeof item?.name === 'string' && item.name.startsWith('Test Files'),
-);
-const testSupportFiles = [
-  'packages/test-support/lib/**',
-  'packages/driver-test-support/lib/**',
-  'packages/plugin-test-support/lib/**',
-];
-const testSupportConfig = testFileConfigItems.map((item) => ({...item, files: testSupportFiles}));
-
-export default defineConfig([
-  {
-    name: 'Base Config',
-    extends: [appiumConfig],
-  },
-  {
-    name: 'Test Support',
-    extends: [testSupportConfig],
-  },
-  {
-    name: 'Consistent type-only imports (all packages)',
-    files: ['**/*.{ts,tsx,mtsx}'],
-    rules: {
-      '@typescript-eslint/consistent-type-imports': [
-        'error',
-        { fixStyle: 'separate-type-imports', prefer: 'type-imports' },
-      ],
-    },
-  },
-  globalIgnores([
-    '**/build-fixtures/**',
-    'packages/appium/docs/**/assets/**',
-    'packages/appium/docs/**/js/**',
-    'packages/appium/sample-code/**',
-  ]),
-]);

lerna.json

@@ -2,9 +2,6 @@
   "$schema": "https://json.schemastore.org/lerna",
   "changelogPreset": "conventional-changelog-conventionalcommits",
   "command": {
-    "add": {
-      "exact": true
-    },
     "publish": {
       "message": "chore: publish"
     },
@@ -14,8 +11,7 @@
     "version": {
       "conventionalCommits": true,
       "createRelease": "github",
-      "allowBranch": ["master", "appium3"],
-      "exact": true
+      "allowBranch": ["master", "appium4"]
     }
   },
   "ignoreChanges": ["**/test/**", "**/*.md"],

oxfmt.config.mjs

@@ -0,0 +1,11 @@
+import appiumConfig, {defineConfig, ignorePatterns as appiumIgnorePatterns} from '@appium/oxc-config/oxfmt';
+
+export default defineConfig({
+  ...appiumConfig,
+  ignorePatterns: [
+    ...appiumIgnorePatterns,
+    'packages/appium/docs/**',
+    'packages/schema/lib/appium-config.schema.json',
+    'packages/types/lib/appium-config.ts',
+  ],
+});

oxlint.config.mjs

@@ -0,0 +1,11 @@
+import appiumConfig, {defineConfig, ignorePatterns as appiumIgnorePatterns} from '@appium/oxc-config/oxlint';
+
+export default defineConfig({
+  extends: [appiumConfig],
+  ignorePatterns: [
+    ...appiumIgnorePatterns,
+    'packages/appium/docs/**/assets/**',
+    'packages/appium/docs/**/js/**',
+    'packages/appium/sample-code/**',
+  ],
+});

package.json

@@ -4,28 +4,31 @@
   "private": true,
   "description": "Automation for Apps.",
   "keywords": [
+    "android",
     "automation",
+    "firefoxos",
+    "ios",
     "javascript",
     "selenium",
-    "webdriver",
-    "ios",
-    "android",
-    "firefoxos",
-    "testing"
+    "testing",
+    "webdriver"
   ],
   "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
   },
+  "license": "Apache-2.0",
+  "author": "https://github.com/appium",
   "repository": {
     "type": "git",
     "url": "https://github.com/appium/appium.git"
   },
-  "license": "Apache-2.0",
-  "author": "https://github.com/appium",
   "workspaces": [
     "packages/*"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "run-s build:*",
     "build:compile": "tsc -b",
@@ -45,11 +48,12 @@
     "docs": "npm run -w packages/appium build:docs",
     "docs:preview": "npm run -w packages/appium build:docs:preview",
     "docs:publish": "npm run -w packages/appium publish:docs",
-    "doctor": "node ./scripts/doctor-stub.mjs",
     "install-docs-deps": "npm run -w packages/appium install-docs-deps",
-    "lint": "eslint .",
-    "lint:ci": "eslint --quiet .",
-    "lint:fix": "run-s \"lint -- --fix\"",
+    "format": "oxfmt -c oxfmt.config.mjs .",
+    "format:check": "oxfmt -c oxfmt.config.mjs --check .",
+    "lint": "oxlint -c oxlint.config.mjs .",
+    "lint:ci": "oxlint -c oxlint.config.mjs --quiet .",
+    "lint:fix": "oxlint -c oxlint.config.mjs --fix .",
     "prepare": "run-p rebuild",
     "prepublishOnly": "run-s rebuild",
     "preversion": "run-s rebuild",
@@ -57,108 +61,56 @@
     "rebuild": "run-s clean build",
     "reinstall": "run-s clean clean:deps ci",
     "reinstall:angry": "npm run clean:dangerously && npm ci",
-    "release": "lerna publish --exact",
+    "release": "lerna publish",
     "stage-synced-pkgs": "git add -A packages/appium/README.md \"packages/*/package.json\"",
     "start": "appium",
-    "sync-pkgs": "run-p sync-pkgs:*",
-    "sync-pkgs:appium-readme": "sync-monorepo-packages --force --no-package-json --packages=packages/appium README.md",
-    "sync-pkgs:common-fields:default": "sync-monorepo-packages --packages=\"!packages/logger\" --fields=author,license,bugs,homepage",
-    "sync-pkgs:common-fields:logger": "sync-monorepo-packages --packages=\"packages/logger\" --fields=author,bugs,homepage",
-    "sync-pkgs:keywords": "sync-monorepo-packages --field=keywords --packages=\"packages/*\" --packages=\"!packages/types\" --packages=\"!packages/eslint-config-appium-ts\" ",
-    "sync-pkgs:license": "sync-monorepo-packages --force --no-package-json --packages=\"!packages/logger\" LICENSE",
+    "sync-pkgs": "node ./scripts/sync-monorepo-packages.mjs",
     "test": "run-s test:quick",
     "test:ci": "run-s test:smoke test:unit test:types test:e2e",
     "test:e2e": "lerna run test:e2e",
     "test:quick": "run-s lint test:unit test:types",
     "test:slow": "run-s test:quick test:smoke test:e2e",
-    "test:smoke": "smoker --all test:smoke",
+    "test:smoke": "lerna run test:smoke",
     "test:types": "lerna run test:types",
     "test:unit": "lerna run test",
     "upload": "gulp github-upload",
+    "verify:changelog-generation": "node ./scripts/verify-changelog-generation.mjs",
     "zip": "zip -qr ./appium.zip ./packages/appium",
     "zip-and-upload": "run-s zip upload"
   },
-  "prettier": {
-    "bracketSpacing": false,
-    "printWidth": 100,
-    "singleQuote": true
-  },
   "devDependencies": {
-    "@colors/colors": "1.6.0",
-    "@eslint/js": "10.0.1",
-    "@stylistic/eslint-plugin": "5.10.0",
-    "@tsconfig/node20": "20.1.9",
-    "@types/argparse": "2.0.17",
+    "@appium/oxc-config": "2.0.0-beta.0",
+    "@tsconfig/node22": "22.0.0",
     "@types/async-lock": "1.4.2",
-    "@types/base64-stream": "1.0.5",
-    "@types/bluebird": "3.5.42",
-    "@types/chai": "5.2.3",
-    "@types/chai-as-promised": "8.0.2",
     "@types/express": "5.0.6",
-    "@types/jsftp": "2.1.5",
     "@types/json-schema": "7.0.15",
-    "@types/klaw": "3.0.7",
     "@types/lockfile": "1.0.4",
-    "@types/lodash": "4.17.24",
     "@types/method-override": "3.0.0",
-    "@types/mocha": "10.0.10",
-    "@types/mv": "2.1.4",
-    "@types/ncp": "2.0.8",
-    "@types/node": "24.12.4",
+    "@types/mime-types": "3.0.1",
+    "@types/morgan": "1.9.10",
+    "@types/node": "24.19.1",
+    "@types/picomatch": "4.0.3",
     "@types/pluralize": "0.0.33",
-    "@types/semver": "7.7.1",
-    "@types/serve-favicon": "2.5.7",
+    "@types/semver": "7.8.0",
     "@types/shell-quote": "1.7.5",
-    "@types/sinon": "21.0.1",
-    "@types/sinon-chai": "4.0.0",
+    "@types/sinon": "22.0.0",
     "@types/which": "3.0.4",
     "@types/ws": "8.18.1",
-    "@types/xmldom": "0.1.34",
     "@types/yargs": "17.0.35",
-    "asyncbox": "6.3.0",
-    "chai": "6.2.2",
-    "chai-as-promised": "8.0.2",
-    "conventional-changelog-conventionalcommits": "7.0.2",
+    "asyncbox": "6.4.3",
+    "conventional-changelog-conventionalcommits": "9.3.1",
     "cpy-cli": "7.0.0",
     "cross-env": "10.1.0",
-    "eslint": "10.4.0",
-    "eslint-config-prettier": "10.1.8",
-    "eslint-import-resolver-typescript": "4.4.4",
-    "eslint-plugin-import-x": "4.16.2",
-    "eslint-plugin-mocha": "11.3.0",
-    "eslint-plugin-n": "18.0.1",
-    "eslint-plugin-promise": "7.3.0",
-    "finalhandler": "2.1.1",
-    "get-port": "7.2.0",
-    "json-schema-to-typescript": "15.0.4",
-    "lerna": "9.0.7",
-    "log-symbols": "7.0.1",
-    "midnight-smoker": "8.0.0",
-    "mjpeg-consumer": "2.0.0",
-    "mjpeg-server": "0.3.1",
-    "mocha": "11.7.6",
-    "npm-run-all2": "9.0.1",
-    "prettier": "3.8.3",
-    "rewiremock": "3.14.6",
+    "json-schema-to-typescript": "16.0.0",
+    "lerna": "10.0.1",
+    "npm-run-all2": "9.0.3",
     "rimraf": "6.1.3",
-    "serve-static": "2.2.1",
-    "sinon": "22.0.0",
-    "sinon-chai": "4.0.1",
-    "sync-monorepo-packages": "1.0.2",
-    "teen_process": "4.1.3",
-    "ts-node": "10.9.2",
+    "sinon": "22.1.0",
+    "teen_process": "4.2.1",
     "tsd": "0.33.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.60.0",
-    "webdriverio": "9.27.2",
-    "ws": "8.21.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
-    "npm": ">=10"
-  },
-  "publishConfig": {
-    "access": "public"
+    "webdriverio": "9.32.0",
+    "ws": "8.22.0"
   },
   "overrides": {
     "@sidvind/better-ajv-errors": {
@@ -167,6 +119,10 @@
     "ajv-formats": {
       "ajv": "8.20.0"
     },
-    "http-cache-semantics": "4.2.0"
+    "http-cache-semantics": "4.3.0"
+  },
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0",
+    "npm": ">=10"
   }
 }

packages/appium/CHANGELOG.md

@@ -3,6 +3,220 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.0.0-beta.4](https://github.com/appium/appium/compare/appium@4.0.0-beta.3...appium@4.0.0-beta.4) (2026-10-09)
+
+### ⚠ BREAKING CHANGES
+
+* **appium:** Replace the `windows` known-driver shortcut with `wincore` pointing to appium-wincore-driver instead of the obsolete appium-windows-driver
+
+### Features
+
+* **appium:** replace obsolete windows driver with appium-wincore-driver  ([#22917](https://github.com/appium/appium/issues/22917)) ([7544a10](https://github.com/appium/appium/commit/7544a1008d96f44f19499500314b6ae21d54d4f2))
+
+### Bug Fixes
+
+* **appium:** prevent recursion when logging the first BiDi event of a method ([#22897](https://github.com/appium/appium/issues/22897)) ([e230727](https://github.com/appium/appium/commit/e230727090f24a3c777c88de9d43d83ff94ea97d))
+* centralize URL hostname formatting and bracket IPv6 hosts ([#22914](https://github.com/appium/appium/issues/22914)) ([c5ddcef](https://github.com/appium/appium/commit/c5ddcef8940dfa5fac8d180bed65dc80ba8fafab))
+* tune wincore driver integration ([#22922](https://github.com/appium/appium/issues/22922)) ([9f8455e](https://github.com/appium/appium/commit/9f8455e1973e97c8a6451a9291de741dadfed775))
+
+
+## [4.0.0-beta.3](https://github.com/appium/appium/compare/appium@4.0.0-beta.2...appium@4.0.0-beta.3) (2026-10-05)
+
+### Features
+
+* **universal-xml-plugin:** add execute methods to toggle translation ([#22862](https://github.com/appium/appium/issues/22862)) ([b95aaac](https://github.com/appium/appium/commit/b95aaac60bed065ce0a0d1e4f7baf9c5e60572b1)), closes [#21630](https://github.com/appium/appium/issues/21630)
+
+### Bug Fixes
+
+* **appium:** apply initial settings from selected capabilities ([#22882](https://github.com/appium/appium/issues/22882)) ([95c0461](https://github.com/appium/appium/commit/95c04611e7d1cd8acfa4c6ce51276899938588d3))
+* **appium:** bracket IPv6 hosts in BiDi websocket URLs ([#22872](https://github.com/appium/appium/issues/22872)) ([3875344](https://github.com/appium/appium/commit/3875344e111dc23e4c99310ad918b769dbb38927))
+* **appium:** close bidi sockets when a session ends unexpectedly ([#22854](https://github.com/appium/appium/issues/22854)) ([3cdc69b](https://github.com/appium/appium/commit/3cdc69b198e85607b4f35a5b3f57b542b0ae9b80))
+* **appium:** detect project homes with prerelease dependencies ([#22871](https://github.com/appium/appium/issues/22871)) ([11d9904](https://github.com/appium/appium/commit/11d9904166c9e692e6fa8491acfce4ac892c1a8e))
+* **appium:** do not crash when a proxied bidi socket closes without a sendable code ([#22835](https://github.com/appium/appium/issues/22835)) ([66ab396](https://github.com/appium/appium/commit/66ab396a71c419f1fb456b8a1ddf23bc3491baf8))
+* **appium:** explain manual recovery after manifest lock timeouts ([#22875](https://github.com/appium/appium/issues/22875)) ([b9c020c](https://github.com/appium/appium/commit/b9c020c6ebf88643ffe6b6d5e302b43673bbb028))
+* **appium:** import extensions through escaped file URLs ([#22884](https://github.com/appium/appium/issues/22884)) ([8312252](https://github.com/appium/appium/commit/83122525db72f2d6ff06e27cd3da5269318be3a8))
+* **appium:** match global and module BiDi event subscriptions ([#22883](https://github.com/appium/appium/issues/22883)) ([879873b](https://github.com/appium/appium/commit/879873bad5669c9b264f3fcb60d05562f6ca3b1e))
+* **appium:** resolve default extension export conditions ([#22885](https://github.com/appium/appium/issues/22885)) ([3188c9f](https://github.com/appium/appium/commit/3188c9fbab17c16192a6e75ff62f69f4d844be8f))
+* **appium:** roll back sessions when initialization fails ([#22873](https://github.com/appium/appium/issues/22873)) ([f24e704](https://github.com/appium/appium/commit/f24e7046eb2815822f655a644aee9786d90fd4e8))
+* **appium:** start idle timeout after session initialization ([#22881](https://github.com/appium/appium/issues/22881)) ([e37f1c1](https://github.com/appium/appium/commit/e37f1c158394617bcaa474da25f1650b9b24ebd1))
+* **base-driver:** track and remove BiDi subscriptions by ID ([#22876](https://github.com/appium/appium/issues/22876)) ([b791915](https://github.com/appium/appium/commit/b791915ffcf322e1cc84dbde606be55d34f020b3))
+* use native ESM entrypoint detection ([#22868](https://github.com/appium/appium/issues/22868)) ([e391bb2](https://github.com/appium/appium/commit/e391bb249fec5f700a6d63a747ff921a80689fb5))
+
+
+## [4.0.0-beta.2](https://github.com/appium/appium/compare/appium@4.0.0-beta.1...appium@4.0.0-beta.2) (2026-09-27)
+
+### ⚠ BREAKING CHANGES
+
+* **base-driver:** @appium/base-driver no longer exports server, normalizeBasePath, configureServer, ServerOpts, ConfigureServerOpts, ConfigureHttpOpts, or StartServerOpts, and no longer depends on express/morgan/body-parser/ method-override/path-to-regexp. Use the new @appium/http-server package instead.
+* **base-driver:** appium/driver.js and driver.d.ts no longer re-export server/normalizeBasePath/configureServer/ServerOpts (or their types), and no longer use a blanket export *. Import from @appium/http-server directly if you were relying on this undocumented path.
+
+### Features
+
+* **appium:** accept package names for installed extension commands ([#22747](https://github.com/appium/appium/issues/22747)) ([#22812](https://github.com/appium/appium/issues/22812)) ([b7356ee](https://github.com/appium/appium/commit/b7356ee53eec3e322707eef0d2bd37976a47cfd2))
+
+### Bug Fixes
+
+* **appium:** release the manifest lock before errAndQuit exits ([#22821](https://github.com/appium/appium/issues/22821)) ([dc0568b](https://github.com/appium/appium/commit/dc0568bc658961f5d6a28fb955d8092d51cf9523))
+* **base-driver:** carry proxy req via AsyncLocalStorage instead of args ([#22799](https://github.com/appium/appium/issues/22799)) ([2596da0](https://github.com/appium/appium/commit/2596da02d201d7e5fbfd24cf9dd2801302f8abc7))
+* **support:** narrow fs.glob overload for default withFileTypes/lazy ([#22795](https://github.com/appium/appium/issues/22795)) ([09a04f4](https://github.com/appium/appium/commit/09a04f48831e17b9b7f3b8dc0a72f0df5096ae51))
+
+### Code Refactoring
+
+* **base-driver:** extract the HTTP/Express server into @appium/http-server ([#22800](https://github.com/appium/appium/issues/22800)) ([225a1c6](https://github.com/appium/appium/commit/225a1c6d9d24fa2696699d4b61436a49b847d666))
+
+
+## [4.0.0-beta.1](https://github.com/appium/appium/compare/appium@4.0.0-beta.0...appium@4.0.0-beta.1) (2026-09-19)
+
+### Bug Fixes
+
+* **deps:** catch up peerDependencies to published beta.0; drop bootstrap_packages ([#22793](https://github.com/appium/appium/issues/22793)) ([b09efc3](https://github.com/appium/appium/commit/b09efc31c6967bbcf2c4314db9d2a0b6454fa8fb))
+
+
+## [4.0.0-beta.0](https://github.com/appium/appium/compare/appium@3.7.0...appium@4.0.0-beta.0) (2026-09-19)
+
+### ⚠ BREAKING CHANGES
+
+* **base-driver:** align timeouts endpoints closer to W3C standard (#22776)
+* users relying on the implicit debug default for console/file logs will now see info-level output unless they explicitly pass --log-level debug.
+* **support:** Any script or tool that consumes Appium CLI output (driver/plugin list/install/update, doctor, etc.) and relies on the previous stream layout will need to be updated. Previously, non-JSON human-readable output (info/success/warning messages) was written to STDERR, with STDOUT reserved almost exclusively for --json output. Now that output goes to STDOUT, and only actual errors go to STDERR.
+* **support:** Scripts that discarded STDOUT (1>/dev/null) to suppress "chatter" while relying on STDERR for status text will now see that text on STDOUT instead.
+* **support:** Scripts that captured STDERR to detect/log informational or success messages will no longer see them there — only genuine errors will appear on STDERR. --json output and error behavior are unaffected: --json continues to write clean JSON to STDOUT only, and errors continue to go to STDERR.
+* **support:** @appium/logger's Log class changes its default output stream from STDERR to STDOUT for all levels except error, and adds an errorStream/stderrLevel pair of properties. Any code that set .stream on a Log instance expecting it to capture all levels (including error) will now need to also set .errorStream to the same target.
+* **base-driver:** @appium/base-driver's default export (BaseDriver) and @appium/base-driver's basedriver/helpers.js default export are removed; use the named exports instead. The appium/driver.js and driver.d.ts re-exports of the default are removed accordingly.
+* **base-driver:** BaseDriver.reset() is removed; it was unused, not part of any protocol route or the Driver interface, and had no callers in this monorepo or any driver package that was checked.
+* **base-driver:** BaseDriver's constructor is removed in favor of inherited DriverCore construction; opts is no longer a required constructor argument (it now defaults to {}, matching DriverCore).
+* **support:** @appium/support's fs.glob option shape changed from the glob package's GlobOptions to a smaller, @appium/support-owned GlobOptions interface. Supported fields: cwd, withFileTypes, absolute, lazy. Options like nodir/ignore/nocase are no longer supported directly — callers needing directory filtering can pass withFileTypes: true and filter on .isFile()/.isDirectory(); callers needing path exclusion can filter the returned array by pattern.
+* **appium:** The --allow-cors CLI flag and allow-cors config file property have been removed. Use --allow-insecure=*:cors (or --relaxed-security, optionally overridden with --deny-insecure=*:cors) instead.
+* **base-driver:** ISessionHandler.createSession (@appium/types) and LegacyCreateSessionArgs — overload and type deleted, single-argument signature only.
+* **base-driver:** BaseDriver.createSession and AppiumDriver.createSession — collapsed to the single-argument mplementation; capability validation now checks the one argument directly instead of scanning three positions for the first W3C-shaped value.
+* **base-driver:** FakeDriver.createSession (and the base-driver e2e test double) — overrides updated to match.
+* **base-driver:** RelaxedCapsPlugin.createSession — this plugin existed specifically to normalize capabilities across the (now-gone) three positions; its hook is simplified to a single caps argument.
+* **base-driver:** POST /session wire route (w3c.ts) — payloadParams.optional no longer sends capabilities three times into the command args.
+* **base-driver:** BaseDriver.getSession, ISessionHandler.getSession, and the GET /session/:sessionId JSONWP route are gone. Use getAppiumSessionCapabilities to retrieve session capabilities and EventCommands.getLogEvents to retrieve event history instead.
+* **base-driver:** The appium:eventTimings capability is removed; it only ever controlled whether getSession's response was decorated with event history, which getLogEvents already exposes unconditionally.
+* **support:** move npm-related helpers into appium package (#22721)
+* **logger:** @appium/logger and @appium/support no longer export a default log — import the named log export instead.
+* **logger:** AppiumLogger#errorAndThrow has been removed; use errorWithException instead.
+* **logger:** Logger#enableProgress, disableProgress, progressEnabled, enableUnicode, disableUnicode have been removed; they were already permanently disabled no-ops.
+* **base-plugin:** Plugin#logger has been removed; use Plugin#log instead.
+* **base-plugin:** @appium/base-plugin no longer exports BasePlugin as the default export; use the named BasePlugin export.
+* Core.driverData, DriverData, and the driverData parameter on ISessionHandler.createSession/deleteSession are gone. Any driver overriding get driverData() or relying on the umbrella driver passing sibling-session data into createSession/deleteSession needs to migrate off this mechanism.
+* FakeDriver no longer supports the uniqueApp capability.
+* **support:** npm.installPackage now takes a hasAppiumDependency boolean computed by the caller instead of importing the check itself, avoiding a support -> appium dependency.
+* **support:** The env export is removed from @appium/support.
+* the minimum supported Node.js engine is set to ^22.22.2 || ^24.15.0 || >=26.0.0
+* **base-driver:** @appium/base-driver no longer exports statusCodes or getSummaryByCode (the jsonwp-status module was removed).
+* **base-driver:** errorFromMJSONWPStatusCode (aliased as errorFromCode) has been removed; use errorFromW3CJsonCode for W3C error-signature mapping.
+* **base-driver:** ProtocolError instances no longer have a jsonwpCode property.
+* **base-driver:** WebDriverProxy (formerly JWProxy) no longer proxies to or interprets responses from downstream servers speaking the legacy MJSONWP protocol; the ProtocolConverter class, COMMAND_URLS_CONFLICTS, and the downstreamProtocol getter/setter have been removed. Downstream automation servers must speak W3C WebDriver.
+* **base-driver:** Responses no longer duplicate element references under the legacy ELEMENT key; only the W3C element-6066-11e4-a52e-4f735466cecf key is present. The MJSONWP_ELEMENT_KEY constant has been removed.
+* **base-driver:** determineProtocol has been removed, and drivers can no longer produce the legacy {sessionId, status, value} response shape; all responses are now W3C-shaped regardless of how the client formatted its createSession capabilities.
+* **base-driver:** DriverCore#setProtocolMJSONWP() has been removed.
+* **base-driver:** The deprecated JWProxy export has been removed; use WebDriverProxy instead. Its source also moved from lib/jsonwp-proxy/proxy.js to lib/wd-proxy/proxy.js.
+* **base-driver:** DriverCore#isMjsonwpProtocol() has been removed.
+* **support:** The following @appium/support exports have been removed: process (getProcessIds, killProcess), mkdirp, imageUtil (requireSharp, cropBase64Image), mjpeg (MJpegStream), net's FTP upload
+support (FtpUploadOptions, NotHttpUploadOptions; uploadFile only supports http/https now), util's uuidV1/uuidV3/uuidV5/localIp/cancellableDelay/multiResolve, and fs's readPackageJsonFrom/findRoot/ F_OK/R_OK/W_OK/X_OK.
+* **appium:** The --nodeconfig server argument and the server.nodeconfig config file property no longer exist. Users who need to register with a Selenium Grid should use the Grid 4 relay feature instead (see the Grid guide).
+* **base-driver:** TLS-enabled Appium servers no longer negotiate SPDY/HTTP2 (spdy/2, spdy/3, spdy/3.1, h2) via ALPN; connections are now served as plain HTTPS (HTTP/1.1) using Node's native https module. Clients relying on SPDY or HTTP/2 multiplexing against Appium's TLS listener must switch to HTTP/1.1.
+* **appium:** `npm install -g appium --drivers=... --plugins=...` no longer installs extensions automatically. Use `appium driver/plugin install` or add extensions to package.json instead.
+* require('@appium/support') no longer works; consumers must import it instead.
+* require('@appium/base-driver') no longer works; drivers extending BaseDriver via require must switch to import.
+* require('@appium/base-plugin') no longer works; plugins extending BasePlugin via require must switch to import.
+* require('appium') no longer works; plugins extending the package via require must switch to import.
+* require('@appium/fake-plugin') no longer works; consumers must import it instead.
+* require('@appium/fake-driver') no longer works; consumers must import it instead.
+* require('@appium/types') no longer works; consumers must import it instead.
+* require('@appium/logger') no longer works; consumers must import it instead.
+* require('@appium/schema') no longer works; consumers must import it instead.
+
+### Features
+
+* **appium:** add --app-url-rules server arg to restrict remote app URLs ([#22753](https://github.com/appium/appium/issues/22753)) ([0b104f6](https://github.com/appium/appium/commit/0b104f6bf9b7180b111df40fd6a15b26d649eabd))
+* **appium:** remove postinstall autoinstall-extensions script ([#22675](https://github.com/appium/appium/issues/22675)) ([cd0d8f1](https://github.com/appium/appium/commit/cd0d8f14e9d5906ecd1b438038a7f67f74f742fc))
+* **appium:** remove Selenium Grid 3 support ([#22677](https://github.com/appium/appium/issues/22677)) ([8fcdcb3](https://github.com/appium/appium/commit/8fcdcb30b07c1ee582256fbef3538d6a3ceea5f2))
+* **appium:** replace --allow-cors flag with --allow-insecure=*:cors ([#22731](https://github.com/appium/appium/issues/22731)) ([926a0a5](https://github.com/appium/appium/commit/926a0a594935a6cf2e7375eb174eeb15af964f12))
+* **appium:** validate extension manifests and extensions.yaml via ajv ([#22732](https://github.com/appium/appium/issues/22732)) ([8840f9f](https://github.com/appium/appium/commit/8840f9f9322b63bc8940c390b8230f1e5306fa62))
+* backport diff from master ([#22749](https://github.com/appium/appium/issues/22749)) ([6323df1](https://github.com/appium/appium/commit/6323df1d7354f85cc631508f5cb6a3e35270d4bd))
+* **base-driver:** add definitions for all WebDriver BiDi commands ([#22770](https://github.com/appium/appium/issues/22770)) ([ac01aa8](https://github.com/appium/appium/commit/ac01aa83ad73982eea48f856dfc0249b4a26e395))
+* **base-driver:** align timeouts endpoints closer to W3C standard ([#22776](https://github.com/appium/appium/issues/22776)) ([93115d1](https://github.com/appium/appium/commit/93115d195773b011306ffb2e6d7d6cc935df0148))
+* **base-driver:** remove legacy (M)JSONWP protocol support ([#22681](https://github.com/appium/appium/issues/22681)) ([0b83e77](https://github.com/appium/appium/commit/0b83e77e7a1c24a885d9895a99db30281cf4acea))
+* **base-driver:** replace spdy with native https transport ([#22676](https://github.com/appium/appium/issues/22676)) ([ec7de47](https://github.com/appium/appium/commit/ec7de4768fdd8dde9d28db6fc2dfd63be45fd4c6))
+* bump minimum supported Node.js engine to ^22.22.2 || ^24.15.0 || >=26.0.0 ([#22685](https://github.com/appium/appium/issues/22685)) ([9f4a11e](https://github.com/appium/appium/commit/9f4a11e7190290986d01743557e90e6e44f87638))
+* Change the default log level to `info` ([#22756](https://github.com/appium/appium/issues/22756)) ([5e644a3](https://github.com/appium/appium/commit/5e644a392fbf11e2ca985408853d7f51aa85be17))
+* convert remaining monorepo packages to ESM-only ([#22674](https://github.com/appium/appium/issues/22674)) ([3516e50](https://github.com/appium/appium/commit/3516e50ce6d022f4c0dc539071c593bf2983325f))
+* **support:** move env/APPIUM_HOME resolution into appium package ([#22708](https://github.com/appium/appium/issues/22708)) ([8db8e57](https://github.com/appium/appium/commit/8db8e5748e26a7150cacbea09ba3ec52c5ce3fc0))
+* **support:** remove deprecated APIs ([#22678](https://github.com/appium/appium/issues/22678)) ([e8ee716](https://github.com/appium/appium/commit/e8ee71685b4c21116e61c88fd8d2f0e39fac2edb))
+* **types:** check execute method params against the command signature ([#22754](https://github.com/appium/appium/issues/22754)) ([b25fc20](https://github.com/appium/appium/commit/b25fc20c51a191c33695c1c71fbf129de834b52d))
+
+### Bug Fixes
+
+* address code review cleanups (plist, env memoize, test reuse) ([#22740](https://github.com/appium/appium/issues/22740)) ([0df8834](https://github.com/appium/appium/commit/0df883463812d57d44a0d6d80e9b88f124361934))
+* Address several TODOs ([#22762](https://github.com/appium/appium/issues/22762)) ([d6ef7e3](https://github.com/appium/appium/commit/d6ef7e3f1240f161df622c850aea06637f9d1078))
+* adjust deprecated JSONWP/MJSONWP routes ([#22763](https://github.com/appium/appium/issues/22763)) ([b129cbb](https://github.com/appium/appium/commit/b129cbbcd55656ae7f33b80b4b52719eb5179509))
+* **appium:** lock the extension manifest while driver/plugin commands run ([#22767](https://github.com/appium/appium/issues/22767)) ([a73644f](https://github.com/appium/appium/commit/a73644fb4f4e7b0363117ac1262d7018094b42ff))
+* **base-driver:** clean up aborted session creation ([#22733](https://github.com/appium/appium/issues/22733)) ([33d866e](https://github.com/appium/appium/commit/33d866e57506e1546aa4870dde75f7209be107bc))
+* declare dependencies that were only resolving via hoisting ([#22758](https://github.com/appium/appium/issues/22758)) ([bcf1c57](https://github.com/appium/appium/commit/bcf1c579997b8dbb8292b1a77583aeef40b11ba4))
+* **support:** route non-error CLI console output to stdout ([#22742](https://github.com/appium/appium/issues/22742)) ([4eb4d7f](https://github.com/appium/appium/commit/4eb4d7f317a685d681b6cf4e25c15b617a8cc7df))
+
+### Code Refactoring
+
+* **base-driver:** remove deprecated getSession command ([#22725](https://github.com/appium/appium/issues/22725)) ([f71d980](https://github.com/appium/appium/commit/f71d980779d23e9a19d33285646fad128eae4917))
+* **base-driver:** remove deprecated multi-argument createSession overload ([#22730](https://github.com/appium/appium/issues/22730)) ([db72249](https://github.com/appium/appium/commit/db722498739ae7fe1deef1b98e02d04b455a4f70))
+* **base-driver:** replace command mixin with explicit named exports ([#22741](https://github.com/appium/appium/issues/22741)) ([506bfee](https://github.com/appium/appium/commit/506bfeeb9aa15c0dd1f481868d347cb9b0d37f86))
+* **base-plugin:** remove deprecated legacy logger and default export ([#22718](https://github.com/appium/appium/issues/22718)) ([62db5f0](https://github.com/appium/appium/commit/62db5f0b20c496b495ce27d490453861ddefb259))
+* **logger:** remove default exports and dead logging APIs ([#22719](https://github.com/appium/appium/issues/22719)) ([fe24f52](https://github.com/appium/appium/commit/fe24f527a4412ed86c7b5e5afe0c6e26dc569e6b))
+* remove deprecated driverData mechanism ([#22716](https://github.com/appium/appium/issues/22716)) ([ef8a8e1](https://github.com/appium/appium/commit/ef8a8e1934bfdc9699c2b9a7eca3e2201b4b9f93))
+* **support:** move npm-related helpers into appium package ([#22721](https://github.com/appium/appium/issues/22721)) ([d82d496](https://github.com/appium/appium/commit/d82d496f9e80d6628abface3b623601a6f9791f9))
+* **support:** replace glob package with native node:fs glob ([#22735](https://github.com/appium/appium/issues/22735)) ([add1615](https://github.com/appium/appium/commit/add161560701ac7fb2bc372ddefd9317146fbae8))
+
+
+## [3.7.0](https://github.com/appium/appium/compare/appium@3.6.0...appium@3.7.0) (2026-08-24)
+
+### Features
+
+* **base-driver:** add httpServer.frontRouter for global extension middleware ([#22632](https://github.com/appium/appium/issues/22632)) ([f06226b](https://github.com/appium/appium/commit/f06226b7bb2fb7ee2f3a61833f4a1d7777d4ef21))
+* **storage-plugin:** Add route aliases ([#22558](https://github.com/appium/appium/issues/22558)) ([a551c38](https://github.com/appium/appium/commit/a551c3817156bbc7e06793227643a2d11c0c0259))
+
+### Bug Fixes
+
+* **appium:** load @appium/docutils dynamically in docs build script ([#22584](https://github.com/appium/appium/issues/22584)) ([2c0f3fd](https://github.com/appium/appium/commit/2c0f3fd9e319c3bc774bdd2a65148da11094c87c))
+* **appium:** parse --webhook as a URI instead of host:port ([#22635](https://github.com/appium/appium/issues/22635)) ([c35a12a](https://github.com/appium/appium/commit/c35a12a51d30fe311ef96ebe386cd9c5540e3927))
+* **support:** do not treat a sibling folder as a subpath of the root ([#22586](https://github.com/appium/appium/issues/22586)) ([3a80498](https://github.com/appium/appium/commit/3a8049887dc673a6658c3821a2882e0145c3aa86))
+
+
+## [3.6.0](https://github.com/appium/appium/compare/appium@3.5.2...appium@3.6.0) (2026-07-25)
+
+
+### Features
+
+* **appium:** add --allow-unknown-args to tolerate unrecognized server CLI arguments ([#22477](https://github.com/appium/appium/issues/22477)) ([f943fab](https://github.com/appium/appium/commit/f943fab1411826212cfb174e3847e610c25f37b7))
+
+
+### Bug Fixes
+
+* **appium:** Duplicated module import ([#22519](https://github.com/appium/appium/issues/22519)) ([154ea18](https://github.com/appium/appium/commit/154ea1825281335569f0d6952db527135c75e153))
+* typescript config ([#22540](https://github.com/appium/appium/issues/22540)) ([ea6a2e1](https://github.com/appium/appium/commit/ea6a2e117f56c1d7ff459378700494407c51608e))
+* Typescript references ([#22458](https://github.com/appium/appium/issues/22458)) ([fd70da7](https://github.com/appium/appium/commit/fd70da7ab407bf1f6fec8a3576b9a33f0aef9b69))
+
+
+
+## [3.5.2](https://github.com/appium/appium/compare/appium@3.5.1...appium@3.5.2) (2026-06-18)
+
+**Note:** Version bump only for package appium
+
+
+
+
+
+## [3.5.1](https://github.com/appium/appium/compare/appium@3.5.0...appium@3.5.1) (2026-06-18)
+
+
+### Bug Fixes
+
+* **storage-plugin:** add fs.sanitizeName for the delete request as well ([#22362](https://github.com/appium/appium/issues/22362)) ([5fee017](https://github.com/appium/appium/commit/5fee01752f2782e96fbe64fd13520b433d4a7535))
+
+
+
 ## [3.5.0](https://github.com/appium/appium/compare/appium@3.4.2...appium@3.5.0) (2026-05-31)
 
 

packages/appium/docs/base-mkdocs.yml

@@ -16,6 +16,8 @@ plugins:
   blog:
     enabled: true
     post_excerpt: required
+  mike:
+    canonical_version: 'latest'
   redirects:
     redirect_maps:
       'intro/requirements.md': 'quickstart/requirements.md'

packages/appium/docs/en/blog/.authors.yml

@@ -17,3 +17,8 @@ authors:
     avatar: 'https://avatars.githubusercontent.com/u/4045041?v=4'
     slug: 'sai'
     url: 'https://saikrishna.tech'
+  mykola:
+    name: 'Mykola Mokhnach'
+    description: 'Appium Core Maintainer'
+    avatar: https://avatars.githubusercontent.com/u/7767781?v=4
+    slug: 'mykola'

packages/appium/docs/en/blog/posts/announcing-lambdatest-as-development-partner.md

@@ -8,11 +8,13 @@ date: 2025-11-25
 # Announcing LambdaTest as Appium's Newest Development Partner
 
 As part of our ongoing effort to recognize organizations that meaningfully support the Appium project through dedicated maintainer time, we are excited to welcome our newest Development Partner: LambdaTest!
-LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
-This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
 
 <!-- more -->
 
+LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
+
+This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
+
 <div style="text-align:center;width:100%">
   <a href="https://lambdatest.com/?utm_source=appium.io&utm_medium=organic&utm_campaign=june_25&utm_term=sk&utm_content=webpage">
     <img src="/docs/en/latest/assets/images/sponsor-logo-lambdatest-dark.png#only-dark" width="300" />
@@ -22,15 +24,19 @@ This kind of hands-on contribution is crucial for ensuring Appium continues to e
 
 
 LambdaTest engineers are already contributing actively across several key Appium repositories. Their current focus includes:
- **appium-mcp** – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
- **appium-remote-xpc** – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
- **appium-tun-tap** – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
+
+* [`appium-mcp`](https://github.com/appium/appium-mcp) – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
+* [`appium-ios-remotexpc`](https://github.com/appium/appium-ios-remotexpc) – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
+* [`appium-ios-tuntap`](https://github.com/appium/appium-ios-tuntap) – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
 
 These contributions strengthen critical infrastructure within the Appium ecosystem and demonstrate LambdaTest's commitment to deep technical involvement in the project's evolution.
-About LambdaTest
+
+**About LambdaTest**
 
 LambdaTest’s platform already serves a massive community of Appium users. As a GenAI-powered Quality Engineering Platform, they provide a full-stack testing cloud with 10,000+ real mobile devices and 3,000+ browsers.
+
 Beyond standard infrastructure, they are pushing the boundaries of test execution with AI-native test management and next-generation agents like KaneAI. By supporting Appium alongside Selenium, Playwright, and other major frameworks, LambdaTest helps teams orchestrate intelligent automation at cloud scale.
 
 LambdaTest will continue contributing people, code, and development expertise to strengthen Appium's core functionality. Their commitment represents a significant investment into the future of the framework, and we're thrilled to have them collaborating with us at this deeper level.
+
 The Appium project is proud to recognize LambdaTest as our newest official Development Partner. We can't wait to see what we'll build together!

packages/appium/docs/en/blog/posts/announcing-watchos-simulator-support.md

@@ -0,0 +1,38 @@
+---
+authors:
+  - mykola
+date: 2026-09-01
+---
+
+# Announcing watchOS Simulator Support in the XCUITest Driver
+
+We’re excited to announce that the XCUITest driver now supports automation of watchOS apps — a
+platform that’s been on Appium’s requested list for a long time.
+
+<!-- more -->
+
+In order to automate watchOS, you'll need the following:
+
+* XCUITest driver version 12.6.0 or later (WebDriverAgent 16.5.0 or later)
+* Xcode 15.4 or later
+* watchOS 10 or later
+
+Important to note: ^^the driver currently only works with simulators — real devices are not
+compatible.^^
+
+The good news: automating a watchOS app looks just like automating any other iOS/iPadOS app. The
+standard use-cases of finding and clicking on elements, retrieving the page source, using the
+Appium Inspector — all work as usual. The one exception here is standard W3C gesture/touch actions
+(tap/swipe via the Actions API), which are not supported.
+
+On top of that, a few watchOS-specific extensions are available:
+
+- `mobile: pressButton` — press the Digital Crown or Action button
+- `mobile: rotateDigitalCrown` — rotate the Digital Crown (since driver version 12.7.0)
+- `mobile: performHandGesture` — perform double-tap or wrist flick hand gestures (since driver
+  version 12.7.0)
+
+For full setup instructions, capabilities, and limitations, check out the
+[watchOS guide](https://appium.github.io/appium-xcuitest-driver/latest/guides/watchos/).
+
+Happy testing!

packages/appium/docs/en/contributing/index.md

@@ -103,6 +103,27 @@ export APPIUM_WORKSPACE=@appium/base-driver
 npm run test:unit -w $APPIUM_WORKSPACE
 ```
 
+### Code Style
+
+#### JSDoc
+
+Add concise JSDoc to all public class methods and exported functions.
+
+#### Module Ordering
+
+Place exported functions and classes before non-exported functions and classes in each module.
+This rule does not apply to constants or variables.
+
+#### Class Member Ordering
+
+When adding or moving class methods, follow these conventions:
+
+- Order methods by visibility: public → protected → private. Methods without an explicit visibility
+  modifier belong to the public group.
+- Place private helper methods at the end of the class.
+- Preserve existing order within each visibility group.
+- Before finishing, check the ordering of methods you added or moved.
+
 ### Documentation
 
 The documentation for this project is [available in the project repository itself](https://github.com/appium/appium/tree/master/packages/appium/docs).

packages/appium/docs/en/developing/build-drivers.md

@@ -222,18 +222,13 @@ So you'll probably end up overriding `createSession`. You can do so by defining
 driver:
 
 ```js
-async createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData) {
-    const [sessionId, caps] = super.createSession(w3cCaps);
+async createSession(w3cCaps) {
+    const [sessionId, caps] = await super.createSession(w3cCaps);
     // do your own stuff here
     return [sessionId, caps];
 }
 ```
 
-For legacy reasons, your function will receive old-style JSON Wire Protocol desired and required
-caps as the first two arguments. Given that the old protocol isn't supported anymore and clients
-have all been updated, you can instead only rely on the `w3cCaps` parameter. (For a discussion
-about what `otherDriverData` is about, see the section below on concurrent drivers).
-
 You'll want to make sure to call `super.createSession` in order to get the session ID as well as
 the processed capabilities (note that capabilities are also set on `this.caps`; modifying `caps`
 locally here would have no effect other than changing what the user sees in the create session
@@ -520,14 +515,13 @@ route, then the route will not be proxied and instead will be handled by your dr
 example, we are avoiding proxying all `POST` routes that have the `appium` prefix.
 
 Next, we have to set up the proxying itself. The way to do this is to use a special class from
-Appium called `JWProxy`. (The name means "JSON Wire Proxy" and is related to a legacy
-implementation of the protocol). You'll want to create a `JWProxy` object using the details required to
-connect to the remote server:
+Appium called `WebDriverProxy`. You'll want to create a `WebDriverProxy` object using the details
+required to connect to the remote server:
 
 ```js
-// import {JWProxy} from 'appium/driver';
+// import {WebDriverProxy} from 'appium/driver';
 
-const proxy = new JWProxy({
+const proxy = new WebDriverProxy({
     server: 'remote.server',
     port: 1234,
     base: '/',
@@ -539,8 +533,8 @@ this.proxyCommand = proxy.command.bind(proxy);
 
 Here we are creating a proxy object and assigning some of its methods to `this` under the names
 `proxyReqRes` and `proxyCommand`. This is required for Appium to use the proxy, so don't forget
-this step! The `JWProxy` has a variety of other options which you can check out in the source code,
-as well. (TODO: publish options as API docs and link here).
+this step! The `WebDriverProxy` has a variety of other options [which you can check out in the
+source code as well.](https://github.com/appium/appium/blob/master/packages/base-driver/lib/wd-proxy/proxy.ts)
 
 Finally, we need a way to tell Appium when the proxy is active. For your driver it might always
 be active, or it might only be active when in a certain context. You can define the logic as an
@@ -720,6 +714,12 @@ A couple notes about this system:
    mode!
 1. The `executeMethod` helper will reject with an error if a script name doesn't match one of the
    script names defined as a command in `executeMethodMap`, or if there are missing parameters.
+1. If your driver is written in TypeScript, declare the map `as const satisfies
+   ExecuteMethodMap<MyDriver>` (with `ExecuteMethodMap` imported from `@appium/types`). The
+   compiler then checks that each `command` names a method of your driver, and that the
+   `required`/`optional` params are consistent with that method's signature: the method must not
+   require a parameter which is listed as `optional` (or not listed at all), and must accept all
+   of the listed parameters.
 
 One of the nice things about the Execute Method strategy is that methods implemented in this way
 will be available via the classic or BiDi interfaces (since they will result in the same Appium
@@ -794,44 +794,32 @@ that multiple simultaneous sessions don't use the same resources:
 
 1. Have your users specify resource IDs via capabilities (`appium:driverPort` etc)
 1. Just always use free resources (find a new random port for each session)
-1. Have each driver express what resources it is using, then examine currently-used resources from
-   other drivers when a new session begins.
+1. Have each running instance of your driver publish and subscribe to messages on a shared IPC
+   channel, so sessions can coordinate directly with one another.
 
-To support this third strategy, you can implement `get driverData` in your driver to return what
-sorts of resources your driver is currently using, for example:
-
-```js
-get driverData() {
-  return {specialPort: 1234, specialFile: /path/to/file}
-}
-```
-
-Now, when a new session is started on your driver, the `driverData` response from any other
-simultaneously running drivers (of the same type) will also be included, as the last parameter of
-the `createSession` method:
-
-```js
-async createSession(jwpCaps, reqCaps, w3cCaps, driverData)
-```
-
-You can dig into this `driverData` array to see what resources other drivers are using to help
-determine which ones you want to use for this particular session.
+The per-session IPC channel described in [Send messages to plugins running on the same
+session](#send-messages-to-plugins-running-on-the-same-session) is isolated per session, so it
+can't be used for this: it doesn't let you talk to *other* sessions of your driver. Instead,
+construct and hold on to your own `AppiumIpc` instance (exported from `appium/driver.js`) at
+module scope in your driver's package, for example as a memoized singleton. Since Node.js caches
+modules, every instance of your driver loaded within the same Appium server process will share
+that one `AppiumIpc` object, and can use it to publish and subscribe to topics across sessions —
+the same way the per-session channel works, just not scoped to a single session. See
+[xcuitest-driver's `session-claim-handler.ts`](https://github.com/appium/appium-xcuitest-driver/blob/master/lib/session-claim-handler.ts)
+for a real example, which uses this technique to detect and resolve conflicting sessions targeting
+the same device UDID.
 
 !!! warning
 
-    Be careful here, since `driverData` is only passed between sessions of a single running Appium
-    server. There's nothing to stop a user from running multiple Appium servers and requesting your
-    driver simultaneously on each of them. In this case, you won't be able to ensure independence
-    of resources via `driverData`, so you might consider using file-based locking mechanisms or
-    something similar.
+    This only works for sessions running within the same Node.js process (i.e. the same Appium
+    server). It cannot coordinate sessions running on different Appium server processes; for that,
+    consider file-based locking or a similar out-of-process mechanism.
 
 !!! warning
 
-    It's also important to note you will only receive `driverData` for other instances of *your*
-    driver. So unrelated drivers also running may still be using some system resources. In general
-    Appium doesn't provide any features for ensuring unrelated drivers don't interfere with one
-    another, so it's up to the drivers to allow users to specify resource locations or addresses to
-    avoid clashes.
+    Appium also doesn't provide any features for ensuring unrelated drivers don't interfere with
+    one another, so it's up to the drivers to allow users to specify resource locations or
+    addresses to avoid clashes.
 
 ### Log events to the Appium event timeline
 
@@ -979,10 +967,15 @@ export type IpcMessage<T> = {
 #### IPC Notes
 
 There are some important things to keep in mind when using Appium's IPC feature:
-- IPC is only available once `onIpcInit` has been called, at the end of the `createSession` flow.
-  It cannot be used statically or in `createSession` hooks
-- In sum, IPC is only for use during a session (this is also to prevent drivers/plugins from
-  accessing or reading data sent on IPC channels in other sessions.)
+- The `ipcSubscribe` method (and the IPC channel it subscribes to) is only available once
+  `onIpcInit` has been called, at the end of the `createSession` flow. It cannot be used statically
+  or in `createSession` hooks
+- The channel that `ipcSubscribe` gives you access to is scoped to the current session, and is
+  shared only with the plugins active in that same session (this is also to prevent drivers/plugins
+  from accessing or reading data sent on IPC channels in other sessions.) To coordinate across
+  multiple concurrent sessions of your own driver instead, see [Make itself aware of resources
+  other concurrent drivers are
+  using](#make-itself-aware-of-resources-other-concurrent-drivers-are-using).
 - The default max size of an IPC message is 1MB. This can be configured by the server-admin by
   using the `--max-ipc-data-size` arg (value is a number in bytes).
 - If a message exceeds the configured size, any call to `publish` methods will throw, so be

packages/appium/docs/en/developing/build-plugins.md

@@ -257,7 +257,7 @@ throw new errors.NoSuchElementError();
 ### Log messages to the Appium log
 
 You can always use `console.log`, of course, but Appium provides a nice logger for you as
-`this.logger` (it has `.info`, `.debug`, `.log`, `.warn`, `.error` methods on it for differing log
+`this.log` (it has `.info`, `.debug`, `.warn`, `.error` methods on it for differing log
 levels). If you want to create an Appium logger outside of a plugin context (say in a script or
 helper file), you can always construct your own too:
 
@@ -476,10 +476,10 @@ capability.
 
 You probably don't normally need to update the Appium server object (which is an
 [Express](https://expressjs.com/) server having already been
-[configured](https://github.com/appium/appium/blob/master/packages/base-driver/lib/express/server.js)
-in a variety of ways). But, for example, you could add new Express middleware to the server to
-support your plugin's requirements. To update the server you must implement the `static async
-updateServer` method in your class. This method takes three parameters:
+[configured](https://github.com/appium/appium/blob/master/packages/http-server/lib/server.ts)
+in a variety of ways). But, for example, you could add new routes to the server to support your
+plugin's requirements. To update the server you must implement the `static async updateServer`
+method in your class. This method takes three parameters:
 
 * `expressApp`: the Express app object
 * `httpServer`: the Node HTTP server object
@@ -492,6 +492,25 @@ results you'll need to test! Warning: this should be considered an advanced feat
 knowledge of Express, as well as the care not to do anything that could affect the operation of
 other parts of the Appium server!
 
+`updateServer` runs *after* Appium's own routes are registered, so `expressApp.use(...)` here
+won't see requests to paths Appium already owns — Express matches middleware and routes in
+registration order. For middleware that must see requests to those routes too (e.g. logging or
+auth), use `httpServer.frontRouter` instead: Appium mounts this
+[Router](https://expressjs.com/en/5x/api/router/) before any route is registered, so anything
+attached to it — even from inside `updateServer` — still runs ahead of route matching. Note this
+is still *after* Appium's own baseline middleware (CORS, WebSocket upgrade handling, body
+parsing, etc.), so it won't see requests Appium itself has already rejected, e.g. a CORS
+preflight failure or a body that failed to parse:
+
+```js
+static async updateServer(expressApp, httpServer, cliArgs) {
+  httpServer.frontRouter.use((req, res, next) => {
+    console.log(`Incoming request: ${req.method} ${req.url}`);
+    next();
+  });
+}
+```
+
 ### Handle unexpected session shutdown
 
 When developing a plugin you may want to add some cleanup logic for when a session ends. You would

packages/appium/docs/en/ecosystem/drivers.md

@@ -69,18 +69,13 @@ appium driver install safari
 appium driver install uiautomator2
 ```
 
-### [Windows](https://github.com/appium/appium-windows-driver)
-
-!!! warning
-
-    Only the Node.js-based driver part is maintained by the Appium team. The server part
-    (WinAppDriver executable) is provided by Microsoft, but has not been maintained since 2022.
+### [WinCore](https://github.com/appium/appium-wincore-driver)
 
 * Target: Windows applications
 * Mode: Native
 
 ```sh title="Install This Driver"
-appium driver install windows
+appium driver install wincore
 ```
 
 ### [XCUITest](https://appium.github.io/appium-xcuitest-driver/)
@@ -126,7 +121,7 @@ appium driver install --source=npm appium-flutter-integration-driver
 appium driver install --source=npm appium-lg-webos-driver
 ```
 
-### [Linux](https://github.com/fantonglang/appium-linux-driver)
+### [Linux (@fantonglang)](https://github.com/fantonglang/appium-linux-driver)
 
 !!! warning
 
@@ -143,13 +138,18 @@ yarn install
 node ./
 ```
 
+### [Linux (@Itsmeaj)](https://github.com/Itsmeaj/appium)
+
+* Target: Linux desktop applications on X11 and Wayland
+* Mode: Native
+* Supported by: `@Itsmeaj`
+
+```sh title="Install This Driver"
+appium driver install --source=npm @itsmeaj/appium-linux-driver
+```
+
 ### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
 
-!!! info
-
-    This driver is recommended as a drop-in replacement for the partially unmaintained
-    [Windows driver](#windows)
-
 * Target: Windows applications
 * Mode: Native
 * Supported by: Community / Automate The Planet
@@ -192,6 +192,20 @@ npm install appium-tizen-driver
 appium driver install --source=npm appium-tizen-tv-driver
 ```
 
+### [Windows (legacy)](https://github.com/appium/appium-windows-driver)
+
+!!! warning
+
+    This driver relies on WinAppDriver, which has not been maintained since 2022, and is only
+    compatible with Appium 1-3. Use the [WinCore](#wincore) driver with Appium 4 and newer.
+
+* Target: Windows applications
+* Mode: Native
+
+```sh title="Install This Driver"
+appium driver install --source=npm appium-windows-driver
+```
+
 ### [You.i Engine](https://github.com/YOU-i-Labs/appium-youiengine-driver)
 
 !!! warning

packages/appium/docs/en/guides/event-timing.md

@@ -6,14 +6,12 @@ title: Retrieving Event Timings
 ---
 
 Appium comes with the ability to retrieve timing information about startup
-information and command length. This is an advanced feature that is controlled
-by the use of the `appium:eventTimings` capability (set it to `true` to log event
-timings).
+information and command length. This is an advanced feature; event and
+command timings are collected automatically for the duration of a session.
 
-With this capability turned on, the `POST /session/:id/appium/events` response (i.e., 
-the response to `driver.logs.events` or similar, depending on client) will be 
-decorated with an `events` property. This is the structure of that `events`
-property:
+The `POST /session/:id/appium/events` response (i.e., the response to
+`driver.logs.events` or similar, depending on client) has the following
+structure:
 
 ```
 {

packages/appium/docs/en/guides/grid.md

@@ -117,62 +117,3 @@ hub, you'll be able to send all your Appium traffic via the single hub endpoint
 
 And of course, you're able to link up Appium servers and nodes running on different machines in
 your network to form a larger grid.
-
-## Using Selenium Grid 3
-
-It is possible to register your Appium server with a local [Selenium Grid 3](https://www.selenium.dev/documentation/legacy/selenium_3/grid_3/)
-([setup docs](https://www.selenium.dev/documentation/legacy/grid_3/setting_up_your_own_grid/)) instance by using the
-`--nodeconfig` server argument.
-
-```bash
-appium server --nodeconfig /path/to/nodeconfig.json --base-path=/wd/hub
-```
-
-In the referenced config file you have to define the `browserName`, `version` and `platform`
-capabilities and based on these parameters the grid will re-direct your test to the right device.
-You will also need to configure your host details and the Selenium Grid details. For a full list of
-all parameters and descriptions see
-[here](https://www.selenium.dev/documentation/legacy/selenium_3/grid_setup/).
-
-Once you start the Appium server it will register with the grid, and you will see your device on
-the grid console page:
-
-`http://**\<grid-ip-adress\>**:**\<grid-port\>**/grid/console`
-
-### Example Grid Node Configuration JSON
-
-```json
-{
-  "capabilities":
-      [
-        {
-          "browserName": "<e.g._iPhone5_or_iPad4>",
-          "version":"<version_of_iOS_e.g._7.1>",
-          "maxInstances": 1,
-          "platform":"<platform_e.g._MAC_or_ANDROID>"
-        }
-      ],
-  "configuration":
-  {
-    "cleanUpCycle":2000,
-    "timeout":30000,
-    "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
-    "url":"http://<host_name_appium_server_or_ip-address_appium_server>:<appium_port>/wd/hub",
-    "host": "<host_name_appium_server_or_ip-address_appium_server>",
-    "port": <appium_port>,
-    "maxSession": 1,
-    "register": true,
-    "registerCycle": 5000,
-    "hubPort": <grid_port>,
-    "hubHost": "<Grid_host_name_or_grid_ip-address>",
-    "hubProtocol": "<Protocol_of_Grid_defaults_to_http>"
-  }
-}
-```
-
-If `url`, `host`, and `port` are not given, the config will be auto updated to point to
-`localhost:<appium-port>`.
-
-If your Appium server is running on a different machine to your Selenium Grid server, make sure you
-use an external name/IP address in your `host` and `url` configuration; `localhost` and `127.0.0.1`
-will prevent Selenium Grid from connecting correctly.

packages/appium/docs/en/guides/migrating-1-to-2.md

@@ -31,10 +31,6 @@ installing it only installs the core Appium server, without any drivers.
 
 When it comes to installing Appium 2 drivers, there are several approaches you can take:
 
-* Add the `--drivers` flag when installing Appium, for example:
-```bash
-npm i -g appium --drivers=xcuitest,uiautomator2
-```
 * Use the [Appium Extension CLI](../reference/cli/extensions.md), for example:
 ```bash
 appium driver install uiautomator2

packages/appium/docs/en/guides/migrating-3-to-4.md

@@ -0,0 +1,313 @@
+---
+title: Migrating to Appium 4
+---
+<style>
+    .md-typeset .grid {
+        grid-template-columns: repeat(auto-fit,minmax(min(100%,11rem),1fr));
+    }
+</style>
+
+This document is a guide for those who are using Appium 3 and would like to upgrade to Appium 4.
+It contains a list of breaking changes, as well as suggestions for handling them.
+
+Appium 4 focuses on modernizing the codebase (Node.js requirements, ESM-only packages, dropping
+long-deprecated protocol support and APIs) rather than introducing a large number of new
+user-facing features. Most Appium users only need to check the [Node.js version](#node-2222-required)
+section below; the remaining breaking changes mostly affect driver and plugin developers, or users
+of specific removed flags/endpoints.
+
+## Installation
+
+Appium 4 is currently only available as a beta release, published under the `beta` npm dist-tag.
+The installation method otherwise remains the same as for Appium 3. If you want to upgrade, you
+can simply install Appium 4 on top of your existing installation:
+
+```bash
+# optional: `appium setup reset`
+npm install -g appium@beta
+```
+
+## Breaking Changes
+
+### Node 22.22+ Required
+
+Appium 3 required Node `^20.19.0 || ^22.12.0 || >=24.0.0`. Appium 4 drops Node 20 support and
+bumps the minimum required version to `^22.22.2 || ^24.15.0 || >=26.0.0`.
+
+!!! info "Actions Needed"
+
+    Upgrade Node.js to `v22.22.2`/`v24.15.0` or newer
+
+### All Packages Are Now ESM-Only
+
+Every `@appium/*` package (and `appium` itself) is now published as `"type": "module"` with no
+CommonJS build. `require()` no longer works for these packages. This affects anyone importing
+Appium or a driver/plugin package directly from Node.js code, not just driver/plugin developers.
+
+!!! info "Actions Needed"
+
+    Import Appium packages with ESM `import` syntax, or use dynamic `import()` from CommonJS code
+
+### `--nodeconfig` Flag Removed
+
+Support for registering with a legacy Selenium Grid 3 hub has been removed, along with the
+`--nodeconfig` server argument and the `server.nodeconfig` config file property.
+
+!!! info "Actions Needed"
+
+    If you relied on Grid 3 registration, use the [Selenium Grid 4 relay feature](./grid.md) instead
+
+### `--allow-cors` Flag Removed
+
+CORS is now gated behind the same [insecure feature](./security.md) mechanism used for other
+server-level features (e.g. `session_discovery`), instead of its own dedicated flag.
+
+!!! info "Actions Needed"
+
+    Replace `--allow-cors` with `--allow-insecure=*:cors` (or enable it via `--relaxed-security`)
+
+### Extension Auto-Install on `npm install` Removed
+
+The `npm install -g appium --drivers=... --plugins=...` postinstall hook that automatically
+installed extensions has been removed, since npm postinstall hooks are a supply-chain security
+risk and newer npm versions no longer support passing custom arguments to them.
+
+!!! info "Actions Needed"
+
+    Use `appium driver install`/`appium plugin install`, or declare extensions in your project's
+    `package.json`, instead of `--drivers`/`--plugins` install-time arguments
+
+### `windows` Driver Shortcut Replaced by `wincore`
+
+The `windows` shortcut for `appium driver install` has been removed, and the new `wincore` shortcut
+resolves to [`appium-wincore-driver`](https://github.com/appium/appium-wincore-driver). The old
+`appium-windows-driver` depends on WinAppDriver, which has not been maintained since 2022 and only
+speaks the legacy JSONWP protocol, so it does not work with Appium 4.
+
+!!! info "Actions Needed"
+
+    1. While Appium 3 is still installed, install `appium-wincore-driver` v3 next to the legacy
+       driver and verify that your Windows tests pass with it. The `wincore` shortcut is not
+       available in Appium 3, so the package must be specified explicitly:
+       `appium driver install --source=npm appium-wincore-driver@^3.0.0`
+    2. After upgrading to Appium 4, update to the Appium 4 compatible driver release,
+       since v3 of the driver only works with Appium 3:
+       `appium driver update wincore --unsafe`
+    3. Uninstall the legacy driver, as it does not work with Appium 4:
+       `appium driver uninstall appium-windows-driver`
+
+### Default Log Level Changed to `info`
+
+The default `--log-level` changed from `debug` to `info`. Debug-level logging is very verbose and
+mostly only useful for troubleshooting.
+
+!!! info "Actions Needed"
+
+    Pass `--log-level debug` explicitly if you rely on the previous verbosity
+
+### CLI Output Streams Split
+
+Appium's CLI commands (`driver`/`plugin install|list|update`, `doctor`, etc.) used to write all
+non-JSON output to `STDERR`. Human-readable output (`log`/`ok`/`info`/`warn`) now goes to
+`STDOUT`; only `error` output still goes to `STDERR`. The main server's log output (Winston-based)
+is unaffected, since it already split streams this way.
+
+!!! info "Actions Needed"
+
+    If you have scripts that capture Appium CLI output, make sure they read from the correct stream
+
+### TLS Server No Longer Negotiates SPDY/HTTP2
+
+Appium's TLS-enabled server used the unmaintained `spdy` package, which allowed negotiating
+SPDY/HTTP2 over ALPN. It has been replaced with Node's native `https` module, which only serves
+plain HTTPS (HTTP/1.1).
+
+!!! info "Actions Needed"
+
+    Clients relying on SPDY or HTTP/2 multiplexing against Appium's TLS listener must switch to
+    plain HTTPS (HTTP/1.1)
+
+### Timeout Errors Now Return HTTP 500
+
+Per the W3C WebDriver standard, `TimeoutError` and `ScriptTimeoutError` now map to HTTP `500`
+instead of `408`. The stale `408` mapping could cause keep-alive clients/proxies to auto-retry an
+already-executed timed-out command.
+
+!!! info "Actions Needed"
+
+    None, unless your code inspects the raw HTTP status code of a timeout response
+
+### Timeouts Endpoint Aligned With W3C Standard
+
+`GET/SET /timeouts` is now closer to [the W3C standard](https://w3c.github.io/webdriver/#timeouts):
+
+* `POST /session/:sessionId/timeouts` now also accepts the standard `command` parameter; the
+  legacy `type`/`ms` parameters are deprecated
+* `POST /session/:sessionId/timeouts` no longer errors out when none of `script`/`pageLoad`/`implicit`
+  are provided
+* `GET /session/:sessionId/timeouts` now also returns `script` and `pageLoad`, in addition to the
+  existing `implicit` and Appium-specific `command` values
+* Driver-level `timeouts()`/`ISessionHandler` type declarations narrow `implicit` to a `number`,
+  matching `script`/`pageLoad` (the wire endpoint still coerces numeric strings at runtime)
+
+!!! info "Actions Needed"
+
+    Update any code that sends the `type`/`ms` timeout parameters or a `string` value for `implicit`
+
+### BiDi Commands No Longer Accept Stray `sessionId`/`id` Params
+
+Unlike HTTP endpoints, WebDriver BiDi commands have no URL-derived session/element id, so a stray
+`sessionId` or `id` key inside BiDi command params is no longer silently accepted; it is now
+validated like any other unknown parameter.
+
+!!! info "Actions Needed"
+
+    Remove `sessionId`/`id` from the parameters of any custom BiDi command invocation
+
+## Endpoint Changes
+
+The following endpoints have been removed:
+
+* `GET/POST /session/:sessionId/ime/*` (all IME endpoints, legacy JSONWP)
+* `GET /session/:sessionId/location`, `POST /session/:sessionId/location` (legacy geolocation, legacy JSONWP)
+* `GET /session/:sessionId/network_connection`, `POST /session/:sessionId/network_connection` (legacy MJSONWP)
+* `POST /session/:sessionId/receive_async_response` (legacy JSONWP)
+* `GET /session/:sessionId/element/:elementId` (undocumented legacy JSONWP stub)
+* `GET /session/:sessionId` (deprecated `getSession`; see [below](#getsession-command-removed) for
+  its replacement)
+
+The `orientation`, `context`/`contexts`, and `rotation` deprecated endpoints are unaffected and
+remain available.
+
+## Changes for Driver and Plugin Developers
+
+The following changes primarily affect authors of Appium drivers, plugins, or tools that import
+Appium's internal packages directly (`@appium/base-driver`, `@appium/base-plugin`,
+`@appium/support`, `@appium/logger`). They do not affect most Appium end users.
+
+### Remaining Legacy (M)JSONWP Support Removed From `@appium/base-driver`
+
+Beyond the removed endpoints above, the internal machinery that translated between the legacy
+(M)JSONWP protocol and W3C WebDriver has been removed:
+
+* `ProtocolError` instances no longer carry a `jsonwpCode` property, and error responses no longer
+  include a legacy numeric `status` code (`errorFromMJSONWPStatusCode`, aliased as `errorFromCode`,
+  has been removed; use `errorFromW3CJsonCode`)
+* Responses no longer duplicate element references under the legacy `ELEMENT` key; only the W3C
+  `element-6066-11e4-a52e-4f735466cecf` key is present
+* `WebDriverProxy` (formerly `JWProxy`, now removed as a name) no longer converts responses from a
+  downstream automation server speaking legacy MJSONWP; downstream servers must speak W3C WebDriver
+* `determineProtocol`, `DriverCore#setProtocolMJSONWP()`, and `DriverCore#isMjsonwpProtocol()` have
+  been removed; drivers can no longer produce the legacy `{sessionId, status, value}` response shape
+* `@appium/base-driver` no longer exports `statusCodes`/`getSummaryByCode` (the `jsonwp-status`
+  module was removed)
+
+!!! info "Actions Needed"
+
+    Ensure any downstream automation server a driver proxies to (via `WebDriverProxy`) speaks pure
+    W3C WebDriver; update code referencing the removed exports to their W3C equivalents
+
+### `@appium/base-driver` Default Export Removed
+
+`BaseDriver` is no longer exported as `@appium/base-driver`'s default export, and
+`basedriver/helpers.js`'s default export has been removed as well. `BaseDriver`'s constructor no
+longer takes command-mixin machinery into account, and the unused `BaseDriver.reset()` method has
+been removed.
+
+!!! info "Actions Needed"
+
+    Replace `import BaseDriver from '@appium/base-driver'` with `import {BaseDriver} from '@appium/base-driver'`
+
+### `@appium/base-plugin` Default Export and Legacy Logger Removed
+
+`BasePlugin` is no longer the default export of `@appium/base-plugin`. `Plugin#logger` has been
+removed in favor of `Plugin#log`, and `Plugin#name`/`Plugin#cliArgs` are now read-only.
+
+!!! info "Actions Needed"
+
+    * Replace `import BasePlugin from '@appium/base-plugin'` with `import {BasePlugin} from '@appium/base-plugin'`
+    * Replace `this.logger` with `this.log` in plugin code
+
+### `@appium/logger` Default Export and Dead APIs Removed
+
+`@appium/logger` and `@appium/support` no longer export a default `log`. `AppiumLogger#errorAndThrow`
+has been removed in favor of `errorWithException`. The long-disabled, no-op progress/unicode
+methods (`enableProgress`, `disableProgress`, `progressEnabled`, `enableUnicode`, `disableUnicode`)
+have also been removed.
+
+!!! info "Actions Needed"
+
+    * Import the named `log` export instead of the default export
+    * Replace `errorAndThrow` calls with `errorWithException`
+
+### `driverData` Mechanism Removed
+
+The deprecated `driverData` mechanism (`Core.driverData`, the `driverData` parameter on
+`createSession`/`deleteSession`, and the `DriverData` type) has been removed, superseded by
+`IAppiumIpc`.
+
+!!! info "Actions Needed"
+
+    Drivers overriding `get driverData()` or relying on it for cross-session coordination need to
+    migrate to `IAppiumIpc`
+
+### `createSession` Multi-Argument Overload Removed
+
+`createSession` no longer accepts the legacy multi-argument form
+(`createSession(jwpCaps, reqCaps, w3cCaps)`), a holdover from JSONWP. Only the single
+`w3cCapabilities` argument is supported now.
+
+!!! info "Actions Needed"
+
+    Update any driver or plugin overriding `createSession` to use the single-argument signature
+
+### `getSession` Command Removed
+
+`BaseDriver.getSession` and `ISessionHandler.getSession` have been removed (see [Endpoint
+Changes](#endpoint-changes) for the removed route), along with the `appium:eventTimings`
+capability that controlled whether its response included event history.
+
+!!! info "Actions Needed"
+
+    Use `GET /session/:sessionId/appium/capabilities` to retrieve session capabilities, and
+    `POST /session/:sessionId/appium/events` to retrieve event history (now returned unconditionally)
+
+### `@appium/support` Deprecated APIs Removed
+
+The following `@appium/support` exports have been removed: `process` (`getProcessIds`,
+`killProcess`), `mkdirp`, `imageUtil` (`requireSharp`, `cropBase64Image`), `mjpeg` (`MJpegStream`),
+`net`'s FTP upload support, `util`'s `uuidV1`/`uuidV3`/`uuidV5`/`localIp`/`cancellableDelay`/`multiResolve`,
+`fs`'s `readPackageJsonFrom`/`findRoot`/`F_OK`/`R_OK`/`W_OK`/`X_OK`, `npm`/`NPM` (moved into the
+`appium` package), and `env` (moved into the `appium` package). `node.requirePackage()` and
+`system.macOsxVersion()` have also been removed. `fs.glob()` is now backed by Node's native
+`fs.promises.glob` instead of the `glob` package, with a narrower `GlobOptions` shape.
+
+!!! info "Actions Needed"
+
+    None for typical drivers/plugins, which don't use these low-level helpers directly. If you do,
+    switch to the suggested replacement or a native Node.js API
+
+### Legacy Test Pages Removed From `@appium/base-driver`
+
+The built-in test fixture routes (`/welcome`, `/test/guinea-pig*`, `/produce_error`, `/crash`),
+the `STATIC_DIR` export, and the `APPIUM_ENABLE_LEGACY_TEST_PAGES` environment variable have been
+removed.
+
+!!! info "Actions Needed"
+
+    Driver test suites that relied on these fixtures should host their own local test server
+
+## New Features
+
+* [`--app-url-rules`](./security.md#restricting-remote-app-urls) lets server operators restrict
+  which hosts/IPs an `appium:app` URL is allowed to be downloaded from (allow/deny lists, HTTPS-only,
+  credentials, redirect limits)
+* Definitions for all current [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) commands are
+  now included for introspection/validation purposes
+* `ExecuteMethodMap` type declarations now check `params` against the target method's signature at
+  compile time, catching mismatched required/optional execute method parameters in driver code
+* Extension manifests and `extensions.yaml` are now validated with `ajv`/JSON Schema; a corrupted
+  `extensions.yaml` now resets to an empty manifest with a warning instead of crashing later with a
+  confusing error
+* `appium driver`/`appium plugin` CLI commands now lock the extension manifest while running,
+  preventing concurrent processes from silently clobbering each other's changes

packages/appium/docs/en/guides/security.md

@@ -85,3 +85,118 @@ Turn on multiple insecure features for specific drivers:
 ```bash
 appium --allow-insecure=uiautomator2:adb_shell,xcuitest:get_server_logs
 ```
+
+## Restricting Remote App URLs
+
+Several drivers accept a URL instead of a local path in capabilities such as `appium:app`, in which
+case the Appium server downloads the application package from that URL before starting the session.
+By default, any `http:` or `https:` URL is accepted. Server hosts who want to control which URLs
+their server is allowed to download from can do so with the `--app-url-rules` argument (or the
+`server.app-url-rules` property in a [configuration file](./config.md)). Its value is a JSON object
+(or a path to a JSON file) with any of the following properties:
+
+|<div style="width:10em">Rule</div>|Description|Default|
+|----------------------------------|-----------|-------|
+|`allow`|List of hostname patterns, IP addresses, or CIDR subnets. If non-empty, a hostname or its resolved address must match _at least one_|`[]`|
+|`deny`|List of hostname patterns, IP addresses, or CIDR subnets. A matching hostname or resolved address is rejected, even if an `allow` rule also matches|`[]`|
+|`httpsOnly`|Only accept `https:` URLs|`false`|
+|`allowCredentials`|Accept URLs containing a username and/or password (e.g. `https://user:pass@host/app.apk`)|`true`|
+|`maxRedirects`|Maximum number of HTTP redirects to follow while downloading. Set to `0` to reject any redirect|`21`|
+
+Hostnames are normalized (lowercased, converted to Punycode, trailing dot removed) before matching
+and resolved on every download. Address rules apply to literal addresses and all dynamically
+resolved IPv4/IPv6 addresses. The rules are also applied to every redirect, so redirects cannot be
+used to escape them. If a URL violates any rule, the session is not created and a generic error
+is returned. The violated rule is deliberately neither reported to the client nor written to the
+server log, since server logs are often handed over to clients as well. URL schemes, ports, paths,
+queries, and fragments are not matched.
+
+Hostname patterns use the [picomatch](https://github.com/micromatch/picomatch#globbing-features)
+glob syntax and are matched against the whole hostname:
+
+|Pattern|Matches|
+|-------|-------|
+|`artifacts.example.com`|Exactly this hostname|
+|`*.example.com`|Any subdomain of `example.com` (including nested ones, like `a.b.example.com`), but not `example.com` itself|
+|`*example.com`|Any hostname ending with `example.com`, including `example.com` itself|
+|`apps.{staging,prod}.example.com`|`apps.staging.example.com` and `apps.prod.example.com`|
+|`build-?.example.com`|`build-1.example.com`, `build-a.example.com`, etc.|
+|`node[0-9].example.com`|`node0.example.com` to `node9.example.com`|
+
+IP address rules match a single address (`192.0.2.10`, `2001:db8::1`) or a whole subnet in CIDR
+notation (`10.0.0.0/8`, `2001:db8::/32`). IPv4 rules also match IPv4-mapped IPv6 addresses
+(e.g. `::ffff:10.1.2.3`).
+
+!!! note
+
+    These rules only apply to URLs the server downloads via the standard app configuration helper,
+    which is used for `appium:app` and similar capabilities by all official drivers. Drivers may
+    define custom capabilities with URLs that are processed differently and thus are not covered.
+
+!!! note
+
+    If the server downloads applications through an HTTP proxy (configured via the `HTTP_PROXY`,
+    `HTTPS_PROXY` and `NO_PROXY` environment variables), the proxy resolves the destination host
+    itself, so rules containing IP addresses or subnets cannot be enforced for proxied downloads.
+    Such downloads are rejected; either exclude the download hosts from proxying via `NO_PROXY`
+    or only use hostname-based rules.
+
+### Examples
+
+Only allow HTTPS downloads from an internal artifact server, without credentials in the URL and
+without following redirects:
+
+```bash
+appium --app-url-rules='{"allow": ["artifacts.example.com", "10.0.0.0/8"], "httpsOnly": true, "allowCredentials": false, "maxRedirects": 0}'
+```
+
+The same configuration as part of a config file:
+
+```yaml
+server:
+  app-url-rules:
+    allow:
+      - 'artifacts.example.com'
+      - '10.0.0.0/8'
+    httpsOnly: true
+    allowCredentials: false
+    maxRedirects: 0
+```
+
+Allow downloads from any subdomain of `example.com` and from two IPv6 subnets, except from the
+staging environment:
+
+```yaml
+server:
+  app-url-rules:
+    allow:
+      - '*.example.com'
+      - '2001:db8:1::/48'
+      - '2001:db8:2::/48'
+    deny:
+      - '*.staging.example.com'
+```
+
+Allow downloads from anywhere, except from the server itself, private networks, link-local
+addresses (such as cloud metadata services), and any `.internal` hostname:
+
+```yaml
+server:
+  app-url-rules:
+    deny:
+      - 'localhost'
+      - '*.internal'
+      - '127.0.0.0/8'
+      - '10.0.0.0/8'
+      - '172.16.0.0/12'
+      - '192.168.0.0/16'
+      - '169.254.0.0/16'
+      - '::1/128'
+      - 'fc00::/7'
+      - 'fe80::/10'
+```
+
+The rules in the last example are applied to the addresses each hostname resolves to, so they
+cannot be bypassed via DNS. Note that the `deny` list also blocks any download from the server's
+own private network, so a private artifact server must be excluded from the `deny` rules in order
+to work.

packages/appium/docs/en/guides/tls.md

@@ -2,7 +2,7 @@
 hide:
   - toc
 
-title: SSL/TLS/SPDY Support
+title: SSL/TLS Support
 ---
 
 Appium 2.2 introduces the option to start the Appium server with SSL/TLS support. 
@@ -19,15 +19,14 @@ Both arguments must be provided and should contain paths to a valid
 [X509 PEM](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/)
 certificate and its corresponding private key.
 
-After the server is started use the `https` protocol and a client supporting SSL/TLS or
-[SPDY](https://en.wikipedia.org/wiki/SPDY) to communicate to it.
+After the server is started use the `https` protocol and a client supporting SSL/TLS to
+communicate to it.
 
 ### Supported Features
 
-Once a secure server socket is established it supports the following protocols:
-`['h2', 'spdy/3.1', 'spdy/3', 'spdy/2', 'http/1.1', 'http/1.0']`. See
-[the SPDY node module documentation](https://www.npmjs.com/package/spdy) to get more details about
-its features. All insecure client connections will be rejected by the server.
+Once a secure server socket is established it uses Node.js' native
+[`https`](https://nodejs.org/api/https.html) module to serve connections. All insecure client
+connections will be rejected by the server.
 
 ### Self-Signed Certificates
 

packages/appium/docs/en/intro/clients.md

@@ -39,6 +39,16 @@ So, for example, the `Find Element` command corresponds to an HTTP `POST` reques
 endpoint `/session/:sessionid/element` (where in this case, `:sessionid` is a placeholder for the
 unique session ID generated by the server in a previous call to `Create Session`).
 
+If the client disconnects before Appium finishes sending a `Create Session` response and the
+request has no `X-Idempotency-Key`, Appium deletes the new session once driver setup completes.
+Setup is not interrupted. With an accepted idempotency key, a retry that arrives before setup
+finishes waits for the same session ID, or the same error if setup failed. If the original client
+and all waiting retries disconnect before setup finishes, Appium deletes the new session and
+discards its cached result; a later retry starts a new session. Otherwise, Appium keeps the session
+and caches its response for replay while it remains in the bounded, in-memory idempotency cache.
+Disconnecting after a response was sent, or during a command in an existing session, does not
+automatically end that session. Use `Delete Session` when you are done.
+
 This information is primarily useful for people developing technology that works with the WebDriver
 spec. It's not particularly useful for people trying to write Appium or Selenium tests. When you
 write an Appium test, you want to use a programming language you're familiar with. Luckily, there

packages/appium/docs/en/intro/drivers.md

@@ -19,7 +19,7 @@ Appium, called `BaseDriver`. You could have something very close to a "working"
 very simple lines of code:
 
 ```js
-import BaseDriver from '@appium/base-driver'
+import {BaseDriver} from '@appium/base-driver'
 
 class MyNewDriver extends BaseDriver {
 }

packages/appium/docs/en/reference/api/appium.md

@@ -106,6 +106,48 @@ Retrieves the [execute methods](../../guides/execute-methods.md) supported in th
 origin (driver-specific or plugin-specific). Refer to [the type definition file](https://github.com/appium/appium/blob/master/packages/types/lib/command.ts)
 for a detailed structure of this object.
 
+### getCurrentAppiumContext
+
+```
+GET /session/:sessionId/appium/context
+```
+
+Retrieves the active application context.
+
+#### Response
+
+`string` - the name of the active context
+
+### setAppiumContext
+
+```
+POST /session/:sessionId/appium/context
+```
+
+Sets an application context as the active context.
+
+#### Parameters
+
+|Name|Description|Type|
+|--|--|--|
+|`name`|Name of the context to set as the active one|string|
+
+#### Response
+
+`null`
+
+### getAppiumContexts
+
+```
+GET /session/:sessionId/appium/contexts
+```
+
+Retrieves all available application contexts.
+
+#### Response
+
+`string[]` - the names of available contexts
+
 ### getLogEvents
 
 ```
@@ -392,3 +434,71 @@ Retrieves data from a directory on the device under test.
 #### Response
 
 `string` - the Base64-encoded zip file of the directory contents
+
+### getAppiumRotation
+
+```
+GET /session/:sessionId/appium/device/rotation
+```
+
+Retrieves the current spatial orientation of the device under test.
+
+#### Response
+
+`Rotation` - an object with the following properties:
+
+|Name|Description|Type|
+|--|--|--|
+|`x`|Degrees by which the device is rotated on its X axis|number|
+|`y`|Degrees by which the device is rotated on its Y axis|number|
+|`z`|Degrees by which the device is rotated on its Z axis|number|
+
+### setAppiumRotation
+
+```
+POST /session/:sessionId/appium/device/rotation
+```
+
+Sets the spatial orientation of the device under test.
+
+#### Parameters
+
+|Name|Description|Type|
+|--|--|--|
+|`x`|Degrees by which the device is rotated on its X axis|number|
+|`y`|Degrees by which the device is rotated on its Y axis|number|
+|`z`|Degrees by which the device is rotated on its Z axis|number|
+
+#### Response
+
+`null`
+
+### getAppiumOrientation
+
+```
+GET /session/:sessionId/appium/device/orientation
+```
+
+Retrieves the current orientation of the device under test.
+
+#### Response
+
+`string` - either `PORTRAIT` or `LANDSCAPE`
+
+### setAppiumOrientation
+
+```
+POST /session/:sessionId/appium/device/orientation
+```
+
+Sets the orientation of the device under test.
+
+#### Parameters
+
+|Name|Description|Type|
+|--|--|--|
+|`orientation`|New device orientation. Supported values are `PORTRAIT` or `LANDSCAPE`.|string|
+
+#### Response
+
+`null`

packages/appium/docs/en/reference/api/bidi.md

@@ -46,7 +46,7 @@ Subscribes to one or more BiDi events.
 
 #### Response
 
-`null`
+`{subscription: string}` — a unique subscription ID that can be passed to `session.unsubscribe`.
 
 ### bidiUnsubscribe
 
@@ -56,15 +56,20 @@ session.unsubscribe
 
 > WebDriver BiDi documentation: [session.unsubscribe](https://w3c.github.io/webdriver-bidi/#command-session-unsubscribe)
 
-Unsubscribes from one or more BiDi events.
+Unsubscribes using previously returned subscription IDs, or the legacy event/context form.
+Removing a subscription ID preserves any overlapping subscriptions.
 
 #### Parameters
 
 |Name|Description|Type|Default|
 |--|--|--|--|
-|`contexts?`|Contexts in which to unsubscribe from the specified events. By default, the global scope is applied.|string[]|`['']`|
-|`events`|Names of events to unsubscribe from|string[]||
+|`subscriptions?`|Non-empty list of subscription IDs returned by `session.subscribe`. Cannot be combined with `events` or `contexts`.|string[]||
+|`contexts?`|Legacy form only: contexts in which to unsubscribe from the specified events. By default, the global scope is applied.|string[]|`['']`|
+|`events?`|Legacy form: non-empty list of event names to unsubscribe from. Required when `subscriptions` is omitted.|string[]||
+
+All subscription IDs must be known to the current session. An unknown ID causes an `invalid argument`
+error without removing any subscriptions. Subscription IDs are cleared when the session is deleted.
 
 #### Response
 
-`null`
+`{}`

packages/appium/docs/en/reference/api/jsonwp.md

@@ -10,125 +10,6 @@ title: JSON Wire Protocol
 The following is a list of legacy [JSON Wire Protocol (JSONWP)](https://www.selenium.dev/documentation/legacy/json_wire_protocol/)
 endpoints supported in Appium.
 
-### getSession
-
-```
-GET /session/:sessionId
-```
-
-> JSONWP documentation: [/session/:sessionId](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionid)
-
-Retrieves the capabilities of the current session.
-
-Appium implements a modified version of this endpoint. If the `appium:eventTimings` capability is
-set to `true`, the returned result will additionally include the `events` key, whose value contains
-the event history and timings.
-
-!!! warning "Deprecated"
-
-    For retrieving capabilities, please use [`getAppiumSessionCapabilities`](./appium.md#getappiumsessioncapabilities).<br />
-    For retrieving event history, please use [`getLogEvents`](./appium.md#getlogevents).
-
-#### Response
-
-`Capabilities` - an object containing the session capabilities, and the event history (if applicable)
-
-### availableIMEEngines
-
-```
-GET /session/:sessionId/ime/available_engines
-```
-
-> JSONWP documentation: [/session/:sessionId/ime/available_engines](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeavailable_engines)
-
-Retrieves all IME (input method editor) engines available on the device under test.
-
-!!! warning "Deprecated"
-
-    In the future, this endpoint will be moved to the [UiAutomator2 and Espresso drivers](../../ecosystem/drivers.md)
-
-#### Response
-
-`string[]` - a list of available IME engines
-
-### getActiveIMEEngine
-
-```
-GET /session/:sessionId/ime/active_engine
-```
-
-> JSONWP documentation: [/session/:sessionId/ime/active_engine](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactive_engine)
-
-Retrieves the name of the active IME engine.
-
-!!! warning "Deprecated"
-
-    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
-
-#### Response
-
-`string` - the name of the active IME engine
-
-### isIMEActivated
-
-```
-GET /session/:sessionId/ime/activated
-```
-
-> JSONWP documentation: [/session/:sessionId/ime/activated](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivated)
-
-Determines if IME input is available and active.
-
-!!! warning "Deprecated"
-
-    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
-
-#### Response
-
-`boolean` - `true` if IME is active, otherwise `false`
-
-### deactivateIMEEngine
-
-```
-POST /session/:sessionId/ime/deactivate
-```
-
-> JSONWP documentation: [/session/:sessionId/ime/deactivate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimedeactivate)
-
-Deactivates the currently active IME engine.
-
-!!! warning "Deprecated"
-
-    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
-
-#### Response
-
-`null`
-
-### activateIMEEngine
-
-```
-POST /session/:sessionId/ime/activate
-```
-
-> JSONWP documentation: [/session/:sessionId/ime/activate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivate)
-
-Activates an IME engine.
-
-!!! warning "Deprecated"
-
-    In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
-
-#### Parameters
-
-|Name|Description|Type|
-|--|--|--|
-|`engine`|Name of the IME engine to activate|string|
-
-#### Response
-
-`null`
-
 ### getOrientation
 
 ```
@@ -139,6 +20,10 @@ GET /session/:sessionId/orientation
 
 Retrieves the current orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumOrientation`](./appium.md#getappiumorientation) instead
+
 #### Response
 
 `string` - either `PORTRAIT` or `LANDSCAPE`
@@ -153,6 +38,10 @@ POST /session/:sessionId/orientation
 
 Sets the orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumOrientation`](./appium.md#setappiumorientation) instead
+
 #### Parameters
 
 |Name|Description|Type|
@@ -162,53 +51,3 @@ Sets the orientation of the device under test.
 #### Response
 
 `null`
-
-### getGeoLocation
-
-```
-GET /session/:sessionId/location
-```
-
-> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
-
-Retrieves the current location of the device under test.
-
-!!! warning "Deprecated"
-
-    Please use driver-specific extension methods such as `mobile: getGeoLocation` or
-    `mobile: getSimulatedLocation`
-
-#### Response
-
-`Location` - an object with the following properties:
-
-|Name|Description|Type|
-|--|--|--|
-|`altitude`|Altitude of the device location|number|
-|`latitude`|Latitude of the device location|number|
-|`longitude`|Longitude of the device location|number|
-
-### setGeoLocation
-
-```
-POST /session/:sessionId/location
-```
-
-> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
-
-Sets the current location of the device under test.
-
-!!! warning "Deprecated"
-
-    Please use driver-specific extension methods such as `mobile: setGeoLocation` or
-    `mobile: setSimulatedLocation`
-
-#### Parameters
-
-|Name|Description|Type|
-|--|--|--|
-|`location`|New device latitude, longitude and altitude|[`Location`](#response_6)|
-
-#### Response
-
-`null`

packages/appium/docs/en/reference/api/mjsonwp.md

@@ -20,6 +20,10 @@ GET /session/:sessionId/rotation
 
 Retrieves the current spatial orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumRotation`](./appium.md#getappiumrotation) instead
+
 #### Response
 
 `Rotation` - an object with the following properties:
@@ -40,6 +44,10 @@ POST /session/:sessionId/rotation
 
 Sets the spatial orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumRotation`](./appium.md#setappiumrotation) instead
+
 #### Parameters
 
 |Name|Description|Type|
@@ -62,6 +70,10 @@ GET /session/:sessionId/context
 
 Retrieves the active application context.
 
+!!! warning "Deprecated"
+
+    Please use [`getCurrentAppiumContext`](./appium.md#getcurrentappiumcontext) instead
+
 #### Response
 
 `string` - the name of the active context
@@ -76,6 +88,10 @@ POST /session/:sessionId/context
 
 Sets an application context as the active context.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumContext`](./appium.md#setappiumcontext) instead
+
 #### Parameters
 
 |Name|Description|Type|
@@ -96,56 +112,10 @@ GET /session/:sessionId/contexts
 
 Retrieves all available application contexts.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumContexts`](./appium.md#getappiumcontexts) instead
+
 #### Response
 
 `string[]` - the names of available contexts
-
-### getNetworkConnection
-
-```
-GET /session/:sessionId/network_connection
-```
-
-> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
-
-Retrieves the current state of network types (data, Wi-Fi, airplane mode).
-
-!!! warning "Deprecated"
-
-    Please use driver-specific extension methods such as `mobile: getConnectivity`
-
-#### Response
-
-`NetworkConnectionState` - a number indicating the current network state:
-
-|Value|Data|Wi-Fi|Airplane Mode|
-|--|--|--|--|
-|`0`|OFF|OFF|OFF|
-|`1`|OFF|OFF|ON|
-|`2`|OFF|ON|OFF|
-|`4`|ON|OFF|OFF|
-|`6`|ON|ON|OFF|
-
-### setNetworkConnection
-
-```
-POST /session/:sessionId/network_connection
-```
-
-> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
-
-Sets the state of network types (data, Wi-Fi, airplane mode).
-
-!!! warning "Deprecated"
-
-    Please use driver-specific extension methods such as `mobile: setConnectivity`
-
-#### Parameters
-
-|<div style="width:6em">Name</div>|Description|<div style="width:18em">Type</div>|
-|--|--|--|
-|`parameters`|Object containing the `type` key, whose value is the desired network state|`{"type": `[`NetworkConnectionState`](#response_5)`}`|
-
-#### Response
-
-[`NetworkConnectionState`](#response_5) - the new network state

packages/appium/docs/en/reference/api/plugins.md

@@ -169,10 +169,17 @@ Modifies the [`createSession`](./webdriver.md#createsession) endpoint:
     All endpoints for this plugin can be invoked without creating a session, allowing you to prepare
     your test environment in advance.
 
+!!! info
+
+    Prior to plugin version 1.2.0, all endpoints below were mounted under the `/storage` prefix
+    (e.g. `/storage/add`) instead of `/appium/storage`. The `/storage`-prefixed routes are still
+    available for backward compatibility, but are deprecated and will be removed in a future
+    version of the plugin.
+
 ### addStorageItem
 
 ```
-POST /storage/add
+POST /appium/storage/add
 ```
 
 Adds a new file to the storage.
@@ -198,8 +205,8 @@ Example:
 ```json
 {
   "ws": {
-    "stream": "/storage/add/ccc963411b2621335657963322890305ebe96186/stream",
-    "events": "/storage/add/ccc963411b2621335657963322890305ebe96186/events"
+    "stream": "/appium/storage/add/ccc963411b2621335657963322890305ebe96186/stream",
+    "events": "/appium/storage/add/ccc963411b2621335657963322890305ebe96186/events"
   },
   "ttlMs": 300000
 }
@@ -208,7 +215,7 @@ Example:
 ### deleteStorageItem
 
 ```
-POST /storage/delete
+POST /appium/storage/delete
 ```
 
 Deletes a file in the storage.
@@ -222,12 +229,12 @@ Deletes a file in the storage.
 #### Response
 
 `boolean` - `true` upon successful file deletion, or `false` if the file does not exist in
-the storage 
+the storage, or if the delete request is invalid.
 
 ### listStorageItems
 
 ```
-GET /storage/list
+GET /appium/storage/list
 ```
 
 List all files present in the storage.
@@ -245,7 +252,7 @@ List all files present in the storage.
 ### resetStorage
 
 ```
-POST /storage/reset
+POST /appium/storage/reset
 ```
 
 Deletes all uploaded files and stops any incomplete uploads.
@@ -258,6 +265,43 @@ preserved, and only the incomplete uploads will be stopped.
 
 ## Universal XML Plugin
 
+Translation is on by default. It can be turned off and on during a session with the
+[execute methods](../../guides/execute-methods.md) below, and applies only to the current session.
+
+### execute
+
+```
+POST /session/:sessionId/execute/sync
+```
+
+Modifies the [`execute`](./webdriver.md#execute) endpoint:
+
+* Adds the `universalXml: setEnabled` and `universalXml: isEnabled` execute methods. Any other
+  script is passed on unchanged
+
+#### universalXml: setEnabled
+
+Turns translation on or off for the current session. While it is off, `findElement`,
+`findElements` and `getPageSource` are passed on unchanged.
+
+##### Parameters
+
+|Name|Description|Type|
+|--|--|--|
+|`enabled`|Whether node/attribute names should be translated|boolean|
+
+##### Response
+
+`null`
+
+#### universalXml: isEnabled
+
+Returns whether translation is on for the current session.
+
+##### Response
+
+`boolean` - `true` if translation is on
+
 ### findElement
 
 ```

packages/appium/docs/en/reference/api/webdriver.md

@@ -25,18 +25,11 @@ POST /session
 
 Creates a new WebDriver session.
 
-Appium implements a modified version of this endpoint for historical reasons. While the W3C
-endpoint only accepts 1 parameter, Appium's implementation allows up to 3 parameters, as this was
-required by the legacy JSON Wire Protocol (JSONWP). Since Appium 2, the JSONWP format is no longer
-supported, and any of the 3 parameters can be used to specify the W3C capabilities.
-
 #### Parameters
 
 |Name|Description|Type|
 |--|--|--|
-|`w3cCapabilities1?`|Capabilities of the new session|`W3CDriverCaps`|
-|`w3cCapabilities2?`|Another location for the new session capabilities (legacy)|`W3CDriverCaps`|
-|`w3cCapabilities?`|Another location for the new session capabilities (legacy)|`W3CDriverCaps`|
+|`capabilities?`|Capabilities of the new session|`W3CDriverCaps`|
 
 #### Response
 
@@ -91,14 +84,19 @@ GET /session/:sessionId/timeouts
 
 Retrieves the timeout values of the current session.
 
+Appium implements a modified version of this endpoint, by also returning the value of the `command`
+timeout for supported drivers and contexts.
+
 #### Response
 
 `GetTimeoutsResult` - an object with the following properties:
 
 |Name|Description|Type|
 |--|--|--|
-|`command`|Command timeout|number|
+|`script`|Script timeout|number|
+|`pageLoad`|Page load timeout|number|
 |`implicit`|Implicit wait timeout|number|
+|`command`|Appium command timeout|number|
 
 ### timeouts
 
@@ -110,13 +108,17 @@ POST /session/:sessionId/timeouts
 
 Sets the timeout values of the current session.
 
+Appium implements a modified version of this endpoint by adding the optional `command` parameter
+for supported drivers and contexts.
+
 #### Parameters
 
 |Name|Description|Type|
 |--|--|--|
+|`script?`|Script timeout (in milliseconds)|number|
 |`implicit?`|Implicit wait timeout (in milliseconds)|number|
 |`pageLoad?`|Page load timeout (in milliseconds)|number|
-|`script?`|Script timeout (in milliseconds)|number|
+|`command?`|Appium command timeout (in milliseconds)|number|
 
 #### Response
 

packages/appium/docs/en/reference/cli/extensions.md

@@ -13,6 +13,12 @@ Provides management options for a specific extension (driver or plugin). Both th
 The following sub-subcommands are supported: `doctor`, `install`, `list`, `run`, `update`,
 and `uninstall`.
 
+For `doctor`, `run`, `update`, and `uninstall`, you can identify an installed extension by its
+short name or its exact npm package name. For example, `appium driver uninstall uiautomator2`
+and `appium driver uninstall appium-uiautomator2-driver` refer to the same installed driver.
+Short names take precedence if a name also matches another extension's package name. Package names
+can include a scope, such as `@appium/fake-driver`, but must not include a version or tag suffix.
+
 ## `doctor`
 
 Runs doctor checks for an installed extension, which validate whether the extension has its prerequisites
@@ -31,7 +37,7 @@ appium {driver|plugin} doctor <extension-name>
 
 |Argument|Description|
 |--|--|
-|`extension-name`|The short name of the installed extension|
+|`extension-name`|The short name or exact npm package name of the installed extension|
 
 #### Options
 
@@ -158,13 +164,13 @@ extensions include scripts.
 #### Usage
 
 ```
-appium {driver|plugin} run <extension-name> <script-name> [script-args]
+appium {driver|plugin} run <extension-name> [<script-name> [<script-args>]]
 ```
 
 |Argument|Description|
 |--|--|
-|`extension-name`|The short name of the installed extension|
-|`script-name`|The name of the script to be run|
+|`extension-name`|The short name or exact npm package name of the installed extension|
+|`script-name`|The name of the script to run. If not provided, a list of available scripts is returned.|
 |`script-args`|Any additional arguments passed to the script|
 
 #### Options
@@ -181,6 +187,12 @@ appium {driver|plugin} run <extension-name> <script-name> [script-args]
     appium driver run uiautomator2 reset
     ```
 
+- List all available scripts included in the XCUITest driver:
+
+    ```
+    appium driver run xcuitest
+    ```
+
 ## `update`
 
 Updates one or more extensions. Only supported for extensions installed via `npm`. By default,
@@ -194,7 +206,7 @@ appium {driver|plugin} update <extension-name>
 
 |Argument|Description|
 |--|--|
-|`extension-name`|The short name of the installed extension, or `installed` to update all installed extensions|
+|`extension-name`|The short name or exact npm package name of the installed extension, or `installed` to update all installed extensions|
 
 #### Options
 
@@ -229,7 +241,7 @@ appium {driver|plugin} uninstall <extension-name>
 
 |Argument|Description|
 |--|--|
-|`extension-name`|The short name of the installed extension|
+|`extension-name`|The short name or exact npm package name of the installed extension|
 
 #### Options
 

packages/appium/docs/en/reference/cli/insecure-features.md

@@ -14,6 +14,7 @@ they can only be enabled using the wildcard (`*`) prefix:
 | Feature Name      | Description                                                                   |
 |-------------------|-------------------------------------------------------------------------------|
 |`session_discovery`|Allows retrieving the list of active server sessions via `GET /appium/sessions`|
+|`cors`             |Allows web browser connections to the server from any host                    |
 
 
 Of course, Appium drivers and plugins are free to define additional insecure features of their own.

packages/appium/docs/en/reference/cli/server.md

@@ -27,8 +27,9 @@ appium
 |<div style="width:15em">Argument</div>|Description|Type|<div style="width:7em">Default</div>|
 |--|--|--|--|
 |`--address`, `-a`|IPv4/IPv6 address to listen on|string|`0.0.0.0`|
-|`--allow-cors`|Allow web browser connections from any host|boolean|`false`|
 |`--allow-insecure`|List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`.|array<string>|`[]`|
+|`--allow-unknown-args`|Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags.|boolean|`false`|
+|`--app-url-rules`|Rules that remote application URLs (e.g. in the `appium:app` capability) must satisfy before the server downloads them. See the [Restricting Remote App URLs](../../guides/security.md#restricting-remote-app-urls) guide for details. Can be a path to a JSON file or raw JSON.|object||
 |`--base-path`, `-pa`|Base path to use as the prefix for all webdriver routes running on the server|string|`""`|
 |`--callback-address`, `-ca`|Callback IP address|string|`0.0.0.0`|
 |`--callback-port`, `-cp`|Callback port|integer|`4723`|
@@ -43,7 +44,7 @@ appium
 |`--local-timezone`|Use local timezone for log timestamps|boolean|`false`|
 |`--log`, `-g`|Path to a file where the server logs should be output. This does not affect output on the console.|string||
 |`--log-filters`|List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details.|array||
-|`--log-level`|The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively.|string|`debug`|
+|`--log-level`|The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively.|string|`info`|
 |`--log-format`|The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors.|string|`text`|
 |`--log-no-colors`|Disable colors in the server log|boolean|`false`|
 |`--log-timestamp`|Show timestamps in the server log|boolean|`false`|
@@ -51,7 +52,6 @@ appium
 |`--max-ipc-data-size`|Maximum byte size of IPC message objects.|integer|`1048576` (1MB)|
 |`--max-ipc-topics`|Maximum number of IPC topics per session.|integer|`1000`|
 |`--no-perms-check`|Skip various permission checks on the server startup|boolean|`false`|
-|`--nodeconfig`|JSON configuration for registering Appium as a node with Selenium Grid 3|object||
 |`--plugin`|Plugin-specific configuration. Keys should correspond to plugin package names|object||
 |`--plugins-import-chunk-size`|Maximum number of plugins that can be imported in parallel on server startup|number|`7`|
 |`--port`, `-p`|Port to listen on|integer|`4723`|
@@ -64,7 +64,7 @@ appium
 |`--tmp`|Absolute path to the directory used for temporary files|string|[`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir)|
 |`--use-drivers`|List of drivers to activate. By default, all installed drivers are activated.|array<string>|`[]`|
 |`--use-plugins`|List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins.|array<string>|`[]`|
-|`--webhook`, `-G`|URL for an HTTP listener where the server logs should be output. This does not affect output on the console.|string||
+|`--webhook`, `-G`|URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`.|string||
 
 ### Info Options
 

packages/appium/docs/en/reference/cli/setup.md

@@ -32,7 +32,7 @@ appium setup browser
 
 Installs the following extensions for desktop application testing:
 
-* Drivers: `mac2`[^1], `windows`[^2]
+* Drivers: `mac2`[^1], `wincore`[^2]
 * Plugins: `images`, `inspector`
 
 #### Usage

packages/appium/docs/en/reference/session/caps.md

@@ -32,7 +32,6 @@ default value.
 | <div style="width:19em">Capability</div> | Description | Type | Default |
 |--|--|--|--|
 | `webSocketUrl` | Toggle support of the WebDriver BiDi protocol | `boolean` ||
-| `appium:eventTimings` (deprecated) | Toggle collection of [Event Timings](../../guides/event-timing.md). This capability is deprecated - please use the [`getLogEvents`](../api/appium.md#getlogevents) endpoint instead. | `boolean` ||
 | `appium:newCommandTimeout` | Number of seconds the Appium server should wait for clients to send commands before stopping the session. A value of `0` disables the timeout. | `number` | `60` |
 | `appium:printPageSourceOnFindFailure` | Toggle retrieval of the the page source and its printing to the Appium log, whenever a request to find an element fails | `boolean` ||
 

packages/appium/docs/en/resources/index.md

@@ -8,11 +8,6 @@ title: Additional Resources
 
 Here you can find links to additional Appium resources around the web:
 
-## Websites
-
-- [Appium Pro](https://appiumpro.com) - a blog and newsletter written by one of Appium's
-maintainers, Jonathan Lipps, with lots of useful guides
-
 ## Online Courses
 
 - [Appium and Selenium Fundamentals](https://ui.headspin.io/university/learn/appium-selenium-fundamentals-2020) - a comprehensive video course on learning Python, Selenium, and Appium by Jonathan Lipps
@@ -26,3 +21,4 @@ maintainers, Jonathan Lipps, with lots of useful guides
 - [AppiumConf 2021](https://www.youtube.com/playlist?list=PL9Z-JgiTsOYRCcJhDfmKAah9XmAp2b903)
 - [AppiumConf 2024](https://www.youtube.com/playlist?list=PL9Z-JgiTsOYQaU5i5LJtAWlh5WVZPi3If)
 - [SeleniumConf & AppiumConf 2025](https://www.youtube.com/playlist?list=PLRdSclUtJDYV2R92TLbmwxws6clruuTjH)
+- [SeleniumConf & AppiumConf 2026](https://www.youtube.com/playlist?list=PLRdSclUtJDYVgVqdKnSyBLBmFdA0KE_Dk)

packages/appium/docs/ja/blog/.authors.yml

@@ -17,3 +17,8 @@ authors:
     avatar: 'https://avatars.githubusercontent.com/u/4045041?v=4'
     slug: 'sai'
     url: 'https://saikrishna.tech'
+  mykola:
+    name: 'Mykola Mokhnach'
+    description: 'Appium Core Maintainer'
+    avatar: https://avatars.githubusercontent.com/u/7767781?v=4
+    slug: 'mykola'

packages/appium/docs/ja/blog/posts/announcing-lambdatest-as-development-partner.md

@@ -8,11 +8,13 @@ date: 2025-11-25
 # Announcing LambdaTest as Appium's Newest Development Partner
 
 As part of our ongoing effort to recognize organizations that meaningfully support the Appium project through dedicated maintainer time, we are excited to welcome our newest Development Partner: LambdaTest!
-LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
-This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
 
 <!-- more -->
 
+LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
+
+This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
+
 <div style="text-align:center;width:100%"><a href="https://lambdatest.com/?utm_source=appium.io&utm_medium=organic&utm_campaign=june_25&utm_term=sk&utm_content=webpage">
     <img src="/docs/en/latest/assets/images/sponsor-logo-lambdatest-dark.png#only-dark" width="300" />
     <img src="/docs/en/latest/assets/images/sponsor-logo-lambdatest-light.png#only-light" width="300" />
@@ -20,15 +22,19 @@ This kind of hands-on contribution is crucial for ensuring Appium continues to e
 </div>
 
 LambdaTest engineers are already contributing actively across several key Appium repositories. Their current focus includes:
-**appium-mcp** – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
-**appium-remote-xpc** – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
-**appium-tun-tap** – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
+
+- [`appium-mcp`](https://github.com/appium/appium-mcp) – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
+- [`appium-ios-remotexpc`](https://github.com/appium/appium-ios-remotexpc) – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
+- [`appium-ios-tuntap`](https://github.com/appium/appium-ios-tuntap) – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
 
 These contributions strengthen critical infrastructure within the Appium ecosystem and demonstrate LambdaTest's commitment to deep technical involvement in the project's evolution.
-About LambdaTest
+
+**About LambdaTest**
 
 LambdaTest’s platform already serves a massive community of Appium users. As a GenAI-powered Quality Engineering Platform, they provide a full-stack testing cloud with 10,000+ real mobile devices and 3,000+ browsers.
+
 Beyond standard infrastructure, they are pushing the boundaries of test execution with AI-native test management and next-generation agents like KaneAI. By supporting Appium alongside Selenium, Playwright, and other major frameworks, LambdaTest helps teams orchestrate intelligent automation at cloud scale.
 
 LambdaTest will continue contributing people, code, and development expertise to strengthen Appium's core functionality. Their commitment represents a significant investment into the future of the framework, and we're thrilled to have them collaborating with us at this deeper level.
+
 The Appium project is proud to recognize LambdaTest as our newest official Development Partner. We can't wait to see what we'll build together!

packages/appium/docs/ja/blog/posts/announcing-watchos-simulator-support.md

@@ -0,0 +1,38 @@
+---
+authors:
+  - mykola
+date: 2026-09-01
+---
+
+# Announcing watchOS Simulator Support in the XCUITest Driver
+
+We’re excited to announce that the XCUITest driver now supports automation of watchOS apps — a
+platform that’s been on Appium’s requested list for a long time.
+
+<!-- more -->
+
+In order to automate watchOS, you'll need the following:
+
+- XCUITest driver version 12.6.0 or later (WebDriverAgent 16.5.0 or later)
+- Xcode 15.4 or later
+- watchOS 10 or later
+
+Important to note: ^^the driver currently only works with simulators — real devices are not
+compatible.^^
+
+The good news: automating a watchOS app looks just like automating any other iOS/iPadOS app. The
+standard use-cases of finding and clicking on elements, retrieving the page source, using the
+Appium Inspector — all work as usual. The one exception here is standard W3C gesture/touch actions
+(tap/swipe via the Actions API), which are not supported.
+
+On top of that, a few watchOS-specific extensions are available:
+
+- `mobile: pressButton` — press the Digital Crown or Action button
+- `mobile: rotateDigitalCrown` — rotate the Digital Crown (since driver version 12.7.0)
+- `mobile: performHandGesture` — perform double-tap or wrist flick hand gestures (since driver
+  version 12.7.0)
+
+For full setup instructions, capabilities, and limitations, check out the
+[watchOS guide](https://appium.github.io/appium-xcuitest-driver/latest/guides/watchos/).
+
+Happy testing!

packages/appium/docs/ja/developing/build-drivers.md

@@ -222,17 +222,24 @@ So you'll probably end up overriding `createSession`. You can do so by defining
 driver:
 
 ```js
-async createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData) {
-    const [sessionId, caps] = super.createSession(w3cCaps);
+async createSession(w3cCaps) {
+    const [sessionId, caps] = await super.createSession(w3cCaps);
     // do your own stuff here
     return [sessionId, caps];
 }
 ```
 
-For legacy reasons, your function will receive old-style JSON Wire Protocol desired and required
-caps as the first two arguments. Given that the old protocol isn't supported anymore and clients
-have all been updated, you can instead only rely on the `w3cCaps` parameter. (For a discussion
-about what `otherDriverData` is about, see the section below on concurrent drivers).
+!!! warning "Deprecated"
+
+```
+Older drivers may still define `createSession` with up to four parameters, e.g.
+`createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData)`. This shape is a holdover from the
+retired JSON Wire Protocol, which required desired and required caps as the first two
+arguments; only the first W3C-shaped argument was ever used. The `otherDriverData` parameter is
+likewise deprecated in favor of [IPC](#send-messages-to-plugins-running-on-the-same-session) for
+coordinating with other concurrently-running sessions. New drivers should use the single-argument
+form shown above.
+```
 
 You'll want to make sure to call `super.createSession` in order to get the session ID as well as
 the processed capabilities (note that capabilities are also set on `this.caps`; modifying `caps`
@@ -522,14 +529,13 @@ route, then the route will not be proxied and instead will be handled by your dr
 example, we are avoiding proxying all `POST` routes that have the `appium` prefix.
 
 Next, we have to set up the proxying itself. The way to do this is to use a special class from
-Appium called `JWProxy`. (The name means "JSON Wire Proxy" and is related to a legacy
-implementation of the protocol). You'll want to create a `JWProxy` object using the details required to
-connect to the remote server:
+Appium called `WebDriverProxy`. You'll want to create a `WebDriverProxy` object using the details
+required to connect to the remote server:
 
 ```js
-// import {JWProxy} from 'appium/driver';
+// import {WebDriverProxy} from 'appium/driver';
 
-const proxy = new JWProxy({
+const proxy = new WebDriverProxy({
     server: 'remote.server',
     port: 1234,
     base: '/',
@@ -541,8 +547,8 @@ this.proxyCommand = proxy.command.bind(proxy);
 
 Here we are creating a proxy object and assigning some of its methods to `this` under the names
 `proxyReqRes` and `proxyCommand`. This is required for Appium to use the proxy, so don't forget
-this step! The `JWProxy` has a variety of other options which you can check out in the source code,
-as well. (TODO: publish options as API docs and link here).
+this step! The `WebDriverProxy` has a variety of other options which you can check out in the
+source code as well.
 
 Finally, we need a way to tell Appium when the proxy is active. For your driver it might always
 be active, or it might only be active when in a certain context. You can define the logic as an
@@ -799,6 +805,14 @@ that multiple simultaneous sessions don't use the same resources:
 3. Have each driver express what resources it is using, then examine currently-used resources from
    other drivers when a new session begins.
 
+!!! warning "Deprecated"
+
+```
+The `driverData`-based mechanism described below is deprecated. Prefer
+[IPC](#send-messages-to-plugins-running-on-the-same-session) for coordinating resources across
+concurrently-running sessions instead.
+```
+
 To support this third strategy, you can implement `get driverData` in your driver to return what
 sorts of resources your driver is currently using, for example:
 
@@ -810,7 +824,7 @@ get driverData() {
 
 Now, when a new session is started on your driver, the `driverData` response from any other
 simultaneously running drivers (of the same type) will also be included, as the last parameter of
-the `createSession` method:
+the deprecated, multi-argument form of the `createSession` method:
 
 ```js
 async createSession(jwpCaps, reqCaps, w3cCaps, driverData)

packages/appium/docs/ja/developing/build-plugins.md

@@ -483,9 +483,9 @@ capability.
 You probably don't normally need to update the Appium server object (which is an
 [Express](https://expressjs.com/) server having already been
 [configured](https://github.com/appium/appium/blob/master/packages/base-driver/lib/express/server.js)
-in a variety of ways). But, for example, you could add new Express middleware to the server to
-support your plugin's requirements. To update the server you must implement the `static async
-updateServer` method in your class. This method takes three parameters:
+in a variety of ways). But, for example, you could add new routes to the server to support your
+plugin's requirements. To update the server you must implement the `static async updateServer`
+method in your class. This method takes three parameters:
 
 - `expressApp`: the Express app object
 - `httpServer`: the Node HTTP server object
@@ -498,6 +498,25 @@ results you'll need to test! Warning: this should be considered an advanced feat
 knowledge of Express, as well as the care not to do anything that could affect the operation of
 other parts of the Appium server!
 
+`updateServer` runs _after_ Appium's own routes are registered, so `expressApp.use(...)` here
+won't see requests to paths Appium already owns — Express matches middleware and routes in
+registration order. For middleware that must see requests to those routes too (e.g. logging or
+auth), use `httpServer.frontRouter` instead: Appium mounts this
+[Router](https://expressjs.com/en/5x/api/router/) before any route is registered, so anything
+attached to it — even from inside `updateServer` — still runs ahead of route matching. Note this
+is still _after_ Appium's own baseline middleware (CORS, WebSocket upgrade handling, body
+parsing, etc.), so it won't see requests Appium itself has already rejected, e.g. a CORS
+preflight failure or a body that failed to parse:
+
+```js
+static async updateServer(expressApp, httpServer, cliArgs) {
+  httpServer.frontRouter.use((req, res, next) => {
+    console.log(`Incoming request: ${req.method} ${req.url}`);
+    next();
+  });
+}
+```
+
 ### Handle unexpected session shutdown
 
 When developing a plugin you may want to add some cleanup logic for when a session ends. You would

packages/appium/docs/ja/ecosystem/drivers.md

@@ -130,7 +130,7 @@ appium driver install --source=npm appium-flutter-integration-driver
 appium driver install --source=npm appium-lg-webos-driver
 ```
 
-### [Linux](https://github.com/fantonglang/appium-linux-driver)
+### [Linux (@fantonglang)](https://github.com/fantonglang/appium-linux-driver)
 
 !!! warning
 
@@ -149,6 +149,16 @@ yarn install
 node ./
 ```
 
+### [Linux (@Itsmeaj)](https://github.com/Itsmeaj/appium)
+
+- Target: Linux desktop applications on X11 and Wayland
+- Mode: Native
+- Supported by: `@Itsmeaj`
+
+```sh title="Install This Driver"
+appium driver install --source=npm @itsmeaj/appium-linux-driver
+```
+
 ### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
 
 !!! info

packages/appium/docs/ja/reference/api/appium.md

@@ -107,6 +107,48 @@ Retrieves the [execute methods](../../guides/execute-methods.md) supported in th
 origin (driver-specific or plugin-specific). Refer to [the type definition file](https://github.com/appium/appium/blob/master/packages/types/lib/command.ts)
 for a detailed structure of this object.
 
+### getCurrentAppiumContext
+
+```
+GET /session/:sessionId/appium/context
+```
+
+Retrieves the active application context.
+
+#### Response
+
+`string` - the name of the active context
+
+### setAppiumContext
+
+```
+POST /session/:sessionId/appium/context
+```
+
+Sets an application context as the active context.
+
+#### Parameters
+
+| Name   | Description                                  | Type   |
+| ------ | -------------------------------------------- | ------ |
+| `name` | Name of the context to set as the active one | string |
+
+#### Response
+
+`null`
+
+### getAppiumContexts
+
+```
+GET /session/:sessionId/appium/contexts
+```
+
+Retrieves all available application contexts.
+
+#### Response
+
+`string[]` - the names of available contexts
+
 ### getLogEvents
 
 ```
@@ -393,3 +435,71 @@ Retrieves data from a directory on the device under test.
 #### Response
 
 `string` - the Base64-encoded zip file of the directory contents
+
+### getAppiumRotation
+
+```
+GET /session/:sessionId/appium/device/rotation
+```
+
+Retrieves the current spatial orientation of the device under test.
+
+#### Response
+
+`Rotation` - an object with the following properties:
+
+| Name | Description                                          | Type   |
+| ---- | ---------------------------------------------------- | ------ |
+| `x`  | Degrees by which the device is rotated on its X axis | number |
+| `y`  | Degrees by which the device is rotated on its Y axis | number |
+| `z`  | Degrees by which the device is rotated on its Z axis | number |
+
+### setAppiumRotation
+
+```
+POST /session/:sessionId/appium/device/rotation
+```
+
+Sets the spatial orientation of the device under test.
+
+#### Parameters
+
+| Name | Description                                          | Type   |
+| ---- | ---------------------------------------------------- | ------ |
+| `x`  | Degrees by which the device is rotated on its X axis | number |
+| `y`  | Degrees by which the device is rotated on its Y axis | number |
+| `z`  | Degrees by which the device is rotated on its Z axis | number |
+
+#### Response
+
+`null`
+
+### getAppiumOrientation
+
+```
+GET /session/:sessionId/appium/device/orientation
+```
+
+Retrieves the current orientation of the device under test.
+
+#### Response
+
+`string` - either `PORTRAIT` or `LANDSCAPE`
+
+### setAppiumOrientation
+
+```
+POST /session/:sessionId/appium/device/orientation
+```
+
+Sets the orientation of the device under test.
+
+#### Parameters
+
+| Name          | Description                                                                                             | Type   |
+| ------------- | ------------------------------------------------------------------------------------------------------- | ------ |
+| `orientation` | New device orientation. Supported values are `PORTRAIT` or `LANDSCAPE`. | string |
+
+#### Response
+
+`null`

packages/appium/docs/ja/reference/api/jsonwp.md

@@ -140,6 +140,10 @@ GET /session/:sessionId/orientation
 
 Retrieves the current orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumOrientation`](./appium.md#getappiumorientation) instead
+
 #### Response
 
 `string` - either `PORTRAIT` or `LANDSCAPE`
@@ -154,6 +158,10 @@ POST /session/:sessionId/orientation
 
 Sets the orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumOrientation`](./appium.md#setappiumorientation) instead
+
 #### Parameters
 
 | Name          | Description                                                                                             | Type   |

packages/appium/docs/ja/reference/api/mjsonwp.md

@@ -21,6 +21,10 @@ GET /session/:sessionId/rotation
 
 Retrieves the current spatial orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumRotation`](./appium.md#getappiumrotation) instead
+
 #### Response
 
 `Rotation` - an object with the following properties:
@@ -41,6 +45,10 @@ POST /session/:sessionId/rotation
 
 Sets the spatial orientation of the device under test.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumRotation`](./appium.md#setappiumrotation) instead
+
 #### Parameters
 
 | Name | Description                                          | Type   |
@@ -63,6 +71,10 @@ GET /session/:sessionId/context
 
 Retrieves the active application context.
 
+!!! warning "Deprecated"
+
+    Please use [`getCurrentAppiumContext`](./appium.md#getcurrentappiumcontext) instead
+
 #### Response
 
 `string` - the name of the active context
@@ -77,6 +89,10 @@ POST /session/:sessionId/context
 
 Sets an application context as the active context.
 
+!!! warning "Deprecated"
+
+    Please use [`setAppiumContext`](./appium.md#setappiumcontext) instead
+
 #### Parameters
 
 | Name   | Description                                  | Type   |
@@ -97,6 +113,10 @@ GET /session/:sessionId/contexts
 
 Retrieves all available application contexts.
 
+!!! warning "Deprecated"
+
+    Please use [`getAppiumContexts`](./appium.md#getappiumcontexts) instead
+
 #### Response
 
 `string[]` - the names of available contexts

packages/appium/docs/ja/reference/api/plugins.md

@@ -170,10 +170,17 @@ Modifies the [`createSession`](./webdriver.md#createsession) endpoint:
     All endpoints for this plugin can be invoked without creating a session, allowing you to prepare
     your test environment in advance.
 
+!!! info
+
+    Prior to plugin version 1.2.0, all endpoints below were mounted under the `/storage` prefix
+    (e.g. `/storage/add`) instead of `/appium/storage`. The `/storage`-prefixed routes are still
+    available for backward compatibility, but are deprecated and will be removed in a future
+    version of the plugin.
+
 ### addStorageItem
 
 ```
-POST /storage/add
+POST /appium/storage/add
 ```
 
 Adds a new file to the storage.
@@ -200,8 +207,8 @@ Example:
 ```json
 {
   "ws": {
-    "stream": "/storage/add/ccc963411b2621335657963322890305ebe96186/stream",
-    "events": "/storage/add/ccc963411b2621335657963322890305ebe96186/events"
+    "stream": "/appium/storage/add/ccc963411b2621335657963322890305ebe96186/stream",
+    "events": "/appium/storage/add/ccc963411b2621335657963322890305ebe96186/events"
   },
   "ttlMs": 300000
 }
@@ -210,7 +217,7 @@ Example:
 ### deleteStorageItem
 
 ```
-POST /storage/delete
+POST /appium/storage/delete
 ```
 
 Deletes a file in the storage.
@@ -224,12 +231,12 @@ Deletes a file in the storage.
 #### Response
 
 `boolean` - `true` upon successful file deletion, or `false` if the file does not exist in
-the storage
+the storage, or if the delete request is invalid.
 
 ### listStorageItems
 
 ```
-GET /storage/list
+GET /appium/storage/list
 ```
 
 List all files present in the storage.
@@ -247,7 +254,7 @@ List all files present in the storage.
 ### resetStorage
 
 ```
-POST /storage/reset
+POST /appium/storage/reset
 ```
 
 Deletes all uploaded files and stops any incomplete uploads.

packages/appium/docs/ja/reference/cli/extensions.md

@@ -14,6 +14,12 @@ Provides management options for a specific extension (driver or plugin). Both th
 The following sub-subcommands are supported: `doctor`, `install`, `list`, `run`, `update`,
 and `uninstall`.
 
+For `doctor`, `run`, `update`, and `uninstall`, you can identify an installed extension by its
+short name or its exact npm package name. For example, `appium driver uninstall uiautomator2`
+and `appium driver uninstall appium-uiautomator2-driver` refer to the same installed driver.
+Short names take precedence if a name also matches another extension's package name. Package names
+can include a scope, such as `@appium/fake-driver`, but must not include a version or tag suffix.
+
 ## `doctor`
 
 Runs doctor checks for an installed extension, which validate whether the extension has its prerequisites
@@ -30,9 +36,9 @@ configured correctly. Note that not all extensions include doctor checks.
 appium {driver|plugin} doctor <extension-name>
 ```
 
-| Argument         | Description                               |
-| ---------------- | ----------------------------------------- |
-| `extension-name` | The short name of the installed extension |
+| Argument         | Description                                                         |
+| ---------------- | ------------------------------------------------------------------- |
+| `extension-name` | The short name or exact npm package name of the installed extension |
 
 #### Options
 
@@ -159,14 +165,14 @@ extensions include scripts.
 #### Usage
 
 ```
-appium {driver|plugin} run <extension-name> <script-name> [script-args]
+appium {driver|plugin} run <extension-name> [<script-name> [<script-args>]]
 ```
 
-| Argument         | Description                                   |
-| ---------------- | --------------------------------------------- |
-| `extension-name` | The short name of the installed extension     |
-| `script-name`    | The name of the script to be run              |
-| `script-args`    | Any additional arguments passed to the script |
+| Argument         | Description                                                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `extension-name` | The short name or exact npm package name of the installed extension                                                      |
+| `script-name`    | The name of the script to run. If not provided, a list of available scripts is returned. |
+| `script-args`    | Any additional arguments passed to the script                                                                            |
 
 #### Options
 
@@ -182,6 +188,12 @@ appium {driver|plugin} run <extension-name> <script-name> [script-args]
     appium driver run uiautomator2 reset
     ```
 
+- List all available scripts included in the XCUITest driver:
+
+    ```
+    appium driver run xcuitest
+    ```
+
 ## `update`
 
 Updates one or more extensions. Only supported for extensions installed via `npm`. By default,
@@ -193,9 +205,9 @@ Appium will only update minor and patch versions, in order to prevent any breaki
 appium {driver|plugin} update <extension-name>
 ```
 
-| Argument         | Description                                                                                  |
-| ---------------- | -------------------------------------------------------------------------------------------- |
-| `extension-name` | The short name of the installed extension, or `installed` to update all installed extensions |
+| Argument         | Description                                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `extension-name` | The short name or exact npm package name of the installed extension, or `installed` to update all installed extensions |
 
 #### Options
 
@@ -228,9 +240,9 @@ Removes an installed extension.
 appium {driver|plugin} uninstall <extension-name>
 ```
 
-| Argument         | Description                               |
-| ---------------- | ----------------------------------------- |
-| `extension-name` | The short name of the installed extension |
+| Argument         | Description                                                         |
+| ---------------- | ------------------------------------------------------------------- |
+| `extension-name` | The short name or exact npm package name of the installed extension |
 
 #### Options
 

packages/appium/docs/ja/reference/cli/server.md

@@ -29,6 +29,7 @@ appium
 | `--address`, `-a`                      | IPv4/IPv6 address to listen on                                                                                                                                                                                                                                                                                                                     | string        | `0.0.0.0`                                                |
 | `--allow-cors`                         | Allow web browser connections from any host                                                                                                                                                                                                                                                                                                        | boolean       | `false`                                                  |
 | `--allow-insecure`                     | List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`.                                                                        | array<string> | `[]`                                                     |
+| `--allow-unknown-args`                 | Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags.                                                                                                                              | boolean       | `false`                                                  |
 | `--base-path`, `-pa`                   | Base path to use as the prefix for all webdriver routes running on the server                                                                                                                                                                                                                                                                      | string        | `""`                                                     |
 | `--callback-address`, `-ca`            | Callback IP address                                                                                                                                                                                                                                                                                                                                | string        | `0.0.0.0`                                                |
 | `--callback-port`, `-cp`               | Callback port                                                                                                                                                                                                                                                                                                                                      | integer       | `4723`                                                   |
@@ -64,7 +65,7 @@ appium
 | `--tmp`                                | Absolute path to the directory used for temporary files                                                                                                                                                                                                                                                                                            | string        | [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir) |
 | `--use-drivers`                        | List of drivers to activate. By default, all installed drivers are activated.                                                                                                                                                                                                                                      | array<string> | `[]`                                                     |
 | `--use-plugins`                        | List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins.                                                                                                                                                                             | array<string> | `[]`                                                     |
-| `--webhook`, `-G`                      | URL for an HTTP listener where the server logs should be output. This does not affect output on the console.                                                                                                                                                                                                       | string        |                                                          |
+| `--webhook`, `-G`                      | URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`.                | string        |                                                          |
 
 ### Info Options
 

packages/appium/docs/ja/resources/index.md

@@ -8,11 +8,6 @@ title: Additional Resources
 
 Here you can find links to additional Appium resources around the web:
 
-## Websites
-
-- [Appium Pro](https://appiumpro.com) - a blog and newsletter written by one of Appium's
-  maintainers, Jonathan Lipps, with lots of useful guides
-
 ## Online Courses
 
 - [Appium and Selenium Fundamentals](https://ui.headspin.io/university/learn/appium-selenium-fundamentals-2020) - a comprehensive video course on learning Python, Selenium, and Appium by Jonathan Lipps
@@ -26,3 +21,4 @@ Here you can find links to additional Appium resources around the web:
 - [AppiumConf 2021](https://www.youtube.com/playlist?list=PL9Z-JgiTsOYRCcJhDfmKAah9XmAp2b903)
 - [AppiumConf 2024](https://www.youtube.com/playlist?list=PL9Z-JgiTsOYQaU5i5LJtAWlh5WVZPi3If)
 - [SeleniumConf & AppiumConf 2025](https://www.youtube.com/playlist?list=PLRdSclUtJDYV2R92TLbmwxws6clruuTjH)
+- [SeleniumConf & AppiumConf 2026](https://www.youtube.com/playlist?list=PLRdSclUtJDYVgVqdKnSyBLBmFdA0KE_Dk)

packages/appium/docs/mkdocs-en.yml

@@ -57,6 +57,7 @@ nav:
           - reference/api/plugins.md
   - Guides:
       - Migration:
+          - guides/migrating-3-to-4.md
           - guides/migrating-2-to-3.md
           - guides/migrating-1-to-2.md
       - Server/Driver Configuration:

packages/appium/docs/overrides/main.html

@@ -1,8 +0,0 @@
-{% extends "base.html" %}
-
-{% block announce %}
-    <center>
-    SeleniumConf & AppiumConf returns on May 6-8, 2026! Join us to learn and connect with the community!
-    <a href="https://seleniumconf.com/">Register Now</a>
-    </center>
-{% endblock %}

packages/appium/docs/scripts/build-docs.js

@@ -10,19 +10,16 @@
 /* eslint-disable promise/prefer-await-to-callbacks */
 /* eslint-disable promise/prefer-await-to-then */
 
-const {deploy, buildSite} = require('@appium/docutils');
-const {
-  log,
-  LANGS,
-  DOCS_DIR,
-  DOCS_BRANCH,
-  DOCS_PREFIX,
-  DOCS_REMOTE,
-  LATEST_ALIAS,
-} = require('./utils');
-const path = require('node:path');
-const semver = require('semver');
-const {version} = require('../../package.json');
+import {readFileSync} from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {deploy, buildSite} from '@appium/docutils';
+import semver from 'semver';
+
+import {log, LANGS, DOCS_DIR, DOCS_BRANCH, DOCS_PREFIX, DOCS_REMOTE, LATEST_ALIAS} from './utils.js';
+
+const {version} = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 
 const branch = process.env.APPIUM_DOCS_BRANCH ?? DOCS_BRANCH;
 const basePrefix = process.env.APPIUM_DOCS_PREFIX ?? DOCS_PREFIX;
@@ -67,10 +64,10 @@ async function main() {
   }
 }
 
-if (require.main === module) {
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
   main().catch((err) => {
     throw err;
   });
 }
 
-module.exports = main;
+export default main;

packages/appium/docs/scripts/gen-cli-args-docs.js

@@ -3,11 +3,14 @@
 /* eslint-disable promise/prefer-await-to-callbacks */
 /* eslint-disable promise/prefer-await-to-then */
 
-const path = require('node:path');
-const {fs} = require('@appium/support');
-const {AppiumConfigJsonSchema} = require('@appium/schema');
+import {realpathSync} from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
 
-const DOC_PATH = path.resolve(__dirname, '..', 'en', 'cli', 'args.md');
+import {AppiumConfigJsonSchema} from '@appium/schema';
+import {fs} from '@appium/support';
+
+const DOC_PATH = path.resolve(import.meta.dirname, '..', 'en', 'cli', 'args.md');
 
 const START_TAG = `<!-- AUTOGEN-START -->`;
 const STOP_TAG = `<!-- AUTOGEN-STOP -->`;
@@ -89,10 +92,10 @@ async function writeNewDoc(preStart, argTable, postEnd) {
   await fs.writeFile(DOC_PATH, newContents);
 }
 
-if (require.main === module) {
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
   main().catch((err) => {
     throw err;
   });
 }
 
-module.exports = main;
+export default main;

packages/appium/docs/scripts/utils.js

@@ -2,28 +2,19 @@
 
 // for simplicity this file is not transpiled and is run directly via an npm script
 //
-const {logger} = require('@appium/support');
-const path = require('node:path');
+import path from 'node:path';
+
+import {logger} from '@appium/support';
 
 const log = logger.getLogger('Docs');
 
 const DOCS_REMOTE = 'origin';
 const DOCS_BRANCH = 'gh-pages';
 const DOCS_PREFIX = 'docs';
-const DOCS_DIR = path.resolve(__dirname, '..');
+const DOCS_DIR = path.resolve(import.meta.dirname, '..');
 const LATEST_ALIAS = 'latest';
 const ASSETS_DIR = path.join(DOCS_DIR, 'assets');
 const LANGS = ['en', 'ja', 'zh'];
 const DEFAULT_LANG = 'en';
 
-module.exports = {
-  log,
-  DOCS_DIR,
-  ASSETS_DIR,
-  LANGS,
-  DEFAULT_LANG,
-  DOCS_BRANCH,
-  DOCS_PREFIX,
-  DOCS_REMOTE,
-  LATEST_ALIAS,
-};
+export {log, DOCS_DIR, ASSETS_DIR, LANGS, DEFAULT_LANG, DOCS_BRANCH, DOCS_PREFIX, DOCS_REMOTE, LATEST_ALIAS};

packages/appium/docs/zh/blog/.authors.yml

@@ -17,3 +17,8 @@ authors:
     avatar: 'https://avatars.githubusercontent.com/u/4045041?v=4'
     slug: 'sai'
     url: 'https://saikrishna.tech'
+  mykola:
+    name: 'Mykola Mokhnach'
+    description: 'Appium Core Maintainer'
+    avatar: https://avatars.githubusercontent.com/u/7767781?v=4
+    slug: 'mykola'

packages/appium/docs/zh/blog/posts/announcing-appiumconf2024.md

@@ -5,9 +5,9 @@ authors:
 date: 2024-07-13
 ---
 
-# Appium Conf 2024: Call for Proposals Now Open!
+# Appium Conf 2024: 现在开始征集提案
 
-We're thrilled to announce that Appium Conf is back and going online for 2024! This is the official Appium conference where you can learn all about what's new in Appium 2.0 and explore the latest in automating tests for devices, mobile apps, and desktop applications.
+我们很兴奋地宣布，Appium Conf 已回归并在2024年上线！ 这是官方的Appium会议，您可以在会上了解Appium 2中的所有新内容。 并探索设备自动化测试、移动应用程序和桌面应用程序的最新版本。
 
 <!-- more -->
 
@@ -17,29 +17,29 @@ We're thrilled to announce that Appium Conf is back and going online for 2024! T
 </a>
 </div>
 
-## Mark Your Calendars: September 13, 2024
+## 标记您的日历：2024年9月13日
 
-Join us on September 13, 2024, for a full day of inspiring and practical talks from the Appium team and the world's top mobile testing and automation experts. With Appium 2.0 now well-established, this is your opportunity to dive deep and learn how to maximize its potential.
+2024年9月13日，请加入我们，参加Appium团队和世界顶级移动测试和自动化专家为期一天的鼓舞人心且实用的演讲。 随着Appium 2.0的成熟，这是您深入了解并学习如何最大限度地发挥其潜力的机会。
 
-## Why Attend Appium Conf 2024?
+## 为什么参加了2024年的Appium Conf ？
 
-1. **Gain Insights**: Hear interesting insights and inspiring case studies from global experts and the core Appium team.
-2. **Improve Your Strategy**: Gain valuable knowledge to enhance your own automation strategy.
-3. **Network**: Make connections with Appium users from around the globe.
-4. **Learn from Specialists**: Benefit from Appium specialists' expertise on a variety of topics.
+1. **获得见解**：听取全球专家和核心Appium团队的有趣见解和鼓舞人心的案例研究。
+2. **改进您的战略**：获得有价值的知识，以增强您自己的自动化战略。
+3. **网络**：与来自全球的Appium用户建立联系。
+4. **向专家学习**：从Appium专家在各种主题上的专业知识中受益。
 
-## Call for Proposals: Share Your Knowledge!
+## 征集提案：分享您的知识！
 
-We're looking for a diverse range of speakers from around the globe who are eager to share innovative ideas and use-cases of mobile test automation. If you have experience with Appium and insights that could benefit the community of test practitioners, we want to hear from you!
+我们正在寻找来自全球各地的各种演讲者，他们渴望分享移动测试自动化的创新想法和用例。 如果您有使用Appium的经验和见解，可以使测试从业者社区受益，我们想听听您的意见！
 
-Don't miss this chance to contribute to the Appium community and showcase your expertise on a global stage.
+不要错过这个机会，为Appium社区做出贡献，并在全球舞台上展示你的专业知识。
 
-## How to Submit Your Proposal
+## 如何提交您的提案
 
-Visit our website at [https://appiumconf.com/](https://appiumconf.com/) and [Submit a Proposal](https://confengine.com/conferences/appium-conf-2024/proposals?utm_medium=referal&utm_source=appium.io&utm_campaign=launch). We're excited to see your innovative ideas and experiences with Appium!
+访问我们的网站 [https://appiumconf.com/](https://appiumconf.com/) 并[提交提案](https://confengine.com/conferences/appium-conf-2024/proposals?utm_medium=referal&utm_source=appium.io&utm_campaign=launch)。 我们很高兴看到您在 Appium 中的创新想法和经验！
 
-## Stay Tuned
+## 敬请期待
 
-Keep an eye on our website and social media channels for updates on the conference schedule, keynote speakers, and more exciting details about Appium Conf 2024.
+关注我们的网站和社交媒体频道以了解会议日程安排的更新， 主旨演讲人和2024年Appium Conf 的更令人兴奋的细节。
 
-Join us in shaping the future of mobile and device test automation. Submit your proposal today and be part of this exciting event!
+加入我们来塑造移动设备测试自动化的未来。 立即提交您的提案，成为这一激动人心的活动的一部分！

packages/appium/docs/zh/blog/posts/announcing-lambdatest-as-development-partner.md

@@ -8,11 +8,13 @@ date: 2025-11-25
 # Announcing LambdaTest as Appium's Newest Development Partner
 
 As part of our ongoing effort to recognize organizations that meaningfully support the Appium project through dedicated maintainer time, we are excited to welcome our newest Development Partner: LambdaTest!
-LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
-This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
 
 <!-- more -->
 
+LambdaTest has long been an active participant in the automated testing ecosystem. Today, they are officially formalizing their commitment by investing people—dedicated engineers who will directly support Appium's development, maintenance, and ecosystem growth.
+
+This kind of hands-on contribution is crucial for ensuring Appium continues to evolve. We deeply value partners who empower their engineering teams to contribute code directly to open source rather than just sponsorship.
+
 <div style="text-align:center;width:100%"><a href="https://lambdatest.com/?utm_source=appium.io&utm_medium=organic&utm_campaign=june_25&utm_term=sk&utm_content=webpage">
     <img src="/docs/en/latest/assets/images/sponsor-logo-lambdatest-dark.png#only-dark" width="300" />
     <img src="/docs/en/latest/assets/images/sponsor-logo-lambdatest-light.png#only-light" width="300" />
@@ -20,15 +22,19 @@ This kind of hands-on contribution is crucial for ensuring Appium continues to e
 </div>
 
 LambdaTest engineers are already contributing actively across several key Appium repositories. Their current focus includes:
-**appium-mcp** – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
-**appium-remote-xpc** – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
-**appium-tun-tap** – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
+
+- [`appium-mcp`](https://github.com/appium/appium-mcp) – Supporting Appium's implementation of the Model Context Protocol (MCP) to drive forward modern AI-assisted capabilities.
+- [`appium-ios-remotexpc`](https://github.com/appium/appium-ios-remotexpc) – Contributing to the native macOS/XPC-based remote execution layer, essential for iOS automation.
+- [`appium-ios-tuntap`](https://github.com/appium/appium-ios-tuntap) – Assisting in the development and maintenance of network virtualization and tunneling components for advanced testing scenarios.
 
 These contributions strengthen critical infrastructure within the Appium ecosystem and demonstrate LambdaTest's commitment to deep technical involvement in the project's evolution.
-About LambdaTest
+
+**About LambdaTest**
 
 LambdaTest’s platform already serves a massive community of Appium users. As a GenAI-powered Quality Engineering Platform, they provide a full-stack testing cloud with 10,000+ real mobile devices and 3,000+ browsers.
+
 Beyond standard infrastructure, they are pushing the boundaries of test execution with AI-native test management and next-generation agents like KaneAI. By supporting Appium alongside Selenium, Playwright, and other major frameworks, LambdaTest helps teams orchestrate intelligent automation at cloud scale.
 
 LambdaTest will continue contributing people, code, and development expertise to strengthen Appium's core functionality. Their commitment represents a significant investment into the future of the framework, and we're thrilled to have them collaborating with us at this deeper level.
+
 The Appium project is proud to recognize LambdaTest as our newest official Development Partner. We can't wait to see what we'll build together!

packages/appium/docs/zh/blog/posts/announcing-watchos-simulator-support.md

@@ -0,0 +1,38 @@
+---
+authors:
+  - mykola
+date: 2026-09-01
+---
+
+# Announcing watchOS Simulator Support in the XCUITest Driver
+
+We’re excited to announce that the XCUITest driver now supports automation of watchOS apps — a
+platform that’s been on Appium’s requested list for a long time.
+
+<!-- more -->
+
+In order to automate watchOS, you'll need the following:
+
+- XCUITest driver version 12.6.0 or later (WebDriverAgent 16.5.0 or later)
+- Xcode 15.4 or later
+- watchOS 10 or later
+
+Important to note: ^^the driver currently only works with simulators — real devices are not
+compatible.^^
+
+The good news: automating a watchOS app looks just like automating any other iOS/iPadOS app. The
+standard use-cases of finding and clicking on elements, retrieving the page source, using the
+Appium Inspector — all work as usual. The one exception here is standard W3C gesture/touch actions
+(tap/swipe via the Actions API), which are not supported.
+
+On top of that, a few watchOS-specific extensions are available:
+
+- `mobile: pressButton` — press the Digital Crown or Action button
+- `mobile: rotateDigitalCrown` — rotate the Digital Crown (since driver version 12.7.0)
+- `mobile: performHandGesture` — perform double-tap or wrist flick hand gestures (since driver
+  version 12.7.0)
+
+For full setup instructions, capabilities, and limitations, check out the
+[watchOS guide](https://appium.github.io/appium-xcuitest-driver/latest/guides/watchos/).
+
+Happy testing!

packages/appium/docs/zh/developing/build-docs.md

@@ -1,84 +1,66 @@
 ---
-title: Building Documentation
+title: 构建文档
 ---
 
-Once you've [built a driver](./build-drivers.md) or [built a plugin](./build-plugins.md) for Appium,
-you will hopefully want to document how that extension works for your users. The most basic way of
-doing this is to write up a quick `README.md` and keep it in the root of your project's repository.
-However, this can involve a lot of effort.
+一旦你为 Appium 构建了 [驱动](./build-drivers.md) 或 [插件](./build-plugins.md)，通常也会希望为用户说明这个扩展是如何工作的。 最基础的方式就是编写一个简短的 `README.md`，并将它放在项目仓库的根目录中。
+不过，这样做可能会耗费不少精力。
 
-The Appium project has built tools to help with this, and we've packaged up these tools so our
-ecosystem developers building drivers and plugins can _also_ use them. The best way to get going
-with these tools is probably to look at an existing Appium driver repo to see how it's done, for
-example the [XCUITest driver repo](https://github.com/appium/appium-xcuitest-driver). But this guide
-will outline the basic approach.
+Appium 项目已经提供了辅助工具，并且我们把这些工具打包好了，以便生态系统中的驱动和插件开发者也能使用。 这些工具最好的入门方式是查看一个现有的 Appium 驱动仓库，看看它是如何组织文档的，例如 [XCUITest 驱动仓库](https://github.com/appium/appium-xcuitest-driver)。 不过，本指南会先介绍基本的实现思路。
 
-### Conceptual architecture
+### 概念架构
 
-Appium settled on [MkDocs](https://www.mkdocs.org/) as a Markdown-based documentation site
-generator. It uses a Python toolchain (and not Node.js), but it turned out to be the best option
-for our purposes. You can adjust this, but by default Appium's utilities also assume that you'll be
-using the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme/extension for
-MkDocs.
+Appium 采用 [MkDocs](https://www.mkdocs.org/) 作为基于 Markdown 的文档站点的生成工具。 它使用 Python 工具链（而不是 Node.js），但这恰好是我们当前需求下最合适的选择。 你可以自行调整，不过默认情况下，Appium 的工具链也会假设你使用 [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) 主题与扩展来搭建 MkDocs。
 
-In order to make different versions of your docs available (one for each minor release of your
-extension, typically), we also bundle [Mike](https://github.com/jimporter/mike).
+为了让你的文档能够支持不同版本（通常是每个小版本一个），我们还会捆绑 [Mike](https://github.com/jimporter/mike)。
 
-From here, building a basic docs site is as easy as collecting your Markdown files together and
-defining how you want them to be organized.
+从这里开始，构建一个基础文档站点其实很简单：把 Markdown 文件收集起来，再定义你希望它们如何组织即可。
 
-### Prerequisites
+### 前置条件
 
-To take advantage of Appium's documentation utilities, you'll need to install:
+要使用 Appium 的文档工具，你需要安装以下内容：
 
 - [Python v3+](https://www.python.org/downloads/)
-- [pip](https://pip.pypa.io/en/stable/installation/) (this may be installed automatically with Python)
-- The `@appium/docutils` package:
+- [pip](https://pip.pypa.io/en/stable/installation/)（通常 Python 会自动附带安装）
+- `@appium/docutils` 包：
 
   ```bash
   npm install --save-dev @appium/docutils
   ```
 
-### Initializing an Extension for Building Docs
+### 初始化用于构建文档的扩展
 
-To prepare your extension for generating documentation, run the following command:
+要为你的扩展准备文档生成环境，请运行下面的命令：
 
 ```bash
 npx appium-docs init
 ```
 
-This will:
+这一步会：
 
-1. Create a `tsconfig.json` if one does not already exist. This is necessary even if your extension
-   is not written in TypeScript.
-2. Create a `mkdocs.yml` with the necessary configuration for MkDocs.
+1. 创建一个 `tsconfig.json`（如果当前还没有的话）。 即使你的扩展并不是 TypeScript 编写的，这也是必需的。
+2. 创建一个 `mkdocs.yml`，其中包含 MkDocs 所需的配置。
 
-### Documenting Your Extension
+### 为你的扩展编写文档
 
-At this point, you can begin documenting your extension. By default, MkDocs will look for Markdown
-files in the `docs` directory. You can therefore create your Markdown documentation files, place
-them in `docs`, and add links to these files in `mkdocs.yml`.
+此时你就可以开始为扩展编写文档了。 默认情况下，MkDocs 会在 `docs` 目录中查找 Markdown 文件。 因此，你可以创建文档文件并放入 `docs`，然后在 `mkdocs.yml` 里添加相应链接。
 
-Refer to the [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/) for
-information on how to organize and structure your documentation.
+请参考 [MkDocs 文档](https://www.mkdocs.org/user-guide/writing-your-docs/) 来了解如何组织与构建你的文档结构。
 
-### Building the Docs
+### 构建文档
 
-At this point, you can use the `appium-docs` CLI tool. Run this tool with no arguments to get the
-full help output and see all the available subcommands and parameters. Here are a few usage
-examples:
+在这个阶段，你可以使用 `appium-docs` CLI 工具。 运行这个工具时不传任何参数，可以看到完整的帮助信息，以及所有可用的子命令与参数。 下面是几个常见用法示例：
 
 ```bash
-# Generate reference and build the mkdocs site into the site dir
+# 生成参考文档并将 mkdocs 站点构建到 site 目录
 npx appium-docs build
 
-# Same as build, but host the docs on a local dev server
-# and watch for changes and rebuild when files change
+# 与 build 相同，但会在本地启动开发服务器
+# 并监听文件变化，在内容变更时自动重建
 npx appium-docs build --serve
 
-# Build the docs and deploy them with mike versioning to the docs-site branch
-# using the included commit message.
-# This is particularly useful for pushing content to a GitHub pages branch!
+# 构建文档并使用 mike 进行版本化部署到 docs-site 分支
+# 其中包含内置提交信息。
+# 这对于把内容推送到 GitHub Pages 分支特别有用！
 npx appium-docs build \
   --deploy \
   -b docs-site \

packages/appium/docs/zh/developing/build-doctor-checks.md

@@ -1,45 +1,33 @@
 ---
-title: Building Doctor Checks
+title: 构建 Doctor Checks
 ---
 
-The idea of Appium Doctor is to assist users with driver or plugin preconditions setup. Sometimes such
-preconditions might be quite complicated and require non-trivial technical knowledge. Doctor checks,
-which are vanilla Node.js class instances written by extension authors, simplify
-the setup process by automating diagnostics and possible fixes for the found issues. These checks
-might also be interactive to ensure better usage experience.
+Appium Doctor 的目标，是帮助用户完成驱动或插件的前置条件配置。 有时这些前置条件可能相当复杂，需要一定的技术知识。 Doctor checks是由扩展作者编写的普通 Node.js 类实例，它可以自动完成诊断并尝试修复发现的问题。 为了提供更好的使用体验，这些检查项有时也会是交互式的。
 
-This tutorial is supposed to be used by plugin or driver authors that would like to help their users
-to deal with complicated setup or configuration steps.
+本教程适用于希望帮助用户处理复杂配置或设置步骤的插件或驱动作者。
 
-## Adding Doctor Checks
+## 添加 Doctor Checks
 
-### Typing Requirements
+### 类型要求
 
-The term `Doctor Check` literally describes a single javascript class instance that implements the
-[IDoctorCheck interface](https://github.com/appium/appium/blob/master/packages/types/lib/doctor.ts).
-The interface defines the following methods and properties:
+术语 `Doctor Check` 的字面含义，是指一个实现了 [IDoctorCheck 接口](https://github.com/appium/appium/blob/master/packages/types/lib/doctor.ts) 的 JavaScript 类实例。
+这个接口定义了以下方法和属性：
 
-- `diagnose(): Promise<DoctorCheckResult>`: Contains the code to diagnose a possible issue
-- `fix(): Promise<string|null>`: Either fixes the actual problem if `hasAutofix()` returns true or
-  returns a string description for possible manual fixes. If this method throws an exception named
-  `FixSkippedError` and `hasAutofix()` returns true then the result of the method invocation
-  is going to be ignored.
-- `hasAutofix(): boolean`: Whether calling `fix()` would resolve the found issue
-- `isOptional(): boolean`: Whether the found issue can be ignored and is not a showstopper
-- `log: AppiumLogger`: May be used for logging. This property may be assigned
-  by the instance itself or by the Appium server if it is left unassigned.
+- `diagnose(): Promise<DoctorCheckResult>`：包含诊断某个问题的代码
+- `fix(): Promise<string|null>`：如果 `hasAutofix()` 返回 true，则修复实际问题；否则返回一段手动修复的说明。 如果此方法抛出名为 `FixSkippedError` 的异常，并且 `hasAutofix()` 返回 true，那么该调用结果将被忽略。
+- `hasAutofix(): boolean`：表示调用 `fix()` 是否能解决发现的问题
+- `isOptional(): boolean`：表示发现的问题是否可以被忽略且不是阻塞性问题
+- `log: AppiumLogger`：可用于日志输出。 这个属性可以由实例自行赋值，也可以由 Appium 服务在未赋值时自动提供。
 
-The `DoctorCheckResult` object returned by the `diagnose()` method must contain the following properties:
+`diagnose()` 方法返回的 `DoctorCheckResult` 对象必须包含以下属性：
 
-- `ok: boolean`: Whether the diagnosis found no issues
-- `optional: boolean`: Whether the diagnosed issue is safe to ignore
-- `message: string`: The text message describing the diagnostic result
+- `ok: boolean`：诊断是否未发现任何问题。
+- `optional: boolean`：诊断出的问题是否可以安全忽略。
+- `message: string`：描述诊断结果的文本信息。
 
-### Manifest Requirements
+### 清单要求
 
-A single extension may export multiple Doctor checks to Appium. In order for these checks to be properly
-picked up by the server CLI after the corresponding extension is installed they might be listed in the
-package .json manifest under the `appium.doctor.checks` section similar to the definition below:
+一个扩展可以向 Appium 导出多个 Doctor checks。 为了让这些检查项在对应扩展安装后能够被服务端 CLI 正确识别，它们需要在package .json 清单文件中列在 `appium.doctor.checks` 部分，格式类似下面这样：
 
 ```json
   // ...
@@ -67,12 +55,11 @@ package .json manifest under the `appium.doctor.checks` section similar to the d
   // ...
 ```
 
-Also, it makes sense to include the [@appium/types](https://www.npmjs.com/package/@appium/types) import
-to the package dev dependencies.
+此外，建议将 [@appium/types](https://www.npmjs.com/package/@appium/types) 加入包的开发依赖中。
 
-### Implementation Example
+### 实现示例
 
-The below example is a "raw" Node.JS implementation that does not use any transpilation:
+下面是一个“原生”的 Node.js 实现示例，没有使用任何转译工具：
 
 ```js
 const {fs, doctor} = require('@appium/support');
@@ -123,8 +110,7 @@ module.exports = {androidHomeCheck};
  */
 ```
 
-This file could be saved as `doctor/android-home-check.js` and then added to the package.json manifest
-as
+这个文件可以保存为 `doctor/android-home-check.js`，然后再将其加入到 package.json 清单中，例如：
 
 ```json
   // ...

packages/appium/docs/zh/developing/build-drivers.md

@@ -222,17 +222,24 @@ So you'll probably end up overriding `createSession`. You can do so by defining
 driver:
 
 ```js
-async createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData) {
-    const [sessionId, caps] = super.createSession(w3cCaps);
+async createSession(w3cCaps) {
+    const [sessionId, caps] = await super.createSession(w3cCaps);
     // do your own stuff here
     return [sessionId, caps];
 }
 ```
 
-For legacy reasons, your function will receive old-style JSON Wire Protocol desired and required
-caps as the first two arguments. Given that the old protocol isn't supported anymore and clients
-have all been updated, you can instead only rely on the `w3cCaps` parameter. (For a discussion
-about what `otherDriverData` is about, see the section below on concurrent drivers).
+!!! warning "Deprecated"
+
+```
+Older drivers may still define `createSession` with up to four parameters, e.g.
+`createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData)`. This shape is a holdover from the
+retired JSON Wire Protocol, which required desired and required caps as the first two
+arguments; only the first W3C-shaped argument was ever used. The `otherDriverData` parameter is
+likewise deprecated in favor of [IPC](#send-messages-to-plugins-running-on-the-same-session) for
+coordinating with other concurrently-running sessions. New drivers should use the single-argument
+form shown above.
+```
 
 You'll want to make sure to call `super.createSession` in order to get the session ID as well as
 the processed capabilities (note that capabilities are also set on `this.caps`; modifying `caps`
@@ -522,14 +529,13 @@ route, then the route will not be proxied and instead will be handled by your dr
 example, we are avoiding proxying all `POST` routes that have the `appium` prefix.
 
 Next, we have to set up the proxying itself. The way to do this is to use a special class from
-Appium called `JWProxy`. (The name means "JSON Wire Proxy" and is related to a legacy
-implementation of the protocol). You'll want to create a `JWProxy` object using the details required to
-connect to the remote server:
+Appium called `WebDriverProxy`. You'll want to create a `WebDriverProxy` object using the details
+required to connect to the remote server:
 
 ```js
-// import {JWProxy} from 'appium/driver';
+// import {WebDriverProxy} from 'appium/driver';
 
-const proxy = new JWProxy({
+const proxy = new WebDriverProxy({
     server: 'remote.server',
     port: 1234,
     base: '/',
@@ -541,8 +547,8 @@ this.proxyCommand = proxy.command.bind(proxy);
 
 Here we are creating a proxy object and assigning some of its methods to `this` under the names
 `proxyReqRes` and `proxyCommand`. This is required for Appium to use the proxy, so don't forget
-this step! The `JWProxy` has a variety of other options which you can check out in the source code,
-as well. (TODO: publish options as API docs and link here).
+this step! The `WebDriverProxy` has a variety of other options which you can check out in the
+source code as well.
 
 Finally, we need a way to tell Appium when the proxy is active. For your driver it might always
 be active, or it might only be active when in a certain context. You can define the logic as an
@@ -799,6 +805,14 @@ that multiple simultaneous sessions don't use the same resources:
 3. Have each driver express what resources it is using, then examine currently-used resources from
    other drivers when a new session begins.
 
+!!! warning "Deprecated"
+
+```
+The `driverData`-based mechanism described below is deprecated. Prefer
+[IPC](#send-messages-to-plugins-running-on-the-same-session) for coordinating resources across
+concurrently-running sessions instead.
+```
+
 To support this third strategy, you can implement `get driverData` in your driver to return what
 sorts of resources your driver is currently using, for example:
 
@@ -810,7 +824,7 @@ get driverData() {
 
 Now, when a new session is started on your driver, the `driverData` response from any other
 simultaneously running drivers (of the same type) will also be included, as the last parameter of
-the `createSession` method:
+the deprecated, multi-argument form of the `createSession` method:
 
 ```js
 async createSession(jwpCaps, reqCaps, w3cCaps, driverData)

packages/appium/docs/zh/developing/build-plugins.md

@@ -483,9 +483,9 @@ capability.
 You probably don't normally need to update the Appium server object (which is an
 [Express](https://expressjs.com/) server having already been
 [configured](https://github.com/appium/appium/blob/master/packages/base-driver/lib/express/server.js)
-in a variety of ways). But, for example, you could add new Express middleware to the server to
-support your plugin's requirements. To update the server you must implement the `static async
-updateServer` method in your class. This method takes three parameters:
+in a variety of ways). But, for example, you could add new routes to the server to support your
+plugin's requirements. To update the server you must implement the `static async updateServer`
+method in your class. This method takes three parameters:
 
 - `expressApp`: the Express app object
 - `httpServer`: the Node HTTP server object
@@ -498,6 +498,25 @@ results you'll need to test! Warning: this should be considered an advanced feat
 knowledge of Express, as well as the care not to do anything that could affect the operation of
 other parts of the Appium server!
 
+`updateServer` runs _after_ Appium's own routes are registered, so `expressApp.use(...)` here
+won't see requests to paths Appium already owns — Express matches middleware and routes in
+registration order. For middleware that must see requests to those routes too (e.g. logging or
+auth), use `httpServer.frontRouter` instead: Appium mounts this
+[Router](https://expressjs.com/en/5x/api/router/) before any route is registered, so anything
+attached to it — even from inside `updateServer` — still runs ahead of route matching. Note this
+is still _after_ Appium's own baseline middleware (CORS, WebSocket upgrade handling, body
+parsing, etc.), so it won't see requests Appium itself has already rejected, e.g. a CORS
+preflight failure or a body that failed to parse:
+
+```js
+static async updateServer(expressApp, httpServer, cliArgs) {
+  httpServer.frontRouter.use((req, res, next) => {
+    console.log(`Incoming request: ${req.method} ${req.url}`);
+    next();
+  });
+}
+```
+
 ### Handle unexpected session shutdown
 
 When developing a plugin you may want to add some cleanup logic for when a session ends. You would

packages/appium/docs/zh/developing/index.md

@@ -2,17 +2,14 @@
 hide:
   - toc
 
-title: Developing Appium Extensions
+title: 开发 Appium 扩展
 ---
 
-Appium is built with a modular structure, which means that Appium extensions (drivers and plugins)
-are decoupled from the main Appium module, and you only need to install the extensions that you
-want to use. This modular structure also unlocks the ability to develop entirely new extensions!
+Appium 采用模块化结构，这意味着 Appium 扩展（驱动和插件）与主 Appium 模块是解耦的；你只需要安装自己想要使用的扩展即可。 这种模块化结构还使得开发全新的扩展变得成为可能。
 
-This section of the Appium documentation is intended to help aspiring developers with creating their
-own Appium extension:
+Appium 文档的这一部分，旨在帮助有志于开发者创建自己的 Appium 扩展：
 
-- For creating a driver, see the [Build Drivers](./build-drivers.md) page
-- For creating a plugin, take a look at the [Build Plugins](build-plugins.md) page
-- Drivers and plugins both need documentation, so check out the [Build Documentation](./build-docs.md) page
-- For creating a doctor check, see the [Building Doctor Checks](./build-doctor-checks.md) page
+- 想要创建驱动，请查看 [构建驱动](./build-drivers.md) 页面
+- 想要创建插件，请查看 [构建插件](build-plugins.md) 页面
+- 驱动和插件都需要文档，因此请查看 [构建文档](./build-docs.md) 页面
+- 想要创建 Doctor check，请查看 [构建Doctor Checks](./build-doctor-checks.md) 页面

packages/appium/docs/zh/developing/sensitive.md

@@ -2,48 +2,38 @@
 hide:
   - toc
 
-title: Masking Sensitive Log Data
+title: 屏蔽敏感日志数据
 ---
 
-Since Appium server version 2.18.0 there is a possibility to mask sensitive
-values in logs. The below tutorial explains how to use this feature in third-party
-extensions.
+自 Appium server 2.18.0 版本起，已经具备了在日志中屏蔽敏感值的能力。 下面的教程将介绍如何在第三方扩展中使用这一功能。
 
-## Why It Might Be Useful
+## 为什么这很有用
 
-It is the right call to hide sensitive information, like passwords, tokens, etc.
-from server logs, so it does not accidentally leak if these logs end up in wrong hands.
-Appium server already provides a way to manipulate logs records via
-[filtering](../guides/log-filters.md), although it has its own limitations.
-The current approach is more sophisticated though, and requires some fine-tuning
-on the driver/plugin side.
+将密码、令牌等敏感信息从服务器日志中隐藏起来是合理且必要的，这样即使日志落入错误的人手中，也不会意外泄露敏感数据。
+Appium server 已经提供了一种通过 [过滤](../guides/log-filters.md) 来处理日志记录的方式，不过它本身存在一些限制。
+当前这种方法则更为先进，但需要驱动/插件侧进行一些细调。
 
-## How To
+## 使用方法
 
-The assumption is that your extension uses the standard built-in
-[@appium/logger](https://www.npmjs.com/package/@appium/logger).
-In order to get some value in logs replaced by a generic mask it is necessary:
+假设你的扩展使用的是标准内置的 [@appium/logger](https://www.npmjs.com/package/@appium/logger)。
+要让日志中的某个值被替换成通用的掩码，需要执行以下步骤：
 
-- Change the logging expression to wrap sensitive values and format them, for example:
+- 将日志表达式改为包裹敏感值并进行格式化，例如：
 
     ```js
-    this.log.info(`Value: ${value}`);
+    this.log.info(`Value: ${value}`)；
     ```
 
-  becomes
+  变为
 
     ```js
     import {logger} from '@appium/support';
     
-    this.log.info('Value: %s', logger.markSensitive(value));
+    this.log.info('Value: %s', logger.markSensitive(value))；
     ```
 
-  The formatting happens via the standard Node.js's
-  [util.format](https://nodejs.org/api/util.html#utilformatformat-args) API.
+  格式化过程会通过标准的 Node.js [util.format](https://nodejs.org/api/util.html#utilformatformat-args) API 完成。
 
-- While sending the appropriate server request, where this log line is used and should be masked,
-  add the custom header `X-Appium-Is-Sensitive` with its value set to `1` or `true` (case-insensitive).
-  Without such header the above log value is not going to be masked.
-  This way it is possible to conditionally mask log records depending on which
-  request is being handled by the extension if the log expression is used in the
-  common section.
+- 在发送相应的服务器请求时，如果这个日志行被使用并且应该被掩码处理，请额外添加自定义请求头 `X-Appium-Is-Sensitive`，其值为 `1` 或 `true`（大小写不敏感）。
+  如果没有这个请求头，上述日志值将不会被掩码处理。
+  这样就可以根据扩展处理的具体请求来有条件地屏蔽日志记录；如果日志表达式位于公共部分，就可以在这里统一控制。

packages/appium/docs/zh/ecosystem/drivers.md

@@ -130,7 +130,7 @@ appium driver install --source=npm appium-flutter-integration-driver
 appium driver install --source=npm appium-lg-webos-driver
 ```
 
-### [Linux](https://github.com/fantonglang/appium-linux-driver)
+### [Linux (@fantonglang)](https://github.com/fantonglang/appium-linux-driver)
 
 !!! warning
 
@@ -149,6 +149,16 @@ yarn install
 node ./
 ```
 
+### [Linux (@Itsmeaj)](https://github.com/Itsmeaj/appium)
+
+- Target: Linux desktop applications on X11 and Wayland
+- Mode: Native
+- Supported by: `@Itsmeaj`
+
+```sh title="Install This Driver"
+appium driver install --source=npm @itsmeaj/appium-linux-driver
+```
+
 ### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
 
 !!! info

packages/appium/docs/zh/guides/config.md

@@ -98,5 +98,5 @@ The above configuration corresponds to the `--driver-xcuitest-webkit-debug-proxy
 ```
 
 All properties are case-sensitive and will be in
-[kebab-case](https://en.wikipedia.org/wiki/Naming_convention_\(programming\)#Delimiter-separated_words).
+[kebab-case](https://en.wikipedia.org/wiki/Naming_convention_(programming)#Delimiter-separated_words).
 For example, `callback-port` is allowed, but `callbackPort` is not.

packages/appium/docs/zh/index.md

@@ -1,6 +1,6 @@
 ---
 hide:
-  - 导航栏
+  - navigation
   - toc
 
 title: 欢迎使用