@aeroswarm/weather 0.1.2 → 0.1.4

package/GRID_STANDARD.md

@@ -0,0 +1,68 @@
+# AeroSwarm Weather Grid (`aeroswarm.weather-grid`) v1
+
+One JSON format for gridded weather forecasts, whatever the source (a model API, a converted GRIB
+file, your own service). A source only has to produce this document; the renderer and the timeline
+never need to know where the data came from.
+
+- Read: `parseWeatherGridSeries(json)` (strict, throws a message naming the bad part).
+- Write: `serializeWeatherGridSeries(series)`.
+- Use: `seriesFieldsAt(series, time)` blends the two nearest frames; `null` outside the time range.
+- Open-Meteo: `latticePoints(lattice)` gives the points to request, `weatherGridFromOpenMeteo(response,
+  lattice)` turns the answer into this format. Nothing here calls the network.
+
+## Document
+
+```json
+{
+  "standard": "aeroswarm.weather-grid",
+  "version": 1,
+  "source": {
+    "name": "open-meteo",
+    "model": "icon_seamless",
+    "runAt": "2026-11-02T00:00:00Z",
+    "generatedAt": "2026-11-02T04:12:00Z"
+  },
+  "grid": { "west": 105, "south": -11, "east": 118, "north": -5, "nx": 14, "ny": 13 },
+  "times": ["2026-11-02T04:00:00Z", "2026-11-02T05:00:00Z"],
+  "fields": {
+    "windU":       [[/* nx*ny values for time 0 */], [/* time 1 */]],
+    "windV":       [[...], [...]],
+    "cloud":       [[...], [...]],
+    "rain":        [[...], [...]],
+    "temperature": [[...], [...]]
+  }
+}
+```
+
+## Rules
+
+| Part | Rule |
+|---|---|
+| `standard`, `version` | Exactly `"aeroswarm.weather-grid"` and `1`. |
+| `source.name` | Required. `model`, `runAt`, `generatedAt` are optional (ISO 8601). |
+| `grid` | `west < east`, `south < north`, `nx` and `ny` integers >= 2. Cells sit on the lattice points: column 0 is `west`, the last column is `east`; row 0 is `north`, the last row is `south`. |
+| `times` | At least one ISO 8601 time in UTC, strictly increasing. |
+| `fields` | At least one quantity. Each present quantity has exactly one array per time, and each array has exactly `nx * ny` values in row-major order (row 0 first). `null` means no data. |
+| `windU` / `windV` | Both or neither. m/s. `windU` blows towards the east, `windV` towards the north. |
+| `cloud` | Total cloud cover, percent 0-100. |
+| `rain` | Precipitation rate, mm per hour. |
+| `temperature` | Degrees Celsius. |
+
+Wind is stored as components, not speed and direction, so frames can be blended and interpolated
+without wrapping problems. To convert: `u = -speed * sin(from)`, `v = -speed * cos(from)`, where
+`from` is the direction the wind comes FROM (meteorological, degrees from north).
+
+## Versioning
+
+A change that breaks readers (a different layout, a changed unit) raises `version`. Adding an optional
+quantity or an optional `source` field does not. A reader must reject a `version` it does not know
+instead of guessing.
+
+## Producing it
+
+- **Open-Meteo (in an app, not in this package):** request the lattice points with
+  `hourly=wind_speed_10m,wind_direction_10m,cloud_cover,precipitation,temperature_2m`,
+  `wind_speed_unit=ms`, `timezone=GMT`, then call `weatherGridFromOpenMeteo`.
+- **GRIB:** convert to JSON on the server (`grib2json` or `wgrib2`), then build the document from the
+  two wind records and any scalar fields.
+- **Your own service:** return this document directly; the app loads it from a URL or a file.

package/README.md

@@ -38,3 +38,11 @@ representation around the airport, not the real position of clouds or rain.
 - `sampleWind`, `sampleScalar` (bilinear) and `blendWindGrids` (between two forecast hours).
 
 Row 0 is north, wind is in m/s (`u` east, `v` north), cells without data are NaN.
+
+## Gridded forecast standard
+
+`GRID_STANDARD.md` defines `aeroswarm.weather-grid` v1: one JSON format (grid + times + wind/cloud/rain/
+temperature) for any model source. `parseWeatherGridSeries`, `serializeWeatherGridSeries`,
+`seriesFieldsAt`, and the Open-Meteo adapter (`latticePoints`, `weatherGridFromOpenMeteo`) are in the
+package; the network call stays in the app.
+

