@mearman/doppler 0.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,98 @@
+# Doppler
+
+Offline and real-time aircraft Doppler audio geolocation: a TypeScript library, a CLI (`doppler`) and an installable PWA (Progressive Web App) that locate where an audio recording was made from the Doppler shifts of aircraft flyovers.
+
+Stack: TypeScript (ESM only), Zod, React with Mantine and vanilla-extract (site), tsdown (library and CLI build), esbuild (site build), Vitest, Playwright, semantic-release. pnpm manages packages.
+
+## Getting started
+
+Prerequisites: Node 22 or later, and pnpm at the version in `packageManager` in `package.json` (Corepack installs it).
+
+```sh
+pnpm install
+```
+
+`pnpm-workspace.yaml` is not a real workspace. It holds pnpm settings only:
+
+- `saveExact` writes exact versions. Add and upgrade packages with `pnpm add`, never by editing `package.json`.
+- `minimumReleaseAge` rejects any release younger than seven days. An install that fails as "too new" needs an older version, or `minimumReleaseAgeExclude` for a package you own.
+- `allowBuilds` permits the `esbuild` install script only. Every other dependency install script is blocked.
+
+No environment variables are required to build, test or run. The scheduled ADS-B workflow reads `HF_TOKEN` from CI secrets.
+
+## Build, test, and lint
+
+| Task | Command |
+| --- | --- |
+| Build library (`dist/`) and CLI (`dist-cli/`) | `pnpm build` |
+| Build the PWA into `site-dist/` | `pnpm site` |
+| Typecheck (five tsconfig projects) | `pnpm typecheck` |
+| Lint, as CI runs it | `pnpm lint:check` |
+| Lint and auto-fix | `pnpm lint` |
+| Unit and integration tests | `pnpm test` |
+| Browser tests (builds first) | `pnpm test:e2e` |
+
+Run one test file or one test:
+
+```sh
+pnpm vitest run src/physics/geo.unit.test.ts
+pnpm vitest run src/physics/geo.unit.test.ts -t "test name" --coverage.enabled=false
+pnpm exec playwright test -g "test name"
+```
+
+Coverage is on by default in `vitest.config.ts`. Add `--coverage.enabled=false` to skip it. `playwright test` serves `site-dist/` and does not rebuild it, so run `pnpm build && pnpm site` first after a source change.
+
+Run the CLI from source or from the build:
+
+```sh
+pnpm tsx cli/doppler.ts locate fixtures/colsto-flyover-36m.wav --json
+node dist-cli/doppler.mjs --help
+```
+
+CI (`.github/workflows/ci.yml`) runs, in order: typecheck, lint, tests, build, `publint` plus `attw --pack --profile esm-only` (package export checks), site build, Playwright. `pnpm prepublishOnly` runs the same gates locally.
+
+## Architecture
+
+The repository has four consumers of one core:
+
+- **`src/`** is the isomorphic core. It must run in Node, browsers and Web Workers. `tsconfig.json` sets `types: []` with a `WebWorker` lib, so a Node-only global in `src/` fails to compile there. It excludes `src/node/`, `src/browser/` and `*.test.ts`, which other tsconfig projects check.
+- **`src/node/`** and **`src/browser/`** are the platform edges (file system, ADS-B streaming, microphone capture, `localStorage` session storage). Each has an `entry.ts` that re-exports `src/index.ts` plus its own surface. These are the package exports `@mearman/doppler`, `@mearman/doppler/node` and `@mearman/doppler/browser`.
+- **`cli/doppler.ts`** is the CLI. It imports from `../src` directly and is bundled to `dist-cli/doppler.mjs`, the package `bin`.
+- **`site/`** is the PWA. `site/build.ts` bundles `site/client/app.tsx`, the solver Web Worker and the service worker with esbuild. `site/build-site.ts` writes `index.html`, the manifest and `precache.json`. `site/precache.ts` appends a SHA-256 digest of the precached files to the manifest version, so the service worker refreshes its cache whenever any precached byte changes.
+
+Data flows through four layers inside `src/`, each importing only from the layers above it in this list:
+
+1. `schemas.ts` (with `define.ts`, `own.ts`, `record.ts`): Zod schemas and the types inferred from them. All data that crosses a boundary (JSON files, worker messages, stored sessions) is parsed with them.
+2. `physics/`: geodesy (`geo.ts`), atmosphere and speed of sound, retarded-time closest-point-of-approach, Ramer-Douglas-Peucker trajectory simplification (`rdp.ts`) and algebra helpers.
+3. `dsp/`: FFT, decimation, spectrogram, ridge tracking that turns a spectrogram into Doppler observations, dechirp, and side channels such as ENF (Electric Network Frequency) detection and WAV encoding.
+4. `solver/`: the constellation index of known flight segments, Gauss-Newton refinement of the observer position, and `DopplerSessionEngine` (`session.ts`), which accumulates observations across listening episodes into a log-posterior over location hypotheses.
+
+`bundled.ts` holds a synthetic reference dataset (Oxford, UK) used as the default dataset by the CLI and the site worker. The browser runs the engine inside `site/client/solver-worker.ts`, which the UI drives through typed request and reply messages.
+
+## Conventions
+
+- **Schema-attached guards.** Define a boundary schema as `export const XSchema = define(z.object({...}))` and export the type under the bare name (`export type X = z.infer<typeof XSchema>`), so the value and the type never share a name. `define` adds `.is()` by defining the property on the schema itself, since a spread copy of a Zod 4 schema loses its prototype methods.
+- **Records keyed by data** use `recordOf` (rejects `__proto__` keys) for parsing and `getOwn` for reading. A plain `record[key]` read finds inherited properties such as `constructor`.
+- **Strict TypeScript.** `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess` are on, so an optional field that you pass through is typed `T | undefined` and an indexed read must be narrowed. Build option objects with conditional spreads, as `solver-worker.ts` does.
+- **File suffixes decide the runner.** `*.unit.test.ts` and `*.integration.test.ts` run in Vitest. `*.browser.ts` under `site/e2e/` runs in Playwright only. Unit tests sit next to the source they test.
+- **Lint comes from `@exadev/eslint-config`.** Overrides live in `eslint.config.ts` with a reason for each. Add a files-scoped override there with a reason, not an inline `eslint-disable`. The magic-number rule is off for numerical code (`physics`, `dsp`, `solver`, tests, `site`, `cli`) and on elsewhere.
+- **Code comments** state the invariant or the reason. Public functions carry a doc comment with `@param` and `@returns`.
+- **Git hooks** are in `.husky/` and are installed by `pnpm install` (the `prepare` script). `pre-commit` lints staged `.ts` and `.tsx` files with `--fix`. `commit-msg` runs commitlint. `pre-push` runs typecheck, lint, tests and build, which is CI without the browser tests. Never bypass them with `--no-verify`: fix the failure.
+- **Commits** follow Conventional Commits. The allowed types and their release levels are the `commitTypes` list in `release.config.ts`, which `commitlint.config.ts` also reads. Every listed type releases at least a patch, `docs`, `test`, `chore` and `ci` included. `feat` releases a minor and a breaking change releases a major.
+- Use British English in prose and comments.
+
+## Non-obvious behaviour
+
+- **External fixture audio is not in git.** `fixtures/*.wav`, `*.m4a` and `*.mp3` are gitignored (the full recording is about 300 MB). Tests against downloaded fixtures guard with `if (!existsSync(path)) { return; }`, while a built-in synthetic benchmark executes and verifies the complete inversion pipeline in CI and clean checkouts. Put recordings in `fixtures/` for full offline forensics verification.
+- **`pnpm test:e2e` needs a free port 4174** and does not reuse a running server (`reuseExistingServer: false`). Chromium runs with fake audio devices so that the microphone permission prompt does not block.
+- **The CLI bundle does not depend on `dist/`.** `tsdown.config.ts` marks `@mearman/doppler` and `@mearman/doppler/node` external for the CLI, but `cli/doppler.ts` imports `../src` directly, so the two builds are independent.
+- **The CLI version is read from `package.json`** via `import.meta.url`, ensuring CLI output (`doppler -v`) stays synchronized with semantic-release without hardcoded literals.
+- **`incremental-adsb.yml` builds a day's dataset but does not publish it.** It streams the `adsb.lol` `globe_history` release for the target day through `doppler ingest --input -` and writes `YYYY-MM-DD.dataset.json` on the runner. Where the file is stored is not configured yet.
+- **Real ADS-B data enters through `doppler ingest`.** It accepts a raw `adsb.lol` or `tar1090` trace file, a directory of them, ready-made segments, or (`--input -`) the day's tar on standard input, with `--bbox` to keep one region. Without `--dataset`, `locate` and the PWA match against the three synthetic flyovers in `src/bundled.ts` only.
+- **Workflows pin actions differently.** `pages.yml` pins actions by commit SHA. `ci.yml` and `incremental-adsb.yml` use version tags. Keep the pins in the style of the file you edit.
+
+## References
+
+- `release.config.ts`: release rules and the commit-type list.
+- `eslint.config.ts`: lint overrides and the reason for each.
+- `.github/workflows/`: CI, GitHub Pages deploy and the scheduled ADS-B pipeline.

