From bd29b9ef2ba2a140e7e7d8835177e5ad34c6bf18 Mon Sep 17 00:00:00 2001
From: Wesley <2011150255@email.szu.edu.cn>
Date: Thu, 30 Apr 2026 00:34:09 +0800
Subject: [PATCH] docs: document $state.snapshot toJSON behavior (#18154)

### Before submitting the PR, please make sure you do the following

- [x] It's really useful if your PR references an issue where it is
discussed ahead of time. In many cases, features are absent for a
reason. For large changes, please create an RFC:
https://github.com/sveltejs/rfcs
- [x] Prefix your PR title with `feat:`, `fix:`, `chore:`, or `docs:`.
- [x] This message body should clearly illustrate what problems it
solves.
- [ ] Ideally, include a test that fails without this PR but passes with
it.
- [ ] If this PR changes code within `packages/svelte/src`, add a
changeset (`npx changeset`).

### Tests and linting

- [ ] Run the tests with `pnpm test` and lint the project with `pnpm
lint`

`$state.snapshot` already clones the value returned from `toJSON`, and
its `Snapshot<T>` type reflects that return type. The `$state.snapshot`
docs now call out that behavior explicitly, including the generated
ambient types shown by editors.

Test plan: `pnpm check`; `pnpm lint`.

Fixes #18129

Co-authored-by: sakaenyeniceri5 <sakaenyeniceri5@users.noreply.github.com>
---
 documentation/docs/02-runes/02-$state.md | 2 ++
 packages/svelte/src/ambient.d.ts         | 2 ++
 packages/svelte/types/index.d.ts         | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/documentation/docs/02-runes/02-$state.md b/documentation/docs/02-runes/02-$state.md
index d763b6578f..b90c71366a 100644
--- a/documentation/docs/02-runes/02-$state.md
+++ b/documentation/docs/02-runes/02-$state.md
@@ -167,6 +167,8 @@ To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snaps
 
 This is handy when you want to pass some state to an external library or API that doesn't expect a proxy, such as `structuredClone`.
 
+If a value has a `toJSON` method, the snapshot will clone the value returned from `toJSON` instead of the original object.
+
 ## `$state.eager`
 
 When state changes, it may not be reflected in the UI immediately if it is used by an `await` expression, because [updates are synchronized](await-expressions#Synchronized-updates).
diff --git a/packages/svelte/src/ambient.d.ts b/packages/svelte/src/ambient.d.ts
index 159a568477..bbbc86c997 100644
--- a/packages/svelte/src/ambient.d.ts
+++ b/packages/svelte/src/ambient.d.ts
@@ -147,6 +147,8 @@ declare namespace $state {
 	 * </script>
 	 * ```
 	 *
+	 * If `state` has a `toJSON` method, the snapshot will clone the value returned from `toJSON` instead of the original object.
+	 *
 	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.snapshot Documentation}
 	 *
 	 * @param state The value to snapshot
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index 019baf45dd..3f71d44177 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -3345,6 +3345,8 @@ declare namespace $state {
 	 * </script>
 	 * ```
 	 *
+	 * If `state` has a `toJSON` method, the snapshot will clone the value returned from `toJSON` instead of the original object.
+	 *
 	 * @see {@link https://svelte.dev/docs/svelte/$state#$state.snapshot Documentation}
 	 *
 	 * @param state The value to snapshot