@jjlmoya/utils-drones 1.39.0 → 1.40.0

package/src/tool/fpv-drone-lap-timer/logic.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from 'vitest';
+import {
+  calculateSpeed,
+  estimateBatteryDrain,
+  computeLapRecords,
+  calculateSessionMetrics,
+  formatLapTime,
+  formatDelta,
+  isDebounceLocked,
+  PRESETS,
+} from './logic';
+
+describe('fpv-drone-lap-timer logic suite', () => {
+  describe('calculateSpeed', () => {
+    it('returns zero for invalid or non-positive inputs', () => {
+      expect(calculateSpeed(0, 10000)).toEqual({ kmh: 0, mph: 0 });
+      expect(calculateSpeed(250, 0)).toEqual({ kmh: 0, mph: 0 });
+      expect(calculateSpeed(-250, 10000)).toEqual({ kmh: 0, mph: 0 });
+      expect(calculateSpeed(250, -5000)).toEqual({ kmh: 0, mph: 0 });
+    });
+
+    it('calculates correct speed for typical 250m track in 15 seconds', () => {
+      const speed = calculateSpeed(250, 15000);
+      expect(speed.kmh).toBe(60);
+      expect(speed.mph).toBe(37.3);
+    });
+
+    it('calculates high-speed sprint accurately', () => {
+      const speed = calculateSpeed(400, 12000);
+      expect(speed.kmh).toBe(120);
+      expect(speed.mph).toBe(74.6);
+    });
+  });
+
+  describe('estimateBatteryDrain', () => {
+    it('returns zero for non-positive values', () => {
+      expect(estimateBatteryDrain(0, 1300)).toBe(0);
+      expect(estimateBatteryDrain(15000, 0)).toBe(0);
+      expect(estimateBatteryDrain(-15000, 1300)).toBe(0);
+    });
+
+    it('estimates linear drain proportional to total usable flight capacity', () => {
+      const drain = estimateBatteryDrain(15000, 1300);
+      expect(drain).toBeGreaterThan(0);
+      expect(drain).toBeLessThan(1300);
+      const drainDoubleTime = estimateBatteryDrain(30000, 1300);
+      expect(Math.abs(drainDoubleTime - drain * 2)).toBeLessThanOrEqual(1);
+    });
+  });
+
+  describe('computeLapRecords', () => {
+    it('returns empty array when no laps recorded', () => {
+      expect(computeLapRecords([], 250, 1300)).toEqual([]);
+    });
+
+    it('identifies fastest lap and computes deltas', () => {
+      const laps = [18500, 16200, 17100];
+      const records = computeLapRecords(laps, 250, 1300);
+
+      expect(records).toHaveLength(3);
+
+      expect(records[0]!.lapIndex).toBe(1);
+      expect(records[0]!.durationMs).toBe(18500);
+      expect(records[0]!.splitTimeMs).toBe(18500);
+      expect(records[0]!.isBest).toBe(false);
+      expect(records[0]!.deltaBestMs).toBe(2300);
+
+      expect(records[1]!.lapIndex).toBe(2);
+      expect(records[1]!.durationMs).toBe(16200);
+      expect(records[1]!.splitTimeMs).toBe(34700);
+      expect(records[1]!.isBest).toBe(true);
+      expect(records[1]!.deltaBestMs).toBe(0);
+
+      expect(records[2]!.lapIndex).toBe(3);
+      expect(records[2]!.durationMs).toBe(17100);
+      expect(records[2]!.splitTimeMs).toBe(51800);
+      expect(records[2]!.isBest).toBe(false);
+      expect(records[2]!.deltaBestMs).toBe(900);
+    });
+  });
+
+  describe('calculateSessionMetrics', () => {
+    it('handles empty session correctly', () => {
+      const stats = calculateSessionMetrics([], 250, 1300);
+      expect(stats.completedLaps).toBe(0);
+      expect(stats.totalDurationMs).toBe(0);
+      expect(stats.consistencyIndex).toBe(100);
+      expect(stats.consistencyRating).toBe('elite');
+      expect(stats.batteryRemainingMah).toBe(1300);
+    });
+
+    it('computes metrics for single lap', () => {
+      const stats = calculateSessionMetrics([16500], 250, 1300);
+      expect(stats.completedLaps).toBe(1);
+      expect(stats.fastestLapMs).toBe(16500);
+      expect(stats.fastestLapIndex).toBe(1);
+      expect(stats.averageLapMs).toBe(16500);
+      expect(stats.standardDeviationMs).toBe(0);
+      expect(stats.consistencyIndex).toBe(100);
+    });
+
+    it('computes high consistency for close lap times', () => {
+      const stats = calculateSessionMetrics([15000, 15100, 15050], 250, 1300);
+      expect(stats.consistencyIndex).toBeGreaterThanOrEqual(95);
+      expect(stats.consistencyRating).toBe('elite');
+      expect(stats.fastestLapMs).toBe(15000);
+      expect(stats.fastestLapIndex).toBe(1);
+    });
+
+    it('computes lower consistency for erratic lap times', () => {
+      const stats = calculateSessionMetrics([14000, 22000, 15000, 31000], 250, 1300);
+      expect(stats.consistencyIndex).toBeLessThan(80);
+      expect(stats.consistencyRating).toBe('novice');
+    });
+  });
+
+  describe('formatLapTime', () => {
+    it('formats millisecond timestamps into mm:ss.mmm', () => {
+      expect(formatLapTime(0)).toBe('00:00.000');
+      expect(formatLapTime(14320)).toBe('00:14.320');
+      expect(formatLapTime(75450)).toBe('01:15.450');
+      expect(formatLapTime(-500)).toBe('00:00.000');
+      expect(formatLapTime(NaN)).toBe('00:00.000');
+    });
+  });
+
+  describe('formatDelta', () => {
+    it('formats delta times cleanly', () => {
+      expect(formatDelta(0, true)).toBe('BEST');
+      expect(formatDelta(0, false)).toBe('±0.000s');
+      expect(formatDelta(450, false)).toBe('+0.450s');
+      expect(formatDelta(-320, false)).toBe('-0.320s');
+    });
+  });
+
+  describe('isDebounceLocked', () => {
+    it('prevents accidental triggers before debounce interval', () => {
+      expect(isDebounceLocked(0, 1000, 3000)).toBe(false);
+      expect(isDebounceLocked(1000, 2500, 3000)).toBe(true);
+      expect(isDebounceLocked(1000, 4001, 3000)).toBe(false);
+    });
+  });
+
+  describe('PRESETS', () => {
+    it('provides valid presets', () => {
+      expect(PRESETS.multigp.trackLengthM).toBe(250);
+      expect(PRESETS.whoop.trackLengthM).toBe(65);
+      expect(PRESETS.sprint.trackLengthM).toBe(400);
+      expect(PRESETS.multigp.debounceMs).toBeGreaterThan(0);
+    });
+  });
+});

