@motionstudies/data 0.1.0-alpha.3 → 0.1.0-alpha.5

package/README.md

@@ -25,8 +25,51 @@ Build release candidates with `npm run build:packages`. Distribution manifests a
 
 Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.
 
+## Selection labels
+
+`NationalNetworkScene` gives the selected station first label priority, followed by the selected route's terminal stops (including branches), then intermediate stops. Selected services use their own endpoints. Priority precedes retained labels and ordinary rank/tier admission; clearing selection restores edition ranking. This is built in for every consumer, including geographic and diagram layouts. Supply complete enabled infrastructure as `referenceSnapshot` to preserve endpoints through timetable gaps; its stop indexes need not match the active snapshot. See the [edition behaviour contract](https://github.com/emmettl/motionstudies/blob/main/docs/EDITIONS.md#selection-and-station-labels).
+
 ## Button help
 
 `mountMotionStudy` installs one shared tooltip surface. Independent consumers such as the lab can render `ButtonTooltips` from `@motionstudies/web/components/ButtonTooltips` once instead. Put concise, action-oriented help in each button’s `data-tooltip`; icon buttons fall back to their `aria-label`. An empty `data-tooltip` opts out. Avoid native `title` attributes on these buttons, which can also appear during touch interaction.
 
 Help appears after a short mouse hover or on keyboard focus when the primary pointer is fine and supports hover. Touch input suppresses it, including on hybrid devices. Escape, activation, scrolling and blur dismiss it. The tooltip stays inside the viewport, can itself be hovered, and temporarily extends `aria-describedby` without replacing existing descriptions. Copy and translations stay in the edition; rendering and input handling stay in this package. The Controls specimen and packed-consumer tests exercise this contract.
