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

[dummdidumm]

Also add a test for it

closes #12333

Dev-time check for @html will be part of #12362

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• Prefix your PR title with feat:, fix:, chore:, or docs:.
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests and linting

• Run the tests with pnpm test and lint the project with pnpm lint

[changeset-bot]

⚠️ No Changeset found

Latest commit: a0f1fb4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Rich-Harris]

another way we could tackle this, which is arguably a better practice since it scales to an arbitrary number of variables:

Suggested change

	onMount(async () => {
	// force update
	raw_html = '';
	src = '';
	await tick();
	// set client values
	raw_html = '<h1>Client</h1>';
	src = '/client.jpg';
	});
	</script>
	{@html raw_html}
	<img {src} />
	let mounted = $state(false);
	$effect(() => {
	// force `markup` and `src` to be re-evaluated
	mounted = true;
	});
	</script>
	{@html (mounted, markup)}
	<img src={(mounted, src)} />

[dummdidumm]

This doesn't work for @html, because it checks against the previous value and does nothing if it's the same

[Rich-Harris]

Hmm. I realised it doesn't really make any sense anyway — if you're dealing with local state, you should just do this:

<script>
	import { onMount, tick } from 'svelte';

	let markup = $state('<h1>Server</h1>');
	let src = $state('/server.jpg');

	onMount(() => {
		markup = '<h1>Client</h1>';
		src = '/client.jpg';
	});
</script>

So this only makes sense if you're dealing with props, in which case you don't know what values to set to. Something like this would make more sense:

<script>
	let { markup, src } = $props();

	if (typeof window !== 'undefined') {
		// stash the values...
		const initial = { markup, src };

		// unset them...
		markup = src = undefined;

		$effect(() => {
			// ...and reset after we've mounted
			markup = initial.markup;
			src = initial.src;
		});
	}
</script>

{@html markup}
<img {src} />

[Rich-Harris]

this is kind of blocked on #12362, so I may rustle up a fix real quick

[Rich-Harris]

actually I can't right now, will come back to it later if @paoloricciuti doesn't beat me to it

[paoloricciuti]

actually I can't right now, will come back to it later if @paoloricciuti doesn't beat me to it

Ugh didn't realized this was blocked...I'll try to do something now but please don't worry about me if you can squeeze the fix.

[Rich-Harris]

all good — we could have just merged without mentioning the warning, but it seems better to consolidate

[paoloricciuti]

all good — we could have just merged without mentioning the warning, but it seems better to consolidate

Btw I shoot my shot with #12396 I hope I did everything correctly

[Rich-Harris]

I saw, thanks — I gave you bad advice when I said 'On the server it means context.state.options.dev', we should really be using DEV in both environments to guarantee consistency. Making a couple of edits and will merge

[paoloricciuti]

I saw, thanks — I gave you bad advice when I said 'On the server it means context.state.options.dev', we should really be using DEV in both environments to guarantee consistency. Making a couple of edits and will merge

Uh gotcha, but also I don't think we can force DEV in tests right?

[Rich-Harris]

IIUC it's the opposite — DEV is always true in tests