chore: document @html and <img src> hydration change (#12373)

* chore: document `@html` and `<img src>` hydration change

Also add a test for it

closes #12333

* add a test

* Update sites/svelte-5-preview/src/routes/docs/content/03-appendix/02-breaking-changes.md

Co-authored-by: Rich Harris <[email protected]>

* lint

* update example and wording

* update test

* since it turns out we already had a test, we can delete the new one

* fix test

---------

Co-authored-by: Rich Harris <[email protected]>

Author: dummdidumm

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

@@ -23,7 +23,7 @@ function check_hash(element, server_hash, value) {
 	const loc = element.__svelte_meta?.loc;
 	if (loc) {
 		location = `near ${loc.file}:${loc.line}:${loc.column}`;
-	} else if (dev_current_component_function.filename) {
+	} else if (dev_current_component_function?.filename) {
 		location = `in ${dev_current_component_function.filename}`;
 	}
 
@@ -59,6 +59,8 @@ export function html(node, get_value, svg, mathml) {
 
 		effect = branch(() => {
 			if (hydrating) {
+				// We're deliberately not trying to repair mismatches between server and client,
+				// as it's costly and error-prone (and it's an edge case to have a mismatch anyway)
 				var hash = /** @type {Comment} */ (hydrate_node).data;
 				var next = hydrate_next();
 				var last = next;

packages/svelte/tests/helpers.js

@@ -69,7 +69,7 @@ export async function compile_directory(
 
 	fs.rmSync(output_dir, { recursive: true, force: true });
 
-	for (const file of glob('**', { cwd, filesOnly: true })) {
+	for (let file of glob('**', { cwd, filesOnly: true })) {
 		if (file.startsWith('_')) continue;
 
 		let text = fs.readFileSync(`${cwd}/${file}`, 'utf-8').replace(/\r\n/g, '\n');
@@ -101,7 +101,17 @@ export async function compile_directory(
 
 				write(out, result);
 			}
-		} else if (file.endsWith('.svelte')) {
+		} else if (
+			file.endsWith('.svelte') &&
+			// Make it possible to compile separate versions for client and server to simulate
+			// cases where `{browser ? 'foo' : 'bar'}` is turning into `{'foo'}` on the server
+			// and `{bar}` on the client, assuming we have sophisticated enough treeshaking
+			// in the future to make this a thing.
+			(!file.endsWith('.server.svelte') || generate === 'server') &&
+			(!file.endsWith('.client.svelte') || generate === 'client')
+		) {
+			file = file.replace(/\.client\.svelte$/, '.svelte').replace(/\.server\.svelte$/, '.svelte');
+
 			if (preprocessor?.preprocess) {
 				const preprocessed = await preprocess(
 					text,

packages/svelte/tests/hydration/samples/html-tag-hydration-2/_config.js

@@ -0,0 +1,17 @@
+import { test } from '../../test';
+
+export default test({
+	server_props: {
+		src: 'server.jpg'
+	},
+	props: {
+		src: 'client.jpg'
+	},
+	test(assert, target) {
+		// We deliberately don't slow down hydration just for supporting this edge case mismatch.
+		assert.htmlEqual(target.innerHTML, '<img src="server.jpg" alt="">');
+	},
+	errors: [
+		'The `src` attribute on `...<img src="server.jpg" alt="">` changed its value between server and client renders. The client value, `client.jpg`, will be ignored in favour of the server value'
+	]
+});

packages/svelte/tests/hydration/samples/html-tag-hydration-2/main.svelte

@@ -0,0 +1,5 @@
+<script>
+	let { src } = $props();
+</script>
+
+<img {src} alt="" />

packages/svelte/tests/hydration/samples/img-src-mismatch/_config.js

@@ -0,0 +1,15 @@
+import { test } from '../../test';
+
+export default test({
+	test(assert, target) {
+		// This test case guards against a potential future bug where we could optimize html tags away for static content:
+		// Even if the {@html } block seems static, it should be preserved as such, because it could be dynamic originally
+		// (like {@html browser ? 'foo' : 'bar'} which is then different between client and server.
+		// Also see https://github.com/sveltejs/svelte/issues/8683 where this happened for Svelte 4.
+		assert.htmlEqual(target.innerHTML, 'Server');
+	},
+
+	errors: [
+		'The value of an `{@html ...}` block changed between server and client renders. The client value will be ignored in favour of the server value'
+	]
+});

packages/svelte/tests/hydration/samples/img-src-mismatch/main.svelte

@@ -0,0 +1 @@
+{@html '<p>Client</p> <span>has more nodes so if we would walk this because we think it is static we would get an error</span>'}

packages/svelte/tests/hydration/samples/raw-mismatch-static/_config.js

@@ -0,0 +1 @@
+{@html 'Server'}

packages/svelte/tests/hydration/samples/raw-mismatch-static/main.client.svelte

@@ -1,10 +1,21 @@
 import { test } from '../../test';
 
 export default test({
-	// Even if the {@html } block seems static, it should be preserved as such, because it could be dynamic originally
-	// (like {@html browser ? 'foo' : 'bar'} which is then different between client and server.
-	// Question is whether that's actually something someone would do in practise, and why, so it's probably better to not
-	// slow down hydration just for supporting this edge case - so far we've said no. If someone really needs this we could
-	// add something like {@html dynamic ...}
-	skip: true
+	server_props: {
+		html: 'Server'
+	},
+
+	props: {
+		html: 'Client'
+	},
+
+	test(assert, target) {
+		// We deliberately don't slow down hydration just for supporting this edge case mismatch.
+		// If someone really needs this and workarounds are insufficient we could add something like {@html dynamic ...}
+		assert.htmlEqual(target.innerHTML, 'Server');
+	},
+
+	errors: [
+		'The value of an `{@html ...}` block changed between server and client renders. The client value will be ignored in favour of the server value'
+	]
 });