@ziztechnology/dial-library 0.0.2 → 0.0.3

package/README.md

@@ -1,115 +1,196 @@
-# Toooony 表盘用户 SDK
+# Toooony 表盘 SDK
+
+`@ziztechnology/dial-library` 为 Toooony 表盘提供统一的设备信息和行车状态 API。你可以用它读取传感器，也可以直接订阅经过平滑、确认和回退处理后的行车状态。
 
 > [!NOTE]
-> 最低支持 Runtime 版本 `v1.5.20`。行车状态传感器 Bridge 仅供经过审核的 `PACKAGED_H5` 使用；第三方应依赖本 SDK API，不要把 Runtime 的 `window` 内部方法当作稳定接口。
+> SDK 最低支持 Toooony Runtime `v1.5.20`。行车状态传感器 Bridge 仅向审核通过的 `PACKAGED_H5` 开放。第三方表盘应使用本 SDK，不要直接依赖 Runtime 注入到 `window` 上的内部方法。
 
 ## 安装
 
+使用 npm、pnpm 或 yarn 安装：
+
+```bash
+npm install @ziztechnology/dial-library
+```
+
 ```bash
-npm i @ziztechnology/dial-library
+pnpm add @ziztechnology/dial-library
 ```
 
-## 行车状态母版快速接入
+```bash
+yarn add @ziztechnology/dial-library
+```
+
+SDK 是 ESM 包，并自带 TypeScript 类型。
+
+## 快速开始
+
+下面的例子会监听行车状态，并把当前状态显示在页面上：
+
+```html
+<p id="driving-status">正在读取行车状态…</p>
+```
 
 ```ts
-import {
-  OFFICIAL_DRIVING_EXPRESSION_FALLBACKS,
-  createDrivingExpressionPlayer,
-  createDrivingStatusController,
-  readDrivingExpressionsConfig,
-} from '@ziztechnology/dial-library';
+import { CAR_RUNNING_LABELS, createDrivingStatusController } from '@ziztechnology/dial-library';
 
-const config = readDrivingExpressionsConfig();
-if (!config) throw new Error('Unsupported or invalid drivingExpressions config');
+const statusElement = document.querySelector('#driving-status');
+if (!statusElement) throw new Error('找不到 #driving-status');
 
-const player = createDrivingExpressionPlayer(document.querySelector('#expression')!, {
-  config,
-  // 官方母版必须显式传入；第三方不传时不会自动获得官方 Emoji。
-  fallbacks: OFFICIAL_DRIVING_EXPRESSION_FALLBACKS,
-});
 const controller = createDrivingStatusController();
 
-await player.show('STOPPED');
+// 控制器默认从 STOPPED 开始。subscribe 只在稳定状态改变后触发。
+statusElement.textContent = CAR_RUNNING_LABELS[controller.getSnapshot().status];
+
 const unsubscribe = controller.subscribe((event) => {
-  if (event.type === 'status_changed') void player.show(event.status);
+  statusElement.textContent = CAR_RUNNING_LABELS[event.status];
 });
-controller.start();
 
-// 也可以由母版显式控制；默认会自动接入 Runtime pause/resume 和页面生命周期。
-const pause = () => {
-  controller.stop();
-  player.pause();
-};
-const resume = () => {
-  player.resume();
-  controller.start();
-};
+controller.start();
 
-// 页面销毁时：
+// 页面不再使用控制器时释放资源。
 const destroy = () => {
   unsubscribe();
   controller.destroy();
-  player.destroy();
 };
 ```
 
-重复调用 `start()`、`stop()`、`destroy()`、`pause()` 或 `resume()`是安全的。启动时 UI 应先显示 `STOPPED`，只有已提交状态才触发媒体切换，候选状态不会触发 UI。
+`start()` 启动传感器轮询；`destroy()` 停止轮询、取消未完成的读取并移除监听器。`start()`、`stop()` 和 `destroy()` 都可以重复调用。
 
-## 稳定的八状态协议
+控制器默认会跟随 Runtime 和页面生命周期自动暂停、恢复，因此大多数表盘不需要额外监听 `visibilitychange`。
 
-`CarRunningStatus` 的 wire 值和 `CAR_RUNNING_STATUSES` 固定为：
+## 常量
 
