fix: align list of passive events with browser defaults, and add documentation (#12933)

closes #12639

Author: Rich-Harris

.changeset/famous-mirrors-count.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+fix: align list of passive events with browser defaults

documentation/docs/02-template-syntax/02-basic-markup.md

@@ -112,6 +112,10 @@ Because events are just attributes, the same rules as for attributes apply:
 
 Timing-wise, event attributes always fire after events from bindings (e.g. `oninput` always fires after an update to `bind:value`). Under the hood, some event handlers are attached directly with `addEventListener`, while others are _delegated_.
 
+When using `onwheel`, `onmousewheel`, `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to align with browser defaults. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`.
+
+In the very rare cases that you need to prevent these event defaults, you should use [`on`](https://svelte-5-preview.vercel.app/docs/imports#svelte-events) instead (for example inside an action).
+
 ### Event delegation
 
 To reduce memory footprint and increase performance, Svelte uses a technique called event delegation. This means that for certain events — see the list below — a single event listener at the application root takes responsibility for running any handlers on the event's path.

packages/svelte/src/utils.js

@@ -222,7 +222,7 @@ export function is_dom_property(name) {
 	return DOM_PROPERTIES.includes(name);
 }
 
-const PASSIVE_EVENTS = ['wheel', 'touchstart', 'touchmove', 'touchend', 'touchcancel'];
+const PASSIVE_EVENTS = ['wheel', 'mousewheel', 'touchstart', 'touchmove'];
 
 /**
  * Returns `true` if `name` is a passive event

sites/svelte-5-preview/src/routes/docs/content/03-appendix/02-breaking-changes.md

@@ -238,6 +238,12 @@ This is [no longer true in Svelte 5](/#H4sIAAAAAAAAE4WQwU7DMAyGX8VESANpXe8lq9Q8A
 <svelte:component this={Thing} />
 ```
 
+### Touch and wheel events are passive
+
+When using `onwheel`, `onmousewheel`, `ontouchstart` and `ontouchmove` event attributes, the handlers are [passive](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#using_passive_listeners) to align with browser defaults. This greatly improves responsiveness by allowing the browser to scroll the document immediately, rather than waiting to see if the event handler calls `event.preventDefault()`.
+
+In the very rare cases that you need to prevent these event defaults, you should use [`on`](https://svelte-5-preview.vercel.app/docs/imports#svelte-events) instead (for example inside an action).
+
 ## Other breaking changes
 
 ### Stricter `@const` assignment validation