@ziztechnology/dial-library 0.0.1 → 0.0.2

package/README.md

@@ -1 +1,184 @@
 # Toooony 表盘用户 SDK
+
+> [!NOTE]
+> 最低支持 Runtime 版本 `v1.5.20`。行车状态传感器 Bridge 仅供经过审核的 `PACKAGED_H5` 使用；第三方应依赖本 SDK API，不要把 Runtime 的 `window` 内部方法当作稳定接口。
+
+## 安装
+
+```bash
+npm i @ziztechnology/dial-library
+```
+
+## 行车状态母版快速接入
+
+```ts
+import {
+  OFFICIAL_DRIVING_EXPRESSION_FALLBACKS,
+  createDrivingExpressionPlayer,
+  createDrivingStatusController,
+  readDrivingExpressionsConfig,
+} from '@ziztechnology/dial-library';
+
+const config = readDrivingExpressionsConfig();
+if (!config) throw new Error('Unsupported or invalid drivingExpressions config');
+
+const player = createDrivingExpressionPlayer(document.querySelector('#expression')!, {
+  config,
+  // 官方母版必须显式传入；第三方不传时不会自动获得官方 Emoji。
+  fallbacks: OFFICIAL_DRIVING_EXPRESSION_FALLBACKS,
+});
+const controller = createDrivingStatusController();
+
+await player.show('STOPPED');
+const unsubscribe = controller.subscribe((event) => {
+  if (event.type === 'status_changed') void player.show(event.status);
+});
+controller.start();
+
+// 也可以由母版显式控制；默认会自动接入 Runtime pause/resume 和页面生命周期。
+const pause = () => {
+  controller.stop();
+  player.pause();
+};
+const resume = () => {
+  player.resume();
+  controller.start();
+};
+
+// 页面销毁时：
+const destroy = () => {
+  unsubscribe();
+  controller.destroy();
+  player.destroy();
+};
+```
+
+重复调用 `start()`、`stop()`、`destroy()`、`pause()` 或 `resume()`是安全的。启动时 UI 应先显示 `STOPPED`，只有已提交状态才触发媒体切换，候选状态不会触发 UI。
+
+## 稳定的八状态协议
+
+`CarRunningStatus` 的 wire 值和 `CAR_RUNNING_STATUSES` 固定为：
+
+```text
+STOPPED
+STEADY_DRIVING
+ACCELERATION
+RAPID_ACCELERATION
+BRAKING
+SUDDEN_BRAKING
+LEFT_TURN
+RIGHT_TURN
+```
+
+`OFFICIAL_DRIVING_EXPRESSION_FALLBACKS` 提供官方母版的固定默认值：`😐 😊 😄 😲 😣 😱 🤨 🤨`。SDK 不会自动使用这张表；第三方未传 `fallbacks` 时，素材缺失或加载失败只会上报错误。
+
+## 配置解析
+
+`drivingExpressions` 使用 schema v1，八个状态必须完整且不能包含未知状态。`parseDrivingExpressionsConfig()` 同时接受 JSON 对象和 JSON 字符串，并返回完整、结构化的配置：
+
+```ts
+import { parseDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const config = parseDrivingExpressionsConfig(customField.value);
+```
+
+支持的素材为：
+
+```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 };
+```
+
+解析器拒绝缺项、轮播字段、非法 kind/字段组合、非单个可见 grapheme 的 Emoji，以及 `http:`、`data:`、`blob:`、localhost、内网/保留 IP、内部单标签 host、带 COS/GCS/OSS 等常见临时签名参数的非长期公网 HTTPS URL。普通公网 HTTPS 与无签名业务 query 仍可使用。后端仍必须按 `mediaAssetId + userID` 重建可信 URL；SDK 静态校验不能替代服务端所有权、DNS 解析和 host allowlist 校验。
+
+`readDrivingExpressionsConfig()` 优先读取 Runtime 注入的 `window.__TOOOONY_DRIVING_EXPRESSIONS__`，再兼容旧 `__TOOOONY_FACE_CONFIG__` 路径；非法或不支持的配置返回 `null`，不会隐式填充官方默认值。
+
+首版 SDK 接受过裸图片 URL。为兼容旧表盘，`resolveDrivingExpression()` 及 `DrivingExpressionsConfig` 仍保留旧形状；只有显式设置 `{ allowLegacyImageUrls: true }` 时，schema 解析器才会把裸 HTTPS URL 归一化为 `kind: 'image'`。
+
+## 纯函数分类
+
+```ts
+import { classifyDrivingSnapshot, unifiedSensorInfo } from '@ziztechnology/dial-library';
+
+const status = classifyDrivingSnapshot(await unifiedSensorInfo());
+```
+
+`classifyDrivingSnapshot(info, tuning?)` 是无状态纯函数。原 API `checkRunningStatus()` 保留为同一函数的兼容别名。数据不可用、非法或超过 1 秒未更新时返回 `null`。
+
+固定安装方向：
+
+```text
++X = 车身右侧
++Y = 上方
+-Z = 车辆前进方向
+```
+
+即 `longitudinal = -linearAcceleration.z`、`lateral = linearAcceleration.x`、`yaw = gyroscope.y`。左转为正 yaw 或负 lateral，右转符号相反。
+
+默认阈值集中在 `DEFAULT_DRIVING_STATUS_TUNING`，版本为 `driving-status-v1`。仅靠惯性传感器无法严格区分静止和理想匀速直线运动；v1 使用 `motionIntensity` 和陀螺仪扰动近似判断，必须通过固定安装真机路测继续调参。
+
+## 状态控制器
+
+```ts
+const controller = createDrivingStatusController({
+  pollIntervalMs: 200,
+  unavailableFallbackMs: 3_000,
+  initialStatus: 'STOPPED',
+  tuning: { turnYawThreshold: 0.32 },
+  onDiagnostic(event) {
+    // 诊断事件不包含完整媒体 URL或逐帧传感器数据。
+  },
+});
+```
+
+控制器统一实现：
+
+- 默认 200ms 轮询，读取期间不会发起重叠请求；`stop()` 会通过 `AbortSignal` 取消/忽略未完成读取。
+- 普通动作短窗口平滑，急动作检查未平滑峰值。
+- 急刹车 > 急加速 > 转弯 > 刹车 > 加速 > 静止/匀速的抢占优先级。
+- 急动作 1 样本、转弯/普通动作 2 样本、匀速 3 样本、静止 5 样本的连续确认。
+- 动作退出阈值为入口阈值的 `0.75`，并对静止/匀速使用反向滞回区间。
+- 每个已提交状态的最短展示时间；更高优先级候选可抢占，锁期间继续采样。
+- 单次/短暂不可用保持最后状态；连续不可用达到 3 秒强制提交 `STOPPED`；恢复后重新确认候选。
+
+`getSnapshot()` 返回生命周期、已提交状态、候选计数、不可用起点和 tuning 版本。`subscribe()` 只发送稳定的 `status_changed` 事件；更细的 `sample_available`、`candidate_changed`、`status_held_by_min_duration`、`fallback_to_stopped` 等通过可选 `onDiagnostic` 获取。
+
+测试和离线回放可注入 `sensorProvider` 与 `clock`。provider 可接收 `AbortSignal`：
+
+```ts
+const controller = createDrivingStatusController({
+  sensorProvider: (signal) => replay.next(signal),
+  clock: fakeClock,
+});
+```
+
+## 媒体播放器
+
+`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 提示，不同时解码八个视频。
+
+控制器和播放器默认共享 `window.__watchFaceRuntimePause` / `window.__watchFaceRuntimeResume`、visibility/page 事件及设备传感器 release/resume 事件。SDK 会链接并在最后一个订阅者销毁时恢复页面原有 hook，避免两者相互覆盖。播放器可通过 `managePageLifecycle: false` 显式关闭自动生命周期管理。
+
+可使用 `onDiagnostic` 监听 `media_ready`、`media_load_failed` 和 `media_fallback_applied`。诊断会截断错误消息并移除 URL query，避免记录临时 token。
+
+## 开发验证
+
+```bash
+pnpm test
+pnpm exec tsc --noEmit
+pnpm run fmt:check
+```
+
+测试使用 fake clock、fake sensor provider 和轻量 DOM，覆盖八状态边界、优先级、候选确认、滞回、最短展示、2.9/3 秒不可用边界、生命周期幂等、所有配置 kind、官方/第三方 fallback 差异，以及图片/视频/Live Photo/TGS 播放行为。

package/dist/index.d.mts

@@ -1,5 +1,15 @@
-//#region src/sensor/unified_info.d.ts
+//#region src/sensor/constants.d.ts
 type UnifiedSensorUnavailableReason = 'SENSOR_MISSING' | 'NO_SAMPLE' | 'PLATFORM_UNAVAILABLE' | 'PERMISSION_DENIED' | 'NOT_CONNECTED';
+type BatteryStatus = 'CHARGING' | 'DISCHARGING' | 'FULL' | 'NOT_CHARGING' | 'UNKNOWN';
+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 {
   x: number;
   y: number;
@@ -14,9 +24,6 @@ interface BatteryCapacityValue {
   levelPercent: number | null;
   chargeCounterUah: number | null;
 }
-type BatteryStatus = 'CHARGING' | 'DISCHARGING' | 'FULL' | 'NOT_CHARGING' | 'UNKNOWN';
-type BatteryPlugged = 'AC' | 'USB' | 'WIRELESS' | 'DOCK' | 'NONE';
-type BatteryHealth = 'GOOD' | 'OVERHEAT' | 'DEAD' | 'OVER_VOLTAGE' | 'UNSPECIFIED_FAILURE' | 'COLD' | 'UNKNOWN';
 interface BatteryStateValue {
   present: boolean;
   charging: boolean;
@@ -45,6 +52,7 @@ type UnifiedSensorMetric<T, TSource extends string, TUnit extends string | null,
 interface UnifiedSensorInfoPayload {
   capturedAtMs: number;
   gyroscope: UnifiedSensorMetric<Vector3Value, 'TYPE_GYROSCOPE', 'rad/s', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
+  accelerometer: UnifiedSensorMetric<Vector3Value, 'TYPE_ACCELEROMETER', 'm/s²', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
   batteryCapacity: UnifiedSensorMetric<BatteryCapacityValue, 'BatteryManager', null, null, number>;
   wifiSsid: UnifiedSensorMetric<string, 'NetworkCapabilities.WifiInfo', null, 'PERMISSION_DENIED' | 'NOT_CONNECTED' | 'PLATFORM_UNAVAILABLE'>;
   battery: UnifiedSensorMetric<BatteryStateValue, 'ACTION_BATTERY_CHANGED', null, 'PLATFORM_UNAVAILABLE'>;
@@ -52,8 +60,254 @@ interface UnifiedSensorInfoPayload {
   gravity: UnifiedSensorMetric<Vector3Value, 'TYPE_GRAVITY', 'm/s²', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
   orientation: UnifiedSensorMetric<OrientationValue, 'TYPE_ROTATION_VECTOR' | 'ACCELEROMETER_MAGNETIC_FIELD', 'degree', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
   magneticField: UnifiedSensorMetric<Vector3Value, 'TYPE_MAGNETIC_FIELD', 'µT', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
-  linearAcceleration: UnifiedSensorMetric<Vector3Value, 'TYPE_LINEAR_ACCELERATION', 'm/s²', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
+  linearAcceleration: UnifiedSensorMetric<Vector3Value, 'TYPE_LINEAR_ACCELERATION' | 'DERIVED_ACCELEROMETER_GRAVITY', 'm/s²', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
+  motionIntensity?: UnifiedSensorMetric<number, 'DERIVED_ACCELEROMETER_MAGNITUDE_STDDEV', 'm/s²', 'SENSOR_MISSING' | 'NO_SAMPLE', number | null>;
 }
 declare const unifiedSensorInfo: () => Promise<UnifiedSensorInfoPayload>;
 //#endregion
-export { AvailableSensorMetric, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, OrientationValue, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, unifiedSensorInfo };
+//#region src/sensor/check_status.d.ts
+interface DrivingStatusTuning {
+  version: string;
+  maxSampleAgeMs: number;
+  rapidLongitudinalThreshold: number;
+  longitudinalThreshold: number;
+  turnYawThreshold: number;
+  turnLateralThreshold: number;
+  stoppedMotionThreshold: number;
+  stoppedGyroThreshold: number;
+  hysteresisRatio: number;
+  smoothingWindowSize: number;
+  confirmationSamples: Readonly<Record<CarRunningStatus, number>>;
+  minimumDisplayMs: Readonly<Record<CarRunningStatus, number>>;
+}
+type DrivingStatusTuningOverrides = Partial<Omit<DrivingStatusTuning, 'confirmationSamples' | 'minimumDisplayMs'>> & {
+  confirmationSamples?: Partial<Record<CarRunningStatus, number>>;
+  minimumDisplayMs?: Partial<Record<CarRunningStatus, number>>;
+};
+declare const DEFAULT_DRIVING_STATUS_TUNING: Readonly<DrivingStatusTuning>;
+interface DrivingSnapshotMetrics {
+  capturedAtMs: number;
+  longitudinal: number;
+  lateral: number;
+  yaw: number;
+  motionIntensity: number;
+  gyroMagnitude: number;
+}
+declare const classifyDrivingSnapshot: (info: UnifiedSensorInfoPayload, tuningOverrides?: DrivingStatusTuningOverrides) => CarRunningStatus | null;
+declare const checkRunningStatus: (info: UnifiedSensorInfoPayload, tuningOverrides?: DrivingStatusTuningOverrides) => CarRunningStatus | null;
+declare const resolveDrivingStatusTuning: (overrides?: DrivingStatusTuningOverrides) => DrivingStatusTuning;
+declare const extractDrivingSnapshotMetrics: (info: UnifiedSensorInfoPayload, tuning?: Pick<DrivingStatusTuning, "maxSampleAgeMs">) => DrivingSnapshotMetrics | null;
+declare const classifyDrivingMetrics: (metrics: DrivingSnapshotMetrics, tuning?: DrivingStatusTuning) => CarRunningStatus;
+//#endregion
+//#region src/sensor/driving_expressions.d.ts
+interface MediaLibraryRef {
+  mediaAssetId?: number;
+}
+interface EmojiDrivingExpressionMedia {
+  kind: 'emoji';
+  text: string;
+}
+interface ImageDrivingExpressionMedia extends MediaLibraryRef {
+  kind: 'image';
+  url: string;
+  mimeType?: string;
+}
+interface VideoDrivingExpressionMedia extends MediaLibraryRef {
+  kind: 'video';
+  url: string;
+  coverUrl?: string;
+  mimeType?: string;
+}
+interface LivePhotoDrivingExpressionMedia extends MediaLibraryRef {
+  kind: 'live_photo';
+  coverUrl: string;
+  motionUrl: string;
+}
+interface TgsDrivingExpressionMedia extends MediaLibraryRef {
+  kind: 'tgs';
+  url: string;
+  coverUrl?: string;
+}
+type StructuredDrivingExpressionMedia = EmojiDrivingExpressionMedia | ImageDrivingExpressionMedia | VideoDrivingExpressionMedia | LivePhotoDrivingExpressionMedia | TgsDrivingExpressionMedia;
+type DrivingExpressionMedia = string | StructuredDrivingExpressionMedia;
+/**
+ * Compatibility shape exported by the first SDK release. New persisted
+ * configurations should be parsed as CompleteDrivingExpressionsConfig.
+ */
+interface DrivingExpressionsConfig {
+  schemaVersion: 1;
+  states: Partial<Record<CarRunningStatus, DrivingExpressionMedia>> & Pick<Record<CarRunningStatus, DrivingExpressionMedia>, 'STOPPED' | 'STEADY_DRIVING'>;
+}
+interface CompleteDrivingExpressionsConfig {
+  schemaVersion: 1;
+  states: Record<CarRunningStatus, StructuredDrivingExpressionMedia>;
+}
+type DrivingExpressionsConfigInput = DrivingExpressionsConfig | CompleteDrivingExpressionsConfig;
+declare const OFFICIAL_DRIVING_EXPRESSION_FALLBACKS: Readonly<Record<CarRunningStatus, Readonly<EmojiDrivingExpressionMedia>>>;
+declare const OFFICIAL_DRIVING_EXPRESSIONS_CONFIG: Readonly<CompleteDrivingExpressionsConfig>;
+type DrivingExpressionsConfigErrorCode = 'DRIVING_EXPRESSIONS_INVALID_SCHEMA' | 'DRIVING_EXPRESSIONS_INCOMPLETE' | 'DRIVING_EXPRESSION_INVALID_MEDIA' | 'MEDIA_URL_NOT_PUBLIC_HTTPS';
+declare class DrivingExpressionsConfigError extends Error {
+  readonly code: DrivingExpressionsConfigErrorCode;
+  readonly state?: CarRunningStatus;
+  constructor(code: DrivingExpressionsConfigErrorCode, message: string, state?: CarRunningStatus);
+}
+declare class DrivingExpressionResolutionError extends Error {
+  readonly status: CarRunningStatus;
+  constructor(status: CarRunningStatus);
+}
+interface ParseDrivingExpressionsOptions {
+  /** Accept the v0 bare HTTPS image URL and normalize it to kind=image. */
+  allowLegacyImageUrls?: boolean;
+}
+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.
+ * It never installs official fallbacks implicitly.
+ */
+declare const readDrivingExpressionsConfig: (raw?: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig | null;
+/** Original resolver behavior: missing legacy slots fall back to STEADY_DRIVING. */
+declare const resolveDrivingExpression: (config: DrivingExpressionsConfigInput, status: CarRunningStatus) => DrivingExpressionMedia;
+/** Strict resolver used by the player; official fallbacks are opt-in. */
+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
+type DrivingStatusChangeReason = 'candidate_confirmed' | 'unavailable_fallback';
+interface DrivingStatusEvent {
+  type: 'status_changed';
+  status: CarRunningStatus;
+  previousStatus: CarRunningStatus;
+  reason: DrivingStatusChangeReason;
+  atMs: number;
+}
+type DrivingStatusDiagnosticEvent = {
+  type: 'sample_available';
+  atMs: number;
+  capturedAtMs: number;
+  tuningVersion: string;
+} | {
+  type: 'sample_unavailable';
+  atMs: number;
+  unavailableForMs: number;
+  category: 'provider_error' | 'invalid_or_stale_snapshot';
+  tuningVersion: string;
+} | {
+  type: 'candidate_changed';
+  atMs: number;
+  candidate: CarRunningStatus | null;
+  previousCandidate: CarRunningStatus | null;
+  tuningVersion: string;
+} | {
+  type: 'status_committed';
+  atMs: number;
+  status: CarRunningStatus;
+  previousStatus: CarRunningStatus;
+  reason: DrivingStatusChangeReason;
+  tuningVersion: string;
+} | {
+  type: 'status_held_by_min_duration';
+  atMs: number;
+  status: CarRunningStatus;
+  candidate: CarRunningStatus;
+  remainingMs: number;
+  tuningVersion: string;
+} | {
+  type: 'fallback_to_stopped';
+  atMs: number;
+  unavailableForMs: number;
+  tuningVersion: string;
+};
+interface DrivingControllerSnapshot {
+  lifecycle: 'stopped' | 'running' | 'destroyed';
+  status: CarRunningStatus;
+  candidate: CarRunningStatus | null;
+  candidateConfirmationCount: number;
+  statusCommittedAtMs: number;
+  lastAvailableAtMs: number | null;
+  unavailableSinceMs: number | null;
+  tuningVersion: string;
+}
+interface DrivingStatusClock {
+  now(): number;
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+type DrivingSensorProvider = (signal?: AbortSignal) => UnifiedSensorInfoPayload | Promise<UnifiedSensorInfoPayload>;
+interface DrivingStatusControllerOptions {
+  sensorProvider?: DrivingSensorProvider;
+  pollIntervalMs?: number;
+  unavailableFallbackMs?: number;
+  tuning?: DrivingStatusTuningOverrides;
+  initialStatus?: CarRunningStatus;
+  clock?: DrivingStatusClock;
+  onDiagnostic?: (event: DrivingStatusDiagnosticEvent) => void;
+  /** Pause on Runtime/visibility/page hooks and resume only if start() is still requested. */
+  managePageLifecycle?: boolean;
+}
+interface DrivingStatusController {
+  start(): void;
+  stop(): void;
+  destroy(): void;
+  getSnapshot(): DrivingControllerSnapshot;
+  subscribe(listener: (event: DrivingStatusEvent) => void): () => void;
+}
+declare const createDrivingStatusController: (options?: DrivingStatusControllerOptions) => DrivingStatusController;
+//#endregion
+//#region src/sensor/driving_expression_player.d.ts
+type DrivingExpressionPlayerErrorCategory = 'invalid_config' | 'network' | 'timeout' | 'decode' | 'unsupported';
+type DrivingExpressionPlayerDiagnosticEvent = {
+  type: 'media_ready';
+  status: CarRunningStatus;
+  kind: StructuredDrivingExpressionMedia['kind'];
+  elapsedMs: number;
+} | {
+  type: 'media_load_failed';
+  status: CarRunningStatus;
+  kind: StructuredDrivingExpressionMedia['kind'] | 'unknown';
+  category: DrivingExpressionPlayerErrorCategory;
+  message: string;
+} | {
+  type: 'media_fallback_applied';
+  status: CarRunningStatus;
+  kind: StructuredDrivingExpressionMedia['kind'];
+};
+interface DrivingExpressionPlayerSnapshot {
+  lifecycle: 'active' | 'paused' | 'destroyed';
+  status: CarRunningStatus | null;
+  phase: 'idle' | 'loading' | 'ready' | 'fallback' | 'error';
+  mediaKind: StructuredDrivingExpressionMedia['kind'] | null;
+  errorCategory: DrivingExpressionPlayerErrorCategory | null;
+}
+interface DrivingTgsAnimationHandle {
+  destroy(): void;
+  pause?(): void;
+  play?(): void;
+  restart?(): void;
+}
+type DrivingTgsRenderer = (container: HTMLElement, animationData: Record<string, unknown>, signal: AbortSignal) => DrivingTgsAnimationHandle | Promise<DrivingTgsAnimationHandle>;
+interface DrivingExpressionPlayerOptions {
+  config: DrivingExpressionsConfigInput;
+  fallbacks?: Partial<Readonly<Record<CarRunningStatus, StructuredDrivingExpressionMedia>>>;
+  loadTimeoutMs?: number;
+  retryBackoffMs?: number;
+  fit?: 'contain' | 'cover';
+  tgsRenderer?: DrivingTgsRenderer;
+  fetch?: typeof globalThis.fetch;
+  onDiagnostic?: (event: DrivingExpressionPlayerDiagnosticEvent) => void;
+  maxTgsCompressedBytes?: number;
+  maxTgsJsonBytes?: number;
+  maxTgsLayers?: number;
+  /** Pause/cancel work on Runtime and page lifecycle hooks. Defaults to true. */
+  managePageLifecycle?: boolean;
+}
+interface DrivingExpressionPlayer {
+  show(status: CarRunningStatus): Promise<void>;
+  pause(): void;
+  resume(): void;
+  destroy(): void;
+  getSnapshot(): DrivingExpressionPlayerSnapshot;
+}
+declare const createDrivingExpressionPlayer: (container: HTMLElement, options: DrivingExpressionPlayerOptions) => DrivingExpressionPlayer;
+//#endregion
+export { AvailableSensorMetric, BATTERY_HEALTH_LABELS, BatteryCapacityValue, BatteryHealth, BatteryPlugged, BatteryStateValue, BatteryStatus, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, CarRunningStatus, CompleteDrivingExpressionsConfig, DEFAULT_DRIVING_STATUS_TUNING, DrivingControllerSnapshot, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingSensorProvider, DrivingSnapshotMetrics, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingTgsAnimationHandle, DrivingTgsRenderer, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, checkRunningStatus, classifyDrivingMetrics, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo };