micro-canvas-confetti-native 0.1.0 → 1.0.0

package/src/physics/collect.ts

@@ -1,100 +1,100 @@
-import {
-	COIN_SIZE,
-	COLLECT_ARC_BEND,
-	COLLECT_END_SCALE,
-	COLLECT_FADE_START,
-	COLLECT_FLIGHT_JITTER_MS,
-	COLLECT_ORIGIN_SCATTER,
-	COLLECT_SPIN_RANGE,
-	COLLECT_STAGGER_JITTER_MS,
-	COLLECT_START_SCALE,
-	CONFETTI_WIDTH_RANGE,
-	MIN_FLATNESS,
-} from "../constants";
-import type { CollectFrame, CollectPiece, ConfettiOrigin, ResolvedCollectOptions } from "../types";
-import { easeInOutCubic, easeInQuad, lerp, pickRandom, randomInRange } from "../utils/math";
-import { computeWobbleScale } from "./wobble";
-
-/** Creates the pieces of a collect flight from `origin` to `target`. */
-export function spawnCollectPieces(options: ResolvedCollectOptions): CollectPiece[] {
-	const { origin, target } = options;
-	const dx = target.x - origin.x;
-	const dy = target.y - origin.y;
-	const distance = Math.hypot(dx, dy);
-	// Unit normal to the flight line; arcs bow to either side of it.
-	const normalX = distance > 0 ? -dy / distance : 0;
-	const normalY = distance > 0 ? dx / distance : 0;
-	const size =
-		options.appearance === "coin"
-			? COIN_SIZE * options.scalar
-			: CONFETTI_WIDTH_RANGE[1] * options.scalar;
-
-	const pieces: CollectPiece[] = [];
-	let delayMs = 0;
-	for (let i = 0; i < options.particleCount; i++) {
-		const scatterAngle = randomInRange(0, Math.PI * 2);
-		const scatter = randomInRange(0, COLLECT_ORIGIN_SCATTER);
-		const startX = origin.x + Math.cos(scatterAngle) * scatter;
-		const startY = origin.y + Math.sin(scatterAngle) * scatter;
-		const bend = randomInRange(-COLLECT_ARC_BEND, COLLECT_ARC_BEND) * distance;
-
-		pieces.push({
-			startX,
-			startY,
-			controlX: (startX + target.x) / 2 + normalX * bend,
-			controlY: (startY + target.y) / 2 + normalY * bend,
-			endX: target.x,
-			endY: target.y,
-			delayMs,
-			flightMs: Math.max(
-				1,
-				options.flightMs + randomInRange(-COLLECT_FLIGHT_JITTER_MS, COLLECT_FLIGHT_JITTER_MS),
-			),
-			size,
-			color: pickRandom(options.colors),
-			shape: pickRandom(options.shapes),
-			wobblePhase: randomInRange(0, Math.PI * 2),
-			wobbleSpeed: randomInRange(...COLLECT_SPIN_RANGE),
-		});
-
-		if (options.staggerMs > 0) {
-			delayMs += Math.max(
-				0,
-				options.staggerMs + randomInRange(-COLLECT_STAGGER_JITTER_MS, COLLECT_STAGGER_JITTER_MS),
-			);
-		}
-	}
-	return pieces;
-}
-
-/** Point the rest of the flight at a new window position, keeping the arc shape. */
-export function retargetCollectPiece(piece: CollectPiece, target: ConfettiOrigin): void {
-	const dx = target.x - piece.endX;
-	const dy = target.y - piece.endY;
-	if (dx === 0 && dy === 0) return;
-	piece.endX = target.x;
-	piece.endY = target.y;
-	piece.controlX += dx;
-	piece.controlY += dy;
-}
-
-/** Position, size, and opacity of a collect piece `elapsedMs` after the flight started. */
-export function sampleCollectPiece(piece: CollectPiece, elapsedMs: number): CollectFrame {
-	const local = elapsedMs - piece.delayMs;
-	const t = Math.min(1, Math.max(0, local / piece.flightMs));
-	const path = easeInOutCubic(t);
-	const inv = 1 - path;
-	const x = inv * inv * piece.startX + 2 * inv * path * piece.controlX + path * path * piece.endX;
-	const y = inv * inv * piece.startY + 2 * inv * path * piece.controlY + path * path * piece.endY;
-	const fade = t <= COLLECT_FADE_START ? 1 : 1 - (t - COLLECT_FADE_START) / (1 - COLLECT_FADE_START);
-	const spinSeconds = Math.max(0, local) / 1000;
-
-	return {
-		x,
-		y,
-		scale: lerp(COLLECT_START_SCALE, COLLECT_END_SCALE, easeInQuad(t)),
-		scaleX: computeWobbleScale(piece.wobblePhase + piece.wobbleSpeed * spinSeconds, MIN_FLATNESS),
-		opacity: local < 0 ? 0 : Math.max(0, fade),
-		done: t >= 1,
-	};
-}
+import {
+	COIN_SIZE,
+	COLLECT_ARC_BEND,
+	COLLECT_END_SCALE,
+	COLLECT_FADE_START,
+	COLLECT_FLIGHT_JITTER_MS,
+	COLLECT_ORIGIN_SCATTER,
+	COLLECT_SPIN_RANGE,
+	COLLECT_STAGGER_JITTER_MS,
+	COLLECT_START_SCALE,
+	CONFETTI_WIDTH_RANGE,
+	MIN_FLATNESS,
+} from "../constants";
+import type { CollectFrame, CollectPiece, ConfettiOrigin, ResolvedCollectOptions } from "../types";
+import { easeInOutCubic, easeInQuad, lerp, pickRandom, randomInRange } from "../utils/math";
+import { computeWobbleScale } from "./wobble";
+
+/** Creates the pieces of a collect flight from `origin` to `target`. */
+export function spawnCollectPieces(options: ResolvedCollectOptions): CollectPiece[] {
+	const { origin, target } = options;
+	const dx = target.x - origin.x;
+	const dy = target.y - origin.y;
+	const distance = Math.hypot(dx, dy);
+	// Unit normal to the flight line; arcs bow to either side of it.
+	const normalX = distance > 0 ? -dy / distance : 0;
+	const normalY = distance > 0 ? dx / distance : 0;
+	const size =
+		options.appearance === "coin"
+			? COIN_SIZE * options.scalar
+			: CONFETTI_WIDTH_RANGE[1] * options.scalar;
+
+	const pieces: CollectPiece[] = [];
+	let delayMs = 0;
+	for (let i = 0; i < options.particleCount; i++) {
+		const scatterAngle = randomInRange(0, Math.PI * 2);
+		const scatter = randomInRange(0, COLLECT_ORIGIN_SCATTER);
+		const startX = origin.x + Math.cos(scatterAngle) * scatter;
+		const startY = origin.y + Math.sin(scatterAngle) * scatter;
+		const bend = randomInRange(-COLLECT_ARC_BEND, COLLECT_ARC_BEND) * distance;
+
+		pieces.push({
+			startX,
+			startY,
+			controlX: (startX + target.x) / 2 + normalX * bend,
+			controlY: (startY + target.y) / 2 + normalY * bend,
+			endX: target.x,
+			endY: target.y,
+			delayMs,
+			flightMs: Math.max(
+				1,
+				options.flightMs + randomInRange(-COLLECT_FLIGHT_JITTER_MS, COLLECT_FLIGHT_JITTER_MS),
+			),
+			size,
+			color: pickRandom(options.colors),
+			shape: pickRandom(options.shapes),
+			wobblePhase: randomInRange(0, Math.PI * 2),
+			wobbleSpeed: randomInRange(...COLLECT_SPIN_RANGE),
+		});
+
+		if (options.staggerMs > 0) {
+			delayMs += Math.max(
+				0,
+				options.staggerMs + randomInRange(-COLLECT_STAGGER_JITTER_MS, COLLECT_STAGGER_JITTER_MS),
+			);
+		}
+	}
+	return pieces;
+}
+
+/** Point the rest of the flight at a new window position, keeping the arc shape. */
+export function retargetCollectPiece(piece: CollectPiece, target: ConfettiOrigin): void {
+	const dx = target.x - piece.endX;
+	const dy = target.y - piece.endY;
+	if (dx === 0 && dy === 0) return;
+	piece.endX = target.x;
+	piece.endY = target.y;
+	piece.controlX += dx;
+	piece.controlY += dy;
+}
+
+/** Position, size, and opacity of a collect piece `elapsedMs` after the flight started. */
+export function sampleCollectPiece(piece: CollectPiece, elapsedMs: number): CollectFrame {
+	const local = elapsedMs - piece.delayMs;
+	const t = Math.min(1, Math.max(0, local / piece.flightMs));
+	const path = easeInOutCubic(t);
+	const inv = 1 - path;
+	const x = inv * inv * piece.startX + 2 * inv * path * piece.controlX + path * path * piece.endX;
+	const y = inv * inv * piece.startY + 2 * inv * path * piece.controlY + path * path * piece.endY;
+	const fade = t <= COLLECT_FADE_START ? 1 : 1 - (t - COLLECT_FADE_START) / (1 - COLLECT_FADE_START);
+	const spinSeconds = Math.max(0, local) / 1000;
+
+	return {
+		x,
+		y,
+		scale: lerp(COLLECT_START_SCALE, COLLECT_END_SCALE, easeInQuad(t)),
+		scaleX: computeWobbleScale(piece.wobblePhase + piece.wobbleSpeed * spinSeconds, MIN_FLATNESS),
+		opacity: local < 0 ? 0 : Math.max(0, fade),
+		done: t >= 1,
+	};
+}

