tensum 0.1.0

package/src/coupled-system.ts

@@ -0,0 +1,383 @@
+export interface CoupledAnchor {
+  target: number;
+  stiffness: number;
+  damping: number;
+}
+
+export interface CoupledParticle {
+  mass: number;
+  position: number;
+  velocity?: number;
+  fixed?: boolean;
+  anchor?: CoupledAnchor;
+  min?: number;
+  max?: number;
+  restitution?: number;
+}
+
+export interface SpringConnection {
+  from: number;
+  to: number;
+  stiffness: number;
+  damping: number;
+  restOffset?: number;
+}
+
+export interface CoupledSpringOptions {
+  particles: readonly CoupledParticle[];
+  connections: readonly SpringConnection[];
+  maxStep?: number;
+}
+
+export interface CoupledSpringState {
+  position: readonly number[];
+  velocity: readonly number[];
+}
+
+export interface MutableCoupledSpringState {
+  position: number[];
+  velocity: number[];
+}
+
+export interface CoupledSpringSystem {
+  readonly dimension: number;
+  readonly particles: readonly Readonly<CoupledParticle>[];
+  readonly connections: readonly Readonly<SpringConnection>[];
+  readonly initialState: Readonly<CoupledSpringState>;
+  readonly maxStep: number;
+  forceAt(state: CoupledSpringState): readonly number[];
+  accelerationAt(state: CoupledSpringState): readonly number[];
+  advance(state: CoupledSpringState, deltaTime: number): CoupledSpringState;
+  advanceInto(
+    state: CoupledSpringState,
+    deltaTime: number,
+    output: MutableCoupledSpringState,
+  ): MutableCoupledSpringState;
+  stateAt(time: number): CoupledSpringState;
+  energyAt(state: CoupledSpringState): number;
+}
+
+const MAX_INTEGRATION_STEPS = 1_000_000;
+
+function assertFinite(name: string, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be a finite number`);
+  }
+}
+
+function assertPositive(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value <= 0) throw new RangeError(`${name} must be greater than 0`);
+}
+
+function assertNonNegative(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value < 0) throw new RangeError(`${name} must be greater than or equal to 0`);
+}
+
+export function createCoupledSpringSystem(
+  options: CoupledSpringOptions,
+): CoupledSpringSystem {
+  if (options.particles.length === 0) {
+    throw new RangeError('a coupled spring system requires at least one particle');
+  }
+  const maxStep = options.maxStep === undefined ? 1 / 240 : options.maxStep;
+  assertPositive('maxStep', maxStep);
+  const particles = Object.freeze(
+    options.particles.map((particle, index) => {
+      assertPositive(`particles[${index}].mass`, particle.mass);
+      assertFinite(`particles[${index}].position`, particle.position);
+      const velocity = particle.velocity === undefined ? 0 : particle.velocity;
+      assertFinite(`particles[${index}].velocity`, velocity);
+      if (particle.min !== undefined) {
+        assertFinite(`particles[${index}].min`, particle.min);
+      }
+      if (particle.max !== undefined) {
+        assertFinite(`particles[${index}].max`, particle.max);
+      }
+      if (
+        particle.min !== undefined &&
+        particle.max !== undefined &&
+        particle.min > particle.max
+      ) {
+        throw new RangeError(`particles[${index}].min must not exceed max`);
+      }
+      const restitution =
+        particle.restitution === undefined ? 0 : particle.restitution;
+      assertFinite(`particles[${index}].restitution`, restitution);
+      if (restitution < 0 || restitution > 1) {
+        throw new RangeError(`particles[${index}].restitution must be between 0 and 1`);
+      }
+      if (particle.anchor) {
+        assertFinite(`particles[${index}].anchor.target`, particle.anchor.target);
+        assertPositive(
+          `particles[${index}].anchor.stiffness`,
+          particle.anchor.stiffness,
+        );
+        assertNonNegative(
+          `particles[${index}].anchor.damping`,
+          particle.anchor.damping,
+        );
+      }
+      return Object.freeze({
+        ...particle,
+        velocity: particle.fixed ? 0 : velocity,
+        restitution,
+        ...(particle.anchor === undefined
+          ? {}
+          : { anchor: Object.freeze({ ...particle.anchor }) }),
+      });
+    }),
+  );
+  const dimension = particles.length;
+  const connections = Object.freeze(
+    options.connections.map((connection, index) => {
+      if (
+        !Number.isInteger(connection.from) ||
+        connection.from < 0 ||
+        connection.from >= dimension
+      ) {
+        throw new RangeError(`connections[${index}].from is out of range`);
+      }
+      if (
+        !Number.isInteger(connection.to) ||
+        connection.to < 0 ||
+        connection.to >= dimension
+      ) {
+        throw new RangeError(`connections[${index}].to is out of range`);
+      }
+      if (connection.from === connection.to) {
+        throw new RangeError(`connections[${index}] must join two particles`);
+      }
+      assertPositive(`connections[${index}].stiffness`, connection.stiffness);
+      assertNonNegative(`connections[${index}].damping`, connection.damping);
+      const restOffset =
+        connection.restOffset === undefined ? 0 : connection.restOffset;
+      assertFinite(`connections[${index}].restOffset`, restOffset);
+      return Object.freeze({ ...connection, restOffset });
+    }),
+  );
+  const fixedPositions = particles.map((particle) => particle.position);
+  const initialState: Readonly<CoupledSpringState> = Object.freeze({
+    position: Object.freeze(particles.map((particle) => particle.position)),
+    velocity: Object.freeze(particles.map((particle) => particle.velocity)),
+  });
+
+  const validateState = (state: CoupledSpringState): void => {
+    if (state.position.length !== dimension || state.velocity.length !== dimension) {
+      throw new RangeError(`state must contain exactly ${dimension} components`);
+    }
+    for (let index = 0; index < dimension; index += 1) {
+      assertFinite(`state.position[${index}]`, state.position[index]!);
+      assertFinite(`state.velocity[${index}]`, state.velocity[index]!);
+    }
+  };
+
+  const forceAtMutable = (
+    position: readonly number[],
+    velocity: readonly number[],
+  ): number[] => {
+    const force = Array<number>(dimension).fill(0);
+    for (let index = 0; index < dimension; index += 1) {
+      const anchor = particles[index]!.anchor;
+      if (!anchor) continue;
+      force[index] =
+        -anchor.stiffness * (position[index]! - anchor.target) -
+        anchor.damping * velocity[index]!;
+    }
+    for (const connection of connections) {
+      const extension =
+        position[connection.to]! -
+        position[connection.from]! -
+        connection.restOffset;
+      const relativeVelocity =
+        velocity[connection.to]! - velocity[connection.from]!;
+      const couplingForce =
+        connection.stiffness * extension + connection.damping * relativeVelocity;
+      force[connection.from]! += couplingForce;
+      force[connection.to]! -= couplingForce;
+    }
+    for (let index = 0; index < dimension; index += 1) {
+      assertFinite(`force[${index}]`, force[index]!);
+    }
+    return force;
+  };
+
+  const derivative = (
+    position: readonly number[],
+    velocity: readonly number[],
+  ): { position: number[]; velocity: number[] } => {
+    const force = forceAtMutable(position, velocity);
+    return {
+      position: velocity.map((value, index) =>
+        particles[index]!.fixed ? 0 : value,
+      ),
+      velocity: force.map((value, index) =>
+        particles[index]!.fixed ? 0 : value / particles[index]!.mass,
+      ),
+    };
+  };
+
+  const integrateStep = (
+    position: number[],
+    velocity: number[],
+    step: number,
+  ): void => {
+    const k1 = derivative(position, velocity);
+    const p2 = position.map((value, index) => value + (k1.position[index]! * step) / 2);
+    const v2 = velocity.map((value, index) => value + (k1.velocity[index]! * step) / 2);
+    const k2 = derivative(p2, v2);
+    const p3 = position.map((value, index) => value + (k2.position[index]! * step) / 2);
+    const v3 = velocity.map((value, index) => value + (k2.velocity[index]! * step) / 2);
+    const k3 = derivative(p3, v3);
+    const p4 = position.map((value, index) => value + k3.position[index]! * step);
+    const v4 = velocity.map((value, index) => value + k3.velocity[index]! * step);
+    const k4 = derivative(p4, v4);
+
+    for (let index = 0; index < dimension; index += 1) {
+      const particle = particles[index]!;
+      if (particle.fixed) {
+        position[index] = fixedPositions[index]!;
+        velocity[index] = 0;
+        continue;
+      }
+      position[index] =
+        position[index]! +
+        (step / 6) *
+        (k1.position[index]! +
+          2 * k2.position[index]! +
+          2 * k3.position[index]! +
+          k4.position[index]!);
+      velocity[index] =
+        velocity[index]! +
+        (step / 6) *
+        (k1.velocity[index]! +
+          2 * k2.velocity[index]! +
+          2 * k3.velocity[index]! +
+          k4.velocity[index]!);
+
+      assertFinite(`position[${index}]`, position[index]!);
+      assertFinite(`velocity[${index}]`, velocity[index]!);
+
+      if (particle.min !== undefined && position[index]! < particle.min) {
+        position[index] = particle.min;
+        if (velocity[index]! < 0) velocity[index] = -velocity[index]! * particle.restitution;
+      }
+      if (particle.max !== undefined && position[index]! > particle.max) {
+        position[index] = particle.max;
+        if (velocity[index]! > 0) velocity[index] = -velocity[index]! * particle.restitution;
+      }
+    }
+  };
+
+  const advanceInto = (
+    state: CoupledSpringState,
+    deltaTime: number,
+    output: MutableCoupledSpringState,
+  ): MutableCoupledSpringState => {
+    validateState(state);
+    assertFinite('deltaTime', deltaTime);
+    if (deltaTime < 0) {
+      throw new RangeError('deltaTime must be greater than or equal to 0');
+    }
+    if (output.position.length < dimension || output.velocity.length < dimension) {
+      throw new RangeError(`output buffers must contain at least ${dimension} components`);
+    }
+    if (deltaTime === 0) {
+      for (let index = 0; index < dimension; index += 1) {
+        output.position[index] = state.position[index]!;
+        output.velocity[index] = state.velocity[index]!;
+      }
+      return output;
+    }
+    const position = Array.from(state.position);
+    const velocity = Array.from(state.velocity);
+    const steps = Math.max(1, Math.ceil(deltaTime / maxStep));
+    if (!Number.isSafeInteger(steps) || steps > MAX_INTEGRATION_STEPS) {
+      throw new RangeError(
+        `advance requires ${steps} integration steps; increase maxStep or split the simulation into smaller calls`,
+      );
+    }
+    const step = deltaTime / steps;
+    for (let index = 0; index < steps; index += 1) {
+      integrateStep(position, velocity, step);
+    }
+    for (let index = 0; index < dimension; index += 1) {
+      output.position[index] = position[index]!;
+      output.velocity[index] = velocity[index]!;
+    }
+    return output;
+  };
+
+  const advance = (
+    state: CoupledSpringState,
+    deltaTime: number,
+  ): CoupledSpringState => {
+    const output = advanceInto(state, deltaTime, {
+      position: Array<number>(dimension),
+      velocity: Array<number>(dimension),
+    });
+    return Object.freeze({
+      position: Object.freeze(output.position),
+      velocity: Object.freeze(output.velocity),
+    });
+  };
+
+  return Object.freeze({
+    dimension,
+    particles,
+    connections,
+    initialState,
+    maxStep,
+    forceAt(state: CoupledSpringState): readonly number[] {
+      validateState(state);
+      return Object.freeze(forceAtMutable(state.position, state.velocity));
+    },
+    accelerationAt(state: CoupledSpringState): readonly number[] {
+      validateState(state);
+      const force = forceAtMutable(state.position, state.velocity);
+      return Object.freeze(
+        force.map((value, index) => {
+          const acceleration = particles[index]!.fixed
+            ? 0
+            : value / particles[index]!.mass;
+          assertFinite(`acceleration[${index}]`, acceleration);
+          return acceleration;
+        }),
+      );
+    },
+    advance,
+    advanceInto,
+    stateAt(time: number): CoupledSpringState {
+      assertFinite('time', time);
+      if (time < 0) throw new RangeError('time must be greater than or equal to 0');
+      if (time === 0) return initialState;
+      return advance(initialState, time);
+    },
+    energyAt(state: CoupledSpringState): number {
+      validateState(state);
+      let energy = 0;
+      for (let index = 0; index < dimension; index += 1) {
+        const particle = particles[index]!;
+        if (!particle.fixed) {
+          energy += (particle.mass * state.velocity[index]! ** 2) / 2;
+        }
+        if (particle.anchor) {
+          energy +=
+            (particle.anchor.stiffness *
+              (state.position[index]! - particle.anchor.target) ** 2) /
+            2;
+        }
+      }
+      for (const connection of connections) {
+        const extension =
+          state.position[connection.to]! -
+          state.position[connection.from]! -
+          connection.restOffset;
+        energy += (connection.stiffness * extension ** 2) / 2;
+      }
+      assertFinite('energy', energy);
+      return energy;
+    },
+  });
+}

package/src/coupled.ts

@@ -0,0 +1,10 @@
+export { createCoupledSpringSystem } from './coupled-system.js';
+export type {
+  CoupledAnchor,
+  CoupledParticle,
+  CoupledSpringOptions,
+  CoupledSpringState,
+  CoupledSpringSystem,
+  MutableCoupledSpringState,
+  SpringConnection,
+} from './coupled-system.js';

package/src/css-linear.ts

@@ -0,0 +1,148 @@
+import type { SpringSolution } from './types.js';
+
+export interface CSSLinearSpringOptions {
+  duration?: number;
+  maxError?: number;
+  maxDepth?: number;
+  maxSamples?: number;
+  precision?: number;
+}
+
+export interface CSSLinearSample {
+  time: number;
+  progress: number;
+}
+
+export interface CSSLinearSpring {
+  easing: string;
+  duration: number;
+  maxError: number;
+  samples: readonly Readonly<CSSLinearSample>[];
+}
+
+function assertPositive(name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${name} must be a finite number greater than 0`);
+  }
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(`${name} must be a positive integer`);
+  }
+}
+
+function rounded(value: number, precision: number): string {
+  const result = Number(value.toFixed(precision));
+  return Object.is(result, -0) ? '0' : String(result);
+}
+
+export function springToCSSLinear(
+  spring: SpringSolution,
+  options: CSSLinearSpringOptions = {},
+): CSSLinearSpring {
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new TypeError('CSS linear options must be an object when provided');
+  }
+  const duration =
+    options.duration === undefined ? spring.timing.settlingDuration : options.duration;
+  const maxError = options.maxError === undefined ? 0.001 : options.maxError;
+  const maxDepth = options.maxDepth === undefined ? 12 : options.maxDepth;
+  const maxSamples = options.maxSamples === undefined ? 4096 : options.maxSamples;
+  const precision = options.precision === undefined ? 6 : options.precision;
+  assertPositive('duration', duration);
+  assertPositive('maxError', maxError);
+  assertPositiveInteger('maxDepth', maxDepth);
+  assertPositiveInteger('maxSamples', maxSamples);
+  if (!Number.isInteger(precision) || precision < 0 || precision > 15) {
+    throw new RangeError('precision must be an integer between 0 and 15');
+  }
+
+  const distance = spring.initialState.target - spring.initialState.position;
+  if (!Number.isFinite(distance)) {
+    throw new RangeError('CSS spring animation distance must be a finite number');
+  }
+  if (distance === 0) {
+    throw new RangeError('CSS spring export requires a non-zero animation distance');
+  }
+
+  const progressAt = (time: number): number => {
+    if (spring.timing.settled && time >= duration) return 1;
+    const progress =
+      (spring.positionAt(time) - spring.initialState.position) / distance;
+    if (!Number.isFinite(progress)) {
+      throw new RangeError('normalized progress must be a finite number');
+    }
+    return progress;
+  };
+  const samples: CSSLinearSample[] = [
+    { time: 0, progress: progressAt(0) },
+  ];
+
+  const append = (sample: CSSLinearSample): void => {
+    if (samples.length >= maxSamples) {
+      throw new RangeError(`CSS linear export exceeded maxSamples (${maxSamples})`);
+    }
+    samples.push(sample);
+  };
+
+  const refine = (
+    start: CSSLinearSample,
+    end: CSSLinearSample,
+    depth: number,
+  ): void => {
+    const span = end.time - start.time;
+    const checkpoints = [0.25, 0.5, 0.75].map((fraction) => {
+      const time = start.time + span * fraction;
+      const progress = progressAt(time);
+      const linear = start.progress + (end.progress - start.progress) * fraction;
+      return { deviation: Math.abs(progress - linear), time, progress };
+    });
+    const needsRefinement = checkpoints.some(
+      ({ deviation }) => deviation > maxError,
+    );
+
+    if (needsRefinement && depth < maxDepth) {
+      const midpoint = checkpoints[1]!;
+      if (midpoint.time === start.time || midpoint.time === end.time) {
+        append(end);
+        return;
+      }
+      const middle = { time: midpoint.time, progress: midpoint.progress };
+      refine(start, middle, depth + 1);
+      refine(middle, end, depth + 1);
+      return;
+    }
+    append(end);
+  };
+
+  // Quarter-period seeds prevent a high-frequency oscillation from aliasing to
+  // deceptively straight midpoint samples before adaptive refinement begins.
+  const seedCount = Math.max(
+    1,
+    Math.ceil((duration * spring.angularFrequency) / (Math.PI / 2)),
+  );
+  if (seedCount + 1 > maxSamples) {
+    throw new RangeError(`CSS linear export requires more than maxSamples (${maxSamples})`);
+  }
+  for (let index = 0; index < seedCount; index += 1) {
+    const start = samples.at(-1)!;
+    const time = ((index + 1) / seedCount) * duration;
+    refine(start, { time, progress: progressAt(time) }, 0);
+  }
+
+  const frozenSamples = Object.freeze(
+    samples.map((sample) => Object.freeze({ ...sample })),
+  );
+  const easing = `linear(${frozenSamples
+    .map(
+      (sample) =>
+        `${rounded(sample.progress, precision)} ${rounded(
+          (sample.time / duration) * 100,
+          precision,
+        )}%`,
+    )
+    .join(', ')})`;
+
+  return Object.freeze({ easing, duration, maxError, samples: frozenSamples });
+}

package/src/css.ts

@@ -0,0 +1,6 @@
+export { springToCSSLinear } from './css-linear.js';
+export type {
+  CSSLinearSample,
+  CSSLinearSpring,
+  CSSLinearSpringOptions,
+} from './css-linear.js';