@flighthq/velocity 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { contributeTransformVelocity } from './transformVelocity';
+export { addVelocity, beginVelocityFrame, clampVelocity, contributeVelocity, copyVelocity, createVelocityField, dampVelocity, ensureVelocitySample, getVelocity, hasVelocity, isVelocityZero, lengthOfVelocity, lerpVelocity, normalizeVelocity, scaleVelocity, subtractVelocity, suppressVelocity, zeroVelocity, } from './velocityField';
+export { getVelocitySampleAt } from './velocitySample';
+//# 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,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { contributeTransformVelocity } from './transformVelocity';
+export { addVelocity, beginVelocityFrame, clampVelocity, contributeVelocity, copyVelocity, createVelocityField, dampVelocity, ensureVelocitySample, getVelocity, hasVelocity, isVelocityZero, lengthOfVelocity, lerpVelocity, normalizeVelocity, scaleVelocity, subtractVelocity, suppressVelocity, zeroVelocity, } from './velocityField';
+export { getVelocitySampleAt } from './velocitySample';
+//# 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,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/transformVelocity.d.ts

@@ -0,0 +1,3 @@
+import type { Transform2DNode, VelocityField } from '@flighthq/types';
+export declare function contributeTransformVelocity<Traits extends object>(field: VelocityField, root: Readonly<Transform2DNode<Traits>>): void;
+//# sourceMappingURL=transformVelocity.d.ts.map

package/dist/transformVelocity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformVelocity.d.ts","sourceRoot":"","sources":["../src/transformVelocity.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAatE,wBAAgB,2BAA2B,CAAC,MAAM,SAAS,MAAM,EAC/D,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,GACtC,IAAI,CAEN"}

package/dist/transformVelocity.js

@@ -0,0 +1,44 @@
+import { copyMatrix, createMatrix } from '@flighthq/geometry';
+import { ensureNodeWorldTransformMatrix, getNodeChildAt, getNodeChildCount, getNodeWorldTransformMatrix, } from '@flighthq/node';
+import { ensureVelocitySample } from './velocityField';
+// The default velocity contributor. Walks `root`'s subtree top-down, deriving each node's screen-space
+// velocity from the delta of its world transform since the previous frame, then commits the current world
+// transform as the new previous. This is the "any transform is velocity" baseline — a tween, physics
+// step, camera move, or manual edit all change world transforms and so produce velocity here for free.
+//
+// Nodes an explicit contributor already set this frame keep that velocity (their explicitFrameId matches),
+// but still have their previous transform updated, so order relative to explicit contributors does not
+// matter. Run once per frame after beginVelocityFrame. Velocity is in node units; a producer scales by
+// the render pixel ratio.
+export function contributeTransformVelocity(field, root) {
+    visitTransformVelocity(field, root);
+}
+function visitTransformVelocity(field, node) {
+    const mutableNode = node;
+    ensureNodeWorldTransformMatrix(mutableNode);
+    const world = getNodeWorldTransformMatrix(mutableNode);
+    const sample = ensureVelocitySample(field, node);
+    if (sample.explicitFrameId !== field.frameId) {
+        if (sample.previousWorldTransform !== null) {
+            sample.velocity.x = world.tx - sample.previousWorldTransform.tx;
+            sample.velocity.y = world.ty - sample.previousWorldTransform.ty;
+        }
+        else {
+            sample.velocity.x = 0;
+            sample.velocity.y = 0;
+        }
+        sample.lastFrameId = field.frameId;
+    }
+    if (sample.previousWorldTransform === null)
+        sample.previousWorldTransform = createMatrix();
+    copyMatrix(sample.previousWorldTransform, world);
+    // Children of a transform node in a homogeneous display/sprite graph are themselves transform nodes;
+    // the hierarchy type does not carry that, so the trait is asserted.
+    const count = getNodeChildCount(mutableNode);
+    for (let i = 0; i < count; i++) {
+        const child = getNodeChildAt(mutableNode, i);
+        if (child !== null)
+            visitTransformVelocity(field, child);
+    }
+}
+//# sourceMappingURL=transformVelocity.js.map