package/src/physics/drag.ts

@@ -1,15 +1,15 @@
-/** Applies exponential drag to a scalar velocity. */
-export function applyDrag(velocity: number, drag: number, dt: number): number {
-	return velocity * Math.exp(-drag * dt);
-}
-
-/** Applies exponential drag to a 2D velocity vector. */
-export function applyDrag2D(
-	vx: number,
-	vy: number,
-	drag: number,
-	dt: number,
-): { vx: number; vy: number } {
-	const dragDecay = Math.exp(-drag * dt);
-	return { vx: vx * dragDecay, vy: vy * dragDecay };
-}
+/** Applies exponential drag to a scalar velocity. */
+export function applyDrag(velocity: number, drag: number, dt: number): number {
+	return velocity * Math.exp(-drag * dt);
+}
+
+/** Applies exponential drag to a 2D velocity vector. */
+export function applyDrag2D(
+	vx: number,
+	vy: number,
+	drag: number,
+	dt: number,
+): { vx: number; vy: number } {
+	const dragDecay = Math.exp(-drag * dt);
+	return { vx: vx * dragDecay, vy: vy * dragDecay };
+}

package/src/physics/spawn.ts

@@ -1,139 +1,139 @@
-import {
-	COIN_ROTATION_FACTOR,
-	COIN_SIZE,
-	CONFETTI_HEIGHT_RANGE,
-	CONFETTI_WIDTH_RANGE,
-	CULL_MARGIN,
-	SETTLE_VELOCITY_THRESHOLD,
-	SETTLE_Y_OFFSET,
-} from "../constants";
-import type { Particle, PhysicsConfig, ResolvedConfettiOptions, Viewport } from "../types";
-import { degreesToRadians, pickRandom, randomInRange } from "../utils/math";
-import { applyDrag2D } from "./drag";
-
-/** Builds one piece with randomized size, color, and initial velocity. */
-function createBaseParticle(
-	options: ResolvedConfettiOptions,
-	theta: number,
-	speed: number,
-	reachLimit: number,
-): Particle {
-	const isCoin = options.appearance === "coin";
-	const coinSize = COIN_SIZE * options.scalar;
-	const ticksMax = options.ticks > 0 ? options.ticks : 0;
-	const rotationFactor = isCoin ? COIN_ROTATION_FACTOR : 1;
-
-	return {
-		x: options.origin.x,
-		y: options.origin.y,
-		vx: Math.cos(theta) * speed,
-		vy: Math.sin(theta) * speed,
-		width: isCoin ? coinSize : randomInRange(...CONFETTI_WIDTH_RANGE) * options.scalar,
-		height: isCoin ? coinSize : randomInRange(...CONFETTI_HEIGHT_RANGE) * options.scalar,
-		color: pickRandom(options.colors),
-		shape: pickRandom(options.shapes),
-		rotation: isCoin ? 0 : randomInRange(0, Math.PI * 2),
-		rotationSpeed: randomInRange(-Math.PI, Math.PI) * options.rotationSpeed * rotationFactor,
-		wobblePhase: randomInRange(0, Math.PI * 2),
-		wobbleSpeed: randomInRange(2, 6) * options.wobbleSpeed,
-		opacity: 1,
-		ticks: ticksMax > 0 ? ticksMax : Number.MAX_SAFE_INTEGER,
-		ticksMax,
-		spawnX: options.origin.x,
-		spawnY: options.origin.y,
-		burstRadius: reachLimit,
-	};
-}
-
-/** Per-piece speed spread — slower pieces stay nearer the origin when reach is limited. */
-function resolveSpawnSpeed(options: ResolvedConfettiOptions): number {
-	const minFactor = options.burstRadius > 0 ? 0.15 : 0.55;
-	return randomInRange(options.startVelocity * minFactor, options.startVelocity);
-}
-
-/** Slightly varies reach per piece so the boundary is not a perfect ring. */
-function resolveReachLimit(options: ResolvedConfettiOptions): number {
-	if (options.burstRadius <= 0) return 0;
-	return options.burstRadius * randomInRange(0.82, 1);
-}
-
-/** Creates all pieces for a burst from resolved options. */
-export function spawnParticles(options: ResolvedConfettiOptions): Particle[] {
-	const particles: Particle[] = [];
-	const baseAngleRad = degreesToRadians(options.angle);
-	const spreadRad = degreesToRadians(Math.min(options.spread, 360));
-
-	for (let i = 0; i < options.particleCount; i++) {
-		const angleOffset =
-			options.spread >= 360
-				? randomInRange(0, Math.PI * 2)
-				: randomInRange(-spreadRad / 2, spreadRad / 2);
-		const theta = baseAngleRad + angleOffset;
-		let particle = createBaseParticle(
-			options,
-			theta,
-			resolveSpawnSpeed(options),
-			resolveReachLimit(options),
-		);
-
-		if (options.createParticle) {
-			const overrides = options.createParticle(i, particle);
-			particle = {
-				...particle,
-				...overrides,
-				spawnX: particle.spawnX,
-				spawnY: particle.spawnY,
-				burstRadius: particle.burstRadius,
-			};
-		}
-
-		particles.push(particle);
-	}
-
-	return particles;
-}
-
-/** Advances one piece by a single simulation step. */
-export function integrateParticle(particle: Particle, dt: number, config: PhysicsConfig): void {
-	particle.vy += config.gravity * dt;
-
-	const dragged = applyDrag2D(particle.vx, particle.vy, config.drag, dt);
-	particle.vx = dragged.vx;
-	particle.vy = dragged.vy;
-
-	particle.x += particle.vx * dt;
-	particle.y += particle.vy * dt;
-
-	particle.rotation += particle.rotationSpeed * dt;
-	particle.rotationSpeed *= Math.exp(-config.rotationDrag * dt);
-
-	particle.wobblePhase += particle.wobbleSpeed * dt;
-	particle.wobbleSpeed *= Math.exp(-config.wobbleDrag * dt);
-
-	if (particle.ticksMax > 0) {
-		const lifeRatio = Math.max(0, particle.ticks / particle.ticksMax);
-		particle.opacity = lifeRatio * (1 - config.decay);
-	} else if (config.decay > 0) {
-		particle.opacity = Math.max(0, particle.opacity - config.decay * dt * 60);
-	}
-
-	particle.ticks -= 1;
-}
-
-/** Returns true when a piece should be removed from the simulation. */
-export function isParticleDead(particle: Particle, viewport: Viewport, originY: number): boolean {
-	if (particle.ticks <= 0) return true;
-	if (particle.opacity <= 0) return true;
-	if (particle.burstRadius > 0) {
-		const dx = particle.x - particle.spawnX;
-		const dy = particle.y - particle.spawnY;
-		if (dx * dx + dy * dy > particle.burstRadius * particle.burstRadius) {
-			return true;
-		}
-	}
-	if (particle.y > viewport.height + CULL_MARGIN) return true;
-	if (particle.x < -CULL_MARGIN || particle.x > viewport.width + CULL_MARGIN) return true;
-
-	const speed = Math.abs(particle.vx) + Math.abs(particle.vy);
-	return speed < SETTLE_VELOCITY_THRESHOLD && particle.y > originY + SETTLE_Y_OFFSET;
-}
+import {
+	COIN_ROTATION_FACTOR,
+	COIN_SIZE,
+	CONFETTI_HEIGHT_RANGE,
+	CONFETTI_WIDTH_RANGE,
+	CULL_MARGIN,
+	SETTLE_VELOCITY_THRESHOLD,
+	SETTLE_Y_OFFSET,
+} from "../constants";
+import type { Particle, PhysicsConfig, ResolvedConfettiOptions, Viewport } from "../types";
+import { degreesToRadians, pickRandom, randomInRange } from "../utils/math";
+import { applyDrag2D } from "./drag";
+
+/** Builds one piece with randomized size, color, and initial velocity. */
+function createBaseParticle(
+	options: ResolvedConfettiOptions,
+	theta: number,
+	speed: number,
+	reachLimit: number,
+): Particle {
+	const isCoin = options.appearance === "coin";
+	const coinSize = COIN_SIZE * options.scalar;
+	const ticksMax = options.ticks > 0 ? options.ticks : 0;
+	const rotationFactor = isCoin ? COIN_ROTATION_FACTOR : 1;
+
+	return {
+		x: options.origin.x,
+		y: options.origin.y,
+		vx: Math.cos(theta) * speed,
+		vy: Math.sin(theta) * speed,
+		width: isCoin ? coinSize : randomInRange(...CONFETTI_WIDTH_RANGE) * options.scalar,
+		height: isCoin ? coinSize : randomInRange(...CONFETTI_HEIGHT_RANGE) * options.scalar,
+		color: pickRandom(options.colors),
+		shape: pickRandom(options.shapes),
+		rotation: isCoin ? 0 : randomInRange(0, Math.PI * 2),
+		rotationSpeed: randomInRange(-Math.PI, Math.PI) * options.rotationSpeed * rotationFactor,
+		wobblePhase: randomInRange(0, Math.PI * 2),
+		wobbleSpeed: randomInRange(2, 6) * options.wobbleSpeed,
+		opacity: 1,
+		ticks: ticksMax > 0 ? ticksMax : Number.MAX_SAFE_INTEGER,
+		ticksMax,
+		spawnX: options.origin.x,
+		spawnY: options.origin.y,
+		burstRadius: reachLimit,
+	};
+}
+
+/** Per-piece speed spread — slower pieces stay nearer the origin when reach is limited. */
+function resolveSpawnSpeed(options: ResolvedConfettiOptions): number {
+	const minFactor = options.burstRadius > 0 ? 0.15 : 0.55;
+	return randomInRange(options.startVelocity * minFactor, options.startVelocity);
+}
+
+/** Slightly varies reach per piece so the boundary is not a perfect ring. */
+function resolveReachLimit(options: ResolvedConfettiOptions): number {
+	if (options.burstRadius <= 0) return 0;
+	return options.burstRadius * randomInRange(0.82, 1);
+}
+
+/** Creates all pieces for a burst from resolved options. */
+export function spawnParticles(options: ResolvedConfettiOptions): Particle[] {
+	const particles: Particle[] = [];
+	const baseAngleRad = degreesToRadians(options.angle);
+	const spreadRad = degreesToRadians(Math.min(options.spread, 360));
+
+	for (let i = 0; i < options.particleCount; i++) {
+		const angleOffset =
+			options.spread >= 360
+				? randomInRange(0, Math.PI * 2)
+				: randomInRange(-spreadRad / 2, spreadRad / 2);
+		const theta = baseAngleRad + angleOffset;
+		let particle = createBaseParticle(
+			options,
+			theta,
+			resolveSpawnSpeed(options),
+			resolveReachLimit(options),
+		);
+
+		if (options.createParticle) {
+			const overrides = options.createParticle(i, particle);
+			particle = {
+				...particle,
+				...overrides,
+				spawnX: particle.spawnX,
+				spawnY: particle.spawnY,
+				burstRadius: particle.burstRadius,
+			};
+		}
+
+		particles.push(particle);
+	}
+
+	return particles;
+}
+
+/** Advances one piece by a single simulation step. */
+export function integrateParticle(particle: Particle, dt: number, config: PhysicsConfig): void {
+	particle.vy += config.gravity * dt;
+
+	const dragged = applyDrag2D(particle.vx, particle.vy, config.drag, dt);
+	particle.vx = dragged.vx;
+	particle.vy = dragged.vy;
+
+	particle.x += particle.vx * dt;
+	particle.y += particle.vy * dt;
+
+	particle.rotation += particle.rotationSpeed * dt;
+	particle.rotationSpeed *= Math.exp(-config.rotationDrag * dt);
+
+	particle.wobblePhase += particle.wobbleSpeed * dt;
+	particle.wobbleSpeed *= Math.exp(-config.wobbleDrag * dt);
+
+	if (particle.ticksMax > 0) {
+		const lifeRatio = Math.max(0, particle.ticks / particle.ticksMax);
+		particle.opacity = lifeRatio * (1 - config.decay);
+	} else if (config.decay > 0) {
+		particle.opacity = Math.max(0, particle.opacity - config.decay * dt * 60);
+	}
+
+	particle.ticks -= 1;
+}
+
+/** Returns true when a piece should be removed from the simulation. */
+export function isParticleDead(particle: Particle, viewport: Viewport, originY: number): boolean {
+	if (particle.ticks <= 0) return true;
+	if (particle.opacity <= 0) return true;
+	if (particle.burstRadius > 0) {
+		const dx = particle.x - particle.spawnX;
+		const dy = particle.y - particle.spawnY;
+		if (dx * dx + dy * dy > particle.burstRadius * particle.burstRadius) {
+			return true;
+		}
+	}
+	if (particle.y > viewport.height + CULL_MARGIN) return true;
+	if (particle.x < -CULL_MARGIN || particle.x > viewport.width + CULL_MARGIN) return true;
+
+	const speed = Math.abs(particle.vx) + Math.abs(particle.vy);
+	return speed < SETTLE_VELOCITY_THRESHOLD && particle.y > originY + SETTLE_Y_OFFSET;
+}

