feat: custom devtools formatters

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

@@ -4,6 +4,10 @@
 
 > `%binding%` (%location%) is binding to a non-reactive property
 
+## enable_custom_formatters
+
+> We recommend enabling custom formatters for better results when logging `$state` objects — in your devtools, click the gear icon and check the 'Custom formatters' box
+
 ## event_handler_invalid
 
 > %handler% should be a function. Did you mean to %suggestion%?

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

@@ -0,0 +1,46 @@
+import { STATE_SYMBOL } from '../constants.js';
+import { VERSION } from '../../../version.js';
+import { snapshot } from '../../shared/clone.js';
+import * as w from '../warnings.js';
+
+export function install_custom_formatter() {
+	// Custom formatters are 'supported' in Firefox, but they're worse than useless.
+	// They're not supported in Firefox. We can maybe tweak this over time
+	var is_chrome = typeof navigator !== 'undefined' && navigator.userAgent.includes('Chrome');
+	var custom_formatters_enabled = false;
+
+	if (is_chrome) {
+		// @ts-expect-error
+		(window.devtoolsFormatters ??= []).push({
+			/**
+			 * @param {any} object
+			 * @param {any} config
+			 */
+			header(object, config) {
+				custom_formatters_enabled = true;
+
+				if (STATE_SYMBOL in object) {
+					return [
+						'div',
+						{},
+						['span', { style: 'font-weight: bold' }, '$state'],
+						['object', { object: snapshot(object), config }]
+					];
+				}
+
+				return null;
+			},
+
+			hasBody: () => false
+		});
+	}
+
+	// the arguments need to include an object, so that we discover
+	// whether custom formatters are enabled
+	// eslint-disable-next-line no-console
+	console.log(`Running Svelte in development mode`, { version: VERSION });
+
+	if (is_chrome && !custom_formatters_enabled) {
+		w.enable_custom_formatters();
+	}
+}

packages/svelte/src/internal/client/index.js

@@ -1,3 +1,6 @@
+import { DEV } from 'esm-env';
+import { install_custom_formatter } from './dev/log.js';
+
 export { FILENAME, HMR } from '../../constants.js';
 export { add_locations } from './dev/elements.js';
 export { hmr } from './dev/hmr.js';
@@ -164,3 +167,7 @@ export {
 	validate_void_dynamic_element
 } from '../shared/validate.js';
 export { strict_equals, equals } from './dev/equality.js';
+
+if (DEV) {
+	install_custom_formatter();
+}

packages/svelte/src/internal/client/warnings.js

@@ -19,6 +19,18 @@ export function binding_property_non_reactive(binding, location) {
 	}
 }
 
+/**
+ * We recommend enabling custom formatters for better results when logging `$state` objects — in your devtools, click the gear icon and check the 'Custom formatters' box
+ */
+export function enable_custom_formatters() {
+	if (DEV) {
+		console.warn(`%c[svelte] enable_custom_formatters\n%cWe recommend enabling custom formatters for better results when logging \`$state\` objects — in your devtools, click the gear icon and check the 'Custom formatters' box`, bold, normal);
+	} else {
+		// TODO print a link to the documentation
+		console.warn("enable_custom_formatters");
+	}
+}
+
 /**
  * %handler% should be a function. Did you mean to %suggestion%?
  * @param {string} handler