ua-browser 1.4.0 → 1.4.1

package/README.en.md

@@ -22,6 +22,23 @@ Detect browser, OS, device type, rendering engine, CPU architecture, bots, headl
 - **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+
 
+## Why ua-browser
+
+UA strings lie — a phone in desktop mode, a headless browser, or an AI crawler can all masquerade as an ordinary user. ua-browser combines hardware signals and Client Hints to stay accurate when the UA string can't be trusted.
+
+| Capability | ua-browser | ua-parser-js | bowser | detect-browser |
+| :-- | :--: | :--: | :--: | :--: |
+| UA string parsing | ✅ | ✅ | ✅ | ✅ |
+| Zero dependencies | ✅ | ✅ | ✅ | ✅ |
+| TypeScript native | ✅ | ✅ | ✅ | ✅ |
+| Tree-shakeable | ✅ | ❌ | ✅ | ❌ |
+| Hardware-signal device detection (accurate in desktop mode) | ✅ | ❌ | ❌ | ❌ |
+| CPU architecture (Apple Silicon vs Intel) | ✅ | ❌ | ❌ | ❌ |
+| SSR Client Hints | ✅ | ❌ | ❌ | ❌ |
+| Headless browser detection | ✅ | ❌ | ❌ | ❌ |
+| AI bot recognition (40+ rules) | ✅ | ❌ | ❌ | ❌ |
+| Extended device types (TV / Console / XR) | ✅ | ❌ | ❌ | ❌ |
+
 ## Installation
 
 ```sh
@@ -79,6 +96,8 @@ if (result.device === 'Mobile') {
 }
 ```
 
+> **Note**: `detect()` uses the Client Hints high-entropy API (`getHighEntropyValues`), which is only available in **HTTPS or localhost** contexts. On plain HTTP pages it degrades silently — browser version and OS version fall back to the frozen UA string values (e.g. Chrome reports `149.0.0.0`, macOS 26+ reports `10.15.7`).
+
 ### Browser (sync: `uaBrowser`)
 
 ```typescript
@@ -223,6 +242,28 @@ Highlights:
 - **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)
 
+## FAQ
+
+**How is ua-browser different from ua-parser-js?**
+
+`ua-parser-js` focuses on parsing the UA string itself and has no hardware-signal collection. It misidentifies device type when a phone is in desktop mode or when the UA is spoofed. ua-browser adds WebGL renderer, Client Hints, CSS `safe-area-inset`, and sensor APIs to detect the actual hardware — plus 40+ AI bot rules and headless browser detection that `ua-parser-js` does not include.
+
+**Does it work in Next.js / Nuxt / other SSR frameworks?**
+
+Yes. `parseUA(ua)` is a pure function with no browser API dependencies — it runs in Node.js, Deno, and Edge Runtime as-is. Pair `parseHeaders()` with `ACCEPT_CH` to leverage Client Hints for precise architecture and platform data on the server.
+
+**Can it detect mobile devices when the user has enabled desktop mode?**
+
+Yes, when you use `uaBrowser.detect()` or `getEnvContext()`. These APIs collect CSS `safe-area-inset`, the Vibration API, and device pixel ratio to identify the actual hardware, independent of what the UA string declares.
+
+**How do I detect GPT, Claude, or other AI crawler requests?**
+
+Check the `isBot` and `botName` fields on the return value. Built-in rules cover GPTBot, ClaudeBot, PerplexityBot, CCBot, and messaging link-preview bots (Slack, Discord, Telegram, WhatsApp).
+
+**What is the bundle size?**
+
+Zero runtime dependencies. The bundle is tiny after gzip; tree-shaking named exports makes it smaller still.
+
 ## License
 
 [MIT](./LICENSE) © yangtianxia

package/README.md

@@ -21,6 +21,23 @@
 - **TypeScript** — 完整类型定义，`BrowserName`、`OsName` 等均为精确字面量联合类型
 - **Tree-shakeable** — 所有功能按需导入，不引入多余代码
 
+## 为什么选 ua-browser
+
+UA 字符串会撒谎 —— 开了桌面模式的手机、无头浏览器、AI 爬虫都可能伪装成普通用户。ua-browser 额外引入硬件信号与 Client Hints，在 UA 失真时依然准确。
+
+| 能力 | ua-browser | ua-parser-js | bowser | detect-browser |
+| :-- | :--: | :--: | :--: | :--: |
+| UA 字符串解析 | ✅ | ✅ | ✅ | ✅ |
+| 零依赖 | ✅ | ✅ | ✅ | ✅ |
+| TypeScript 原生 | ✅ | ✅ | ✅ | ✅ |
+| Tree-shakeable | ✅ | ❌ | ✅ | ❌ |
+| 硬件信号设备检测（桌面模式下仍准确）| ✅ | ❌ | ❌ | ❌ |
+| CPU 架构（Apple Silicon / Intel 区分）| ✅ | ❌ | ❌ | ❌ |
+| SSR Client Hints | ✅ | ❌ | ❌ | ❌ |
+| 无头浏览器检测 | ✅ | ❌ | ❌ | ❌ |
+| AI 爬虫识别 | ✅ 40+ | ❌ | ❌ | ❌ |
+| 设备类型（TV / Console / XR）| ✅ | ❌ | ❌ | ❌ |
+
 ## 安装
 
 ```sh