package/dist/browser/entry.d.ts

@@ -0,0 +1,105 @@
+import { $ as computeSegmentCpa, $t as QuietIntervalSchema, A as synthesizeMultiFlyoverAudio, At as ConstellationEntry, B as SpectrogramOptions, Bt as GeoPoint3D, C as formatConstellationKey, Ct as define, D as SyntheticAudioConfig, Dt as AircraftCategorySchema, E as encodeWavPcm16, Et as AircraftCategory, F as extractDopplerObservations, Ft as DopplerObservationSchema, G as downmixToMono, Gt as LinearFlightSegmentSchema, H as computeSingleSpectrogramFrame, Ht as HypothesisMatch, I as ComputedSingleFrame, It as DopplerRidgePoint, J as fft, Jt as LocationHypothesis, K as ComplexSpectrum, Kt as ListeningEpisode, L as DopplerSpectrogram, Lt as DopplerRidgePointSchema, M as DechirpScoreResult, Mt as DopplerDataset, N as scoreByEmissionDechirping, Nt as DopplerDatasetSchema, O as detectEnfSignature, Ot as AsymptoticKinematics, P as RidgeTrackerOptions, Pt as DopplerObservation, Q as SynthesizeCurveOptions, Qt as QuietInterval, R as SingleFrameOptions, Rt as EnfSignature, S as expandConstellationQueryKeys, St as getOwn, T as decodeWavBytes, Tt as AdsbPingSchema, U as decimateAudioStream, Ut as HypothesisMatchSchema, V as computeDopplerSpectrogram, Vt as GeoPoint3DSchema, W as designLowPassFirKernel, Wt as LinearFlightSegment, X as simplifyTrajectory4D, Xt as LocationSession, Y as TraceMetadata, Yt as LocationHypothesisSchema, Z as RetardedAcousticPoint, Zt as LocationSessionSchema, _ as unmatchedObservationLogPenalty, _t as geoToLocalEnu, a as BUNDLED_SEGMENTS, at as DEFAULT_SOUND_SPEED_MPS, b as QUERY_BUCKET_SPAN, bt as slantDistanceMeters, c as DopplerSessionEngine, ct as DEFAULT_ELLIPSE_SEGMENTS, d as ObservationSegmentPair, dt as HALF_TURN_DEG, en as SearchConstraints, et as solveRetardedDelaySec, f as RefineCoordinateOptions, ft as HorizontalEllipse, g as refineObserverCoordinateGaussNewton, gt as geoToEcef, h as fisherToConfidenceEllipse95, ht as encodeSpatialCell, i as BUNDLED_GROUND_TRUTH, it as AtmosphereState, j as DechirpOptions, jt as ConstellationEntrySchema, k as estimateTempFromCricketChirpsCelsius, kt as AsymptoticKinematicsSchema, l as SessionEngineOptions, lt as DEFAULT_SPATIAL_RESOLUTION, m as SLANT_SIGMA_FLOOR_METERS, mt as ellipseOutline, n as BUNDLED_DATASET, nn as Vector3D, nt as DopplerCurveMeasurement, o as generateBundledReferenceAudio, ot as effectiveRaySoundSpeedMps, p as RefinedLocationResult, pt as decodeSpatialCellCenter, q as computeHannPowerSpectrumDb, qt as ListeningEpisodeSchema, r as BUNDLED_DEM_GRID, rn as Vector3DSchema, rt as extractAsymptoticKinematics, s as generateBundledReferenceWavBytes, st as speedOfSoundAtTempMps, t as BUNDLED_CONSTELLATIONS, tn as SearchConstraintsSchema, tt as synthesizeRetardedDopplerCurve, u as MAX_ALONG_TRACK_WIND_MPS, ut as FULL_TURN_DEG, v as BuildConstellationOptions, vt as interpolateTerrainElevationMeters, w as matchesSearchConstraints, wt as AdsbPing, x as buildConstellationIndex, xt as recordOf, y as CandidateConstraintTarget, yt as localEnuToGeo, z as SpectrogramFrame, zt as EnfSignatureSchema } from "../index-TOQF-n8K.js";
+/**
+ * Decodes an audio or video file's soundtrack into mono samples. WAV decodes in-process at its own sample rate; every other container goes through the browser's decoder, so the supported formats are the ones the browser plays.
+ * @param buffer - The file's bytes. A browser decode detaches this buffer.
+ * @returns Mono samples and their sample rate in Hz.
+ * @throws When the bytes are not a WAV file and the browser cannot decode them.
+ */
+export declare function decodeAudioFile(buffer: Readonly<ArrayBuffer>): Promise<{
+  readonly samples: Float32Array;
+  readonly sampleRateHz: number;
+}>;
+/**
+ * Event callbacks emitted during continuous or episodic microphone listening.
+ */
+export interface MicMonitorCallbacks {
+  readonly onSpectrogramFrame?: (frame: Readonly<ComputedSingleFrame>) => void;
+  readonly onNoiseUpdate?: (noiseFloorDb: number, noisePolluted: boolean) => void;
+  readonly onObservationDetected?: (observation: Readonly<DopplerObservation>) => void;
+  readonly onError?: (error: Readonly<Error>) => void;
+}
+/**
+ * Live audio monitor that captures raw microphone audio without WebRTC voice filters,
+ * applies streaming 24x decimation to 2,000 Hz, tracks in-band noise pollution, and extracts
+ * aircraft Doppler S-curves in real time.
+ * Capture runs in an audio worklet loaded from `mic-capture.worklet.js`, which must be served next to the module that contains this class.
+ */
+export declare class MicMonitor {
+  private audioCtx;
+  private mediaStream;
+  private captureNode;
+  private sampleBuffer;
+  private isListening;
+  private isPaused;
+  private episodeId;
+  private episodeStartEpochSec;
+  private actualSampleRateHz;
+  private readonly callbacks;
+  constructor(callbacks?: MicMonitorCallbacks);
+  /**
+   * Starts microphone capture with all browser noise suppression, echo cancellation, and AGC explicitly disabled.
+   * @param episodeId - Identifier for the active listening episode.
+   */
+  start(episodeId: string): Promise<void>;
+  /**
+   * Temporarily pauses listening (e.g. user pauses or moves through a high-noise area).
+   */
+  pause(): void;
+  /**
+   * Resumes listening from a paused state.
+   */
+  resume(): void;
+  /**
+   * Stops microphone capture, releases the hardware audio stream, and flushes remaining buffer.
+   */
+  stop(): void;
+  /**
+   * Processes a raw 48 kHz chunk, decimates it to 2,000 Hz, appends it to the rolling window, and checks for Doppler ridges.
+   */
+  private handleRawAudioChunk;
+}
+/**
+ * Saves a LocationSession snapshot into local browser storage.
+ * @param session - The LocationSession to save.
+ */
+export declare function saveSessionToStorage(session: Readonly<LocationSession>): void;
+/**
+ * Loads all saved sessions from browser storage.
+ * @returns The stored sessions, or an empty array when nothing is stored or the stored value is not a list of valid sessions.
+ */
+export declare function loadSessionsFromStorage(): LocationSession[];
+/**
+ * Loads a specific session by ID from browser storage.
+ * @param sessionId - Session identifier string.
+ * @returns Found LocationSession or undefined.
+ */
+export declare function loadSessionById(sessionId: string): LocationSession | undefined;
+/**
+ * Deletes a session from browser storage.
+ * @param sessionId - Session identifier string.
+ */
+export declare function deleteSessionFromStorage(sessionId: string): void;
+/**
+ * Saves an uploaded or synced DopplerDataset into local browser storage.
+ * @param dataset - The DopplerDataset to save.
+ */
+export declare function saveCustomDataset(dataset: Readonly<DopplerDataset>): void;
+/**
+ * Loads any custom saved dataset from browser storage.
+ * @returns The saved DopplerDataset, or null when nothing is stored or the stored value is not a valid dataset.
+ */
+export declare function loadCustomDataset(): DopplerDataset | null;
+/**
+ * Exports a LocationSession as a downloadable JSON string.
+ * @param session - LocationSession to export.
+ * @returns Pretty-printed JSON string.
+ */
+export declare function exportSessionJson(session: Readonly<LocationSession>): string;
+/**
+ * Parses and validates an imported session JSON string.
+ * @param jsonText - Raw imported JSON text.
+ * @returns Parsed `LocationSession`.
+ * @throws When the text is not JSON or not a valid session.
+ */
+export declare function importSessionJson(jsonText: string): LocationSession;
+export { AdsbPing, AdsbPingSchema, AircraftCategory, AircraftCategorySchema, AsymptoticKinematics, AsymptoticKinematicsSchema, AtmosphereState, BUNDLED_CONSTELLATIONS, BUNDLED_DATASET, BUNDLED_DEM_GRID, BUNDLED_GROUND_TRUTH, BUNDLED_SEGMENTS, BuildConstellationOptions, CandidateConstraintTarget, ComplexSpectrum, ComputedSingleFrame, ConstellationEntry, ConstellationEntrySchema, DEFAULT_ELLIPSE_SEGMENTS, DEFAULT_SOUND_SPEED_MPS, DEFAULT_SPATIAL_RESOLUTION, DechirpOptions, DechirpScoreResult, DopplerCurveMeasurement, DopplerDataset, DopplerDatasetSchema, DopplerObservation, DopplerObservationSchema, DopplerRidgePoint, DopplerRidgePointSchema, DopplerSessionEngine, DopplerSpectrogram, EnfSignature, EnfSignatureSchema, FULL_TURN_DEG, GeoPoint3D, GeoPoint3DSchema, HALF_TURN_DEG, HorizontalEllipse, HypothesisMatch, HypothesisMatchSchema, LinearFlightSegment, LinearFlightSegmentSchema, ListeningEpisode, ListeningEpisodeSchema, LocationHypothesis, LocationHypothesisSchema, LocationSession, LocationSessionSchema, MAX_ALONG_TRACK_WIND_MPS, ObservationSegmentPair, QUERY_BUCKET_SPAN, QuietInterval, QuietIntervalSchema, RefineCoordinateOptions, RefinedLocationResult, RetardedAcousticPoint, RidgeTrackerOptions, SLANT_SIGMA_FLOOR_METERS, SearchConstraints, SearchConstraintsSchema, SessionEngineOptions, SingleFrameOptions, SpectrogramFrame, SpectrogramOptions, SynthesizeCurveOptions, SyntheticAudioConfig, TraceMetadata, Vector3D, Vector3DSchema, buildConstellationIndex, computeDopplerSpectrogram, computeHannPowerSpectrumDb, computeSegmentCpa, computeSingleSpectrogramFrame, decimateAudioStream, decodeSpatialCellCenter, decodeWavBytes, define, designLowPassFirKernel, detectEnfSignature, downmixToMono, effectiveRaySoundSpeedMps, ellipseOutline, encodeSpatialCell, encodeWavPcm16, estimateTempFromCricketChirpsCelsius, expandConstellationQueryKeys, extractAsymptoticKinematics, extractDopplerObservations, fft, fisherToConfidenceEllipse95, formatConstellationKey, generateBundledReferenceAudio, generateBundledReferenceWavBytes, geoToEcef, geoToLocalEnu, getOwn, interpolateTerrainElevationMeters, localEnuToGeo, matchesSearchConstraints, recordOf, refineObserverCoordinateGaussNewton, scoreByEmissionDechirping, simplifyTrajectory4D, slantDistanceMeters, solveRetardedDelaySec, speedOfSoundAtTempMps, synthesizeMultiFlyoverAudio, synthesizeRetardedDopplerCurve, unmatchedObservationLogPenalty };

