Create polished demo videos without editing skills. Mac/Windows/Linux
import { describe, expect, it } from "vitest";
import type { ZoomRegion } from "../types";
import { clamp01, cubicBezier, easeOutExpo, easeOutZoom } from "./mathUtils";
import {
clampDeltaMs,
createSpringState,
getCursorSpringConfig,
getZoomSpringConfig,
resetSpringState,
type SpringConfig,
type SpringState,
stepSpringValue,
} from "./motionSmoothing";
import { computeRegionStrength, findDominantRegion } from "./zoomRegionUtils";
// ---------------------------------------------------------------------------
// motionSmoothing — spring state helpers
// ---------------------------------------------------------------------------
describe("createSpringState", () => {
it("returns uninitialized state at 0", () => {
const s = createSpringState();
expect(s).toEqual({ value: 0, velocity: 0, initialized: false });
});
it("accepts a custom initial value", () => {
const s = createSpringState(5);
expect(s.value).toBe(5);
expect(s.initialized).toBe(false);
});
});
describe("resetSpringState", () => {
it("clears velocity and initialized flag", () => {
const s: SpringState = { value: 3, velocity: 10, initialized: true };
resetSpringState(s);
expect(s.velocity).toBe(0);
expect(s.initialized).toBe(false);
expect(s.value).toBe(3); // kept
});
it("resets value when provided", () => {
const s: SpringState = { value: 3, velocity: 10, initialized: true };
resetSpringState(s, 7);
expect(s.value).toBe(7);
expect(s.velocity).toBe(0);
});
});
describe("clampDeltaMs", () => {
it("passes through a normal 16ms frame", () => {
expect(clampDeltaMs(16.67)).toBeCloseTo(16.67, 2);
});
it("clamps negative delta to fallback", () => {
expect(clampDeltaMs(-1)).toBeCloseTo(1000 / 60, 2);
});
it("clamps zero delta to fallback", () => {
expect(clampDeltaMs(0)).toBeCloseTo(1000 / 60, 2);
});
it("clamps NaN to fallback", () => {
expect(clampDeltaMs(Number.NaN)).toBeCloseTo(1000 / 60, 2);
});
it("clamps excessively large delta to 80ms", () => {
expect(clampDeltaMs(500)).toBe(80);
});
});
// ---------------------------------------------------------------------------
// motionSmoothing — stepSpringValue
// ---------------------------------------------------------------------------
describe("stepSpringValue", () => {
const config: SpringConfig = {
stiffness: 320,
damping: 40,
mass: 0.92,
restDelta: 0.0005,
restSpeed: 0.015,
};
it("snaps to target on first tick (initialization)", () => {
const s = createSpringState();
const result = stepSpringValue(s, 1, 16, config);
expect(result).toBe(1);
expect(s.initialized).toBe(true);
});
it("converges toward the target over many ticks", () => {
const s = createSpringState();
stepSpringValue(s, 0, 16, config); // init at 0
// Drive toward 1 over many frames
for (let i = 0; i < 200; i++) {
stepSpringValue(s, 1, 16, config);
}
expect(s.value).toBeCloseTo(1, 3);
});
it("converges within reasonable time for default zoom config", () => {
const zoomConfig = getZoomSpringConfig(1.0);
const s = createSpringState();
stepSpringValue(s, 0, 16, zoomConfig); // init at 0
let frames = 0;
while (Math.abs(s.value - 1) > 0.001 && frames < 500) {
stepSpringValue(s, 1, 16, zoomConfig);
frames++;
}
// Should converge well within 500 frames (~8 seconds)
// High damping (ζ ≈ 2) settles without overshoot but takes longer
expect(frames).toBeLessThan(400); // ~6.5s at 60fps
expect(s.value).toBeCloseTo(1, 2);
});
it("handles target change mid-animation", () => {
const s = createSpringState();
stepSpringValue(s, 0.5, 16, config);
// Animate toward 1
for (let i = 0; i < 30; i++) {
stepSpringValue(s, 1, 16, config);
}
const midway = s.value;
expect(midway).toBeGreaterThan(0.5);
// Reverse direction toward 0
for (let i = 0; i < 200; i++) {
stepSpringValue(s, 0, 16, config);
}
expect(s.value).toBeCloseTo(0, 2);
});
it("settles exactly at target when within rest thresholds", () => {
const s = createSpringState();
stepSpringValue(s, 0, 16, config);
// Manually place near target
s.value = 0.9999;
s.velocity = 0;
stepSpringValue(s, 1, 16, config);
expect(s.value).toBe(1);
expect(s.velocity).toBe(0);
});
it("does not produce NaN or Infinity values", () => {
const s = createSpringState();
stepSpringValue(s, 0, 16, config);
for (let i = 0; i < 300; i++) {
stepSpringValue(s, Math.sin(i * 0.1), 16, config);
expect(Number.isFinite(s.value)).toBe(true);
expect(Number.isFinite(s.velocity)).toBe(true);
}
});
});
// ---------------------------------------------------------------------------
// motionSmoothing — spring configs
// ---------------------------------------------------------------------------
describe("getZoomSpringConfig", () => {
it("returns snap-like config at smoothness 0", () => {
const c = getZoomSpringConfig(0);
expect(c.stiffness).toBe(1000);
expect(c.damping).toBe(100);
});
it("returns the default mapped config at smoothness 0.5", () => {
const c = getZoomSpringConfig(0.5);
expect(c.stiffness).toBe(100);
expect(c.mass).toBeCloseTo(1, 2);
});
it("returns the max mapped config at smoothness 1.0", () => {
const c = getZoomSpringConfig(1.0);
expect(c.stiffness).toBe(50);
expect(c.mass).toBeCloseTo(2, 2);
});
it("clamps values above 1.0 to the max config", () => {
expect(getZoomSpringConfig(2.0)).toEqual(getZoomSpringConfig(1.0));
});
it("clamps values far above 1.0 to the max config", () => {
const c = getZoomSpringConfig(5);
expect(c).toEqual(getZoomSpringConfig(1.0));
});
it("defaults to 0.5 when called without arguments", () => {
expect(getZoomSpringConfig()).toEqual(getZoomSpringConfig(0.5));
});
});
describe("getCursorSpringConfig", () => {
it("returns stiff config at 0 (no smoothing)", () => {
const c = getCursorSpringConfig(0);
expect(c.stiffness).toBe(1000);
});
it("returns config in legacy range at 0.25", () => {
const c = getCursorSpringConfig(0.25);
expect(c.stiffness).toBeLessThan(760);
expect(c.stiffness).toBeGreaterThan(300);
expect(c.mass).toBeGreaterThan(1);
});
it("returns config in extended range at 1.5", () => {
const c = getCursorSpringConfig(1.5);
expect(c.stiffness).toBeLessThan(340);
expect(c.mass).toBeGreaterThan(1.6);
});
it("clamps at max smoothing", () => {
expect(getCursorSpringConfig(999)).toEqual(getCursorSpringConfig(2));
});
it("applies cursor spring tuning multipliers", () => {
const untuned = getCursorSpringConfig(0.5);
const tuned = getCursorSpringConfig(0.5, {
stiffnessMultiplier: 1.5,
dampingMultiplier: 0.75,
massMultiplier: 1.25,
});
expect(tuned.stiffness).toBeCloseTo(untuned.stiffness * 1.5, 6);
expect(tuned.damping).toBeCloseTo(untuned.damping * 0.75, 6);
expect(tuned.mass).toBeCloseTo(untuned.mass * 1.25, 6);
});
});
// ---------------------------------------------------------------------------
// mathUtils
// ---------------------------------------------------------------------------
describe("clamp01", () => {
it("passes values in [0,1]", () => {
expect(clamp01(0.5)).toBe(0.5);
});
it("clamps below 0", () => {
expect(clamp01(-0.1)).toBe(0);
});
it("clamps above 1", () => {
expect(clamp01(1.5)).toBe(1);
});
});
describe("easeOutZoom", () => {
it("starts at 0", () => {
expect(easeOutZoom(0)).toBeCloseTo(0, 4);
});
it("ends at 1", () => {
expect(easeOutZoom(1)).toBeCloseTo(1, 4);
});
it("is monotonically increasing", () => {
let previous = 0;
for (let t = 0.05; t <= 1; t += 0.05) {
const current = easeOutZoom(t);
expect(current).toBeGreaterThanOrEqual(previous);
previous = current;
}
});
it("has steep initial rise (ease-out character)", () => {
// At t=0.25 the curve should already be well above linear (0.25)
expect(easeOutZoom(0.25)).toBeGreaterThan(0.5);
});
});
describe("easeOutExpo", () => {
it("starts at 0 and ends at 1", () => {
expect(easeOutExpo(0)).toBeCloseTo(0, 4);
expect(easeOutExpo(1)).toBe(1);
});
});
describe("cubicBezier", () => {
it("linear bezier returns identity", () => {
for (let t = 0; t <= 1; t += 0.1) {
expect(cubicBezier(0.333, 0.333, 0.666, 0.666, t)).toBeCloseTo(t, 1);
}
});
});
// ---------------------------------------------------------------------------
// zoomRegionUtils — computeRegionStrength
// ---------------------------------------------------------------------------
describe("computeRegionStrength", () => {
const region: ZoomRegion = {
id: "z1",
startMs: 2000,
endMs: 5000,
depth: 2,
focus: { cx: 0.5, cy: 0.5 },
};
it("returns 0 well before the region", () => {
expect(computeRegionStrength(region, 0)).toBe(0);
});
it("does not start playing 300ms before the timeline block", () => {
expect(computeRegionStrength(region, region.startMs - 300)).toBe(0);
expect(computeRegionStrength(region, region.startMs + 300)).toBeGreaterThan(0);
expect(region.startMs).toBe(2000);
expect(region.endMs).toBe(5000);
});
it("returns 0 well after the region", () => {
expect(computeRegionStrength(region, 10000)).toBe(0);
});
it("reaches full strength during the hold phase", () => {
// Mid-region: after zoom-in completes, before zoom-out starts
expect(computeRegionStrength(region, 3500)).toBe(1);
});
it("rises smoothly during zoom-in", () => {
// The entrance ramp is beginning at the timeline block start.
const s = computeRegionStrength(region, region.startMs);
expect(s).toBeGreaterThan(0);
expect(s).toBeLessThan(1);
});
it("falls smoothly during zoom-out", () => {
// Sample the zoom-out ramp after the animation delay.
const zoomOutStart = region.endMs - 150;
const s = computeRegionStrength(region, zoomOutStart + 700);
expect(s).toBeGreaterThan(0);
expect(s).toBeLessThan(1);
});
it("shifts zoom timing when custom durations are provided", () => {
const defaultStrength = computeRegionStrength(region, region.startMs);
const fasterStrength = computeRegionStrength(region, region.startMs, {
zoomInDurationMs: 300,
zoomOutDurationMs: 300,
});
expect(fasterStrength).not.toBe(defaultStrength);
expect(fasterStrength).toBeGreaterThan(defaultStrength);
});
});
// ---------------------------------------------------------------------------
// zoomRegionUtils — findDominantRegion
// ---------------------------------------------------------------------------
describe("findDominantRegion", () => {
it("returns null region when no regions exist", () => {
const result = findDominantRegion([], 1000);
expect(result.region).toBeNull();
expect(result.strength).toBe(0);
});
it("returns the active region at its hold phase", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 4000, depth: 2, focus: { cx: 0.3, cy: 0.3 } },
];
const result = findDominantRegion(regions, 2500);
expect(result.region).not.toBeNull();
expect(result.region!.id).toBe("a");
expect(result.strength).toBe(1);
});
it("returns null region outside all regions", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 2000, depth: 2, focus: { cx: 0.5, cy: 0.5 } },
];
const result = findDominantRegion(regions, 10000);
expect(result.region).toBeNull();
});
it("connects chained zooms when connectZooms is true", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 3000, depth: 2, focus: { cx: 0.2, cy: 0.2 } },
{ id: "b", startMs: 3500, endMs: 6000, depth: 3, focus: { cx: 0.8, cy: 0.8 } },
];
// During the connected handoff, the next region becomes the spring target.
const result = findDominantRegion(regions, 3500, { connectZooms: true });
expect(result.strength).toBe(1);
expect(result.transition).toBeNull();
expect(result.region?.id).toBe("b");
});
it("keeps the outgoing region active until the connected transition begins", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 3000, depth: 2, focus: { cx: 0.2, cy: 0.2 } },
{ id: "b", startMs: 3500, endMs: 6000, depth: 3, focus: { cx: 0.8, cy: 0.8 } },
];
const result = findDominantRegion(regions, 3100, { connectZooms: true });
expect(result.transition).toBeNull();
expect(result.region?.id).toBe("a");
expect(result.strength).toBeGreaterThan(0);
});
it("keeps the incoming region at full strength after a connected handoff", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 3000, depth: 2, focus: { cx: 0.2, cy: 0.2 } },
{ id: "b", startMs: 3500, endMs: 6000, depth: 3, focus: { cx: 0.8, cy: 0.8 } },
];
const result = findDominantRegion(regions, 4300, { connectZooms: true });
expect(result.transition).toBeNull();
expect(result.region?.id).toBe("b");
expect(result.strength).toBe(1);
});
it("does NOT connect zooms with a large gap", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 3000, depth: 2, focus: { cx: 0.2, cy: 0.2 } },
{ id: "b", startMs: 8000, endMs: 10000, depth: 3, focus: { cx: 0.8, cy: 0.8 } },
];
// In the gap — should be no active region
const result = findDominantRegion(regions, 5000, { connectZooms: true });
expect(result.region).toBeNull();
});
it("keeps the next region active during the connected transition", () => {
const regions: ZoomRegion[] = [
{ id: "a", startMs: 1000, endMs: 3000, depth: 2, focus: { cx: 0.2, cy: 0.2 } },
{ id: "b", startMs: 4300, endMs: 7000, depth: 3, focus: { cx: 0.7, cy: 0.7 } },
];
// During the handoff (3500–4500), before b starts (4300).
const result = findDominantRegion(regions, 4250, { connectZooms: true });
expect(result.strength).toBe(1);
expect(result.region).not.toBeNull();
expect(result.region!.id).toBe("b");
});
});
// ---------------------------------------------------------------------------
// ZoomRegion mode field
// ---------------------------------------------------------------------------
describe("ZoomRegion mode field", () => {
it("accepts manual mode", () => {
const r: ZoomRegion = {
id: "m1",
startMs: 0,
endMs: 1000,
depth: 2,
focus: { cx: 0.5, cy: 0.5 },
mode: "manual",
};
expect(r.mode).toBe("manual");
});
it("accepts auto mode", () => {
const r: ZoomRegion = {
id: "a1",
startMs: 0,
endMs: 1000,
depth: 2,
focus: { cx: 0.5, cy: 0.5 },
mode: "auto",
};
expect(r.mode).toBe("auto");
});
it("mode is optional", () => {
const r: ZoomRegion = {
id: "x1",
startMs: 0,
endMs: 1000,
depth: 2,
focus: { cx: 0.5, cy: 0.5 },
};
expect(r.mode).toBeUndefined();
});
});
// ---------------------------------------------------------------------------
// Spring physics — damping regimes
// ---------------------------------------------------------------------------
describe("spring damping regimes", () => {
it("underdamped spring overshoots then converges", () => {
// Low damping → expect overshoot
const config: SpringConfig = {
stiffness: 300,
damping: 10,
mass: 1,
restDelta: 0.0005,
restSpeed: 0.015,
};
const s = createSpringState();
stepSpringValue(s, 0, 16, config);
let maxValue = 0;
for (let i = 0; i < 500; i++) {
stepSpringValue(s, 1, 16, config);
if (s.value > maxValue) maxValue = s.value;
}
// Should have overshot past 1 at some point
expect(maxValue).toBeGreaterThan(1.01);
// But should converge
expect(s.value).toBeCloseTo(1, 1);
});
it("overdamped spring converges without overshoot", () => {
const config: SpringConfig = {
stiffness: 100,
damping: 200,
mass: 1,
restDelta: 0.0005,
restSpeed: 0.015,
};
const s = createSpringState();
stepSpringValue(s, 0, 16, config);
let maxValue = 0;
for (let i = 0; i < 1000; i++) {
stepSpringValue(s, 1, 16, config);
if (s.value > maxValue) maxValue = s.value;
}
// Overdamped should not overshoot
expect(maxValue).toBeLessThanOrEqual(1.001);
// Should still converge (overdamped converges slowly)
expect(s.value).toBeCloseTo(1, 2);
});
it("critically damped spring converges without oscillation", () => {
// ζ = c / (2√(km)) = 1 → c = 2√(km)
const stiffness = 200;
const mass = 1;
const criticalDamping = 2 * Math.sqrt(stiffness * mass);
const config: SpringConfig = {
stiffness,
damping: criticalDamping,
mass,
restDelta: 0.0005,
restSpeed: 0.015,
};
const s = createSpringState();
stepSpringValue(s, 0, 16, config);
for (let i = 0; i < 300; i++) {
stepSpringValue(s, 1, 16, config);
}
expect(s.value).toBeCloseTo(1, 2);
});
});