vehicle-path2 2.4.0 → 3.0.1

package/README.md

@@ -1,6 +1,6 @@
 # vehicle-path2
 
-Library untuk simulasi pergerakan kendaraan dual-axle sepanjang jalur.
+Library untuk simulasi pergerakan kendaraan multi-axle sepanjang jalur yang terdiri dari Lines dan Curves.
 
 ## Instalasi
 
@@ -8,161 +8,282 @@ Library untuk simulasi pergerakan kendaraan dual-axle sepanjang jalur.
 npm install vehicle-path2
 ```
 
-## Quick Start
+## Konsep Dasar
 
-```tsx
-import { useVehicleSimulation } from 'vehicle-path2/react'
+- **Line** — segmen garis lurus antara dua titik. Kendaraan bergerak di atas line.
+- **Curve** — koneksi antara dua line. Berbentuk kurva bezier, menghubungkan ujung satu line ke awal line berikutnya.
+- **Vehicle** — kendaraan dengan N axle yang ditempatkan di atas sebuah line. Library tidak menyimpan daftar vehicle — itu tanggung jawab client.
 
-function App() {
-  const sim = useVehicleSimulation({ wheelbase: 30 })
+Titik acuan kendaraan adalah **axle paling belakang** (`axles[N-1]`). Semua axle lainnya dihitung ke depan berdasarkan `axleSpacings`.
 
-  // Buat jalur
-  sim.addLine({ id: 'line1', start: [0, 0], end: [400, 0] })
-  sim.addLine({ id: 'line2', start: [400, 0], end: [400, 300] })
-  sim.connect('line1', 'line2')
+---
 
-  // Tambah kendaraan
-  sim.addVehicles({ id: 'v1', lineId: 'line1', position: 0 })
+## Setup
 
-  // Gerakkan ke tujuan
-  sim.goto({ id: 'v1', lineId: 'line2', position: 1.0 })
+```typescript
+import { PathEngine } from 'vehicle-path2/core'
 
-  // Jalankan animasi
-  sim.prepare()
-  sim.tick(5) // panggil di animation loop
-}
+const engine = new PathEngine({
+  maxWheelbase: 100,              // batas maksimum total panjang kendaraan
+  tangentMode: 'proportional-40' // mode kurva bezier
+})
 ```
 
-## API
+---
 
-### Format Posisi
+## Manajemen Scene
 
-Semua nilai posisi menggunakan format **0-1** untuk persentase:
-- `0` = 0% (awal line)
-- `0.5` = 50% (tengah line)
-- `1` = 100% (ujung line)
+### Lines
 
-Untuk posisi absolut (dalam satuan koordinat), gunakan `isPercentage: false`.
+```typescript
+// Tambah line
+engine.addLine({ id: 'L1', start: { x: 0, y: 0 }, end: { x: 400, y: 0 } })
+// → false jika ID sudah ada
 
-### Setup
+// Update posisi titik
+engine.updateLine('L1', { end: { x: 500, y: 0 } })
+engine.updateLineEndpoint('L1', 'start', { x: 10, y: 0 })
 
-```ts
-const sim = useVehicleSimulation({
-  wheelbase: 30,                    // jarak antar roda
-  tangentMode: 'proportional-40'    // mode kurva (opsional)
-})
-```
+// Rename — cascade: semua curve yang referensi 'L1' otomatis diupdate ke 'L1-new'
+engine.renameLine('L1', 'L1-new')
+// → { success: true } atau { success: false, error: '...' }
 
-### Scene
+// Hapus — cascade: semua curve yang terhubung ke line ini ikut dihapus
+engine.removeLine('L1')
 
-```ts
-sim.addLine({ id: 'line1', start: [0, 0], end: [400, 0] })
-sim.updateLine('line1', { end: [500, 100] })
-sim.removeLine('line1')
-sim.clearScene()
+// Baca semua lines
+engine.lines // → Line[]
 ```
 
-### Koneksi
+> **Konsekuensi `removeLine`:** Semua curve yang `fromLineId` atau `toLineId`-nya adalah line tersebut akan otomatis ikut dihapus.
+
+> **Konsekuensi `renameLine`:** Semua curve yang `fromLineId` atau `toLineId`-nya adalah ID lama otomatis diupdate ke ID baru. Graph di-rebuild secara otomatis.
+
+---
+
+### Curves
+
+Curve menghubungkan **ujung satu line** ke **awal line lain**. Tidak bisa berdiri sendiri — harus selalu mereferensi dua line yang valid.
 
-```ts
-sim.connect('line1', 'line2')
-sim.connect('line1', 'line2', { fromOffset: 0.8, toOffset: 0.2 })
-sim.connect('line1', 'line2', { fromOffset: 150, fromIsPercentage: false, toOffset: 50, toIsPercentage: false })
-sim.updateConnection('line1', 'line2', { fromOffset: 0.5 })              // update offset
-sim.updateConnection('line1', 'line2', { toOffset: 100, toIsPercentage: false }) // absolute
-sim.disconnect('line1', 'line2')
+```typescript
+import type { Curve } from 'vehicle-path2/core'
+
+// Tambah curve
+engine.addCurve({
+  fromLineId: 'L1',
+  toLineId: 'L2',
+  fromOffset: 380,        // posisi di L1 (px dari start)
+  fromIsPercentage: false,
+  toOffset: 20,           // posisi di L2 (px dari start)
+  toIsPercentage: false,
+} as Curve)
+
+// Atau dengan offset persentase (0–1)
+engine.addCurve({
+  fromLineId: 'L1',
+  toLineId: 'L2',
+  fromOffset: 0.95,
+  fromIsPercentage: true,
+  toOffset: 0.05,
+  toIsPercentage: true,
+} as Curve)
+
+// Update curve berdasarkan index
+engine.updateCurve(0, { fromOffset: 0.9 })
+
+// Hapus curve berdasarkan index
+engine.removeCurve(0)
+
+// Baca semua curves
+engine.getCurves() // → Curve[]
 ```
 
-### Kendaraan
+> **Catatan:** Curve diidentifikasi via **array index** (bukan named ID). Gunakan `getCurves()` lalu cari index yang sesuai sebelum update/delete.
+
+> **Konsekuensi `removeLine`:** Curve yang terhubung ke line yang dihapus otomatis ikut terhapus, sehingga index curve-curve lainnya bisa bergeser.
+
+---
 
-```ts
-sim.addVehicles({ id: 'v1', lineId: 'line1', position: 0 })
-sim.addVehicles({ id: 'v2', lineId: 'line1', position: 150, isPercentage: false }) // absolute
-sim.updateVehicle('v1', { position: 0.5 })                    // pindah ke 50%
-sim.updateVehicle('v1', { lineId: 'line2' })                  // pindah ke line lain
-sim.updateVehicle('v1', { lineId: 'line2', position: 0.8 })   // pindah ke 80% di line2
-sim.removeVehicle('v1')
-sim.clearVehicles()
+### Muat Scene Sekaligus
+
+```typescript
+// Replace seluruh scene secara atomik
+engine.setScene(lines, curves)
 ```
 
-### Pergerakan
+---
+
+## Vehicle
+
+Library menyediakan tipe dasar `VehicleDefinition`. Client bebas extend dengan field tambahan (id, name, color, dsb).
+
+```typescript
+import type { VehicleDefinition } from 'vehicle-path2/core'
+
+// Definisi minimal
+const def: VehicleDefinition = { axleSpacings: [40] } // 2 axle, jarak 40px
+
+// Client extend sesuai kebutuhan
+interface MyVehicle extends VehicleDefinition {
+  id: string
+  name: string
+}
 
-```ts
-sim.goto({ id: 'v1', lineId: 'line2' })                // default position = 1.0 (ujung)
-sim.goto({ id: 'v1', lineId: 'line2', position: 0.5 }) // 0.5 = tengah line
-sim.goto({ id: 'v1', lineId: 'line2', position: 150, isPercentage: false }) // absolute
-sim.goto({ id: 'v1', lineId: 'line2', payload: { orderId: '123' } })        // dengan payload
-sim.clearQueue('v1')
+const truck: MyVehicle = { id: 'v1', name: 'Truck A', axleSpacings: [40, 40] } // 3 axle
 ```
 
-### Animasi
+> `axleSpacings[i]` = jarak arc-length antara `axles[i]` dan `axles[i+1]`. Array harus memiliki minimal 1 entry.
 
-```ts
-sim.prepare()              // siapkan sebelum animasi
-sim.tick(5)                // gerakkan 5 pixel per tick
-sim.reset()                // kembali ke posisi awal
-sim.isMoving()             // cek ada yang bergerak
-sim.continueVehicle('v1')  // lanjutkan vehicle yang wait
+---
+
+## Pergerakan Kendaraan
+
+Tiga method berikut digunakan secara berurutan:
+
+### 1. `initializeVehicle` — Tempatkan kendaraan
+
+Hitung posisi awal semua axle di atas sebuah line.
+
+```typescript
+const state = engine.initializeVehicle(
+  'L1',    // lineId: line tempat kendaraan ditempatkan
+  0,       // rearOffset: jarak dari start line ke axle paling belakang (px)
+  truck    // VehicleDefinition (atau object yang extends-nya)
+)
+
+// state → VehiclePathState | null (null jika lineId tidak ditemukan)
+// state.axles[0]   = axle terdepan
+// state.axles[N-1] = axle paling belakang (titik acuan)
+// state.axleSpacings = [40, 40]
 ```
 
-### Load dari DSL
+### 2. `preparePath` — Tentukan tujuan
+
+Jalankan Dijkstra untuk mencari rute dari posisi saat ini ke tujuan. Dipanggil **sekali** sebelum animasi dimulai.
 
-```ts
-sim.loadFromDSL(`
-  line1 : (0, 0) -> (400, 0)
-  line2 : (400, 0) -> (400, 300)
-  line1 -> line2
-`)
+```typescript
+const execution = engine.preparePath(
+  state,    // posisi vehicle sekarang (dari initializeVehicle atau tick sebelumnya)
+  'L3',     // targetLineId: line tujuan
+  0.5,      // targetOffset: posisi di line tujuan
+  true      // isPercentage: true = 50% dari panjang line, false = nilai absolut (px)
+)
+
+// execution → PathExecution | null (null jika tidak ada rute)
 ```
 
-### State
+### 3. `moveVehicle` — Jalankan per tick
+
+Dipanggil setiap frame di animation loop. Mengembalikan posisi baru semua axle.
+
+```typescript
+const result = engine.moveVehicle(
+  state,      // posisi vehicle sekarang
+  execution,  // rencana rute (dari preparePath)
+  speed * deltaTime  // jarak yang ditempuh di frame ini (px)
+)
+
+state = result.state         // posisi baru → simpan untuk tick berikutnya
+execution = result.execution // progress terbaru → simpan untuk tick berikutnya
 
-```ts
-sim.lines          // semua line
-sim.curves         // semua koneksi
-sim.vehicles       // kendaraan (posisi awal)
-sim.movingVehicles // kendaraan (posisi saat animasi)
+if (result.arrived) {
+  // Kendaraan sudah sampai tujuan
+}
 ```
 
-## Contoh Lengkap
+---
+
+### Contoh Lengkap: Animation Loop
+
+```typescript
+import { PathEngine } from 'vehicle-path2/core'
+import type { VehiclePathState, PathExecution } from 'vehicle-path2/core'
+
+const engine = new PathEngine({ maxWheelbase: 100, tangentMode: 'proportional-40' })
 
-```tsx
-import { useVehicleSimulation } from 'vehicle-path2/react'
-import { useEffect } from 'react'
+engine.setScene(
+  [
+    { id: 'L1', start: { x: 0,   y: 0 }, end: { x: 400, y: 0 } },
+    { id: 'L2', start: { x: 400, y: 0 }, end: { x: 400, y: 300 } },
+  ],
+  [
+    { fromLineId: 'L1', toLineId: 'L2', fromOffset: 1.0, fromIsPercentage: true, toOffset: 0.0, toIsPercentage: true }
+  ]
+)
 
-function AnimatedVehicle() {
-  const sim = useVehicleSimulation({ wheelbase: 30 })
+// Client mengelola data vehicle sendiri
+const myVehicle = { id: 'v1', name: 'Truck', axleSpacings: [40] }
 
-  useEffect(() => {
-    sim.addLine({ id: 'line1', start: [100, 100], end: [500, 100] })
-    sim.addVehicles({ id: 'v1', lineId: 'line1', position: 0 })
-    sim.goto({ id: 'v1', lineId: 'line1', position: 1.0 })
-    sim.prepare()
+// 1. Tempatkan di L1, axle belakang di posisi 0
+let state: VehiclePathState = engine.initializeVehicle('L1', 0, myVehicle)!
 
-    const animate = () => {
-      if (sim.tick(3)) {
-        requestAnimationFrame(animate)
-      }
-    }
+// 2. Tentukan tujuan: ujung L2
+let execution: PathExecution = engine.preparePath(state, 'L2', 1.0, true)!
+
+const speed = 80 // px/detik
+let lastTime = performance.now()
+
+function animate() {
+  const now = performance.now()
+  const deltaTime = (now - lastTime) / 1000 // dalam detik
+  lastTime = now
+
+  // 3. Gerakkan vehicle setiap frame
+  const result = engine.moveVehicle(state, execution, speed * deltaTime)
+  state = result.state
+  execution = result.execution
+
+  // Render semua axle
+  for (const axle of state.axles) {
+    drawCircle(axle.position.x, axle.position.y)
+  }
+
+  if (!result.arrived) {
     requestAnimationFrame(animate)
-  }, [])
-
-  return (
-    <svg width={600} height={200}>
-      {sim.movingVehicles.map(v => (
-        <circle
-          key={v.id}
-          cx={v.rear.position.x}
-          cy={v.rear.position.y}
-          r={10}
-          fill="blue"
-        />
-      ))}
-    </svg>
-  )
+  }
 }
+
+requestAnimationFrame(animate)
 ```
 
+---
+
+## Serialisasi Scene
+
+Hanya lines dan curves yang di-serialize oleh library. **Vehicle tidak termasuk** — persistensi vehicle adalah tanggung jawab client.
+
+```typescript
+import { serializeScene, deserializeScene } from 'vehicle-path2/core'
+
+// Simpan scene ke JSON string
+const json = serializeScene(engine.lines, engine.getCurves())
+
+// Muat kembali
+const snapshot = deserializeScene(json)
+engine.setScene(snapshot.lines, snapshot.curves)
+```
+
+---
+
+## Geometry Utilities
+
+```typescript
+import { projectPointOnLine, getValidRearOffsetRange, computeMinLineLength } from 'vehicle-path2/core'
+
+// Proyeksikan mouse/pointer ke garis — berguna untuk hit detection
+const { offset, distance } = projectPointOnLine({ x: 150, y: 10 }, line)
+// offset   = jarak dari start line ke titik proyeksi (px)
+// distance = jarak tegak lurus dari point ke garis (px)
+
+// Hitung range offset yang valid untuk axle belakang agar semua axle muat di line
+const [min, max] = getValidRearOffsetRange(line, myVehicle.axleSpacings)
+
+// Hitung panjang minimum sebuah line agar semua curve offset-nya tidak keluar batas
+const minLen = computeMinLineLength('L1', engine.getCurves())
+```
+
+---
+
 ## License
 
 MIT

package/dist/core/algorithms/acceleration.d.ts

@@ -0,0 +1,75 @@
+import type { VehiclePathState, PathExecution } from '../engine';
+import type { Line } from '../types/geometry';
+/**
+ * Konfigurasi acceleration/deceleration untuk vehicle.
+ * Nilai-nilai ini bersifat global (sama untuk semua segmen path).
+ */
+export interface AccelerationConfig {
+    /** px/s² — laju percepatan dari berhenti menuju maxSpeed */
+    acceleration: number;
+    /** px/s² — laju perlambatan (digunakan untuk curve dan arrival) */
+    deceleration: number;
+    /** px/s — kecepatan maksimum di garis lurus */
+    maxSpeed: number;
+    /** px/s — kecepatan minimum saat memasuki curve (tidak berhenti total) */
+    minCurveSpeed: number;
+}
+/**
+ * State kecepatan kendaraan saat ini.
+ * Caller menyimpan ini di luar dan meneruskan ke setiap tick.
+ */
+export interface AccelerationState {
+    /** Kecepatan kendaraan saat ini dalam px/s */
+    currentSpeed: number;
+}
+/**
+ * Hitung jarak tersisa dari posisi rear axle ke akhir path (tujuan).
+ */
+export declare function computeRemainingToArrival(execution: PathExecution): number;
+/**
+ * Hitung jarak dari posisi front axle ke awal segment curve berikutnya di path.
+ * Return 0 jika front axle sudah berada di dalam curve.
+ * Return null jika tidak ada curve lagi di depan.
+ *
+ * Menggunakan front axle (axleExecutions[0]) sebagai referensi — karena deceleration
+ * harus selesai (mencapai minCurveSpeed) tepat saat front axle secara visual memasuki
+ * curve. Jika menggunakan rear axle, kendaraan baru melambat setelah front axle
+ * sudah masuk curve.
+ */
+export declare function computeDistToNextCurve(execution: PathExecution): number | null;
+/**
+ * Hitung target speed berdasarkan lookahead jarak ke arrival dan curve.
+ *
+ * Menggunakan formula fisika: v = sqrt(2 * a * d)
+ * - Arrival: target = sqrt(2 * decel * distToArrival) → berhenti di tujuan
+ * - Curve: target = sqrt(minCurveSpeed² + 2 * decel * distToNextCurve) → capai minCurveSpeed di curve
+ * - Batas atas: maxSpeed
+ */
+export declare function computeTargetSpeed(distToArrival: number, distToNextCurve: number | null, config: AccelerationConfig): number;
+/**
+ * Sesuaikan kecepatan saat ini menuju target dengan laju acceleration/deceleration.
+ */
+export declare function approachSpeed(current: number, target: number, acceleration: number, deceleration: number, deltaTime: number): number;
+/**
+ * Gerakkan vehicle per tick dengan efek acceleration dan deceleration.
+ *
+ * Versi eksperimental dari PathEngine.moveVehicle yang menambahkan:
+ * - Startup acceleration: kendaraan mulai dari berhenti dan mempercepat
+ * - Pre-curve deceleration: melambat sebelum memasuki curve
+ * - Arrival deceleration: melambat hingga berhenti total di tujuan
+ *
+ * Tidak memodifikasi PathEngine atau moveVehicle yang sudah ada.
+ *
+ * @param state      - Posisi vehicle saat ini
+ * @param execution  - Rencana rute (dari preparePath atau tick sebelumnya)
+ * @param accelState - State kecepatan saat ini (simpan antar tick)
+ * @param config     - Parameter acceleration/deceleration
+ * @param deltaTime  - Durasi frame dalam detik (misal: 1/60 untuk 60fps)
+ * @param linesMap   - Map dari line ID ke Line object (buat dari engine.lines)
+ */
+export declare function moveVehicleWithAcceleration(state: VehiclePathState, execution: PathExecution, accelState: AccelerationState, config: AccelerationConfig, deltaTime: number, linesMap: Map<string, Line>): {
+    state: VehiclePathState;
+    execution: PathExecution;
+    accelState: AccelerationState;
+    arrived: boolean;
+};

package/dist/core/engine.d.ts

@@ -9,11 +9,11 @@
  * ```typescript
  * import { PathEngine } from 'vehicle-path/core'
  *
- * const engine = new PathEngine({ wheelbase: 30, tangentMode: 'proportional-40' })
+ * const engine = new PathEngine({ maxWheelbase: 100, tangentMode: 'proportional-40' })
  *
  * engine.setScene(lines, curves)
  *
- * const state = engine.initializeVehicle('line-1', 0)
+ * const state = engine.initializeVehicle('line-1', 0, { axleSpacings: [40] })
  * const execution = engine.preparePath(state, 'line-3', 1.0, true)
  *
  * // In your animation/game loop:
@@ -26,6 +26,7 @@
  * ```
  */
 import type { Line, Curve, Point } from './types/geometry';
+import type { VehicleDefinition } from './types/vehicle';
 import type { MovementConfig, CurveData } from './types/movement';
 import type { PathResult } from './algorithms/pathFinding';
 import type { TangentMode } from './types/config';
@@ -37,14 +38,12 @@ export interface PathEngineConfig {
  * Multi-axle position state for use with PathEngine.
  * axles[0] = terdepan, axles[N-1] = paling belakang.
  */
-export interface VehiclePathState {
+export interface VehiclePathState extends VehicleDefinition {
     axles: Array<{
         lineId: string;
         offset: number;
         position: Point;
     }>;
-    /** N-1 jarak arc-length antar axle berurutan */
-    axleSpacings: number[];
 }
 /**
  * Active path execution state for a vehicle in motion.
@@ -127,10 +126,11 @@ export declare class PathEngine {
      *
      * @param lineId - The line to place the vehicle on
      * @param rearOffset - Absolute distance offset untuk axle paling belakang
-     * @param axleSpacings - Jarak antar axle berurutan (N-1 nilai untuk N axle)
+     * @param vehicle - VehicleDefinition (or any object extending it with axleSpacings)
      * @returns Initial VehiclePathState, or null if lineId does not exist
+     * @throws if axleSpacings is empty
      */
-    initializeVehicle(lineId: string, rearOffset: number, axleSpacings: number[]): VehiclePathState | null;
+    initializeVehicle(lineId: string, rearOffset: number, vehicle: VehicleDefinition): VehiclePathState | null;
     /**
      * Prepare a path from the vehicle's current position to a target.
      *

package/dist/core/index.d.ts

@@ -11,7 +11,7 @@
  * ```
  */
 export type { Point, Line, BezierCurve, Curve } from './types/geometry';
-export type { VehicleState, VehicleStart, Vehicle, AxleState, GotoCommand, GotoCompletionInfo, GotoCompletionCallback } from './types/vehicle';
+export type { VehicleDefinition, VehicleState, VehicleStart, Vehicle, AxleState, GotoCommand, GotoCompletionInfo, GotoCompletionCallback } from './types/vehicle';
 export type { CurveData, AxleExecutionState, PathExecutionState, VehicleMovementState, MovementConfig, SceneContext } from './types/movement';
 export type { TangentMode } from './types/config';
 export type { CoordinateInput, SceneLineInput, SceneConnectionInput, SceneConfig, VehicleInput, VehicleUpdateInput, ConnectionUpdateInput, GotoCommandInput } from './types/api';
@@ -20,4 +20,5 @@ export { initializeMovingVehicle, createInitialMovementState, initializeAllVehic
 export { PathEngine, type PathEngineConfig, type VehiclePathState, type PathExecution } from './engine';
 export { distance, normalize, getPointOnLine, getPointOnLineByOffset, getPointOnBezier, createBezierCurve, buildArcLengthTable, distanceToT, getArcLength, calculateTangentLength, isPointNearPoint, type ArcLengthEntry, type CurveOffsetOptions } from './algorithms/math';
 export { serializeScene, deserializeScene, type SceneSnapshot } from './snapshot';
+export { moveVehicleWithAcceleration, computeRemainingToArrival, computeDistToNextCurve, computeTargetSpeed, approachSpeed, type AccelerationConfig, type AccelerationState } from './algorithms/acceleration';
 export { projectPointOnLine, getValidRearOffsetRange, computeMinLineLength } from './algorithms/geometry';

package/dist/core/snapshot.d.ts

@@ -10,24 +10,10 @@ export interface SceneSnapshot {
         toOffset: number;
         toIsPercentage: boolean;
     }>;
-    vehicles: Array<{
-        id: string;
-        lineId: string;
-        axles: Array<{
-            offset: number;
-        }>;
-        axleSpacings: number[];
-        isPercentage: boolean;
-    }>;
 }
 /**
- * Serialize scene state to a JSON string suitable for clipboard or storage.
- * Strips derived fields (bezier curves, axle positions) — only source-of-truth
- * data is included.
- *
- * Note: lineId is per-vehicle (not per-axle) because this snapshot captures
- * static placement where all axles share the same line. For mid-movement state,
- * use AxleState directly.
+ * Serialize scene state (lines + curves) to a JSON string.
+ * Vehicles are NOT included — vehicle persistence is the client's responsibility.
  */
 export declare function serializeScene(lines: Line[], curves: Array<{
     id: string;
@@ -37,18 +23,10 @@ export declare function serializeScene(lines: Line[], curves: Array<{
     fromIsPercentage?: boolean;
     toOffset: number;
     toIsPercentage?: boolean;
-}>, vehicles: Array<{
-    id: string;
-    axles: Array<{
-        lineId: string;
-        offset: number;
-        [key: string]: unknown;
-    }>;
-    axleSpacings: number[];
-    isPercentage?: boolean;
 }>): string;
 /**
  * Deserialize a JSON string back into a SceneSnapshot.
- * Throws if the string is not valid JSON or missing required fields.
+ * Throws if the string is not valid JSON or missing required fields (lines, curves).
+ * Extra fields in the JSON (e.g. legacy "vehicles") are silently ignored.
  */
 export declare function deserializeScene(json: string): SceneSnapshot;

package/dist/core/types/vehicle.d.ts

@@ -2,6 +2,17 @@
  * Vehicle-related types
  */
 import type { Point } from './geometry';
+/**
+ * Base definition of a vehicle's physical structure.
+ * Client code is free to extend this with additional fields (id, name, color, etc).
+ *
+ * @example
+ * interface MyVehicle extends VehicleDefinition { id: string; name: string }
+ */
+export interface VehicleDefinition {
+    /** N-1 arc-length spacings between consecutive axles. axleSpacings[i] = distance from axles[i] to axles[i+1]. */
+    axleSpacings: number[];
+}
 /**
  * Animation state for a vehicle
  */
@@ -28,14 +39,13 @@ export interface AxleState {
 /**
  * Vehicle with runtime state (used during animation)
  */
-export interface Vehicle {
+export interface Vehicle extends VehicleDefinition {
     id: string;
     lineId: string;
     offset: number;
     isPercentage: boolean;
     state: VehicleState;
     axles: AxleState[];
-    axleSpacings: number[];
 }
 /**
  * Command to move a vehicle to a target position

package/dist/core.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-BUYdltrL.cjs");function f(a,t,i){const r={lines:a,curves:t.map(n=>({id:n.id,fromLineId:n.fromLineId,toLineId:n.toLineId,fromOffset:n.fromOffset,fromIsPercentage:n.fromIsPercentage??!1,toOffset:n.toOffset,toIsPercentage:n.toIsPercentage??!1})),vehicles:i.map(n=>({id:n.id,lineId:n.axles[0].lineId,axles:n.axles.map(o=>({offset:o.offset})),axleSpacings:n.axleSpacings,isPercentage:n.isPercentage??!1}))};return JSON.stringify(r,null,2)}function g(a){let t;try{t=JSON.parse(a)}catch{throw new Error("deserializeScene: invalid JSON")}if(!t||typeof t!="object"||Array.isArray(t))throw new Error("deserializeScene: expected a JSON object");const i=t;if(!Array.isArray(i.lines))throw new Error('deserializeScene: missing "lines"');if(!Array.isArray(i.curves))throw new Error('deserializeScene: missing "curves"');if(!Array.isArray(i.vehicles))throw new Error('deserializeScene: missing "vehicles"');return{lines:i.lines,curves:i.curves,vehicles:i.vehicles}}function h(a,t){const i=t.end.x-t.start.x,r=t.end.y-t.start.y,n=i*i+r*r;if(n===0)return{offset:0,distance:Math.sqrt((a.x-t.start.x)**2+(a.y-t.start.y)**2)};const o=Math.max(0,Math.min(1,((a.x-t.start.x)*i+(a.y-t.start.y)*r)/n)),s=t.start.x+o*i,c=t.start.y+o*r,l=Math.sqrt((a.x-s)**2+(a.y-c)**2);return{offset:o*Math.sqrt(n),distance:l}}function d(a,t){const i=e.getLineLength(a),r=t.reduce((o,s)=>o+s,0);return[0,Math.max(0,i-r)]}function u(a,t){let i=0;for(const r of t)r.fromLineId===a&&!r.fromIsPercentage&&r.fromOffset!==void 0&&(i=Math.max(i,r.fromOffset)),r.toLineId===a&&!r.toIsPercentage&&r.toOffset!==void 0&&(i=Math.max(i,r.toOffset));return i}exports.PathEngine=e.PathEngine;exports.arcLengthToSegmentPosition=e.arcLengthToSegmentPosition;exports.buildArcLengthTable=e.buildArcLengthTable;exports.buildGraph=e.buildGraph;exports.calculateBezierArcLength=e.calculateBezierArcLength;exports.calculateFrontAxlePosition=e.calculateFrontAxlePosition;exports.calculateInitialAxlePositions=e.calculateInitialAxlePositions;exports.calculatePositionOnCurve=e.calculatePositionOnCurve;exports.calculatePositionOnLine=e.calculatePositionOnLine;exports.calculateTangentLength=e.calculateTangentLength;exports.createBezierCurve=e.createBezierCurve;exports.createInitialMovementState=e.createInitialMovementState;exports.distance=e.distance;exports.distanceToT=e.distanceToT;exports.findPath=e.findPath;exports.getArcLength=e.getArcLength;exports.getCumulativeArcLength=e.getCumulativeArcLength;exports.getLineLength=e.getLineLength;exports.getPointOnBezier=e.getPointOnBezier;exports.getPointOnLine=e.getPointOnLine;exports.getPointOnLineByOffset=e.getPointOnLineByOffset;exports.getPositionFromOffset=e.getPositionFromOffset;exports.handleArrival=e.handleArrival;exports.initializeAllVehicles=e.initializeAllVehicles;exports.initializeMovingVehicle=e.initializeMovingVehicle;exports.isPointNearPoint=e.isPointNearPoint;exports.moveVehicle=e.moveVehicle;exports.normalize=e.normalize;exports.prepareCommandPath=e.prepareCommandPath;exports.resolveFromLineOffset=e.resolveFromLineOffset;exports.resolveToLineOffset=e.resolveToLineOffset;exports.updateAxlePosition=e.updateAxlePosition;exports.computeMinLineLength=u;exports.deserializeScene=g;exports.getValidRearOffsetRange=d;exports.projectPointOnLine=h;exports.serializeScene=f;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("./index-C4FckUel.cjs");function P(n,e){const a={lines:n,curves:e.map(t=>({id:t.id,fromLineId:t.fromLineId,toLineId:t.toLineId,fromOffset:t.fromOffset,fromIsPercentage:t.fromIsPercentage??!1,toOffset:t.toOffset,toIsPercentage:t.toIsPercentage??!1}))};return JSON.stringify(a,null,2)}function O(n){let e;try{e=JSON.parse(n)}catch{throw new Error("deserializeScene: invalid JSON")}if(!e||typeof e!="object"||Array.isArray(e))throw new Error("deserializeScene: expected a JSON object");const a=e;if(!Array.isArray(a.lines))throw new Error('deserializeScene: missing "lines"');if(!Array.isArray(a.curves))throw new Error('deserializeScene: missing "curves"');return{lines:a.lines,curves:a.curves}}function h(n){const e=n.axleExecutions[n.axleExecutions.length-1],a=i.getCumulativeArcLength(n.path,e.segmentIndex,e.segmentDistance);return Math.max(0,n.path.totalDistance-a)}function d(n){const e=n.axleExecutions[0],a=i.getCumulativeArcLength(n.path,e.segmentIndex,e.segmentDistance);let t=0;for(let r=0;r<n.path.segments.length;r++){const o=n.path.segments[r];if(r>=e.segmentIndex&&o.type==="curve")return Math.max(0,t-a);t+=o.length}return null}function p(n,e,a){let t=a.maxSpeed;const r=Math.sqrt(2*a.deceleration*Math.max(0,n));if(t=Math.min(t,r),e!==null){const o=Math.sqrt(a.minCurveSpeed**2+2*a.deceleration*e);t=Math.min(t,o)}return Math.max(0,t)}function x(n,e,a,t,r){return n<e?Math.min(e,n+a*r):n>e?Math.max(e,n-t*r):n}function S(n,e,a,t,r,o){const c=h(e),l=d(e),f=p(c,l,t),g=x(a.currentSpeed,f,t.acceleration,t.deceleration,r),u=g*r,v=n.axles.map(s=>({lineId:s.lineId,position:s.position,absoluteOffset:s.offset})),L=e.axleExecutions.map(s=>({currentSegmentIndex:s.segmentIndex,segmentDistance:s.segmentDistance})),m=i.moveVehicle(v,L,e.path,u,o,e.curveDataMap);return{state:{axles:m.axles.map(s=>({lineId:s.lineId,offset:s.absoluteOffset,position:s.position})),axleSpacings:n.axleSpacings},execution:{...e,axleExecutions:m.axleExecutions.map(s=>({segmentIndex:s.currentSegmentIndex,segmentDistance:s.segmentDistance}))},accelState:{currentSpeed:g},arrived:m.arrived}}function A(n,e){const a=e.end.x-e.start.x,t=e.end.y-e.start.y,r=a*a+t*t;if(r===0)return{offset:0,distance:Math.sqrt((n.x-e.start.x)**2+(n.y-e.start.y)**2)};const o=Math.max(0,Math.min(1,((n.x-e.start.x)*a+(n.y-e.start.y)*t)/r)),c=e.start.x+o*a,l=e.start.y+o*t,f=Math.sqrt((n.x-c)**2+(n.y-l)**2);return{offset:o*Math.sqrt(r),distance:f}}function I(n,e){const a=i.getLineLength(n),t=e.reduce((o,c)=>o+c,0);return[0,Math.max(0,a-t)]}function M(n,e){let a=0;for(const t of e)t.fromLineId===n&&!t.fromIsPercentage&&t.fromOffset!==void 0&&(a=Math.max(a,t.fromOffset)),t.toLineId===n&&!t.toIsPercentage&&t.toOffset!==void 0&&(a=Math.max(a,t.toOffset));return a}exports.PathEngine=i.PathEngine;exports.arcLengthToSegmentPosition=i.arcLengthToSegmentPosition;exports.buildArcLengthTable=i.buildArcLengthTable;exports.buildGraph=i.buildGraph;exports.calculateBezierArcLength=i.calculateBezierArcLength;exports.calculateFrontAxlePosition=i.calculateFrontAxlePosition;exports.calculateInitialAxlePositions=i.calculateInitialAxlePositions;exports.calculatePositionOnCurve=i.calculatePositionOnCurve;exports.calculatePositionOnLine=i.calculatePositionOnLine;exports.calculateTangentLength=i.calculateTangentLength;exports.createBezierCurve=i.createBezierCurve;exports.createInitialMovementState=i.createInitialMovementState;exports.distance=i.distance;exports.distanceToT=i.distanceToT;exports.findPath=i.findPath;exports.getArcLength=i.getArcLength;exports.getCumulativeArcLength=i.getCumulativeArcLength;exports.getLineLength=i.getLineLength;exports.getPointOnBezier=i.getPointOnBezier;exports.getPointOnLine=i.getPointOnLine;exports.getPointOnLineByOffset=i.getPointOnLineByOffset;exports.getPositionFromOffset=i.getPositionFromOffset;exports.handleArrival=i.handleArrival;exports.initializeAllVehicles=i.initializeAllVehicles;exports.initializeMovingVehicle=i.initializeMovingVehicle;exports.isPointNearPoint=i.isPointNearPoint;exports.moveVehicle=i.moveVehicle;exports.normalize=i.normalize;exports.prepareCommandPath=i.prepareCommandPath;exports.resolveFromLineOffset=i.resolveFromLineOffset;exports.resolveToLineOffset=i.resolveToLineOffset;exports.updateAxlePosition=i.updateAxlePosition;exports.approachSpeed=x;exports.computeDistToNextCurve=d;exports.computeMinLineLength=M;exports.computeRemainingToArrival=h;exports.computeTargetSpeed=p;exports.deserializeScene=O;exports.getValidRearOffsetRange=I;exports.moveVehicleWithAcceleration=S;exports.projectPointOnLine=A;exports.serializeScene=P;