package/dist/gridSeries.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Standar data medan cuaca AeroSwarm (`aeroswarm.weather-grid` versi 1).
+ *
+ * Satu format untuk semua sumber model (Open-Meteo, hasil konversi GRIB, layanan sendiri): grid
+ * beraturan, beberapa waktu, dan beberapa besaran. Sumber apa pun cukup menghasilkan format ini; renderer
+ * dan timeline tidak perlu tahu asalnya. Lihat GRID_STANDARD.md untuk bentuk JSON-nya.
+ *
+ * Konvensi: baris 0 = utara, kolom 0 = barat. Angin m/s (`windU` ke timur, `windV` ke utara), awan %,
+ * hujan mm/jam, suhu °C. Nilai `null` = tanpa data. Waktu UTC.
+ */
+import { type GridBounds, type ScalarGrid, type WindGrid } from "./grid.js";
+export declare const WEATHER_GRID_STANDARD = "aeroswarm.weather-grid";
+export declare const WEATHER_GRID_VERSION = 1;
+export type GridQuantity = "windU" | "windV" | "cloud" | "rain" | "temperature";
+export interface WeatherGridSource {
+    /** Nama sumber, mis. `open-meteo`. */
+    name: string;
+    /** Nama model, mis. `icon_seamless`. */
+    model?: string;
+    /** Waktu model dijalankan (run), bila diketahui. */
+    runAt?: Date;
+    /** Waktu data diambil/dibuat. */
+    generatedAt?: Date;
+}
+export interface WeatherGridSeries {
+    source: WeatherGridSource;
+    bounds: GridBounds;
+    nx: number;
+    ny: number;
+    /** Waktu tiap bingkai, naik. */
+    times: Date[];
+    /** Per besaran: satu larik nx*ny per waktu. Besaran yang tidak ada dibiarkan kosong. */
+    fields: Partial<Record<GridQuantity, Float32Array[]>>;
+}
+export interface SeriesFields {
+    at: Date;
+    wind: WindGrid | null;
+    cloud: ScalarGrid | null;
+    rain: ScalarGrid | null;
+    temperature: ScalarGrid | null;
+}
+/**
+ * Baca dan periksa JSON berstandar `aeroswarm.weather-grid` v1. Melempar galat yang menyebut bagian
+ * mana yang salah. Nilai di luar angka (null) menjadi NaN (tanpa data).
+ */
+export declare function parseWeatherGridSeries(input: unknown): WeatherGridSeries;
+/** Bentuk JSON berstandar dari seri (kebalikan `parseWeatherGridSeries`); NaN menjadi null. */
+export declare function serializeWeatherGridSeries(series: WeatherGridSeries): Record<string, unknown>;
+/** Rentang waktu seri. */
+export declare function seriesRange(series: WeatherGridSeries): {
+    from: Date;
+    to: Date;
+};
+/**
+ * Medan pada waktu `at`, dicampur linear antar dua bingkai terdekat. Null di luar rentang waktu seri.
+ * Besaran yang tidak ada di seri dikembalikan null.
+ */
+export declare function seriesFieldsAt(series: WeatherGridSeries, at: Date): SeriesFields | null;
+//# sourceMappingURL=gridSeries.d.ts.map

package/dist/gridSeries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gridSeries.d.ts","sourceRoot":"","sources":["../src/gridSeries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAC9D,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC;AAEhF,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,UAAU,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,wFAAwF;IACxF,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC;CAChC;AAaD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAgExE;AAED,+FAA+F;AAC/F,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB7F;AAED,0BAA0B;AAC1B,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CAK/E;AAqBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,EAAE,IAAI,GAAG,YAAY,GAAG,IAAI,CAwBvF"}

package/dist/gridSeries.test.d.ts

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

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

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

package/dist/index.d.ts

@@ -3,8 +3,11 @@ export * from "./aftn.js";
 export * from "./animation.js";
 export * from "./conditions.js";
 export * from "./grid.js";
+export * from "./gridSeries.js";
+export * from "./openMeteo.js";
 export * from "./metar.js";
 export * from "./taf.js";
+export * from "./store.js";
 export * from "./time.js";
 export * from "./types.js";
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,IAAiB,GAC3B,MAAM,EAAE,CAUV"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAE3B;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,IAAiB,GAC3B,MAAM,EAAE,CAUV"}

package/dist/index.js

@@ -688,10 +688,10 @@ function parseGrib2Json(input) {
     v: orient(vRecord.data)
   };
 }
