@ziztechnology/dial-library 0.0.15 → 0.0.17

package/README.md

@@ -1,37 +1,57 @@
 # Toooony 表盘 SDK
 
-`@ziztechnology/dial-library` 为 Toooony 表盘提供统一的设备信息和行车状态 API。你可以用它读取传感器，也可以直接订阅经过平滑、确认和回退处理后的行车状态。
+`@ziztechnology/dial-library` 是 Toooony 表盘的前端 SDK，主要做几件事：
+
+1. 读取设备的基础传感器和电池、网络信息；
+2. 把传感器数据分析成“静止、加速、转弯”等行车状态；
+3. 根据行车状态显示 Emoji、图片、视频、Live Photo 或 TGS 动画。
+4. 把网页播放器接入 Runtime 的车载媒体按键和状态同步能力。
+
+SDK 是 ESM 包，自带 TypeScript 类型。
 
 > [!NOTE]
-> SDK 最低支持 Toooony Runtime `v1.5.22`。行车状态传感器 Bridge 仅向审核通过的 `PACKAGED_H5` 开放。第三方表盘应使用本 SDK，不要直接依赖 Runtime 注入到 `window` 上的内部方法。
+> SDK 最低支持 Toooony Runtime `v1.5.22`。行车状态传感器 Bridge 只向审核通过的 `PACKAGED_H5` 开放。表盘应通过本 SDK 使用这些能力，不要直接调用 Runtime 注入到 `window` 上的内部方法。
 
 ## 安装
 
-使用 npm、pnpm 或 yarn 安装：
-
 ```bash
 npm install @ziztechnology/dial-library
 ```
 
-SDK 是 ESM 包，并自带 TypeScript 类型。
+也可以使用 pnpm 或 yarn。
+
+## 功能模块
+
+文档按照 `src` 的公开导出顺序划分：
+
+| 顺序 | 模块           | 解决什么问题                                         |
+| ---- | -------------- | ---------------------------------------------------- |
+| 1    | 基础传感器     | 一次读取陀螺仪、加速度、电池、温度、Wi-Fi 等设备信息 |
+| 2    | 行车状态       | 持续分析传感器数据，得到八种稳定的行车状态           |
+| 3    | 单次分析       | 查看某一帧传感器数据的车辆坐标和瞬时候选状态         |
+| 4    | 行车表情配置   | 读取、解析和校验 Runtime 注入的素材配置              |
+| 5    | 媒体 URL       | 判断素材地址能否作为长期有效的公网 HTTPS URL 使用    |
+| 6    | 行车表情播放器 | 根据状态显示 Emoji、图片、视频、Live Photo 或 TGS    |
+| 7    | 页面生命周期   | 页面隐藏或 Runtime 暂停时，自动暂停传感器和播放器    |
+| 8    | 车载多媒体     | 接收车载播放按键，并把网页播放器状态同步给 Runtime   |
 
 ## 快速开始
 
-下面的例子会监听行车状态，并把当前状态显示在页面上：
+下面的例子只监听行车状态，并把中文状态显示在页面中：
 
 ```html
 <p id="driving-status">正在读取行车状态…</p>
 ```
 
 ```ts
-import { CAR_RUNNING_LABELS, createDrivingStatusController } from '@ziztechnology/dial-library';
+import { CAR_RUNNING_LABELS, DrivingStatusController } from '@ziztechnology/dial-library';
 
-const statusElement = document.querySelector('#driving-status');
+const statusElement = document.querySelector<HTMLElement>('#driving-status');
 if (!statusElement) throw new Error('找不到 #driving-status');
 
-const controller = createDrivingStatusController();
+const controller = new DrivingStatusController();
 
-// 控制器默认从 STOPPED 开始。subscribe 只在稳定状态改变后触发。
+// subscribe 只通知后续变化，所以先显示一次当前状态。
 statusElement.textContent = CAR_RUNNING_LABELS[controller.getSnapshot().status];
 
 const unsubscribe = controller.subscribe((event) => {
@@ -40,62 +60,20 @@ const unsubscribe = controller.subscribe((event) => {
 
 controller.start();
 
-// 页面不再使用控制器时释放资源。
+// 页面销毁时释放资源。
 const destroy = () => {
   unsubscribe();
   controller.destroy();
 };
 ```
 
-`start()` 启动传感器轮询；`destroy()` 停止轮询、取消未完成的读取并移除监听器。`start()`、`stop()` 和 `destroy()` 都可以重复调用。
-
-控制器默认会跟随 Runtime 和页面生命周期自动暂停、恢复，因此大多数表盘不需要额外监听 `visibilitychange`。
+`start()` 开始轮询传感器，`stop()` 临时停止，`destroy()` 永久释放资源。三者都可以安全地重复调用，但 `destroy()` 之后不能重新启动。
 
