@ziztechnology/dial-library 0.0.3 → 0.0.5

package/README.md

@@ -311,6 +311,8 @@ const destroy = () => {
 
 播放器同一时间只保留一个活动动态素材。它会复用视频元素，并在状态离开时停止播放；页面暂停或隐藏时，播放器与控制器都会自动暂停。
 
+TGS 使用 SDK 内置的 SVG light 播放器，并且只在首次显示 TGS 素材时动态加载。表盘项目不需要安装、导入或配置 `lottie-web`，也不需要为构建工具添加 Lottie alias。
+
 ## 行车状态的回退
 
 行车状态有两类彼此独立的回退：传感器不可用时的**状态回退**，以及表情素材失败时的**媒体回退**。
@@ -397,6 +399,21 @@ if (!config) {
 }
 ```
 
+正常的 PACKAGED_H5 Runtime 会在 document-start 阶段完成配置注入，因此优先使用上述同步读取。若表盘还需兼容旧 Runtime 或异常的晚注入时序，可以进行一次有上限的异步等待：
+
+```ts
+import { waitForDrivingExpressionsConfig } from '@ziztechnology/dial-library';
+
+const abortController = new AbortController();
+const config = await waitForDrivingExpressionsConfig({
+  timeoutMs: 3_000,
+  pollIntervalMs: 100,
+  signal: abortController.signal,
+});
+```
+
+该函数会立即读取一次，之后使用单个定时器重试。首次读到完整合法的配置时返回；超时返回 `null`；取消时以 `AbortError` 结束。它不会隐式使用官方 Emoji，超时后的界面和回退仍由表盘决定。页面卸载时应调用 `abortController.abort()`。
+
 schema v1 要求 `states` 恰好包含全部八种状态。支持的单个状态素材为：
 
 ```ts

package/dist/index.d.mts

@@ -162,6 +162,16 @@ interface ParseDrivingExpressionsOptions {
   /** Accept the v0 bare HTTPS image URL and normalize it to kind=image. */
   allowLegacyImageUrls?: boolean;
 }
+interface WaitForDrivingExpressionsConfigOptions {
+  /** Maximum time to wait for Runtime injection. Defaults to 3000ms. */
+  timeoutMs?: number;
+  /** Delay between reads while waiting. Defaults to 100ms. */
+  pollIntervalMs?: number;
+  /** Cancels the pending wait and rejects with AbortError. */
+  signal?: AbortSignal;
+  /** Parsing compatibility options applied to every read. */
+  parseOptions?: ParseDrivingExpressionsOptions;
+}
 declare const parseDrivingExpressionsConfig: (raw: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig;
 declare const tryParseDrivingExpressionsConfig: (raw: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig | null;
 /**
@@ -169,6 +179,11 @@ declare const tryParseDrivingExpressionsConfig: (raw: unknown, options?: ParseDr
  * It never installs official fallbacks implicitly.
  */
 declare const readDrivingExpressionsConfig: (raw?: unknown, options?: ParseDrivingExpressionsOptions) => CompleteDrivingExpressionsConfig | null;
+/**
+ * Waits for a valid Runtime-injected configuration using bounded polling.
+ * It never installs official fallbacks implicitly.
+ */
+declare const waitForDrivingExpressionsConfig: (options?: WaitForDrivingExpressionsConfigOptions) => Promise<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. */
@@ -282,20 +297,12 @@ interface DrivingExpressionPlayerSnapshot {
   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;
@@ -313,4 +320,4 @@ interface DrivingExpressionPlayer {
 }
 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 };
+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, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, checkRunningStatus, classifyDrivingMetrics, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };

package/dist/index.mjs

@@ -256,6 +256,63 @@ const readDrivingExpressionsConfig = (raw, options) => {
 	const source = raw === void 0 ? readRuntimeDrivingExpressionsValue() : raw;
 	return source === void 0 ? null : tryParseDrivingExpressionsConfig(source, options);
 };
+/**
+* Waits for a valid Runtime-injected configuration using bounded polling.
+* It never installs official fallbacks implicitly.
+*/
+const waitForDrivingExpressionsConfig = (options = {}) => {
+	const timeoutMs = requireNonNegativeFinite("timeoutMs", options.timeoutMs ?? 3e3);
+	const pollIntervalMs = requirePositiveFinite$1("pollIntervalMs", options.pollIntervalMs ?? 100);
+	const { signal } = options;
+	return new Promise((resolve, reject) => {
+		const deadlineMs = Date.now() + timeoutMs;
+		let timer;
+		let settled = false;
+		const cleanup = () => {
+			if (timer !== void 0) {
+				globalThis.clearTimeout(timer);
+				timer = void 0;
+			}
+			signal?.removeEventListener("abort", handleAbort);
+		};
+		const finish = (config) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(config);
+		};
+		const fail = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		};
+		const handleAbort = () => {
+			fail(createAbortError$1());
+		};
+		const read = () => readDrivingExpressionsConfig(void 0, options.parseOptions);
+		const poll = () => {
+			if (settled) return;
+			if (signal?.aborted) {
+				handleAbort();
+				return;
+			}
+			const config = read();
+			if (config !== null) {
+				finish(config);
+				return;
+			}
+			const remainingMs = deadlineMs - Date.now();
+			if (remainingMs <= 0) {
+				finish(null);
+				return;
+			}
+			timer = globalThis.setTimeout(poll, Math.min(pollIntervalMs, remainingMs));
+		};
+		signal?.addEventListener("abort", handleAbort, { once: true });
+		poll();
+	});
+};
 /** Original resolver behavior: missing legacy slots fall back to STEADY_DRIVING. */
 const resolveDrivingExpression = (config, status) => config.states[status] ?? config.states.STEADY_DRIVING;
 /** Strict resolver used by the player; official fallbacks are opt-in. */
