vehicle-path2 2.3.0 → 3.0.0

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

@@ -0,0 +1,31 @@
+import type { Point, Line, Curve } from '../types/geometry';
+/**
+ * Project a point onto a line segment.
+ *
+ * Returns:
+ * - offset: absolute distance from line.start along the line (clamped to [0, lineLength])
+ * - distance: perpendicular distance from point to the nearest point on the line
+ */
+export declare function projectPointOnLine(point: Point, line: Line): {
+    offset: number;
+    distance: number;
+};
+/**
+ * Compute the valid [min, max] offset range for placing the rear axle of a
+ * multi-axle vehicle on a line.
+ *
+ * - min is always 0 (rear axle at line start)
+ * - max is lineLength - totalAxleSpacing (so all axles fit on the line)
+ * - If the vehicle is too long for the line, returns [0, 0]
+ */
+export declare function getValidRearOffsetRange(line: Line, axleSpacings: number[]): [number, number];
+/**
+ * Compute the minimum length a line must have so that all attached curve
+ * offsets (fromOffset / toOffset) remain within valid bounds.
+ *
+ * Only absolute offsets contribute to the minimum — percentage-based offsets
+ * scale with the line and therefore impose no hard minimum.
+ *
+ * Returns 0 if no curves are attached or all offsets are percentage-based.
+ */
+export declare function computeMinLineLength(lineId: string, curves: Curve[]): number;

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,3 +20,4 @@ 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 { 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 o(r,n,t){const a={lines:r,curves:n.map(i=>({id:i.id,fromLineId:i.fromLineId,toLineId:i.toLineId,fromOffset:i.fromOffset,fromIsPercentage:i.fromIsPercentage??!1,toOffset:i.toOffset,toIsPercentage:i.toIsPercentage??!1})),vehicles:t.map(i=>({id:i.id,lineId:i.axles[0].lineId,axles:i.axles.map(l=>({offset:l.offset})),axleSpacings:i.axleSpacings,isPercentage:i.isPercentage??!1}))};return JSON.stringify(a,null,2)}function s(r){let n;try{n=JSON.parse(r)}catch{throw new Error("deserializeScene: invalid JSON")}if(!n||typeof n!="object"||Array.isArray(n))throw new Error("deserializeScene: expected a JSON object");const t=n;if(!Array.isArray(t.lines))throw new Error('deserializeScene: missing "lines"');if(!Array.isArray(t.curves))throw new Error('deserializeScene: missing "curves"');if(!Array.isArray(t.vehicles))throw new Error('deserializeScene: missing "vehicles"');return{lines:t.lines,curves:t.curves,vehicles:t.vehicles}}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.deserializeScene=s;exports.serializeScene=o;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-C4FckUel.cjs");function f(r,n){const i={lines:r,curves:n.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(i,null,2)}function g(r){let n;try{n=JSON.parse(r)}catch{throw new Error("deserializeScene: invalid JSON")}if(!n||typeof n!="object"||Array.isArray(n))throw new Error("deserializeScene: expected a JSON object");const i=n;if(!Array.isArray(i.lines))throw new Error('deserializeScene: missing "lines"');if(!Array.isArray(i.curves))throw new Error('deserializeScene: missing "curves"');return{lines:i.lines,curves:i.curves}}function u(r,n){const i=n.end.x-n.start.x,t=n.end.y-n.start.y,o=i*i+t*t;if(o===0)return{offset:0,distance:Math.sqrt((r.x-n.start.x)**2+(r.y-n.start.y)**2)};const a=Math.max(0,Math.min(1,((r.x-n.start.x)*i+(r.y-n.start.y)*t)/o)),s=n.start.x+a*i,c=n.start.y+a*t,l=Math.sqrt((r.x-s)**2+(r.y-c)**2);return{offset:a*Math.sqrt(o),distance:l}}function h(r,n){const i=e.getLineLength(r),t=n.reduce((a,s)=>a+s,0);return[0,Math.max(0,i-t)]}function d(r,n){let i=0;for(const t of n)t.fromLineId===r&&!t.fromIsPercentage&&t.fromOffset!==void 0&&(i=Math.max(i,t.fromOffset)),t.toLineId===r&&!t.toIsPercentage&&t.toOffset!==void 0&&(i=Math.max(i,t.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=d;exports.deserializeScene=g;exports.getValidRearOffsetRange=h;exports.projectPointOnLine=u;exports.serializeScene=f;

package/dist/core.js

@@ -1,8 +1,9 @@
-import { P as f, a as g, b as h, c as d, d as u, e as m, f as P, g as A, h as v, i as L, j as O, k as p, l as S, m as z, n as y, o as w, p as x, q as I, r as b, s as E, t as T, u as B, v as C, w as N, x as j, y as J, z as F, A as V, B as M, C as k, D as q, E as D } from "./index-D-HctiIv.js";
-function n(s, a, i) {
-  const r = {
-    lines: s,
-    curves: a.map((e) => ({
+import { g as f } from "./index-BV93143R.js";
+import { P as y, a as v, b as A, c as S, d as p, e as z, f as I, h as M, i as w, j as b, k as j, l as E, m as T, n as q, o as B, p as C, q as N, r as J, s as V, t as F, u as R, v as k, w as D, x as G, y as X, z as Y, A as H, B as K, C as Q, D as U, E as W } from "./index-BV93143R.js";
+function u(a, t) {
+  const s = {
+    lines: a,
+    curves: t.map((e) => ({
       id: e.id,
       fromLineId: e.fromLineId,
       toLineId: e.toLineId,
@@ -10,69 +11,88 @@ function n(s, a, i) {
       fromIsPercentage: e.fromIsPercentage ?? !1,
       toOffset: e.toOffset,
       toIsPercentage: e.toIsPercentage ?? !1
-    })),
-    vehicles: i.map((e) => ({
-      id: e.id,
-      lineId: e.axles[0].lineId,
-      axles: e.axles.map((t) => ({ offset: t.offset })),
-      axleSpacings: e.axleSpacings,
-      isPercentage: e.isPercentage ?? !1
     }))
   };
-  return JSON.stringify(r, null, 2);
+  return JSON.stringify(s, null, 2);
 }
-function o(s) {
-  let a;
+function g(a) {
+  let t;
   try {
-    a = JSON.parse(s);
+    t = JSON.parse(a);
   } catch {
     throw new Error("deserializeScene: invalid JSON");
   }
-  if (!a || typeof a != "object" || Array.isArray(a))
+  if (!t || typeof t != "object" || Array.isArray(t))
     throw new Error("deserializeScene: expected a JSON object");
-  const i = a;
-  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"');
+  const s = t;
+  if (!Array.isArray(s.lines)) throw new Error('deserializeScene: missing "lines"');
+  if (!Array.isArray(s.curves)) throw new Error('deserializeScene: missing "curves"');
   return {
-    lines: i.lines,
-    curves: i.curves,
-    vehicles: i.vehicles
+    lines: s.lines,
+    curves: s.curves
   };
 }
+function h(a, t) {
+  const s = t.end.x - t.start.x, e = t.end.y - t.start.y, n = s * s + e * e;
+  if (n === 0)
+    return { offset: 0, distance: Math.sqrt(
+      (a.x - t.start.x) ** 2 + (a.y - t.start.y) ** 2
+    ) };
+  const r = Math.max(
+    0,
+    Math.min(
+      1,
+      ((a.x - t.start.x) * s + (a.y - t.start.y) * e) / n
+    )
+  ), i = t.start.x + r * s, o = t.start.y + r * e, c = Math.sqrt((a.x - i) ** 2 + (a.y - o) ** 2);
+  return { offset: r * Math.sqrt(n), distance: c };
+}
+function L(a, t) {
+  const s = f(a), e = t.reduce((r, i) => r + i, 0);
+  return [0, Math.max(0, s - e)];
+}
+function O(a, t) {
+  let s = 0;
+  for (const e of t)
+    e.fromLineId === a && !e.fromIsPercentage && e.fromOffset !== void 0 && (s = Math.max(s, e.fromOffset)), e.toLineId === a && !e.toIsPercentage && e.toOffset !== void 0 && (s = Math.max(s, e.toOffset));
+  return s;
+}
 export {
-  f as PathEngine,
-  g as arcLengthToSegmentPosition,
-  h as buildArcLengthTable,
-  d as buildGraph,
-  u as calculateBezierArcLength,
-  m as calculateFrontAxlePosition,
-  P as calculateInitialAxlePositions,
-  A as calculatePositionOnCurve,
-  v as calculatePositionOnLine,
-  L as calculateTangentLength,
-  O as createBezierCurve,
-  p as createInitialMovementState,
-  o as deserializeScene,
-  S as distance,
-  z as distanceToT,
-  y as findPath,
-  w as getArcLength,
-  x as getCumulativeArcLength,
-  I as getLineLength,
-  b as getPointOnBezier,
-  E as getPointOnLine,
-  T as getPointOnLineByOffset,
-  B as getPositionFromOffset,
-  C as handleArrival,
-  N as initializeAllVehicles,
-  j as initializeMovingVehicle,
-  J as isPointNearPoint,
-  F as moveVehicle,
-  V as normalize,
-  M as prepareCommandPath,
-  k as resolveFromLineOffset,
-  q as resolveToLineOffset,
-  n as serializeScene,
-  D as updateAxlePosition
+  y as PathEngine,
+  v as arcLengthToSegmentPosition,
+  A as buildArcLengthTable,
+  S as buildGraph,
+  p as calculateBezierArcLength,
+  z as calculateFrontAxlePosition,
+  I as calculateInitialAxlePositions,
+  M as calculatePositionOnCurve,
+  w as calculatePositionOnLine,
+  b as calculateTangentLength,
+  O as computeMinLineLength,
+  j as createBezierCurve,
+  E as createInitialMovementState,
+  g as deserializeScene,
+  T as distance,
+  q as distanceToT,
+  B as findPath,
+  C as getArcLength,
+  N as getCumulativeArcLength,
+  f as getLineLength,
+  J as getPointOnBezier,
+  V as getPointOnLine,
+  F as getPointOnLineByOffset,
+  R as getPositionFromOffset,
+  L as getValidRearOffsetRange,
+  k as handleArrival,
+  D as initializeAllVehicles,
+  G as initializeMovingVehicle,
+  X as isPointNearPoint,
+  Y as moveVehicle,
+  H as normalize,
+  K as prepareCommandPath,
+  h as projectPointOnLine,
+  Q as resolveFromLineOffset,
+  U as resolveToLineOffset,
+  u as serializeScene,
+  W as updateAxlePosition
 };