-## 常量
+## 1. 基础传感器
 
-### 行车状态
+### 读取设备快照
 
-`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、方向和磁场等信息：
+`unifiedSensorInfo()` 会一次返回当前设备信息：
 
 ```ts
 import { unifiedSensorInfo } from '@ziztechnology/dial-library';
@@ -114,99 +92,83 @@ if (info.linearAcceleration.available) {
 }
 ```
 
-每个指标都使用 `available` 作为区分字段：
+每项数据都带有 `available`。先判断它，再读取 `value`：
 
 ```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;
-    };
+if (info.wifiSsid.available) {
+  console.log(info.wifiSsid.value);
+}
 ```
 
-先判断 `available`，TypeScript 才会把 `value` 收窄到真实类型。不要用 `value === null` 猜测设备是否支持某项指标。
+不要只用 `value === null` 判断设备是否支持某项能力，因为不可用的原因可能不同。
 
-常见的 `unavailableReason` 有：
+### 可读取的字段
 
-| 原因                   | 含义                       |
-| ---------------------- | -------------------------- |
-| `SENSOR_MISSING`       | 设备没有对应传感器         |
-| `NO_SAMPLE`            | 传感器存在，但暂时没有样本 |
-| `PLATFORM_UNAVAILABLE` | 当前平台不提供该能力       |
-| `PERMISSION_DENIED`    | 没有读取权限               |
-| `NOT_CONNECTED`        | 对应设备或网络未连接       |
+| 字段                 | 内容                                 | 单位     |
+| -------------------- | ------------------------------------ | -------- |
+| `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`           | 当前 Wi-Fi 名称                      | 无       |
+| `batteryCapacity`    | 电量百分比和电荷计数                 | 无       |
+| `battery`            | 是否有电池、充电状态、健康度、电压等 | 无       |
 
-`capturedAtMs` 是快照时间，具体指标的 `sampledAtMs` 是采样时间。行车状态识别默认拒绝未来样本和超过 1 秒的旧样本。
+`capturedAtMs` 是整个快照的生成时间，单项数据中的 `sampledAtMs` 是该传感器的采样时间。
 
-### 可用字段
+### 数据为什么不可用
 
-| 字段                 | 值                                     | 单位     |
-| -------------------- | -------------------------------------- | -------- |
-| `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`            | 电池是否存在、充电状态、健康度和电压等 | 无       |
+`unavailableReason` 可能是：
 
-如果需要检查单次快照的车辆坐标投影和瞬时候选，可以使用 `classifyDrivingSnapshot()`：
+| 值                     | 含义                     |
+| ---------------------- | ------------------------ |
+| `SENSOR_MISSING`       | 设备没有对应传感器       |
+| `NO_SAMPLE`            | 有传感器，但暂时没有样本 |
+| `PLATFORM_UNAVAILABLE` | 当前平台不提供这项能力   |
+| `PERMISSION_DENIED`    | 没有读取权限             |
+| `NOT_CONNECTED`        | 设备或网络没有连接       |
 
-```ts
-import { classifyDrivingSnapshot, unifiedSensorInfo } from '@ziztechnology/dial-library';
+电池相关类型包括 `BatteryStatus`、`BatteryPlugged` 和 `BatteryHealth`。`BATTERY_HEALTH_LABELS` 可以把电池健康状态转换成中文。
 
-const analysis = classifyDrivingSnapshot(await unifiedSensorInfo());
+## 2. 行车状态
 
