vehicle-path2 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+# vehicle-path2
+
+Library untuk simulasi pergerakan kendaraan dual-axle sepanjang jalur.
+
+## Instalasi
+
+```bash
+npm install vehicle-path2
+```
+
+## Quick Start
+
+```tsx
+import { useVehicleSimulation } from 'vehicle-path2/react'
+
+function App() {
+  const sim = useVehicleSimulation({ wheelbase: 30 })
+
+  // 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 })
+
+  // Gerakkan ke tujuan
+  sim.goto({ id: 'v1', lineId: 'line2', position: 1.0 })
+
+  // Jalankan animasi
+  sim.prepare()
+  sim.tick(5) // panggil di animation loop
+}
+```
+
+## API
+
+### Setup
+
+```ts
+const sim = useVehicleSimulation({
+  wheelbase: 30,                    // jarak antar roda
+  tangentMode: 'proportional-40'    // mode kurva (opsional)
+})
+```
+
+### Scene
+
+```ts
+sim.addLine({ id: 'line1', start: [0, 0], end: [400, 0] })
+sim.updateLine('line1', { end: [500, 100] })
+sim.removeLine('line1')
+sim.clearScene()
+```
+
+### Koneksi
+
+```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')
+```
+
+### Kendaraan
+
+```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()
+```
+
+### Pergerakan
+
+```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', position: 0.5, wait: true })          // berhenti di tujuan
+sim.goto({ id: 'v1', lineId: 'line2', payload: { orderId: '123' } })        // dengan payload
+sim.clearQueue('v1')
+```
+
+### Animasi
+
+```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
+```
+
+### Load dari DSL
+
+```ts
+sim.loadFromDSL(`
+  line1 : (0, 0) -> (400, 0)
+  line2 : (400, 0) -> (400, 300)
+  line1 -> line2
+`)
+```
+
+### State
+
+```ts
+sim.lines          // semua line
+sim.curves         // semua koneksi
+sim.vehicles       // kendaraan (posisi awal)
+sim.movingVehicles // kendaraan (posisi saat animasi)
+```
+
+## Contoh Lengkap
+
+```tsx
+import { useVehicleSimulation } from 'vehicle-path2/react'
+import { useEffect } from 'react'
+
+function AnimatedVehicle() {
+  const sim = useVehicleSimulation({ wheelbase: 30 })
+
+  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()
+
+    const animate = () => {
+      if (sim.tick(3)) {
+        requestAnimationFrame(animate)
+      }
+    }
+    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>
+  )
+}
+```
+
+## License
+
+MIT

package/dist/animation-loop-bZEm2pMN.js

@@ -0,0 +1,37 @@
+import { useRef as p, useEffect as d } from "react";
+function A(o) {
+  const { onTick: t, onComplete: a, onStart: i, onPause: c, onStop: f } = o;
+  let n = null, u = null, e = !1, l = !1;
+  const s = (r) => {
+    if (!e) return;
+    const m = u !== null ? r - u : 0;
+    if (u = r, t(m) === !1) {
+      e = !1, n = null, u = null, a?.();
+      return;
+    }
+    n = requestAnimationFrame(s);
+  };
+  return {
+    start: () => {
+      e || (e = !0, l = !1, u = null, i?.(), n = requestAnimationFrame(s));
+    },
+    pause: () => {
+      !e || l || (e = !1, l = !0, n !== null && (cancelAnimationFrame(n), n = null), c?.());
+    },
+    stop: () => {
+      e = !1, l = !1, u = null, n !== null && (cancelAnimationFrame(n), n = null), f?.();
+    },
+    isRunning: () => e,
+    isPaused: () => l
+  };
+}
+function q(o) {
+  const t = p(null);
+  return t.current || (t.current = A(o)), d(() => () => {
+    t.current?.stop();
+  }, []), t.current;
+}
+export {
+  A as c,
+  q as u
+};

package/dist/animation-loop-fC2LjxCd.cjs

