@jjlmoya/utils-drones 1.39.0 → 1.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jjlmoya/utils-drones",
-    "version": "1.39.0",
+    "version": "1.41.0",
     "type": "module",
     "main": "./src/index.ts",
     "types": "./src/index.ts",
@@ -36,7 +36,7 @@
         "postinstall": "node scripts/postinstall.mjs",
         "predev": "node scripts/postinstall.mjs",
         "prestart": "node scripts/postinstall.mjs",
-        "prebuild": "node scripts/postinstall.mjs",
+        "prebuild": "node scripts/postinstall.mjs && node scripts/validate-icons.mjs",
         "qa": "npm run lint && npm run test && npm run build",
         "cf:dry-run": "npm run build && wrangler deploy --dry-run",
         "cf:preview": "npm run build && wrangler deploy --config wrangler.staging.jsonc",

package/scripts/validate-icons.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const packageJsonPath = require.resolve('@iconify-json/mdi/package.json');
+const packageRoot = dirname(packageJsonPath);
+const iconSet = JSON.parse(readFileSync(join(packageRoot, 'icons.json'), 'utf8'));
+const availableIcons = new Set([
+  ...Object.keys(iconSet.icons ?? {}),
+  ...Object.keys(iconSet.aliases ?? {}),
+]);
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const sourceRoot = resolve(repoRoot, 'src');
+const extensions = new Set(['.astro', '.js', '.mjs', '.ts', '.tsx']);
+const iconPattern = /\bmdi:([a-z0-9-]+)\b/g;
+const failures = [];
+let references = 0;
+
+function walk(directory) {
+  const entries = readdirSync(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules' && entry.name !== 'dist' && entry.name !== 'tests') {
+        walk(path);
+      }
+      continue;
+    }
+    if (!extensions.has(path.slice(path.lastIndexOf('.')))) continue;
+
+    const source = readFileSync(path, 'utf8');
+    for (const match of source.matchAll(iconPattern)) {
+      references += 1;
+      const iconName = match[1];
+      if (availableIcons.has(iconName)) continue;
+
+      const line = source.slice(0, match.index).split('\n').length;
+      failures.push(`${relative(repoRoot, path)}:${line} — mdi:${iconName}`);
+    }
+  }
+}
+
+walk(sourceRoot);
+
+if (failures.length > 0) {
+  console.error('Invalid MDI icons found:');
+  for (const failure of failures) console.error(`- ${failure}`);
+  console.error(`Checked ${references} MDI icon references against @iconify-json/mdi.`);
+  process.exitCode = 1;
+} else {
+  console.log(`MDI icon validation passed: ${references} references checked.`);
+}

package/src/category/index.ts

@@ -9,6 +9,7 @@ import { fpvDroneThrustToWeightRatio } from '../tool/fpv-drone-thrust-to-weight-
 import { droneMotorPropellerCalculator } from '../tool/drone-motor-propeller-calculator/entry';
 import { fpvDroneSpeedCalculator } from '../tool/fpv-drone-speed-calculator/entry';
 import { droneMissionBatteryReservePlanner } from '../tool/drone-mission-battery-reserve-planner/entry';