package/dist/transformVelocity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformVelocity.js","sourceRoot":"","sources":["../src/transformVelocity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAC9B,cAAc,EACd,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,uGAAuG;AACvG,0GAA0G;AAC1G,qGAAqG;AACrG,uGAAuG;AACvG,EAAE;AACF,2GAA2G;AAC3G,uGAAuG;AACvG,uGAAuG;AACvG,0BAA0B;AAC1B,MAAM,UAAU,2BAA2B,CACzC,KAAoB,EACpB,IAAuC;IAEvC,sBAAsB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,sBAAsB,CAC7B,KAAoB,EACpB,IAAuC;IAEvC,MAAM,WAAW,GAAG,IAA+B,CAAC;IACpD,8BAA8B,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,2BAA2B,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAEjD,IAAI,MAAM,CAAC,eAAe,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,MAAM,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;YAC3C,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;YAChE,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAClE,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC;YACtB,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QACD,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC;IACrC,CAAC;IAED,IAAI,MAAM,CAAC,sBAAsB,KAAK,IAAI;QAAE,MAAM,CAAC,sBAAsB,GAAG,YAAY,EAAE,CAAC;IAC3F,UAAU,CAAC,MAAM,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;IAEjD,qGAAqG;IACrG,oEAAoE;IACpE,MAAM,KAAK,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC7C,IAAI,KAAK,KAAK,IAAI;YAAE,sBAAsB,CAAC,KAAK,EAAE,KAAqD,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC"}

package/dist/velocityField.d.ts

@@ -0,0 +1,20 @@
+import type { Velocity2D, VelocityField, VelocitySample } from '@flighthq/types';
+export declare function addVelocity(out: Velocity2D, a: Readonly<Velocity2D>, b: Readonly<Velocity2D>): Velocity2D;
+export declare function beginVelocityFrame(field: VelocityField): void;
+export declare function clampVelocity(out: Velocity2D, velocity: Readonly<Velocity2D>, maxLength: number): Velocity2D;
+export declare function contributeVelocity(field: VelocityField, source: object, x: number, y: number): void;
+export declare function copyVelocity(out: Velocity2D, source: Readonly<Velocity2D>): Velocity2D;
+export declare function createVelocityField(): VelocityField;
+export declare function dampVelocity(out: Velocity2D, current: Readonly<Velocity2D>, previous: Readonly<Velocity2D>, factor: number): Velocity2D;
+export declare function ensureVelocitySample(field: VelocityField, source: object): VelocitySample;
+export declare function getVelocity(field: VelocityField, source: object, out: Velocity2D): Velocity2D;
+export declare function hasVelocity(field: VelocityField, source: object): boolean;
+export declare function isVelocityZero(velocity: Readonly<Velocity2D>, epsilon?: number): boolean;
+export declare function lengthOfVelocity(velocity: Readonly<Velocity2D>): number;
+export declare function lerpVelocity(out: Velocity2D, a: Readonly<Velocity2D>, b: Readonly<Velocity2D>, t: number): Velocity2D;
+export declare function normalizeVelocity(out: Velocity2D, source: Readonly<Velocity2D>): Velocity2D;
+export declare function scaleVelocity(out: Velocity2D, velocity: Readonly<Velocity2D>, scale: number): Velocity2D;
+export declare function subtractVelocity(out: Velocity2D, a: Readonly<Velocity2D>, b: Readonly<Velocity2D>): Velocity2D;
+export declare function suppressVelocity(field: VelocityField, source: object): void;
+export declare function zeroVelocity(out: Velocity2D): Velocity2D;
+//# sourceMappingURL=velocityField.d.ts.map

package/dist/velocityField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocityField.d.ts","sourceRoot":"","sources":["../src/velocityField.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AASjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAMzG;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAE7D;AAID,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,CAc5G;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAMnG;AAGD,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAMtF;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD;AAKD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC7B,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC9B,MAAM,EAAE,MAAM,GACb,UAAU,CAQZ;AAGD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAOzF;AAID,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,UAAU,CAU7F;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKzE;AAID,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAGxF;AAGD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,MAAM,CAEvE;AAGD,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAMrH;AAID,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAa3F;AAID,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAMxG;AAGD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAM9G;AAGD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAE3E;AAGD,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAIxD"}

package/dist/velocityField.js