@@ -0,0 +1 @@
+"use strict";const i=require("react");function a(s){const{onTick:t,onComplete:c,onStart:f,onPause:m,onStop:p}=s;let n=null,o=null,e=!1,u=!1;const l=r=>{if(!e)return;const A=o!==null?r-o:0;if(o=r,t(A)===!1){e=!1,n=null,o=null,c?.();return}n=requestAnimationFrame(l)};return{start:()=>{e||(e=!0,u=!1,o=null,f?.(),n=requestAnimationFrame(l))},pause:()=>{!e||u||(e=!1,u=!0,n!==null&&(cancelAnimationFrame(n),n=null),m?.())},stop:()=>{e=!1,u=!1,o=null,n!==null&&(cancelAnimationFrame(n),n=null),p?.()},isRunning:()=>e,isPaused:()=>u}}function d(s){const t=i.useRef(null);return t.current||(t.current=a(s)),i.useEffect(()=>()=>{t.current?.stop()},[]),t.current}exports.createAnimationLoop=a;exports.useAnimationLoop=d;

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

@@ -0,0 +1,35 @@
+import type { Point, Line, BezierCurve } from '../types/geometry';
+import type { TangentMode } from '../types/config';
+import type { MovementConfig } from '../types/movement';
+export declare function distance(p1: Point, p2: Point): number;
+export declare function normalize(p1: Point, p2: Point): Point;
+export declare function calculateTangentLength(mode: TangentMode, distance: number): number;
+export interface CurveOffsetOptions {
+    fromOffset?: number;
+    fromIsPercentage?: boolean;
+    toOffset?: number;
+    toIsPercentage?: boolean;
+}
+export declare function createBezierCurve(line: Line, nextLine: Line, config: MovementConfig, willFlip?: boolean, offsetOptions?: CurveOffsetOptions): BezierCurve;
+export declare function getPointOnLine(line: Line, t: number): Point;
+export declare function getPointOnLineByOffset(line: Line, offset: number, isPercentage: boolean): Point;
+export declare function getPointOnBezier(bezier: BezierCurve, t: number): Point;
+export declare function isPointNearPoint(p1: Point, p2: Point, threshold?: number): boolean;
+export interface ArcLengthEntry {
+    t: number;
+    distance: number;
+}
+/**
+ * Build a lookup table for arc-length parameterization.
+ * Maps t values to cumulative distances along the curve.
+ */
+export declare function buildArcLengthTable(bezier: BezierCurve, samples?: number): ArcLengthEntry[];
+/**
+ * Convert a distance along the curve to the corresponding t parameter.
+ * Uses linear interpolation between table entries for smooth results.
+ */
+export declare function distanceToT(table: ArcLengthEntry[], targetDistance: number): number;
+/**
+ * Get the total arc length from a pre-built table
+ */
+export declare function getArcLength(table: ArcLengthEntry[]): number;

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

@@ -0,0 +1,62 @@
+import type { Line, Curve, BezierCurve } from '../types/geometry';
+import type { MovementConfig } from '../types/movement';
+export interface GraphEdge {
+    curveIndex: number;
+    fromLineId: string;
+    toLineId: string;
+    fromOffset: number;
+    toOffset: number;
+    curveLength: number;
+}
+export interface Graph {
+    adjacency: Map<string, GraphEdge[]>;
+    lines: Map<string, Line>;
+    lineLengths: Map<string, number>;
+}
+export interface PathSegment {
+    type: 'line' | 'curve';
+    lineId?: string;
+    curveIndex?: number;
+    startOffset: number;
+    endOffset: number;
+    length: number;
+}
+export interface PathResult {
+    segments: PathSegment[];
+    totalDistance: number;
+}
+export interface VehiclePosition {
+    lineId: string;
+    offset: number;
+}
+/**
+ * Menghitung arc length dari bezier curve menggunakan numerical integration
+ */
+export declare function calculateBezierArcLength(bezier: BezierCurve, segments?: number): number;
+/**
+ * Resolve offset untuk FROM line (garis asal kurva)
+ * - 0% → wheelbase (bukan 0, untuk memberi ruang vehicle)
+ * - 100% → lineLength (ujung garis)
+ *
+ * Effective range: [wheelbase, lineLength]
+ */
+export declare function resolveFromLineOffset(line: Line, offset: number | undefined, isPercentage: boolean | undefined, defaultPercentage: number, wheelbase: number): number;
+/**
+ * Resolve offset untuk TO line (garis tujuan kurva)
+ * - 0% → 0 (awal garis)
+ * - 100% → lineLength - wheelbase (untuk memberi ruang vehicle)
+ *
+ * Effective range: [0, lineLength - wheelbase]
+ */
+export declare function resolveToLineOffset(line: Line, offset: number | undefined, isPercentage: boolean | undefined, defaultPercentage: number, wheelbase: number): number;
+/**
+ * Membangun graph dari lines dan curves
+ */
+export declare function buildGraph(lines: Line[], curves: Curve[], config: MovementConfig): Graph;
+/**
+ * Mencari path terpendek dari posisi vehicle ke target
+ *
+ * @returns PathResult jika path ditemukan, null jika tidak ada path valid
+ */
+export declare function findPath(graph: Graph, vehiclePos: VehiclePosition, targetLineId: string, targetOffset: number, // Absolute offset
+targetIsPercentage?: boolean): PathResult | null;

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