-```text
-STOPPED
-STEADY_DRIVING
-ACCELERATION
-RAPID_ACCELERATION
-BRAKING
-SUDDEN_BRAKING
-LEFT_TURN
-RIGHT_TURN
+### 行车状态
+
+`CarRunningStatus` 一共有八种取值。状态字符串是稳定协议，可以用于判断逻辑或作为素材配置的键：
+
+| 常量值               | `CAR_RUNNING_LABELS` 中文名称 | 默认优先级 |
+| -------------------- | ----------------------------- | ---------: |
+| `STOPPED`            | 静止                          |          0 |
+| `STEADY_DRIVING`     | 匀速行驶                      |          0 |
+| `ACCELERATION`       | 加速                          |          1 |
+| `BRAKING`            | 刹车                          |          2 |
+| `LEFT_TURN`          | 左转                          |          3 |
+| `RIGHT_TURN`         | 右转                          |          3 |
+| `RAPID_ACCELERATION` | 急加速                        |          4 |
+| `SUDDEN_BRAKING`     | 急刹车                        |          5 |
+
+相关导出：
+
+- `CAR_RUNNING_STATUSES`：按协议顺序保存全部八种状态，适合遍历。
+- `CAR_RUNNING_LABELS`：状态到中文名称的映射。
+- `CAR_RUNNING_STATUS_PRIORITY`：状态优先级。高优先级动作可以抢占正在展示的低优先级状态。
+
+```ts
+import { CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, type CarRunningStatus } from '@ziztechnology/dial-library';
+
+const renderStatus = (status: CarRunningStatus) => {
+  console.log(status, CAR_RUNNING_LABELS[status]);
+};
+
+CAR_RUNNING_STATUSES.forEach(renderStatus);
 ```
 
-`OFFICIAL_DRIVING_EXPRESSION_FALLBACKS` 提供官方母版的固定默认值：`😐 😊 😄 😲 😣 😱 🤨 🤨`。SDK 不会自动使用这张表；第三方未传 `fallbacks` 时，素材缺失或加载失败只会上报错误。
+### 电池状态
+
+统一传感器信息中的电池字段使用以下字符串联合类型：
 
-## 配置解析
+- `BatteryStatus`：`CHARGING`、`DISCHARGING`、`FULL`、`NOT_CHARGING`、`UNKNOWN`。
+- `BatteryPlugged`：`AC`、`USB`、`WIRELESS`、`DOCK`、`NONE`。
+- `BatteryHealth`：`GOOD`、`OVERHEAT`、`DEAD`、`OVER_VOLTAGE`、`UNSPECIFIED_FAILURE`、`COLD`、`UNKNOWN`。
+- `BATTERY_HEALTH_LABELS`：`BatteryHealth` 到中文名称的映射。
 
-`drivingExpressions` 使用 schema v1，八个状态必须完整且不能包含未知状态。`parseDrivingExpressionsConfig()` 同时接受 JSON 对象和 JSON 字符串，并返回完整、结构化的配置：
+## 统一的传感器
+
+`unifiedSensorInfo()` 一次返回设备当前的统一快照。快照包含陀螺仪、加速度、电池、温度、Wi-Fi、方向和磁场等信息：
 
 ```ts