+import { fpvDroneLapTimer } from '../tool/fpv-drone-lap-timer/entry';
 
 export const dronesCategory: DronesCategoryEntry = {
   icon: 'mdi:drone',
@@ -23,6 +24,7 @@ export const dronesCategory: DronesCategoryEntry = {
     droneMotorPropellerCalculator,
     fpvDroneSpeedCalculator,
     droneMissionBatteryReservePlanner,
+    fpvDroneLapTimer,
   ],
   i18n: {
     es: () => import('./i18n/es').then((m) => m.content),

package/src/entries.ts

@@ -18,6 +18,8 @@ export { fpvDroneSpeedCalculator } from './tool/fpv-drone-speed-calculator/entry
 export type { FpvDroneSpeedUI, FpvDroneSpeedLocaleContent } from './tool/fpv-drone-speed-calculator/entry';
 export { droneMissionBatteryReservePlanner } from './tool/drone-mission-battery-reserve-planner/entry';
 export type { DroneMissionBatteryReservePlannerUI, DroneMissionBatteryReservePlannerLocaleContent } from './tool/drone-mission-battery-reserve-planner/entry';
+export { fpvDroneLapTimer } from './tool/fpv-drone-lap-timer/entry';
+export type { FpvDroneLapTimerUI, FpvDroneLapTimerLocaleContent } from './tool/fpv-drone-lap-timer/entry';
 export { dronesCategory } from './category';
 
 import { antennaLengthCalculator } from './tool/antenna-length-calculator/entry';
@@ -30,6 +32,7 @@ import { fpvDroneThrustToWeightRatio } from './tool/fpv-drone-thrust-to-weight-r
 import { droneMotorPropellerCalculator } from './tool/drone-motor-propeller-calculator/entry';
 import { fpvDroneSpeedCalculator } from './tool/fpv-drone-speed-calculator/entry';
 import { droneMissionBatteryReservePlanner } from './tool/drone-mission-battery-reserve-planner/entry';
+import { fpvDroneLapTimer } from './tool/fpv-drone-lap-timer/entry';
 
 export const ALL_ENTRIES = [
   antennaLengthCalculator,
@@ -42,4 +45,5 @@ export const ALL_ENTRIES = [
   droneMotorPropellerCalculator,
   fpvDroneSpeedCalculator,
   droneMissionBatteryReservePlanner,
+  fpvDroneLapTimer,
 ];

package/src/index.ts

@@ -23,3 +23,4 @@ export { DRONE_POWER_ANALYZER_TOOL } from './tool/drone-power-analyzer/index';
 export { GSD_FLIGHT_PLANNER_TOOL } from './tool/gsd-flight-planner/index';
 export { DRONE_MOTOR_PROPELLER_CALCULATOR_TOOL } from './tool/drone-motor-propeller-calculator/index';
 export { FPV_DRONE_SPEED_CALCULATOR_TOOL } from './tool/fpv-drone-speed-calculator/index';
+export { FPV_DRONE_LAP_TIMER_TOOL } from './tool/fpv-drone-lap-timer/index';

package/src/tests/locale_completeness.test.ts

@@ -17,7 +17,7 @@ describe('Locale Completeness Validation', () => {
     });
   });
 
-  it('all 10 tools registered', () => {
-    expect(ALL_TOOLS.length).toBe(10);
+  it('all 11 tools registered', () => {
+    expect(ALL_TOOLS.length).toBe(11);
   });
 });

package/src/tests/tool_validation.test.ts

@@ -4,8 +4,8 @@ import { dronesCategory } from '../data';
 
 describe('Tool Validation Suite', () => {
   describe('Library Registration', () => {
-    it('should have 10 tools in ALL_TOOLS', () => {
-      expect(ALL_TOOLS.length).toBe(10);
+    it('should have 11 tools in ALL_TOOLS', () => {
+      expect(ALL_TOOLS.length).toBe(11);
     });
 
     it('dronesCategory should be defined', () => {

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

@@ -0,0 +1,160 @@
+export class RaceAudioSynthesizer {
+  private audioCtx: AudioContext | null = null;
+  private enabled = true;
+  private activeTimeouts: number[] = [];
+
+  constructor(enabled = true) {
+    this.enabled = enabled;
+  }
+
+  public setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+    if (!enabled) {
+      this.cancelPendingTones();
+    }
+  }
+
+  public isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  private initContext(): AudioContext | null {
+    if (typeof window === 'undefined') {
+      return null;
+    }
+    if (!this.audioCtx) {
+      const AudioContextClass = window.AudioContext || (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+      if (AudioContextClass) {
+        this.audioCtx = new AudioContextClass();
+      }
+    }
+    if (this.audioCtx && this.audioCtx.state === 'suspended') {
+      this.audioCtx.resume().catch(() => {});
+    }
+    return this.audioCtx;
+  }
+
+  public playTone(frequency: number, durationSeconds: number, type: OscillatorType = 'sine', peakGain = 0.25): void {
+    if (!this.enabled) {
+      return;
+    }
+    const ctx = this.initContext();
+    if (!ctx) {
+      return;
+    }
+
+    try {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+
+      osc.type = type;
+      osc.frequency.setValueAtTime(frequency, ctx.currentTime);
+
+      gain.gain.setValueAtTime(0.0001, ctx.currentTime);
+      gain.gain.exponentialRampToValueAtTime(peakGain, ctx.currentTime + 0.02);
+      gain.gain.exponentialRampToValueAtTime(0.0001, ctx.currentTime + durationSeconds);
+
+      osc.connect(gain);
+      gain.connect(ctx.destination);
+
+      osc.start(ctx.currentTime);
+      osc.stop(ctx.currentTime + durationSeconds + 0.05);
+    } catch {}
+  }
+
+  public playFaiCountdown(onTick: (label: string) => void, onGo: () => void): void {
+    this.cancelPendingTones();
+    const steps = ['3', '2', '1'];
+
+    if (!this.enabled) {
+      steps.forEach((label, idx) => {
+        const tid = window.setTimeout(() => onTick(label), idx * 1000);
+        this.activeTimeouts.push(tid);
+      });
+      const goTid = window.setTimeout(() => {
+        onTick('Go');
+        onGo();
+      }, steps.length * 1000);
+      this.activeTimeouts.push(goTid);
+      return;
+    }
+
+    this.initContext();
+
+    steps.forEach((label, idx) => {
+      const tid = window.setTimeout(() => {
+        this.playTone(440, 0.18, 'sine', 0.3);
+        onTick(label);
+      }, idx * 1000);
+      this.activeTimeouts.push(tid);
+    });
+
+    const goTid = window.setTimeout(() => {
+      this.playTone(880, 0.45, 'sawtooth', 0.4);
+      onTick('Go');
+      onGo();
+    }, steps.length * 1000);
+    this.activeTimeouts.push(goTid);
+  }
+
+  public playCountdownSequence(onGo: () => void, onTick?: (label: string) => void): void {
+    this.playFaiCountdown(
+      (label) => {
+        onTick?.(label);
+      },
+      () => {
+        onGo();
+      }
+    );
+  }
+
+  public playLapSound(isFastest = false): void {
+    if (isFastest) {
+      this.playFastestLapChime();
+    } else {
+      this.playLapChirp();
+    }
+  }
+
+  public playLapChirp(): void {
+    if (!this.enabled) {
+      return;
+    }
+    this.playTone(660, 0.06, 'sine', 0.25);
+    const tid = window.setTimeout(() => {
+      this.playTone(880, 0.08, 'sine', 0.3);
+    }, 70);
+    this.activeTimeouts.push(tid);
+  }
+
+  public playFastestLapChime(): void {
+    if (!this.enabled) {
+      return;
+    }
+    const notes = [523.25, 659.25, 783.99, 1046.5];
+    notes.forEach((freq, idx) => {
+      const tid = window.setTimeout(() => {
+        this.playTone(freq, 0.12, 'triangle', 0.35);
+      }, idx * 75);
+      this.activeTimeouts.push(tid);
+    });
+  }
+
+  public playFinishFanfare(): void {
+    if (!this.enabled) {
+      return;
+    }
+    const notes = [440, 554.37, 659.25, 880];
+    notes.forEach((freq, idx) => {
+      const tid = window.setTimeout(() => {
+        this.playTone(freq, 0.22, 'triangle', 0.3);
+      }, idx * 110);
+      this.activeTimeouts.push(tid);
+    });
+  }
+
+  public cancelPendingTones(): void {
+    this.activeTimeouts.forEach((tid) => clearTimeout(tid));
+    this.activeTimeouts = [];
+  }
+}

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

@@ -0,0 +1,6 @@
+---
+import { Bibliography as BibliographyComponent } from "@jjlmoya/utils-shared";
+import { bibliography } from "./bibliography";
+---
+
+<BibliographyComponent links={bibliography} />

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

@@ -0,0 +1,14 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Fédération Aéronautique Internationale (FAI) - CIAM Sporting Code Section 4: F9U Drone Racing World Championship Regulations',
+    url: 'https://www.fai.org/sites/default/files/2026-06/CIAM-F9-Drones-2026-06-01.pdf',
+  },
+  {
+    name: 'MultiGP Drone Racing Championship - Official Track Design and Lap Timing Specifications',
+    url: 'https://www.multigp.com/class-specifications/',
+  }
+];
+
+export const BIBLIOGRAPHY_ITEMS = bibliography;

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

@@ -0,0 +1,20 @@
+import type { FpvDroneLapTimerUI } from './ui';
+import { LapTimerSession } from './controller';
+
+export function initializeLapTimer(root: HTMLElement, ui: FpvDroneLapTimerUI): () => void {
+  const session = new LapTimerSession(root, ui);
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.code === 'Space') {
+      const tag = document.activeElement?.tagName;
+      if (tag !== 'INPUT' && tag !== 'BUTTON') {
+        e.preventDefault();
+        session.recordLap();
+      }
+    }
+  };
+  window.addEventListener('keydown', onKeyDown);
+  return () => {
+    session.destroy();
+    window.removeEventListener('keydown', onKeyDown);
+  };
+}

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

@@ -0,0 +1,136 @@
+---
+import type { FpvDroneLapTimerUI } from './ui';
+import { DEFAULT_CONFIG, calculateSessionMetrics, computeLapRecords } from './logic';
+import { renderTelemetryScene, renderLapTable } from './dom-views';
+import './fpv-drone-lap-timer.css';
+
+interface Props {
+  ui: FpvDroneLapTimerUI;
+}
+
+const { ui } = Astro.props;
+
+const initialLaps = computeLapRecords([], DEFAULT_CONFIG.trackLengthM, DEFAULT_CONFIG.batteryCapacityMah);
+const initialMetrics = calculateSessionMetrics([], DEFAULT_CONFIG.trackLengthM, DEFAULT_CONFIG.batteryCapacityMah);
+const initialTelemetryHtml = renderTelemetryScene({
+  metrics: initialMetrics,
+  laps: initialLaps,
+  currentLapNumber: 1,
+  targetLaps: DEFAULT_CONFIG.targetLaps,
+  status: 'idle',
+  ui,
+});
+const initialTableHtml = renderLapTable(initialLaps, ui);
+---
+
+<div class="fpv-lap-timer-card" data-fpv-lap-timer>
+  <script is:inline type="application/json" data-fpv-lap-timer-ui set:html={JSON.stringify(ui)}></script>
+
+  <aside class="fpv-lap-timer-sidebar" aria-labelledby="fpv-lap-timer-setup-title">
+    <div class="fpv-lap-timer-sidebar-header">
+      <span class="fpv-lap-timer-kicker">OSD CONFIG</span>
+      <h3 id="fpv-lap-timer-setup-title" class="fpv-lap-timer-sidebar-title">{ui.setupHeading}</h3>
+    </div>
+
+    <div class="fpv-lap-timer-presets" role="group" aria-label="Session Presets">
+      <button type="button" class="fpv-lap-timer-preset active" data-preset="multigp">{ui.presetMultiGpLabel}</button>
+      <button type="button" class="fpv-lap-timer-preset" data-preset="whoop">{ui.presetWhoopLabel}</button>
+      <button type="button" class="fpv-lap-timer-preset" data-preset="sprint">{ui.presetSprintLabel}</button>
+    </div>
+
+    <div class="fpv-lap-timer-fields">
+      <label class="fpv-lap-timer-field">
+        <span class="fpv-lap-timer-field-label">{ui.trackLengthLabel} <small>({ui.trackLengthUnit})</small></span>
+        <input id="fpv-lap-timer-track-length" type="number" min="10" max="2000" step="5" value={DEFAULT_CONFIG.trackLengthM} />
+      </label>
+
+      <label class="fpv-lap-timer-field">
+        <span class="fpv-lap-timer-field-label">{ui.targetLapsLabel} <small>({ui.targetLapsUnit})</small></span>
+        <input id="fpv-lap-timer-target-laps" type="number" min="0" max="50" step="1" value={DEFAULT_CONFIG.targetLaps} />
+      </label>
+
+      <label class="fpv-lap-timer-field">
+        <span class="fpv-lap-timer-field-label">{ui.batteryCapacityLabel} <small>({ui.batteryCapacityUnit})</small></span>
+        <input id="fpv-lap-timer-battery" type="number" min="100" max="10000" step="50" value={DEFAULT_CONFIG.batteryCapacityMah} />
+      </label>
+
+      <label class="fpv-lap-timer-field">
+        <span class="fpv-lap-timer-field-label">{ui.debounceThresholdLabel} <small>({ui.debounceThresholdUnit})</small></span>
+        <input id="fpv-lap-timer-debounce" type="number" min="1" max="10" step="0.5" value="3.0" />
+      </label>
+
+      <label class="fpv-lap-timer-checkbox">
+        <input id="fpv-lap-timer-sound" type="checkbox" checked />
+        <span>{ui.soundEnabledLabel}</span>
+      </label>
+    </div>
+
+    <div class="fpv-lap-timer-specs-card">
+      <div class="fpv-lap-timer-spec-row">
+        <span>{ui.completedLapsLabel}</span>
+        <strong id="fpv-lap-timer-stat-completed" class="font-mono">0</strong>
+      </div>
+      <div class="fpv-lap-timer-spec-row">
+        <span>{ui.averageLapHeading}</span>
+        <strong id="fpv-lap-timer-stat-avg" class="font-mono">--</strong>
+      </div>
+      <div class="fpv-lap-timer-spec-row">
+        <span>{ui.estimatedSpeedHeading}</span>
+        <strong id="fpv-lap-timer-stat-speed" class="font-mono">--</strong>
+      </div>
+    </div>
+  </aside>
+
+  <div class="fpv-lap-timer-stage">
+    <section class="fpv-lap-timer-hud" aria-label="Race Stopwatch Display">
+      <div class="fpv-lap-timer-hud-bar">
+        <div class="fpv-lap-timer-chip fpv-lap-timer-status-chip">
+          <span class="fpv-lap-timer-status-dot"></span>
+          <span id="fpv-lap-timer-status-text">{ui.statusIdle}</span>
+        </div>
+        <div class="fpv-lap-timer-chip fpv-lap-timer-lap-chip">
+          <span id="fpv-lap-timer-hud-lap">{ui.lapNumberPrefix} 1 / {DEFAULT_CONFIG.targetLaps}</span>
+        </div>
+      </div>
+
+      <div class="fpv-lap-timer-digits font-mono" aria-live="off">00:00.000</div>
+      <div class="fpv-lap-timer-hud-sublabel">{ui.currentLapHeading}</div>
+    </section>
+
+    <section class="fpv-lap-timer-trigger-box" aria-label="Timing Controls">
+      <button type="button" class="fpv-lap-timer-giant-btn" disabled aria-keyshortcuts="Space">
+        <span class="fpv-lap-timer-btn-caption">{ui.recordLapButton}</span>
+      </button>
+      <div class="fpv-lap-timer-hint">{ui.spacebarHint}</div>
+
+      <div class="fpv-lap-timer-controls">
+        <button type="button" class="fpv-lap-timer-btn fpv-lap-timer-btn-primary" id="fpv-lap-timer-btn-start">{ui.startCountdownButton}</button>
+        <button type="button" class="fpv-lap-timer-btn" id="fpv-lap-timer-btn-pause" style="display: none;">{ui.pauseTimerButton}</button>
+        <button type="button" class="fpv-lap-timer-btn" id="fpv-lap-timer-btn-reset">{ui.resetTimerButton}</button>
+      </div>
+    </section>
+
+    <section class="fpv-lap-timer-telemetry-mount" set:html={initialTelemetryHtml}></section>
+
+    <section class="fpv-lap-timer-table-mount" set:html={initialTableHtml}></section>
+
+    <footer class="fpv-lap-timer-footer">
+      <button type="button" class="fpv-lap-timer-btn" id="fpv-lap-timer-export-csv">{ui.exportCsvButton}</button>
+      <button type="button" class="fpv-lap-timer-btn" id="fpv-lap-timer-copy-summary">{ui.copySummaryButton}</button>
+      <span class="fpv-lap-timer-notice" id="fpv-lap-timer-copy-notice" style="display: none;">{ui.copiedNotice}</span>
+    </footer>
+  </div>
+</div>
+
+<script>
+  import { initializeLapTimer } from './controller';
+
+  const root = document.querySelector<HTMLElement>('[data-fpv-lap-timer]');
+  const scriptData = root?.querySelector<HTMLScriptElement>('[data-fpv-lap-timer-ui]');
+  if (root && scriptData) {
+    try {
+      const parsedUi = JSON.parse(scriptData.textContent || '{}');
+      initializeLapTimer(root, parsedUi);
+    } catch {}
+  }
+</script>

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

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { FPV_DRONE_LAP_TIMER_TOOL, fpvDroneLapTimer } from './index';
+
+describe('fpv-drone-lap-timer contract suite', () => {
+  it('exposes a valid tool definition with lazy component loaders', () => {
+    expect(FPV_DRONE_LAP_TIMER_TOOL.entry).toBe(fpvDroneLapTimer);
+    expect(typeof FPV_DRONE_LAP_TIMER_TOOL.Component).toBe('function');
+    expect(typeof FPV_DRONE_LAP_TIMER_TOOL.SEOComponent).toBe('function');
+    expect(typeof FPV_DRONE_LAP_TIMER_TOOL.BibliographyComponent).toBe('function');
+  });
+
+  it('loads English locale content without errors', async () => {
+    expect(typeof fpvDroneLapTimer.i18n.en).toBe('function');
+    const content = await fpvDroneLapTimer.i18n.en!();
+    expect(content.slug).toBe('fpv-drone-lap-timer');
+    expect(content.title).toBeDefined();
+    expect(content.ui).toBeDefined();
+    expect(content.seo.length).toBeGreaterThanOrEqual(4);
+    expect(content.faq.length).toBeGreaterThanOrEqual(4);
+    expect(content.howTo.length).toBeGreaterThanOrEqual(3);
+    expect(content.bibliography.length).toBeGreaterThanOrEqual(2);
+    expect(content.schemas.length).toBeGreaterThanOrEqual(3);
+  });
+});