+
+## Airport heroes and split-flap boards
+
+`AirportHeroCard` provides an airport identity header and switchable departure/arrival boards. `SplitFlapBoard` is the underlying transport-neutral widget, also suitable for rail stations. Both use scoped package styles, semantic tables, full accessible cell values, keyboard-operable selection, contained horizontal scrolling and reduced-motion support. Only changed characters remount for the flap animation.
+
+```tsx
+import { AirportHeroCard } from '@motionstudies/web/components/AirportHeroCard'
+import '@motionstudies/web/airport-hero-card.css'
+
+<AirportHeroCard
+  key={airport.id}
+  airport={airport}
+  departures={departures}
+  arrivals={arrivals}
+  study={{ time, windowStart: metadata.windowStart, windowEnd: metadata.windowEnd }}
+  dateLabel={metadata.serviceDate}
+  note="Observed study · inferred directions; times are observations."
+  onSelectFlight={selectAirTrack}
+  selectedFlightId={selectedAirTrackId}
+/>
+```
+
+Entries have a stable `id`, a `service` label, and optional numeric `time`, `place`, `stand`, `status` and `tone` (`neutral`, `accent` or `warning`). Movement times and `study.time`, `windowStart`, and `windowEnd` must use the same study-relative seconds and service date. Do not parse display strings or normalize numeric times at midnight: an event after 24:00 retains its value above 86,400. `formatTime` optionally controls display formatting; the default uses the study's `formatServiceTime` helper. The header clock is derived directly from `study.time`, with no independent wall clock.
+
+The card sorts movements chronologically and shows up to eight rows per direction inside the intersection of the study bounds and a rolling window: ten minutes behind the playback clock and sixty minutes ahead, with inclusive endpoints. Override this with `horizon={{ lookBehindSeconds: 600, lookAheadSeconds: 3600 }}` and `maxRows`. Playback, backward seeking, changed study bounds and updated movement times all recalculate the rows. An out-of-study or invalid clock shows no movements; rows with missing or non-finite times are excluded because they cannot be placed in the window. Other unknown fields render as a dash. Labels include `studyTime`, `boardWindow` and `outsideWindow` for localization. Filtering does not infer operational statuses or clear the consumer's map selection when a row leaves the window.
+
+Consumers still own time coordinates, source interpretation and data loading. Supply movements for the displayed horizon, not just aircraft active at the current second, and use the selected study's bounds rather than an individual progressive chunk's bounds. Do not turn an approach-envelope association into a confirmed departure/arrival: unclassified tracks should remain outside these direction lists. Current `AirTrack` data does not supply scheduled times, routes or gates; leave those fields absent, use observation times only when clearly labelled, and explain any inference in the required `note`.
+
+Pass `labels` for edition translations, `loading`, or a localized `error` and `onRetry` for data states. The selected direction is local to each card; key the card by airport ID to reset it on selection changes. The Airports lab specimen exercises synthetic timetables, playback, scrubbing, study-window changes, incomplete observations, French labels, long destinations, updates and recovery. Edition adoption happens through their independently pinned package releases; adding this export does not update deployed studies.
+
+For a custom rail or transport board, import `SplitFlapBoard` from `@motionstudies/web/components/SplitFlapBoard` and `@motionstudies/web/split-flap-board.css`. Supply `columns` (`key`, `label`, `characters`) and `rows` (`id`, `cells`, optional `tone`). Cell text longer than its flap count is visually ellipsized, with the full value retained for assistive technology and hover. `onSelectRow`, `selectedRowId` and `selectionColumn` optionally make one cell per row selectable.
+
+The shared board also accepts `loading`, a localized `loadingMessage`, and `loadingRows` (default five). While loading, its decorative rows cycle through staggered letters and digits; they are hidden from assistive technology and cannot be selected. A single status message announces loading. When data arrives, characters flip through a short sequence and settle into their actual values; later changes animate only the changed characters. These CSS animations have no JavaScript timers and stop looping when loading ends or the board is removed. Reduced-motion users get static blank loading flaps and immediate final text. `AirportHeroCard` uses this shared loading treatment automatically. Use **Reload board** in the Airports lab to preview the complete loading-to-ready transition.
+
+Empty messages also appear on the flaps, in the widest column (the destination/origin column in airport cards), with the other columns blank. Longer localized messages wrap across display rows instead of being truncated. They settle with the same animation as flight details, and one hidden status announces the complete message to assistive technology. This also applies when the study clock moves into a window with no movements.
+
+Rail and other transport consumers can share the same time filtering through `movementBoardWindow(study, horizon)` and `movementsForBoard(entries, window, maxRows)` from `@motionstudies/core/domain/movement-board`. Format the returned numeric times when mapping them into `SplitFlapBoard` cells. The lab's rail board follows the same study clock and horizon as its airport card.
+
+`@motionstudies/data/air-endpoints` provides offline `enrichAirEndpoints` for existing air manifests, chunks and opening snapshots. Supply cached same-date global ADSB.lol heatmaps, an OurAirports CSV and the service date's local UTC offset. It associates only unambiguous low-altitude endpoints near a reference airport; cruise-only traces and uncertain routes stay unknown. Optional `AirEndpoint` origin/destination fields carry airport identity, observed boundary time and `observed-endpoint` evidence. `airportBoardMovements` maps full manifest entries to board rows without confusing playback chunk boundaries with flight endpoints. Input hashes and source/licence attribution are recorded in fixture metadata. These fields describe inferred observations, never flight schedules, gates or live status.

package/air-endpoints.d.mts

@@ -0,0 +1,5 @@
+import type { AirEndpoint, AirSample } from '@motionstudies/core/domain/air'
+export interface EndpointAirport { icao: string; iata: string; name: string; city: string; longitude: number; latitude: number; elevation: number }
+export function parseAirports(csv: string): EndpointAirport[]
+export function inferAirEndpoints(samples: readonly AirSample[], airports: readonly EndpointAirport[]): { origin?: AirEndpoint; destination?: AirEndpoint }
+export function enrichAirEndpoints(options: { manifestPath: string; snapshotPaths?: string[]; heatmapDirectory: string; airportCsvPath: string; utcOffsetHours: number }): Promise<{ tracks: number; origins: number; destinations: number }>

package/air-endpoints.mjs

