@flighthq/motionpath 0.1.0

package/dist/createMotionPath.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath, MotionPathLoopMode, Path } from '@flighthq/types';
+export declare function createMotionPath(path: Path, speed?: number, loopMode?: MotionPathLoopMode, tolerance?: number): MotionPath;
+//# sourceMappingURL=createMotionPath.d.ts.map

package/dist/createMotionPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMotionPath.d.ts","sourceRoot":"","sources":["../src/createMotionPath.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAS5E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,SAAI,EACT,QAAQ,GAAE,kBAA4B,EACtC,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU,CASZ"}

package/dist/createMotionPath.js

@@ -0,0 +1,19 @@
+import { getPathLength } from '@flighthq/path';
+// Allocate a `MotionPath` marker at the start of `path` (`distance` 0, `direction` forward).
+// `speed` is the traversal rate in path units per second (a magnitude; default 0 = stationary),
+// `loopMode` the end behavior (default `clamp`). The path's total arc length is measured once here
+// with `getPathLength(path, tolerance)` and cached in `length`; per-frame updates reuse it rather
+// than re-measuring. `tolerance` is the curve-flattening tolerance forwarded to the arc-length
+// measurement. This is the only allocating function; `updateMotionPath` and the seek helpers write
+// into an existing marker.
+export function createMotionPath(path, speed = 0, loopMode = 'clamp', tolerance) {
+    return {
+        direction: 1,
+        distance: 0,
+        length: getPathLength(path, tolerance),
+        loopMode,
+        path,
+        speed,
+    };
+}
+//# sourceMappingURL=createMotionPath.js.map

package/dist/createMotionPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createMotionPath.js","sourceRoot":"","sources":["../src/createMotionPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,6FAA6F;AAC7F,gGAAgG;AAChG,mGAAmG;AACnG,kGAAkG;AAClG,+FAA+F;AAC/F,mGAAmG;AACnG,2BAA2B;AAC3B,MAAM,UAAU,gBAAgB,CAC9B,IAAU,EACV,KAAK,GAAG,CAAC,EACT,WAA+B,OAAO,EACtC,SAAkB;IAElB,OAAO;QACL,SAAS,EAAE,CAAC;QACZ,QAAQ,EAAE,CAAC;QACX,MAAM,EAAE,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC;QACtC,QAAQ;QACR,IAAI;QACJ,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/getMotionPathHeading.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath } from '@flighthq/types';
+export declare function getMotionPathHeading(mp: Readonly<MotionPath>): number;
+//# sourceMappingURL=getMotionPathHeading.d.ts.map

package/dist/getMotionPathHeading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathHeading.d.ts","sourceRoot":"","sources":["../src/getMotionPathHeading.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAGrE"}

package/dist/getMotionPathHeading.js

@@ -0,0 +1,12 @@
+import { createVector2 } from '@flighthq/geometry';
+import { getPathTangentAtDistance } from '@flighthq/path';
+// Return the marker's heading angle in radians — `atan2(tangentY, tangentX)` of the path tangent at
+// the current `distance` — for orienting an object along the curve. Samples the tangent into a
+// module-scoped scratch vector, so the query allocates nothing. For an empty/degenerate path the
+// tangent falls back to `(1, 0)`, giving a heading of 0.
+export function getMotionPathHeading(mp) {
+    getPathTangentAtDistance(mp.path, mp.distance, scratchTangent);
+    return Math.atan2(scratchTangent.y, scratchTangent.x);
+}
+const scratchTangent = createVector2();
+//# sourceMappingURL=getMotionPathHeading.js.map

package/dist/getMotionPathHeading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathHeading.js","sourceRoot":"","sources":["../src/getMotionPathHeading.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAG1D,oGAAoG;AACpG,+FAA+F;AAC/F,iGAAiG;AACjG,yDAAyD;AACzD,MAAM,UAAU,oBAAoB,CAAC,EAAwB;IAC3D,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,cAAc,GAAG,aAAa,EAAE,CAAC"}

package/dist/getMotionPathPosition.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath, Vector2Like } from '@flighthq/types';
+export declare function getMotionPathPosition(mp: Readonly<MotionPath>, pointOut: Vector2Like, tangentOut: Vector2Like): boolean;
+//# sourceMappingURL=getMotionPathPosition.d.ts.map