package/dist/browser/entry.js

@@ -0,0 +1,276 @@
+import { $ as recordOf, A as downmixToMono, B as speedOfSoundAtTempMps, C as synthesizeMultiFlyoverAudio, D as computeSingleSpectrogramFrame, E as computeDopplerSpectrogram, F as solveRetardedDelaySec, G as decodeSpatialCellCenter, H as DEFAULT_SPATIAL_RESOLUTION, I as synthesizeRetardedDopplerCurve, J as geoToEcef, K as ellipseOutline, L as extractAsymptoticKinematics, M as fft, N as simplifyTrajectory4D, O as decimateAudioStream, P as computeSegmentCpa, Q as slantDistanceMeters, R as DEFAULT_SOUND_SPEED_MPS, S as estimateTempFromCricketChirpsCelsius, T as extractDopplerObservations, U as FULL_TURN_DEG, V as DEFAULT_ELLIPSE_SEGMENTS, W as HALF_TURN_DEG, X as interpolateTerrainElevationMeters, Y as geoToLocalEnu, Z as localEnuToGeo, _ as formatConstellationKey, _t as Vector3DSchema, a as BUNDLED_SEGMENTS, at as DopplerDatasetSchema, b as encodeWavPcm16, c as DopplerSessionEngine, ct as EnfSignatureSchema, d as fisherToConfidenceEllipse95, dt as LinearFlightSegmentSchema, et as getOwn, f as refineObserverCoordinateGaussNewton, ft as ListeningEpisodeSchema, g as expandConstellationQueryKeys, gt as SearchConstraintsSchema, h as buildConstellationIndex, ht as QuietIntervalSchema, i as BUNDLED_GROUND_TRUTH, it as ConstellationEntrySchema, j as computeHannPowerSpectrumDb, k as designLowPassFirKernel, l as MAX_ALONG_TRACK_WIND_MPS, lt as GeoPoint3DSchema, m as QUERY_BUCKET_SPAN, mt as LocationSessionSchema, n as BUNDLED_DATASET, nt as AircraftCategorySchema, o as generateBundledReferenceAudio, ot as DopplerObservationSchema, p as unmatchedObservationLogPenalty, pt as LocationHypothesisSchema, q as encodeSpatialCell, r as BUNDLED_DEM_GRID, rt as AsymptoticKinematicsSchema, s as generateBundledReferenceWavBytes, st as DopplerRidgePointSchema, t as BUNDLED_CONSTELLATIONS, tt as AdsbPingSchema, u as SLANT_SIGMA_FLOOR_METERS, ut as HypothesisMatchSchema, v as matchesSearchConstraints, vt as define, w as scoreByEmissionDechirping, x as detectEnfSignature, y as decodeWavBytes, z as effectiveRaySoundSpeedMps } from "../src-C4UucgwP.js";
+import { t as MS_PER_SECOND } from "../time-DWqWWgPL.js";
+import { t as MIC_CAPTURE_PROCESSOR_NAME } from "../mic-capture-protocol-CfYodiRN.js";
+import { z } from "zod";
+// src/browser/decode-audio.ts
+/** Rate the browser decodes compressed audio at. Analysis decimates to a far lower rate, so the exact value only has to cover the aircraft band. */
+const COMPRESSED_DECODE_RATE_HZ = 44100;
+/** Bytes of a RIFF four-character code, such as `RIFF` or `WAVE`. */
+const FOUR_CC_BYTES = 4;
+/** Bytes of the RIFF header's tag plus size field that precede the WAVE form type. */
+const RIFF_FORM_OFFSET = 8;
+function isWav(bytes) {
+	const tag = (offset) => String.fromCharCode(...bytes.subarray(offset, offset + FOUR_CC_BYTES));
+	return bytes.length >= 12 && tag(0) === "RIFF" && tag(RIFF_FORM_OFFSET) === "WAVE";
+}
+/**
+* Decodes an audio or video file's soundtrack into mono samples. WAV decodes in-process at its own sample rate; every other container goes through the browser's decoder, so the supported formats are the ones the browser plays.
+* @param buffer - The file's bytes. A browser decode detaches this buffer.
+* @returns Mono samples and their sample rate in Hz.
+* @throws When the bytes are not a WAV file and the browser cannot decode them.
+*/
+async function decodeAudioFile(buffer) {
+	if (isWav(new Uint8Array(buffer))) return decodeWavBytes(new Uint8Array(buffer));
+	const decoded = await new OfflineAudioContext(1, 1, COMPRESSED_DECODE_RATE_HZ).decodeAudioData(buffer);
+	const channels = Array.from({ length: decoded.numberOfChannels }, (_, channel) => decoded.getChannelData(channel));
+	return {
+		samples: downmixToMono(channels),
+		sampleRateHz: decoded.sampleRate
+	};
+}
+// src/browser/mic-monitor.ts
+/** Sample rate the captured audio is decimated to before analysis. The aircraft Doppler band lies far below its Nyquist frequency of 1,000 Hz. */
+const ANALYSIS_RATE_HZ = 2e3;
+/** Capture rate assumed until the `AudioContext` reports the real one, in Hz. */
+const DEFAULT_CAPTURE_RATE_HZ = 48e3;
+/** Samples of the rolling window at the analysis rate. */
+const MAX_WINDOW_SAMPLES = 60 * ANALYSIS_RATE_HZ;
+/** FFT length of both the live waterfall frame and the ridge-tracking spectrogram: a power of two giving about 1 Hz of resolution at the analysis rate. */
+const FFT_SIZE = 2048;
+/** Passband of the live waterfall frame, in Hz. */
+const LIVE_MIN_FREQ_HZ = 50;
+const LIVE_MAX_FREQ_HZ = 500;
+/** Analysis window that must be buffered before ridges are extracted: 4 s of audio at the analysis rate. */
+const RIDGE_MIN_WINDOW_SAMPLES = 8e3;
+/** Hop of the ridge-tracking spectrogram, in samples at the analysis rate. */
+const SPECTROGRAM_HOP_SAMPLES = 500;
+/** Smallest signal-to-noise ratio, in dB, at which a spectrogram ridge counts as an observation. */
+const MIN_RIDGE_SNR_DB = 6;
+/** Location of the audio worklet module, which the site build emits next to the bundle that contains this code. */
+const WORKLET_MODULE_URL = new URL("./mic-capture.worklet.js", import.meta.url);
+/**
+* Live audio monitor that captures raw microphone audio without WebRTC voice filters,
+* applies streaming 24x decimation to 2,000 Hz, tracks in-band noise pollution, and extracts
+* aircraft Doppler S-curves in real time.
+* Capture runs in an audio worklet loaded from `mic-capture.worklet.js`, which must be served next to the module that contains this class.
+*/
+var MicMonitor = class {
+	audioCtx = null;
+	mediaStream = null;
+	captureNode = null;
+	sampleBuffer = /* @__PURE__ */ new Float32Array(0);
+	isListening = false;
+	isPaused = false;
+	episodeId = "";
+	episodeStartEpochSec = 0;
+	actualSampleRateHz = DEFAULT_CAPTURE_RATE_HZ;
+	callbacks;
+	constructor(callbacks = {}) {
+		this.callbacks = callbacks;
+	}
+	/**
+	* Starts microphone capture with all browser noise suppression, echo cancellation, and AGC explicitly disabled.
+	* @param episodeId - Identifier for the active listening episode.
+	*/
+	async start(episodeId) {
+		if (this.isListening) return;
+		this.episodeId = episodeId;
+		this.episodeStartEpochSec = Math.floor(Date.now() / MS_PER_SECOND);
+		this.isListening = true;
+		this.isPaused = false;
+		this.sampleBuffer = /* @__PURE__ */ new Float32Array(0);
+		try {
+			this.mediaStream = await navigator.mediaDevices.getUserMedia({ audio: {
+				echoCancellation: false,
+				noiseSuppression: false,
+				autoGainControl: false
+			} });
+			this.audioCtx = new AudioContext();
+			this.actualSampleRateHz = this.audioCtx.sampleRate;
+			const source = this.audioCtx.createMediaStreamSource(this.mediaStream);
+			await this.audioCtx.audioWorklet.addModule(WORKLET_MODULE_URL);
+			this.captureNode = new AudioWorkletNode(this.audioCtx, MIC_CAPTURE_PROCESSOR_NAME, {
+				numberOfInputs: 1,
+				numberOfOutputs: 1,
+				outputChannelCount: [1],
+				channelCount: 1,
+				channelCountMode: "explicit"
+			});
+			this.captureNode.port.onmessage = (event) => {
+				if (!this.isListening || this.isPaused || !(event.data instanceof Float32Array)) return;
+				this.handleRawAudioChunk(event.data);
+			};
+			source.connect(this.captureNode);
+			this.captureNode.connect(this.audioCtx.destination);
+		} catch (err) {
+			this.stop();
+			const errorObj = err instanceof Error ? err : new Error(String(err));
+			this.callbacks.onError?.(errorObj);
+			throw errorObj;
+		}
+	}
+	/**
+	* Temporarily pauses listening (e.g. user pauses or moves through a high-noise area).
+	*/
+	pause() {
+		this.isPaused = true;
+	}
+	/**
+	* Resumes listening from a paused state.
+	*/
+	resume() {
+		this.isPaused = false;
+	}
+	/**
+	* Stops microphone capture, releases the hardware audio stream, and flushes remaining buffer.
+	*/
+	stop() {
+		this.isListening = false;
+		this.isPaused = false;
+		if (this.captureNode !== null) {
+			this.captureNode.port.onmessage = null;
+			this.captureNode.disconnect();
+			this.captureNode = null;
+		}
+		if (this.mediaStream !== null) {
+			for (const track of this.mediaStream.getTracks()) track.stop();
+			this.mediaStream = null;
+		}
+		if (this.audioCtx !== null) {
+			this.audioCtx.close();
+			this.audioCtx = null;
+		}
+		this.sampleBuffer = /* @__PURE__ */ new Float32Array(0);
+	}
+	/**
+	* Processes a raw 48 kHz chunk, decimates it to 2,000 Hz, appends it to the rolling window, and checks for Doppler ridges.
+	*/
+	handleRawAudioChunk(rawChunk) {
+		const decimated = decimateAudioStream(rawChunk, this.actualSampleRateHz, ANALYSIS_RATE_HZ);
+		const newBuf = new Float32Array(this.sampleBuffer.length + decimated.samples.length);
+		newBuf.set(this.sampleBuffer, 0);
+		newBuf.set(decimated.samples, this.sampleBuffer.length);
+		this.sampleBuffer = newBuf;
+		if (this.sampleBuffer.length > MAX_WINDOW_SAMPLES) this.sampleBuffer = this.sampleBuffer.slice(this.sampleBuffer.length - MAX_WINDOW_SAMPLES);
+		if (this.sampleBuffer.length >= FFT_SIZE) {
+			const windowSlice = this.sampleBuffer.subarray(this.sampleBuffer.length - FFT_SIZE);
+			const frameTimeSec = this.episodeStartEpochSec + this.sampleBuffer.length / ANALYSIS_RATE_HZ;
+			const liveFrame = computeSingleSpectrogramFrame(windowSlice, {
+				sampleRateHz: ANALYSIS_RATE_HZ,
+				fftSize: FFT_SIZE,
+				minFreqHz: LIVE_MIN_FREQ_HZ,
+				maxFreqHz: LIVE_MAX_FREQ_HZ,
+				timeSec: frameTimeSec
+			});
+			this.callbacks.onSpectrogramFrame?.(liveFrame);
+			this.callbacks.onNoiseUpdate?.(liveFrame.medianNoiseFloorDb, liveFrame.noisePolluted);
+		}
+		if (this.sampleBuffer.length >= RIDGE_MIN_WINDOW_SAMPLES) {
+			const spectrogram = computeDopplerSpectrogram(this.sampleBuffer, {
+				sampleRateHz: ANALYSIS_RATE_HZ,
+				startTimeSec: this.episodeStartEpochSec,
+				fftSize: FFT_SIZE,
+				hopSamples: SPECTROGRAM_HOP_SAMPLES
+			});
+			const observations = extractDopplerObservations(spectrogram, {
+				episodeId: this.episodeId,
+				minSnrDb: MIN_RIDGE_SNR_DB
+			});
+			for (const obs of observations) this.callbacks.onObservationDetected?.(obs);
+		}
+	}
+};
+// src/browser/storage.ts
+const SESSIONS_KEY = "doppler_sessions_v1";
+const DATASET_KEY = "doppler_custom_dataset_v1";
+/**
+* Saves a LocationSession snapshot into local browser storage.
+* @param session - The LocationSession to save.
+*/
+function saveSessionToStorage(session) {
+	try {
+		const list = loadSessionsFromStorage().filter((s) => s.id !== session.id);
+		list.unshift(session);
+		localStorage.setItem(SESSIONS_KEY, JSON.stringify(list));
+	} catch (err) {
+		console.warn("Failed to save session to localStorage:", err);
+	}
+}
+/**
+* Loads all saved sessions from browser storage.
+* @returns The stored sessions, or an empty array when nothing is stored or the stored value is not a list of valid sessions.
+*/
+function loadSessionsFromStorage() {
+	try {
+		const raw = localStorage.getItem(SESSIONS_KEY);
+		if (raw === null) return [];
+		const parsed = JSON.parse(raw);
+		return z.array(LocationSessionSchema).parse(parsed);
+	} catch {
+		return [];
+	}
+}
+/**
+* Loads a specific session by ID from browser storage.
+* @param sessionId - Session identifier string.
+* @returns Found LocationSession or undefined.
+*/
+function loadSessionById(sessionId) {
+	return loadSessionsFromStorage().find((s) => s.id === sessionId);
+}
+/**
+* Deletes a session from browser storage.
+* @param sessionId - Session identifier string.
+*/
+function deleteSessionFromStorage(sessionId) {
+	try {
+		const list = loadSessionsFromStorage().filter((s) => s.id !== sessionId);
+		localStorage.setItem(SESSIONS_KEY, JSON.stringify(list));
+	} catch (err) {
+		console.warn("Failed to delete session from localStorage:", err);
+	}
+}
+/**
+* Saves an uploaded or synced DopplerDataset into local browser storage.
+* @param dataset - The DopplerDataset to save.
+*/
+function saveCustomDataset(dataset) {
+	try {
+		localStorage.setItem(DATASET_KEY, JSON.stringify(dataset));
+	} catch (err) {
+		console.warn("Failed to save custom dataset to localStorage:", err);
+	}
+}
+/**
+* Loads any custom saved dataset from browser storage.
+* @returns The saved DopplerDataset, or null when nothing is stored or the stored value is not a valid dataset.
+*/
+function loadCustomDataset() {
+	try {
+		const raw = localStorage.getItem(DATASET_KEY);
+		if (raw === null) return null;
+		const parsed = JSON.parse(raw);
+		return DopplerDatasetSchema.parse(parsed);
+	} catch {
+		return null;
+	}
+}
+/**
+* Exports a LocationSession as a downloadable JSON string.
+* @param session - LocationSession to export.
+* @returns Pretty-printed JSON string.
+*/
+function exportSessionJson(session) {
+	return JSON.stringify(session, null, 2);
+}
+/**
+* Parses and validates an imported session JSON string.
+* @param jsonText - Raw imported JSON text.
+* @returns Parsed `LocationSession`.
+* @throws When the text is not JSON or not a valid session.
+*/
+function importSessionJson(jsonText) {
+	const parsed = JSON.parse(jsonText);
+	return LocationSessionSchema.parse(parsed);
+}
+export { AdsbPingSchema, AircraftCategorySchema, AsymptoticKinematicsSchema, BUNDLED_CONSTELLATIONS, BUNDLED_DATASET, BUNDLED_DEM_GRID, BUNDLED_GROUND_TRUTH, BUNDLED_SEGMENTS, ConstellationEntrySchema, DEFAULT_ELLIPSE_SEGMENTS, DEFAULT_SOUND_SPEED_MPS, DEFAULT_SPATIAL_RESOLUTION, DopplerDatasetSchema, DopplerObservationSchema, DopplerRidgePointSchema, DopplerSessionEngine, EnfSignatureSchema, FULL_TURN_DEG, GeoPoint3DSchema, HALF_TURN_DEG, HypothesisMatchSchema, LinearFlightSegmentSchema, ListeningEpisodeSchema, LocationHypothesisSchema, LocationSessionSchema, MAX_ALONG_TRACK_WIND_MPS, MicMonitor, QUERY_BUCKET_SPAN, QuietIntervalSchema, SLANT_SIGMA_FLOOR_METERS, SearchConstraintsSchema, Vector3DSchema, buildConstellationIndex, computeDopplerSpectrogram, computeHannPowerSpectrumDb, computeSegmentCpa, computeSingleSpectrogramFrame, decimateAudioStream, decodeAudioFile, decodeSpatialCellCenter, decodeWavBytes, define, deleteSessionFromStorage, designLowPassFirKernel, detectEnfSignature, downmixToMono, effectiveRaySoundSpeedMps, ellipseOutline, encodeSpatialCell, encodeWavPcm16, estimateTempFromCricketChirpsCelsius, expandConstellationQueryKeys, exportSessionJson, extractAsymptoticKinematics, extractDopplerObservations, fft, fisherToConfidenceEllipse95, formatConstellationKey, generateBundledReferenceAudio, generateBundledReferenceWavBytes, geoToEcef, geoToLocalEnu, getOwn, importSessionJson, interpolateTerrainElevationMeters, loadCustomDataset, loadSessionById, loadSessionsFromStorage, localEnuToGeo, matchesSearchConstraints, recordOf, refineObserverCoordinateGaussNewton, saveCustomDataset, saveSessionToStorage, scoreByEmissionDechirping, simplifyTrajectory4D, slantDistanceMeters, solveRetardedDelaySec, speedOfSoundAtTempMps, synthesizeMultiFlyoverAudio, synthesizeRetardedDopplerCurve, unmatchedObservationLogPenalty };