@@ -0,0 +1,146 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { gunzipSync } from 'node:zlib'
+import { createHash } from 'node:crypto'
+import { parseCsvLine } from './gtfs.mjs'
+
+export function parseAirports(csv) {
+  const [header, ...lines] = csv.trim().split(/\r?\n/)
+  const keys = parseCsvLine(header)
+  return lines.map(line => Object.fromEntries(parseCsvLine(line).map((value, index) => [keys[index], value])))
+    .filter(row => ['large_airport', 'medium_airport'].includes(row.type) && row.ident && row.elevation_ft)
+    .map(row => ({ icao: row.ident, iata: row.iata_code, name: row.name, city: row.municipality,
+      longitude: Number(row.longitude_deg), latitude: Number(row.latitude_deg), elevation: Number(row.elevation_ft) }))
+    .filter(row => [row.longitude, row.latitude, row.elevation].every(Number.isFinite))
+}
+
+function distance(sample, airport) {
+  const longitude = ((sample[1] - airport.longitude + 540) % 360) - 180
+  return Math.hypot(longitude * 111.32 * Math.cos((sample[2] + airport.latitude) * Math.PI / 360), (sample[2] - airport.latitude) * 111.32)
+}
+
+function atAirport(sample, airport) {
+  return sample[3] >= airport.elevation - 500 && sample[3] <= airport.elevation + 1500 && sample[4] <= 250 && distance(sample, airport) <= 6
+}
+
+/** Conservative endpoint association; cruise-only traces and ambiguous neighbouring airports stay unknown. */
+export function inferAirEndpoints(samples, airports) {
+  if (samples.length < 4) return {}
+  const maximumAltitude = Math.max(...samples.map(sample => sample[3]))
+  const endpoint = (arrival) => {
+    const ordered = arrival ? [...samples].reverse() : samples
+    const candidates = airports.filter(airport => atAirport(ordered[0], airport) && maximumAltitude >= airport.elevation + 3000)
+    if (candidates.length !== 1) return undefined
+    const airport = candidates[0]
+    let boundary = ordered[0]
+    for (const sample of ordered.slice(1)) {
+      if (!atAirport(sample, airport)) break
+      boundary = sample
+    }
+    return { icao: airport.icao, iata: airport.iata, name: airport.name, city: airport.city, time: boundary[0], evidence: 'observed-endpoint' }
+  }
+  const origin = endpoint(false), destination = endpoint(true)
+  if (origin && destination && (origin.icao === destination.icao || origin.time >= destination.time)) return {}
+  return { ...(origin ? { origin } : {}), ...(destination ? { destination } : {}) }
+}
+
+function segmentsFor(samples) {
+  const segments = []
+  let current = []
+  for (const sample of samples.sort((a, b) => a[0] - b[0])) {
+    const previous = current.at(-1)
+    if (previous && previous[0] === sample[0]) continue
+    if (previous && (sample[0] - previous[0] > 1800 || sample[5] !== previous[5])) {
+      segments.push(current)
+      current = []
+    }
+    current.push(sample)
+  }
+  if (current.length) segments.push(current)
+  return segments
+}
+
+/** Enrich an existing study and its chunks using cached, same-date global heatmaps. No network requests. */
+export async function enrichAirEndpoints({ manifestPath, snapshotPaths = [], heatmapDirectory, airportCsvPath, utcOffsetHours }) {
+  const readJson = async path => JSON.parse(await readFile(path, 'utf8'))
+  const manifest = await readJson(manifestPath)
+  const snapshots = await Promise.all(snapshotPaths.map(readJson))
+  const date = manifest.metadata.serviceDate
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(utcOffsetHours)) throw new Error('A service date and UTC offset are required')
+  if (snapshots.some(snapshot => snapshot.metadata.serviceDate !== date)) throw new Error('Air snapshots must share the manifest service date')
+  const tracks = [...manifest.aircraft, ...snapshots.flatMap(snapshot => snapshot.tracks)]
+  const wanted = new Set(tracks.map(track => parseInt(track.icaoAddress ?? track.id.split('-')[0], 16)))
+  const records = new Map()
+  const dayStart = Date.parse(`${date}T00:00:00Z`) - utcOffsetHours * 3600000
+  const files = (await readdir(heatmapDirectory)).filter(file => file.endsWith('.bin.ttf')).sort()
+  if (!files.length) throw new Error('No cached heatmap slices found')
+  const sources = []
+  for (const file of files) {
+    const raw = await readFile(join(heatmapDirectory, file))
+    const buffer = gunzipSync(raw)
+    let time
+    const callsigns = new Map()
+    let used = false
+    for (let offset = 0; offset + 16 <= buffer.length; offset += 16) {
+      const address = buffer.readUInt32LE(offset), latitude = buffer.readInt32LE(offset + 4)
+      if (address === 0x0e7f7c9d) {
+        time = Math.round((Number((BigInt(latitude) << 32n) | BigInt(buffer.readUInt32LE(offset + 8))) - dayStart) / 1000)
+        continue
+      }
+      const id = address & 0xffffff
+      if (!wanted.has(id) || (address & 0x01000000)) continue
+      if (latitude >= 0 && (latitude & 0x40000000) !== 0) {
+        callsigns.set(id, buffer.subarray(offset + 8, offset + 16).toString('ascii').replaceAll('\0', '').trim().toUpperCase())
+        continue
+      }
+      if (time === undefined || time < 0 || time > 86400) continue
+      const altitude = buffer.readInt16LE(offset + 12), speed = buffer.readInt16LE(offset + 14)
+      if (altitude < 0 || speed < 0) continue
+      const samples = records.get(id) ?? []
+      samples.push([time, buffer.readInt32LE(offset + 8) / 1e6, latitude / 1e6, altitude * 25, speed / 10, callsigns.get(id) ?? samples.at(-1)?.[5] ?? ''])
+      records.set(id, samples)
+      used = true
+    }
+    if (used) sources.push({ file, sha256: createHash('sha256').update(raw).digest('hex') })
+  }
+  const csv = await readFile(airportCsvPath, 'utf8')
+  if (!sources.length) throw new Error('No same-date observations matched the study aircraft')
+  const airports = parseAirports(csv)
+  if (!airports.length) throw new Error('No usable airports in the reference CSV')
+  const segments = new Map([...records].map(([id, samples]) => [id, segmentsFor(samples).map(samples => ({
+    start: samples[0][0], end: samples.at(-1)[0], callsign: samples[0][5], ...inferAirEndpoints(samples, airports),
+  }))]))
+  const enrich = (track) => {
+    const candidates = (segments.get(parseInt(track.icaoAddress ?? track.id.split('-')[0], 16)) ?? [])
+      .filter(segment => segment.callsign && segment.callsign === track.callsign && segment.start <= track.start + 30 && segment.end >= track.end - 30)
+    const { origin: _origin, destination: _destination, ...rest } = track
+    if (candidates.length !== 1) return rest
+    const { origin, destination } = candidates[0]
+    return { ...rest, ...(origin ? { origin } : {}), ...(destination ? { destination } : {}) }
+  }
+  const metadata = {
+    serviceDate: date, method: 'observed-endpoint', note: 'Origin/destination inferred from full-trace endpoints within 6 km and 1500 ft above an airport; observed times, not schedules or confirmed flight plans.',
+    airportSource: 'https://ourairports.com/data/', airportLicense: 'Public Domain', airportSha256: createHash('sha256').update(csv).digest('hex'),
+    traceSource: manifest.metadata.sourceUrl, traceLicense: 'ODbL 1.0', utcOffsetHours, sourceFiles: sources,
+  }
+  const aircraft = manifest.aircraft.map(enrich)
+  const byId = new Map(aircraft.map(track => [track.id, track]))
+  const writes = []
+  for (const descriptor of manifest.chunks) {
+    const path = join(dirname(manifestPath), descriptor.path)
+    const chunk = await readJson(path)
+    chunk.tracks = chunk.tracks.map(track => {
+      const { origin: _origin, destination: _destination, ...rest } = track
+      const full = byId.get(track.id)
+      return { ...rest, ...(full?.origin ? { origin: full.origin } : {}), ...(full?.destination ? { destination: full.destination } : {}) }
+    })
+    const bytes = Buffer.from(`${JSON.stringify(chunk)}\n`)
+    if ('bytes' in descriptor) descriptor.bytes = bytes.length
+    if ('sha256' in descriptor) descriptor.sha256 = createHash('sha256').update(bytes).digest('hex')
+    writes.push([path, chunk])
+  }
+  writes.push([manifestPath, { ...manifest, metadata: { ...manifest.metadata, routeEnrichment: metadata }, aircraft }])
+  snapshots.forEach((snapshot, index) => writes.push([snapshotPaths[index], { ...snapshot, metadata: { ...snapshot.metadata, routeEnrichment: metadata }, tracks: snapshot.tracks.map(enrich) }]))
+  for (const [path, value] of writes) await writeFile(path, `${JSON.stringify(value)}\n`)
+  return { tracks: aircraft.length, origins: aircraft.filter(track => track.origin).length, destinations: aircraft.filter(track => track.destination).length }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/data",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -23,6 +23,10 @@
     "node": ">=24.0.0"
   },
   "exports": {
+    "./air-endpoints": {
+      "types": "./air-endpoints.d.mts",
+      "import": "./air-endpoints.mjs"
+    },
     "./gtfs": {
       "types": "./gtfs.d.mts",
       "import": "./gtfs.mjs"
@@ -51,6 +55,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.3"
+    "@motionstudies/core": "0.1.0-alpha.5"
   }
 }