package/src/tool/fpv-drone-lap-timer/logic.ts

@@ -0,0 +1,228 @@
+export interface LapRecord {
+  lapIndex: number;
+  durationMs: number;
+  splitTimeMs: number;
+  speedKmh: number;
+  speedMph: number;
+  batteryUsedMah: number;
+  deltaBestMs: number;
+  isBest: boolean;
+}
+
+export interface SessionMetrics {
+  totalDurationMs: number;
+  completedLaps: number;
+  fastestLapMs: number;
+  fastestLapIndex: number;
+  averageLapMs: number;
+  standardDeviationMs: number;
+  consistencyIndex: number;
+  consistencyRating: 'elite' | 'pro' | 'club' | 'novice';
+  totalBatteryUsedMah: number;
+  batteryRemainingMah: number;
+  averageSpeedKmh: number;
+  averageSpeedMph: number;
+}
+
+export interface SessionConfig {
+  trackLengthM: number;
+  targetLaps: number;
+  batteryCapacityMah: number;
+  debounceMs: number;
+  soundEnabled: boolean;
+}
+
+export const DEFAULT_CONFIG: SessionConfig = {
+  trackLengthM: 250,
+  targetLaps: 3,
+  batteryCapacityMah: 1300,
+  debounceMs: 3000,
+  soundEnabled: true,
+};
+
+export const PRESETS: Record<'multigp' | 'whoop' | 'sprint', SessionConfig> = {
+  multigp: {
+    trackLengthM: 250,
+    targetLaps: 3,
+    batteryCapacityMah: 1300,
+    debounceMs: 3000,
+    soundEnabled: true,
+  },
+  whoop: {
+    trackLengthM: 65,
+    targetLaps: 5,
+    batteryCapacityMah: 300,
+    debounceMs: 2000,
+    soundEnabled: true,
+  },
+  sprint: {
+    trackLengthM: 400,
+    targetLaps: 2,
+    batteryCapacityMah: 1550,
+    debounceMs: 4000,
+    soundEnabled: true,
+  },
+};
+
+export function calculateSpeed(trackLengthM: number, durationMs: number): { kmh: number; mph: number } {
+  if (trackLengthM <= 0 || durationMs <= 0) {
+    return { kmh: 0, mph: 0 };
+  }
+  const metersPerSecond = trackLengthM / (durationMs / 1000);
+  const kmh = metersPerSecond * 3.6;
+  const mph = kmh * 0.621371;
+  return {
+    kmh: Math.round(kmh * 10) / 10,
+    mph: Math.round(mph * 10) / 10,
+  };
+}
+
+export function estimateBatteryDrain(
+  durationMs: number,
+  batteryCapacityMah: number,
+  usableCapacityRatio = 0.8,
+  assumedFlightTimeMin = 3.5
+): number {
+  if (durationMs <= 0 || batteryCapacityMah <= 0 || assumedFlightTimeMin <= 0) {
+    return 0;
+  }
+  const totalUsableMah = batteryCapacityMah * usableCapacityRatio;
+  const totalAvailableMs = assumedFlightTimeMin * 60 * 1000;
+  const estimatedDrain = (durationMs / totalAvailableMs) * totalUsableMah;
+  return Math.round(estimatedDrain);
+}
+
+export function computeLapRecords(
+  lapDurationsMs: number[],
+  trackLengthM: number,
+  batteryCapacityMah: number
+): LapRecord[] {
+  if (lapDurationsMs.length === 0) {
+    return [];
+  }
+
+  const validDurations = lapDurationsMs.map((d) => Math.max(0, d));
+  const minDuration = Math.min(...validDurations);
+  let cumulativeSplitMs = 0;
+
+  return validDurations.map((durationMs, idx) => {
+    cumulativeSplitMs += durationMs;
+    const isBest = durationMs === minDuration && durationMs > 0;
+    const deltaBestMs = durationMs - minDuration;
+    const speed = calculateSpeed(trackLengthM, durationMs);
+    const batteryUsedMah = estimateBatteryDrain(durationMs, batteryCapacityMah);
+
+    return {
+      lapIndex: idx + 1,
+      durationMs,
+      splitTimeMs: cumulativeSplitMs,
+      speedKmh: speed.kmh,
+      speedMph: speed.mph,
+      batteryUsedMah,
+      deltaBestMs,
+      isBest,
+    };
+  });
+}
+
+function getEmptySessionMetrics(batteryCapacityMah: number): SessionMetrics {
+  return {
+    totalDurationMs: 0,
+    completedLaps: 0,
+    fastestLapMs: 0,
+    fastestLapIndex: 0,
+    averageLapMs: 0,
+    standardDeviationMs: 0,
+    consistencyIndex: 100,
+    consistencyRating: 'elite',
+    totalBatteryUsedMah: 0,
+    batteryRemainingMah: batteryCapacityMah,
+    averageSpeedKmh: 0,
+    averageSpeedMph: 0,
+  };
+}
+
+function calculateConsistency(durations: number[], avgMs: number) {
+  const count = durations.length;
+  const variance = durations.reduce((sum, d) => sum + Math.pow(d - avgMs, 2), 0) / count;
+  const stdDev = Math.round(Math.sqrt(variance));
+  const rawScore = count > 1 && avgMs > 0 ? (1 - stdDev / avgMs) * 100 : 100;
+  const index = Math.max(0, Math.min(100, Math.round(rawScore)));
+  let rating: 'elite' | 'pro' | 'club' | 'novice' = 'novice';
+  if (index >= 95) {
+    rating = 'elite';
+  } else if (index >= 88) {
+    rating = 'pro';
+  } else if (index >= 78) {
+    rating = 'club';
+  }
+  return { index, rating, stdDev };
+}
+
+export function calculateSessionMetrics(
+  lapDurationsMs: number[],
+  trackLengthM: number,
+  batteryCapacityMah: number
+): SessionMetrics {
+  const count = lapDurationsMs.length;
+  if (count === 0) return getEmptySessionMetrics(batteryCapacityMah);
+
+  const valid = lapDurationsMs.map((d) => Math.max(0, d));
+  const totalDurationMs = valid.reduce((sum, d) => sum + d, 0);
+  const fastestLapMs = Math.min(...valid);
+  const averageLapMs = Math.round(totalDurationMs / count);
+  const { index, rating, stdDev } = calculateConsistency(valid, averageLapMs);
+  const totalBatteryUsedMah = estimateBatteryDrain(totalDurationMs, batteryCapacityMah);
+  const avgSpeed = calculateSpeed(trackLengthM, averageLapMs);
+
+  return {
+    totalDurationMs,
+    completedLaps: count,
+    fastestLapMs,
+    fastestLapIndex: valid.indexOf(fastestLapMs) + 1,
+    averageLapMs,
+    standardDeviationMs: stdDev,
+    consistencyIndex: index,
+    consistencyRating: rating,
+    totalBatteryUsedMah,
+    batteryRemainingMah: Math.max(0, batteryCapacityMah - totalBatteryUsedMah),
+    averageSpeedKmh: avgSpeed.kmh,
+    averageSpeedMph: avgSpeed.mph,
+  };
+}
+
+export function formatLapTime(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) {
+    return '00:00.000';
+  }
+  const totalSeconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const milliseconds = Math.floor(ms % 1000);
+
+  const mm = String(minutes).padStart(2, '0');
+  const ss = String(seconds).padStart(2, '0');
+  const mmm = String(milliseconds).padStart(3, '0');
+
+  return `${mm}:${ss}.${mmm}`;
+}
+
+export function formatDelta(deltaMs: number, isBest = false): string {
+  if (isBest) {
+    return 'BEST';
+  }
+  if (!Number.isFinite(deltaMs) || deltaMs === 0) {
+    return '±0.000s';
+  }
+  const sign = deltaMs > 0 ? '+' : '-';
+  const seconds = (Math.abs(deltaMs) / 1000).toFixed(3);
+  return `${sign}${seconds}s`;
+}
+
+export function isDebounceLocked(lastRecordedTimestampMs: number, currentTimestampMs: number, debounceThresholdMs: number): boolean {
+  if (lastRecordedTimestampMs <= 0 || currentTimestampMs <= 0) {
+    return false;
+  }
+  const diff = Math.abs(currentTimestampMs - lastRecordedTimestampMs);
+  return diff < debounceThresholdMs;
+}

