@motionstudies/data 0.1.0-alpha.8 → 0.1.0-alpha.9

package/README.md

@@ -179,3 +179,17 @@ See [service architecture and operations](../docs/LIVE-AIRPORTS.md). The Worker
 The same `decodeAdsbHeatmap` now powers `enrichAirEndpoints`; endpoint inference retains full coordinate precision, while playback compilation retains the existing five-decimal coordinates. `transportAirTracks` and `chunkAirSnapshot` are also available for consumers that assemble their own pipeline. All functions have public TypeScript declarations and work in the packed Node package.
 
 Editions supply geographic bounds, service date, explicit UTC offset, optional timezone, input files and output paths. Flight IDs and chunk overlap retain the existing contracts. The default splits known callsign changes and gaps over 30 minutes. Set `splitTracks: false` only when reproducing a legacy opening snapshot with one ID per aircraft. See [adoption and compatibility](../docs/AIR-DATA.md).
+
+## Shared edition controllers and performance
+
+`positionForTrain` now indexes chronological stop times with binary search and retains sequential behavior for unordered observations. Stop arrays are immutable: replace the array when a timetable changes. Arrival/departure boundaries, dwell, cancellation and backward seeking retain the existing contract.
+
+`countableVehicleTrains(network, stations, selection)` and `createActiveTimetableVehicleCounter(trains, options)` from `@motionstudies/core/domain/vehicle-counts` separate station/route/category membership from clock updates. Build the selector and counter with `useMemo` when data or selection changes, then call the counter at the displayed time. It includes both interval endpoints and excludes cancellations and inverted intervals. Missing stations yield no matches. By default it counts timetable intervals even if a journey lacks enough stops to position; `{ requirePositionable: true }` excludes journeys with fewer than two stops. This distinction is explicit so an edition can retain its established metric.
+
+The renderer now shares active GPU upload ranges, paused frame reuse, label and trail frame budgets, cached text comparators and batched hub lines. Custom layers can import the low-level helpers from `@motionstudies/three/render-performance`. Recreate frame trackers when their geometry/data/selection inputs change; `batchHubLines` takes ownership of two-vertex source line resources. Edition-specific worker transfer, picking and cartographic adapters remain consumer-owned.
+
+`useJsonAsset<T>(url, enabled, parse?, optional?)` from `@motionstudies/web/use-json-asset` loads a single asset lazily and exposes `data`, `loading`, `error`, `unavailable`, and `retry`. Keep the parser stable and perform edition-specific schema/source compatibility checks there. Successful data remains cached while disabled; consumers decide whether to display it. Changing the URL or parser immediately discards prior-source state, and disabling/unmounting cancels requests. `retry()` discards cached state and requests again when enabled. Optional HTTP 404 responses are unavailable; other failures are errors. No source fallback or freshness policy is inferred.
+
+`useTransitionValue(target, { durationMs, easing, steps })` from `@motionstudies/web/use-transition-value` animates a numeric value, returning `value` and `transitioning`. It reverses from the current frame, cancels on teardown, and settles immediately when reduced motion becomes active. `smoothTransition` is the default easing; `cosineTransition` and stepped progress support existing edition rhythms. Keep custom easing functions stable. Camera actions and lazy layout loading stay in the edition.
+
+Edition chunk scripts can call `runNetworkChunkCli()` from `@motionstudies/data/network-chunk-cli`. It accepts the existing `--input`, `--manifest`, `--opening`, `--chunk-hours`, `--opening-start`, `--opening-end`, and `--focus` arguments. Source acquisition, provenance, output paths and command invocation remain edition-owned.

package/network-chunk-cli.d.mts

@@ -0,0 +1 @@
+export function runNetworkChunkCli(argv?: readonly string[]): Promise<void>

package/network-chunk-cli.mjs

@@ -0,0 +1,65 @@
+import { chunkNetworkSnapshot, extractNetworkWindow } from './network-chunks.mjs'
+
+import { createWriteStream } from 'node:fs'
+import { mkdir, readFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+
+function argument(argv, name, fallback) {
+  const index = argv.indexOf(`--${name}`)
+  return index === -1 ? fallback : argv[index + 1]
+}
+
+function parseClock(value) {
+  const [hours, minutes = 0] = value.split(':').map(Number)
+  if (!Number.isFinite(hours) || !Number.isFinite(minutes)) {
+    throw new Error(`Invalid clock value ${value}`)
+  }
+  return hours * 3600 + minutes * 60
+}
+
+async function writeJson(filePath, value) {
+  await mkdir(dirname(filePath), { recursive: true })
+  await new Promise((resolvePromise, rejectPromise) => {
+    const output = createWriteStream(filePath)
+    output.once('error', rejectPromise)
+    output.once('finish', resolvePromise)
+    output.end(JSON.stringify(value))
+  })
+}
+
+export async function runNetworkChunkCli(argv = process.argv.slice(2)) {
+  const input = argument(argv, 'input')
+  const manifestOutput = argument(argv, 'manifest')
+  const openingOutput = argument(argv, 'opening')
+  if (!input || !manifestOutput || !openingOutput) {
+    throw new Error(
+      'Usage: node scripts/chunk-network-snapshot.mjs --input day.json --manifest day-manifest.json --opening morning.json [--chunk-hours 2] [--opening-start 06:45] [--opening-end 08:45] [--focus 07:45]',
+    )
+  }
+  const snapshot = JSON.parse(await readFile(resolve(input), 'utf8'))
+  const manifestPath = resolve(manifestOutput)
+  const outputDirectory = dirname(manifestPath)
+  const outputStem = basename(manifestPath, extname(manifestPath)).replace(/-manifest$/, '')
+  const chunkDirectoryName = `${outputStem}-chunks`
+  const { manifest, chunks } = chunkNetworkSnapshot(
+    snapshot,
+    Number(argument(argv, 'chunk-hours', '2')) * 3600,
+    chunkDirectoryName,
+  )
+  const opening = extractNetworkWindow(
+    snapshot,
+    parseClock(argument(argv, 'opening-start', '06:45')),
+    parseClock(argument(argv, 'opening-end', '08:45')),
+    parseClock(argument(argv, 'focus', '07:45')),
+  )
+  await Promise.all([
+    writeJson(manifestPath, manifest),
+    writeJson(resolve(openingOutput), opening),
+    ...chunks.map(({ descriptor, payload }) =>
+      writeJson(join(outputDirectory, descriptor.path), payload),
+    ),
+  ])
+  console.log(
+    `Wrote ${manifestOutput}, ${chunks.length} progressive chunks and ${opening.trains.length} opening journeys.`,
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/data",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "private": false,
   "type": "module",
   "description": "Offline data preparation primitives for Motion Studies.",
@@ -46,6 +46,10 @@
     "./merge-network": {
       "types": "./merge-network.d.mts",
       "import": "./merge-network.mjs"
+    },
+    "./network-chunk-cli": {
+      "types": "./network-chunk-cli.d.mts",
+      "import": "./network-chunk-cli.mjs"
     }
   },
   "files": [
@@ -59,6 +63,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@motionstudies/core": "0.1.0-alpha.8"
+    "@motionstudies/core": "0.1.0-alpha.9"
   }
 }