add test + some docs

Author: trueadm

packages/svelte/src/ambient.d.ts

@@ -372,6 +372,21 @@ declare function $inspect<T extends any[]>(
 ): { with: (fn: (type: 'init' | 'update', ...values: T) => void) => void };
 
 declare namespace $inspect {
+	/**
+	 * Traces the reactive graph of the tracking reactive context. Must be placed within a block statement.
+	 * Example:
+	 *
+	 * ```svelte
+	 * <script>
+	 *   let count = $state(0);
+	 *
+	 *   $effect(() => {
+	 *     $inspect.trace('my effect');
+	 *
+	 *     count;
+	 *   });
+	 * </script>
+	 */
 	export function trace(name: string): void;
 }
 

packages/svelte/src/compiler/errors.js

@@ -470,30 +470,30 @@ export function store_invalid_subscription_module(node) {
 }
 
 /**
- * `$track` requires a string argument for the trace name
+ * `$track` must only be used once within the same block statement
  * @param {null | number | NodeLike} node
  * @returns {never}
  */
-export function trace_rune_invalid_argument(node) {
-	e(node, "trace_rune_invalid_argument", "`$track` requires a string argument for the trace name");
+export function trace_rune_duplicate(node) {
+	e(node, "trace_rune_duplicate", "`$track` must only be used once within the same block statement");
 }
 
 /**
- * `$track` must be placed directly inside a block statement
+ * `$track` requires a string argument for the trace name
  * @param {null | number | NodeLike} node
  * @returns {never}
  */
-export function trace_rune_invalid_location(node) {
-	e(node, "trace_rune_invalid_location", "`$track` must be placed directly inside a block statement");
+export function trace_rune_invalid_argument(node) {
+	e(node, "trace_rune_invalid_argument", "`$track` requires a string argument for the trace name");
 }
 
 /**
- * `$track` must only be used once within the same block statement
+ * `$track` must be placed directly inside a block statement
  * @param {null | number | NodeLike} node
  * @returns {never}
  */
-export function trace_rune_duplicate(node) {
-	e(node, "trace_rune_duplicate", "`$track` must only be used once within the same block statement");
+export function trace_rune_invalid_location(node) {
+	e(node, "trace_rune_invalid_location", "`$track` must be placed directly inside a block statement");
 }
 
 /**

packages/svelte/tests/runtime-runes/samples/inspect-console-trace/_config.js

@@ -0,0 +1,19 @@
+import { test } from '../../test';
+
+export default test({
+	compileOptions: {
+		dev: true
+	},
+
+	async test({ assert, target, logs }) {
+		assert.deepEqual(logs, []);
+
+		const [b1, b2] = target.querySelectorAll('button');
+		b1.click();
+		b2.click();
+		await Promise.resolve();
+
+		assert.ok(logs[0].stack.startsWith('Error:') && logs[0].stack.includes('HTMLButtonElement.'));
+		assert.deepEqual(logs[1], 1);
+	}
+});

packages/svelte/tests/runtime-runes/samples/inspect-console-trace/main.svelte

@@ -0,0 +1,11 @@
+<script>
+	let x = $state(0);
+	let y = $state(0);
+
+	$inspect(x).with((type, x) => {
+		if (type === 'update') console.log(new Error(), x);
+	});
+</script>
+
+<button on:click={() => x++}>{x}</button>
+<button on:click={() => y++}>{y}</button>

packages/svelte/tests/runtime-runes/samples/inspect-trace/_config.js

@@ -1,19 +1,41 @@
+import { flushSync } from 'svelte';
 import { test } from '../../test';
 
+/**
+ * @param {any[]} logs
+ */
+function normalise_trace_logs(logs) {
+	let normalised = [];
+	for (let i = 0; i < logs.length; i++) {
+		const log = logs[i];
+
+		if (typeof log === 'string' && log.includes('%c')) {
+			const split = log.split('%c');
+			normalised.push((split[0].length !== 0 ? split[0] : split[1]).trim());
+			i++;
+		} else if (log instanceof Error) {
+			continue;
+		} else {
+			normalised.push(log);
+		}
+	}
+	return normalised;
+}
+
 export default test({
 	compileOptions: {
 		dev: true
 	},
 
-	async test({ assert, target, logs }) {
-		assert.deepEqual(logs, []);
+	test({ assert, target, logs }) {
+		assert.deepEqual(normalise_trace_logs(logs), ['effect', '$derived', 0, '$state', 0]);
+
+		logs.length = 0;
 
-		const [b1, b2] = target.querySelectorAll('button');
-		b1.click();
-		b2.click();
-		await Promise.resolve();
+		const button = target.querySelector('button');
+		button?.click();
+		flushSync();
 
-		assert.ok(logs[0].stack.startsWith('Error:') && logs[0].stack.includes('HTMLButtonElement.'));
-		assert.deepEqual(logs[1], 1);
+		assert.deepEqual(normalise_trace_logs(logs), ['effect', '$derived', 2, '$state', 1]);
 	}
 });

packages/svelte/tests/runtime-runes/samples/inspect-trace/main.svelte

@@ -1,11 +1,12 @@
 <script>
-	let x = $state(0);
-	let y = $state(0);
+	let count = $state(0);
+	let double = $derived(count * 2);
 
-	$inspect(x).with((type, x) => {
-		if (type === 'update') console.log(new Error(), x);
-	});
+	$effect(() => {
+		$inspect.trace('effect');
+
+		double;
+	})
 </script>
 
-<button on:click={() => x++}>{x}</button>
-<button on:click={() => y++}>{y}</button>
+<button onclick={() => count++}>{double}</button>

packages/svelte/types/index.d.ts

@@ -2693,6 +2693,21 @@ declare function $inspect<T extends any[]>(
 ): { with: (fn: (type: 'init' | 'update', ...values: T) => void) => void };
 
 declare namespace $inspect {
+	/**
+	 * Traces the reactive graph of the tracking reactive context. Must be placed within a block statement.
+	 * Example:
+	 *
+	 * ```svelte
+	 * <script>
+	 *   let count = $state(0);
+	 *
+	 *   $effect(() => {
+	 *     $inspect.trace('my effect');
+	 *
+	 *     count;
+	 *   });
+	 * </script>
+	 */
 	export function trace(name: string): void;
 }
 

sites/svelte-5-preview/src/lib/autocomplete.js

@@ -119,7 +119,8 @@ const runes = [
 	{ snippet: '$effect.root(() => {\n\t${}\n})' },
 	{ snippet: '$state.snapshot(${})' },
 	{ snippet: '$effect.tracking()' },
-	{ snippet: '$inspect(${});', test: is_statement }
+	{ snippet: '$inspect(${});', test: is_statement },
+	{ snippet: '$inspect.trace(${})' }
 ];
 
 const options = runes.map(({ snippet, test }, i) => ({