-function stationWindsFromMetars(reports, locate) {
+function stationWindsFromMetars(reports, locate2) {
   const out = [];
   for (const report of reports) {
-    const place = locate(report.station);
+    const place = locate2(report.station);
     if (!place) continue;
     const { wind } = report.conditions;
     out.push({
@@ -766,6 +766,428 @@ function decodeGridJson(input, fallback) {
   throw new Error("Format medan tidak dikenal: harus grib2json, JSON grid {bounds,nx,ny,u,v|values}, atau respons banyak lokasi");
 }
 
+// src/gridSeries.ts
+var WEATHER_GRID_STANDARD = "aeroswarm.weather-grid";
+var WEATHER_GRID_VERSION = 1;
+var QUANTITIES = ["windU", "windV", "cloud", "rain", "temperature"];
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseDate(value, where) {
+  const date = typeof value === "string" ? new Date(value) : new Date(Number.NaN);
+  if (Number.isNaN(date.getTime())) throw new Error(`${where}: bukan tanggal ISO 8601 yang valid`);
+  return date;
+}
+function parseWeatherGridSeries(input) {
+  if (!isRecord2(input)) throw new Error("Bukan objek JSON");
+  if (input.standard !== WEATHER_GRID_STANDARD) {
+    throw new Error(`standard harus "${WEATHER_GRID_STANDARD}"`);
+  }
+  if (input.version !== WEATHER_GRID_VERSION) {
+    throw new Error(`version ${String(input.version)} tidak didukung (didukung: ${WEATHER_GRID_VERSION})`);
+  }
+  const src = isRecord2(input.source) ? input.source : null;
+  if (!src || typeof src.name !== "string" || src.name === "") throw new Error("source.name wajib diisi");
+  const source = {
+    name: src.name,
+    model: typeof src.model === "string" ? src.model : void 0,
+    runAt: src.runAt === void 0 ? void 0 : parseDate(src.runAt, "source.runAt"),
+    generatedAt: src.generatedAt === void 0 ? void 0 : parseDate(src.generatedAt, "source.generatedAt")
+  };
+  const grid = isRecord2(input.grid) ? input.grid : null;
+  if (!grid) throw new Error("grid wajib diisi");
+  const { west, south, east, north } = grid;
+  const nx = Number(grid.nx);
+  const ny = Number(grid.ny);
+  if (![west, south, east, north].every((n) => typeof n === "number" && Number.isFinite(n))) {
+    throw new Error("grid.west/south/east/north harus angka");
+  }
+  if (!Number.isInteger(nx) || !Number.isInteger(ny) || nx < 2 || ny < 2) {
+    throw new Error("grid.nx dan grid.ny harus bilangan bulat >= 2");
+  }
+  const bounds = { west, south, east, north };
+  if (bounds.west >= bounds.east || bounds.south >= bounds.north) {
+    throw new Error("grid: west < east dan south < north");
+  }
+  if (!Array.isArray(input.times) || input.times.length === 0) throw new Error("times wajib berisi minimal satu waktu");
+  const times = input.times.map((t, i) => parseDate(t, `times[${i}]`));
+  for (let i = 1; i < times.length; i++) {
+    if (times[i].getTime() <= times[i - 1].getTime()) {
+      throw new Error(`times[${i}] harus lebih baru dari times[${i - 1}]`);
+    }
+  }
+  const rawFields = isRecord2(input.fields) ? input.fields : null;
+  if (!rawFields) throw new Error("fields wajib diisi");
+  const fields = {};
+  for (const quantity of QUANTITIES) {
+    const frames = rawFields[quantity];
+    if (frames === void 0) continue;
+    if (!Array.isArray(frames) || frames.length !== times.length) {
+      throw new Error(`fields.${quantity} harus berisi ${times.length} bingkai (satu per waktu)`);
+    }
+    fields[quantity] = frames.map((frame, t) => {
+      if (!Array.isArray(frame) || frame.length !== nx * ny) {
+        throw new Error(`fields.${quantity}[${t}] harus berisi ${nx * ny} nilai (nx * ny)`);
+      }
+      return Float32Array.from(frame, (v) => typeof v === "number" && Number.isFinite(v) ? v : Number.NaN);
+    });
+  }
+  if (fields.windU === void 0 !== (fields.windV === void 0)) {
+    throw new Error("windU dan windV harus ada berdua");
+  }
+  if (Object.keys(fields).length === 0) throw new Error("fields tidak berisi satu besaran pun");
+  return { source, bounds, nx, ny, times, fields };
+}
+function serializeWeatherGridSeries(series) {
+  const fields = {};
+  for (const quantity of QUANTITIES) {
+    const frames = series.fields[quantity];
+    if (!frames) continue;
+    fields[quantity] = frames.map(
+      (frame) => Array.from(frame, (v) => Number.isNaN(v) ? null : Math.round(v * 1e3) / 1e3)
+    );
+  }
+  return {
+    standard: WEATHER_GRID_STANDARD,
+    version: WEATHER_GRID_VERSION,
+    source: {
+      name: series.source.name,
+      ...series.source.model ? { model: series.source.model } : {},
+      ...series.source.runAt ? { runAt: series.source.runAt.toISOString() } : {},
+      ...series.source.generatedAt ? { generatedAt: series.source.generatedAt.toISOString() } : {}
+    },
+    grid: { ...series.bounds, nx: series.nx, ny: series.ny },
+    times: series.times.map((t) => t.toISOString()),
+    fields
+  };
+}
+function seriesRange(series) {
+  return {
+    from: series.times[0],
+    to: series.times[series.times.length - 1]
+  };
+}
+function locate(times, at) {
+  const ms = at.getTime();
+  const first = times[0].getTime();
+  const last = times[times.length - 1].getTime();
+  if (ms < first || ms > last) return null;
+  for (let i = 1; i < times.length; i++) {
+    const hi = times[i].getTime();
+    if (ms <= hi) {
+      const lo = times[i - 1].getTime();
+      return { a: i - 1, b: i, t: (ms - lo) / (hi - lo || 1) };
+    }
+  }
+  return { a: times.length - 1, b: times.length - 1, t: 0 };
+}
+var mixFrames = (frames, a, b, t) => Float32Array.from(frames[a], (value, i) => value + (frames[b][i] - value) * t);
+function seriesFieldsAt(series, at) {
+  const where = locate(series.times, at);
+  if (!where) return null;
+  const { bounds, nx, ny } = series;
+  const scalar = (quantity) => {
+    const frames = series.fields[quantity];
+    return frames ? { bounds, nx, ny, values: mixFrames(frames, where.a, where.b, where.t) } : null;
+  };
+  const u = series.fields.windU;
+  const v = series.fields.windV;
+  let wind = null;
+  if (u && v) {
+    const from = { bounds, nx, ny, u: u[where.a], v: v[where.a] };
+    const to = { bounds, nx, ny, u: u[where.b], v: v[where.b] };
+    wind = where.a === where.b ? from : blendWindGrids(from, to, where.t);
+  }
+  return {
+    at,
+    wind,
+    cloud: scalar("cloud"),
+    rain: scalar("rain"),
+    temperature: scalar("temperature")
+  };
+}
+
+// src/openMeteo.ts
+function latticePoints(lattice) {
+  const latitude = [];
+  const longitude = [];
+  for (let row = 0; row < lattice.ny; row++) {
+    const lat = lattice.north - (lattice.north - lattice.south) * row / (lattice.ny - 1);
+    for (let col = 0; col < lattice.nx; col++) {
+      latitude.push(round(lat));
+      longitude.push(round(lattice.west + (lattice.east - lattice.west) * col / (lattice.nx - 1)));
+    }
+  }
+  return { latitude, longitude };
+}
+var round = (value) => Math.round(value * 1e4) / 1e4;
+var SPEED_TO_MS = { "m/s": 1, "km/h": 1 / 3.6, kn: 0.514444, mph: 0.44704 };
+var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var toUtc = (iso) => new Date(/[zZ]|[+-]\d\d:?\d\d$/.test(iso) ? iso : `${iso}Z`);
+function weatherGridFromOpenMeteo(response, lattice, options = {}) {
+  const items = Array.isArray(response) ? response : [response];
+  const expected = lattice.nx * lattice.ny;
+  if (items.length !== expected) {
+    throw new Error(`Respons berisi ${items.length} titik, kisi memerlukan ${expected} (${lattice.nx} x ${lattice.ny})`);
+  }
+  const hourly = items.map((item, i) => {
+    const h = isRecord3(item) && isRecord3(item.hourly) ? item.hourly : null;
+    if (!h || !Array.isArray(h.time)) throw new Error(`Titik ${i}: tidak ada data hourly.time`);
+    return h;
+  });
+  const timesIso = hourly[0].time;
+  if (timesIso.length === 0) throw new Error("hourly.time kosong");
+  for (const [i, h] of hourly.entries()) {
+    if (h.time.length !== timesIso.length) throw new Error(`Titik ${i}: jumlah waktu berbeda dari titik pertama`);
+  }
+  const times = timesIso.map(toUtc);
+  const toMs = SPEED_TO_MS[options.speedUnit ?? "m/s"] ?? 1;
+  const frame = (pick) => times.map((_, t) => Float32Array.from(hourly, (h) => pick(h, t)));
+  const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : Number.NaN;
+  const fields = {};
+  const has = (key) => hourly.every((h) => Array.isArray(h[key]));
+  if (has("wind_speed_10m") && has("wind_direction_10m")) {
+    const uv = (h, t) => {
+      const speed = num(h.wind_speed_10m?.[t]) * toMs;
+      const dir = num(h.wind_direction_10m?.[t]);
+      return Number.isNaN(speed) || Number.isNaN(dir) ? { u: Number.NaN, v: Number.NaN } : uvFromSpeedDirection(speed, dir);
+    };
+    fields.windU = frame((h, t) => uv(h, t).u);
+    fields.windV = frame((h, t) => uv(h, t).v);
+  }
+  if (has("cloud_cover")) fields.cloud = frame((h, t) => num(h.cloud_cover?.[t]));
+  if (has("precipitation")) fields.rain = frame((h, t) => num(h.precipitation?.[t]));
+  if (has("temperature_2m")) fields.temperature = frame((h, t) => num(h.temperature_2m?.[t]));
+  if (Object.keys(fields).length === 0) {
+    throw new Error("Respons tidak memuat wind_speed_10m, wind_direction_10m, cloud_cover, precipitation, atau temperature_2m");
+  }
+  return {
+    source: {
+      name: "open-meteo",
+      model: options.model,
+      runAt: options.runAt,
+      generatedAt: options.generatedAt ?? /* @__PURE__ */ new Date()
+    },
+    bounds: { west: lattice.west, south: lattice.south, east: lattice.east, north: lattice.north },
+    nx: lattice.nx,
+    ny: lattice.ny,
+    times,
+    fields
+  };
+}
+
+// src/store.ts
+var MAX_OBSERVATIONS_PER_STATION = 48;
+var MAX_FORECASTS_PER_STATION = 8;
+var rainRate = (intensity) => intensity * intensity * 15;
+var hhmm = (d) => `${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}`;
+var WeatherStore = class {
+  constructor(locate2) {
+    this.locate = locate2;
+  }
+  locate;
+  observations = /* @__PURE__ */ new Map();
+  forecasts = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  /** Naik tiap data berubah; berguna untuk memicu render ulang. */
+  version = 0;
+  /** Terima pesan mentah (laporan polos, buletin, atau pesan AFTN; boleh banyak laporan). */
+  ingest(message, options = {}) {
+    const receivedAt = options.receivedAt ?? /* @__PURE__ */ new Date();
+    const manual = options.manual === true;
+    const result = { metars: 0, tafs: 0, skipped: 0, stations: [] };
+    const touched = /* @__PURE__ */ new Set();
+    for (const raw of extractReports(message)) {
+      if (raw.kind === "TAF") {
+        const taf = parseTaf(raw.text, receivedAt);
+        if (!taf) {
+          result.skipped++;
+          continue;
+        }
+        this.add(this.forecasts, taf.station, { report: taf, manual, receivedAt }, MAX_FORECASTS_PER_STATION);
+        touched.add(taf.station);
+        result.tafs++;
+      } else {
+        const metar = parseMetar(raw.text, receivedAt);
+        if (!metar) {
+          result.skipped++;
+          continue;
+        }
+        this.add(this.observations, metar.station, { report: metar, manual, receivedAt }, MAX_OBSERVATIONS_PER_STATION);
+        touched.add(metar.station);
+        result.metars++;
+      }
+    }
+    result.stations = [...touched];
+    if (result.metars + result.tafs > 0) this.changed();
+    return result;
+  }
+  /** Hapus semua data manual (seluruh stasiun, atau satu stasiun). */
+  clearManual(station) {
+    let removed = false;
+    for (const store of [this.observations, this.forecasts]) {
+      for (const [icao, list] of store) {
+        if (station && icao !== station) continue;
+        const kept = list.filter((s) => !s.manual);
+        if (kept.length !== list.length) removed = true;
+        store.set(icao, kept);
+      }
+    }
+    if (removed) this.changed();
+  }
+  /** Hapus semua data (otomatis dan manual). */
+  clear() {
+    this.observations.clear();
+    this.forecasts.clear();
+    this.changed();
+  }
+  hasManual() {
+    for (const store of [this.observations, this.forecasts]) {
+      for (const list of store.values()) if (list.some((s) => s.manual)) return true;
+    }
+    return false;
+  }
+  stations() {
+    return [.../* @__PURE__ */ new Set([...this.observations.keys(), ...this.forecasts.keys()])].filter(
+      (icao) => (this.observations.get(icao)?.length ?? 0) + (this.forecasts.get(icao)?.length ?? 0) > 0
+    );
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** Cuaca satu stasiun pada waktu `at`; null bila tidak ada data. */
+  snapshotAt(station, at, options = {}) {
+    return animationSnapshot({
+      observation: this.pickObservation(station, at, options.maxObservationAgeMs),
+      forecast: this.pickForecast(station, at),
+      at,
+      maxObservationAgeMs: options.maxObservationAgeMs,
+      includeProbable: options.includeProbable
+    });
+  }
+  /** Rentang waktu dan pembagian periode (BASE/BECMG/TEMPO/FM) dari TAF, untuk timeline. */
+  timeline() {
+    const segments = [];
+    const observations = [];
+    let from = null;
+    let to = null;
+    const widen = (a, b) => {
+      from = from === null ? a.getTime() : Math.min(from, a.getTime());
+      to = to === null ? b.getTime() : Math.max(to, b.getTime());
+    };
+    for (const [station, list] of this.forecasts) {
+      const taf = this.latest(list, (t) => t.issuedAt);
+      if (!taf || taf.cancelled) continue;
+      widen(taf.validFrom, taf.validTo);
+      for (const period of taf.periods) {
+        if (period.change === "BASE") continue;
+        const label = period.change === "FM" ? `FM ${hhmm(period.from)}` : `${period.probability ? `PROB${period.probability} ` : ""}${period.change} ${hhmm(period.from)}-${hhmm(period.to)}`;
+        segments.push({ station, change: period.change, from: period.from, to: period.to, label });
+      }
+    }
+    for (const list of this.observations.values()) {
+      for (const source of list) {
+        observations.push(source.report.observedAt);
+        widen(source.report.observedAt, source.report.observedAt);
+      }
+    }
+    if (from === null || to === null) return null;
+    observations.sort((a, b) => a.getTime() - b.getTime());
+    return { from: new Date(from), to: new Date(to), segments, observations };
+  }
+  /**
+   * Medan angin, awan, hujan, dan suhu pada waktu `at`, dari semua stasiun yang punya data dan
+   * koordinat, diinterpolasi ke grid. Mengembalikan null bila tidak ada stasiun yang bisa dipakai.
+   */
+  fieldsAt(at, grid, options = {}) {
+    const winds = [];
+    const clouds = [];
+    const rains = [];
+    const temperatures = [];
+    const used = [];
+    for (const station of this.stations()) {
+      const place = this.locate(station);
+      if (!place) continue;
+      const snapshot = this.snapshotAt(station, at, options);
+      if (!snapshot) continue;
+      used.push(station);
+      const { state } = snapshot;
+      winds.push({
+        lat: place.lat,
+        lon: place.lon,
+        speedKt: state.wind.speedKt,
+        directionDeg: state.wind.fromDeg
+      });
+      clouds.push({ lat: place.lat, lon: place.lon, value: state.clouds.total * 100 });
+      rains.push({
+        lat: place.lat,
+        lon: place.lon,
+        value: state.precipitation ? rainRate(state.precipitation.intensity) : 0
+      });
+      const observed = this.pickObservation(station, at);
+      if (observed?.temperatureC !== null && observed?.temperatureC !== void 0) {
+        temperatures.push({ lat: place.lat, lon: place.lon, value: observed.temperatureC });
+      }
+    }
+    if (used.length === 0) return null;
+    return {
+      at,
+      stations: used,
+      wind: windGridFromStations(winds, grid),
+      cloud: interpolateScalar(clouds, grid),
+      rain: interpolateScalar(rains, grid),
+      temperature: temperatures.length > 0 ? interpolateScalar(temperatures, grid) : null
+    };
+  }
+  // ---- internal -------------------------------------------------------------
+  changed() {
+    this.version++;
+    for (const listener of this.listeners) listener();
+  }
+  add(store, station, source, limit) {
+    const list = store.get(station) ?? [];
+    const key = (s) => {
+      const report = s.report;
+      return (report.observedAt ?? report.issuedAt)?.getTime() ?? 0;
+    };
+    const next = list.filter((s) => !(s.manual === source.manual && key(s) === key(source)));
+    next.push(source);
+    next.sort((a, b) => key(a) - key(b));
+    store.set(station, next.slice(-limit));
+  }
+  latest(list, timeOf) {
+    const pool = list.some((s) => s.manual) ? list.filter((s) => s.manual) : list;
+    let best = null;
+    for (const source of pool) {
+      if (!best || timeOf(source.report).getTime() >= timeOf(best.report).getTime()) best = source;
+    }
+    return best?.report ?? null;
+  }
+  pickObservation(station, at, maxAgeMs = 3 * 36e5) {
+    const list = this.observations.get(station) ?? [];
+    const usable = (s) => {
+      const age = at.getTime() - s.report.observedAt.getTime();
+      return age >= 0 && age <= maxAgeMs;
+    };
+    const manual = list.filter((s) => s.manual && usable(s));
+    const pool = manual.length > 0 ? manual : list.filter(usable);
+    let best = null;
+    for (const source of pool) {
+      if (!best || source.report.observedAt.getTime() >= best.report.observedAt.getTime()) best = source;
+    }
+    if (best) return best.report;
+    const before = list.filter((s) => s.report.observedAt.getTime() <= at.getTime());
+    return before.length > 0 ? before[before.length - 1].report : null;
+  }
+  pickForecast(station, at) {
+    const list = this.forecasts.get(station) ?? [];
+    const covers = (s) => !s.report.cancelled && at.getTime() >= s.report.validFrom.getTime() && at.getTime() < s.report.validTo.getTime();
+    const manual = list.filter((s) => s.manual && covers(s));
+    const pool = manual.length > 0 ? manual : list.filter(covers);
+    if (pool.length === 0) return null;
+    return this.latest(pool, (t) => t.issuedAt);
+  }
+};
+
 // src/index.ts
 function decodeWeatherMessage(message, reference = /* @__PURE__ */ new Date()) {
   const reports = [];
@@ -776,6 +1198,9 @@ function decodeWeatherMessage(message, reference = /* @__PURE__ */ new Date()) {
   return reports;
 }
 export {
+  WEATHER_GRID_STANDARD,
+  WEATHER_GRID_VERSION,
+  WeatherStore,
   animationFromConditions,
   animationSnapshot,
   blendConditions,
@@ -787,19 +1212,25 @@ export {
   extractReports,
   forecastAt,
   interpolateScalar,
+  latticePoints,
   mergeConditions,
   parseConditionTokens,
   parseGrib2Json,
   parseGridJson,
   parseMetar,
   parseTaf,
+  parseWeatherGridSeries,
   pointOf,
   resolveDayTime,
   sampleScalar,
   sampleWind,
+  serializeWeatherGridSeries,
+  seriesFieldsAt,
+  seriesRange,
   speedOf,
   stationWindsFromMetars,
   stationWindsFromModelPoints,
   uvFromSpeedDirection,
+  weatherGridFromOpenMeteo,
   windGridFromStations
 };

package/dist/openMeteo.d.ts

@@ -0,0 +1,40 @@
+import { type WeatherGridSeries } from "./gridSeries.js";
+/**
+ * Adaptor respons layanan model bergaya Open-Meteo menjadi standar `aeroswarm.weather-grid`. Murni:
+ * tidak memanggil jaringan. Pemanggilnya (aplikasi) yang mengambil datanya.
+ *
+ * Titik diminta sebagai kisi beraturan (lihat `latticePoints`), jadi responsnya langsung menjadi
+ * grid tanpa interpolasi.
+ */
+export interface Lattice {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+    nx: number;
+    ny: number;
+}
+/**
+ * Titik-titik kisi, baris demi baris dari utara ke selatan, kolom dari barat ke timur. Urutan ini
+ * sama dengan urutan respons banyak lokasi, dan dengan urutan sel pada grid standar.
+ */
+export declare function latticePoints(lattice: Lattice): {
+    latitude: number[];
+    longitude: number[];
+};
+declare const SPEED_TO_MS: Record<string, number>;
+export interface OpenMeteoOptions {
+    /** Satuan kecepatan angin di respons. Bawaan `m/s` (minta dengan `wind_speed_unit=ms`). */
+    speedUnit?: keyof typeof SPEED_TO_MS;
+    model?: string;
+    runAt?: Date;
+    generatedAt?: Date;
+}
+/**
+ * Susun seri standar dari respons banyak lokasi (satu elemen per titik kisi, urutan `latticePoints`).
+ * Meminta `hourly=wind_speed_10m,wind_direction_10m,cloud_cover,precipitation,temperature_2m`,
+ * `timezone=GMT`, dan `wind_speed_unit=ms`.
+ */
+export declare function weatherGridFromOpenMeteo(response: unknown, lattice: Lattice, options?: OpenMeteoOptions): WeatherGridSeries;
+export {};
+//# sourceMappingURL=openMeteo.d.ts.map

package/dist/openMeteo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openMeteo.d.ts","sourceRoot":"","sources":["../src/openMeteo.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AAEH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAW3F;AAID,QAAA,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAA6D,CAAC;AAEtG,MAAM,WAAW,gBAAgB;IAC/B,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,OAAO,WAAW,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAiBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,gBAAqB,GAC7B,iBAAiB,CAyDnB"}

package/dist/store.d.ts

@@ -0,0 +1,91 @@
+import { type AnimationSnapshot } from "./animation.js";
+import { type GeoPoint, type GridBounds, type ScalarGrid, type WindGrid } from "./grid.js";
+import type { TafChange } from "./types.js";
+export type Locate = (icao: string) => GeoPoint | undefined;
+export interface IngestOptions {
+    /** Waktu pesan diterima (menentukan bulan/tahun laporan). Bawaan: sekarang. */
+    receivedAt?: Date;
+    /** Data manual selalu menimpa data otomatis untuk stasiun dan waktu yang sama. */
+    manual?: boolean;
+}
+export interface IngestResult {
+    metars: number;
+    tafs: number;
+    /** Laporan yang dikenali kata kuncinya tetapi tidak terbaca. */
+    skipped: number;
+    stations: string[];
+}
+export interface TimelineSegment {
+    station: string;
+    change: TafChange;
+    from: Date;
+    to: Date;
+    label: string;
+}
+export interface Timeline {
+    from: Date;
+    to: Date;
+    segments: TimelineSegment[];
+    /** Waktu pengamatan (METAR/SPECI) yang ada. */
+    observations: Date[];
+}
+export interface WeatherFields {
+    at: Date;
+    /** Stasiun yang punya data pada waktu itu. */
+    stations: string[];
+    wind: WindGrid;
+    /** Tutupan awan 0-100. */
+    cloud: ScalarGrid;
+    /** Curah hujan (mm/jam), perkiraan dari intensitas pada laporan. */
+    rain: ScalarGrid;
+    /** Suhu (°C); null bila tidak ada pengamatan bersuhu. */
+    temperature: ScalarGrid | null;
+}
+export interface FieldGridOptions {
+    bounds: GridBounds;
+    nx: number;
+    ny: number;
+    maxDistanceKm?: number;
+}
+/**
+ * Menampung laporan cuaca (METAR, SPECI, TAF) dari mana pun, lalu menjawab "bagaimana cuacanya di
+ * waktu T": per stasiun maupun sebagai medan grid. Data manual selalu menimpa data otomatis.
+ */
+export declare class WeatherStore {
+    private readonly locate;
+    private readonly observations;
+    private readonly forecasts;
+    private readonly listeners;
+    /** Naik tiap data berubah; berguna untuk memicu render ulang. */
+    version: number;
+    constructor(locate: Locate);
+    /** Terima pesan mentah (laporan polos, buletin, atau pesan AFTN; boleh banyak laporan). */
+    ingest(message: string, options?: IngestOptions): IngestResult;
+    /** Hapus semua data manual (seluruh stasiun, atau satu stasiun). */
+    clearManual(station?: string): void;
+    /** Hapus semua data (otomatis dan manual). */
+    clear(): void;
+    hasManual(): boolean;
+    stations(): string[];
+    onChange(listener: () => void): () => void;
+    /** Cuaca satu stasiun pada waktu `at`; null bila tidak ada data. */
+    snapshotAt(station: string, at: Date, options?: {
+        maxObservationAgeMs?: number;
+        includeProbable?: boolean;
+    }): AnimationSnapshot | null;
+    /** Rentang waktu dan pembagian periode (BASE/BECMG/TEMPO/FM) dari TAF, untuk timeline. */
+    timeline(): Timeline | null;
+    /**
+     * Medan angin, awan, hujan, dan suhu pada waktu `at`, dari semua stasiun yang punya data dan
+     * koordinat, diinterpolasi ke grid. Mengembalikan null bila tidak ada stasiun yang bisa dipakai.
+     */
+    fieldsAt(at: Date, grid: FieldGridOptions, options?: {
+        includeProbable?: boolean;
+    }): WeatherFields | null;
+    private changed;
+    private add;
+    private latest;
+    private pickObservation;
+    private pickForecast;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/store.test.d.ts

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeroswarm/weather",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Decode raw AFTN/METAR/SPECI/TAF messages and turn them into animation parameters.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "GRID_STANDARD.md"
   ],
   "publishConfig": {
     "access": "public",