package/dist/getMotionPathPosition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathPosition.d.ts","sourceRoot":"","sources":["../src/getMotionPathPosition.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM/D,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,EACxB,QAAQ,EAAE,WAAW,EACrB,UAAU,EAAE,WAAW,GACtB,OAAO,CAET"}

package/dist/getMotionPathPosition.js

@@ -0,0 +1,9 @@
+import { getPathPositionAtDistance } from '@flighthq/path';
+// Sample the marker's current world position and unit tangent, writing them into `pointOut` and
+// `tangentOut`. Returns `true` on success, `false` for an empty/degenerate path (in which case the
+// outputs are left unchanged). Delegates to `@flighthq/path`'s `getPathPositionAtDistance` at the
+// marker's current `distance`.
+export function getMotionPathPosition(mp, pointOut, tangentOut) {
+    return getPathPositionAtDistance(mp.path, mp.distance, pointOut, tangentOut);
+}
+//# sourceMappingURL=getMotionPathPosition.js.map

package/dist/getMotionPathPosition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathPosition.js","sourceRoot":"","sources":["../src/getMotionPathPosition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAG3D,gGAAgG;AAChG,mGAAmG;AACnG,kGAAkG;AAClG,+BAA+B;AAC/B,MAAM,UAAU,qBAAqB,CACnC,EAAwB,EACxB,QAAqB,EACrB,UAAuB;IAEvB,OAAO,yBAAyB,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC/E,CAAC"}

package/dist/getMotionPathProgress.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath } from '@flighthq/types';
+export declare function getMotionPathProgress(mp: Readonly<MotionPath>): number;
+//# sourceMappingURL=getMotionPathProgress.d.ts.map

package/dist/getMotionPathProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathProgress.d.ts","sourceRoot":"","sources":["../src/getMotionPathProgress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAEtE"}

package/dist/getMotionPathProgress.js

@@ -0,0 +1,6 @@
+// Return the marker's normalized progress along the path, `distance / length` in `[0, 1]`. A
+// zero-length path reports 0.
+export function getMotionPathProgress(mp) {
+    return mp.length > 0 ? mp.distance / mp.length : 0;
+}
+//# sourceMappingURL=getMotionPathProgress.js.map

package/dist/getMotionPathProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMotionPathProgress.js","sourceRoot":"","sources":["../src/getMotionPathProgress.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,8BAA8B;AAC9B,MAAM,UAAU,qBAAqB,CAAC,EAAwB;IAC5D,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './createMotionPath';
+export * from './getMotionPathHeading';
+export * from './getMotionPathPosition';
+export * from './getMotionPathProgress';
+export * from './setMotionPathDistance';
+export * from './setMotionPathProgress';
+export * from './updateMotionPath';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './createMotionPath';
+export * from './getMotionPathHeading';
+export * from './getMotionPathPosition';
+export * from './getMotionPathProgress';
+export * from './setMotionPathDistance';
+export * from './setMotionPathProgress';
+export * from './updateMotionPath';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC"}

package/dist/setMotionPathDistance.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath } from '@flighthq/types';
+export declare function setMotionPathDistance(mp: MotionPath, distance: number): void;
+//# sourceMappingURL=setMotionPathDistance.d.ts.map

package/dist/setMotionPathDistance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setMotionPathDistance.d.ts","sourceRoot":"","sources":["../src/setMotionPathDistance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM5E"}

package/dist/setMotionPathDistance.js

@@ -0,0 +1,12 @@
+// Seek the marker to an absolute arc-length `distance`, clamping to the valid `[0, length]` range.
+// Does not change `direction` or `speed`.
+export function setMotionPathDistance(mp, distance) {
+    const length = mp.length;
+    let clamped = distance;
+    if (clamped < 0)
+        clamped = 0;
+    else if (clamped > length)
+        clamped = length;
+    mp.distance = clamped;
+}
+//# sourceMappingURL=setMotionPathDistance.js.map