@@ -0,0 +1,174 @@
+/**
+ * Vehicle Movement Module
+ *
+ * Handles dual-axle vehicle movement including:
+ * - Position calculations (line and curve)
+ * - Arc-length tracking for wheelbase
+ * - Path preparation and execution
+ * - Segment transitions
+ */
+import type { Line, Point, Curve } from '../types/geometry';
+import type { Vehicle, AxleState, GotoCommand, GotoCompletionCallback } from '../types/vehicle';
+import type { VehicleMovementState, PathExecutionState, AxleExecutionState, CurveData, SceneContext, MovementConfig } from '../types/movement';
+import type { PathResult } from './pathFinding';
+import type { CommandStartInfo } from '../../utils/event-emitter';
+export type { CurveData, PathExecutionState, VehicleMovementState } from '../types/movement';
+/**
+ * Get position on line from absolute offset
+ * This is a pure function that converts absolute offset to Point coordinates
+ */
+export declare function getPositionFromOffset(line: Line, absoluteOffset: number): Point;
+/**
+ * Calculate line length
+ */
+export declare function getLineLength(line: Line): number;
+/**
+ * Calculate cumulative arc-length from start of path
+ *
+ * @param path - The path being followed
+ * @param segmentIndex - Current segment index
+ * @param segmentDistance - Distance along current segment
+ * @returns Total arc-length from path start
+ */
+export declare function getCumulativeArcLength(path: PathResult, segmentIndex: number, segmentDistance: number): number;
+/**
+ * Convert arc-length to segment position
+ *
+ * @param path - The path being followed
+ * @param targetArcLength - Target cumulative arc-length
+ * @returns Segment position or null if exceeds path length
+ */
+export declare function arcLengthToSegmentPosition(path: PathResult, targetArcLength: number): {
+    segmentIndex: number;
+    segmentDistance: number;
+} | null;
+/**
+ * Calculate front axle position from rear position + wheelbase
+ *
+ * @param path - The path being followed
+ * @param rearSegmentIndex - Rear axle segment index
+ * @param rearSegmentDistance - Rear axle distance in segment
+ * @param wheelbase - Distance between front and rear axles
+ * @returns Front axle position or null if exceeds path
+ */
+export declare function calculateFrontAxlePosition(path: PathResult, rearSegmentIndex: number, rearSegmentDistance: number, wheelbase: number): {
+    segmentIndex: number;
+    segmentDistance: number;
+} | null;
+/**
+ * Calculate initial front axle position from rear position
+ *
+ * @param rLineId - Rear axle line ID
+ * @param rAbsoluteOffset - Rear axle absolute offset on line
+ * @param wheelbase - Distance between front and rear axles
+ * @param line - The line the vehicle is on
+ * @returns Front axle state
+ */
+export declare function calculateInitialFrontPosition(rLineId: string, rAbsoluteOffset: number, wheelbase: number, line: Line): AxleState;
+/**
+ * Initialize Vehicle with runtime state for dual-axle
+ *
+ * @param vehicle - Vehicle to initialize (must have rear and front already populated)
+ * @param _line - The line (kept for compatibility)
+ * @returns Vehicle with state set to idle
+ */
+export declare function initializeMovingVehicle(vehicle: Vehicle, _line: Line): Vehicle;
+/**
+ * Create initial movement state for a vehicle
+ */
+export declare function createInitialMovementState(vehicle: Vehicle): VehicleMovementState;
+export interface InitializationResult {
+    movingVehicles: Vehicle[];
+    stateMap: Map<string, VehicleMovementState>;
+}
+/**
+ * Initialize all vehicles and their movement states
+ *
+ * @param vehicles - Array of vehicles to initialize
+ * @param linesMap - Map of line IDs to Line objects
+ * @returns InitializationResult with moving vehicles and state map
+ */
+export declare function initializeAllVehicles(vehicles: Vehicle[], linesMap: Map<string, Line>): InitializationResult;
+/**
+ * Calculate position on line (pure function)
+ *
+ * @param line - The line to calculate position on
+ * @param absoluteOffset - The offset along the line
+ * @returns Position data
+ */
+export declare function calculatePositionOnLine(line: Line, absoluteOffset: number): {
+    position: Point;
+    lineId: string;
+    absoluteOffset: number;
+};
+/**
+ * Calculate position on curve (pure function)
+ *
+ * @param curveData - The curve data with arc-length table
+ * @param segmentDistance - Distance along the curve
+ * @returns Position data
+ */
+export declare function calculatePositionOnCurve(curveData: CurveData, segmentDistance: number): {
+    position: Point;
+};
+/**
+ * Update single axle position and handle segment transitions
+ *
+ * @param axleState - Current axle state
+ * @param axleExecution - Current execution state for this axle
+ * @param path - The path being followed
+ * @param velocity - Distance to move this frame
+ * @param linesMap - Map of line IDs to Line objects
+ * @param curveDataMap - Map of curve indices to curve data
+ * @param maxOffset - Optional max offset for extending beyond path (for front axle)
+ * @returns Updated axle state, execution state, and completion flag
+ */
+export declare function updateAxlePosition(axleState: AxleState, axleExecution: AxleExecutionState, path: PathResult, velocity: number, linesMap: Map<string, Line>, curveDataMap: Map<number, CurveData>, maxOffset?: number): {
+    axleState: AxleState;
+    execution: AxleExecutionState;
+    completed: boolean;
+};
+export interface PreparedPath {
+    path: PathResult;
+    curveDataMap: Map<number, CurveData>;
+}
+/**
+ * Prepare path and curve data for a goto command
+ * Returns null if no path found
+ *
+ * @param vehicle - The vehicle to move
+ * @param command - The goto command with target
+ * @param ctx - Scene context with graph, linesMap, curves, and config
+ * @returns PreparedPath with path and curve data, or null if no path found
+ */
+export declare function prepareCommandPath(vehicle: Vehicle, command: GotoCommand, ctx: SceneContext): PreparedPath | null;
+type CommandStartCallback = (info: CommandStartInfo) => void;
+export interface SegmentCompletionContext {
+    linesMap: Map<string, Line>;
+    config: MovementConfig;
+    vehicleQueues: Map<string, GotoCommand[]>;
+    curves: Curve[];
+    graphRef: {
+        current: ReturnType<typeof import('./pathFinding').buildGraph> | null;
+    };
+    prepareCommandPath: (vehicle: Vehicle, command: GotoCommand, ctx: SceneContext) => {
+        path: PathResult;
+        curveDataMap: Map<number, CurveData>;
+    } | null;
+    onCommandComplete?: GotoCompletionCallback;
+    onCommandStart?: CommandStartCallback;
+}
+export interface SegmentCompletionResult {
+    handled: boolean;
+    vehicle: Vehicle;
+    /** New execution state (null if completed or unchanged) */
+    newExecution?: PathExecutionState | null;
+    /** True if vehicle is waiting for confirmation to continue */
+    isWaiting?: boolean;
+}
+/**
+ * Handle arrival at destination - all segments completed (pure function)
+ * Checks for next command in queue and starts it, or marks vehicle as arrived
+ */
+export declare function handleArrival(state: VehicleMovementState, ctx: SegmentCompletionContext): SegmentCompletionResult;
+export type { VehicleMovementState as SegmentVehicleState };

