tensum 0.1.0

package/src/gsap/spring-track-policy.ts

@@ -0,0 +1,133 @@
+import type { SettlingResult, SpringSolution, SpringState } from '../types.js';
+
+export const UNSETTLED_POLICIES = [
+  'continue',
+  'stop',
+  'snap',
+  'error',
+] as const;
+export type UnsettledPolicy = (typeof UNSETTLED_POLICIES)[number];
+
+export interface SpringTrackSampleSource {
+  readonly duration: number;
+  readonly settling: SettlingResult;
+  readonly spring: SpringSolution;
+  readonly target: number;
+}
+
+export interface SpringTrackTiming {
+  readonly driverDuration: number;
+  readonly finiteDuration: number;
+  readonly hasUnsettled: boolean;
+  readonly logicalDuration: number;
+  readonly requestedLogicalDuration: number;
+  readonly unsettledAt: number;
+}
+
+const GSAP_TIME_PRECISION = 1e7;
+
+export function validateUnsettledPolicy(
+  value: unknown,
+  context = 'unsettled',
+): UnsettledPolicy {
+  if (
+    value !== 'continue' &&
+    value !== 'stop' &&
+    value !== 'snap' &&
+    value !== 'error'
+  ) {
+    throw new TypeError(
+      `${context} must be one of: ${UNSETTLED_POLICIES.join(', ')}`,
+    );
+  }
+  return value;
+}
+
+export function gsapSafeDuration(duration: number): number {
+  if (!Number.isFinite(duration) || duration < 0) {
+    throw new RangeError(
+      'GSAP duration must be a finite number greater than or equal to 0',
+    );
+  }
+  const wholeSeconds = Math.floor(duration);
+  const fractionalSeconds = duration - wholeSeconds;
+  const rounded =
+    wholeSeconds +
+    Math.ceil(fractionalSeconds * GSAP_TIME_PRECISION) / GSAP_TIME_PRECISION;
+  return Number.isFinite(rounded) ? rounded : duration;
+}
+
+export function gsapDriverTime(
+  elapsed: number,
+  finiteDuration: number,
+  driverDuration: number = gsapSafeDuration(finiteDuration),
+): number {
+  if (!Number.isFinite(elapsed) || elapsed < 0) {
+    throw new RangeError(
+      'elapsed time must be a finite number greater than or equal to 0',
+    );
+  }
+  if (finiteDuration === 0 || elapsed >= finiteDuration) return driverDuration;
+  return (elapsed / finiteDuration) * driverDuration;
+}
+
+export function springElapsedTime(
+  driverTime: number,
+  finiteDuration: number,
+  driverDuration: number = gsapSafeDuration(finiteDuration),
+): number {
+  if (!Number.isFinite(driverTime) || driverTime < 0) {
+    throw new RangeError(
+      'driver time must be a finite number greater than or equal to 0',
+    );
+  }
+  if (finiteDuration === 0 || driverDuration === 0) return 0;
+  if (driverTime >= driverDuration) return finiteDuration;
+  return (driverTime / driverDuration) * finiteDuration;
+}
+
+export function springTrackState(
+  track: SpringTrackSampleSource,
+  time: number,
+  policy: UnsettledPolicy,
+): SpringState {
+  if (track.settling.settled && time >= track.duration) {
+    return { position: track.target, velocity: 0 };
+  }
+  if (!track.settling.settled && time >= track.duration) {
+    if (policy === 'snap') return { position: track.target, velocity: 0 };
+    if (policy === 'continue') return track.spring.stateAt(time);
+    return track.spring.stateAt(track.duration);
+  }
+  return track.spring.stateAt(time);
+}
+
+export function springTrackTiming(
+  tracks: readonly SpringTrackSampleSource[],
+  policy: UnsettledPolicy,
+): SpringTrackTiming {
+  const finiteDuration = Math.max(...tracks.map((track) => track.duration), 0);
+  const hasUnsettled = tracks.some((track) => !track.settling.settled);
+  const requestedLogicalDuration = Math.max(
+    ...tracks.map((track) => track.spring.timing.perceptualDuration),
+    0,
+  );
+  const logicalDuration =
+    policy === 'continue' && hasUnsettled
+      ? requestedLogicalDuration
+      : Math.min(requestedLogicalDuration, finiteDuration);
+
+  return {
+    driverDuration: gsapSafeDuration(finiteDuration),
+    finiteDuration,
+    hasUnsettled,
+    logicalDuration,
+    requestedLogicalDuration,
+    unsettledAt: Math.max(
+      ...tracks
+        .filter((track) => !track.settling.settled)
+        .map((track) => track.duration),
+      0,
+    ),
+  };
+}

