breaking: use structuredClone inside $state.snapshot (#12413)

* move cloning logic into new file, use structuredClone, add tests

* changeset

* breaking

* tweak

* use same cloning approach between server and client

* get types mostly working

* fix type error that popped up

* cheeky hack

* we no longer need deep_snapshot

* shallow copy state when freezing

* throw if argument is a state proxy

* docs

* regenerate

Author: Rich-Harris

.changeset/perfect-actors-bake.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+breaking: use structuredClone inside `$state.snapshot`

documentation/docs/03-runes/01-state.md

@@ -91,7 +91,7 @@ State declared with `$state.frozen` cannot be mutated; it can only be _reassigne
 
 This can improve performance with large arrays and objects that you weren't planning to mutate anyway, since it avoids the cost of making them reactive. Note that frozen state can _contain_ reactive state (for example, a frozen array of reactive objects).
 
-> Objects and arrays passed to `$state.frozen` will be shallowly frozen using `Object.freeze()`. If you don't want this, pass in a clone of the object or array instead.
+> Objects and arrays passed to `$state.frozen` will be shallowly frozen using `Object.freeze()`. If you don't want this, pass in a clone of the object or array instead. The argument cannot be an existing state proxy created with `$state(...)`.
 
 ## `$state.snapshot`
 

packages/svelte/messages/client-errors/errors.md

@@ -60,6 +60,10 @@
 
 > The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files
 
+## state_frozen_invalid_argument
+
+> The argument to `$state.frozen(...)` cannot be an object created with `$state(...)`. You should create a copy of it first, for example with `$state.snapshot`
+
 ## state_prototype_fixed
 
 > Cannot set prototype of `$state` object

packages/svelte/src/ambient.d.ts

@@ -32,6 +32,75 @@ declare function $state<T>(initial: T): T;
 declare function $state<T>(): T | undefined;
 
 declare namespace $state {
+	type Primitive = string | number | boolean | null | undefined;
+
+	type TypedArray =
+		| Int8Array
+		| Uint8Array
+		| Uint8ClampedArray
+		| Int16Array
+		| Uint16Array
+		| Int32Array
+		| Uint32Array
+		| Float32Array
+		| Float64Array
+		| BigInt64Array
+		| BigUint64Array;
+
+	/** The things that `structuredClone` can handle — https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm */
+	export type Cloneable =
+		| ArrayBuffer
+		| DataView
+		| Date
+		| Error
+		| Map<any, any>
+		| RegExp
+		| Set<any>
+		| TypedArray
+		// web APIs
+		| Blob
+		| CryptoKey
+		| DOMException
+		| DOMMatrix
+		| DOMMatrixReadOnly
+		| DOMPoint
+		| DOMPointReadOnly
+		| DOMQuad
+		| DOMRect
+		| DOMRectReadOnly
+		| File
+		| FileList
+		| FileSystemDirectoryHandle
+		| FileSystemFileHandle
+		| FileSystemHandle
+		| ImageBitmap
+		| ImageData
+		| RTCCertificate
+		| VideoFrame;
+
+	/** Turn `SvelteDate`, `SvelteMap` and `SvelteSet` into their non-reactive counterparts. (`URL` is uncloneable.) */
+	type NonReactive<T> = T extends Date
+		? Date
+		: T extends Map<infer K, infer V>
+			? Map<K, V>
+			: T extends Set<infer K>
+				? Set<K>
+				: T;
+
+	type Snapshot<T> = T extends Primitive
+		? T
+		: T extends Cloneable
+			? NonReactive<T>
+			: T extends { toJSON(): infer R }
+				? R
+				: T extends Array<infer U>
+					? Array<Snapshot<U>>
+					: T extends object
+						? T extends { [key: string]: any }
+							? { [K in keyof T]: Snapshot<T[K]> }
+							: never
+						: never;
+
 	/**
 	 * Declares reactive read-only state that is shallowly immutable.
 	 *
@@ -75,7 +144,7 @@ declare namespace $state {
 	 *
 	 * @param state The value to snapshot
 	 */
-	export function snapshot<T>(state: T): T;
+	export function snapshot<T>(state: T): Snapshot<T>;
 
 	/**
 	 * Compare two values, one or both of which is a reactive `$state(...)` proxy.

packages/svelte/src/compiler/phases/3-transform/server/transform-server.js

@@ -423,7 +423,10 @@ const global_visitors = {
 		}
 
 		if (rune === '$state.snapshot') {
-			return /** @type {import('estree').Expression} */ (context.visit(node.arguments[0]));
+			return b.call(
+				'$.snapshot',
+				/** @type {import('estree').Expression} */ (context.visit(node.arguments[0]))
+			);
 		}
 
 		if (rune === '$state.is') {

packages/svelte/src/index-client.js

@@ -1,5 +1,5 @@
 import { current_component_context, flush_sync, untrack } from './internal/client/runtime.js';
-import { is_array } from './internal/client/utils.js';
+import { is_array } from './internal/shared/utils.js';
 import { user_effect } from './internal/client/index.js';
 import * as e from './internal/client/errors.js';
 import { lifecycle_outside_component } from './internal/shared/errors.js';

packages/svelte/src/internal/client/dev/inspect.js

@@ -1,6 +1,5 @@
-import { snapshot } from '../proxy.js';
+import { snapshot } from '../../shared/clone.js';
 import { inspect_effect, validate_effect } from '../reactivity/effects.js';
-import { array_prototype, get_prototype_of, object_prototype } from '../utils.js';
 
 /**
  * @param {() => any[]} get_value
@@ -13,47 +12,7 @@ export function inspect(get_value, inspector = console.log) {
 	let initial = true;
 
 	inspect_effect(() => {
-		inspector(initial ? 'init' : 'update', ...deep_snapshot(get_value()));
+		inspector(initial ? 'init' : 'update', ...snapshot(get_value()));
 		initial = false;
 	});
 }
-
-/**
- * Like `snapshot`, but recursively traverses into normal arrays/objects to find potential states in them.
- * @param {any} value
- * @param {Map<any, any>} visited
- * @returns {any}
- */
-function deep_snapshot(value, visited = new Map()) {
-	if (typeof value === 'object' && value !== null && !visited.has(value)) {
-		const unstated = snapshot(value);
-
-		if (unstated !== value) {
-			visited.set(value, unstated);
-			return unstated;
-		}
-
-		const prototype = get_prototype_of(value);
-
-		// Only deeply snapshot plain objects and arrays
-		if (prototype === object_prototype || prototype === array_prototype) {
-			let contains_unstated = false;
-			/** @type {any} */
-			const nested_unstated = Array.isArray(value) ? [] : {};
-
-			for (let key in value) {
-				const result = deep_snapshot(value[key], visited);
-				nested_unstated[key] = result;
-				if (result !== value[key]) {
-					contains_unstated = true;
-				}
-			}
-
-			visited.set(value, contains_unstated ? nested_unstated : value);
-		} else {
-			visited.set(value, value);
-		}
-	}
-
-	return visited.get(value) ?? value;
-}

packages/svelte/src/internal/client/dev/ownership.js

@@ -4,7 +4,7 @@
 import { STATE_SYMBOL } from '../constants.js';
 import { render_effect, user_pre_effect } from '../reactivity/effects.js';
 import { dev_current_component_function } from '../runtime.js';
-import { get_prototype_of } from '../utils.js';
+import { get_prototype_of } from '../../shared/utils.js';
 import * as w from '../warnings.js';
 
 /** @type {Record<string, Array<{ start: Location, end: Location, component: Function }>>} */

packages/svelte/src/internal/client/dom/blocks/each.js

@@ -28,7 +28,7 @@ import {
 	resume_effect
 } from '../../reactivity/effects.js';
 import { source, mutable_source, set } from '../../reactivity/sources.js';
-import { is_array, is_frozen } from '../../utils.js';
+import { is_array, is_frozen } from '../../../shared/utils.js';
 import { INERT, STATE_FROZEN_SYMBOL, STATE_SYMBOL } from '../../constants.js';
 import { queue_micro_task } from '../task.js';
 import { current_effect } from '../../runtime.js';

packages/svelte/src/internal/client/dom/css.js

@@ -20,7 +20,7 @@ export function append_styles(anchor, css) {
 
 		var target = /** @type {ShadowRoot} */ (root).host
 			? /** @type {ShadowRoot} */ (root)
-			: /** @type {Document} */ (root).head;
+			: /** @type {Document} */ (root).head ?? /** @type {Document} */ (root.ownerDocument).head;
 
 		if (!target.querySelector('#' + css.hash)) {
 			const style = document.createElement('style');