package/dist/browser/mic-capture.worklet.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/browser/mic-capture.worklet.js

@@ -0,0 +1,35 @@
+import { t as MIC_CAPTURE_PROCESSOR_NAME } from "../mic-capture-protocol-CfYodiRN.js";
+// src/browser/mic-capture.worklet.ts
+/**
+* Audio worklet module that batches the microphone's 128-frame render quanta into fixed-size chunks and posts each chunk to the main thread, which receives it as a `Float32Array` message.
+* It runs in the `AudioWorkletGlobalScope`, which the DOM library does not describe, so the two globals it uses are declared here. Nothing is exported: the module's only effect is registering the processor, and the main thread loads it with `audioWorklet.addModule`.
+*/
+/** Samples per posted chunk: about 85 ms at 48 kHz, a multiple of the 128-frame render quantum. */
+const CAPTURE_CHUNK_FRAMES = 4096;
+var MicCaptureProcessor = class extends AudioWorkletProcessor {
+	chunk = new Float32Array(CAPTURE_CHUNK_FRAMES);
+	filled = 0;
+	/**
+	* Appends one render quantum of the first input's first channel to the current chunk and posts the chunk, transferring its buffer, whenever it is full.
+	* @param inputs - The node's inputs; empty while nothing is connected.
+	* @returns True, so the processor stays alive for as long as the node does.
+	*/
+	process(inputs) {
+		const channel = inputs[0]?.[0];
+		if (channel === void 0) return true;
+		let offset = 0;
+		while (offset < channel.length) {
+			const count = Math.min(channel.length - offset, this.chunk.length - this.filled);
+			this.chunk.set(channel.subarray(offset, offset + count), this.filled);
+			this.filled += count;
+			offset += count;
+			if (this.filled === this.chunk.length) {
+				this.port.postMessage(this.chunk, [this.chunk.buffer]);
+				this.chunk = new Float32Array(CAPTURE_CHUNK_FRAMES);
+				this.filled = 0;
+			}
+		}
+		return true;
+	}
+};
+registerProcessor(MIC_CAPTURE_PROCESSOR_NAME, MicCaptureProcessor);