-if (analysis === null) {
-  console.log('传感器数据不可用、非法或已经过期');
-} else {
-  console.log('纵向加速度：', analysis.metrics.longitudinal);
-  console.log('偏航角速度：', analysis.metrics.yaw);
-  console.log('瞬时候选：', analysis.candidateStatus);
-  console.log('拒绝原因：', analysis.rejectionReason);
-}
-```
-
-该函数不返回最终的 `STOPPED` 或 `STEADY_DRIVING`，也不保存时间窗口。`candidateStatus` 只能用于诊断，面向 UI 必须使用下一节的状态控制器。
+### 八种状态
 
-设备的正反面和车头朝向需要固定，但允许安装倾角变化。SDK 对重力向量做低通滤波，并动态建立车辆坐标系：
+| 状态                 | 中文     | 默认优先级 |
+| -------------------- | -------- | ---------: |
+| `STOPPED`            | 静止     |          0 |
+| `STEADY_DRIVING`     | 匀速行驶 |          0 |
+| `ACCELERATION`       | 加速     |          1 |
+| `BRAKING`            | 刹车     |          2 |
+| `LEFT_TURN`          | 左转     |          3 |
+| `RIGHT_TURN`         | 右转     |          3 |
+| `RAPID_ACCELERATION` | 急加速   |          4 |
+| `SUDDEN_BRAKING`     | 急刹车   |          5 |
 
-```text
-right   = 将设备 +X 投影到水平面
-up      = 归一化后的 TYPE_GRAVITY
-forward = right × up
-```
+相关导出：
 
-线性加速度和陀螺仪随后投影到该坐标系。标准化后的正偏航表示左转，负偏航表示右转，因此同一安装朝向下的俯仰角偏差不会改变前后、左右和转向符号。
+- `CAR_RUNNING_STATUSES`：全部状态，适合遍历；
+- `CAR_RUNNING_LABELS`：状态对应的中文名称；
+- `CAR_RUNNING_STATUS_PRIORITY`：状态优先级；
+- `CarRunningStatus`：八种状态的 TypeScript 联合类型。
 
-## 行车状态基本使用
+高优先级动作可以抢占正在显示的低优先级状态。
 
-### 订阅稳定状态
+### 持续监听稳定状态
 
-`createDrivingStatusController()` 负责持续读取传感器，并处理瞬时噪声。推荐让页面只响应它发出的 `status_changed`：
+页面展示行车状态时，推荐使用 `new DrivingStatusController()`。它会持续读取传感器，并通过时间窗口过滤瞬时噪声：
 
 ```ts
-import { CAR_RUNNING_LABELS, createDrivingStatusController } from '@ziztechnology/dial-library';
+import { CAR_RUNNING_LABELS, DrivingStatusController } from '@ziztechnology/dial-library';
 
