@ziztechnology/dial-library 0.0.4 → 0.0.5

package/README.md

@@ -399,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. */
@@ -305,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, 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();
@@ -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.4",
+  "version": "0.0.5",
   "private": false,
   "description": "Tooony 表盘工具函数、方法",
   "files": [
@@ -11,6 +11,13 @@
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "test": "pnpm run build && node --test test/*.test.mjs"
+  },
   "dependencies": {
     "fflate": "^0.8.2",
     "lottie-web": "^5.13.0"
@@ -19,12 +26,5 @@
     "oxfmt": "^0.58.0",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "fmt": "oxfmt",
-    "fmt:check": "oxfmt --check",
-    "test": "pnpm run build && node --test test/*.test.mjs"
   }
-}
+}