package/dist/setMotionPathDistance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setMotionPathDistance.js","sourceRoot":"","sources":["../src/setMotionPathDistance.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,0CAA0C;AAC1C,MAAM,UAAU,qBAAqB,CAAC,EAAc,EAAE,QAAgB;IACpE,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;IACzB,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,CAAC;SACxB,IAAI,OAAO,GAAG,MAAM;QAAE,OAAO,GAAG,MAAM,CAAC;IAC5C,EAAE,CAAC,QAAQ,GAAG,OAAO,CAAC;AACxB,CAAC"}

package/dist/setMotionPathProgress.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath } from '@flighthq/types';
+export declare function setMotionPathProgress(mp: MotionPath, t: number): void;
+//# sourceMappingURL=setMotionPathProgress.d.ts.map

package/dist/setMotionPathProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setMotionPathProgress.d.ts","sourceRoot":"","sources":["../src/setMotionPathProgress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAKrE"}

package/dist/setMotionPathProgress.js

@@ -0,0 +1,11 @@
+// Seek the marker to a normalized progress `t` along the path, clamping `t` to `[0, 1]` and setting
+// `distance` to `t * length`. Does not change `direction` or `speed`.
+export function setMotionPathProgress(mp, t) {
+    let clamped = t;
+    if (clamped < 0)
+        clamped = 0;
+    else if (clamped > 1)
+        clamped = 1;
+    mp.distance = clamped * mp.length;
+}
+//# sourceMappingURL=setMotionPathProgress.js.map

package/dist/setMotionPathProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setMotionPathProgress.js","sourceRoot":"","sources":["../src/setMotionPathProgress.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,sEAAsE;AACtE,MAAM,UAAU,qBAAqB,CAAC,EAAc,EAAE,CAAS;IAC7D,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,CAAC;SACxB,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,CAAC;IAClC,EAAE,CAAC,QAAQ,GAAG,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC;AACpC,CAAC"}

package/dist/updateMotionPath.d.ts

@@ -0,0 +1,3 @@
+import type { MotionPath } from '@flighthq/types';
+export declare function updateMotionPath(mp: MotionPath, deltaTime: number): void;
+//# sourceMappingURL=updateMotionPath.d.ts.map

package/dist/updateMotionPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateMotionPath.d.ts","sourceRoot":"","sources":["../src/updateMotionPath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMlD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQxE"}

package/dist/updateMotionPath.js

@@ -0,0 +1,60 @@
+// Advance `mp` by `deltaTime` seconds: move the marker `speed * deltaTime` path units along its
+// current `direction`, then resolve the end behavior (`applyMotionPathLoopMode`). `deltaTime <= 0`
+// and a zero-length path are no-ops. `distance` (and, for `pingpong`, `direction`) are updated in
+// place; all inputs are read into locals before any write, so `mp` aliasing itself is safe.
+export function updateMotionPath(mp, deltaTime) {
+    if (deltaTime <= 0)
+        return;
+    const length = mp.length;
+    if (length <= 0)
+        return;
+    // `move` is a magnitude (path units this frame); the travel sign lives in `mp.direction`.
+    const move = mp.speed * deltaTime;
+    applyMotionPathLoopMode(mp, move, length);
+}
+// Resolve the end behavior after advancing `mp` by `move` units along `mp.direction`, writing the
+// new `distance` (kept in `[0, length]`) and, for `pingpong`, the new `direction` back into `mp`.
+//
+// `clamp` stops at the ends. `loop` wraps the signed advance modulo `length` into `[0, length)`.
+// `pingpong` reflects off both ends: the marker travels on a phase line of period `2 * length`
+// whose triangle wave folds back into `[0, length]`, so the closed form below bounces correctly even
+// when a single large `move` crosses the path several times. Because `distance` alone is ambiguous
+// between the outbound and return legs, the current `direction` selects which phase-line branch the
+// marker is on (`direction < 0` mirrors it onto the descending branch) before advancing.
+function applyMotionPathLoopMode(mp, move, length) {
+    const loopMode = mp.loopMode;
+    const distance = mp.distance;
+    const direction = mp.direction;
+    if (loopMode === 'loop') {
+        let wrapped = (distance + direction * move) % length;
+        if (wrapped < 0)
+            wrapped += length;
+        mp.distance = wrapped;
+        return;
+    }
+    if (loopMode === 'pingpong') {
+        const period = 2 * length;
+        // Phase of the current marker: identity on the outbound (forward) leg, mirrored on the return.
+        const phase = direction < 0 ? period - distance : distance;
+        let advanced = (phase + move) % period;
+        if (advanced < 0)
+            advanced += period;
+        if (advanced <= length) {
+            mp.distance = advanced;
+            mp.direction = 1;
+        }
+        else {
+            mp.distance = period - advanced;
+            mp.direction = -1;
+        }
+        return;
+    }
+    // clamp
+    let clamped = distance + direction * move;
+    if (clamped < 0)
+        clamped = 0;
+    else if (clamped > length)
+        clamped = length;
+    mp.distance = clamped;
+}
+//# sourceMappingURL=updateMotionPath.js.map

