@ziztechnology/dial-library 0.0.1 → 0.0.3

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,257 @@ 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;
+  motionWindowMs: number;
+  motionMinimumSamples: number;
+  drivingMotionThreshold: 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 };