package/src/gsap/track-lifecycle.ts

@@ -0,0 +1,53 @@
+import type { ActiveTrackRegistration } from './active-tracks.js';
+
+export interface ActiveTrackTransition {
+  readonly isOwner: boolean;
+  readonly releasedAtStart: boolean;
+  readonly restoredPrevious: boolean;
+}
+
+/**
+ * Keeps registry membership aligned with GSAP playback without allowing a
+ * discarded forward-running track to reclaim ownership. Earlier registrations
+ * may reactivate only when their local clock moves backwards.
+ */
+export function syncActiveTrackRegistration(
+  registration: ActiveTrackRegistration,
+  time: number,
+  lastTime: number,
+  options: { retainAtStart?: boolean } = {},
+): ActiveTrackTransition {
+  if (
+    !options.retainAtStart &&
+    time <= 0 &&
+    lastTime > 0 &&
+    registration.isActive()
+  ) {
+    const restored = registration.release();
+    return {
+      isOwner: false,
+      releasedAtStart: true,
+      restoredPrevious: restored,
+    };
+  }
+
+  if (
+    time > 0 &&
+    !registration.isActive() &&
+    (lastTime <= 0 || time < lastTime)
+  ) {
+    registration.activate();
+  }
+
+  return {
+    isOwner: registration.isOwner(),
+    releasedAtStart: false,
+    restoredPrevious: false,
+  };
+}
+
+export function retireActiveTrackRegistrations(
+  registrations: Iterable<ActiveTrackRegistration | undefined>,
+): void {
+  for (const registration of registrations) registration?.retire();
+}

package/src/index.ts