@@ -0,0 +1,153 @@
+// The VelocityField is the generic seam: any system (physics, tween, camera, manual edit) contributes a
+// source object's screen-space velocity for the current frame, and any consumer reads it. The accessors
+// are source-agnostic — they key on any object, not only nodes (a batch, a custom entity, etc.). The
+// node-graph-specific baseline is contributeTransformVelocity. Explicit contributions win over the
+// baseline regardless of call order, via per-sample explicitFrameId.
+// Adds velocity contributions: `out = a + b`.
+export function addVelocity(out, a, b) {
+    const ax = a.x;
+    const ay = a.y;
+    out.x = ax + b.x;
+    out.y = ay + b.y;
+    return out;
+}
+export function beginVelocityFrame(field) {
+    field.frameId++;
+}
+// Clamps velocity to `maxLength` in-place style: `out` may equal `velocity` (alias-safe).
+// The most common motion-blur safety helper — prevents runaway blur lengths on fast objects.
+export function clampVelocity(out, velocity, maxLength) {
+    const vx = velocity.x;
+    const vy = velocity.y;
+    const lenSq = vx * vx + vy * vy;
+    const maxSq = maxLength * maxLength;
+    if (lenSq > maxSq && lenSq > 0) {
+        const scale = maxLength / Math.sqrt(lenSq);
+        out.x = vx * scale;
+        out.y = vy * scale;
+    }
+    else {
+        out.x = vx;
+        out.y = vy;
+    }
+    return out;
+}
+export function contributeVelocity(field, source, x, y) {
+    const sample = ensureVelocitySample(field, source);
+    sample.velocity.x = x;
+    sample.velocity.y = y;
+    sample.lastFrameId = field.frameId;
+    sample.explicitFrameId = field.frameId;
+}
+// Copies one velocity value into another (alias-safe: out may equal source).
+export function copyVelocity(out, source) {
+    const sx = source.x;
+    const sy = source.y;
+    out.x = sx;
+    out.y = sy;
+    return out;
+}
+export function createVelocityField() {
+    return { samples: new WeakMap(), frameId: 0 };
+}
+// Exponential moving average (EMA) of velocity across frames. Useful for jitter-free motion buffers.
+// `factor` in (0, 1]: 1 = no smoothing (current wins), 0.1 = heavy smoothing (previous dominates).
+// Alias-safe: `out` may equal `current` or `previous`.
+export function dampVelocity(out, current, previous, factor) {
+    const cx = current.x;
+    const cy = current.y;
+    const px = previous.x;
+    const py = previous.y;
+    out.x = cx * factor + px * (1 - factor);
+    out.y = cy * factor + py * (1 - factor);
+    return out;
+}
+// Get-or-create a source's per-frame sample. Shared with the transform-delta contributor in this package.
+export function ensureVelocitySample(field, source) {
+    let sample = field.samples.get(source);
+    if (sample === undefined) {
+        sample = { previousWorldTransform: null, velocity: { x: 0, y: 0 }, lastFrameId: -1, explicitFrameId: -1 };
+        field.samples.set(source, sample);
+    }
+    return sample;
+}
+// Writes the source's current-frame velocity into `out`. Returns zero velocity for sources with no
+// sample or whose sample is stale (not touched this frame).
+export function getVelocity(field, source, out) {
+    const sample = field.samples.get(source);
+    if (sample === undefined || sample.lastFrameId !== field.frameId) {
+        out.x = 0;
+        out.y = 0;
+        return out;
+    }
+    out.x = sample.velocity.x;
+    out.y = sample.velocity.y;
+    return out;
+}
+export function hasVelocity(field, source) {
+    const sample = field.samples.get(source);
+    return (sample !== undefined && sample.lastFrameId === field.frameId && (sample.velocity.x !== 0 || sample.velocity.y !== 0));
+}
+// Returns true if the velocity vector's magnitude is within `epsilon` of zero. Useful for skipping
+// velocity-buffer writes on effectively-still objects.
+export function isVelocityZero(velocity, epsilon) {
+    const e = epsilon ?? 0;
+    return Math.abs(velocity.x) <= e && Math.abs(velocity.y) <= e;
+}
+// Returns the magnitude (length) of the velocity vector.
+export function lengthOfVelocity(velocity) {
+    return Math.sqrt(velocity.x * velocity.x + velocity.y * velocity.y);
+}
+// Linearly interpolates between two velocity values. Alias-safe: `out` may equal `a` or `b`.
+export function lerpVelocity(out, a, b, t) {
+    const ax = a.x;
+    const ay = a.y;
+    out.x = ax + (b.x - ax) * t;
+    out.y = ay + (b.y - ay) * t;
+    return out;
+}
+// Normalizes the velocity vector to unit length. Returns the zero vector when length is zero.
+// Alias-safe: `out` may equal `source`.
+export function normalizeVelocity(out, source) {
+    const sx = source.x;
+    const sy = source.y;
+    const len = Math.sqrt(sx * sx + sy * sy);
+    if (len > 0) {
+        const inv = 1 / len;
+        out.x = sx * inv;
+        out.y = sy * inv;
+    }
+    else {
+        out.x = 0;
+        out.y = 0;
+    }
+    return out;
+}
+// Scales a velocity by a scalar factor. Used for pixel-ratio conversion and unit normalization.
+// Alias-safe: `out` may equal `velocity`.
+export function scaleVelocity(out, velocity, scale) {
+    const vx = velocity.x;
+    const vy = velocity.y;
+    out.x = vx * scale;
+    out.y = vy * scale;
+    return out;
+}
+// Subtracts `b` from `a`: `out = a - b`. Alias-safe.
+export function subtractVelocity(out, a, b) {
+    const ax = a.x;
+    const ay = a.y;
+    out.x = ax - b.x;
+    out.y = ay - b.y;
+    return out;
+}
+// Zeroes a source's velocity this frame — a teleport/cut that must not smear.
+export function suppressVelocity(field, source) {
+    contributeVelocity(field, source, 0, 0);
+}
+// Sets both components to zero.
+export function zeroVelocity(out) {
+    out.x = 0;
+    out.y = 0;
+    return out;
+}
+//# sourceMappingURL=velocityField.js.map