package/src/physics/wobble.ts

@@ -1,11 +1,11 @@
-import { MIN_FLATNESS } from "../constants";
-
-/** Returns the horizontal scale for 3D wobble on a rotating piece. */
-export function computeWobbleScale(phase: number, minFlatness: number = MIN_FLATNESS): number {
-	return Math.max(minFlatness, Math.abs(Math.cos(phase)));
-}
-
-/** Returns the skew applied to simulate depth during wobble. */
-export function computeSkewX(phase: number, skewFactor: number): number {
-	return Math.sin(phase) * skewFactor;
-}
+import { MIN_FLATNESS } from "../constants";
+
+/** Returns the horizontal scale for 3D wobble on a rotating piece. */
+export function computeWobbleScale(phase: number, minFlatness: number = MIN_FLATNESS): number {
+	return Math.max(minFlatness, Math.abs(Math.cos(phase)));
+}
+
+/** Returns the skew applied to simulate depth during wobble. */
+export function computeSkewX(phase: number, skewFactor: number): number {
+	return Math.sin(phase) * skewFactor;
+}

package/src/sequence.ts

@@ -1,39 +1,39 @@
-import type { ConfettiOptions, ConfettiSequenceHandle, ConfettiSequenceStep } from "./types";
-
-type BurstFn = (options?: ConfettiOptions) => unknown;
-
-/** Builds a sequence runner that schedules bursts through the given trigger function. */
-export function createSequenceRunner(
-	burst: BurstFn,
-): (steps: readonly ConfettiSequenceStep[]) => ConfettiSequenceHandle {
-	return (steps) => {
-		const timers: ReturnType<typeof setTimeout>[] = [];
-		let cancelled = false;
-
-		const promise = new Promise<void>((resolve) => {
-			if (steps.length === 0) {
-				resolve();
-				return;
-			}
-			let completed = 0;
-			for (const step of steps) {
-				timers.push(
-					setTimeout(() => {
-						if (cancelled) return;
-						burst(step.options);
-						completed += 1;
-						if (completed >= steps.length) resolve();
-					}, step.delay),
-				);
-			}
-		});
-
-		return {
-			cancel: () => {
-				cancelled = true;
-				for (const timer of timers) clearTimeout(timer);
-			},
-			promise,
-		};
-	};
-}
+import type { ConfettiOptions, ConfettiSequenceHandle, ConfettiSequenceStep } from "./types";
+
+type BurstFn = (options?: ConfettiOptions) => unknown;
+
+/** Builds a sequence runner that schedules bursts through the given trigger function. */
+export function createSequenceRunner(
+	burst: BurstFn,
+): (steps: readonly ConfettiSequenceStep[]) => ConfettiSequenceHandle {
+	return (steps) => {
+		const timers: ReturnType<typeof setTimeout>[] = [];
+		let cancelled = false;
+
+		const promise = new Promise<void>((resolve) => {
+			if (steps.length === 0) {
+				resolve();
+				return;
+			}
+			let completed = 0;
+			for (const step of steps) {
+				timers.push(
+					setTimeout(() => {
+						if (cancelled) return;
+						burst(step.options);
+						completed += 1;
+						if (completed >= steps.length) resolve();
+					}, step.delay),
+				);
+			}
+		});
+
+		return {
+			cancel: () => {
+				cancelled = true;
+				for (const timer of timers) clearTimeout(timer);
+			},
+			promise,
+		};
+	};
+}