breaking: replace $state.frozen with $state.raw (#12808)

* breaking: replace `$state.frozen` with `$state.raw`

* regenerate

* rename

* rename

* rename

* rename

* rename

* rename

* rename

* rename

* rename

* typo

* add compiler error for existing `$state.frozen` uses

* regenerate

* rename

* tidy up

* move proxy logic into props function

Author: Rich-Harris

.changeset/four-yaks-boil.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+breaking: replace `$state.frozen` with `$state.raw`

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

@@ -64,10 +64,6 @@
 
 > 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

@@ -102,12 +102,13 @@ declare namespace $state {
 						: never;
 
 	/**
-	 * Declares reactive read-only state that is shallowly immutable.
+	 * Declares state that is _not_ made deeply reactive — instead of mutating it,
+	 * you must reassign it.
 	 *
 	 * Example:
 	 * ```ts
 	 * <script>
-	 *   let items = $state.frozen([0]);
+	 *   let items = $state.raw([0]);
 	 *
 	 *   const addItem = () => {
 	 *     items = [...items, items.length];
@@ -123,8 +124,8 @@ declare namespace $state {
 	 *
 	 * @param initial The initial value
 	 */
-	export function frozen<T>(initial: T): Readonly<T>;
-	export function frozen<T>(): Readonly<T> | undefined;
+	export function raw<T>(initial: T): T;
+	export function raw<T>(): T | undefined;
 	/**
 	 * To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`:
 	 *

packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js

@@ -34,7 +34,7 @@ export function BindDirective(node, context) {
 			node.name !== 'this' && // bind:this also works for regular variables
 			(!binding ||
 				(binding.kind !== 'state' &&
-					binding.kind !== 'frozen_state' &&
+					binding.kind !== 'raw_state' &&
 					binding.kind !== 'prop' &&
 					binding.kind !== 'bindable_prop' &&
 					binding.kind !== 'each' &&

packages/svelte/src/compiler/phases/2-analyze/visitors/CallExpression.js

@@ -73,7 +73,7 @@ export function CallExpression(node, context) {
 			break;
 
 		case '$state':
-		case '$state.frozen':
+		case '$state.raw':
 		case '$derived':
 		case '$derived.by':
 			if (

packages/svelte/src/compiler/phases/2-analyze/visitors/ExportNamedDeclaration.js

@@ -32,7 +32,7 @@ export function ExportNamedDeclaration(node, context) {
 					e.derived_invalid_export(node);
 				}
 
-				if ((binding.kind === 'state' || binding.kind === 'frozen_state') && binding.reassigned) {
+				if ((binding.kind === 'state' || binding.kind === 'raw_state') && binding.reassigned) {
 					e.state_invalid_export(node);
 				}
 			}

packages/svelte/src/compiler/phases/2-analyze/visitors/ExportSpecifier.js

@@ -26,7 +26,7 @@ export function ExportSpecifier(node, context) {
 			if (
 				binding !== null &&
 				(binding.kind === 'state' ||
-					binding.kind === 'frozen_state' ||
+					binding.kind === 'raw_state' ||
 					(binding.kind === 'normal' &&
 						(binding.declaration_kind === 'let' || binding.declaration_kind === 'var')))
 			) {
@@ -60,7 +60,7 @@ function validate_export(node, scope, name) {
 		e.derived_invalid_export(node);
 	}
 
-	if ((binding.kind === 'state' || binding.kind === 'frozen_state') && binding.reassigned) {
+	if ((binding.kind === 'state' || binding.kind === 'raw_state') && binding.reassigned) {
 		e.state_invalid_export(node);
 	}
 }

packages/svelte/src/compiler/phases/2-analyze/visitors/Identifier.js

@@ -1,7 +1,7 @@
 /** @import { Expression, Identifier } from 'estree' */
 /** @import { Context } from '../types' */
 import is_reference from 'is-reference';
-import { should_proxy_or_freeze } from '../../3-transform/client/utils.js';
+import { should_proxy } from '../../3-transform/client/utils.js';
 import * as e from '../../../errors.js';
 import * as w from '../../../warnings.js';
 import { is_rune } from '../../../../utils.js';
@@ -53,6 +53,10 @@ export function Identifier(node, context) {
 						e.rune_renamed(parent, '$effect.active', '$effect.tracking');
 					}
 
+					if (name === '$state.frozen') {
+						e.rune_renamed(parent, '$state.frozen', '$state.raw');
+					}
+
 					e.rune_invalid_name(parent, name);
 				}
 			}
@@ -132,8 +136,8 @@ export function Identifier(node, context) {
 					(binding.initial?.type === 'CallExpression' &&
 						binding.initial.arguments.length === 1 &&
 						binding.initial.arguments[0].type !== 'SpreadElement' &&
-						!should_proxy_or_freeze(binding.initial.arguments[0], context.state.scope)))) ||
-				binding.kind === 'frozen_state' ||
+						!should_proxy(binding.initial.arguments[0], context.state.scope)))) ||
+				binding.kind === 'raw_state' ||
 				binding.kind === 'derived') &&
 			// We're only concerned with reads here
 			(parent.type !== 'AssignmentExpression' || parent.left !== node) &&

packages/svelte/src/compiler/phases/2-analyze/visitors/VariableDeclarator.js

@@ -21,7 +21,7 @@ export function VariableDeclarator(node, context) {
 		// TODO feels like this should happen during scope creation?
 		if (
 			rune === '$state' ||
-			rune === '$state.frozen' ||
+			rune === '$state.raw' ||
 			rune === '$derived' ||
 			rune === '$derived.by' ||
 			rune === '$props'
@@ -32,8 +32,8 @@ export function VariableDeclarator(node, context) {
 				binding.kind =
 					rune === '$state'
 						? 'state'
-						: rune === '$state.frozen'
-							? 'frozen_state'
+						: rune === '$state.raw'
+							? 'raw_state'
 							: rune === '$derived' || rune === '$derived.by'
 								? 'derived'
 								: path.is_rest

packages/svelte/src/compiler/phases/2-analyze/visitors/shared/utils.js

@@ -78,7 +78,7 @@ export function validate_no_const_assignment(node, argument, scope, is_binding)
 			// 	// This takes advantage of the fact that we don't assign initial for let directives and then/catch variables.
 			// 	// If we start doing that, we need another property on the binding to differentiate, or give up on the more precise error message.
 			// 	binding.kind !== 'state' &&
-			// 		binding.kind !== 'frozen_state' &&
+			// 		binding.kind !== 'raw_state' &&
 			// 		(binding.kind !== 'normal' || !binding.initial)
 			// );