package/dist/updateMotionPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateMotionPath.js","sourceRoot":"","sources":["../src/updateMotionPath.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,mGAAmG;AACnG,kGAAkG;AAClG,4FAA4F;AAC5F,MAAM,UAAU,gBAAgB,CAAC,EAAc,EAAE,SAAiB;IAChE,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO;IAC3B,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;IACzB,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO;IAExB,0FAA0F;IAC1F,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,GAAG,SAAS,CAAC;IAClC,uBAAuB,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,kGAAkG;AAClG,kGAAkG;AAClG,EAAE;AACF,iGAAiG;AACjG,+FAA+F;AAC/F,qGAAqG;AACrG,mGAAmG;AACnG,oGAAoG;AACpG,yFAAyF;AACzF,SAAS,uBAAuB,CAAC,EAAc,EAAE,IAAY,EAAE,MAAc;IAC3E,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;IAC7B,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;IAC7B,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC;IAE/B,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,IAAI,OAAO,GAAG,CAAC,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QACrD,IAAI,OAAO,GAAG,CAAC;YAAE,OAAO,IAAI,MAAM,CAAC;QACnC,EAAE,CAAC,QAAQ,GAAG,OAAO,CAAC;QACtB,OAAO;IACT,CAAC;IAED,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC;QAC1B,+FAA+F;QAC/F,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC3D,IAAI,QAAQ,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QACvC,IAAI,QAAQ,GAAG,CAAC;YAAE,QAAQ,IAAI,MAAM,CAAC;QACrC,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;YACvB,EAAE,CAAC,QAAQ,GAAG,QAAQ,CAAC;YACvB,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,EAAE,CAAC,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;YAChC,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACpB,CAAC;QACD,OAAO;IACT,CAAC;IAED,QAAQ;IACR,IAAI,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;IAC1C,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC,CAAC;SACxB,IAAI,OAAO,GAAG,MAAM;QAAE,OAAO,GAAG,MAAM,CAAC;IAC5C,EAAE,CAAC,QAAQ,GAAG,OAAO,CAAC;AACxB,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/motionpath",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/path": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Path-following animation — advances a marker along a @flighthq/path by arc length at a controlled speed and reports its world position, tangent, and heading angle, with clamp/loop/pingpong end behaviors and distance/progress seek; plain-data MotionPath state stepped by small out-param functions over path's arc-length sampling",
+  "sideEffects": false
+}

package/src/createMotionPath.test.ts

