feat: add onFrame lifecycle function

Author: Rich-Harris

.changeset/tasty-kangaroos-greet.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: add `onFrame` lifecycle function

packages/svelte/src/index-client.js

@@ -161,6 +161,32 @@ export function afterUpdate(fn) {
 	init_update_callbacks(component_context).a.push(fn);
 }
 
+/**
+ * The `onFrame` function schedules a callback to run on `requestAnimationFrame`. It must be called inside an effect (e.g. during component initialisation).
+ *
+ * `onFrame` does not run inside [server-side components](https://svelte.dev/docs/svelte/svelte-server#render).
+ *
+ * @template T
+ * @param {() => NotFunction<T> | Promise<NotFunction<T>> | (() => any)} fn
+ * @returns {void}
+ */
+export function onFrame(fn) {
+	onMount(() => {
+		let frame = -1;
+
+		function next() {
+			frame = requestAnimationFrame(next);
+			fn();
+		}
+
+		next();
+
+		return () => {
+			cancelAnimationFrame(frame);
+		};
+	});
+}
+
 /**
  * Legacy-mode: Init callbacks object for onMount/beforeUpdate/afterUpdate
  * @param {ComponentContext} context

packages/svelte/types/index.d.ts

@@ -408,6 +408,13 @@ declare module 'svelte' {
 	 * @deprecated Use [`$effect`](https://svelte.dev/docs/svelte/$effect) instead
 	 * */
 	export function afterUpdate(fn: () => void): void;
+	/**
+	 * The `onFrame` function schedules a callback to run on `requestAnimationFrame`. It must be called inside an effect (e.g. during component initialisation).
+	 *
+	 * `onFrame` does not run inside [server-side components](https://svelte.dev/docs/svelte/svelte-server#render).
+	 *
+	 * */
+	export function onFrame<T>(fn: () => NotFunction<T> | Promise<NotFunction<T>> | (() => any)): void;
 	/**
 	 * Synchronously flushes any pending state changes and those that result from it.
 	 * */
@@ -1671,6 +1678,7 @@ declare module 'svelte/motion' {
 	 * <input type="range" bind:value={spring.target} />
 	 * <input type="range" bind:value={spring.current} disabled />
 	 * ```
+	 * @since 5.8.0
 	 */
 	export class Spring<T> {
 		constructor(value: T, options?: SpringOpts);