@ziztechnology/dial-library 0.0.12 → 0.0.14

package/README.md

@@ -3,7 +3,7 @@
 `@ziztechnology/dial-library` 为 Toooony 表盘提供统一的设备信息和行车状态 API。你可以用它读取传感器，也可以直接订阅经过平滑、确认和回退处理后的行车状态。
 
 > [!NOTE]
-> SDK 最低支持 Toooony Runtime `v1.5.20`。行车状态传感器 Bridge 仅向审核通过的 `PACKAGED_H5` 开放。第三方表盘应使用本 SDK，不要直接依赖 Runtime 注入到 `window` 上的内部方法。
+> SDK 最低支持 Toooony Runtime `v1.5.22`。行车状态传感器 Bridge 仅向审核通过的 `PACKAGED_H5` 开放。第三方表盘应使用本 SDK，不要直接依赖 Runtime 注入到 `window` 上的内部方法。
 
 ## 安装
 
@@ -223,11 +223,11 @@ unsubscribe();
 controller.destroy();
 ```
 
-控制器默认每 200ms 读取一次，并保证上一次读取结束后才开始下一次。所有确认都使用传感器时间而不是轮询次数；相同 `sampledAtMs` 的重复数据不会推进窗口。
+控制器默认以 200ms 为目标节拍读取，并保证同一时间只有一次 Bridge 读取。下一轮会扣除上一轮 Bridge 耗时；Bridge 本身超过 200ms 时则在返回后立即开始下一轮，避免再叠加固定等待。所有确认都使用传感器时间而不是轮询次数；相同 `sampledAtMs` 的重复数据不会推进窗口。正常 5Hz 采样仍需满足配置的 5/4/3 个样本，较慢的 Bridge 可以用至少 3 个独立观测覆盖同一确认时长；相邻有效观测间隔达到 1 秒时会重新建立动作窗口，不能跨越长数据空洞确认。
 
-静止和匀速使用 accelerometer 的 1 秒三轴 MAD 稳健波动窗口，至少需要 5 个唯一样本。运动量不高于 `0.12 m/s²` 且陀螺仪足够稳定，连续 5 秒才进入 `STOPPED`；运动量达到 `0.18 m/s²` 或陀螺仪出现持续运动，连续 0.6 秒进入 `STEADY_DRIVING`。中间区间保持原基础状态。
+静止和匀速使用 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.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。车辆刚出现方向稳定的物理偏航后，强转向路径要求 0.4 秒内至少 3 个唯一样本，窗口均值达到 `0.08 rad/s`；在默认轮询频率下通常会在 0.4–0.6 秒内触发。转向也可以由累计转角触发，并锁存到回正结束。算法不会预测车辆尚未产生转动时的驾驶意图。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
 
 缓慢转向还要求偏航旋转占陀螺仪能量的主要部分，或存在足够的横向加速度；垂直颠簸占主导且缺少偏航佐证时不会创建转向事件。重力样本短时缺失时，控制器会在 `maxSampleAgeMs` 内复用最后一个滤波后的车辆坐标系；缓存到期后按传感器不可用处理。单独调用 `classifyDrivingSnapshot()` 不会使用控制器缓存。
 
@@ -254,12 +254,14 @@ console.log(snapshot.tuningVersion);
 ```ts
 const controller = createDrivingStatusController({
   tuning: {
-    turnYawThreshold: 0.13,
+    turnYawThreshold: 0.08,
+    turnConfirmationMs: 400,
+    turnMinimumSamples: 3,
     motionWindowMs: 1_200,
     motionMinimumSamples: 6,
     drivingMotionThreshold: 0.2,
     stoppedMotionThreshold: 0.11,
-    stoppedConfirmationMs: 5_000,
+    stoppedConfirmationMs: 1_500,
     longitudinalThreshold: 0.75,
     turnYawDominanceThreshold: 0.65,
     turnLateralEvidenceThreshold: 0.3,
@@ -275,7 +277,7 @@ const controller = createDrivingStatusController({
 
 检测器状态变化时还会发送 `detector_transition`，其 `phase` 为 `candidate_entered`、`candidate_rejected`、`candidate_confirmed` 或 `candidate_exited`。该事件携带当时的完整 `statistics`，可直接用于真车回放调参；同一状态不会逐轮询重复发送。
 
-惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
+惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 1.5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
 
 ### 驱动行车表情
 
@@ -326,7 +328,7 @@ TGS 使用 SDK 内置的 SVG light 播放器，并且只在首次显示 TGS 素
 
 ### 传感器不可用时回退到静止
 
-控制器遇到一次读取失败、非法快照或过期样本时，会暂时保持最后一个已提交状态，避免页面闪烁。连续不可用达到 3 秒后，控制器才提交 `STOPPED`：
+控制器遇到一次读取失败、非法快照或过期样本时，会暂时保持最后一个已提交状态和仍在有效时间范围内的识别窗口，避免页面闪烁或丢失转向、刹车证据。连续不可用达到 3 秒后，控制器才清空窗口并提交 `STOPPED`：
 
 ```ts
 const controller = createDrivingStatusController({
@@ -345,7 +347,7 @@ controller.subscribe((event) => {
 });
 ```
 
-传感器恢复后，控制器会清除不可用状态并重新确认候选，不会立即把单个样本提交给 UI。`unavailableFallbackMs` 必须是大于 0 的有限数值。
+传感器恢复后，控制器会清除不可用状态；短缺样前后的时间窗仍需满足独立观测数、持续时间和小于 1 秒的相邻间隔约束，不会把跨越长空洞的数据或单个样本提交给 UI。`unavailableFallbackMs` 必须是大于 0 的有限数值。
 
 ### 素材失败时使用显式回退
 
@@ -396,7 +398,7 @@ const player = createDrivingExpressionPlayer(container, {
 
 ### 配置本身无效时
 
-`readDrivingExpressionsConfig()` 优先读取 Runtime 注入的 `__TOOOONY_DRIVING_EXPRESSIONS__`，并兼容旧的 `__TOOOONY_FACE_CONFIG__` 路径。配置不存在或无效时返回 `null`，不会替你补齐默认值：
+`readDrivingExpressionsConfig()` 只读取 Runtime 注入的 `__TOOOONY_DRIVING_EXPRESSIONS__`。配置不存在或无效时返回 `null`，不会替你补齐默认值：
 
 ```ts
 const config = readDrivingExpressionsConfig();
@@ -406,7 +408,7 @@ if (!config) {
 }
 ```
 
-正常的 PACKAGED_H5 Runtime 会在 document-start 阶段完成配置注入，因此优先使用上述同步读取。若表盘还需兼容旧 Runtime 或异常的晚注入时序，可以进行一次有上限的异步等待：
+Runtime v1.5.22 及以上的 PACKAGED_H5 会在 document-start 阶段完成配置注入，因此优先使用上述同步读取。若需要容忍异常的晚注入时序，可以进行一次有上限的异步等待：
 
 ```ts
 import { waitForDrivingExpressionsConfig } from '@ziztechnology/dial-library';

package/dist/index.d.mts

@@ -4,10 +4,6 @@ type BatteryStatus = 'CHARGING' | 'DISCHARGING' | 'FULL' | 'NOT_CHARGING' | 'UNK
 type BatteryPlugged = 'AC' | 'USB' | 'WIRELESS' | 'DOCK' | 'NONE';
 type BatteryHealth = 'GOOD' | 'OVERHEAT' | 'DEAD' | 'OVER_VOLTAGE' | 'UNSPECIFIED_FAILURE' | 'COLD' | 'UNKNOWN';
 declare const BATTERY_HEALTH_LABELS: Record<BatteryHealth, string>;
-type CarRunningStatus = 'STOPPED' | 'STEADY_DRIVING' | 'ACCELERATION' | 'RAPID_ACCELERATION' | 'BRAKING' | 'SUDDEN_BRAKING' | 'LEFT_TURN' | 'RIGHT_TURN';
-declare const CAR_RUNNING_LABELS: Record<CarRunningStatus, string>;
-declare const CAR_RUNNING_STATUSES: readonly ["STOPPED", "STEADY_DRIVING", "ACCELERATION", "RAPID_ACCELERATION", "BRAKING", "SUDDEN_BRAKING", "LEFT_TURN", "RIGHT_TURN"];
-declare const CAR_RUNNING_STATUS_PRIORITY: Readonly<Record<CarRunningStatus, number>>;
 //#endregion
 //#region src/sensor/unified_info.d.ts
 interface Vector3Value {
@@ -65,7 +61,13 @@ interface UnifiedSensorInfoPayload {
 }
 declare const unifiedSensorInfo: () => Promise<UnifiedSensorInfoPayload>;
 //#endregion
-//#region src/sensor/check_status.d.ts
+//#region src/driving_expression/constants.d.ts
+type CarRunningStatus = 'STOPPED' | 'STEADY_DRIVING' | 'ACCELERATION' | 'RAPID_ACCELERATION' | 'BRAKING' | 'SUDDEN_BRAKING' | 'LEFT_TURN' | 'RIGHT_TURN';
+declare const CAR_RUNNING_LABELS: Record<CarRunningStatus, string>;
+declare const CAR_RUNNING_STATUSES: readonly ["STOPPED", "STEADY_DRIVING", "ACCELERATION", "RAPID_ACCELERATION", "BRAKING", "SUDDEN_BRAKING", "LEFT_TURN", "RIGHT_TURN"];
+declare const CAR_RUNNING_STATUS_PRIORITY: Readonly<Record<CarRunningStatus, number>>;
+//#endregion
+//#region src/driving_expression/check_status.d.ts
 interface DrivingStatusTuning {
   version: string;
   maxSampleAgeMs: number;
@@ -155,7 +157,7 @@ declare const resolveDrivingStatusTuning: (overrides?: DrivingStatusTuningOverri
 declare const extractDrivingSnapshotMetrics: (info: UnifiedSensorInfoPayload, tuning?: Pick<DrivingStatusTuning, "maxSampleAgeMs" | "vehicleRightMinimumNorm">, correction?: DrivingMetricsCorrection) => DrivingSnapshotMetrics | null;
 declare const buildVehicleFrame: (gravity: Vector3Value, rightMinimumNorm?: number) => DrivingVehicleFrame | null;
 //#endregion
-//#region src/sensor/driving_expressions.d.ts
+//#region src/driving_expression/driving_expressions.d.ts
 interface MediaLibraryRef {
   mediaAssetId?: number;
 }
@@ -228,7 +230,7 @@ interface WaitForDrivingExpressionsConfigOptions {
 declare const parseDrivingExpressionsConfig: (raw: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig;
 declare const tryParseDrivingExpressionsConfig: (raw: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig | null;
 /**
- * Reads Runtime's typed injection first, then the legacy face-config value.
+ * Reads Runtime's typed driving-expressions injection.
  * It never installs official fallbacks implicitly.
  */
 declare const readDrivingExpressionsConfig: (raw?: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig | null;
@@ -243,7 +245,7 @@ declare const resolveDrivingExpression: (config: DrivingExpressionsConfigInput,
 declare const resolveDrivingExpressionStrict: (config: DrivingExpressionsConfigInput, status: CarRunningStatus, fallbacks?: Partial<Readonly<Record<CarRunningStatus, StructuredDrivingExpressionMedia>>>) => DrivingExpressionMedia;
 declare const isPublicDrivingMediaUrl: (value: string) => boolean;
 //#endregion
-//#region src/sensor/driving_status_controller.d.ts
+//#region src/driving_expression/driving_status_controller.d.ts
 type DrivingStatusChangeReason = 'candidate_confirmed' | 'unavailable_fallback';
 interface DrivingStatusEvent {
   type: 'status_changed';
@@ -386,7 +388,7 @@ interface DrivingStatusController {
 }
 declare const createDrivingStatusController: (options?: DrivingStatusControllerOptions) => DrivingStatusController;
 //#endregion
-//#region src/sensor/driving_expression_player.d.ts
+//#region src/driving_expression/driving_expression_player.d.ts
 type DrivingExpressionPlayerErrorCategory = 'invalid_config' | 'network' | 'timeout' | 'decode' | 'unsupported';
 type DrivingExpressionPlayerDiagnosticEvent = {
   type: 'media_ready';
@@ -413,6 +415,10 @@ interface DrivingExpressionPlayerSnapshot {
 }
 interface DrivingExpressionPlayerOptions {
   config: DrivingExpressionsConfigInput;
+  /**
+   * Emoji and image entries are renderable fallbacks. Other structured kinds
+   * remain accepted for source compatibility but are reported as invalid_config.
+   */
   fallbacks?: Partial<Readonly<Record<CarRunningStatus, StructuredDrivingExpressionMedia>>>;
   loadTimeoutMs?: number;
   retryBackoffMs?: number;