ua-browser 1.3.1 → 1.4.0-beta.0

package/README.en.md

@@ -0,0 +1,226 @@
+# ua-browser
+
+[![npm version](https://img.shields.io/npm/v/ua-browser?color=cb3837)](https://www.npmjs.com/package/ua-browser)
+[![npm downloads](https://img.shields.io/npm/dm/ua-browser)](https://www.npmjs.com/package/ua-browser)
+[![license](https://img.shields.io/npm/l/ua-browser)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](https://www.typescriptlang.org/)
+
+Detect browser, OS, device type, rendering engine, CPU architecture, bots, headless browsers, and Mini Programs from User Agent strings. Zero dependencies. Works in both browser and Node.js environments.
+
+**[📖 Documentation](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[中文](./README.md)**
+
+## Features
+
+- **Comprehensive UA detection** — browser (incl. Arc / Brave), OS (incl. visionOS / tvOS), engine, device type (Mobile / Tablet / PC / TV / Console / XR), CPU arch, bots, headless browsers
+- **Robust device detection** — hardware signals (WebGL GPU renderer, CSS safe-area-inset, DPR, vibration/motion APIs) correctly identify mobile devices even when desktop mode is enabled
+- **Multi-signal arch detection** — `getEnvContext()` collects Client Hints, WebGL renderer, and font probes to accurately distinguish Apple Silicon from Intel Mac
+- **SSR Client Hints** — `parseHeaders()` + `ACCEPT_CH` for precise server-side detection (CPU arch, platform) in Chrome / Edge 90+
+- **AI bot recognition** — 40+ built-in bot rules: GPTBot, ClaudeBot, PerplexityBot, CCBot, messaging link-preview bots (Slack, Discord, Telegram, WhatsApp), and more
+- **Condition matching** — `satisfies(info, { os: 'iOS', device: 'Mobile' })` helper with TypeScript type checking
+- **Zero dependencies** — no runtime dependencies, tiny bundle size after gzip
+- **Pure function** — `parseUA()` has no global state, works seamlessly with SSR / Node.js
+- **TypeScript** — full type definitions with precise literal union types (`BrowserName`, `OsName`, etc.)
+- **Tree-shakeable** — named exports + `sideEffects: false`, unused code eliminated by Vite / Rollup / webpack 5+
+
+## Installation
+
+```sh
+npm i ua-browser
+# pnpm
+pnpm add ua-browser
+# yarn
+yarn add ua-browser
+```
+
+## Quick Start
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const info = uaBrowser()
+
+console.log(info)
+// {
+//   browser:        'Chrome',
+//   version:        '124.0.0.0',
+//   versionMajor:   124,
+//   engine:         'Blink',
+//   os:             'Windows',
+//   osVersion:      '10',
+//   device:         'PC',
+//   arch:           'x86_64',
+//   isWebview:      false,
+//   isHeadless:     false,
+//   isBot:          false,
+//   botName:        'unknown',
+//   language:       'en-US',
+//   platform:       'Win32',
+//   connectionType: 'unknown'
+// }
+```
+
+> To parse an arbitrary UA string, use the named export: `parseUA('Mozilla/5.0 ...')`
+
+## Usage
+
+### Browser (recommended: `detect`)
+
+Use `detect()` for accurate device and arch detection — it collects hardware signals in addition to parsing the UA string:
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const result = await uaBrowser.detect()
+console.log(result.device) // 'Mobile' — correct even in desktop mode
+console.log(result.arch)   // 'arm64' or 'x86_64'
+
+if (result.device === 'Mobile') {
+  // redirect to mobile version
+}
+```
+
+### Browser (sync: `uaBrowser`)
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const { browser, os, device } = uaBrowser()
+
+if (device === 'Mobile') {
+  // redirect to mobile version
+}
+```
+
+### Node.js / SSR
+
+```typescript
+import { parseUA } from 'ua-browser'
+
+const ua = req.headers['user-agent'] ?? ''
+const { browser, os, isBot } = parseUA(ua)
+
+if (isBot) {
+  // block or allow crawlers
+}
+```
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/ua-browser/dist/index.min.js"></script>
+<script>
+  const { browser, os } = uaBrowser()
+</script>
+```
+
+### Multi-signal Detection
+
+`getEnvContext()` collects Client Hints, WebGL renderer, and other browser signals in one async call. Use it when you need to reuse the context object or compose it with other options:
+
+```typescript
+import { getEnvContext, parseUA } from 'ua-browser'
+
+const ctx = await getEnvContext()
+const result = parseUA(navigator.userAgent, { ctx })
+
+console.log(result.device) // 'Mobile' — correct even in desktop mode
+console.log(result.arch)   // 'arm64' or 'x86_64'
+```
+
+### SSR Client Hints
+
+Set the `ACCEPT_CH` response header so Chrome / Edge 90+ browsers send Client Hints on subsequent requests, then use `parseHeaders` for precise server-side detection:
+
+```typescript
+import { parseHeaders, ACCEPT_CH } from 'ua-browser'
+
+// First response — tell the browser to send Client Hints
+res.setHeader('Accept-CH', ACCEPT_CH)
+
+// Subsequent requests — accurate arch / OS detection
+const result = parseHeaders(req.headers)
+console.log(result.arch) // 'x86_64' (from Sec-CH-UA-Arch)
+```
+
+### Accurate Windows 10 / 11 Detection
+
+Windows 10 and 11 share the same UA string. Use the Client Hints API to distinguish them:
+
+```typescript
+import { parseUA, getWindowsVersion, getNavContext } from 'ua-browser'
+
+const nav = getNavContext()
+const windowsVersion = await getWindowsVersion(nav)
+const result = parseUA(navigator.userAgent, { nav, windowsVersion })
+
+console.log(result.osVersion) // '10' or '11'
+```
+
+## API
+
+### Default export `uaBrowser()`
+
+Detects the current browser environment, automatically injecting the `navigator` context (language, platform, MIME types, etc.).
+
+```typescript
+uaBrowser()         // reads navigator.userAgent automatically
+parseUA(customUA)   // parse any UA string without browser context
+```
+
+### Named exports (tree-shakeable)
+
+```typescript
+import {
+  parseUA,              // pure function, ideal for SSR / Node.js
+  getNavContext,        // read current browser navigator context
+  getWindowsVersion,    // async: accurately distinguish Windows 10 / 11
+  getLanguage,          // extract browser language from NavContext
+  getEnvContext,        // collect all browser signals (Client Hints, WebGL, etc.)
+  parseHeaders,         // parse UA and Client Hints from HTTP headers (SSR)
+  ACCEPT_CH,            // response header constant to request Client Hints
+  isWebview,            // detect Android Webview / iOS WKWebView
+  detectBot,            // standalone bot detection
+  detectBrowser,        // standalone browser detection
+  detectOS,             // standalone OS detection
+  detectArch,           // standalone CPU architecture detection
+  detectHeadless,       // standalone headless browser detection
+  satisfies,            // condition-matching helper
+  VERSION,              // current library version
+} from 'ua-browser'
+```
+
+### Return value `EnvOption`
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `browser` | `BrowserName` | Browser name |
+| `version` | `string` | Browser version |
+| `versionMajor` | `number` | Browser major version (`parseInt(version)`) |
+| `engine` | `EngineName` | Rendering engine |
+| `os` | `OsName` | Operating system |
+| `osVersion` | `string` | OS version |
+| `device` | `DeviceName` | Device type: `Mobile` \| `Tablet` \| `PC` \| `TV` \| `Console` \| `XR` |
+| `arch` | `ArchName` | CPU architecture |
+| `isWebview` | `boolean` | Whether running in Android Webview or iOS WKWebView |
+| `isHeadless` | `boolean` | Whether running in a headless / automated browser |
+| `isBot` | `boolean` | Whether the UA belongs to a bot / crawler |
+| `botName` | `BotName` | Bot name |
+| `language` | `string` | Browser language, e.g. `en-US` |
+| `platform` | `string` | Platform identifier, e.g. `Win32` |
+| `connectionType` | `string` | Network type: `4g` \| `3g` \| `2g` \| `slow-2g` \| `unknown` |
+
+> All fields return `'unknown'` when undetected — never an empty string or `null`.
+
+## Supported
+
+Over 70 browsers, 20 operating systems, and 40+ bot rules built in. See the **[full support list](https://yangtianxia.github.io/ua-browser/guide/support-list)**.
+
+Highlights:
+- **Browsers** — Chrome, Safari, Arc, Brave, Firefox, Edge, Samsung Internet, UC, WeChat, DingTalk, TikTok, Bilibili, Kuaishou, Xiaohongshu, Feishu and more
+- **OS** — Windows, macOS, Android, iOS, visionOS, tvOS, HarmonyOS, OpenHarmony, Tizen, KaiOS and more
+- **Bots** — GPTBot, ClaudeBot, PerplexityBot, CCBot; messaging bots (Slack, Discord, Telegram, WhatsApp) and more
+- **Devices** — Mobile, Tablet, PC, TV (Samsung Smart TV, HbbTV), Console (PS5, Xbox, Switch), XR (Vision Pro, Quest)
+
+## License
+
+[MIT](./LICENSE) © yangtianxia

package/README.md

@@ -5,22 +5,23 @@
 [![license](https://img.shields.io/npm/l/ua-browser)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](https://www.typescriptlang.org/)
 
-Detect browser, OS, device type, rendering engine, CPU architecture, bots, headless browsers, and Mini Programs from User Agent strings. Zero dependencies. Works in both browser and Node.js environments.
+通过 User Agent 检测浏览器、操作系统、设备类型、渲染内核、CPU 架构、爬虫、无头浏览器及小程序运行环境。零依赖，支持浏览器与 Node.js 双环境。
 
-**[📖 Documentation](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[中文](./README.zh-CN.md)**
+**[📖 文档](https://yangtianxia.github.io/ua-browser/)** · **[🎮 Playground](https://yangtianxia.github.io/ua-browser/playground)** · **[English](./README.en.md)**
 
-## Features
+## 特性
 
-- **Comprehensive UA detection** — browser, OS, engine, device type (Mobile / Tablet / TV / PC), CPU arch, bots, headless browsers
-- **Multi-signal arch detection** — `getEnvContext()` collects Client Hints, WebGL renderer, and font probes to accurately distinguish Apple Silicon from Intel Mac
-- **SSR Client Hints** — `parseHeaders()` + `ACCEPT_CH` for precise server-side detection (CPU arch, platform) in Chrome / Edge 90+
-- **AI bot recognition** — built-in support for GPTBot, ClaudeBot, PerplexityBot, CCBot and more
-- **Zero dependencies** — no runtime dependencies, tiny bundle size after gzip
-- **Pure function** — `parseUA()` has no global state, works seamlessly with SSR / Node.js
-- **TypeScript** — full type definitions with precise literal union types (`BrowserName`, `OsName`, etc.)
-- **Tree-shakeable** — named exports + `sideEffects: false`, unused code eliminated by Vite / Rollup / webpack 5+
+- **全面 UA 检测** — 浏览器（含 Arc / Brave）、OS（含 visionOS / tvOS）、渲染内核、设备类型（Mobile / Tablet / TV / PC / Console / XR）、CPU 架构、爬虫、无头浏览器
+- **多信号架构检测** — `getEnvContext()` 采集 Client Hints、WebGL 渲染器、字体探针，精确区分 Apple Silicon 与 Intel Mac
+- **SSR Client Hints** — `parseHeaders()` + `ACCEPT_CH`，在 Chrome / Edge 90+ 中实现服务端精准检测（CPU 架构、平台等）
+- **AI 爬虫识别** — 内置 GPTBot、ClaudeBot、PerplexityBot、CCBot 等 40+ 种爬虫规则，含消息应用链接预览 Bot（Slack、Discord、Telegram）
+- **条件匹配** — `satisfies(info, { os: 'iOS', device: 'Mobile' })` 辅助函数，支持 TypeScript 类型检查
+- **零依赖** — 无任何运行时依赖，gzip 后体积极小
+- **纯函数** — `parseUA()` 无全局状态，天然支持 SSR / Node.js
+- **TypeScript** — 完整类型定义，`BrowserName`、`OsName` 等均为精确字面量联合类型
+- **Tree-shakeable** — 所有功能按需导入，不引入多余代码
 
-## Installation
+## 安装
 
 ```sh
 npm i ua-browser
@@ -30,7 +31,7 @@ pnpm add ua-browser
 yarn add ua-browser
 ```
 
-## Quick Start
+## 快速上手
 
 ```typescript
 import uaBrowser from 'ua-browser'
@@ -39,27 +40,29 @@ const info = uaBrowser()
 
 console.log(info)
 // {
-//   browser:    'Chrome',
-//   version:    '124.0.0.0',
-//   engine:     'Blink',
-//   os:         'Windows',
-//   osVersion:  '10',
-//   device:     'PC',
-//   arch:       'x86_64',
-//   isWebview:  false,
-//   isHeadless: false,
-//   isBot:      false,
-//   botName:    'unknown',
-//   language:   'en-US',
-//   platform:   'Win32'
+//   browser:        'Chrome',
+//   version:        '124.0.0.0',
+//   versionMajor:   124,
+//   engine:         'Blink',
+//   os:             'Windows',
+//   osVersion:      '10',
+//   device:         'PC',
+//   arch:           'x86_64',
+//   isWebview:      false,
+//   isHeadless:     false,
+//   isBot:          false,
+//   botName:        'unknown',
+//   language:       'zh-CN',
+//   platform:       'Win32',
+//   connectionType: 'unknown'
 // }
 ```
 
-> Pass a custom UA string: `uaBrowser('Mozilla/5.0 ...')`
+> 解析任意 UA 字符串请使用命名导出：`parseUA('Mozilla/5.0 ...')`
 
-## Usage
+## 使用
 
-### Browser
+### 浏览器环境
 
 ```typescript
 import uaBrowser from 'ua-browser'
@@ -67,7 +70,7 @@ import uaBrowser from 'ua-browser'
 const { browser, os, device } = uaBrowser()
 
 if (device === 'Mobile') {
-  // redirect to mobile version
+  // 跳转移动版
 }
 ```
 
@@ -80,7 +83,7 @@ const ua = req.headers['user-agent'] ?? ''
 const { browser, os, isBot } = parseUA(ua)
 
 if (isBot) {
-  // block or allow crawlers
+  // 拦截或放行爬虫
 }
 ```
 
@@ -93,9 +96,9 @@ if (isBot) {
 </script>
 ```
 
-### Multi-signal Architecture Detection
+### 多信号架构检测
 
-`getEnvContext()` collects Client Hints, WebGL renderer, and other browser signals in one async call — enough to distinguish Apple Silicon from Intel Mac:
+`getEnvContext()` 一次性采集 Client Hints、WebGL 渲染器等多维信号，可区分 Apple Silicon 与 Intel Mac：
 
 ```typescript
 import { getEnvContext, parseUA } from 'ua-browser'
@@ -103,27 +106,27 @@ import { getEnvContext, parseUA } from 'ua-browser'
 const ctx = await getEnvContext()
 const result = parseUA(navigator.userAgent, { ctx })
 
-console.log(result.arch) // 'arm64' or 'x86_64'
+console.log(result.arch) // 'arm64' 或 'x86_64'
 ```
 
 ### SSR Client Hints
 
-Set the `ACCEPT_CH` response header so Chrome / Edge 90+ browsers send Client Hints on subsequent requests, then use `parseHeaders` for precise server-side detection:
+通过响应头告知 Chrome / Edge 90+ 上报 Client Hints，再用 `parseHeaders` 在服务端精准解析：
 
 ```typescript
 import { parseHeaders, ACCEPT_CH } from 'ua-browser'
 
-// First response — tell the browser to send Client Hints
+// 第一次响应时写入 Accept-CH
 res.setHeader('Accept-CH', ACCEPT_CH)
 
-// Subsequent requests — accurate arch / OS detection
+// 后续请求携带 Client Hints 后，精准识别架构等信息
 const result = parseHeaders(req.headers)
-console.log(result.arch) // 'x86_64' (from Sec-CH-UA-Arch)
+console.log(result.arch) // 'x86_64'（来自 Sec-CH-UA-Arch）
 ```
 
-### Accurate Windows 10 / 11 Detection
+### 精确区分 Windows 10 / 11
 
-Windows 10 and 11 share the same UA string. Use the Client Hints API to distinguish them:
+Windows 10 和 11 的 UA 字符串相同，需借助 Client Hints API 异步获取：
 
 ```typescript
 import { parseUA, getWindowsVersion, getNavContext } from 'ua-browser'
@@ -132,68 +135,73 @@ const nav = getNavContext()
 const windowsVersion = await getWindowsVersion(nav)
 const result = parseUA(navigator.userAgent, { nav, windowsVersion })
 
-console.log(result.osVersion) // '10' or '11'
+console.log(result.osVersion) // '10' 或 '11'
 ```
 
 ## API
 
-### Default export `uaBrowser(ua?)`
+### 默认导出 `uaBrowser()`
 
-Automatically injects the `navigator` context (language, platform, MIME types, etc.) in browser environments.
+检测当前浏览器环境，自动注入 `navigator` 上下文（语言、平台、MIME 类型等）。
 
 ```typescript
-uaBrowser()          // reads navigator.userAgent automatically
-uaBrowser(customUA)  // custom UA string, still injects browser context
+uaBrowser()          // 自动读取 navigator.userAgent
+parseUA(customUA)    // 解析任意 UA 字符串（无浏览器上下文依赖）
 ```
 
-### Named exports (tree-shakeable)
+### 命名导出（按需引入）
 
 ```typescript
 import {
-  parseUA,              // pure function, ideal for SSR / Node.js
-  getNavContext,        // read current browser navigator context
-  getWindowsVersion,    // async: accurately distinguish Windows 10 / 11
-  getLanguage,          // extract browser language from NavContext
-  getEnvContext,        // collect all browser signals (Client Hints, WebGL, etc.)
-  parseHeaders,         // parse UA and Client Hints from HTTP headers (SSR)
-  ACCEPT_CH,            // response header constant to request Client Hints
-  isWebview,            // detect Android Webview / iOS WKWebView
-  detectBot,            // standalone bot detection
-  detectArch,           // standalone CPU architecture detection
-  detectHeadless,       // standalone headless browser detection
-  VERSION,              // current library version
+  parseUA,              // 纯函数，适合 SSR / Node.js
+  getNavContext,        // 读取当前浏览器 navigator 上下文
+  getWindowsVersion,    // 异步精确区分 Windows 10 / 11
+  getLanguage,          // 从 NavContext 获取浏览器语言
+  getEnvContext,        // 采集所有浏览器环境信号（Client Hints、WebGL 等）
+  parseHeaders,         // 从 HTTP 请求头解析 UA 及 Client Hints（SSR）
+  ACCEPT_CH,            // 响应头常量，告知浏览器上报 Client Hints
+  isWebview,            // 检测 Android Webview / iOS WKWebView
+  detectBot,            // 独立爬虫检测
+  detectBrowser,        // 独立浏览器检测
+  detectOS,             // 独立操作系统检测
+  detectArch,           // 独立 CPU 架构检测
+  detectHeadless,       // 独立无头浏览器检测
+  satisfies,            // 条件匹配辅助函数
+  VERSION,              // 当前版本号
 } from 'ua-browser'
 ```
 
-### Return value `EnvOption`
+### 返回值 `EnvOption`
 
-| Field | Type | Description |
+| 字段 | 类型 | 说明 |
 | :-- | :-- | :-- |
-| `browser` | `BrowserName` | Browser name |
-| `version` | `string` | Browser version |
-| `engine` | `EngineName` | Rendering engine |
-| `os` | `OsName` | Operating system |
-| `osVersion` | `string` | OS version |
-| `device` | `DeviceName` | Device type: `Mobile` \| `Tablet` \| `TV` \| `PC` |
-| `arch` | `ArchName` | CPU architecture |
-| `isWebview` | `boolean` | Whether running in Android Webview or iOS WKWebView |
-| `isHeadless` | `boolean` | Whether running in a headless / automated browser |
-| `isBot` | `boolean` | Whether the UA belongs to a bot / crawler |
-| `botName` | `BotName` | Bot name |
-| `language` | `string` | Browser language, e.g. `en-US` |
-| `platform` | `string` | Platform identifier, e.g. `Win32` |
-
-> All fields return `'unknown'` when undetected — never an empty string or `null`.
-
-## Supported
-
-Over 70 browsers, 17 operating systems, and 19 bot rules built in. See the **[full support list](https://yangtianxia.github.io/ua-browser/guide/support-list)**.
-
-Highlights:
-- **Browsers** — Chrome, Safari, Firefox, Edge, Samsung Internet, UC, WeChat, DingTalk, TikTok, Bilibili, Kuaishou, Xiaohongshu, Feishu and more
-- **OS** — Windows, macOS, Android, iOS, HarmonyOS, OpenHarmony, Tizen, KaiOS and more
-- **AI bots** — GPTBot, ClaudeBot, PerplexityBot, CCBot and more
-- **Devices** — Mobile, Tablet, TV (Samsung Smart TV, HbbTV), PC
+| `browser` | `BrowserName` | 浏览器名称 |
+| `version` | `string` | 浏览器版本 |
+| `versionMajor` | `number` | 浏览器主版本号（`parseInt(version)`） |
+| `engine` | `EngineName` | 渲染内核 |
+| `os` | `OsName` | 操作系统 |
+| `osVersion` | `string` | 系统版本 |
+| `device` | `DeviceName` | 设备类型：`Mobile` \| `Tablet` \| `PC` \| `TV` \| `Console` \| `XR` |
+| `arch` | `ArchName` | CPU 架构 |
+| `isWebview` | `boolean` | 是否为 Android Webview / iOS WKWebView |
+| `isHeadless` | `boolean` | 是否为无头 / 自动化浏览器 |
+| `isBot` | `boolean` | 是否为爬虫 / 机器人 |
+| `botName` | `BotName` | 爬虫名称 |
+| `language` | `string` | 浏览器语言，如 `zh-CN` |
+| `platform` | `string` | 平台标识，如 `Win32` |
+| `connectionType` | `string` | 网络类型：`4g` \| `3g` \| `2g` \| `slow-2g` \| `unknown` |
+
+> 所有字段在无法识别时统一返回 `'unknown'`，不返回空字符串或 `null`。
+
+## 支持范围
+
+内置超过 70 种浏览器、20 种操作系统、40+ 种爬虫规则，详见 **[内置支持列表](https://yangtianxia.github.io/ua-browser/guide/support-list)**。
+
+部分覆盖：
+- **浏览器** — Chrome、Safari、Arc、Brave、Firefox、Edge、Samsung Internet、UC、微信、钉钉、抖音、哔哩哔哩、快手、小红书、飞书等
+- **操作系统** — Windows、macOS、Android、iOS、visionOS、tvOS、HarmonyOS、OpenHarmony、Tizen、KaiOS 等
+- **AI 爬虫** — GPTBot、ClaudeBot、PerplexityBot、CCBot；消息应用 Bot（Slack、Discord、Telegram、WhatsApp）等
+- **设备** — Mobile、Tablet、PC、TV（含三星 Smart TV、HbbTV 标准）、Console（PS5、Xbox、Switch）、XR（Vision Pro、Quest）
 
 ## License