package/src/tool/fpv-drone-lap-timer/seo.astro

@@ -0,0 +1,16 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { fpvDroneLapTimer } from './entry';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = fpvDroneLapTimer.i18n[locale] || fpvDroneLapTimer.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content.seo?.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/fpv-drone-lap-timer/storage.ts

@@ -0,0 +1,52 @@
+import type { SessionConfig } from './logic';
+import { DEFAULT_CONFIG } from './logic';
+
+const STORAGE_KEY_CONFIG = 'fpv_drone_lap_timer_config_v1';
+const STORAGE_KEY_LAPS = 'fpv_drone_lap_timer_laps_v1';
+
+export function loadSessionConfig(): SessionConfig {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY_CONFIG);
+    if (!raw) {
+      return { ...DEFAULT_CONFIG };
+    }
+    const parsed = JSON.parse(raw);
+    return {
+      trackLengthM: Number(parsed.trackLengthM) || DEFAULT_CONFIG.trackLengthM,
+      targetLaps: Number(parsed.targetLaps) || DEFAULT_CONFIG.targetLaps,
+      batteryCapacityMah: Number(parsed.batteryCapacityMah) || DEFAULT_CONFIG.batteryCapacityMah,
+      debounceMs: Number(parsed.debounceMs) || DEFAULT_CONFIG.debounceMs,
+      soundEnabled: typeof parsed.soundEnabled === 'boolean' ? parsed.soundEnabled : DEFAULT_CONFIG.soundEnabled,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function saveSessionConfig(config: SessionConfig): void {
+  try {
+    localStorage.setItem(STORAGE_KEY_CONFIG, JSON.stringify(config));
+  } catch {}
+}
+
+export function loadSessionLaps(): number[] {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY_LAPS);
+    if (!raw) {
+      return [];
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter((n) => typeof n === 'number' && Number.isFinite(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+
+export function saveSessionLaps(laps: number[]): void {
+  try {
+    localStorage.setItem(STORAGE_KEY_LAPS, JSON.stringify(laps));
+  } catch {}
+}

package/src/tool/fpv-drone-lap-timer/ui.ts

@@ -0,0 +1,58 @@
+export interface FpvDroneLapTimerUI {
+  [key: string]: string;
+  setupHeading: string;
+  trackLengthLabel: string;
+  trackLengthUnit: string;
+  targetLapsLabel: string;
+  targetLapsUnit: string;
+  batteryCapacityLabel: string;
+  batteryCapacityUnit: string;
+  soundEnabledLabel: string;
+  debounceThresholdLabel: string;
+  debounceThresholdUnit: string;
+  presetMultiGpLabel: string;
+  presetWhoopLabel: string;
+  presetSprintLabel: string;
+  startCountdownButton: string;
+  pauseTimerButton: string;
+  resumeTimerButton: string;
+  resetTimerButton: string;
+  recordLapButton: string;
+  spacebarHint: string;
+  statusIdle: string;
+  statusCountdown: string;
+  statusRunning: string;
+  statusPaused: string;
+  statusFinished: string;
+  currentLapHeading: string;
+  lapNumberPrefix: string;
+  lastLapHeading: string;
+  fastestLapHeading: string;
+  averageLapHeading: string;
+  deltaBestHeading: string;
+  consistencyIndexHeading: string;
+  estimatedSpeedHeading: string;
+  estimatedBatteryHeading: string;
+  speedUnitKmh: string;
+  speedUnitMph: string;
+  batteryUsedUnit: string;
+  batteryRemainingUnit: string;
+  lapHistoryHeading: string;
+  lapColumnHeader: string;
+  timeColumnHeader: string;
+  splitColumnHeader: string;
+  speedColumnHeader: string;
+  batteryColumnHeader: string;
+  noLapsRecordedNotice: string;
+  consistencyRatingElite: string;
+  consistencyRatingPro: string;
+  consistencyRatingClub: string;
+  consistencyRatingNovice: string;
+  fastestLapBadge: string;
+  sessionSummaryHeading: string;
+  totalTimeLabel: string;
+  completedLapsLabel: string;
+  exportCsvButton: string;
+  copySummaryButton: string;
+  copiedNotice: string;
+}

package/src/tools.ts

@@ -9,6 +9,7 @@ import { FPV_DRONE_THRUST_TO_WEIGHT_RATIO_TOOL } from './tool/fpv-drone-thrust-t
 import { DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL } from './tool/drone-motor-propeller-calculator/index';
 import { FPV_DRONE_SPEED_CALCULATOR_TOOL } from './tool/fpv-drone-speed-calculator/index';
 import { DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL } from './tool/drone-mission-battery-reserve-planner/index';
+import { FPV_DRONE_LAP_TIMER_TOOL } from './tool/fpv-drone-lap-timer/index';
 import type { ToolDefinition } from './types';
 
 export const ALL_TOOLS: ToolDefinition[] = [
@@ -22,6 +23,7 @@ export const ALL_TOOLS: ToolDefinition[] = [
   DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL,
   FPV_DRONE_SPEED_CALCULATOR_TOOL,
   DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL,
+  FPV_DRONE_LAP_TIMER_TOOL,
 ];
 
 export {
@@ -35,5 +37,6 @@ export {
   DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL,
   FPV_DRONE_SPEED_CALCULATOR_TOOL,
   DRONE_MISSION_BATTERY_RESERVE_PLANNER_TOOL,
+  FPV_DRONE_LAP_TIMER_TOOL,
 };