package/dist/velocityField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocityField.js","sourceRoot":"","sources":["../src/velocityField.ts"],"names":[],"mappings":"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"}

package/dist/velocitySample.d.ts

@@ -0,0 +1,3 @@
+import type { Matrix, Velocity2D, VelocitySample } from '@flighthq/types';
+export declare function getVelocitySampleAt(sample: Readonly<VelocitySample>, currentWorldTransform: Readonly<Matrix>, pointX: number, pointY: number, out: Velocity2D): Velocity2D;
+//# sourceMappingURL=velocitySample.d.ts.map

package/dist/velocitySample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocitySample.d.ts","sourceRoot":"","sources":["../src/velocitySample.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAQ1E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,EAChC,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,UAAU,GACd,UAAU,CAoBZ"}

package/dist/velocitySample.js

@@ -0,0 +1,26 @@
+// Returns the per-pixel screen-space velocity at local-space point (`pointX`, `pointY`) by computing
+// `current·p − previous·p` using the sample's stored previousWorldTransform and the node's current world
+// transform. Writes the result into `out`. Returns zero when the sample has no previous transform.
+//
+// Use when the full affine delta (rotation + scale) at a specific point is needed, such as when writing
+// a per-pixel velocity buffer from a screen-space fragment shader.
+export function getVelocitySampleAt(sample, currentWorldTransform, pointX, pointY, out) {
+    if (sample.previousWorldTransform === null) {
+        out.x = 0;
+        out.y = 0;
+        return out;
+    }
+    // Read both transforms into locals before writing out (alias safety, though out is Velocity2D here).
+    const cx = currentWorldTransform.a * pointX + currentWorldTransform.c * pointY + currentWorldTransform.tx;
+    const cy = currentWorldTransform.b * pointX + currentWorldTransform.d * pointY + currentWorldTransform.ty;
+    const px = sample.previousWorldTransform.a * pointX +
+        sample.previousWorldTransform.c * pointY +
+        sample.previousWorldTransform.tx;
+    const py = sample.previousWorldTransform.b * pointX +
+        sample.previousWorldTransform.d * pointY +
+        sample.previousWorldTransform.ty;
+    out.x = cx - px;
+    out.y = cy - py;
+    return out;
+}
+//# sourceMappingURL=velocitySample.js.map

