@ziztechnology/dial-library 0.0.11 → 0.0.12

package/README.md

@@ -229,6 +229,8 @@ controller.destroy();
 
 普通加速和刹车要求 0.8 秒内至少 4/5 的样本方向一致；急加速和急刹要求峰值、0.6 秒持续均值及方向一致性同时成立，并拒绝垂直能量占主导或短时间反号的颠簸。转向由偏航持续值或累计转角触发并锁存到回正结束。最终优先级为：急加减速、已锁存转向、普通加减速、基础状态。
 
+缓慢转向还要求偏航旋转占陀螺仪能量的主要部分，或存在足够的横向加速度；垂直颠簸占主导且缺少偏航佐证时不会创建转向事件。重力样本短时缺失时，控制器会在 `maxSampleAgeMs` 内复用最后一个滤波后的车辆坐标系；缓存到期后按传感器不可用处理。单独调用 `classifyDrivingSnapshot()` 不会使用控制器缓存。
+
 ### 读取当前状态
 
 订阅只通知后续变化。初次渲染或调试时，可以读取快照：
@@ -259,12 +261,20 @@ const controller = createDrivingStatusController({
     stoppedMotionThreshold: 0.11,
     stoppedConfirmationMs: 5_000,
     longitudinalThreshold: 0.75,
+    turnYawDominanceThreshold: 0.65,
+    turnLateralEvidenceThreshold: 0.3,
   },
 });
 ```
 
 `drivingMotionThreshold` 必须大于 `stoppedMotionThreshold`，进入阈值也必须大于相应退出阈值。样本数必须是正整数，方向一致率必须大于 `0.5` 且不大于 `1`，其余窗口和阈值必须是正有限数值。
 
+### 识别诊断
+
+`onDiagnostic` 的 `sample_available` 事件包含 `frameSource`（`live` 或 `cached`）和 `frameAgeMs`。`detector_evidence` 会报告基础状态 MAD、普通/急加减速的均值、峰值、方向一致率和 RMS，以及转向的累计角度、偏航主导率和横向/垂直 RMS。
+
+检测器状态变化时还会发送 `detector_transition`，其 `phase` 为 `candidate_entered`、`candidate_rejected`、`candidate_confirmed` 或 `candidate_exited`。该事件携带当时的完整 `statistics`，可直接用于真车回放调参；同一状态不会逐轮询重复发送。
+
 惯性传感器无法严格区分“完全静止”和“没有任何振动的理想匀速直线运动”。默认算法使用稳健振动统计、陀螺仪扰动和 5 秒确认近似判断，修改阈值后应使用完整路测过程回放验证。
 
 ### 驱动行车表情

package/dist/index.d.mts

@@ -102,6 +102,10 @@ interface DrivingStatusTuning {
   turnConfirmationMs: number;
   turnIntegratedAngleThreshold: number;
   turnSignCoherence: number;
+  turnYawDominanceThreshold: number;
+  turnLateralEvidenceThreshold: number;
+  turnVerticalNoiseFloor: number;
+  turnVerticalBumpRatio: number;
   turnExitYawThreshold: number;
   turnExitConfirmationMs: number;
   turnClosureWindowMs: number;
@@ -115,6 +119,7 @@ interface DrivingVehicleFrame {
 }
 interface DrivingMetricsCorrection {
   filteredGravity?: Vector3Value;
+  filteredGravitySampledAtMs?: number;
   linearAccelerationBias?: Vector3Value;
   gyroscopeBias?: Vector3Value;
 }
@@ -247,10 +252,54 @@ interface DrivingStatusEvent {
   reason: DrivingStatusChangeReason;
   atMs: number;
 }
+type DrivingFrameSource = 'live' | 'cached';
+type DrivingDetectorName = 'base' | 'rapid_longitudinal' | 'longitudinal' | 'turn';
+type DrivingDetectorTransitionPhase = 'candidate_entered' | 'candidate_rejected' | 'candidate_confirmed' | 'candidate_exited';
+type DrivingDetectorRejectionReason = 'vertical_bump' | 'longitudinal_reversal' | null;
+interface DrivingBaseDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  motionMad: number | null;
+  gyroMagnitude: number;
+  rawGyroMagnitude: number;
+}
+interface DrivingLongitudinalWindowStatistics {
+  sampleCount: number;
+  durationMs: number;
+  mean: number;
+  peak: number;
+  coherence: number;
+}
+interface DrivingRapidLongitudinalStatistics extends DrivingLongitudinalWindowStatistics {
+  longitudinalRms: number;
+  verticalRms: number;
+  hasReversal: boolean;
+}
+interface DrivingTurnDetectorStatistics {
+  sampleCount: number;
+  durationMs: number;
+  strongMean: number;
+  strongCoherence: number;
+  signedAngle: number;
+  gentleCoherence: number;
+  yawRms: number;
+  rawGyroRms: number;
+  yawDominance: number;
+  lateralRms: number;
+  verticalRms: number;
+}
+interface DrivingDetectorStatistics {
+  base: DrivingBaseDetectorStatistics;
+  longitudinal: DrivingLongitudinalWindowStatistics | null;
+  rapidLongitudinal: DrivingRapidLongitudinalStatistics | null;
+  turn: DrivingTurnDetectorStatistics | null;
+}
 type DrivingStatusDiagnosticEvent = {
   type: 'sample_available';
   atMs: number;
   capturedAtMs: number;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
   tuningVersion: string;
 } | {
   type: 'sample_unavailable';
@@ -266,7 +315,19 @@ type DrivingStatusDiagnosticEvent = {
   rapidCandidate: 'RAPID_ACCELERATION' | 'SUDDEN_BRAKING' | null;
   longitudinalCandidate: 'ACCELERATION' | 'BRAKING' | null;
   turnCandidate: 'LEFT_TURN' | 'RIGHT_TURN' | null;
-  rejectionReason: 'vertical_bump' | 'longitudinal_reversal' | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  frameSource: DrivingFrameSource;
+  frameAgeMs: number;
+  statistics: DrivingDetectorStatistics;
+  tuningVersion: string;
+} | {
+  type: 'detector_transition';
+  atMs: number;
+  detector: DrivingDetectorName;
+  phase: DrivingDetectorTransitionPhase;
+  status: CarRunningStatus | null;
+  rejectionReason: DrivingDetectorRejectionReason;
+  statistics: DrivingDetectorStatistics;
   tuningVersion: string;
 } | {
   type: 'candidate_changed';
@@ -373,4 +434,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, DrivingMetricsCorrection, DrivingSensorProvider, DrivingSnapshotAnalysis, DrivingSnapshotCandidate, DrivingSnapshotMetrics, DrivingSnapshotRejectionReason, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingVehicleFrame, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, buildVehicleFrame, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };
+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, DrivingBaseDetectorStatistics, DrivingControllerSnapshot, DrivingDetectorName, DrivingDetectorRejectionReason, DrivingDetectorStatistics, DrivingDetectorTransitionPhase, DrivingExpressionMedia, DrivingExpressionPlayer, DrivingExpressionPlayerDiagnosticEvent, DrivingExpressionPlayerErrorCategory, DrivingExpressionPlayerOptions, DrivingExpressionPlayerSnapshot, DrivingExpressionResolutionError, DrivingExpressionsConfig, DrivingExpressionsConfigError, DrivingExpressionsConfigErrorCode, DrivingExpressionsConfigInput, DrivingFrameSource, DrivingLongitudinalWindowStatistics, DrivingMetricsCorrection, DrivingRapidLongitudinalStatistics, DrivingSensorProvider, DrivingSnapshotAnalysis, DrivingSnapshotCandidate, DrivingSnapshotMetrics, DrivingSnapshotRejectionReason, DrivingStatusChangeReason, DrivingStatusClock, DrivingStatusController, DrivingStatusControllerOptions, DrivingStatusDiagnosticEvent, DrivingStatusEvent, DrivingStatusTuning, DrivingStatusTuningOverrides, DrivingTurnDetectorStatistics, DrivingVehicleFrame, EmojiDrivingExpressionMedia, ImageDrivingExpressionMedia, LivePhotoDrivingExpressionMedia, MediaLibraryRef, OFFICIAL_DRIVING_EXPRESSIONS_CONFIG, OFFICIAL_DRIVING_EXPRESSION_FALLBACKS, OrientationValue, ParseDrivingExpressionsOptions, StructuredDrivingExpressionMedia, TgsDrivingExpressionMedia, UnavailableSensorMetric, UnifiedSensorInfoPayload, UnifiedSensorMetric, UnifiedSensorUnavailableReason, Vector3Value, VideoDrivingExpressionMedia, WaitForDrivingExpressionsConfigOptions, buildVehicleFrame, classifyDrivingSnapshot, createDrivingExpressionPlayer, createDrivingStatusController, extractDrivingSnapshotMetrics, isPublicDrivingMediaUrl, parseDrivingExpressionsConfig, readDrivingExpressionsConfig, resolveDrivingExpression, resolveDrivingExpressionStrict, resolveDrivingStatusTuning, tryParseDrivingExpressionsConfig, unifiedSensorInfo, waitForDrivingExpressionsConfig };

package/dist/index.mjs

@@ -91,6 +91,10 @@ const DEFAULT_DRIVING_STATUS_TUNING = Object.freeze({
 	turnConfirmationMs: 600,
 	turnIntegratedAngleThreshold: .12,
 	turnSignCoherence: .7,
+	turnYawDominanceThreshold: .6,
+	turnLateralEvidenceThreshold: .25,
+	turnVerticalNoiseFloor: .1,
+	turnVerticalBumpRatio: 1.25,
 	turnExitYawThreshold: .04,
 	turnExitConfirmationMs: 700,
 	turnClosureWindowMs: 1500
@@ -154,6 +158,9 @@ const resolveDrivingStatusTuning = (overrides = {}) => {
 		"turnYawThreshold",
 		"turnConfirmationMs",
 		"turnIntegratedAngleThreshold",
+		"turnLateralEvidenceThreshold",
+		"turnVerticalNoiseFloor",
+		"turnVerticalBumpRatio",
 		"turnExitYawThreshold",
 		"turnExitConfirmationMs",
 		"turnClosureWindowMs"
@@ -167,7 +174,8 @@ const resolveDrivingStatusTuning = (overrides = {}) => {
 	for (const field of [
 		"longitudinalSignCoherence",
 		"rapidLongitudinalSignCoherence",
-		"turnSignCoherence"
+		"turnSignCoherence",
+		"turnYawDominanceThreshold"
 	]) {
 		const value = tuning[field];
 		if (!Number.isFinite(value) || value <= .5 || value > 1) throwLoggedRangeError("resolveDrivingStatusTuning", `${field} must be greater than 0.5 and less than or equal to 1`);
@@ -195,19 +203,22 @@ const extractDrivingSnapshotMetrics = (info, tuning = DEFAULT_DRIVING_STATUS_TUN
 	const linearAcceleration = availableFreshVector(info.linearAcceleration, info.capturedAtMs, tuning.maxSampleAgeMs);
 	const gyroscope = availableFreshVector(info.gyroscope, info.capturedAtMs, tuning.maxSampleAgeMs);
 	const gravityMetric = availableFreshVector(info.gravity, info.capturedAtMs, tuning.maxSampleAgeMs);
-	if (linearAcceleration === null || gyroscope === null || gravityMetric === null) {
+	const gravity = availableCorrectedGravity(correction, info.capturedAtMs, tuning.maxSampleAgeMs) ?? (correction.filteredGravity !== void 0 && gravityMetric !== null ? {
+		value: correction.filteredGravity,
+		sampledAtMs: gravityMetric.sampledAtMs
+	} : gravityMetric);
+	if (linearAcceleration === null || gyroscope === null || gravity === null) {
 		dialSdkDebugWarn(DEBUG_MODULE$5, "extractDrivingSnapshotMetrics", "returned unavailable vectors", {
 			linearAcceleration,
 			gyroscope,
-			gravity: gravityMetric
+			gravity
 		});
 		return null;
 	}
-	const gravity = correction.filteredGravity ?? gravityMetric.value;
-	const frame = buildVehicleFrame(gravity, tuning.vehicleRightMinimumNorm);
+	const frame = buildVehicleFrame(gravity.value, tuning.vehicleRightMinimumNorm);
 	if (frame === null) {
 		dialSdkDebugWarn(DEBUG_MODULE$5, "extractDrivingSnapshotMetrics", "returned invalid vehicle frame", {
-			gravity,
+			gravity: gravity.value,
 			vehicleRightMinimumNorm: tuning.vehicleRightMinimumNorm
 		});
 		return null;
@@ -218,7 +229,7 @@ const extractDrivingSnapshotMetrics = (info, tuning = DEFAULT_DRIVING_STATUS_TUN
 		capturedAtMs: info.capturedAtMs,
 		linearAccelerationSampledAtMs: linearAcceleration.sampledAtMs,
 		gyroscopeSampledAtMs: gyroscope.sampledAtMs,
-		gravitySampledAtMs: gravityMetric.sampledAtMs,
+		gravitySampledAtMs: gravity.sampledAtMs,
 		longitudinal: dot(correctedLinear, frame.forward),
 		lateral: dot(correctedLinear, frame.right),
 		vertical: dot(correctedLinear, frame.up),
@@ -299,6 +310,19 @@ const availableFreshVector = (metric, capturedAtMs, maxSampleAgeMs) => {
 		sampledAtMs: metric.sampledAtMs
 	} : null;
 };
+const availableCorrectedGravity = (correction, capturedAtMs, maxSampleAgeMs) => {
+	const { filteredGravity, filteredGravitySampledAtMs } = correction;
+	if (filteredGravity === void 0 || filteredGravitySampledAtMs === void 0 || !isFresh(filteredGravitySampledAtMs, capturedAtMs, maxSampleAgeMs)) return null;
+	const { x, y, z } = filteredGravity;
+	return [
+		x,
+		y,
+		z
+	].every(Number.isFinite) ? {
+		value: filteredGravity,
+		sampledAtMs: filteredGravitySampledAtMs
+	} : null;
+};
 const isFresh = (sampledAtMs, capturedAtMs, maxSampleAgeMs) => {
 	if (sampledAtMs === null || !Number.isFinite(sampledAtMs)) return false;
 	const age = capturedAtMs - sampledAtMs;
@@ -1363,6 +1387,18 @@ var DefaultDrivingStatusController = class {
 		this.turnStatus = null;
 		this.turnQuietSinceMs = null;
 		this.oppositeTurnSinceMs = null;
+		this.detectorCandidates = {
+			base: null,
+			rapid_longitudinal: null,
+			longitudinal: null,
+			turn: null
+		};
+		this.detectorRejections = {
+			base: null,
+			rapid_longitudinal: null,
+			longitudinal: null,
+			turn: null
+		};
 		this.requestedRunning = false;
 		this.polling = false;
 		this.lifecycleSuspended = false;
@@ -1567,21 +1603,22 @@ var DefaultDrivingStatusController = class {
 				});
 				return;
 			}
-			const gravity = this.updateFilteredGravity(payload);
+			const gravity = this.resolveGravityFrame(payload);
 			const metrics = gravity === null ? null : extractDrivingSnapshotMetrics(payload, this.tuning, {
-				filteredGravity: gravity,
+				filteredGravity: gravity.value,
+				filteredGravitySampledAtMs: gravity.sampledAtMs,
 				linearAccelerationBias: this.linearAccelerationBias,
 				gyroscopeBias: this.gyroscopeBias
 			});
 			const accelerometerSample = extractFreshVectorMetric(payload.accelerometer, payload.capturedAtMs, this.tuning.maxSampleAgeMs);
-			if (metrics === null || accelerometerSample === null) {
+			if (gravity === null || metrics === null || accelerometerSample === null) {
 				dialSdkDebugWarn(DEBUG_MODULE$1, "DefaultDrivingStatusController.poll", "invalid or stale snapshot", {
 					metrics,
 					accelerometerSample
 				});
 				this.processUnavailable("invalid_or_stale_snapshot");
 			} else {
-				this.processAvailable(metrics, accelerometerSample);
+				this.processAvailable(metrics, accelerometerSample, gravity);
 				dialSdkDebugWarn(DEBUG_MODULE$1, "DefaultDrivingStatusController.poll", "processed sample", { capturedAtMs: metrics.capturedAtMs });
 			}
 		} catch (error) {
@@ -1600,21 +1637,44 @@ var DefaultDrivingStatusController = class {
 			});
 		}
 	}
-	updateFilteredGravity(info) {
+	resolveGravityFrame(info) {
 		const sample = extractFreshVectorMetric(info.gravity, info.capturedAtMs, this.tuning.maxSampleAgeMs);
-		if (sample === null) return null;
-		if (sample.sampledAtMs === this.lastGravitySampledAtMs) return this.filteredGravity;
+		if (sample === null) {
+			if (this.filteredGravity === null || this.lastGravitySampledAtMs === null) return null;
+			const ageMs = info.capturedAtMs - this.lastGravitySampledAtMs;
+			return ageMs >= 0 && ageMs <= this.tuning.maxSampleAgeMs ? {
+				value: this.filteredGravity,
+				sampledAtMs: this.lastGravitySampledAtMs,
+				source: "cached"
+			} : null;
+		}
+		if (sample.sampledAtMs === this.lastGravitySampledAtMs && this.filteredGravity !== null) return {
+			value: this.filteredGravity,
+			sampledAtMs: sample.sampledAtMs,
+			source: "live"
+		};
 		if (this.filteredGravity === null || this.lastGravitySampledAtMs === null) this.filteredGravity = { ...sample.value };
 		else {
-			if (sample.sampledAtMs < this.lastGravitySampledAtMs) return this.filteredGravity;
+			if (sample.sampledAtMs < this.lastGravitySampledAtMs) {
+				const ageMs = info.capturedAtMs - this.lastGravitySampledAtMs;
+				return ageMs >= 0 && ageMs <= this.tuning.maxSampleAgeMs ? {
+					value: this.filteredGravity,
+					sampledAtMs: this.lastGravitySampledAtMs,
+					source: "cached"
+				} : null;
+			}
 			const elapsedMs = Math.max(0, sample.sampledAtMs - this.lastGravitySampledAtMs);
 			const alpha = 1 - Math.exp(-elapsedMs / this.tuning.gravityFilterTimeConstantMs);
 			this.filteredGravity = lerpVector(this.filteredGravity, sample.value, alpha);
 		}
 		this.lastGravitySampledAtMs = sample.sampledAtMs;
-		return this.filteredGravity;
+		return {
+			value: this.filteredGravity,
+			sampledAtMs: sample.sampledAtMs,
+			source: "live"
+		};
 	}
-	processAvailable(metrics, accelerometerSample) {
+	processAvailable(metrics, accelerometerSample, gravity) {
 		dialSdkDebugWarn(DEBUG_MODULE$1, "DefaultDrivingStatusController.processAvailable", "called", {
 			metrics,
 			accelerometerSample
@@ -1627,6 +1687,8 @@ var DefaultDrivingStatusController = class {
 			type: "sample_available",
 			atMs: now,
 			capturedAtMs: metrics.capturedAtMs,
+			frameSource: gravity.source,
+			frameAgeMs: metrics.capturedAtMs - gravity.sampledAtMs,
 			tuningVersion: this.tuning.version
 		});
 		const addedLongitudinal = pushUniqueMetric(this.longitudinalWindow, metrics, "linearAccelerationSampledAtMs", Math.max(this.tuning.longitudinalWindowMs, this.tuning.rapidLongitudinalWindowMs));
@@ -1637,6 +1699,10 @@ var DefaultDrivingStatusController = class {
 			return;
 		}
 		const motionMad = calculateCombinedAxisMad(this.motionWindow, this.tuning.motionMinimumSamples);
+		const previousBaseStatus = this.baseStatus;
+		const previousUrgentStatus = this.urgentStatus;
+		const previousLongitudinalStatus = this.normalLongitudinalStatus;
+		const previousTurnStatus = this.turnStatus;
 		const baseCondition = this.updateBaseDetector(motionMad, metrics, accelerometerSample.sampledAtMs, addedMotion);
 		const longitudinalEvidence = detectLongitudinalEvidence(this.longitudinalWindow, this.tuning);
 		if (addedLongitudinal) this.updateLongitudinalDetector(longitudinalEvidence, metrics.linearAccelerationSampledAtMs);
@@ -1648,6 +1714,27 @@ var DefaultDrivingStatusController = class {
 			this.stationaryConfirmed = false;
 		}
 		if (this.stationaryConfirmed) this.updateBias(metrics);
+		const statistics = {
+			base: {
+				sampleCount: this.motionWindow.length,
+				durationMs: vectorWindowDuration(this.motionWindow),
+				motionMad,
+				gyroMagnitude: metrics.gyroMagnitude,
+				rawGyroMagnitude: metrics.rawGyroMagnitude
+			},
+			longitudinal: longitudinalEvidence.normalStatistics,
+			rapidLongitudinal: longitudinalEvidence.rapidStatistics,
+			turn: turnEvidence.statistics
+		};
+		const baseCandidate = baseCondition === "stationary" ? "STOPPED" : baseCondition === "moving" ? "STEADY_DRIVING" : null;
+		this.updateDetectorCandidate("base", baseCandidate, null, statistics, now);
+		this.updateDetectorCandidate("rapid_longitudinal", longitudinalEvidence.rapidCandidate, longitudinalEvidence.rejectionReason, statistics, now);
+		this.updateDetectorCandidate("longitudinal", longitudinalEvidence.normalCandidate, null, statistics, now);
+		this.updateDetectorCandidate("turn", turnEvidence.candidate, turnEvidence.rejectionReason, statistics, now);
+		this.emitDetectorConfirmation("base", previousBaseStatus, this.baseStatus, statistics, now);
+		this.emitDetectorConfirmation("rapid_longitudinal", previousUrgentStatus, this.urgentStatus, statistics, now);
+		this.emitDetectorConfirmation("longitudinal", previousLongitudinalStatus, this.normalLongitudinalStatus, statistics, now);
+		this.emitDetectorConfirmation("turn", previousTurnStatus, this.turnStatus, statistics, now);
 		const pendingCandidate = instantaneousCandidate(metrics, this.tuning);
 		this.setCandidate(pendingCandidate === this.status ? null : pendingCandidate, observationTime(metrics));
 		this.emitDiagnostic({
@@ -1658,7 +1745,10 @@ var DefaultDrivingStatusController = class {
 			rapidCandidate: longitudinalEvidence.rapidCandidate,
 			longitudinalCandidate: longitudinalEvidence.normalCandidate,
 			turnCandidate: turnEvidence.candidate,
-			rejectionReason: longitudinalEvidence.rejectionReason,
+			rejectionReason: longitudinalEvidence.rejectionReason ?? turnEvidence.rejectionReason,
+			frameSource: gravity.source,
+			frameAgeMs: metrics.capturedAtMs - gravity.sampledAtMs,
+			statistics,
 			tuningVersion: this.tuning.version
 		});
 		const hasAction = this.urgentStatus !== null || this.turnStatus !== null || this.normalLongitudinalStatus !== null;
@@ -1766,6 +1856,31 @@ var DefaultDrivingStatusController = class {
 		}
 		this.lastBiasSampledAtMs = sampledAtMs;
 	}
+	updateDetectorCandidate(detector, candidate, rejectionReason, statistics, atMs) {
+		const previousCandidate = this.detectorCandidates[detector];
+		if (previousCandidate !== candidate) {
+			if (previousCandidate !== null) this.emitDetectorTransition(detector, "candidate_exited", previousCandidate, null, statistics, atMs);
+			if (candidate !== null) this.emitDetectorTransition(detector, "candidate_entered", candidate, null, statistics, atMs);
+			this.detectorCandidates[detector] = candidate;
+		}
+		if (rejectionReason !== null && rejectionReason !== this.detectorRejections[detector]) this.emitDetectorTransition(detector, "candidate_rejected", null, rejectionReason, statistics, atMs);
+		this.detectorRejections[detector] = rejectionReason;
+	}
+	emitDetectorConfirmation(detector, previousStatus, status, statistics, atMs) {
+		if (status !== null && status !== previousStatus) this.emitDetectorTransition(detector, "candidate_confirmed", status, null, statistics, atMs);
+	}
+	emitDetectorTransition(detector, phase, status, rejectionReason, statistics, atMs) {
+		this.emitDiagnostic({
+			type: "detector_transition",
+			atMs,
+			detector,
+			phase,
+			status,
+			rejectionReason,
+			statistics,
+			tuningVersion: this.tuning.version
+		});
+	}
 	commitSelectedStatus(now) {
 		const selected = this.urgentStatus ?? this.turnStatus ?? this.normalLongitudinalStatus ?? this.baseStatus;
 		this.commit(selected, now, "candidate_confirmed");
@@ -1868,6 +1983,10 @@ var DefaultDrivingStatusController = class {
 		this.turnStatus = null;
 		this.turnQuietSinceMs = null;
 		this.oppositeTurnSinceMs = null;
+		for (const detector of Object.keys(this.detectorCandidates)) {
+			this.detectorCandidates[detector] = null;
+			this.detectorRejections[detector] = null;
+		}
 	}
 	resetTransientRecognition() {
 		this.clearRecognitionWindows();
@@ -1899,36 +2018,57 @@ const detectLongitudinalEvidence = (window, tuning) => {
 	const normalWindow = recentMetrics(window, tuning.longitudinalWindowMs, "linearAccelerationSampledAtMs");
 	let rapidCandidate = null;
 	let rejectionReason = null;
+	const rapidValues = rapidWindow.map((sample) => sample.longitudinal);
+	const rapidMean = trimmedMean(rapidValues);
+	const rapidDirection = Math.sign(rapidMean);
+	const rapidCoherence = signCoherence(rapidValues, rapidDirection, tuning.longitudinalExitThreshold);
+	const rapidPeak = maximumAbsolute(rapidValues);
+	const longitudinalRms = rootMeanSquare(rapidValues);
+	const verticalRms = rootMeanSquare(rapidWindow.map((sample) => sample.vertical));
+	const reversalWindow = recentMetrics(window, tuning.longitudinalReversalWindowMs, "linearAccelerationSampledAtMs");
+	const hasReversal = containsBothSigns(reversalWindow.map((sample) => sample.longitudinal), tuning.longitudinalThreshold);
+	const rapidStatistics = rapidWindow.length === 0 ? null : {
+		sampleCount: rapidWindow.length,
+		durationMs: metricWindowDuration(rapidWindow, "linearAccelerationSampledAtMs"),
+		mean: rapidMean,
+		peak: rapidPeak,
+		coherence: rapidCoherence,
+		longitudinalRms,
+		verticalRms,
+		hasReversal
+	};
 	if (windowCovers(rapidWindow, tuning.rapidLongitudinalMinimumSamples, tuning.rapidLongitudinalWindowMs, "linearAccelerationSampledAtMs")) {
-		const values = rapidWindow.map((sample) => sample.longitudinal);
-		const direction = Math.sign(trimmedMean(values));
-		const coherence = signCoherence(values, direction, tuning.longitudinalExitThreshold);
-		const peak = Math.max(...values.map(Math.abs));
-		const mean = Math.abs(trimmedMean(values));
-		const longitudinalRms = rootMeanSquare(values);
-		const verticalRms = rootMeanSquare(rapidWindow.map((sample) => sample.vertical));
-		const reversalWindow = recentMetrics(window, tuning.longitudinalReversalWindowMs, "linearAccelerationSampledAtMs");
-		const hasReversal = containsBothSigns(reversalWindow.map((sample) => sample.longitudinal), tuning.longitudinalThreshold);
-		if (peak >= tuning.rapidLongitudinalPeakThreshold && mean >= tuning.rapidLongitudinalMeanThreshold) {
+		if (rapidPeak >= tuning.rapidLongitudinalPeakThreshold && Math.abs(rapidMean) >= tuning.rapidLongitudinalMeanThreshold) {
 			if (verticalRms > longitudinalRms * tuning.verticalBumpRatio) rejectionReason = "vertical_bump";
 			else if (hasReversal) rejectionReason = "longitudinal_reversal";
-			else if (direction !== 0 && coherence >= tuning.rapidLongitudinalSignCoherence) rapidCandidate = direction > 0 ? "RAPID_ACCELERATION" : "SUDDEN_BRAKING";
+			else if (rapidDirection !== 0 && rapidCoherence >= tuning.rapidLongitudinalSignCoherence) rapidCandidate = rapidDirection > 0 ? "RAPID_ACCELERATION" : "SUDDEN_BRAKING";
 		}
 	}
 	let normalCandidate = null;
 	let retainedNormal = false;
+	let normalStatistics = null;
 	if (normalWindow.length > 0) {
 		const values = normalWindow.map((sample) => sample.longitudinal);
 		const mean = trimmedMean(values);
 		const direction = Math.sign(mean);
+		const coherence = signCoherence(values, direction, tuning.longitudinalExitThreshold);
+		normalStatistics = {
+			sampleCount: normalWindow.length,
+			durationMs: metricWindowDuration(normalWindow, "linearAccelerationSampledAtMs"),
+			mean,
+			peak: maximumAbsolute(values),
+			coherence
+		};
 		retainedNormal = Math.abs(mean) >= tuning.longitudinalExitThreshold;
-		if (windowCovers(normalWindow, tuning.longitudinalMinimumSamples, tuning.longitudinalWindowMs, "linearAccelerationSampledAtMs") && Math.abs(mean) >= tuning.longitudinalThreshold && signCoherence(values, direction, tuning.longitudinalExitThreshold) >= tuning.longitudinalSignCoherence) normalCandidate = direction > 0 ? "ACCELERATION" : "BRAKING";
+		if (windowCovers(normalWindow, tuning.longitudinalMinimumSamples, tuning.longitudinalWindowMs, "linearAccelerationSampledAtMs") && Math.abs(mean) >= tuning.longitudinalThreshold && coherence >= tuning.longitudinalSignCoherence) normalCandidate = direction > 0 ? "ACCELERATION" : "BRAKING";
 	}
 	return {
 		rapidCandidate,
 		normalCandidate,
 		retainedNormal,
-		rejectionReason
+		rejectionReason,
+		normalStatistics,
+		rapidStatistics
 	};
 };
 const detectTurnEvidence = (window, tuning) => {
@@ -1936,20 +2076,47 @@ const detectTurnEvidence = (window, tuning) => {
 	if (!latest) return {
 		candidate: null,
 		latestYaw: 0,
-		sampledAtMs: 0
+		sampledAtMs: 0,
+		rejectionReason: null,
+		statistics: null
 	};
 	const strongWindow = recentMetrics(window, tuning.turnConfirmationMs, "gyroscopeSampledAtMs");
 	const strongMean = trimmedMean(strongWindow.map((sample) => sample.yaw));
 	const strongDirection = Math.sign(strongMean);
-	const strong = windowCovers(strongWindow, tuning.turnMinimumSamples, tuning.turnConfirmationMs, "gyroscopeSampledAtMs") && Math.abs(strongMean) >= tuning.turnYawThreshold && signCoherence(strongWindow.map((sample) => sample.yaw), strongDirection, tuning.turnExitYawThreshold) >= tuning.turnSignCoherence;
+	const strongCoherence = signCoherence(strongWindow.map((sample) => sample.yaw), strongDirection, tuning.turnExitYawThreshold);
+	const strong = windowCovers(strongWindow, tuning.turnMinimumSamples, tuning.turnConfirmationMs, "gyroscopeSampledAtMs") && Math.abs(strongMean) >= tuning.turnYawThreshold && strongCoherence >= tuning.turnSignCoherence;
 	const signedAngle = integrateYaw(window);
 	const gentleDirection = Math.sign(signedAngle);
-	const gentle = window.length >= tuning.turnMinimumSamples && Math.abs(signedAngle) >= tuning.turnIntegratedAngleThreshold && signCoherence(window.map((sample) => sample.yaw), gentleDirection, tuning.turnExitYawThreshold) >= tuning.turnSignCoherence;
-	const direction = strong ? strongDirection : gentle ? gentleDirection : 0;
+	const gentleCoherence = signCoherence(window.map((sample) => sample.yaw), gentleDirection, tuning.turnExitYawThreshold);
+	const yawRms = rootMeanSquare(window.map((sample) => sample.yaw));
+	const rawGyroRms = rootMeanSquare(window.map((sample) => sample.rawGyroMagnitude));
+	const yawDominance = rawGyroRms <= Number.EPSILON ? 0 : Math.min(1, yawRms / rawGyroRms);
+	const lateralRms = rootMeanSquare(window.map((sample) => sample.lateral));
+	const verticalRms = rootMeanSquare(window.map((sample) => sample.vertical));
+	const gentleShape = window.length >= tuning.turnMinimumSamples && Math.abs(signedAngle) >= tuning.turnIntegratedAngleThreshold && gentleCoherence >= tuning.turnSignCoherence;
+	const verticalDominant = verticalRms > Math.max(lateralRms, tuning.turnVerticalNoiseFloor) * tuning.turnVerticalBumpRatio;
+	const yawDominant = yawDominance >= tuning.turnYawDominanceThreshold;
+	const laterallySupported = lateralRms >= tuning.turnLateralEvidenceThreshold;
+	const rejectionReason = !strong && gentleShape && verticalDominant && !yawDominant ? "vertical_bump" : null;
+	const direction = strong ? strongDirection : gentleShape && rejectionReason === null && (yawDominant || laterallySupported) ? gentleDirection : 0;
 	return {
 		candidate: direction === 0 ? null : direction > 0 ? "LEFT_TURN" : "RIGHT_TURN",
 		latestYaw: latest.yaw,
-		sampledAtMs: latest.gyroscopeSampledAtMs
+		sampledAtMs: latest.gyroscopeSampledAtMs,
+		rejectionReason,
+		statistics: {
+			sampleCount: window.length,
+			durationMs: metricWindowDuration(window, "gyroscopeSampledAtMs"),
+			strongMean,
+			strongCoherence,
+			signedAngle,
+			gentleCoherence,
+			yawRms,
+			rawGyroRms,
+			yawDominance,
+			lateralRms,
+			verticalRms
+		}
 	};
 };
 const instantaneousCandidate = (metrics, tuning) => {
@@ -1990,6 +2157,12 @@ const signCoherence = (values, direction, deadband) => {
 };
 const containsBothSigns = (values, threshold) => values.some((value) => value >= threshold) && values.some((value) => value <= -threshold);
 const rootMeanSquare = (values) => values.length === 0 ? 0 : Math.sqrt(values.reduce((sum, value) => sum + value ** 2, 0) / values.length);
+const maximumAbsolute = (values) => values.length === 0 ? 0 : Math.max(...values.map(Math.abs));
+const metricWindowDuration = (values, timestampKey) => {
+	const first = values[0];
+	const last = values[values.length - 1];
+	return first && last ? Math.max(0, last[timestampKey] - first[timestampKey]) : 0;
+};
 const calculateCombinedAxisMad = (samples, minimumSamples) => {
 	if (samples.length < minimumSamples) return null;
 	const medianX = median(samples.map((sample) => sample.value.x));
@@ -2000,6 +2173,11 @@ const calculateCombinedAxisMad = (samples, minimumSamples) => {
 	const madZ = median(samples.map((sample) => Math.abs(sample.value.z - medianZ)));
 	return Math.hypot(madX, madY, madZ);
 };
+const vectorWindowDuration = (values) => {
+	const first = values[0];
+	const last = values[values.length - 1];
+	return first && last ? Math.max(0, last.sampledAtMs - first.sampledAtMs) : 0;
+};
 const median = (values) => {
 	if (values.length === 0) return 0;
 	const sorted = [...values].sort((left, right) => left - right);

package/package.json

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