@@ -0,0 +1,130 @@
+export { createSpring } from './spring.js';
+export { createSpringModel } from './model.js';
+export { createVectorSpring } from './vector.js';
+export {
+  springCharacteristics,
+  springParameters,
+  springPresets,
+} from './parameters.js';
+export {
+  MOTION_COMPATIBILITY_COMMIT,
+  MOTION_COMPATIBILITY_VERSION,
+  motionSpringParameters,
+} from './motion-compatibility.js';
+export {
+  CRITICAL_DAMPING_TOLERANCE,
+  angularFrequency,
+  classifyDamping,
+  dampingRatio,
+} from './math.js';
+export { createAnalyticalSolver, validateSpringParameters } from './solver.js';
+export {
+  DEFAULT_SETTLING_OPTIONS,
+  getSettlingResult,
+  resolveSettlingOptions,
+  validateSettlingOptions,
+} from './settling.js';
+export type {
+  SettlingResult,
+  SpringInitialState,
+  SpringOptions,
+  SpringParameters,
+  SpringRegime,
+  SpringSettleInput,
+  SpringSettlingOptions,
+  SpringSolution,
+  SpringState,
+  SpringTiming,
+  SpringTimingInput,
+} from './types.js';
+export type {
+  PerceptualSpringInput,
+  ResponseSpringInput,
+  SettlingDurationSpringInput,
+  SpringCharacteristics,
+  SpringParameterConverters,
+  SpringPreset,
+  SpringPresetOptions,
+  SpringPresets,
+  VisualSpringInput,
+} from './parameters.js';
+export type {
+  MotionDurationSpringInput,
+  MotionSpringParameterConverters,
+  MotionVisualDurationSpringInput,
+} from './motion-compatibility.js';
+export type { SpringModel } from './model.js';
+export type {
+  MutableVectorSpringState,
+  VectorSpringOptions,
+  VectorSpringSolution,
+  VectorSpringState,
+} from './vector.js';
+export {
+  createMotionSpringTween,
+  registerSpringPlugin,
+} from './gsap/plugin.js';
+export type {
+  MotionSpringEffectTweenVars,
+  MotionSpringEffectVars,
+  MotionSpringVars,
+} from './gsap/plugin.js';
+export { SUPPORTED_PROPERTIES, springTo } from './gsap/spring-to.js';
+export type {
+  BuiltInSpringProperty,
+  SpringController,
+  SpringProperty,
+  SpringPropertyAdapter,
+  SpringPropertyOptions,
+  SpringSolutionMap,
+  SpringStateMap,
+  SpringTargetValue,
+  SpringTargets,
+  SpringTweenTarget,
+  SpringToSnapshot,
+  SpringToVars,
+  SpringVelocities,
+  UnsettledPolicy,
+} from './gsap/spring-to.js';
+export { createSpringValue } from './support/spring-value.js';
+export { createAdditiveSpringValue } from './support/additive-spring-value.js';
+export { createSpringKeyframes } from './support/keyframes.js';
+export { createInertia, snapToGrid } from './support/inertia.js';
+export {
+  normalizedVelocity,
+  physicalVelocity,
+  velocityFromSamples,
+} from './support/velocity.js';
+export type {
+  AdditiveSpringContributionOptions,
+  AdditiveSpringEvent,
+  AdditiveSpringListener,
+  AdditiveSpringOptions,
+  AdditiveSpringSnapshot,
+  AdditiveSpringValue,
+} from './support/additive-spring-value.js';
+export type {
+  SpringKeyframe,
+  SpringKeyframeSegment,
+  SpringKeyframeSequence,
+  SpringKeyframesOptions,
+} from './support/keyframes.js';
+export type {
+  InertiaBoundaryTransition,
+  InertiaOptions,
+  InertiaPhase,
+  InertiaSolution,
+} from './support/inertia.js';
+export type {
+  FrameDriver,
+  SpringValue,
+  SpringValueEvent,
+  SpringValueListener,
+  SpringValueOptions,
+  SpringValueRetargetOptions,
+  SpringValueSnapshot,
+} from './support/spring-value.js';
+export type {
+  VelocityFromSamplesOptions,
+  VelocitySample,
+} from './support/velocity.js';

package/src/math.ts

