@ziztechnology/dial-library 0.0.1 → 0.0.3

package/README.md

@@ -1 +1,432 @@
-# Toooony 表盘用户 SDK
+# Toooony 表盘 SDK
+
+`@ziztechnology/dial-library` 为 Toooony 表盘提供统一的设备信息和行车状态 API。你可以用它读取传感器，也可以直接订阅经过平滑、确认和回退处理后的行车状态。
+
+> [!NOTE]
+> SDK 最低支持 Toooony Runtime `v1.5.20`。行车状态传感器 Bridge 仅向审核通过的 `PACKAGED_H5` 开放。第三方表盘应使用本 SDK，不要直接依赖 Runtime 注入到 `window` 上的内部方法。
+
+## 安装
+
+使用 npm、pnpm 或 yarn 安装：
+
+```bash
+npm install @ziztechnology/dial-library
+```
+
+```bash
+pnpm add @ziztechnology/dial-library
+```
+
+```bash
+yarn add @ziztechnology/dial-library
+```
+
+SDK 是 ESM 包，并自带 TypeScript 类型。
+
+## 快速开始
+
+下面的例子会监听行车状态，并把当前状态显示在页面上：
+
+```html
+<p id="driving-status">正在读取行车状态…</p>
+```
+
+```ts
+import { CAR_RUNNING_LABELS, createDrivingStatusController } from '@ziztechnology/dial-library';
+
+const statusElement = document.querySelector('#driving-status');
+if (!statusElement) throw new Error('找不到 #driving-status');
+
+const controller = createDrivingStatusController();
+
+// 控制器默认从 STOPPED 开始。subscribe 只在稳定状态改变后触发。
+statusElement.textContent = CAR_RUNNING_LABELS[controller.getSnapshot().status];
+
+const unsubscribe = controller.subscribe((event) => {
+  statusElement.textContent = CAR_RUNNING_LABELS[event.status];
+});
+
+controller.start();
+
+// 页面不再使用控制器时释放资源。
+const destroy = () => {
+  unsubscribe();
+  controller.destroy();
+};
+```
+
+`start()` 启动传感器轮询；`destroy()` 停止轮询、取消未完成的读取并移除监听器。`start()`、`stop()` 和 `destroy()` 都可以重复调用。
+
+控制器默认会跟随 Runtime 和页面生命周期自动暂停、恢复，因此大多数表盘不需要额外监听 `visibilitychange`。
+
+## 常量
+
+### 行车状态
+
+`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);
+```
+
+### 电池状态
+
+统一传感器信息中的电池字段使用以下字符串联合类型：
+
+- `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` 到中文名称的映射。
+
+## 统一的传感器
+
+`unifiedSensorInfo()` 一次返回设备当前的统一快照。快照包含陀螺仪、加速度、电池、温度、Wi-Fi、方向和磁场等信息：
+
+```ts
+import { unifiedSensorInfo } from '@ziztechnology/dial-library';
+
+const info = await unifiedSensorInfo();
+
+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 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;
+    };
+```
+
+先判断 `available`，TypeScript 才会把 `value` 收窄到真实类型。不要用 `value === null` 猜测设备是否支持某项指标。
+
+常见的 `unavailableReason` 有：
+
+| 原因                   | 含义                       |
+| ---------------------- | -------------------------- |
+| `SENSOR_MISSING`       | 设备没有对应传感器         |
+| `NO_SAMPLE`            | 传感器存在，但暂时没有样本 |
+| `PLATFORM_UNAVAILABLE` | 当前平台不提供该能力       |
+| `PERMISSION_DENIED`    | 没有读取权限               |
+| `NOT_CONNECTED`        | 对应设备或网络未连接       |
+
+`capturedAtMs` 是快照时间，具体指标的 `sampledAtMs` 是采样时间。行车状态识别默认拒绝未来样本和超过 1 秒的旧样本。
+
+### 可用字段
+
+| 字段                 | 值                                     | 单位     |
+| -------------------- | -------------------------------------- | -------- |
+| `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);
+}
+```
+
+`checkRunningStatus()` 是同一函数的兼容别名。单次分类不会去抖，也不会保存上一次状态；它使用 Runtime 的 `motionIntensity >= 0.4 m/s²` 判断瞬时行驶。面向 UI 时，通常应该使用下一节带 accelerometer 滑窗的状态控制器。
+
+设备的固定安装方向为：
+
+```text
++X = 车身右侧
++Y = 上方
+-Z = 车辆前进方向
+```
+
+因此纵向加速度取 `-linearAcceleration.z`，横向加速度取 `linearAcceleration.x`，偏航角速度取 `gyroscope.y`。
+
+## 行车状态基本使用
+
+### 订阅稳定状态
+
+`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,
+  onDiagnostic(event) {
+    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 的有限数值。
+
+### 素材失败时使用显式回退
+
+SDK 提供 `OFFICIAL_DRIVING_EXPRESSION_FALLBACKS`，对应的默认 Emoji 为：
+
+| 状态                 | 回退内容 |
+| -------------------- | -------- |
+| `STOPPED`            | 😐       |
+| `STEADY_DRIVING`     | 😊       |
+| `ACCELERATION`       | 😄       |
+| `RAPID_ACCELERATION` | 😲       |
+| `BRAKING`            | 😣       |
+| `SUDDEN_BRAKING`     | 😱       |
+| `LEFT_TURN`          | 🤨       |
+| `RIGHT_TURN`         | 🤨       |
+
+官方母版必须显式把它传给播放器：
+
+```ts
+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` 诊断事件。如果你对你开发的表盘的样式一致性比较高，你可以编写自己的回退。
+
+也可以只为部分状态提供自己的回退：
+
+```ts
+const player = createDrivingExpressionPlayer(container, {
+  config,
+  fallbacks: {
+    STOPPED: { kind: 'emoji', text: '😐' },
+    STEADY_DRIVING: { kind: 'emoji', text: '😊' },
+  },
+});
+```
+
+播放器默认等待素材 5 秒，失败后按 15 秒退避重试。可以通过 `loadTimeoutMs` 和 `retryBackoffMs` 调整。Live Photo 的 motion 加载失败时也会应用该状态的显式回退，而不会一直停留在 cover。
+
+### 配置本身无效时
+
+`readDrivingExpressionsConfig()` 优先读取 Runtime 注入的 `__TOOOONY_DRIVING_EXPRESSIONS__`，并兼容旧的 `__TOOOONY_FACE_CONFIG__` 路径。配置不存在或无效时返回 `null`，不会替你补齐默认值：
+
+```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 };
+```
+
+媒体 URL 必须是长期有效的公网 HTTPS 地址。解析器会拒绝 `http:`、`data:`、`blob:`、localhost、内网或保留地址，以及带常见临时签名参数的 URL。服务端仍应根据 `mediaAssetId` 和用户身份重建可信 URL；前端校验不能替代服务端所有权和域名校验。
+
+旧版表盘曾使用裸图片 URL。只有迁移旧配置时，才应显式开启兼容：
+
+```ts
+import { parseDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const config = parseDrivingExpressionsConfig(rawConfig, {
+  allowLegacyImageUrls: true,
+});
+```