-import { parseDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+import { unifiedSensorInfo } from '@ziztechnology/dial-library';
+
+const info = await unifiedSensorInfo();
 
-const config = parseDrivingExpressionsConfig(customField.value);
+if (info.temperature.available) {
+  console.log(`电池温度：${info.temperature.value}${info.temperature.unit}`);
+} else {
+  console.log(`温度不可用：${info.temperature.unavailableReason}`);
+}
+
+if (info.linearAcceleration.available) {
+  const { x, y, z } = info.linearAcceleration.value;
+  console.log('线性加速度：', { x, y, z }, info.linearAcceleration.unit);
+}
 ```
 
-支持的素材为：
+每个指标都使用 `available` 作为区分字段：
 
 ```ts
-type StructuredDrivingExpressionMedia =
-  | { kind: 'emoji'; text: string }
-  | { kind: 'image'; mediaAssetId?: number; url: string; mimeType?: string }
-  | { kind: 'video'; mediaAssetId?: number; url: string; coverUrl?: string; mimeType?: string }
-  | { kind: 'live_photo'; mediaAssetId?: number; coverUrl: string; motionUrl: string }
-  | { kind: 'tgs'; mediaAssetId?: number; url: string; coverUrl?: string };
+type SensorMetric<T> =
+  | {
+      available: true;
+      value: T;
+      unit: string | null;
+      source: string;
+      sampledAtMs: number;
+      unavailableReason: null;
+    }
+  | {
+      available: false;
+      value: null;
+      unit: string | null;
+      source: string;
+      sampledAtMs: number | null;
+      unavailableReason: UnifiedSensorUnavailableReason | null;
+    };
 ```
 
-解析器拒绝缺项、轮播字段、非法 kind/字段组合、非单个可见 grapheme 的 Emoji，以及 `http:`、`data:`、`blob:`、localhost、内网/保留 IP、内部单标签 host、带 COS/GCS/OSS 等常见临时签名参数的非长期公网 HTTPS URL。普通公网 HTTPS 与无签名业务 query 仍可使用。后端仍必须按 `mediaAssetId + userID` 重建可信 URL；SDK 静态校验不能替代服务端所有权、DNS 解析和 host allowlist 校验。
+先判断 `available`，TypeScript 才会把 `value` 收窄到真实类型。不要用 `value === null` 猜测设备是否支持某项指标。
+
+常见的 `unavailableReason` 有：
+
+| 原因                   | 含义                       |
+| ---------------------- | -------------------------- |
+| `SENSOR_MISSING`       | 设备没有对应传感器         |
+| `NO_SAMPLE`            | 传感器存在，但暂时没有样本 |
+| `PLATFORM_UNAVAILABLE` | 当前平台不提供该能力       |
+| `PERMISSION_DENIED`    | 没有读取权限               |
+| `NOT_CONNECTED`        | 对应设备或网络未连接       |
 
-`readDrivingExpressionsConfig()` 优先读取 Runtime 注入的 `window.__TOOOONY_DRIVING_EXPRESSIONS__`，再兼容旧 `__TOOOONY_FACE_CONFIG__` 路径；非法或不支持的配置返回 `null`，不会隐式填充官方默认值。
+`capturedAtMs` 是快照时间，具体指标的 `sampledAtMs` 是采样时间。行车状态识别默认拒绝未来样本和超过 1 秒的旧样本。
 
-首版 SDK 接受过裸图片 URL。为兼容旧表盘，`resolveDrivingExpression()` 及 `DrivingExpressionsConfig` 仍保留旧形状；只有显式设置 `{ allowLegacyImageUrls: true }` 时，schema 解析器才会把裸 HTTPS URL 归一化为 `kind: 'image'`。
+### 可用字段
 
-## 纯函数分类
+| 字段                 | 值                                     | 单位     |
+| -------------------- | -------------------------------------- | -------- |
+| `gyroscope`          | `{ x, y, z }`                          | `rad/s`  |
+| `accelerometer`      | `{ x, y, z }`                          | `m/s²`   |
+| `linearAcceleration` | `{ x, y, z }`                          | `m/s²`   |
+| `gravity`            | `{ x, y, z }`                          | `m/s²`   |
+| `magneticField`      | `{ x, y, z }`                          | `µT`     |
+| `orientation`        | `{ azimuth, pitch, roll }`             | `degree` |
+| `motionIntensity`    | 数值；旧 Runtime 中可能不存在          | `m/s²`   |
+| `temperature`        | 数值                                   | `°C`     |
+| `wifiSsid`           | 字符串                                 | 无       |
+| `batteryCapacity`    | `{ levelPercent, chargeCounterUah }`   | 无       |
+| `battery`            | 电池是否存在、充电状态、健康度和电压等 | 无       |
+
+如果只需要根据单次快照做无状态判断，可以使用纯函数 `classifyDrivingSnapshot()`：
 
 ```ts
 import { classifyDrivingSnapshot, unifiedSensorInfo } from '@ziztechnology/dial-library';
 
 const status = classifyDrivingSnapshot(await unifiedSensorInfo());
+
+if (status === null) {
+  console.log('传感器数据不可用、非法或已经过期');
+} else {
+  console.log('当前瞬时状态：', status);
+}
 ```
 
-`classifyDrivingSnapshot(info, tuning?)` 是无状态纯函数。原 API `checkRunningStatus()` 保留为同一函数的兼容别名。数据不可用、非法或超过 1 秒未更新时返回 `null`。
+`checkRunningStatus()` 是同一函数的兼容别名。单次分类不会去抖，也不会保存上一次状态；它使用 Runtime 的 `motionIntensity >= 0.4 m/s²` 判断瞬时行驶。面向 UI 时，通常应该使用下一节带 accelerometer 滑窗的状态控制器。
 
-固定安装方向：
+设备的固定安装方向为：
 
 ```text
 +X = 车身右侧
@@ -117,68 +198,235 @@ const status = classifyDrivingSnapshot(await unifiedSensorInfo());
 -Z = 车辆前进方向
 ```
 
-即 `longitudinal = -linearAcceleration.z`、`lateral = linearAcceleration.x`、`yaw = gyroscope.y`。左转为正 yaw 或负 lateral，右转符号相反。
+因此纵向加速度取 `-linearAcceleration.z`，横向加速度取 `linearAcceleration.x`，偏航角速度取 `gyroscope.y`。
+
+## 行车状态基本使用
 
-默认阈值集中在 `DEFAULT_DRIVING_STATUS_TUNING`，版本为 `driving-status-v1`。仅靠惯性传感器无法严格区分静止和理想匀速直线运动；v1 使用 `motionIntensity` 和陀螺仪扰动近似判断，必须通过固定安装真机路测继续调参。
+### 订阅稳定状态
 
-## 状态控制器
+`createDrivingStatusController()` 负责持续读取传感器，并处理瞬时噪声。推荐让页面只响应它发出的 `status_changed`：
 
 ```ts
+import { CAR_RUNNING_LABELS, createDrivingStatusController } from '@ziztechnology/dial-library';
+
 const controller = createDrivingStatusController({
+  initialStatus: 'STOPPED',
   pollIntervalMs: 200,
+});
+
+const unsubscribe = controller.subscribe((event) => {
+  console.log(`${CAR_RUNNING_LABELS[event.previousStatus]} -> ${CAR_RUNNING_LABELS[event.status]}`, event.reason);
+});
+
+controller.start();
+
+// 临时停止；之后可以再次 start()。
+controller.stop();
+
+// 永久释放；destroy() 后不能重新启动。
+unsubscribe();
+controller.destroy();
+```
+
+控制器默认每 200ms 读取一次，并保证上一次读取结束后才开始下一次。它会对普通动作平滑、要求候选状态连续出现、设置状态最短展示时间，并允许急刹车等高优先级状态抢占。候选状态不会触发 UI，只有提交后的稳定状态才会通知订阅者。
+
+静止和匀速使用 accelerometer 的 1 秒三轴波动窗口判断。窗口按 `sampledAtMs` 去重，至少积累 5 个有效样本；总体标准差大于 `0.4 m/s²` 时进入 `STEADY_DRIVING`，小于 `0.25 m/s²` 时进入 `STOPPED`，中间区间保持原基础状态。滑窗预热不影响加速、刹车或转弯识别。accelerometer 不可用或过期时，整次行车快照进入不可用流程。
+
+### 读取当前状态
+
+订阅只通知后续变化。初次渲染或调试时，可以读取快照：
+
+```ts
+const snapshot = controller.getSnapshot();
+
+console.log(snapshot.status); // 已提交状态
+console.log(snapshot.candidate); // 正在确认的候选状态，可能为 null
+console.log(snapshot.candidateConfirmationCount);
+console.log(snapshot.lifecycle); // stopped、running 或 destroyed
+console.log(snapshot.tuningVersion); // driving-status-v1
+```
+
+### 调整识别参数
+
+默认参数集中在 `DEFAULT_DRIVING_STATUS_TUNING`。只覆盖需要调整的字段即可：
+
+```ts
+const controller = createDrivingStatusController({
+  tuning: {
+    turnYawThreshold: 0.6,
+    motionWindowMs: 1_200,
+    motionMinimumSamples: 6,
+    drivingMotionThreshold: 0.45,
+    stoppedMotionThreshold: 0.28,
+    confirmationSamples: {
+      LEFT_TURN: 3,
+      RIGHT_TURN: 3,
+    },
+  },
+});
+```
+
+`drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，形成进入行驶和退出行驶的迟滞区间。`motionMinimumSamples` 必须是正整数，其余窗口和阈值必须是正有限数值。
+
+固定安装的惯性传感器无法严格区分“完全静止”和“理想匀速直线运动”。默认算法使用三轴加速度波动和陀螺仪扰动近似判断，修改阈值后应在真机上路测。
+
+### 驱动行车表情
+
+Runtime 可以为八种状态注入图片、视频、Live Photo、TGS 或 Emoji 配置。`readDrivingExpressionsConfig()` 会读取并校验这份配置，播放器负责切换素材：
+
+```html
+<div id="expression"></div>
+```
+
+```ts
+import {
+  createDrivingExpressionPlayer,
+  createDrivingStatusController,
+  readDrivingExpressionsConfig,
+} from '@ziztechnology/dial-library';
+
+const container = document.querySelector<HTMLElement>('#expression');
+if (!container) throw new Error('找不到 #expression');
+
+const config = readDrivingExpressionsConfig();
+if (!config) throw new Error('Runtime 未提供有效的行车表情配置');
+
+const player = createDrivingExpressionPlayer(container, { config });
+const controller = createDrivingStatusController();
+
+await player.show(controller.getSnapshot().status);
+
+const unsubscribe = controller.subscribe((event) => {
+  void player.show(event.status);
+});
+
+controller.start();
+
+const destroy = () => {
+  unsubscribe();
+  controller.destroy();
+  player.destroy();
+};
+```
+
+播放器同一时间只保留一个活动动态素材。它会复用视频元素，并在状态离开时停止播放；页面暂停或隐藏时，播放器与控制器都会自动暂停。
+
+## 行车状态的回退
+
+行车状态有两类彼此独立的回退：传感器不可用时的**状态回退**，以及表情素材失败时的**媒体回退**。
+
+### 传感器不可用时回退到静止
+
+控制器遇到一次读取失败、非法快照或过期样本时，会暂时保持最后一个已提交状态，避免页面闪烁。连续不可用达到 3 秒后，控制器才提交 `STOPPED`：
+
+```ts
+const controller = createDrivingStatusController({
   unavailableFallbackMs: 3_000,
-  initialStatus: 'STOPPED',
-  tuning: { turnYawThreshold: 0.32 },
   onDiagnostic(event) {
-    // 诊断事件不包含完整媒体 URL或逐帧传感器数据。
+    if (event.type === 'fallback_to_stopped') {
+      console.warn(`传感器已连续不可用 ${event.unavailableForMs}ms`);
+    }
   },
 });
+
+controller.subscribe((event) => {
+  if (event.reason === 'unavailable_fallback') {
+    console.log('已回退到 STOPPED');
+  }
+});
 ```
 
-控制器统一实现：
+传感器恢复后，控制器会清除不可用状态并重新确认候选，不会立即把单个样本提交给 UI。`unavailableFallbackMs` 必须是大于 0 的有限数值。
+
+### 素材失败时使用显式回退
 
-- 默认 200ms 轮询，读取期间不会发起重叠请求；`stop()` 会通过 `AbortSignal` 取消/忽略未完成读取。
-- 普通动作短窗口平滑，急动作检查未平滑峰值。
-- 急刹车 > 急加速 > 转弯 > 刹车 > 加速 > 静止/匀速的抢占优先级。
-- 急动作 1 样本、转弯/普通动作 2 样本、匀速 3 样本、静止 5 样本的连续确认。
-- 动作退出阈值为入口阈值的 `0.75`，并对静止/匀速使用反向滞回区间。
-- 每个已提交状态的最短展示时间；更高优先级候选可抢占，锁期间继续采样。
-- 单次/短暂不可用保持最后状态；连续不可用达到 3 秒强制提交 `STOPPED`；恢复后重新确认候选。
+SDK 提供 `OFFICIAL_DRIVING_EXPRESSION_FALLBACKS`，对应的默认 Emoji 为：
 
-`getSnapshot()` 返回生命周期、已提交状态、候选计数、不可用起点和 tuning 版本。`subscribe()` 只发送稳定的 `status_changed` 事件；更细的 `sample_available`、`candidate_changed`、`status_held_by_min_duration`、`fallback_to_stopped` 等通过可选 `onDiagnostic` 获取。
+| 状态                 | 回退内容 |
+| -------------------- | -------- |
+| `STOPPED`            | 😐       |
+| `STEADY_DRIVING`     | 😊       |
+| `ACCELERATION`       | 😄       |
+| `RAPID_ACCELERATION` | 😲       |
+| `BRAKING`            | 😣       |
+| `SUDDEN_BRAKING`     | 😱       |
+| `LEFT_TURN`          | 🤨       |
+| `RIGHT_TURN`         | 🤨       |
 
-测试和离线回放可注入 `sensorProvider` 与 `clock`。provider 可接收 `AbortSignal`：
+官方母版必须显式把它传给播放器：
 
 ```ts
-const controller = createDrivingStatusController({
-  sensorProvider: (signal) => replay.next(signal),
-  clock: fakeClock,
+import { OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, createDrivingExpressionPlayer } from '@ziztechnology/dial-library';
+
+const player = createDrivingExpressionPlayer(container, {
+  config,
+  fallbacks: OFFICIAL_DRIVING_EXPRESSION_FALLBACKS,
+  onDiagnostic(event) {
+    if (event.type === 'media_fallback_applied') {
+      console.warn(`${event.status} 已使用 ${event.kind} 回退素材`);
+    }
+  },
 });
 ```
 
-## 媒体播放器
+回退是**选择加入**的：第三方不传 `fallbacks`，SDK 就不会自动使用官方 Emoji。素材缺失、URL 非法、网络失败、超时或解码失败时，播放器会进入错误状态并发送 `media_load_failed` 诊断事件。如果你对你开发的表盘的样式一致性比较高，你可以编写自己的回退。
 
-`createDrivingExpressionPlayer(container, options)` 同时只保留一个活动动态播放器：
+也可以只为部分状态提供自己的回退：
 
-- Emoji 直接渲染本地文本。
-- 图片/GIF 使用原生 `<img>`，保留 GIF 动画。
-- 视频复用一个 `<video muted loop playsinline>`；离开状态时停止并清空，重新进入从 `0` 开始。
-- Live Photo 先显示 cover，motion 就绪后使用静音循环视频；motion 失败时应用该状态 fallback，不会永久停在 cover。
-- TGS 以无凭据 CORS fetch 读取，限制压缩/解压大小、图层数、帧率和帧数；使用 `fflate` 解压并通过 `lottie-web` 循环渲染。
-- TGS 仅接受约定的 TGS、gzip 或 JSON Content-Type；HTML 和无关 MIME 会立即回退。
-- 默认加载超时 5 秒。失败后应用显式 fallback，并按退避时间重试；状态离开、pause 或 destroy 会取消网络、预加载和动画。
-- 轻量预加载顺序为当前状态、`STOPPED`、其余状态；只缓存图片/cover 提示，不同时解码八个视频。
+```ts
+const player = createDrivingExpressionPlayer(container, {
+  config,
+  fallbacks: {
+    STOPPED: { kind: 'emoji', text: '😐' },
+    STEADY_DRIVING: { kind: 'emoji', text: '😊' },
+  },
+});
+```
 
-控制器和播放器默认共享 `window.__watchFaceRuntimePause` / `window.__watchFaceRuntimeResume`、visibility/page 事件及设备传感器 release/resume 事件。SDK 会链接并在最后一个订阅者销毁时恢复页面原有 hook，避免两者相互覆盖。播放器可通过 `managePageLifecycle: false` 显式关闭自动生命周期管理。
+播放器默认等待素材 5 秒，失败后按 15 秒退避重试。可以通过 `loadTimeoutMs` 和 `retryBackoffMs` 调整。Live Photo 的 motion 加载失败时也会应用该状态的显式回退，而不会一直停留在 cover。
 
-可使用 `onDiagnostic` 监听 `media_ready`、`media_load_failed` 和 `media_fallback_applied`。诊断会截断错误消息并移除 URL query，避免记录临时 token。
+### 配置本身无效时
 
-## 开发验证
+`readDrivingExpressionsConfig()` 优先读取 Runtime 注入的 `__TOOOONY_DRIVING_EXPRESSIONS__`，并兼容旧的 `__TOOOONY_FACE_CONFIG__` 路径。配置不存在或无效时返回 `null`，不会替你补齐默认值：
 
-```bash
-pnpm test
-pnpm exec tsc --noEmit
-pnpm run fmt:check
+```ts
+const config = readDrivingExpressionsConfig();
+
+if (!config) {
+  // 由表盘决定：显示静态占位、隐藏组件或终止初始化。
+}
+```
+
+schema v1 要求 `states` 恰好包含全部八种状态。支持的单个状态素材为：
+
+```ts
+type StructuredDrivingExpressionMedia =
+  | { kind: 'emoji'; text: string }
+  | { kind: 'image'; mediaAssetId?: number; url: string; mimeType?: string }
+  | {
+      kind: 'video';
+      mediaAssetId?: number;
+      url: string;
+      coverUrl?: string;
+      mimeType?: string;
+    }
+  | {
+      kind: 'live_photo';
+      mediaAssetId?: number;
+      coverUrl: string;
+      motionUrl: string;
+    }
+  | { kind: 'tgs'; mediaAssetId?: number; url: string; coverUrl?: string };
 ```
 
-测试使用 fake clock、fake sensor provider 和轻量 DOM，覆盖八状态边界、优先级、候选确认、滞回、最短展示、2.9/3 秒不可用边界、生命周期幂等、所有配置 kind、官方/第三方 fallback 差异，以及图片/视频/Live Photo/TGS 播放行为。
+媒体 URL 必须是长期有效的公网 HTTPS 地址。解析器会拒绝 `http:`、`data:`、`blob:`、localhost、内网或保留地址，以及带常见临时签名参数的 URL。服务端仍应根据 `mediaAssetId` 和用户身份重建可信 URL；前端校验不能替代服务端所有权和域名校验。
+
+旧版表盘曾使用裸图片 URL。只有迁移旧配置时，才应显式开启兼容：
+
+```ts
+import { parseDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const config = parseDrivingExpressionsConfig(rawConfig, {
+  allowLegacyImageUrls: true,
+});
+```

package/dist/index.d.mts

@@ -73,6 +73,9 @@ interface DrivingStatusTuning {
   longitudinalThreshold: number;
   turnYawThreshold: number;
   turnLateralThreshold: number;
+  motionWindowMs: number;
+  motionMinimumSamples: number;
+  drivingMotionThreshold: number;
   stoppedMotionThreshold: number;
   stoppedGyroThreshold: number;
   hysteresisRatio: number;

package/dist/index.mjs

@@ -5,10 +5,13 @@ const DEFAULT_DRIVING_STATUS_TUNING = Object.freeze({
 	maxSampleAgeMs: 1e3,
 	rapidLongitudinalThreshold: 3,
 	longitudinalThreshold: 1,
-	turnYawThreshold: .3,
-	turnLateralThreshold: 1.2,
-	stoppedMotionThreshold: .15,
-	stoppedGyroThreshold: .05,
+	turnYawThreshold: .5,
+	turnLateralThreshold: 2.5,
+	motionWindowMs: 1e3,
+	motionMinimumSamples: 5,
+	drivingMotionThreshold: .4,
+	stoppedMotionThreshold: .25,
+	stoppedGyroThreshold: .1,
 	hysteresisRatio: .75,
 	smoothingWindowSize: 3,
 	confirmationSamples: Object.freeze({
@@ -56,8 +59,12 @@ const resolveDrivingStatusTuning = (overrides = {}) => {
 	assertPositiveFinite("longitudinalThreshold", tuning.longitudinalThreshold);
 	assertPositiveFinite("turnYawThreshold", tuning.turnYawThreshold);
 	assertPositiveFinite("turnLateralThreshold", tuning.turnLateralThreshold);
+	assertPositiveFinite("motionWindowMs", tuning.motionWindowMs);
+	if (!Number.isInteger(tuning.motionMinimumSamples) || tuning.motionMinimumSamples < 1) throw new RangeError("motionMinimumSamples must be a positive integer");
+	assertPositiveFinite("drivingMotionThreshold", tuning.drivingMotionThreshold);
 	assertPositiveFinite("stoppedMotionThreshold", tuning.stoppedMotionThreshold);
 	assertPositiveFinite("stoppedGyroThreshold", tuning.stoppedGyroThreshold);
+	if (tuning.drivingMotionThreshold <= tuning.stoppedMotionThreshold) throw new RangeError("drivingMotionThreshold must be greater than stoppedMotionThreshold");
 	if (!Number.isInteger(tuning.smoothingWindowSize) || tuning.smoothingWindowSize < 1) throw new RangeError("smoothingWindowSize must be a positive integer");
 	if (tuning.rapidLongitudinalThreshold < tuning.longitudinalThreshold) throw new RangeError("rapidLongitudinalThreshold must be greater than or equal to longitudinalThreshold");
 	if (!Number.isFinite(tuning.hysteresisRatio) || tuning.hysteresisRatio <= 0 || tuning.hysteresisRatio >= 1) throw new RangeError("hysteresisRatio must be greater than 0 and less than 1");
@@ -92,7 +99,7 @@ const classifyDrivingMetrics = (metrics, tuning = DEFAULT_DRIVING_STATUS_TUNING)
 	if (Math.abs(lateral) >= tuning.turnLateralThreshold) return lateral < 0 ? "LEFT_TURN" : "RIGHT_TURN";
 	if (longitudinal <= -tuning.longitudinalThreshold) return "BRAKING";
 	if (longitudinal >= tuning.longitudinalThreshold) return "ACCELERATION";
-	if (motionIntensity <= tuning.stoppedMotionThreshold && gyroMagnitude <= tuning.stoppedGyroThreshold) return "STOPPED";
+	if (motionIntensity < tuning.drivingMotionThreshold && gyroMagnitude <= tuning.stoppedGyroThreshold) return "STOPPED";
 	return "STEADY_DRIVING";
 };
 const availableFreshVector = (metric, capturedAtMs, maxSampleAgeMs) => {
@@ -628,6 +635,7 @@ var DefaultDrivingStatusController = class {
 	constructor(options) {
 		this.listeners = /* @__PURE__ */ new Set();
 		this.metricWindow = [];
+		this.motionWindow = [];
 		this.candidate = null;
 		this.candidateConfirmationCount = 0;
 		this.lastAvailableAtMs = null;
@@ -662,6 +670,7 @@ var DefaultDrivingStatusController = class {
 		const initialStatus = options.initialStatus ?? "STOPPED";
 		if (!CAR_RUNNING_STATUSES.includes(initialStatus)) throw new TypeError(`Unsupported initialStatus: ${initialStatus}`);
 		this.status = initialStatus;
+		this.baseStatus = isBaseStatus(initialStatus) ? initialStatus : "STOPPED";
 		this.statusCommittedAtMs = this.clock.now();
 	}
 	start() {
@@ -688,6 +697,7 @@ var DefaultDrivingStatusController = class {
 		this.destroyed = true;
 		this.listeners.clear();
 		this.metricWindow.length = 0;
+		this.motionWindow.length = 0;
 	}
 	getSnapshot() {
 		return {
@@ -743,8 +753,9 @@ var DefaultDrivingStatusController = class {
 			const payload = await this.sensorProvider(pendingRead.signal);
 			if (!this.polling || generation !== this.generation || pendingRead.signal.aborted) return;
 			const metrics = extractDrivingSnapshotMetrics(payload, this.tuning);
-			if (metrics === null) this.processUnavailable("invalid_or_stale_snapshot");
-			else this.processAvailable(metrics);
+			const accelerometerSample = extractFreshAccelerometerSample(payload, this.tuning.maxSampleAgeMs);
+			if (metrics === null || accelerometerSample === null) this.processUnavailable("invalid_or_stale_snapshot");
+			else this.processAvailable(metrics, accelerometerSample);
 		} catch (error) {
 			if (!this.polling || generation !== this.generation || pendingRead.signal.aborted || isAbortError$1(error)) return;
 			this.processUnavailable("provider_error");
@@ -753,7 +764,7 @@ var DefaultDrivingStatusController = class {
 			if (this.polling && generation === this.generation) this.schedulePoll(this.pollIntervalMs, generation);
 		}
 	}
-	processAvailable(rawMetrics) {
+	processAvailable(rawMetrics, accelerometerSample) {
 		const now = this.clock.now();
 		this.lastAvailableAtMs = now;
 		this.unavailableSinceMs = null;
@@ -767,14 +778,26 @@ var DefaultDrivingStatusController = class {
 		this.metricWindow.push(rawMetrics);
 		while (this.metricWindow.length > Math.floor(this.tuning.smoothingWindowSize)) this.metricWindow.shift();
 		const smoothedMetrics = averageMetrics(this.metricWindow);
-		const nextCandidate = classifyControllerCandidate(rawMetrics, smoothedMetrics, this.status, this.tuning);
+		const motionIntensity = this.recordMotionSample(accelerometerSample, rawMetrics.capturedAtMs);
+		const nextCandidate = classifyControllerCandidate(rawMetrics, smoothedMetrics, motionIntensity, this.status, this.baseStatus, this.tuning);
 		this.processCandidate(nextCandidate, now);
 	}
+	recordMotionSample(sample, capturedAtMs) {
+		if (!this.motionWindow.some((existing) => existing.sampledAtMs === sample.sampledAtMs)) {
+			this.motionWindow.push(sample);
+			this.motionWindow.sort((left, right) => left.sampledAtMs - right.sampledAtMs);
+		}
+		const cutoffMs = capturedAtMs - this.tuning.motionWindowMs;
+		while (this.motionWindow[0] && this.motionWindow[0].sampledAtMs <= cutoffMs) this.motionWindow.shift();
+		if (this.motionWindow.length < this.tuning.motionMinimumSamples) return null;
+		return combinedAxisStandardDeviation(this.motionWindow);
+	}
 	processUnavailable(category) {
 		const now = this.clock.now();
 		if (this.unavailableSinceMs === null) this.unavailableSinceMs = now;
 		const unavailableForMs = Math.max(0, now - this.unavailableSinceMs);
 		this.metricWindow.length = 0;
+		this.motionWindow.length = 0;
 		this.setCandidate(null, now);
 		this.emitDiagnostic({
 			type: "sample_unavailable",
@@ -828,6 +851,7 @@ var DefaultDrivingStatusController = class {
 		if (nextStatus === this.status) return;
 		const previousStatus = this.status;
 		this.status = nextStatus;
+		if (isBaseStatus(nextStatus)) this.baseStatus = nextStatus;
 		this.statusCommittedAtMs = now;
 		this.setCandidate(null, now);
 		this.heldCandidate = null;
@@ -867,6 +891,7 @@ var DefaultDrivingStatusController = class {
 	}
 	resetTransientRecognition() {
 		this.metricWindow.length = 0;
+		this.motionWindow.length = 0;
 		this.candidate = null;
 		this.candidateConfirmationCount = 0;
 		this.unavailableSinceMs = null;
@@ -885,26 +910,28 @@ var DefaultDrivingStatusController = class {
 		this.unsubscribePageLifecycle = null;
 	}
 };
-const classifyControllerCandidate = (raw, smoothed, current, tuning) => {
-	const entry = classifyEntryCandidate(raw, smoothed, current, tuning);
-	if (!retainsCurrentStatus(raw, smoothed, current, tuning)) return entry;
+const classifyControllerCandidate = (raw, smoothed, motionIntensity, current, baseStatus, tuning) => {
+	const entry = classifyEntryCandidate(raw, smoothed, motionIntensity, baseStatus, tuning);
+	if (!retainsCurrentStatus(raw, smoothed, motionIntensity, current, tuning)) return entry;
 	if (entry === current) return current;
 	if (CAR_RUNNING_STATUS_PRIORITY[entry] > CAR_RUNNING_STATUS_PRIORITY[current]) return entry;
 	if (isOppositeTurn(entry, current)) return entry;
 	if ((entry === "STOPPED" || entry === "STEADY_DRIVING") && (current === "STOPPED" || current === "STEADY_DRIVING")) return entry;
 	return current;
 };
-const classifyEntryCandidate = (raw, smoothed, current, tuning) => {
+const classifyEntryCandidate = (raw, smoothed, motionIntensity, baseStatus, tuning) => {
 	if (raw.longitudinal <= -tuning.rapidLongitudinalThreshold) return "SUDDEN_BRAKING";
 	if (raw.longitudinal >= tuning.rapidLongitudinalThreshold) return "RAPID_ACCELERATION";
 	if (Math.abs(smoothed.yaw) >= tuning.turnYawThreshold) return smoothed.yaw > 0 ? "LEFT_TURN" : "RIGHT_TURN";
 	if (Math.abs(smoothed.lateral) >= tuning.turnLateralThreshold) return smoothed.lateral < 0 ? "LEFT_TURN" : "RIGHT_TURN";
 	if (smoothed.longitudinal <= -tuning.longitudinalThreshold) return "BRAKING";
 	if (smoothed.longitudinal >= tuning.longitudinalThreshold) return "ACCELERATION";
-	const stoppedEntryRatio = current === "STOPPED" ? 1 : tuning.hysteresisRatio;
-	return smoothed.motionIntensity <= tuning.stoppedMotionThreshold * stoppedEntryRatio && smoothed.gyroMagnitude <= tuning.stoppedGyroThreshold * stoppedEntryRatio ? "STOPPED" : "STEADY_DRIVING";
+	if (motionIntensity === null) return baseStatus;
+	if (motionIntensity > tuning.drivingMotionThreshold || smoothed.gyroMagnitude > tuning.stoppedGyroThreshold) return "STEADY_DRIVING";
+	if (motionIntensity < tuning.stoppedMotionThreshold) return "STOPPED";
+	return baseStatus;
 };
-const retainsCurrentStatus = (raw, smoothed, current, tuning) => {
+const retainsCurrentStatus = (raw, smoothed, motionIntensity, current, tuning) => {
 	const ratio = tuning.hysteresisRatio;
 	switch (current) {
 		case "SUDDEN_BRAKING": return raw.longitudinal <= -tuning.rapidLongitudinalThreshold * ratio;
@@ -913,8 +940,8 @@ const retainsCurrentStatus = (raw, smoothed, current, tuning) => {
 		case "RIGHT_TURN": return smoothed.yaw <= -tuning.turnYawThreshold * ratio || smoothed.lateral >= tuning.turnLateralThreshold * ratio;
 		case "BRAKING": return smoothed.longitudinal <= -tuning.longitudinalThreshold * ratio;
 		case "ACCELERATION": return smoothed.longitudinal >= tuning.longitudinalThreshold * ratio;
-		case "STOPPED": return smoothed.motionIntensity <= tuning.stoppedMotionThreshold && smoothed.gyroMagnitude <= tuning.stoppedGyroThreshold;
-		case "STEADY_DRIVING": return false;
+		case "STOPPED": return (motionIntensity === null || motionIntensity <= tuning.drivingMotionThreshold) && smoothed.gyroMagnitude <= tuning.stoppedGyroThreshold;
+		case "STEADY_DRIVING": return motionIntensity === null || motionIntensity >= tuning.stoppedMotionThreshold || smoothed.gyroMagnitude > tuning.stoppedGyroThreshold;
 	}
 };
 const averageMetrics = (metrics) => {
@@ -941,6 +968,45 @@ const averageMetrics = (metrics) => {
 	result.gyroMagnitude /= count;
 	return result;
 };
+const extractFreshAccelerometerSample = (info, maxSampleAgeMs) => {
+	const metric = info?.accelerometer;
+	if (!metric?.available || !Number.isFinite(info.capturedAtMs) || !Number.isFinite(metric.sampledAtMs)) return null;
+	const ageMs = info.capturedAtMs - metric.sampledAtMs;
+	if (ageMs < 0 || ageMs > maxSampleAgeMs) return null;
+	const { x, y, z } = metric.value;
+	if (![
+		x,
+		y,
+		z
+	].every(Number.isFinite)) return null;
+	return {
+		sampledAtMs: metric.sampledAtMs,
+		value: metric.value
+	};
+};
+const combinedAxisStandardDeviation = (samples) => {
+	const count = samples.length;
+	let meanX = 0;
+	let meanY = 0;
+	let meanZ = 0;
+	for (const sample of samples) {
+		meanX += sample.value.x;
+		meanY += sample.value.y;
+		meanZ += sample.value.z;
+	}
+	meanX /= count;
+	meanY /= count;
+	meanZ /= count;
+	let varianceX = 0;
+	let varianceY = 0;
+	let varianceZ = 0;
+	for (const sample of samples) {
+		varianceX += (sample.value.x - meanX) ** 2;
+		varianceY += (sample.value.y - meanY) ** 2;
+		varianceZ += (sample.value.z - meanZ) ** 2;
+	}
+	return Math.sqrt((varianceX + varianceY + varianceZ) / count);
+};
 const defaultSensorProvider = () => {
 	const runtimeGlobal = globalThis;
 	if (typeof runtimeGlobal.unifiedSensorInfo !== "function") return Promise.reject(/* @__PURE__ */ new Error("window.unifiedSensorInfo is unavailable"));
@@ -952,6 +1018,7 @@ const systemClock = {
 	clearTimeout: (handle) => globalThis.clearTimeout(handle)
 };
 const isOppositeTurn = (candidate, current) => candidate === "LEFT_TURN" && current === "RIGHT_TURN" || candidate === "RIGHT_TURN" && current === "LEFT_TURN";
+const isBaseStatus = (status) => status === "STOPPED" || status === "STEADY_DRIVING";
 const isAbortError$1 = (error) => error instanceof Error && error.name === "AbortError";
 const requirePositiveFinite = (name, value) => {
 	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a positive finite number`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziztechnology/dial-library",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "private": false,
   "description": "Tooony 表盘工具函数、方法",
   "files": [