@@ -0,0 +1,46 @@
+import type { SpringParameters, SpringRegime } from './types.js';
+
+export const CRITICAL_DAMPING_TOLERANCE = 1e-7;
+
+export function angularFrequency({ mass, stiffness }: SpringParameters): number {
+  return Math.sqrt(stiffness) / Math.sqrt(mass);
+}
+
+export function dampingDecayRate({ mass, damping }: SpringParameters): number {
+  if (damping === 0) return 0;
+
+  // Divide the larger operand first so a representable c / (2m) is not lost
+  // to either an overflowing ratio or an underflowing c / 2 intermediate.
+  return damping > mass ? damping / 2 / mass : damping / mass / 2;
+}
+
+export function dampingRatio(parameters: SpringParameters): number {
+  return dampingDecayRate(parameters) / angularFrequency(parameters);
+}
+
+export function classifyDamping(
+  ratio: number,
+  tolerance: number = CRITICAL_DAMPING_TOLERANCE,
+): SpringRegime {
+  assertFinite('dampingRatio', ratio);
+  assertFinite('tolerance', tolerance);
+  if (ratio < 0) {
+    throw new RangeError('dampingRatio must be greater than or equal to 0');
+  }
+  if (tolerance < 0) {
+    throw new RangeError('tolerance must be greater than or equal to 0');
+  }
+  if (Math.abs(ratio - 1) <= tolerance) return 'critical';
+  return ratio < 1 ? 'underdamped' : 'overdamped';
+}
+
+export function assertFinite(name: string, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be a finite number`);
+  }
+}
+
+export function assertNonNegativeTime(time: number): void {
+  assertFinite('time', time);
+  if (time < 0) throw new RangeError('time must be greater than or equal to 0');
+}

package/src/model.ts

@@ -0,0 +1,70 @@
+import { assertFinite } from './math.js';
+import { springCharacteristics } from './parameters.js';
+import { getSettlingResult, resolveSettlingOptions } from './settling.js';
+import { createAnalyticalSolver, validateInitialState } from './solver.js';
+import {
+  createSpringSolution,
+  type SpringSolutionOptions,
+} from './spring.js';
+import type { SpringCharacteristics } from './parameters.js';
+import type {
+  SettlingResult,
+  SpringInitialState,
+  SpringParameters,
+  SpringSettleInput,
+  SpringSolution,
+  SpringState,
+} from './types.js';
+
+export interface SpringModel {
+  readonly parameters: Readonly<SpringParameters>;
+  readonly characteristics: Readonly<SpringCharacteristics>;
+  force(state: SpringState, target: number): number;
+  stateAt(initial: SpringInitialState, time: number): SpringState;
+  advance(state: SpringState, target: number, deltaTime: number): SpringState;
+  settling(initial: SpringInitialState, options?: SpringSettleInput): SettlingResult;
+  solve(initial: SpringInitialState, options?: SpringSolutionOptions): SpringSolution;
+}
+
+export function createSpringModel(parameters: SpringParameters): SpringModel {
+  const characteristics = springCharacteristics(parameters);
+  const canonicalParameters: Readonly<SpringParameters> = Object.freeze({
+    mass: parameters.mass,
+    stiffness: parameters.stiffness,
+    damping: parameters.damping,
+  });
+
+  return Object.freeze({
+    parameters: canonicalParameters,
+    characteristics,
+    force(state: SpringState, target: number): number {
+      validateInitialState({ ...state, target });
+      const force =
+        -canonicalParameters.stiffness * (state.position - target) -
+        canonicalParameters.damping * state.velocity;
+      assertFinite('force', force);
+      return force;
+    },
+    stateAt(initial: SpringInitialState, time: number): SpringState {
+      return createAnalyticalSolver(canonicalParameters, initial).stateAt(time);
+    },
+    advance(state: SpringState, target: number, deltaTime: number): SpringState {
+      return createAnalyticalSolver(canonicalParameters, { ...state, target }).stateAt(
+        deltaTime,
+      );
+    },
+    settling(
+      initial: SpringInitialState,
+      options?: SpringSettleInput,
+    ): SettlingResult {
+      const solver = createAnalyticalSolver(canonicalParameters, initial);
+      return getSettlingResult(solver, resolveSettlingOptions(options));
+    },
+    solve(
+      initial: SpringInitialState,
+      options?: SpringSolutionOptions,
+    ): SpringSolution {
+      return createSpringSolution(canonicalParameters, initial, options);
+    },
+  });
+}

package/src/motion-compatibility.ts

@@ -0,0 +1,131 @@
+import { assertFinite } from './math.js';
+import { springParameters } from './parameters.js';
+import type { SpringParameters } from './types.js';
+
+export const MOTION_COMPATIBILITY_VERSION = '13.1.0';
+export const MOTION_COMPATIBILITY_COMMIT =
+  'adaf7a4e5368d704ea350669f6ac674fb26ff270';
+
+const SAFE_MINIMUM = 0.001;
+const ROOT_ITERATIONS = 12;
+const MIN_DURATION = 0.01;
+const MAX_DURATION = 10;
+const MIN_DAMPING_RATIO = 0.05;
+const MAX_DAMPING_RATIO = 1;
+
+export interface MotionDurationSpringInput {
+  /** Public compatibility input in seconds. Motion's audited generator stores this in ms. */
+  duration: number;
+  bounce?: number;
+}
+
+export interface MotionVisualDurationSpringInput {
+  visualDuration: number;
+  bounce?: number;
+}
+
+export interface MotionSpringParameterConverters {
+  fromDuration(input: MotionDurationSpringInput): Readonly<SpringParameters>;
+  fromVisualDuration(input: MotionVisualDurationSpringInput): Readonly<SpringParameters>;
+}
+
+function clamp(minimum: number, maximum: number, value: number): number {
+  return Math.min(Math.max(value, minimum), maximum);
+}
+
+function assertPositive(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value <= 0) throw new RangeError(`${name} must be greater than 0`);
+}
+
+function approximateRoot(
+  envelope: (frequency: number) => number,
+  derivative: (frequency: number) => number,
+  initialGuess: number,
+): number {
+  let result = initialGuess;
+  for (let iteration = 1; iteration < ROOT_ITERATIONS; iteration += 1) {
+    result -= envelope(result) / derivative(result);
+  }
+  return result;
+}
+
+function durationParameters(
+  requestedDuration: number,
+  requestedBounce: number,
+): Readonly<SpringParameters> {
+  assertPositive('duration', requestedDuration);
+  assertFinite('bounce', requestedBounce);
+
+  const duration = clamp(MIN_DURATION, MAX_DURATION, requestedDuration);
+  const ratio = clamp(
+    MIN_DAMPING_RATIO,
+    MAX_DAMPING_RATIO,
+    1 - requestedBounce,
+  );
+  let envelope: (frequency: number) => number;
+  let derivative: (frequency: number) => number;
+
+  if (ratio < 1) {
+    envelope = (frequency: number): number => {
+      const exponentialDecay = frequency * ratio;
+      const dampedFrequency = frequency * Math.sqrt(1 - ratio * ratio);
+      return (
+        SAFE_MINIMUM -
+        (exponentialDecay / dampedFrequency) *
+          Math.exp(-exponentialDecay * duration)
+      );
+    };
+    derivative = (frequency: number): number => {
+      const exponentialDecay = frequency * ratio;
+      const squaredDecay = ratio * ratio * frequency * frequency * duration;
+      const decay = Math.exp(-exponentialDecay * duration);
+      const squaredDampedFrequency =
+        frequency * frequency * Math.sqrt(1 - ratio * ratio);
+      const factor = -envelope(frequency) + SAFE_MINIMUM > 0 ? -1 : 1;
+      return (factor * -squaredDecay * decay) / squaredDampedFrequency;
+    };
+  } else {
+    envelope = (frequency: number): number =>
+      -SAFE_MINIMUM +
+      Math.exp(-frequency * duration) * (frequency * duration + 1);
+    derivative = (frequency: number): number =>
+      Math.exp(-frequency * duration) * -frequency * duration * duration;
+  }
+
+  const frequency = approximateRoot(envelope, derivative, 5 / duration);
+  if (!Number.isFinite(frequency) || frequency <= 0) {
+    // This mirrors the audited generator's deterministic fallback, while the
+    // compatibility module keeps it explicit and isolated from canonical APIs.
+    return springParameters.fromPhysics({ mass: 1, stiffness: 100, damping: 10 });
+  }
+
+  return springParameters.fromPhysics({
+    mass: 1,
+    stiffness: frequency * frequency,
+    damping: ratio * 2 * frequency,
+  });
+}
+
+export const motionSpringParameters: MotionSpringParameterConverters = Object.freeze({
+  fromDuration({
+    duration,
+    bounce = 0.3,
+  }: MotionDurationSpringInput): Readonly<SpringParameters> {
+    return durationParameters(duration, bounce);
+  },
+  fromVisualDuration({
+    visualDuration,
+    bounce = 0,
+  }: MotionVisualDurationSpringInput): Readonly<SpringParameters> {
+    assertPositive('visualDuration', visualDuration);
+    assertFinite('bounce', bounce);
+    const frequency = (2 * Math.PI) / (visualDuration * 1.2);
+    const ratio = clamp(MIN_DAMPING_RATIO, MAX_DAMPING_RATIO, 1 - bounce);
+    return springParameters.fromPhysics({
+      mass: 1,
+      stiffness: frequency * frequency,
+      damping: 2 * ratio * frequency,
+    });
+  },
+});