package/dist/velocitySample.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"velocitySample.js","sourceRoot":"","sources":["../src/velocitySample.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,yGAAyG;AACzG,mGAAmG;AACnG,EAAE;AACF,wGAAwG;AACxG,mEAAmE;AACnE,MAAM,UAAU,mBAAmB,CACjC,MAAgC,EAChC,qBAAuC,EACvC,MAAc,EACd,MAAc,EACd,GAAe;IAEf,IAAI,MAAM,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;QAC3C,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACV,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,CAAC;IACb,CAAC;IACD,qGAAqG;IACrG,MAAM,EAAE,GAAG,qBAAqB,CAAC,CAAC,GAAG,MAAM,GAAG,qBAAqB,CAAC,CAAC,GAAG,MAAM,GAAG,qBAAqB,CAAC,EAAE,CAAC;IAC1G,MAAM,EAAE,GAAG,qBAAqB,CAAC,CAAC,GAAG,MAAM,GAAG,qBAAqB,CAAC,CAAC,GAAG,MAAM,GAAG,qBAAqB,CAAC,EAAE,CAAC;IAC1G,MAAM,EAAE,GACN,MAAM,CAAC,sBAAsB,CAAC,CAAC,GAAG,MAAM;QACxC,MAAM,CAAC,sBAAsB,CAAC,CAAC,GAAG,MAAM;QACxC,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;IACnC,MAAM,EAAE,GACN,MAAM,CAAC,sBAAsB,CAAC,CAAC,GAAG,MAAM;QACxC,MAAM,CAAC,sBAAsB,CAAC,CAAC,GAAG,MAAM;QACxC,MAAM,CAAC,sBAAsB,CAAC,EAAE,CAAC;IACnC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAChB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@flighthq/velocity",
+  "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/node": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@flighthq/displayobject": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "Generic per-node velocity field and contributors (transform-delta baseline + explicit overrides)",
+  "sideEffects": false
+}

package/src/transformVelocity.test.ts

@@ -0,0 +1,58 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { invalidateNodeLocalTransform } from '@flighthq/node';
+
+import { contributeTransformVelocity } from './transformVelocity';
+import { beginVelocityFrame, contributeVelocity, createVelocityField, getVelocity } from './velocityField';
+
+describe('contributeTransformVelocity', () => {
+  it('reports zero velocity on the first frame', () => {
+    const field = createVelocityField();
+    const obj = createDisplayObject();
+    contributeTransformVelocity(field, obj);
+    expect(getVelocity(field, obj, { x: 0, y: 0 })).toEqual({ x: 0, y: 0 });
+  });
+
+  it('derives velocity from the world-transform delta between frames', () => {
+    const field = createVelocityField();
+    const obj = createDisplayObject();
+    contributeTransformVelocity(field, obj);
+
+    obj.x = 10;
+    obj.y = -5;
+    invalidateNodeLocalTransform(obj);
+    beginVelocityFrame(field);
+    contributeTransformVelocity(field, obj);
+
+    expect(getVelocity(field, obj, { x: 0, y: 0 })).toEqual({ x: 10, y: -5 });
+  });
+
+  it('lets an explicit contribution override the derived delta regardless of call order', () => {
+    const field = createVelocityField();
+    const obj = createDisplayObject();
+    contributeTransformVelocity(field, obj);
+
+    obj.x = 100;
+    invalidateNodeLocalTransform(obj);
+    beginVelocityFrame(field);
+    contributeVelocity(field, obj, 2, 2); // explicit set before the baseline runs
+    contributeTransformVelocity(field, obj);
+
+    expect(getVelocity(field, obj, { x: 0, y: 0 })).toEqual({ x: 2, y: 2 });
+  });
+
+  it('still updates previousWorldTransform when an explicit override is in effect', () => {
+    const field = createVelocityField();
+    const obj = createDisplayObject();
+    contributeTransformVelocity(field, obj);
+    obj.x = 10;
+    invalidateNodeLocalTransform(obj);
+    beginVelocityFrame(field);
+    contributeVelocity(field, obj, 99, 99);
+    contributeTransformVelocity(field, obj);
+    // On the third frame with no explicit override, previousWorldTransform should reflect frame 2 position.
+    beginVelocityFrame(field);
+    contributeTransformVelocity(field, obj);
+    // No movement between frame 2 and frame 3 — velocity should be zero.
+    expect(getVelocity(field, obj, { x: 0, y: 0 })).toEqual({ x: 0, y: 0 });
+  });
+});

package/src/velocityField.test.ts