@@ -0,0 +1,34 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+
+describe('createMotionPath', () => {
+  it('caches the path arc length measured from the path', () => {
+    const mp = createMotionPath(line());
+    expect(mp.length).toBeCloseTo(100, 6);
+  });
+
+  it('starts at the path start, forward, with clamp defaults', () => {
+    const mp = createMotionPath(line());
+    expect(mp.distance).toBe(0);
+    expect(mp.direction).toBe(1);
+    expect(mp.speed).toBe(0);
+    expect(mp.loopMode).toBe('clamp');
+  });
+
+  it('carries the provided speed and loop mode', () => {
+    const mp = createMotionPath(line(), 50, 'pingpong');
+    expect(mp.speed).toBe(50);
+    expect(mp.loopMode).toBe('pingpong');
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100, tangent (1,0) everywhere.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}

package/src/getMotionPathHeading.test.ts

@@ -0,0 +1,43 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { getMotionPathHeading } from './getMotionPathHeading';
+import { setMotionPathDistance } from './setMotionPathDistance';
+
+describe('getMotionPathHeading', () => {
+  it('reads 0 radians along a rightward line', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, 50);
+    expect(getMotionPathHeading(mp)).toBeCloseTo(0, 6);
+  });
+
+  it('differs before and after a corner', () => {
+    const mp = createMotionPath(corner());
+    setMotionPathDistance(mp, 50); // on the horizontal leg, heading 0
+    const before = getMotionPathHeading(mp);
+    setMotionPathDistance(mp, 150); // on the vertical leg, heading +pi/2
+    const after = getMotionPathHeading(mp);
+    expect(before).toBeCloseTo(0, 6);
+    expect(after).toBeCloseTo(Math.PI / 2, 6);
+    expect(after).not.toBeCloseTo(before, 3);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}
+
+// An L-shape: (0,0) -> (100,0) -> (100,100). Arc length 200, corner at distance 100.
+function corner(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  appendPathLineTo(path, 100, 100);
+  return path;
+}

package/src/getMotionPathPosition.test.ts

@@ -0,0 +1,41 @@
+import { createVector2 } from '@flighthq/geometry';
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { getMotionPathPosition } from './getMotionPathPosition';
+import { setMotionPathDistance } from './setMotionPathDistance';
+
+describe('getMotionPathPosition', () => {
+  it('samples the point and tangent at the current distance', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, 50);
+    const point = createVector2();
+    const tangent = createVector2();
+    const ok = getMotionPathPosition(mp, point, tangent);
+    expect(ok).toBe(true);
+    expect(point.x).toBeCloseTo(50, 6);
+    expect(point.y).toBeCloseTo(0, 6);
+    expect(tangent.x).toBeCloseTo(1, 6);
+    expect(tangent.y).toBeCloseTo(0, 6);
+  });
+
+  it('returns false and leaves outputs unchanged for an empty path', () => {
+    const mp = createMotionPath(createPath());
+    const point = createVector2(7, 8);
+    const tangent = createVector2(9, 9);
+    const ok = getMotionPathPosition(mp, point, tangent);
+    expect(ok).toBe(false);
+    expect(point.x).toBe(7);
+    expect(point.y).toBe(8);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}

package/src/getMotionPathProgress.test.ts

@@ -0,0 +1,28 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { getMotionPathProgress } from './getMotionPathProgress';
+import { setMotionPathDistance } from './setMotionPathDistance';
+
+describe('getMotionPathProgress', () => {
+  it('reports distance / length', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, 25);
+    expect(getMotionPathProgress(mp)).toBeCloseTo(0.25, 6);
+  });
+
+  it('reports 0 for a zero-length path', () => {
+    const mp = createMotionPath(createPath());
+    expect(getMotionPathProgress(mp)).toBe(0);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}

package/src/setMotionPathDistance.test.ts

@@ -0,0 +1,34 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { setMotionPathDistance } from './setMotionPathDistance';
+
+describe('setMotionPathDistance', () => {
+  it('seeks to an absolute arc-length distance', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, 25);
+    expect(mp.distance).toBe(25);
+  });
+
+  it('clamps distances above the length', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, 150);
+    expect(mp.distance).toBe(100);
+  });
+
+  it('clamps negative distances to 0', () => {
+    const mp = createMotionPath(line());
+    setMotionPathDistance(mp, -10);
+    expect(mp.distance).toBe(0);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}

package/src/setMotionPathProgress.test.ts

@@ -0,0 +1,34 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { setMotionPathProgress } from './setMotionPathProgress';
+
+describe('setMotionPathProgress', () => {
+  it('seeks to a normalized progress along the path', () => {
+    const mp = createMotionPath(line());
+    setMotionPathProgress(mp, 0.25);
+    expect(mp.distance).toBeCloseTo(25, 6);
+  });
+
+  it('clamps progress above 1 to the end', () => {
+    const mp = createMotionPath(line());
+    setMotionPathProgress(mp, 1.5);
+    expect(mp.distance).toBeCloseTo(100, 6);
+  });
+
+  it('clamps negative progress to the start', () => {
+    const mp = createMotionPath(line());
+    setMotionPathProgress(mp, -0.5);
+    expect(mp.distance).toBe(0);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}

package/src/updateMotionPath.test.ts

@@ -0,0 +1,105 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from '@flighthq/path';
+import type { Path } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createMotionPath } from './createMotionPath';
+import { getMotionPathProgress } from './getMotionPathProgress';
+import { updateMotionPath } from './updateMotionPath';
+
+describe('updateMotionPath', () => {
+  it('advances distance by speed * deltaTime', () => {
+    const mp = createMotionPath(line(), 50);
+    updateMotionPath(mp, 1);
+    expect(mp.distance).toBeCloseTo(50, 6);
+    expect(getMotionPathProgress(mp)).toBeCloseTo(0.5, 6);
+  });
+
+  it('clamp stops at the end and stays there', () => {
+    const mp = createMotionPath(line(), 50, 'clamp');
+    updateMotionPath(mp, 10); // 500 units of travel, past the 100-length end
+    expect(mp.distance).toBeCloseTo(100, 6);
+    expect(getMotionPathProgress(mp)).toBeCloseTo(1, 6);
+    updateMotionPath(mp, 5);
+    expect(mp.distance).toBeCloseTo(100, 6);
+  });
+
+  it('loop wraps past the end modulo length', () => {
+    const mp = createMotionPath(line(), 30, 'loop');
+    updateMotionPath(mp, 4); // 120 -> 20
+    expect(mp.distance).toBeCloseTo(20, 6);
+  });
+
+  it('loop wraps backward into [0, length)', () => {
+    const mp = createMotionPath(line(), 30, 'loop');
+    mp.direction = -1;
+    updateMotionPath(mp, 4); // 0 - 120 -> -120 mod 100 -> 80
+    expect(mp.distance).toBeCloseTo(80, 6);
+  });
+
+  it('pingpong reflects at the end and flips direction to -1', () => {
+    const mp = createMotionPath(line(), 30, 'pingpong');
+    mp.distance = 90;
+    updateMotionPath(mp, 1); // 90 + 30 = 120 -> reflect to 80
+    expect(mp.distance).toBeCloseTo(80, 6);
+    expect(mp.direction).toBe(-1);
+  });
+
+  it('pingpong then travels back toward the start', () => {
+    const mp = createMotionPath(line(), 30, 'pingpong');
+    mp.distance = 90;
+    updateMotionPath(mp, 1); // -> 80, direction -1
+    updateMotionPath(mp, 1); // 80 - 30 = 50
+    expect(mp.distance).toBeCloseTo(50, 6);
+    expect(mp.direction).toBe(-1);
+  });
+
+  it('loop wraps a single large step across the path multiple times', () => {
+    const mp = createMotionPath(line(), 250, 'loop');
+    updateMotionPath(mp, 1); // 250 mod 100 -> 50
+    expect(mp.distance).toBeCloseTo(50, 6);
+  });
+
+  it('pingpong resolves a single large step that crosses the path several times', () => {
+    const mp = createMotionPath(line(), 250, 'pingpong');
+    updateMotionPath(mp, 1); // 0->100 (flip), 100->0 (flip), 0->50 => 50, direction +1
+    expect(mp.distance).toBeCloseTo(50, 6);
+    expect(mp.direction).toBe(1);
+  });
+
+  it('pingpong reflects again at the start and flips direction back to +1', () => {
+    const mp = createMotionPath(line(), 80, 'pingpong');
+    mp.distance = 50;
+    mp.direction = -1;
+    updateMotionPath(mp, 1); // 50 - 80 = -30 -> reflect to 30, direction +1
+    expect(mp.distance).toBeCloseTo(30, 6);
+    expect(mp.direction).toBe(1);
+  });
+
+  it('deltaTime <= 0 is a no-op', () => {
+    const mp = createMotionPath(line(), 50);
+    updateMotionPath(mp, 0);
+    expect(mp.distance).toBe(0);
+    updateMotionPath(mp, -1);
+    expect(mp.distance).toBe(0);
+  });
+
+  it('a zero-length path is a no-op', () => {
+    const mp = createMotionPath(empty(), 50);
+    expect(mp.length).toBe(0);
+    updateMotionPath(mp, 1);
+    expect(mp.distance).toBe(0);
+  });
+});
+
+// A straight horizontal line from (0,0) to (100,0): arc length 100.
+function line(): Path {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 100, 0);
+  return path;
+}
+
+// An empty path with no commands: arc length 0.
+function empty(): Path {
+  return createPath();
+}