@aeroswarm/weather 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog: @aeroswarm/weather
+
+Format: [Keep a Changelog](https://keepachangelog.com/). Versioning: see [STABILITY.md](./STABILITY.md). Entries for
+0.1.1 to 0.4.0 were written afterwards from the git history; every one of them was released on 2026-11-02.
+
+## 0.4.0 (2026-11-02)
+
+- Release only: no source change since 0.3.0.
+
+## 0.3.0 (2026-11-02)
+
+### Added
+- Operational functions: `flightCategory` (FAA thresholds), `windComponents`, `runwayAdvice`, `evaluateMinima`,
+  `upcomingChanges`, `qnhTrend`, `stationOperations`, and runway helpers (`runwayFromHeading`, `runwayFromPolygon`).
+- Parsers for SIGMET, AIRMET, volcanic ash advisories (VAA), SNOWTAM and NIL reports.
+- Real-data test corpus (METAR/SPECI, 200+ TAF, SIGMET, VAA) and the fixtures README.
+
+### Behaviour
+- A TAF change group with a malformed period (for example `TEMPO 0214/02014`) is no longer merged silently into
+  the base conditions: it is dropped and reported in `Taf.unparsed`.
+- Several tokens that were silently ignored are now decoded or reported in `unparsed` (found by the real-data corpus).
+
+## 0.2.0 (2026-11-02)
+
+### Added
+- Real-data corpus and the first versions of the NIL, SIGMET, AIRMET, VAA and SNOWTAM parsers.
+
+## 0.1.5 (2026-11-02)
+
+### Added
+- Blend a model series with station reports (`WeatherStore.blendInto`).
+
+## 0.1.4 (2026-11-02)
+
+### Added
+- The `aeroswarm.weather-grid` v1 standard (`parseWeatherGridSeries`, `seriesFieldsAt`, `GRID_STANDARD.md`) and the
+  Open-Meteo adapter (`weatherGridFromOpenMeteo`, `latticePoints`).
+
+## 0.1.3 (2026-11-02)
+
+### Added
+- `WeatherStore`: ingest raw messages (including AFTN), manual override, `snapshotAt`, `timeline`.
+
+## 0.1.2 (2026-11-02)
+
+### Added
+- Gridded wind and scalar fields (`WindGrid`, `ScalarGrid`, sampling and interpolation).
+
+## 0.1.1 (2026-11-02)
+
+- First release: METAR/SPECI/TAF parsers, AFTN message extraction, animation parameters.

package/LIMITS.md

@@ -0,0 +1,51 @@
+# Limits of use
+
+Read this before putting weather data in front of operators.
+
+## Not an official source
+
+The packages decode and display weather messages. They are not a meteorological authority. METAR, SPECI, TAF and
+other messages issued by the responsible meteorological service are the official information, and a displayed
+value is only as good as the message it came from and the parser that read it.
+
+**Do not use output of these packages as the only basis for a safety decision** (take-off, landing, runway choice,
+diversion, closing an aerodrome). Verify against the official message. Operational helpers (flight category, runway
+advice, minima checks, alerts) are decision aids, and they assume the thresholds you configured are correct.
+
+## What the display shows
+
+- METAR and TAF describe one point (the aerodrome). Wind, cloud and rain drawn around an airport are a
+  representation of those reports, not the real position of clouds or rain.
+- A grid built from several stations is an interpolation between points; between stations it is an estimate.
+- A model forecast (Open-Meteo and others) is a model, with its own resolution and errors. Blending with reports
+  adjusts it near airports only.
+- With a tilted or 3D map the direction of wind on screen is an approximation.
+- There is no terrain or land mask: wind over mountains is not corrected.
+
+## What is read, and what is not verified
+
+Decoding is tested on real messages for METAR, SPECI, TAF (200+), international SIGMET and Tokyo VAAC
+advisories. These are supported but have **not** been checked against real messages, only against the ICAO
+description: AIRMET, NIL reports and SNOWTAM. Not covered by any test: Darwin VAAC, raw AFTN envelopes from a
+live circuit, raw BMKG messages. Tokens a parser does not understand are kept in the `unparsed` field of the
+result instead of being dropped; check it.
+
+Known simplifications:
+
+- METAR wind is in degrees true; runway headings are usually magnetic. Pass the magnetic variation, or the
+  crosswind is off by that angle.
+- Flight category follows the FAA definition (ICAO does not define one).
+- Runway headings taken from a polygon are the long axis of the shape, so they are only as accurate as the polygon.
+- Report time has no month or year; they are taken from the time you give as "received".
+
+## Data sources
+
+Each source has its own licence and limits; see `SOURCES.md` in `@aeroswarm/weather-sources`. In short: the free
+Open-Meteo endpoint is for non-commercial use only; BMKG access follows your agreement and the token is personal;
+aviationweather.gov data is public but limited to 100 requests a minute. Respect the limits, credit the source,
+and do not redistribute data you are not allowed to.
+
+## No warranty
+
+The software is provided as is, without warranty of any kind. (No licence file is included in the packages yet; the
+licence terms are set by the package owner.)

package/README.md

@@ -26,6 +26,13 @@ const snapshot = animationSnapshot({ observation: metar, forecast: taf, at: new
 METAR/TAF describe one point (the aerodrome), not a weather field, so the animation is a
 representation around the airport, not the real position of clouds or rain.
 
+## Documentation
+
+- [STABILITY.md](./STABILITY.md): what is public, semver policy, deprecation, the weather-grid standard.
+- [LIMITS.md](./LIMITS.md): **read before operational use**: not an official source, not for safety decisions
+  without verification, what is and is not verified.
+- [CHANGELOG.md](./CHANGELOG.md), [GRID_STANDARD.md](./GRID_STANDARD.md).
+
 ## Gridded fields
 
 `grid.ts` turns wind and scalar data into grids, whatever the source:

package/STABILITY.md

@@ -0,0 +1,62 @@
+# Stability and versioning
+
+Applies to `@aeroswarm/weather`, `@aeroswarm/weather-layer` and `@aeroswarm/weather-sources`.
+
+## What is public
+
+Public means exported from a documented entry point:
+
+| Package | Entry points |
+|---|---|
+| `@aeroswarm/weather` | `@aeroswarm/weather` |
+| `@aeroswarm/weather-layer` | `@aeroswarm/weather-layer`, `/react`, `/react-ui`, `/maplibre`, `/leaflet`, `/cesium`, `/ria`, and the stylesheet `/react-ui/weather-ui.css` (class names `aw-*` and variables `--aw-*`) |
+| `@aeroswarm/weather-sources` | `@aeroswarm/weather-sources` |
+
+Not public, may change in any release: anything you reach by importing a file inside `dist/`, anything not exported
+from an entry point, internal CSS selectors other than the documented `aw-*` classes, the exact wording of default
+UI texts, and the text of error messages.
+
+The runtime export names of every entry point are pinned by a test in each package (`src/api.test.ts` with a
+snapshot in `src/__snapshots__/`). Adding, removing or renaming an export fails the test until the snapshot is
+updated on purpose, so an API change cannot slip in unnoticed. The test covers exported names, not type shapes.
+
+## Versioning (semver)
+
+We follow [semver](https://semver.org/). All three packages are currently `0.x`, which semver treats as unstable;
+we hold ourselves to this stricter rule anyway:
+
+| Change | Release while `0.x` | Release from `1.0` |
+|---|---|---|
+| Bug fix, no API change | patch | patch |
+| New export, new option, new report type understood | minor | minor |
+| Removed or renamed export, changed signature, changed default | minor, listed under **Breaking** in the changelog | major |
+| Decoded values change because a parser bug was fixed | minor, listed under **Behaviour** in the changelog | minor |
+| Dependency range change, new peer dependency | minor, listed in the changelog | major if it forces consumers to upgrade |
+
+Every release has an entry in the package's `CHANGELOG.md`. A change that can break a consumer must say so there.
+Parser fixes can change what a message decodes to; that is intended, and is why it is called out separately.
+
+## Deprecation
+
+- A public export is deprecated before it is removed: it keeps working, is marked `@deprecated` in its type
+  declaration with the replacement, and is listed in the changelog.
+- While `0.x`: removed no earlier than the next minor release.
+- From `1.0`: removed no earlier than the next major release, and not within 90 days of the deprecation.
+
+## Peer dependencies
+
+`@aeroswarm/weather-layer` and `@aeroswarm/weather-sources` declare `@aeroswarm/weather` as a peer dependency
+(`>=0.4.0 <1.0.0`), so your app has one copy of it. Install it yourself next to them. React (18 or newer) is an
+optional peer of `@aeroswarm/weather-layer`, needed only for `/react` and `/react-ui`.
+
+## The weather-grid standard
+
+`aeroswarm.weather-grid` version 1 (see `GRID_STANDARD.md`) is frozen: the meaning of existing fields does not
+change, and a document valid today stays valid. Optional fields may be added in version 1. Anything that would
+invalidate an existing document is a new standard version (2), supported alongside 1 for at least one minor
+release of the packages. The parser rejects documents with an unknown version instead of guessing.
+
+## Migration
+
+Breaking changes are described in the changelog entry of the release that introduces them, with what to change.
+When a release needs more than a few lines, a `MIGRATION.md` section is added to the same package.

package/dist/api.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.test.d.ts.map

package/dist/api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../src/api.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,41 +1,44 @@
-{
-  "name": "@aeroswarm/weather",
-  "version": "0.3.0",
-  "description": "Decode raw AFTN/METAR/SPECI/TAF messages and turn them into animation parameters.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts",
-      "main": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "GRID_STANDARD.md"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --clean && tsc --emitDeclarationOnly",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
-    "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build",
-    "release": "release-it",
-    "release:dry": "release-it --dry-run",
-    "release:patch": "release-it patch --no-git.requireCleanWorkingDir",
-    "release:minor": "release-it minor --no-git.requireCleanWorkingDir",
-    "release:major": "release-it major --no-git.requireCleanWorkingDir"
-  },
-  "devDependencies": {
-    "release-it": "^18.1.2",
-    "tsup": "^8.5.1",
-    "vitest": "^4.1.6"
-  }
-}
+{
+  "name": "@aeroswarm/weather",
+  "version": "0.4.1",
+  "description": "Decode raw AFTN/METAR/SPECI/TAF messages and turn them into animation parameters.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "main": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "GRID_STANDARD.md",
+    "CHANGELOG.md",
+    "STABILITY.md",
+    "LIMITS.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && tsc --emitDeclarationOnly",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm run typecheck && pnpm run test && pnpm run build",
+    "release": "release-it",
+    "release:dry": "release-it --dry-run",
+    "release:patch": "release-it patch --no-git.requireCleanWorkingDir",
+    "release:minor": "release-it minor --no-git.requireCleanWorkingDir",
+    "release:major": "release-it major --no-git.requireCleanWorkingDir"
+  },
+  "devDependencies": {
+    "release-it": "^18.1.2",
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.6"
+  }
+}