package/dist/core/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Core Layer - Pure algorithms and types
+ *
+ * This layer contains the essential logic without any framework dependencies.
+ * Use this if you want to implement your own animation loop or React integration.
+ *
+ * @example
+ * ```typescript
+ * import { buildGraph, findPath, distance } from 'vehicle-path/core'
+ * import type { Point, Line, Vehicle } from 'vehicle-path/core'
+ * ```
+ */
+export type { Point, Line, BezierCurve, Curve } from './types/geometry';
+export type { VehicleState, VehicleStart, Vehicle, AxleState, GotoCommand, GotoCompletionInfo, GotoCompletionCallback } from './types/vehicle';
+export type { CurveData, 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';
+export { buildGraph, findPath, calculateBezierArcLength, resolveFromLineOffset, resolveToLineOffset, type Graph, type GraphEdge, type PathSegment, type PathResult, type VehiclePosition } from './algorithms/pathFinding';
+export { initializeMovingVehicle, createInitialMovementState, initializeAllVehicles, calculateInitialFrontPosition, type InitializationResult, updateAxlePosition, calculatePositionOnLine, calculatePositionOnCurve, calculateFrontAxlePosition, getCumulativeArcLength, arcLengthToSegmentPosition, prepareCommandPath, type PreparedPath, handleArrival, type SegmentCompletionContext, type SegmentCompletionResult, type SegmentVehicleState, getPositionFromOffset, getLineLength } from './algorithms/vehicleMovement';
+export { distance, normalize, getPointOnLine, getPointOnLineByOffset, getPointOnBezier, createBezierCurve, buildArcLengthTable, distanceToT, getArcLength, calculateTangentLength, isPointNearPoint, type ArcLengthEntry, type CurveOffsetOptions } from './algorithms/math';

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

@@ -0,0 +1,185 @@
+/**
+ * API Input Types
+ *
+ * These types define the simplified input format for the programmatic API.
+ * They are designed to be more ergonomic than the internal types.
+ */
+/**
+ * Simple coordinate input - can be [x, y] tuple or {x, y} object
+ */
+export type CoordinateInput = [number, number] | {
+    x: number;
+    y: number;
+};
+/**
+ * Line definition for Scene API
+ *
+ * @example
+ * { id: 'line001', start: [100, 100], end: [500, 100] }
+ * { id: 'line002', start: { x: 500, y: 100 }, end: { x: 500, y: 400 } }
+ */
+export interface SceneLineInput {
+    id: string;
+    start: CoordinateInput;
+    end: CoordinateInput;
+}
+/**
+ * Connection (curve) definition for Scene API
+ *
+ * @example
+ * { from: 'line001', to: 'line002' }
+ * { from: 'line001', fromPosition: 0.8, to: 'line002', toPosition: 0.2 }
+ * { from: 'line001', fromPosition: 150, fromIsPercentage: false, to: 'line002', toPosition: 50, toIsPercentage: false }
+ */
+export interface SceneConnectionInput {
+    from: string;
+    fromPosition?: number;
+    fromIsPercentage?: boolean;
+    to: string;
+    toPosition?: number;
+    toIsPercentage?: boolean;
+}
+/**
+ * Full scene configuration for setScene()
+ *
+ * @example
+ * setScene({
+ *   lines: [
+ *     { id: 'line001', start: [100, 100], end: [500, 100] },
+ *     { id: 'line002', start: [500, 100], end: [500, 400] }
+ *   ],
+ *   connections: [
+ *     { from: 'line001', to: 'line002' }
+ *   ]
+ * })
+ */
+export interface SceneConfig {
+    lines: SceneLineInput[];
+    connections?: SceneConnectionInput[];
+}
+/**
+ * Vehicle creation input for addVehicle()
+ *
+ * @example
+ * addVehicle({ id: 'v1', lineId: 'line001' })  // position defaults to 0 (start)
+ * addVehicle({ id: 'v2', lineId: 'line002', position: 0.5 })  // 50% of line
+ * addVehicle({ id: 'v3', lineId: 'line003', position: 150, isPercentage: false })  // absolute 150
+ */
+export interface VehicleInput {
+    id: string;
+    lineId: string;
+    position?: number;
+    isPercentage?: boolean;
+}
+/**
+ * Vehicle update input for updateVehicle()
+ *
+ * @example
+ * updateVehicle('v1', { lineId: 'line002' })  // move to different line (keeps position 0)
+ * updateVehicle('v1', { position: 0.5 })  // move to 50% on current line
+ * updateVehicle('v1', { lineId: 'line002', position: 0.8 })  // move to 80% on line002
+ * updateVehicle('v1', { position: 150, isPercentage: false })  // move to absolute 150
+ */
+export interface VehicleUpdateInput {
+    lineId?: string;
+    position?: number;
+    isPercentage?: boolean;
+}
+/**
+ * Connection update input for updateConnection()
+ *
+ * @example
+ * updateConnection('line001', 'line002', { fromOffset: 0.8 })  // change from offset to 80%
+ * updateConnection('line001', 'line002', { toOffset: 0.2 })    // change to offset to 20%
+ * updateConnection('line001', 'line002', { fromOffset: 150, fromIsPercentage: false })  // absolute offset
+ */
+export interface ConnectionUpdateInput {
+    fromOffset?: number;
+    fromIsPercentage?: boolean;
+    toOffset?: number;
+    toIsPercentage?: boolean;
+}
+/**
+ * Simplified goto input for useVehicleSimulation.goto()
+ *
+ * @example
+ * goto({ id: 'v1', lineId: 'line002' })  // position defaults to 1.0 (end)
+ * goto({ id: 'v1', lineId: 'line002', position: 0.5 })  // 50% of line
+ * goto({ id: 'v1', lineId: 'line002', position: 150, isPercentage: false })  // absolute 150
+ * goto({ id: 'v1', lineId: 'line002', position: 0.5, wait: true })  // wait at destination
+ * goto({ id: 'v1', lineId: 'line002', payload: { orderId: '123' } })  // with payload
+ */
+export interface GotoInput {
+    id: string;
+    lineId: string;
+    position?: number;
+    isPercentage?: boolean;
+    wait?: boolean;
+    payload?: unknown;
+}
+/**
+ * Input for goto/queueMovement commands (API-friendly version of GotoCommand)
+ *
+ * @example
+ * queueMovement('v1', { targetLineId: 'line002' })  // targetPosition defaults to 1.0 (end)
+ * queueMovement('v1', { targetLineId: 'line002', targetPosition: 0.5 })  // 50% of line
+ * queueMovement('v1', {
+ *   targetLineId: 'line002',
+ *   targetPosition: 0.5,
+ *   wait: true,
+ *   payload: { orderId: '123' }
+ * })
+ * queueMovement('v1', { targetLineId: 'line002', targetPosition: 150, isPercentage: false })
+ */
+export interface GotoCommandInput {
+    targetLineId: string;
+    targetPosition?: number;
+    isPercentage?: boolean;
+    wait?: boolean;
+    payload?: unknown;
+}
+/**
+ * Movement command input for SimulationConfig
+ *
+ * @example
+ * { vehicleId: 'v1', targetLineId: 'line002' }  // position defaults to 1.0 (end)
+ * { vehicleId: 'v1', targetLineId: 'line002', targetPosition: 0.5 }  // 50% of line
+ * { vehicleId: 'v1', targetLineId: 'line002', targetPosition: 150, isPercentage: false }
+ */
+export interface MovementCommandInput {
+    vehicleId: string;
+    targetLineId: string;
+    targetPosition?: number;
+    isPercentage?: boolean;
+    wait?: boolean;
+    payload?: unknown;
+}
+/**
+ * Full simulation configuration for loadFromJSON()
+ *
+ * Allows loading an entire simulation state from a JSON object,
+ * including lines, connections, vehicles, and movement commands.
+ *
+ * @example
+ * loadFromJSON({
+ *   lines: [
+ *     { id: 'line001', start: [100, 100], end: [500, 100] },
+ *     { id: 'line002', start: [500, 100], end: [500, 400] }
+ *   ],
+ *   connections: [
+ *     { from: 'line001', to: 'line002' }
+ *   ],
+ *   vehicles: [
+ *     { id: 'v1', lineId: 'line001', position: 0 }
+ *   ],
+ *   movements: [
+ *     { vehicleId: 'v1', targetLineId: 'line002', targetPosition: 1.0 }
+ *   ]
+ * })
+ */
+export interface SimulationConfig {
+    lines: SceneLineInput[];
+    connections?: SceneConnectionInput[];
+    vehicles?: VehicleInput[];
+    movements?: MovementCommandInput[];
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Configuration types for algorithm behavior
+ */
+/**
+ * Tangent calculation mode for bezier curves
+ * - proportional-40: 40% of distance for tangent length
+ * - magic-55: 55.22% of distance (approximates circular arc)
+ */
+export type TangentMode = 'proportional-40' | 'magic-55';