@@ -531,6 +588,20 @@ const compact = (value) => {
 	return value;
 };
 const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const requireNonNegativeFinite = (name, value) => {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${name} must be a non-negative finite number`);
+	return value;
+};
+const requirePositiveFinite$1 = (name, value) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a positive finite number`);
+	return value;
+};
+const createAbortError$1 = () => {
+	if (typeof DOMException === "function") return new DOMException("The operation was aborted", "AbortError");
+	const error = /* @__PURE__ */ new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+};
 //#endregion
 //#region src/sensor/page_lifecycle.ts
 const subscribers = /* @__PURE__ */ new Set();
@@ -1071,7 +1142,7 @@ var DefaultDrivingExpressionPlayer = class {
 		this.loadTimeoutMs = positiveFinite("loadTimeoutMs", options.loadTimeoutMs ?? 5e3);
 		this.retryBackoffMs = positiveFinite("retryBackoffMs", options.retryBackoffMs ?? 15e3);
 		this.fit = options.fit ?? "contain";
-		this.tgsRenderer = options.tgsRenderer ?? defaultTgsRenderer;
+		this.tgsRenderer = defaultTgsRenderer;
 		this.fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
 		this.onDiagnostic = options.onDiagnostic;
 		this.maxTgsCompressedBytes = positiveFinite("maxTgsCompressedBytes", options.maxTgsCompressedBytes ?? 2 * 1024 * 1024);
@@ -1604,7 +1675,7 @@ const withTimeout = (promise, timeoutMs, signal) => new Promise((resolve, reject
 });
 const defaultTgsRenderer = async (container, animationData, signal) => {
 	if (signal.aborted) throw createAbortError();
-	const module = await import("lottie-web");
+	const module = await import("lottie-web/build/player/lottie_light.js");
 	if (signal.aborted) throw createAbortError();
 	const animation = module.default.loadAnimation({
 		animationData,
@@ -1731,4 +1802,4 @@ const safeDestroy = (handle) => {
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 //#endregion
-export { BATTERY_HEALTH_LABELS, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, DEFAULT_DRIVING_STATUS_TUNING, DrivingExpressionResolutionError, DrivingExpressionsConfigError, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, checkRunningStatus, classifyDrivingMetrics, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo };
+export { BATTERY_HEALTH_LABELS, CAR_RUNNING_LABELS, CAR_RUNNING_STATUSES, CAR_RUNNING_STATUS_PRIORITY, DEFAULT_DRIVING_STATUS_TUNING, DrivingExpressionResolutionError, DrivingExpressionsConfigError, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, checkRunningStatus, classifyDrivingMetrics, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziztechnology/dial-library",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "private": false,
   "description": "Tooony 表盘工具函数、方法",
   "files": [