From 6a6e2af7f72a0c4668cd938d9963d30c576c4713 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Wed, 9 Apr 2025 20:47:55 -0400
Subject: [PATCH 1/8] docs: add inline documentation for svelte/reactivity

---
 packages/svelte/src/reactivity/date.js | 32 ++++++++++++++++++++++++++
 packages/svelte/types/index.d.ts       | 32 ++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/packages/svelte/src/reactivity/date.js b/packages/svelte/src/reactivity/date.js
index 33da2e176159..982f2c41cb90 100644
--- a/packages/svelte/src/reactivity/date.js
+++ b/packages/svelte/src/reactivity/date.js
@@ -5,6 +5,38 @@ import { active_reaction, get, set_active_reaction } from '../internal/client/ru
 
 var inited = false;
 
+/**
+ * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
+ * Reading the date in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (whether with methods like `date.getTime()` or `date.toString()`,
+ * or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) will cause it to be re-evaluated when the
+ * value of the date changes.
+ *
+ * ```svelte
+ * <script>
+ * 	import { SvelteDate } from 'svelte/reactivity';
+ *
+ * 	const date = new SvelteDate();
+ *
+ * 	const formatter = new Intl.DateTimeFormat(undefined, {
+ * 	  hour: 'numeric',
+ * 	  minute: 'numeric',
+ * 	  second: 'numeric'
+ * 	});
+ *
+ * 	$effect(() => {
+ * 		const interval = setInterval(() => {
+ * 			date.setTime(Date.now());
+ * 		}, 1000);
+ *
+ * 		return () => {
+ * 			clearInterval(interval);
+ * 		};
+ * 	});
+ * </script>
+ *
+ * <p>The time is {formatter.format(date)}</p>
+ * ```
+ */
 export class SvelteDate extends Date {
 	#time = source(super.getTime());
 
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index c6000fc4b67f..5722464fafc9 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -1898,6 +1898,38 @@ declare module 'svelte/motion' {
 }
 
 declare module 'svelte/reactivity' {
+	/**
+	 * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
+	 * Reading the date in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (whether with methods like `date.getTime()` or `date.toString()`,
+	 * or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) will cause it to be re-evaluated when the
+	 * value of the date changes.
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { SvelteDate } from 'svelte/reactivity';
+	 *
+	 * 	const date = new SvelteDate();
+	 *
+	 * 	const formatter = new Intl.DateTimeFormat(undefined, {
+	 * 	  hour: 'numeric',
+	 * 	  minute: 'numeric',
+	 * 	  second: 'numeric'
+	 * 	});
+	 *
+	 * 	$effect(() => {
+	 * 		const interval = setInterval(() => {
+	 * 			date.setTime(Date.now());
+	 * 		}, 1000);
+	 *
+	 * 		return () => {
+	 * 			clearInterval(interval);
+	 * 		};
+	 * 	});
+	 * </script>
+	 *
+	 * <p>The time is {formatter.format(date)}</p>
+	 * ```
+	 */
 	export class SvelteDate extends Date {
 		
 		constructor(...params: any[]);

From 435aa92199bf107363eb70b5e684c9d6bef4b6ba Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 14:15:17 -0400
Subject: [PATCH 2/8] map

---
 packages/svelte/src/reactivity/map.js | 41 +++++++++++++++++++++++++
 packages/svelte/types/index.d.ts      | 44 +++++++++++++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/packages/svelte/src/reactivity/map.js b/packages/svelte/src/reactivity/map.js
index 3fa2945ef08c..7c5f28469efb 100644
--- a/packages/svelte/src/reactivity/map.js
+++ b/packages/svelte/src/reactivity/map.js
@@ -5,6 +5,47 @@ import { get } from '../internal/client/runtime.js';
 import { increment } from './utils.js';
 
 /**
+ * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
+ * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293?version=5.25.10) below)
+ * will cause it to be re-evaluated as necessary when the map is updated.
+ *
+ * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ * <script>
+ * 	import { SvelteMap } from 'svelte/reactivity';
+ * 	import { result } from './game.js';
+ *
+ * 	let board = new SvelteMap();
+ * 	let player = $state('x');
+ * 	let winner = $derived(result(board));
+ *
+ * 	function reset() {
+ * 		player = 'x';
+ * 		board.clear();
+ * 	}
+ * </script>
+ *
+ * <div class="board">
+ * 	{#each Array(9), i}
+ * 		<button
+ * 			disabled={board.has(i) || winner}
+ * 			onclick={() => {
+ * 				board.set(i, player);
+ * 				player = player === 'x' ? 'o' : 'x';
+ * 			}}
+ * 		>{board.get(i)}</button>
+ * 	{/each}
+ * </div>
+ *
+ * {#if winner}
+ * 	<p>{winner} wins!</p>
+ * 	<button onclick={reset}>reset</button>
+ * {:else}
+ * 	<p>{player} is next</p>
+ * {/if}
+ * ```
+ *
  * @template K
  * @template V
  * @extends {Map<K, V>}
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 5722464fafc9..5b79eae8023a 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -1942,6 +1942,50 @@ declare module 'svelte/reactivity' {
 		add(value: T): this;
 		#private;
 	}
+	/**
+	 * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
+	 * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293?version=5.25.10) below)
+	 * will cause it to be re-evaluated as necessary when the map is updated.
+	 *
+	 * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { SvelteMap } from 'svelte/reactivity';
+	 * 	import { result } from './game.js';
+	 *
+	 * 	let board = new SvelteMap();
+	 * 	let player = $state('x');
+	 * 	let winner = $derived(result(board));
+	 *
+	 * 	function reset() {
+	 * 		player = 'x';
+	 * 		board.clear();
+	 * 	}
+	 * </script>
+	 *
+	 * <div class="board">
+	 * 	{#each Array(9), i}
+	 * 		<button
+	 * 			disabled={board.has(i) || winner}
+	 * 			onclick={() => {
+	 * 				board.set(i, player);
+	 * 				player = player === 'x' ? 'o' : 'x';
+	 * 			}}
+	 * 		>{board.get(i)}</button>
+	 * 	{/each}
+	 * </div>
+	 *
+	 * {#if winner}
+	 * 	<p>{winner} wins!</p>
+	 * 	<button onclick={reset}>reset</button>
+	 * {:else}
+	 * 	<p>{player} is next</p>
+	 * {/if}
+	 * ```
+	 *
+	 * 
+	 */
 	export class SvelteMap<K, V> extends Map<K, V> {
 		
 		constructor(value?: Iterable<readonly [K, V]> | null | undefined);

From 0985ba97a5deb2dda06cdcb2381441c3c2576d0e Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 14:32:37 -0400
Subject: [PATCH 3/8] set

---
 packages/svelte/src/reactivity/map.js |  2 +-
 packages/svelte/src/reactivity/set.js | 31 +++++++++++++++++++++++
 packages/svelte/types/index.d.ts      | 36 ++++++++++++++++++++++++++-
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/packages/svelte/src/reactivity/map.js b/packages/svelte/src/reactivity/map.js
index 7c5f28469efb..fa986415fb27 100644
--- a/packages/svelte/src/reactivity/map.js
+++ b/packages/svelte/src/reactivity/map.js
@@ -6,7 +6,7 @@ import { increment } from './utils.js';
 
 /**
  * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
- * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293?version=5.25.10) below)
+ * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below)
  * will cause it to be re-evaluated as necessary when the map is updated.
  *
  * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
diff --git a/packages/svelte/src/reactivity/set.js b/packages/svelte/src/reactivity/set.js
index be0c2d2cf5d6..050e7ef3c260 100644
--- a/packages/svelte/src/reactivity/set.js
+++ b/packages/svelte/src/reactivity/set.js
@@ -10,6 +10,37 @@ var set_like_methods = ['difference', 'intersection', 'symmetricDifference', 'un
 var inited = false;
 
 /**
+ * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
+ * Reading contents of the set in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below)
+ * will cause it to be re-evaluated as necessary when the set is updated.
+ *
+ * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+ *
+ * ```svelte
+ * <script>
+ * 	import { SvelteSet } from 'svelte/reactivity';
+ * 	let monkeys = new SvelteSet();
+ *
+ * 	function toggle(monkey) {
+ * 		if (monkeys.has(monkey)) {
+ * 			monkeys.delete(monkey);
+ * 		} else {
+ * 			monkeys.add(monkey);
+ * 		}
+ * 	}
+ * </script>
+ *
+ * {#each ['🙈', '🙉', '🙊'] as monkey}
+ * 	<button onclick={() => toggle(monkey)}>{monkey}</button>
+ * {/each}
+ *
+ * <button onclick={() => monkeys.clear()}>clear</button>
+ *
+ * {#if monkeys.has('🙈')}<p>see no evil</p>{/if}
+ * {#if monkeys.has('🙉')}<p>hear no evil</p>{/if}
+ * {#if monkeys.has('🙊')}<p>speak no evil</p>{/if}
+ * ```
+ *
  * @template T
  * @extends {Set<T>}
  */
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 5b79eae8023a..211c911b66f1 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -1935,6 +1935,40 @@ declare module 'svelte/reactivity' {
 		constructor(...params: any[]);
 		#private;
 	}
+	/**
+	 * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
+	 * Reading contents of the set in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below)
+	 * will cause it to be re-evaluated as necessary when the set is updated.
+	 *
+	 * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { SvelteSet } from 'svelte/reactivity';
+	 * 	let monkeys = new SvelteSet();
+	 *
+	 * 	function toggle(monkey) {
+	 * 		if (monkeys.has(monkey)) {
+	 * 			monkeys.delete(monkey);
+	 * 		} else {
+	 * 			monkeys.add(monkey);
+	 * 		}
+	 * 	}
+	 * </script>
+	 *
+	 * {#each ['🙈', '🙉', '🙊'] as monkey}
+	 * 	<button onclick={() => toggle(monkey)}>{monkey}</button>
+	 * {/each}
+	 *
+	 * <button onclick={() => monkeys.clear()}>clear</button>
+	 *
+	 * {#if monkeys.has('🙈')}<p>see no evil</p>{/if}
+	 * {#if monkeys.has('🙉')}<p>hear no evil</p>{/if}
+	 * {#if monkeys.has('🙊')}<p>speak no evil</p>{/if}
+	 * ```
+	 *
+	 * 
+	 */
 	export class SvelteSet<T> extends Set<T> {
 		
 		constructor(value?: Iterable<T> | null | undefined);
@@ -1944,7 +1978,7 @@ declare module 'svelte/reactivity' {
 	}
 	/**
 	 * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
-	 * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293?version=5.25.10) below)
+	 * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below)
 	 * will cause it to be re-evaluated as necessary when the map is updated.
 	 *
 	 * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).

From 515d056b4e8790255d9f1552cb540b9c9ca796ea Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 15:28:28 -0400
Subject: [PATCH 4/8] more

---
 packages/svelte/src/reactivity/date.js        |  6 +-
 packages/svelte/src/reactivity/map.js         |  2 +-
 packages/svelte/src/reactivity/set.js         |  2 +-
 .../src/reactivity/url-search-params.js       | 27 ++++++++
 packages/svelte/src/reactivity/url.js         | 27 ++++++++
 packages/svelte/types/index.d.ts              | 63 +++++++++++++++++--
 6 files changed, 117 insertions(+), 10 deletions(-)

diff --git a/packages/svelte/src/reactivity/date.js b/packages/svelte/src/reactivity/date.js
index 982f2c41cb90..721673bc36f3 100644
--- a/packages/svelte/src/reactivity/date.js
+++ b/packages/svelte/src/reactivity/date.js
@@ -7,9 +7,9 @@ var inited = false;
 
 /**
  * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
- * Reading the date in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (whether with methods like `date.getTime()` or `date.toString()`,
- * or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) will cause it to be re-evaluated when the
- * value of the date changes.
+ * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat))
+ * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated when the value of the date changes.
  *
  * ```svelte
  * <script>
diff --git a/packages/svelte/src/reactivity/map.js b/packages/svelte/src/reactivity/map.js
index fa986415fb27..3ae8fe5ad19c 100644
--- a/packages/svelte/src/reactivity/map.js
+++ b/packages/svelte/src/reactivity/map.js
@@ -6,7 +6,7 @@ import { increment } from './utils.js';
 
 /**
  * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
- * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below)
+ * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
  * will cause it to be re-evaluated as necessary when the map is updated.
  *
  * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
diff --git a/packages/svelte/src/reactivity/set.js b/packages/svelte/src/reactivity/set.js
index 050e7ef3c260..4a0b4dfdb398 100644
--- a/packages/svelte/src/reactivity/set.js
+++ b/packages/svelte/src/reactivity/set.js
@@ -11,7 +11,7 @@ var inited = false;
 
 /**
  * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
- * Reading contents of the set in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below)
+ * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
  * will cause it to be re-evaluated as necessary when the set is updated.
  *
  * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
diff --git a/packages/svelte/src/reactivity/url-search-params.js b/packages/svelte/src/reactivity/url-search-params.js
index 13f697199643..c1a8275f150b 100644
--- a/packages/svelte/src/reactivity/url-search-params.js
+++ b/packages/svelte/src/reactivity/url-search-params.js
@@ -5,6 +5,32 @@ import { increment } from './utils.js';
 
 export const REPLACE = Symbol();
 
+/**
+ * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
+ * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the params are updated.
+ *
+ * ```svelte
+ * <script>
+ * 	import { SvelteURLSearchParams } from 'svelte/reactivity';
+ *
+ * 	const params = new SvelteURLSearchParams('message=hello');
+ *
+ * 	let key = $state('key');
+ * 	let value = $state('value');
+ * </script>
+ *
+ * <input bind:value={key} />
+ * <input bind:value={value} />
+ * <button onclick={() => params.append(key, value)}>append</button>
+ *
+ * <p>?{params.toString()}</p>
+ *
+ * {#each params as [key, value]}
+ * 	<p>{key}: {value}</p>
+ * {/each}
+ * ```
+ */
 export class SvelteURLSearchParams extends URLSearchParams {
 	#version = source(0);
 	#url = get_current_url();
@@ -23,6 +49,7 @@ export class SvelteURLSearchParams extends URLSearchParams {
 
 	/**
 	 * @param {URLSearchParams} params
+	 * @internal
 	 */
 	[REPLACE](params) {
 		if (this.#updating) return;
diff --git a/packages/svelte/src/reactivity/url.js b/packages/svelte/src/reactivity/url.js
index 5d003be0210a..cb63827e55fd 100644
--- a/packages/svelte/src/reactivity/url.js
+++ b/packages/svelte/src/reactivity/url.js
@@ -10,6 +10,33 @@ export function get_current_url() {
 	return current_url;
 }
 
+/**
+ * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
+ * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+ * will cause it to be re-evaluated as necessary when the URL changes.
+ *
+ * The `searchParams` property is an instance of [SvelteURLSearchParams](http://localhost:5173/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+ *
+ * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
+ *
+ * ```svelte
+ * <script>
+ * 	import { SvelteURL } from 'svelte/reactivity';
+ *
+ * 	const url = new SvelteURL('https://example.com/path');
+ * </script>
+ *
+ * <!-- changes to these... -->
+ * <input bind:value={url.protocol} />
+ * <input bind:value={url.hostname} />
+ * <input bind:value={url.pathname} />
+ *
+ * <hr />
+ *
+ * <!-- will update `href` and vice versa -->
+ * <input bind:value={url.href} size="65" />
+ * ```
+ */
 export class SvelteURL extends URL {
 	#protocol = source(super.protocol);
 	#username = source(super.username);
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 211c911b66f1..c256483037d6 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -1900,9 +1900,9 @@ declare module 'svelte/motion' {
 declare module 'svelte/reactivity' {
 	/**
 	 * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object.
-	 * Reading the date in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (whether with methods like `date.getTime()` or `date.toString()`,
-	 * or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) will cause it to be re-evaluated when the
-	 * value of the date changes.
+	 * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat))
+	 * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+	 * will cause it to be re-evaluated when the value of the date changes.
 	 *
 	 * ```svelte
 	 * <script>
@@ -1937,7 +1937,7 @@ declare module 'svelte/reactivity' {
 	}
 	/**
 	 * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object.
-	 * Reading contents of the set in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below)
+	 * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
 	 * will cause it to be re-evaluated as necessary when the set is updated.
 	 *
 	 * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
@@ -1978,7 +1978,7 @@ declare module 'svelte/reactivity' {
 	}
 	/**
 	 * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object.
-	 * Reading contents of the map in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below)
+	 * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
 	 * will cause it to be re-evaluated as necessary when the map is updated.
 	 *
 	 * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state).
@@ -2027,11 +2027,64 @@ declare module 'svelte/reactivity' {
 		set(key: K, value: V): this;
 		#private;
 	}
+	/**
+	 * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object.
+	 * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+	 * will cause it to be re-evaluated as necessary when the URL changes.
+	 *
+	 * The `searchParams` property is an instance of [SvelteURLSearchParams](http://localhost:5173/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+	 *
+	 * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { SvelteURL } from 'svelte/reactivity';
+	 *
+	 * 	const url = new SvelteURL('https://example.com/path');
+	 * </script>
+	 *
+	 * <!-- changes to these... -->
+	 * <input bind:value={url.protocol} />
+	 * <input bind:value={url.hostname} />
+	 * <input bind:value={url.pathname} />
+	 *
+	 * <hr />
+	 *
+	 * <!-- will update `href` and vice versa -->
+	 * <input bind:value={url.href} size="65" />
+	 * ```
+	 */
 	export class SvelteURL extends URL {
 		get searchParams(): SvelteURLSearchParams;
 		#private;
 	}
 	const REPLACE: unique symbol;
+	/**
+	 * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object.
+	 * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
+	 * will cause it to be re-evaluated as necessary when the params are updated.
+	 *
+	 * ```svelte
+	 * <script>
+	 * 	import { SvelteURLSearchParams } from 'svelte/reactivity';
+	 *
+	 * 	const params = new SvelteURLSearchParams('message=hello');
+	 *
+	 * 	let key = $state('key');
+	 * 	let value = $state('value');
+	 * </script>
+	 *
+	 * <input bind:value={key} />
+	 * <input bind:value={value} />
+	 * <button onclick={() => params.append(key, value)}>append</button>
+	 *
+	 * <p>?{params.toString()}</p>
+	 *
+	 * {#each params as [key, value]}
+	 * 	<p>{key}: {value}</p>
+	 * {/each}
+	 * ```
+	 */
 	export class SvelteURLSearchParams extends URLSearchParams {
 		
 		[REPLACE](params: URLSearchParams): void;

From b7b5179ff9b3a9aa4cb1d9cdbe8aa43c70caeb59 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 15:29:09 -0400
Subject: [PATCH 5/8] dedupe

---
 .../docs/98-reference/21-svelte-reactivity.md  | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md
index 6857c1dba80d..1589aff3ed13 100644
--- a/documentation/docs/98-reference/21-svelte-reactivity.md
+++ b/documentation/docs/98-reference/21-svelte-reactivity.md
@@ -4,22 +4,4 @@ title: svelte/reactivity
 
 Svelte provides reactive versions of various built-ins like `SvelteMap`, `SvelteSet` and `SvelteURL`. These can be imported from `svelte/reactivity` and used just like their native counterparts.
 
-```svelte
-<script>
-	import { SvelteURL } from 'svelte/reactivity';
-
-	const url = new SvelteURL('https://example.com/path');
-</script>
-
-<!-- changes to these... -->
-<input bind:value={url.protocol} />
-<input bind:value={url.hostname} />
-<input bind:value={url.pathname} />
-
-<hr />
-
-<!-- will update `href` and vice versa -->
-<input bind:value={url.href} />
-```
-
 > MODULE: svelte/reactivity

From 759ab26125c7c1b95cae5801cad1d2604601eca4 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 15:31:00 -0400
Subject: [PATCH 6/8] tweak

---
 documentation/docs/98-reference/21-svelte-reactivity.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md
index 1589aff3ed13..d17707f1c682 100644
--- a/documentation/docs/98-reference/21-svelte-reactivity.md
+++ b/documentation/docs/98-reference/21-svelte-reactivity.md
@@ -2,6 +2,6 @@
 title: svelte/reactivity
 ---
 
-Svelte provides reactive versions of various built-ins like `SvelteMap`, `SvelteSet` and `SvelteURL`. These can be imported from `svelte/reactivity` and used just like their native counterparts.
+Svelte provides reactive versions of various built-ins like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used just like their native counterparts, as well as a handful of addtional utilities for handling reactivity.
 
 > MODULE: svelte/reactivity

From 1c476f50fa87c2d8ce00296c6a1fcfa452b06d84 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Thu, 10 Apr 2025 16:26:56 -0400
Subject: [PATCH 7/8] typo

---
 documentation/docs/98-reference/21-svelte-reactivity.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md
index d17707f1c682..8070331f481b 100644
--- a/documentation/docs/98-reference/21-svelte-reactivity.md
+++ b/documentation/docs/98-reference/21-svelte-reactivity.md
@@ -2,6 +2,6 @@
 title: svelte/reactivity
 ---
 
-Svelte provides reactive versions of various built-ins like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used just like their native counterparts, as well as a handful of addtional utilities for handling reactivity.
+Svelte provides reactive versions of various built-ins like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used just like their native counterparts, as well as a handful of additional utilities for handling reactivity.
 
 > MODULE: svelte/reactivity

From a52c869ed52b4716ee189cc4b99ec47b8aee09b6 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Mon, 14 Apr 2025 09:09:46 -0400
Subject: [PATCH 8/8] Apply suggestions from code review

Co-authored-by: bytecodemanipulator <bytecodemanipulator@gmail.com>
---
 packages/svelte/src/reactivity/url.js | 2 +-
 packages/svelte/types/index.d.ts      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/svelte/src/reactivity/url.js b/packages/svelte/src/reactivity/url.js
index cb63827e55fd..879006f057dc 100644
--- a/packages/svelte/src/reactivity/url.js
+++ b/packages/svelte/src/reactivity/url.js
@@ -15,7 +15,7 @@ export function get_current_url() {
  * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
  * will cause it to be re-evaluated as necessary when the URL changes.
  *
- * The `searchParams` property is an instance of [SvelteURLSearchParams](http://localhost:5173/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+ * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
  *
  * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
  *
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index c256483037d6..eec4cc0f8705 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -2032,7 +2032,7 @@ declare module 'svelte/reactivity' {
 	 * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived)
 	 * will cause it to be re-evaluated as necessary when the URL changes.
 	 *
-	 * The `searchParams` property is an instance of [SvelteURLSearchParams](http://localhost:5173/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
+	 * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams).
 	 *
 	 * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a):
 	 *