@@ -62,7 +79,25 @@ console.log(info)
 
 ## 使用
 
-### 浏览器环境
+### 浏览器环境（推荐：`detect`）
+
+使用 `detect()` 获得精准设备与架构信息 —— 在 UA 解析的基础上额外采集硬件信号：
+
+```typescript
+import uaBrowser from 'ua-browser'
+
+const result = await uaBrowser.detect()
+console.log(result.device) // 'Mobile' —— 即使开了桌面模式也正确
+console.log(result.arch)   // 'arm64' 或 'x86_64'
+
+if (result.device === 'Mobile') {
+  // 跳转移动版
+}
+```
+
+> **注意**：`detect()` 内部调用 Client Hints 高熵 API（`getHighEntropyValues`），该 API 仅在 **HTTPS 或 localhost** 环境下可用。HTTP 页面中调用时会静默降级，浏览器版本和 OS 版本将退回 UA 字符串的冻结值（如 Chrome 版本显示为 `149.0.0.0`，macOS 26+ 显示为 `10.15.7`）。
+
+### 浏览器环境（同步：`uaBrowser`）
 
 ```typescript
 import uaBrowser from 'ua-browser'
@@ -205,6 +240,28 @@ import {
 - **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）
 
+## 常见问题
+
+**和 ua-parser-js 有什么区别？**
+
+`ua-parser-js` 专注于 UA 字符串本身的解析，不具备硬件信号采集能力；在手机开启桌面模式或 UA 被篡改时会给出错误结果。ua-browser 额外引入 WebGL 渲染器、Client Hints、CSS `safe-area-inset` 等多维信号，并内置 40+ AI 爬虫识别规则和无头浏览器检测，`ua-parser-js` 均不支持。
+
+**在 Next.js / Nuxt 等 SSR 框架里能用吗？**
+
+可以。`parseUA(ua)` 是纯函数，无任何浏览器 API 依赖，可直接在 Node.js / Edge Runtime 中使用。搭配 `parseHeaders()` 和 `ACCEPT_CH` 还可在服务端利用 Client Hints 获取精准的架构与平台信息。
+
+**手机开了"请求桌面网站"，还能正确识别设备类型吗？**
+
+可以，但需要使用 `uaBrowser.detect()` 或手动调用 `getEnvContext()`。这两种方式会采集 CSS `safe-area-inset`、振动 API、设备像素比等硬件信号，不依赖 UA 字符串里的设备声明。
+
+**如何识别 GPT、Claude 等 AI 爬虫的抓取请求？**
+
+读取返回值的 `isBot` 和 `botName` 字段即可。库内置了 GPTBot、ClaudeBot、PerplexityBot、CCBot 等规则，同时也覆盖 Slack、Discord、Telegram 等消息应用的链接预览 Bot。
+
+**包体积有多大？**
+
+零运行时依赖，gzip 后极小；按需引入（named exports + tree-shaking）体积更小。
+
 ## License
 
 [MIT](./LICENSE) © yangtianxia

package/dist/index.cjs

@@ -4,25 +4,24 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 // package.json
 var package_default = {
-  version: "1.4.0"};
+  version: "1.4.1"};
 
 // src/constants/os.ts
 var OS_DEFS = [
-  { name: "WebOS", detect: /hpwOS/, versionPattern: /hpwOS\/([\d.]+)/ },
-  { name: "Symbian", detect: /Symbian/, versionPattern: null },
-  { name: "MeeGo", detect: /MeeGo/, versionPattern: null },
-  { name: "BlackBerry", detect: /(BlackBerry|RIM)/, versionPattern: null },
-  { name: "FreeBSD", detect: /FreeBSD/, versionPattern: null },
-  { name: "Debian", detect: /Debian/, versionPattern: /Debian\/([\d.]+)/ },
-  { name: "Ubuntu", detect: /Ubuntu/, versionPattern: null },
-  // Linux must come before Chrome OS: Chrome OS UAs contain "X11", so Linux matches first,
-  // then Chrome OS overrides it.
-  { name: "Linux", detect: /(Linux|X11)/, versionPattern: null },
-  { name: "Chrome OS", detect: /CrOS/, versionPattern: null },
-  { name: "Tizen", detect: /Tizen/, versionPattern: /Tizen ([\d.]+)/ },
-  { name: "iOS", detect: /like Mac OS X/, versionPattern: /OS ([\d_]+) like/ },
+  { name: "WebOS", priority: 20, detect: /hpwOS/, versionPattern: /hpwOS\/([\d.]+)/ },
+  { name: "Symbian", priority: 20, detect: /Symbian/, versionPattern: null },
+  { name: "MeeGo", priority: 20, detect: /MeeGo/, versionPattern: null },
+  { name: "BlackBerry", priority: 20, detect: /(BlackBerry|RIM)/, versionPattern: null },
+  { name: "FreeBSD", priority: 20, detect: /FreeBSD/, versionPattern: null },
+  { name: "Debian", priority: 20, detect: /Debian/, versionPattern: /Debian\/([\d.]+)/ },
+  { name: "Ubuntu", priority: 20, detect: /Ubuntu/, versionPattern: null },
+  { name: "Linux", priority: 10, detect: /(Linux|X11)/, versionPattern: null },
+  { name: "Chrome OS", priority: 30, detect: /CrOS/, versionPattern: null },
+  { name: "Tizen", priority: 20, detect: /Tizen/, versionPattern: /Tizen ([\d.]+)/ },
+  { name: "iOS", priority: 20, detect: /like Mac OS X/, versionPattern: /OS ([\d_]+) like/ },
   {
     name: "MacOS",
+    priority: 20,
     detect: /Macintosh/,
     versionPattern: /Mac OS X -?([\d_.]+)/,
     versionNames: {
@@ -40,27 +39,21 @@ var OS_DEFS = [
       "15": "Sequoia"
     }
   },
-  // visionOS / tvOS must come AFTER iOS: their UAs also contain "like Mac OS X",
-  // so they need to override iOS via the last-match-wins iteration.
-  { name: "visionOS", detect: /visionOS/, versionPattern: /visionOS ([\d_]+)/ },
-  { name: "tvOS", detect: /Apple TV/, versionPattern: /OS ([\d_]+) like/ },
-  { name: "Android", detect: /(Android|Adr)/, versionPattern: /(?:Android|Adr) ([\d.]+)/ },
-  // HarmonyOS must come after Android: HarmonyOS UAs include "Android", so Android matches
-  // first, then HarmonyOS overrides it. versionPattern tries direct extraction first (5.0+
-  // pure HarmonyOS UAs don't have Android token), then falls back to Android version + lookup.
+  { name: "visionOS", priority: 30, detect: /visionOS/, versionPattern: /visionOS ([\d_]+)/ },
+  { name: "tvOS", priority: 30, detect: /Apple TV/, versionPattern: /OS ([\d_]+) like/ },
+  { name: "Android", priority: 20, detect: /(Android|Adr)/, versionPattern: /(?:Android|Adr) ([\d.]+)/ },
   {
     name: "HarmonyOS",
+    priority: 30,
     detect: /HarmonyOS/,
     versionPattern: [/HarmonyOS[\s/]([\d.]+)/, /Android ([\d.]+)[;)]/],
-    versionLookup: { "10": "2", "11": "3", "12": "3", "13": "4" }
+    versionLookup: { "10": "2", "11": "3", "12": "3", "13": "4", "14": "4" }
   },
-  // OpenHarmony (open-source base) must come after HarmonyOS to override any earlier match.
-  { name: "OpenHarmony", detect: /OpenHarmony/, versionPattern: /OpenHarmony[\s/]([\d.]+)/ },
-  { name: "KaiOS", detect: /KAIOS/, versionPattern: /KAIOS\/([\d.]+)/ },
-  // Windows must come before Windows Phone: Windows Phone UAs contain "Windows", so Windows
-  // matches first, then Windows Phone overrides it.
+  { name: "OpenHarmony", priority: 30, detect: /OpenHarmony/, versionPattern: /OpenHarmony[\s/]([\d.]+)/ },
+  { name: "KaiOS", priority: 30, detect: /KAIOS/, versionPattern: /KAIOS\/([\d.]+)/ },
   {
     name: "Windows",
+    priority: 10,
     detect: /Windows/,
     versionPattern: /Windows NT ([\d.]+)/,
     versionLookup: {
@@ -82,7 +75,7 @@ var OS_DEFS = [
       "11": "Windows 11"
     }
   },
-  { name: "Windows Phone", detect: /(IEMobile|Windows Phone)/, versionPattern: /Windows Phone(?: OS)? ([\d.]+)/ }
+  { name: "Windows Phone", priority: 30, detect: /(IEMobile|Windows Phone)/, versionPattern: /Windows Phone(?: OS)? ([\d.]+)/ }
 ];
 
 // src/constants/browsers.ts
@@ -304,9 +297,11 @@ function lookupVersionName(map, version) {
 }
 function detectOs(ua, windowsVersion) {
   let matchedDef = null;
+  let bestPriority = -1;
   for (const def of OS_DEFS) {
-    if (def.detect.test(ua)) {
+    if (def.detect.test(ua) && def.priority > bestPriority) {
       matchedDef = def;
+      bestPriority = def.priority;
     }
   }
   if (!matchedDef) return { os: "unknown", osVersion: "unknown", osVersionName: "unknown" };
@@ -455,7 +450,7 @@ var BOT_DEFS = [
   { name: "Facebookbot", detect: /(facebookexternalhit|FacebookBot)/, category: "social" },
   { name: "Twitterbot", detect: /Twitterbot/, category: "social" },
   { name: "LinkedInBot", detect: /LinkedInBot/, category: "social" },
-  { name: "PinterestBot", detect: /Pinterest/, category: "social" },
+  { name: "PinterestBot", detect: /Pinterestbot/i, category: "social" },
   // Messaging link preview bots
   { name: "Slackbot", detect: /Slackbot/, category: "link-preview" },
   { name: "Discordbot", detect: /Discordbot/, category: "link-preview" },
@@ -584,6 +579,7 @@ var BRAND_TO_BROWSER = [
   ["Microsoft Edge", "Edge"],
   ["Opera", "Opera"],
   ["Vivaldi", "Vivaldi"],
+  ["Brave", "Brave"],
   ["Google Chrome", "Chrome"],
   ["Chromium", "Chromium"]
 ];
@@ -648,6 +644,82 @@ function normalizeBCP47(raw) {
     return p.toUpperCase();
   }).join("-");
 }
+var ISO_639_1 = /* @__PURE__ */ new Set([
+  "af",
+  "am",
+  "ar",
+  "az",
+  "be",
+  "bg",
+  "bn",
+  "bs",
+  "ca",
+  "cs",
+  "cy",
+  "da",
+  "de",
+  "el",
+  "en",
+  "es",
+  "et",
+  "eu",
+  "fa",
+  "fi",
+  "fr",
+  "ga",
+  "gl",
+  "gu",
+  "he",
+  "hi",
+  "hr",
+  "hu",
+  "hy",
+  "id",
+  "is",
+  "it",
+  "ja",
+  "ka",
+  "kk",
+  "km",
+  "kn",
+  "ko",
+  "lt",
+  "lv",
+  "mk",
+  "ml",
+  "mn",
+  "mr",
+  "ms",
+  "mt",
+  "my",
+  "nb",
+  "ne",
+  "nl",
+  "no",
+  "pa",
+  "pl",
+  "pt",
+  "ro",
+  "ru",
+  "si",
+  "sk",
+  "sl",
+  "sq",
+  "sr",
+  "sv",
+  "sw",
+  "ta",
+  "te",
+  "th",
+  "tl",
+  "tr",
+  "uk",
+  "ur",
+  "uz",
+  "vi",
+  "zh",
+  "zu"
+]);
 function languageFromUA(ua) {
   const kwMatch = /\bLanguage\/([a-zA-Z]{2,3}(?:[-_][a-zA-Z]{2,4}){1,2})\b/i.exec(ua);
   if (kwMatch) return normalizeBCP47(kwMatch[1]);
@@ -657,6 +729,10 @@ function languageFromUA(ua) {
     const parts = m[1].replace(/_/g, "-").split("-");
     if (parts.length >= 2) return normalizeBCP47(m[1]);
   }
+  const bare = /[;(]\s*([a-z]{2,3})\s*[;)]/g;
+  while ((m = bare.exec(ua)) !== null) {
+    if (ISO_639_1.has(m[1])) return m[1];
+  }
   return "unknown";
 }
 function parseUA(ua, options = {}) {
@@ -713,20 +789,8 @@ function parseUA(ua, options = {}) {
     const opVer = (_h = (_g = /OPR\/([\d.]+)/.exec(ua)) != null ? _g : /OPT\/([\d.]+)/.exec(ua)) != null ? _h : /Opera\/([\d.]+)/.exec(ua);
     version = (_i = opVer == null ? void 0 : opVer[1]) != null ? _i : "unknown";
   }
-  if (browser === "Chrome" && /\S+Browser\//.test(ua)) {
-    const m = /(\S+Browser)\/([\d.]+)/.exec(ua);
-    if (m) {
-      browser = m[1];
-      version = m[2];
-    }
-  }
-  if (browser === "Firefox" && nav) {
-    try {
-      if (typeof clientInformation !== "undefined" || typeof u2f === "undefined") {
-        browser = "Firefox Nightly";
-      }
-    } catch (e) {
-    }
+  if (browser === "Firefox" && /Firefox\/[\d.]+a\d/.test(ua)) {
+    browser = "Firefox Nightly";
   }
   if (os === "iOS" && browser === "Safari") {
     const m = /Version\/([\d.]+)/.exec(ua);
@@ -769,7 +833,8 @@ function parseUA(ua, options = {}) {
     }
   }
   const { engine, engineVersion } = detectEngine(ua, browser, version);
-  const versionMajor = parseInt((_l = version.split(".")[0]) != null ? _l : "0", 10) || 0;
+  const major = parseInt((_l = version.split(".")[0]) != null ? _l : "", 10);
+  const versionMajor = Number.isNaN(major) ? 0 : major;
   const connectionType = (_p = (_o = (_n = (_m = options.ctx) != null ? _m : options.nav) == null ? void 0 : _n.connection) == null ? void 0 : _o.effectiveType) != null ? _p : "unknown";
   const finalOsVersionName = os === "MacOS" || os === "Windows" ? (() => {
     var _a2;
@@ -1010,7 +1075,7 @@ function deriveWindowsVersion2(platformVersion) {
   return isNaN(major) ? null : major >= 13 ? "11" : "10";
 }
 function parseHeaders(headers) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f;
   const normalised = {};
   for (const key of Object.keys(headers)) {
     normalised[key.toLowerCase()] = headers[key];
@@ -1027,12 +1092,24 @@ function parseHeaders(headers) {
   const model = unquote(get("sec-ch-ua-model"));
   const platformVersion = unquote(get("sec-ch-ua-platform-version"));
   const platform = (_e = unquote(get("sec-ch-ua-platform"))) != null ? _e : "";
+  const fullVersionListRaw = get("sec-ch-ua-full-version-list");
+  const fullVersionList = [];
+  if (fullVersionListRaw) {
+    const re = /"([^"]+)";v="([^"]+)"/g;
+    let m;
+    while ((m = re.exec(fullVersionListRaw)) !== null) {
+      fullVersionList.push({ brand: m[1], version: m[2] });
+    }
+  }
   const highEntropyData = {};
   if (architecture !== void 0) highEntropyData.architecture = architecture;
   if (bitness !== void 0) highEntropyData.bitness = bitness;
   if (model !== void 0) highEntropyData.model = model;
   if (platformVersion !== void 0) highEntropyData.platformVersion = platformVersion;
+  if (fullVersionList.length > 0) highEntropyData.fullVersionList = fullVersionList;
   const isMobile = get("sec-ch-ua-mobile") === "?1";
+  const secCHUA = (_f = get("sec-ch-ua")) != null ? _f : "";
+  const hasBrave = /"Brave"/.test(secCHUA);
   const windowsVersion = platform === "Windows" ? deriveWindowsVersion2(platformVersion) : null;
   const ctx = {
     userAgent: ua,
@@ -1040,7 +1117,8 @@ function parseHeaders(headers) {
     language,
     maxTouchPoints: isMobile ? 1 : 0,
     highEntropyData: Object.keys(highEntropyData).length > 0 ? highEntropyData : void 0,
-    windowsVersion
+    windowsVersion,
+    hasBrave
   };
   return parseUA(ua, { ctx });
 }