-const controller = createDrivingStatusController({
+const controller = new DrivingStatusController({
   initialStatus: 'STOPPED',
   pollIntervalMs: 200,
+  unavailableFallbackMs: 3_000,
 });
 
 const unsubscribe = controller.subscribe((event) => {
@@ -215,73 +177,206 @@ const unsubscribe = controller.subscribe((event) => {
 
 controller.start();
 
-// 临时停止；之后可以再次 start()。
+// 临时暂停
 controller.stop();
 
-// 永久释放；destroy() 后不能重新启动。
+// 需要时可以再次启动
+controller.start();
+
+// 永久释放
 unsubscribe();
 controller.destroy();
 ```
 
-控制器默认以 200ms 为目标节拍读取，并保证同一时间只有一次 Bridge 读取。下一轮会扣除上一轮 Bridge 耗时；Bridge 本身超过 200ms 时则在返回后立即开始下一轮，避免再叠加固定等待。所有确认都使用传感器时间而不是轮询次数；相同 `sampledAtMs` 的重复数据不会推进窗口。正常 5Hz 采样仍需满足配置的 5/4/3 个样本，较慢的 Bridge 可以用至少 3 个独立观测覆盖同一确认时长；相邻有效观测间隔达到 1 秒时会重新建立动作窗口，不能跨越长数据空洞确认。
-
-静止和匀速使用 accelerometer 的 1 秒三轴 MAD 稳健波动窗口；正常 5Hz 采样至少需要 5 个唯一样本，慢 Bridge 使用相同的时间覆盖规则。运动量不高于 `0.12 m/s²` 且陀螺仪足够稳定，连续 1.5 秒才进入 `STOPPED`；运动量达到 `0.18 m/s²` 或陀螺仪出现持续运动后，从当前运动样本开始连续 0.6 秒才进入 `STEADY_DRIVING`。中间区间保持原基础状态，停车时一次短促晃动不会立即切回行驶。
-
-普通加速和刹车要求 0.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。车辆刚出现方向稳定的物理偏航后，强转向路径要求 0.4 秒内至少 3 个唯一样本，窗口均值达到 `0.08 rad/s`；在默认轮询频率下通常会在 0.4–0.6 秒内触发。转向也可以由累计转角触发，并锁存到回正结束。算法不会预测车辆尚未产生转动时的驾驶意图。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
+控制器默认每 `200ms` 读取一次，并保证同一时间只有一个读取任务。它不会因为一次抖动就改变状态，而是等多个独立样本在一段时间内保持一致后再通知页面。
 
-缓慢转向还要求偏航旋转占陀螺仪能量的主要部分，或存在足够的横向加速度；垂直颠簸占主导且缺少偏航佐证时不会创建转向事件。重力样本短时缺失时，控制器会在 `maxSampleAgeMs` 内复用最后一个滤波后的车辆坐标系；缓存到期后按传感器不可用处理。单独调用 `classifyDrivingSnapshot()` 不会使用控制器缓存。
+如果传感器短暂失败，控制器会先保留最后状态。连续不可用达到 `unavailableFallbackMs` 后，才回退到 `STOPPED`。
 
-### 读取当前状态
-
-订阅只通知后续变化。初次渲染或调试时，可以读取快照：
+### 读取控制器当前情况
 
 ```ts
 const snapshot = controller.getSnapshot();
 
-console.log(snapshot.status); // 已提交状态
+console.log(snapshot.status); // 当前已经确认的状态
 console.log(snapshot.candidate); // 正在确认的候选状态，可能为 null
-console.log(snapshot.candidateSinceMs); // 候选首次出现的传感器时间
-console.log(snapshot.activeTurn); // 已锁存的转向事件
 console.log(snapshot.baseStatus); // STOPPED 或 STEADY_DRIVING
+console.log(snapshot.activeTurn); // 当前锁定的转向，可能为 null
 console.log(snapshot.lifecycle); // stopped、running 或 destroyed
-console.log(snapshot.tuningVersion);
 ```
 
 ### 调整识别参数
 
-默认参数集中在 `DEFAULT_DRIVING_STATUS_TUNING`。只覆盖需要调整的字段即可：
+默认参数保存在 `DEFAULT_DRIVING_STATUS_TUNING`。通常不需要修改；真车测试发现识别过慢或过于敏感时，只覆盖需要调整的字段：
 
 ```ts
-const controller = createDrivingStatusController({
+const controller = new DrivingStatusController({
   tuning: {
     turnYawThreshold: 0.08,
     turnConfirmationMs: 400,
-    turnMinimumSamples: 3,
-    motionWindowMs: 1_200,
-    motionMinimumSamples: 6,
-    drivingMotionThreshold: 0.2,
-    stoppedMotionThreshold: 0.11,
-    stoppedConfirmationMs: 1_500,
     longitudinalThreshold: 0.75,
-    turnYawDominanceThreshold: 0.65,
-    turnLateralEvidenceThreshold: 0.3,
+    stoppedConfirmationMs: 1_500,
+  },
+});
+```
+
+可以先调用 `resolveDrivingStatusTuning(overrides)` 检查参数并得到完整配置。阈值和时间窗口必须是有效的正数，样本数必须是正整数。调整后应使用完整路测数据验证，不要只用一两帧数据判断效果。
+
+### 诊断识别过程
+
+`onDiagnostic` 适合调试和真车调参：
+
+```ts
+const controller = new DrivingStatusController({
+  onDiagnostic(event) {
+    if (event.type === 'detector_transition') {
+      console.log(event.detector, event.phase, event.status, event.statistics);
+    }
+
+    if (event.type === 'fallback_to_stopped') {
+      console.warn(`传感器已连续不可用 ${event.unavailableForMs}ms`);
+    }
+  },
+});
+```
+
+诊断事件会告诉你样本是否有效、各检测器看到了什么证据、候选状态为什么进入或退出，以及何时因为传感器不可用而回退。
+
+## 3. 单次分析
+
+`classifyDrivingSnapshot()` 分析一份传感器快照，适合开发和调试：
+
+```ts
+import { classifyDrivingSnapshot, unifiedSensorInfo } from '@ziztechnology/dial-library';
+
+const analysis = classifyDrivingSnapshot(await unifiedSensorInfo());
+
+if (!analysis) {
+  console.log('必要的传感器数据缺失、非法或已经过期');
+} else {
+  console.log('纵向加速度：', analysis.metrics.longitudinal);
+  console.log('横向加速度：', analysis.metrics.lateral);
+  console.log('偏航角速度：', analysis.metrics.yaw);
+  console.log('瞬时候选状态：', analysis.candidateStatus);
+  console.log('是否因颠簸被拒绝：', analysis.rejectionReason);
+}
+```
+
+这个函数只看当前快照，不保存时间窗口，因此不会给出最终的 `STOPPED` 或 `STEADY_DRIVING`。页面 UI 应使用状态控制器，不能把 `candidateStatus` 当成最终结果。
+
+更底层的分析接口还有：
+
+- `extractDrivingSnapshotMetrics()`：提取车辆坐标系下的纵向、横向、垂直和偏航数据；
+- `buildVehicleFrame()`：根据重力方向建立车辆坐标系。
+
+这两个接口主要用于算法调试。设备安装时应固定正反面和车头方向；安装倾角可以变化，SDK 会根据重力方向进行校正。
+
+## 4. 行车表情配置
+
+Runtime 会把配置注入到 `__TOOOONY_DRIVING_EXPRESSIONS__`。正常情况下直接读取：
+
+```ts
+import { readDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const config = readDrivingExpressionsConfig();
+
+if (!config) {
+  console.log('Runtime 没有提供完整、有效的行车表情配置');
+}
+```
+
+配置不存在或无效时返回 `null`，SDK 不会偷偷补上默认素材。
+
+### 配置格式
+
+`schemaVersion: 1` 要求 `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 };
+```
+
+最小示例：
+
+```ts
+const rawConfig = {
+  schemaVersion: 1,
+  states: {
+    STOPPED: { kind: 'emoji', text: '😐' },
+    STEADY_DRIVING: { kind: 'emoji', text: '😊' },
+    ACCELERATION: { kind: 'emoji', text: '😄' },
+    RAPID_ACCELERATION: { kind: 'emoji', text: '😲' },
+    BRAKING: { kind: 'emoji', text: '😣' },
+    SUDDEN_BRAKING: { kind: 'emoji', text: '😱' },
+    LEFT_TURN: { kind: 'emoji', text: '🤨' },
+    RIGHT_TURN: { kind: 'emoji', text: '🤨' },
   },
+};
+```
+
+### 解析配置
+
+| API                                     | 结果                                           |
+| --------------------------------------- | ---------------------------------------------- |
+| `parseDrivingExpressionsConfig(raw)`    | 配置无效时抛出 `DrivingExpressionsConfigError` |
+| `tryParseDrivingExpressionsConfig(raw)` | 配置无效时返回 `null`                          |
+| `readDrivingExpressionsConfig()`        | 读取 Runtime 注入值；不存在或无效时返回 `null` |
+| `waitForDrivingExpressionsConfig()`     | 等待晚到的注入；超时返回 `null`                |
+
+Runtime 通常会在页面脚本运行前完成注入。只有确实需要兼容晚注入时，才使用异步等待：
+
+```ts
+import { waitForDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const abortController = new AbortController();
+window.addEventListener('pagehide', () => abortController.abort(), { once: true });
+
+const config = await waitForDrivingExpressionsConfig({
+  timeoutMs: 3_000,
+  pollIntervalMs: 100,
+  signal: abortController.signal,
+});
+```
+
+取消时 Promise 会以 `AbortError` 结束。
+
+旧版配置允许直接写图片 URL。只在迁移旧配置时开启兼容：
+
+```ts
+const config = parseDrivingExpressionsConfig(rawConfig, {
+  allowLegacyImageUrls: true,
 });
 ```
 
-`drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，进入阈值也必须大于相应退出阈值。样本数必须是正整数，方向一致率必须大于 `0.5` 且不大于 `1`，其余窗口和阈值必须是正有限数值。
+`resolveDrivingExpression()` 会在某个旧版状态缺失时使用 `STEADY_DRIVING` 素材；`resolveDrivingExpressionStrict()` 不会自动这样做，缺失且没有显式回退时会抛出错误。播放器使用严格规则。
+
+## 5. 媒体 URL
+
+图片、视频、Live Photo 和 TGS 使用的地址必须是长期有效的公网 HTTPS URL。
 
-### 识别诊断
+```ts
+import { isPublicDrivingMediaUrl } from '@ziztechnology/dial-library';
+
+console.log(isPublicDrivingMediaUrl('https://cdn.example.com/expression.png')); // true
+console.log(isPublicDrivingMediaUrl('http://cdn.example.com/expression.png')); // false
+console.log(isPublicDrivingMediaUrl('https://localhost/expression.png')); // false
+```
 
-`onDiagnostic` 的 `sample_available` 事件包含 `frameSource`（`live` 或 `cached`）和 `frameAgeMs`。`detector_evidence` 会报告基础状态 MAD、普通/急加减速的均值、峰值、方向一致率和 RMS，以及转向的累计角度、偏航主导率和横向/垂直 RMS。
+SDK 会拒绝：
 
-检测器状态变化时还会发送 `detector_transition`，其 `phase` 为 `candidate_entered`、`candidate_rejected`、`candidate_confirmed` 或 `candidate_exited`。该事件携带当时的完整 `statistics`，可直接用于真车回放调参；同一状态不会逐轮询重复发送。
+- `http:`、`data:`、`blob:` 等非 HTTPS 地址；
+- 带用户名或密码的地址；
+- localhost、内网 IP 和保留地址；
+- 带常见临时签名参数的地址。
 
-惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 1.5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
+前端 URL 校验只能防止明显错误。服务端仍应根据 `mediaAssetId` 和用户身份检查素材所有权，并重新生成可信地址。
 
-### 驱动行车表情
+## 6. 行车表情播放器
 
-Runtime 可以为八种状态注入图片、视频、Live Photo、TGS 或 Emoji 配置。`readDrivingExpressionsConfig()` 会读取并校验这份配置，播放器负责切换素材：
+### 把状态和素材连起来
 
 ```html
 <div id="expression"></div>
@@ -290,7 +385,7 @@ Runtime 可以为八种状态注入图片、视频、Live Photo、TGS 或 Emoji
 ```ts
 import {
   createDrivingExpressionPlayer,
-  createDrivingStatusController,
+  DrivingStatusController,
   readDrivingExpressionsConfig,
 } from '@ziztechnology/dial-library';
 
@@ -301,7 +396,7 @@ const config = readDrivingExpressionsConfig();
 if (!config) throw new Error('Runtime 未提供有效的行车表情配置');
 
 const player = createDrivingExpressionPlayer(container, { config });
-const controller = createDrivingStatusController();
+const controller = new DrivingStatusController();
 
 await player.show(controller.getSnapshot().status);
 
@@ -318,53 +413,13 @@ const destroy = () => {
 };
 ```
 
-播放器同一时间只保留一个活动动态素材。它会复用视频元素，并在状态离开时停止播放；页面暂停或隐藏时，播放器与控制器都会自动暂停。
-
-TGS 使用 SDK 内置的 SVG light 播放器，并且只在首次显示 TGS 素材时动态加载。表盘项目不需要安装、导入或配置 `lottie-web`，也不需要为构建工具添加 Lottie alias。
-
-## 行车状态的回退
-
-行车状态有两类彼此独立的回退：传感器不可用时的**状态回退**，以及表情素材失败时的**媒体回退**。
-
-### 传感器不可用时回退到静止
-
-控制器遇到一次读取失败、非法快照或过期样本时，会暂时保持最后一个已提交状态和仍在有效时间范围内的识别窗口，避免页面闪烁或丢失转向、刹车证据。连续不可用达到 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');
-  }
-});
-```
-
-传感器恢复后，控制器会清除不可用状态；短缺样前后的时间窗仍需满足独立观测数、持续时间和小于 1 秒的相邻间隔约束，不会把跨越长空洞的数据或单个样本提交给 UI。`unavailableFallbackMs` 必须是大于 0 的有限数值。
+播放器会复用视频元素，并保证同一时间只有一个动态素材在播放。TGS 播放能力已包含在 SDK 中，表盘项目不需要额外安装或配置 `lottie-web`。
 
-### 素材失败时使用显式回退
+播放器提供 `show()`、`pause()`、`resume()`、`destroy()` 和 `getSnapshot()`。快照中的 `phase` 可能是 `idle`、`loading`、`ready`、`fallback` 或 `error`。
 
-SDK 提供 `OFFICIAL_DRIVING_EXPRESSION_FALLBACKS`，对应的默认 Emoji 为：
+### 素材失败时使用回退
 
-| 状态                 | 回退内容 |
-| -------------------- | -------- |
-| `STOPPED`            | 😐       |
-| `STEADY_DRIVING`     | 😊       |
-| `ACCELERATION`       | 😄       |
-| `RAPID_ACCELERATION` | 😲       |
-| `BRAKING`            | 😣       |
-| `SUDDEN_BRAKING`     | 😱       |
-| `LEFT_TURN`          | 🤨       |
-| `RIGHT_TURN`         | 🤨       |
-
-官方母版必须显式把它传给播放器：
+官方 Emoji 回退不会自动启用，需要显式传入：
 
 ```ts
 import { OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, createDrivingExpressionPlayer } from '@ziztechnology/dial-library';
@@ -380,79 +435,156 @@ const player = createDrivingExpressionPlayer(container, {
 });
 ```
 
-回退是**选择加入**的：第三方不传 `fallbacks`，SDK 就不会自动使用官方 Emoji。素材缺失、URL 非法、网络失败、超时或解码失败时，播放器会进入错误状态并发送 `media_load_failed` 诊断事件。如果你对你开发的表盘的样式一致性比较高，你可以编写自己的回退。
-
-也可以只为部分状态提供自己的回退：
+也可以只为部分状态提供自己的 Emoji 或图片回退：
 
 ```ts
 const player = createDrivingExpressionPlayer(container, {
   config,
   fallbacks: {
     STOPPED: { kind: 'emoji', text: '😐' },
-    STEADY_DRIVING: { kind: 'emoji', text: '😊' },
+    STEADY_DRIVING: { kind: 'image', url: 'https://cdn.example.com/steady.png' },
   },
 });
 ```
 
-播放器默认等待素材 5 秒，失败后按 15 秒退避重试。可以通过 `loadTimeoutMs` 和 `retryBackoffMs` 调整。Live Photo 的 motion 加载失败时也会应用该状态的显式回退，而不会一直停留在 cover。
+只有 Emoji 和图片可以作为回退素材。网络失败、加载超时、解码失败或配置无效时，`onDiagnostic` 会收到 `media_load_failed`；如果有可用回退，还会收到 `media_fallback_applied`。
 
-### 配置本身无效时
+默认加载超时是 5 秒，失败后 15 秒再重试。可以通过 `loadTimeoutMs` 和 `retryBackoffMs` 修改。图片和视频的显示方式可以通过 `fit: 'contain' | 'cover'` 设置。
 
-`readDrivingExpressionsConfig()` 只读取 Runtime 注入的 `__TOOOONY_DRIVING_EXPRESSIONS__`。配置不存在或无效时返回 `null`，不会替你补齐默认值：
+## 7. 页面生命周期
 
-```ts
-const config = readDrivingExpressionsConfig();
+状态控制器和播放器默认都会跟随以下情况自动暂停和恢复：
 
-if (!config) {
-  // 由表盘决定：显示静态占位、隐藏组件或终止初始化。
-}
-```
+- 页面隐藏或重新显示；
+- `pagehide`、`pageshow`、`freeze`、`resume`；
+- Runtime 的传感器暂停和恢复通知。
 
-Runtime v1.5.22 及以上的 PACKAGED_H5 会在 document-start 阶段完成配置注入，因此优先使用上述同步读取。若需要容忍异常的晚注入时序，可以进行一次有上限的异步等待：
+因此大多数表盘不需要自己监听 `visibilitychange`。如果页面已经有统一的生命周期管理，可以关闭自动管理，再手动调用相应方法：
 
 ```ts
-import { waitForDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+const controller = new DrivingStatusController({
+  managePageLifecycle: false,
+});
 
-const abortController = new AbortController();
-const config = await waitForDrivingExpressionsConfig({
-  timeoutMs: 3_000,
-  pollIntervalMs: 100,
-  signal: abortController.signal,
+const player = createDrivingExpressionPlayer(container, {
+  config,
+  managePageLifecycle: false,
 });
 ```
 
-该函数会立即读取一次，之后使用单个定时器重试。首次读到完整合法的配置时返回；超时返回 `null`；取消时以 `AbortError` 结束。它不会隐式使用官方 Emoji，超时后的界面和回退仍由表盘决定。页面卸载时应调用 `abortController.abort()`。
+关闭后，页面需要自行调用 `controller.start()` / `controller.stop()` 和 `player.resume()` / `player.pause()`。页面最终销毁时仍应调用两者的 `destroy()`。
+
+## 8. 车载多媒体
+
+多媒体控制器把网页播放器接入 Runtime 的车载媒体控制能力。页面只需要提供当前状态和播放回调，不要直接创建或调用 `window.AndroidCarBridge`、`window.__carBridge`，也不要自行监听 Runtime 的内部媒体事件。
 
-schema v1 要求 `states` 恰好包含全部八种状态。支持的单个状态素材为：
+`AndroidCarBridge` 不依赖 `customFields`，Runtime 会为加载的本地 H5 和直接打开的外部网址注入该能力。页面可以直接创建控制器：
 
 ```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 };
-```
+import { MultimediaController } from '@ziztechnology/dial-library';
 
-媒体 URL 必须是长期有效的公网 HTTPS 地址。解析器会拒绝 `http:`、`data:`、`blob:`、localhost、内网或保留地址，以及带常见临时签名参数的 URL。服务端仍应根据 `mediaAssetId` 和用户身份重建可信 URL；前端校验不能替代服务端所有权和域名校验。
+const tracks = [
+  { title: 'First Song', artist: 'Toooony', url: 'https://cdn.example.com/first.mp3' },
+  { title: 'Second Song', artist: 'Toooony', url: 'https://cdn.example.com/second.mp3' },
+];
 
-旧版表盘曾使用裸图片 URL。只有迁移旧配置时，才应显式开启兼容：
+const audio = new Audio();
+let currentIndex = 0;
 
-```ts
-import { parseDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+const loadCurrentTrack = () => {
+  audio.src = tracks[currentIndex].url;
+  audio.load();
+};
 
-const config = parseDrivingExpressionsConfig(rawConfig, {
-  allowLegacyImageUrls: true,
+let multimedia: MultimediaController;
+
+const changeTrack = async (offset: number) => {
+  currentIndex = (currentIndex + offset + tracks.length) % tracks.length;
+  loadCurrentTrack();
+  await audio.play();
+};
+
+loadCurrentTrack();
+
+multimedia = new MultimediaController({
+  getState() {
+    const track = tracks[currentIndex];
+    return {
+      isPlaying: !audio.paused && !audio.ended,
+      title: track.title,
+      artist: track.artist,
+      canNext: tracks.length > 1,
+      canPrevious: tracks.length > 1,
+    };
+  },
+  controls: {
+    play: () => audio.play(),
+    pause: () => audio.pause(),
+    next: () => changeTrack(1),
+    previous: () => changeTrack(-1),
+    seekToMs: (positionMs) => {
+      audio.currentTime = positionMs / 1_000;
+    },
+  },
 });
+
+// 播放状态变化时立即同步；播放期间 SDK 还会每秒补报一次。
+const reportState = () => multimedia.reportState();
+audio.addEventListener('playing', reportState);
+audio.addEventListener('pause', reportState);
+audio.addEventListener('ended', reportState);
+
+window.addEventListener(
+  'pagehide',
+  () => {
+    audio.removeEventListener('playing', reportState);
+    audio.removeEventListener('pause', reportState);
+    audio.removeEventListener('ended', reportState);
+    multimedia.destroy();
+  },
+  { once: true },
+);
 ```
+
+### 播放器状态
+
+`getState()` 必须同步返回以下五个字段。SDK 只会把这些字段交给 Runtime：
+
+| 字段          | 含义                     |
+| ------------- | ------------------------ |
+| `isPlaying`   | 当前是否正在播放         |
+| `title`       | 当前内容标题             |
+| `artist`      | 当前作者或歌手           |
+| `canNext`     | 当前是否允许切换到下一项 |
+| `canPrevious` | 当前是否允许切换到上一项 |
+
+当前 Runtime 不读取 `positionMs`、`durationMs`、`album` 或 `artworkUrl` 等扩展字段，因此它们不属于 SDK 的状态契约。曲目或导航能力发生变化时，即使播放状态没有变化，也应调用 `reportState()`。
+
+### 控制回调和状态上报
+
+`play` 和 `pause` 是必需回调；`toggle`、`next`、`previous`、`seekToMs` 可以省略。没有提供 `toggle` 时，SDK 会根据 `getState().isPlaying` 自动选择 `play` 或 `pause`。Runtime 只会给 `seekToMs` 传入有限且非负的毫秒值，SDK 也会拒绝非法值。
+
+控制回调可以返回 Promise。回调成功后 SDK 会再上报一次状态；异步失败会写入 SDK 和 Android 日志，不会形成未处理的 Promise rejection。业务仍应在真实的播放器事件中调用 `reportState()`，因为播放开始、缓冲或曲目加载可能晚于控制回调。
+
+首次创建时，SDK 会先读取并校验初始状态，再通知 Runtime 控制器已经 ready，随后立即上报该状态。初始状态无效或读取失败时不会向 Runtime 留下可接收按键的 ready 控制器。只要最新状态中的 `isPlaying` 为 `true`，SDK 就会默认每 `1_000ms` 补报一次；可以用 `reportIntervalMs` 设置其他正数间隔。一次临时的状态读取失败不会停止心跳，后续周期会继续重试。暂停或销毁后心跳会停止。
+
+同一个页面同一时间只能存在一个多媒体控制器。SDK 不会覆盖已有的内部 `__carBridge`；不再使用时必须调用 `destroy()`，该方法可以安全地重复调用。支持媒体生命周期协议的 Runtime 会在销毁时立即清除 ready、最后播放状态和按键路由状态，因此旧控制器不会继续吞掉车载按键。旧版 Runtime 不支持显式销毁通知时，SDK 会尽力补报一次暂停状态，页面切换或 Runtime 停用 WebView 时仍会完成最终清理。初始化异常可以通过 `MultimediaBridgeError.code` 区分：
+
+| code                                      | 含义                                   |
+| ----------------------------------------- | -------------------------------------- |
+| `MULTIMEDIA_BRIDGE_CONFLICT`              | 页面已经存在媒体命令入口或另一个控制器 |
+| `MULTIMEDIA_BRIDGE_INITIALIZATION_FAILED` | Ready 通知或初始状态上报失败           |
+
+## 常用导出速查
+
+| 需求                  | 推荐 API                            |
+| --------------------- | ----------------------------------- |
+| 读取一次设备信息      | `unifiedSensorInfo()`               |
+| 持续获取稳定行车状态  | `new DrivingStatusController()`     |
+| 分析一帧传感器数据    | `classifyDrivingSnapshot()`         |
+| 读取 Runtime 素材配置 | `readDrivingExpressionsConfig()`    |
+| 等待晚注入的配置      | `waitForDrivingExpressionsConfig()` |
+| 校验一份原始配置      | `parseDrivingExpressionsConfig()`   |
+| 检查媒体 URL          | `isPublicDrivingMediaUrl()`         |
+| 根据状态播放素材      | `createDrivingExpressionPlayer()`   |
+| 接入车载多媒体控制    | `new MultimediaController()`        |