Merge e83cc688c3 into 5895c637b0

documentation/docs/02-runes/07-$inspect.md

@@ -62,3 +62,11 @@ This rune, added in 5.14, causes the surrounding function to be _traced_ in deve
 ```
 
 `$inspect.trace` takes an optional first argument which will be used as the label.
+
+## $inspect vs {@debug ...}
+
+Svelte has both `$inspect` and [`{@debug ...}`](@debug) because they debug from different places and do different jobs. `{@debug}` is not deprecated.
+
+Use `$inspect` from `<script>` when you want a development-only log that re-runs as reactive state changes, including nested updates inside objects and arrays. It can take expressions, and `.with()` / `$inspect.trace()` cover custom callbacks and effect tracing. In production it becomes a noop.
+
+Use `{@debug}` when you need to debug from the template itself, or when you want the browser debugger to pause. It only accepts variable names (not expressions like `user.firstname`), and it compiles to `console.log` plus a `debugger` statement.

documentation/docs/03-template-syntax/11-@debug.md

@@ -33,3 +33,11 @@ The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the
 
 The `{@debug}` tag without any arguments will insert a `debugger` statement that gets triggered when _any_ state changes, as opposed to the specified variables.
 
+
+## {@debug ...} vs $inspect
+
+`{@debug}` and [`$inspect`]($inspect) both exist because one is a template debugger and the other is a `<script>` rune. `{@debug}` is not deprecated.
+
+Reach for `{@debug}` when the value you care about is used in markup and you want DevTools to pause (`debugger`) when it changes. It only accepts identifiers, not expressions.
+
+Reach for `$inspect` when you are already in `<script>`, need to log an expression, or want deep reactive tracking that is stripped from production builds. If you only need a breakpoint from script, `$inspect(value).with(() => { debugger; })` is the rune equivalent of `{@debug}`.