@@ -0,0 +1,295 @@
+import {
+  addVelocity,
+  beginVelocityFrame,
+  clampVelocity,
+  contributeVelocity,
+  copyVelocity,
+  createVelocityField,
+  dampVelocity,
+  ensureVelocitySample,
+  getVelocity,
+  hasVelocity,
+  isVelocityZero,
+  lengthOfVelocity,
+  lerpVelocity,
+  normalizeVelocity,
+  scaleVelocity,
+  subtractVelocity,
+  suppressVelocity,
+  zeroVelocity,
+} from './velocityField';
+
+describe('addVelocity', () => {
+  it('adds two velocity vectors', () => {
+    const out = { x: 0, y: 0 };
+    addVelocity(out, { x: 1, y: 2 }, { x: 3, y: 4 });
+    expect(out).toEqual({ x: 4, y: 6 });
+  });
+
+  it('is alias-safe when out equals a', () => {
+    const a = { x: 5, y: 3 };
+    addVelocity(a, a, { x: 1, y: 1 });
+    expect(a).toEqual({ x: 6, y: 4 });
+  });
+});
+
+describe('beginVelocityFrame', () => {
+  it('advances the frame id', () => {
+    const field = createVelocityField();
+    const before = field.frameId;
+    beginVelocityFrame(field);
+    expect(field.frameId).toBe(before + 1);
+  });
+});
+
+describe('clampVelocity', () => {
+  it('returns velocity unchanged when length is within maxLength', () => {
+    const out = { x: 0, y: 0 };
+    clampVelocity(out, { x: 3, y: 0 }, 5);
+    expect(out).toEqual({ x: 3, y: 0 });
+  });
+
+  it('clamps to maxLength when length exceeds maxLength', () => {
+    const out = { x: 0, y: 0 };
+    clampVelocity(out, { x: 10, y: 0 }, 5);
+    expect(out.x).toBeCloseTo(5);
+    expect(out.y).toBeCloseTo(0);
+  });
+
+  it('clamps a diagonal velocity to maxLength', () => {
+    const out = { x: 0, y: 0 };
+    clampVelocity(out, { x: 3, y: 4 }, 2.5);
+    expect(lengthOfVelocity(out)).toBeCloseTo(2.5);
+  });
+
+  it('is alias-safe when out equals velocity', () => {
+    const v = { x: 10, y: 0 };
+    clampVelocity(v, v, 5);
+    expect(v.x).toBeCloseTo(5);
+    expect(v.y).toBeCloseTo(0);
+  });
+
+  it('handles zero-length velocity without division error', () => {
+    const out = { x: 0, y: 0 };
+    clampVelocity(out, { x: 0, y: 0 }, 5);
+    expect(out).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('contributeVelocity', () => {
+  it('records an explicit velocity readable this frame', () => {
+    const field = createVelocityField();
+    const source = {};
+    contributeVelocity(field, source, 3, -4);
+    expect(getVelocity(field, source, { x: 0, y: 0 })).toEqual({ x: 3, y: -4 });
+  });
+
+  it('accepts any object source, not only nodes', () => {
+    const field = createVelocityField();
+    const batchLike = { instances: 12 };
+    contributeVelocity(field, batchLike, 1, 2);
+    expect(getVelocity(field, batchLike, { x: 0, y: 0 })).toEqual({ x: 1, y: 2 });
+  });
+});
+
+describe('copyVelocity', () => {
+  it('copies x and y', () => {
+    const out = { x: 0, y: 0 };
+    copyVelocity(out, { x: 5, y: -3 });
+    expect(out).toEqual({ x: 5, y: -3 });
+  });
+
+  it('is alias-safe when out equals source', () => {
+    const v = { x: 7, y: 2 };
+    copyVelocity(v, v);
+    expect(v).toEqual({ x: 7, y: 2 });
+  });
+});
+
+describe('createVelocityField', () => {
+  it('starts at frame zero and returns zero for unknown sources', () => {
+    const field = createVelocityField();
+    expect(field.frameId).toBe(0);
+    expect(getVelocity(field, {}, { x: 0, y: 0 })).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('dampVelocity', () => {
+  it('returns current at factor=1 (no smoothing)', () => {
+    const out = { x: 0, y: 0 };
+    dampVelocity(out, { x: 10, y: 5 }, { x: 0, y: 0 }, 1);
+    expect(out).toEqual({ x: 10, y: 5 });
+  });
+
+  it('returns previous at factor=0 (full smoothing)', () => {
+    const out = { x: 0, y: 0 };
+    dampVelocity(out, { x: 10, y: 5 }, { x: 2, y: 3 }, 0);
+    expect(out).toEqual({ x: 2, y: 3 });
+  });
+
+  it('blends at factor=0.5', () => {
+    const out = { x: 0, y: 0 };
+    dampVelocity(out, { x: 10, y: 0 }, { x: 0, y: 0 }, 0.5);
+    expect(out).toEqual({ x: 5, y: 0 });
+  });
+
+  it('is alias-safe when out equals current', () => {
+    const current = { x: 10, y: 0 };
+    dampVelocity(current, current, { x: 0, y: 0 }, 0.5);
+    expect(current).toEqual({ x: 5, y: 0 });
+  });
+});
+
+describe('ensureVelocitySample', () => {
+  it('returns the same sample on repeat calls', () => {
+    const field = createVelocityField();
+    const source = {};
+    expect(ensureVelocitySample(field, source)).toBe(ensureVelocitySample(field, source));
+  });
+});
+
+describe('getVelocity', () => {
+  it('returns zero once the sample is stale after the frame advances', () => {
+    const field = createVelocityField();
+    const source = {};
+    contributeVelocity(field, source, 5, 5);
+    beginVelocityFrame(field);
+    expect(getVelocity(field, source, { x: 0, y: 0 })).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('hasVelocity', () => {
+  it('is true for nonzero velocity this frame and false for suppressed', () => {
+    const field = createVelocityField();
+    const moving = {};
+    const still = {};
+    contributeVelocity(field, moving, 1, 0);
+    suppressVelocity(field, still);
+    expect(hasVelocity(field, moving)).toBe(true);
+    expect(hasVelocity(field, still)).toBe(false);
+  });
+});
+
+describe('isVelocityZero', () => {
+  it('returns true for exact zero', () => {
+    expect(isVelocityZero({ x: 0, y: 0 })).toBe(true);
+  });
+
+  it('returns false for nonzero', () => {
+    expect(isVelocityZero({ x: 0.001, y: 0 })).toBe(false);
+  });
+
+  it('respects epsilon', () => {
+    expect(isVelocityZero({ x: 0.001, y: 0 }, 0.01)).toBe(true);
+    expect(isVelocityZero({ x: 0.1, y: 0 }, 0.01)).toBe(false);
+  });
+});
+
+describe('lengthOfVelocity', () => {
+  it('returns the magnitude of the velocity vector', () => {
+    expect(lengthOfVelocity({ x: 3, y: 4 })).toBeCloseTo(5);
+  });
+
+  it('returns 0 for zero vector', () => {
+    expect(lengthOfVelocity({ x: 0, y: 0 })).toBe(0);
+  });
+});
+
+describe('lerpVelocity', () => {
+  it('returns a at t=0', () => {
+    const out = { x: 0, y: 0 };
+    lerpVelocity(out, { x: 1, y: 2 }, { x: 9, y: 8 }, 0);
+    expect(out).toEqual({ x: 1, y: 2 });
+  });
+
+  it('returns b at t=1', () => {
+    const out = { x: 0, y: 0 };
+    lerpVelocity(out, { x: 1, y: 2 }, { x: 9, y: 8 }, 1);
+    expect(out).toEqual({ x: 9, y: 8 });
+  });
+
+  it('interpolates at t=0.5', () => {
+    const out = { x: 0, y: 0 };
+    lerpVelocity(out, { x: 0, y: 0 }, { x: 10, y: 4 }, 0.5);
+    expect(out).toEqual({ x: 5, y: 2 });
+  });
+
+  it('is alias-safe when out equals a', () => {
+    const a = { x: 0, y: 0 };
+    lerpVelocity(a, a, { x: 10, y: 0 }, 0.5);
+    expect(a).toEqual({ x: 5, y: 0 });
+  });
+});
+
+describe('normalizeVelocity', () => {
+  it('returns unit vector for nonzero input', () => {
+    const out = { x: 0, y: 0 };
+    normalizeVelocity(out, { x: 3, y: 4 });
+    expect(lengthOfVelocity(out)).toBeCloseTo(1);
+    expect(out.x).toBeCloseTo(0.6);
+    expect(out.y).toBeCloseTo(0.8);
+  });
+
+  it('returns zero vector for zero input', () => {
+    const out = { x: 0, y: 0 };
+    normalizeVelocity(out, { x: 0, y: 0 });
+    expect(out).toEqual({ x: 0, y: 0 });
+  });
+
+  it('is alias-safe when out equals source', () => {
+    const v = { x: 5, y: 0 };
+    normalizeVelocity(v, v);
+    expect(v).toEqual({ x: 1, y: 0 });
+  });
+});
+
+describe('scaleVelocity', () => {
+  it('scales by a factor', () => {
+    const out = { x: 0, y: 0 };
+    scaleVelocity(out, { x: 3, y: -2 }, 2);
+    expect(out).toEqual({ x: 6, y: -4 });
+  });
+
+  it('is alias-safe when out equals velocity', () => {
+    const v = { x: 4, y: 2 };
+    scaleVelocity(v, v, 0.5);
+    expect(v).toEqual({ x: 2, y: 1 });
+  });
+});
+
+describe('subtractVelocity', () => {
+  it('subtracts b from a', () => {
+    const out = { x: 0, y: 0 };
+    subtractVelocity(out, { x: 5, y: 3 }, { x: 2, y: 1 });
+    expect(out).toEqual({ x: 3, y: 2 });
+  });
+
+  it('is alias-safe when out equals a', () => {
+    const a = { x: 5, y: 3 };
+    subtractVelocity(a, a, { x: 2, y: 1 });
+    expect(a).toEqual({ x: 3, y: 2 });
+  });
+});
+
+describe('suppressVelocity', () => {
+  it('zeroes a previously set velocity', () => {
+    const field = createVelocityField();
+    const source = {};
+    contributeVelocity(field, source, 9, 9);
+    suppressVelocity(field, source);
+    expect(getVelocity(field, source, { x: 0, y: 0 })).toEqual({ x: 0, y: 0 });
+  });
+});
+
+describe('zeroVelocity', () => {
+  it('sets both components to zero', () => {
+    const v = { x: 5, y: -3 };
+    zeroVelocity(v);
+    expect(v).toEqual({ x: 0, y: 0 });
+  });
+
+  it('returns the out reference', () => {
+    const v = { x: 1, y: 1 };
+    expect(zeroVelocity(v)).toBe(v);
+  });
+});

package/src/velocitySample.test.ts

@@ -0,0 +1,61 @@
+import { createMatrix } from '@flighthq/geometry';
+
+import { createVelocityField, ensureVelocitySample } from './velocityField';
+import { getVelocitySampleAt } from './velocitySample';
+
+describe('getVelocitySampleAt', () => {
+  it('returns zero when the sample has no previousWorldTransform', () => {
+    const field = createVelocityField();
+    const source = {};
+    const sample = ensureVelocitySample(field, source);
+    const identity = createMatrix();
+    const out = { x: 99, y: 99 };
+    getVelocitySampleAt(sample, identity, 0, 0, out);
+    expect(out).toEqual({ x: 0, y: 0 });
+  });
+
+  it('returns translation delta at the origin when transform is translation-only', () => {
+    const field = createVelocityField();
+    const source = {};
+    const sample = ensureVelocitySample(field, source);
+    sample.previousWorldTransform = createMatrix(1, 0, 0, 1, 3, 4);
+    const current = createMatrix(1, 0, 0, 1, 8, 9);
+    const out = { x: 0, y: 0 };
+    getVelocitySampleAt(sample, current, 0, 0, out);
+    expect(out).toEqual({ x: 5, y: 5 });
+  });
+
+  it('computes affine reprojection for a non-origin point', () => {
+    const field = createVelocityField();
+    const source = {};
+    const sample = ensureVelocitySample(field, source);
+    sample.previousWorldTransform = createMatrix();
+    const current = createMatrix(1, 0, 0, 1, 2, 3);
+    const out = { x: 0, y: 0 };
+    getVelocitySampleAt(sample, current, 1, 0, out);
+    expect(out).toEqual({ x: 2, y: 3 });
+  });
+
+  it('computes correct velocity for a rotating transform at a non-origin point', () => {
+    const field = createVelocityField();
+    const source = {};
+    const sample = ensureVelocitySample(field, source);
+    sample.previousWorldTransform = createMatrix();
+    const rotated90 = createMatrix(0, 1, -1, 0, 0, 0);
+    const out = { x: 0, y: 0 };
+    getVelocitySampleAt(sample, rotated90, 1, 0, out);
+    expect(out.x).toBeCloseTo(-1);
+    expect(out.y).toBeCloseTo(1);
+  });
+
+  it('is alias-safe when out references a different object (basic alias check)', () => {
+    const field = createVelocityField();
+    const source = {};
+    const sample = ensureVelocitySample(field, source);
+    sample.previousWorldTransform = createMatrix(1, 0, 0, 1, 1, 2);
+    const current = createMatrix(1, 0, 0, 1, 4, 6);
+    const out = { x: 0, y: 0 };
+    getVelocitySampleAt(sample, current, 0, 0, out);
+    expect(out).toEqual({ x: 3, y: 4 });
+  });
+});