From 0481a1dfef290e1ddb7e510f1bbb838e3277e771 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Thu, 29 Aug 2024 16:25:04 +0800
Subject: [PATCH 01/17] 3.5: failSilently for onScopeDispose

---
 src/api/reactivity-advanced.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/api/reactivity-advanced.md b/src/api/reactivity-advanced.md
index 2e63a5aeba..825b2373f5 100644
--- a/src/api/reactivity-advanced.md
+++ b/src/api/reactivity-advanced.md
@@ -336,8 +336,10 @@ Registers a dispose callback on the current active [effect scope](#effectscope).
 
 This method can be used as a non-component-coupled replacement of `onUnmounted` in reusable composition functions, since each Vue component's `setup()` function is also invoked in an effect scope.
 
+A warning will be thrown if this function is called without an active effect scope. In 3.5+, this warning can be suppressed by passing `true` as the second argument.
+
 - **Type**
 
   ```ts
-  function onScopeDispose(fn: () => void): void
+  function onScopeDispose(fn: () => void, failSilently?: boolean): void
   ```

From db3ba8dc88b44cccd86fd7d238ac9799c9f6e0ae Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Thu, 29 Aug 2024 17:02:54 +0800
Subject: [PATCH 02/17] 3.5: reactive props destructure

---
 src/api/sfc-script-setup.md             | 45 ++++++++++++++++++++++---
 src/guide/components/props.md           | 39 +++++++++++++++++++++
 src/guide/typescript/composition-api.md | 17 ++++++++--
 3 files changed, 93 insertions(+), 8 deletions(-)

diff --git a/src/api/sfc-script-setup.md b/src/api/sfc-script-setup.md
index d7ee22d963..fe955a6eaa 100644
--- a/src/api/sfc-script-setup.md
+++ b/src/api/sfc-script-setup.md
@@ -209,12 +209,48 @@ const emit = defineEmits<{
 
   This limitation has been resolved in 3.3. The latest version of Vue supports referencing imported and a limited set of complex types in the type parameter position. However, because the type to runtime conversion is still AST-based, some complex types that require actual type analysis, e.g. conditional types, are not supported. You can use conditional types for the type of a single prop, but not the entire props object.
 
-### Default props values when using type declaration {#default-props-values-when-using-type-declaration}
+### Reactive Props Destructure <sup class="vt-badge" data-text="3.5+" /> {#reactive-props-destructure}
 
-One drawback of the type-only `defineProps` declaration is that it doesn't have a way to provide default values for the props. To resolve this problem, a `withDefaults` compiler macro is also provided:
+In Vue 3.5 and above, variables destructured from the return value of `defineProps` are reactive. Vue's compiler automatically prepends `props.` when code in the same `<script setup>` block accesses variables destructured from `defineProps`:
 
 ```ts
-export interface Props {
+const { foo } = defineProps(['foo'])
+
+watchEffect(() => {
+  // runs only once before 3.5
+  // re-runs when the "foo" prop changes in 3.5+
+  console.log(foo)
+})
+```
+
+The above is compiled to the following equivalent:
+
+```js {5}
+const props = defineProps(['foo'])
+
+watchEffect(() => {
+  // `foo` transformed to `props.foo` by the compiler
+  console.log(props.foo)
+})
+```
+
+In addition, you can use JavaScript's native default value syntax to declare default values for the props. This is particularly useful when using the type-based props declaration:
+
+```ts
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
+```
+
+### Default props values when using type declaration <sup class="vt-badge ts" /> {#default-props-values-when-using-type-declaration}
+
+In 3.5 and above, default values can be naturally declared when using Reactive Props Destructure. But in 3.4 and below, Reactive Props Destructure is not enabled by default. In order to declare props default values with type-based declaration, the `withDefaults` compiler macro is needed:
+
+```ts
+interface Props {
   msg?: string
   labels?: string[]
 }
@@ -228,7 +264,7 @@ const props = withDefaults(defineProps<Props>(), {
 This will be compiled to equivalent runtime props `default` options. In addition, the `withDefaults` helper provides type checks for the default values, and ensures the returned `props` type has the optional flags removed for properties that do have default values declared.
 
 :::info
-Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value.
+Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions when using `withDefaults` to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value. This is **not** necessary when using default values with destructure.
 :::
 
 ## defineModel() <sup class="vt-badge" data-text="3.4+" /> {#definemodel}
@@ -487,7 +523,6 @@ ref<InstanceType<typeof componentWithoutGenerics>>();
 ref<ComponentExposed<typeof genericComponent>>();
 ```
 
-
 ## Restrictions {#restrictions}
 
 - Due to the difference in module execution semantics, code inside `<script setup>` relies on the context of an SFC. When moved into external `.js` or `.ts` files, it may lead to confusion for both developers and tools. Therefore, **`<script setup>`** cannot be used with the `src` attribute.
diff --git a/src/guide/components/props.md b/src/guide/components/props.md
index b550a5abf3..8d6dafc918 100644
--- a/src/guide/components/props.md
+++ b/src/guide/components/props.md
@@ -117,6 +117,45 @@ More details: [Typing Component Props](/guide/typescript/composition-api#typing-
 
 </div>
 
+<div class="composition-api">
+
+## Reactive Props Destructure <sup class="vt-badge" data-text="3.5+" /> \*\* {#reactive-props-destructure}
+
+Vue's reactivity system tracks state usage based on property access. E.g. when you access `props.foo` in a computed getter or a watcher, the `foo` prop gets tracked as a dependency.
+
+So, given the following code:
+
+```js
+const { foo } = defineProps(['foo'])
+
+watchEffect(() => {
+  // runs only once before 3.5
+  // re-runs when the "foo" prop changes in 3.5+
+  console.log(foo)
+})
+```
+
+In version 3.4 and below, `foo` is an actual constant and will never change. In version 3.5 and above, Vue's compiler automatically prepends `props.` when code in the same `<script setup>` block accesses variables destructured from `defineProps`. Therefore the code above becomes equivalent to the following:
+
+```js {5}
+const props = defineProps(['foo'])
+
+watchEffect(() => {
+  // `foo` transformed to `props.foo` by the compiler
+  console.log(props.foo)
+})
+```
+
+In addition, you can use JavaScript's native default value syntax to declare default values for the props. This is particularly useful when using the type-based props declaration:
+
+```ts
+const { foo = 'hello' } = defineProps<{ foo?: string }>()
+```
+
+### Passing Destructured Props into Functions
+
+</div>
+
 ## Prop Passing Details {#prop-passing-details}
 
 ### Prop Name Casing {#prop-name-casing}
diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
index 7093823e80..5797e38c9b 100644
--- a/src/guide/typescript/composition-api.md
+++ b/src/guide/typescript/composition-api.md
@@ -68,10 +68,21 @@ This limitation has been resolved in 3.3. The latest version of Vue supports ref
 
 ### Props Default Values {#props-default-values}
 
-When using type-based declaration, we lose the ability to declare default values for the props. This can be resolved by the `withDefaults` compiler macro:
+When using type-based declaration, we lose the ability to declare default values for the props. This can be resolved by using [Reactive Props Destructure](/guide/components/props#reactive-props-destructure) <sup class="vt-badge" data-text="3.5+" />:
 
 ```ts
-export interface Props {
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const { msg = 'hello', labels = ['one', 'two'] } = defineProps<Props>()
+```
+
+In 3.4 and below, Reactive Props Destructure is not enabled by default. An alternative is to use the `withDefaults` compiler macro:
+
+```ts
+interface Props {
   msg?: string
   labels?: string[]
 }
@@ -85,7 +96,7 @@ const props = withDefaults(defineProps<Props>(), {
 This will be compiled to equivalent runtime props `default` options. In addition, the `withDefaults` helper provides type checks for the default values, and ensures the returned `props` type has the optional flags removed for properties that do have default values declared.
 
 :::info
-Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value.
+Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions when using `withDefaults` to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value. This is **not** necessary when using default values with destructure.
 :::
 
 ### Without `<script setup>` {#without-script-setup}

From ef3eea493d705b22b212ecd5d614e1f42c1007c6 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 14:28:28 +0800
Subject: [PATCH 03/17] 3.5: watcher side effect cleanup + WatchHandle pause /
 resume

---
 src/api/reactivity-core.md       | 114 ++++++++++++++++++++++++++++-
 src/guide/essentials/watchers.md | 122 +++++++++++++++++++++++++++++++
 2 files changed, 232 insertions(+), 4 deletions(-)

diff --git a/src/api/reactivity-core.md b/src/api/reactivity-core.md
index 7fd6cf6d3d..6e5aba7109 100644
--- a/src/api/reactivity-core.md
+++ b/src/api/reactivity-core.md
@@ -238,7 +238,7 @@ Runs a function immediately while reactively tracking its dependencies and re-ru
   function watchEffect(
     effect: (onCleanup: OnCleanup) => void,
     options?: WatchEffectOptions
-  ): StopHandle
+  ): WatchHandle
 
   type OnCleanup = (cleanupFn: () => void) => void
 
@@ -248,7 +248,12 @@ Runs a function immediately while reactively tracking its dependencies and re-ru
     onTrigger?: (event: DebuggerEvent) => void
   }
 
-  type StopHandle = () => void
+  interface WatchHandle {
+    (): void // callable, same as `stop`
+    pause: () => void
+    resume: () => void
+    stop: () => void
+  }
   ```
 
 - **Details**
@@ -295,6 +300,47 @@ Runs a function immediately while reactively tracking its dependencies and re-ru
   stop()
   ```
 
+  Pausing / resuming the watcher: <sup class="vt-badge" data-text="3.5+" />
+
+  ```js
+  const { stop, pause, resume } = watchEffect(() => {})
+
+  // temporarily pause the watcher
+  pause()
+
+  // resume later
+  resume()
+
+  // stop
+  stop()
+  ```
+
+  Side effect cleanup:
+
+  ```js
+  watchEffect(async (onCleanup) => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `cancel` will be called if `id` changes, cancelling
+    // the previous request if it hasn't completed yet
+    onCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
+  Side effect cleanup in 3.5+:
+
+  ```js
+  import { onWatcherCleanup } from 'vue'
+
+  watchEffect(async () => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `cancel` will be called if `id` changes, cancelling
+    // the previous request if it hasn't completed yet
+    onWatcherCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
   Options:
 
   ```js
@@ -333,14 +379,14 @@ Watches one or more reactive data sources and invokes a callback function when t
     source: WatchSource<T>,
     callback: WatchCallback<T>,
     options?: WatchOptions
-  ): StopHandle
+  ): WatchHandle
 
   // watching multiple sources
   function watch<T>(
     sources: WatchSource<T>[],
     callback: WatchCallback<T[]>,
     options?: WatchOptions
-  ): StopHandle
+  ): WatchHandle
 
   type WatchCallback<T> = (
     value: T,
@@ -363,6 +409,13 @@ Watches one or more reactive data sources and invokes a callback function when t
     onTrigger?: (event: DebuggerEvent) => void
     once?: boolean // default: false (3.4+)
   }
+
+  interface WatchHandle {
+    (): void // callable, same as `stop`
+    pause: () => void
+    resume: () => void
+    stop: () => void
+  }
   ```
 
   > Types are simplified for readability.
@@ -472,6 +525,21 @@ Watches one or more reactive data sources and invokes a callback function when t
   stop()
   ```
 
+  Pausing / resuming the watcher: <sup class="vt-badge" data-text="3.5+" />
+
+  ```js
+  const { stop, pause, resume } = watchEffect(() => {})
+
+  // temporarily pause the watcher
+  pause()
+
+  // resume later
+  resume()
+
+  // stop
+  stop()
+  ```
+
   Side effect cleanup:
 
   ```js
@@ -484,7 +552,45 @@ Watches one or more reactive data sources and invokes a callback function when t
   })
   ```
 
+  Side effect cleanup in 3.5+:
+
+  ```js
+  import { onWatcherCleanup } from 'vue'
+
+  watch(id, async (newId) => {
+    const { response, cancel } = doAsyncWork(newId)
+    onWatcherCleanup(cancel)
+    data.value = await response
+  })
+  ```
+
 - **See also**
 
   - [Guide - Watchers](/guide/essentials/watchers)
   - [Guide - Watcher Debugging](/guide/extras/reactivity-in-depth#watcher-debugging)
+
+## onWatcherCleanup() <sup class="vt-badge" data-text="3.5+" /> {#onwatchercleanup}
+
+Register a cleanup function to be executed when the current watcher is about to re-run. Can only be called during the synchronous execution of a `watchEffect` effect function or `watch` callback function (i.e. it cannot be called after an `await` statement in an async function.)
+
+- **Type**
+
+  ```ts
+  function onWatcherCleanup(
+    cleanupFn: () => void,
+    failSilently?: boolean
+  ): void
+  ```
+
+- **Example**
+
+  ```ts
+  import { watch, onWatcherCleanup } from 'vue'
+
+  watch(id, (newId) => {
+    const { response, cancel } = doAsyncWork(newId)
+    // `cancel` will be called if `id` changes, cancelling
+    // the previous request if it hasn't completed yet
+    onWatcherCleanup(cancel)
+  })
+  ```
diff --git a/src/guide/essentials/watchers.md b/src/guide/essentials/watchers.md
index d950548db6..e6a0465ada 100644
--- a/src/guide/essentials/watchers.md
+++ b/src/guide/essentials/watchers.md
@@ -362,6 +362,128 @@ For examples like these, with only one dependency, the benefit of `watchEffect()
 
 </div>
 
+## Side Effect Cleanup {#side-effect-cleanup}
+
+Sometimes we may perform side effects, e.g. asynchronous requests, in a watcher:
+
+<div class="composition-api">
+
+```js
+watch(id, (newId) => {
+  fetch(`/api/${newId}`).then(() => {
+    // callback logic
+  })
+})
+```
+
+</div>
+<div class="options-api">
+
+```js
+export default {
+  watch: {
+    id(newId) {
+      fetch(`/api/${newId}`).then(() => {
+        // callback logic
+      })
+    }
+  }
+}
+```
+
+</div>
+
+But what if `id` changes before the request completes? When the previous request completes, it will still fire the callback with an ID value that is already stale. Ideally, we want to be able to cancel the stale request when `id` changes to a new value.
+
+We can use the [`onWatcherCleanup()`](/api/reactivity-core/#onwatchercleanup) <sup class="vt-badge" data-text="3.5+" /> API to register a cleanup function that will be called when the watcher is invalidated and is about to re-run:
+
+<div class="composition-api">
+
+```js {10-13}
+import { watch, onWatcherCleanup } from 'vue'
+
+watch(id, (newId) => {
+  const controller = new AbortController()
+
+  fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
+    // callback logic
+  })
+
+  onWatcherCleanup(() => {
+    // abort stale request
+    controller.abort()
+  })
+})
+```
+
+</div>
+<div class="options-api">
+
+```js {12-15}
+import { onWatcherCleanup } from 'vue'
+
+export default {
+  watch: {
+    id(newId) {
+      const controller = new AbortController()
+
+      fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
+        // callback logic
+      })
+
+      onWatcherCleanup(() => {
+        // abort stale request
+        controller.abort()
+      })
+    }
+  }
+}
+```
+
+</div>
+
+Note that `onWatcherCleanup` is only supported in Vue 3.5+ and must be called during the synchronous execution of a `watchEffect` effect function or `watch` callback function: you cannot call it after an `await` statement in an async function.
+
+Alternaitvely, an `onCleanup` function is also passed to watcher callbacks as the 3rd argument<span class="composition-api">, and to the `watchEffect` effect function as the first argument</span>:
+
+<div class="composition-api">
+
+```js
+watch(id, (newId, oldId, onCleanup) => {
+  // ...
+  onCleanup(() => {
+    // cleanup logic
+  })
+})
+
+watchEffect((onCleanup) => {
+  // ...
+  onCleanup(() => {
+    // cleanup logic
+  })
+})
+```
+
+</div>
+<div class="options-api">
+
+```js
+export default {
+  watch: {
+    id(newId, oldId, onCleanup) {
+      // ...
+      onCleanup(() => {
+        // cleanup logic
+      })
+    }
+  }
+}
+```
+
+</div>
+
+This works in versions before 3.5. In addition, `onCleanup` passed via function argument is bound to the watcher instance so it is not subject to the synchronously constraint of `onWatcherCleanup`.
+
 ## Callback Flush Timing {#callback-flush-timing}
 
 When you mutate reactive state, it may trigger both Vue component updates and watcher callbacks created by you.

From 4fa98d4521114c36e20b321048e950dacb1a53ee Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 14:41:18 +0800
Subject: [PATCH 04/17] 3.5: watch deep support number

---
 src/api/reactivity-core.md       | 4 ++--
 src/guide/essentials/watchers.md | 2 ++
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/api/reactivity-core.md b/src/api/reactivity-core.md
index 6e5aba7109..456928c4b2 100644
--- a/src/api/reactivity-core.md
+++ b/src/api/reactivity-core.md
@@ -403,7 +403,7 @@ Watches one or more reactive data sources and invokes a callback function when t
 
   interface WatchOptions extends WatchEffectOptions {
     immediate?: boolean // default: false
-    deep?: boolean // default: false
+    deep?: boolean | number // default: false
     flush?: 'pre' | 'post' | 'sync' // default: 'pre'
     onTrack?: (event: DebuggerEvent) => void
     onTrigger?: (event: DebuggerEvent) => void
@@ -438,7 +438,7 @@ Watches one or more reactive data sources and invokes a callback function when t
   The third optional argument is an options object that supports the following options:
 
   - **`immediate`**: trigger the callback immediately on watcher creation. Old value will be `undefined` on the first call.
-  - **`deep`**: force deep traversal of the source if it is an object, so that the callback fires on deep mutations. See [Deep Watchers](/guide/essentials/watchers#deep-watchers).
+  - **`deep`**: force deep traversal of the source if it is an object, so that the callback fires on deep mutations. In 3.5+, this can also be a number indicating the max traversal depth. See [Deep Watchers](/guide/essentials/watchers#deep-watchers).
   - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core#watcheffect).
   - **`onTrack / onTrigger`**: debug the watcher's dependencies. See [Watcher Debugging](/guide/extras/reactivity-in-depth#watcher-debugging).
   - **`once`**: run the callback only once. The watcher is automatically stopped after the first callback run. <sup class="vt-badge" data-text="3.4+" />
diff --git a/src/guide/essentials/watchers.md b/src/guide/essentials/watchers.md
index e6a0465ada..45fc0742ae 100644
--- a/src/guide/essentials/watchers.md
+++ b/src/guide/essentials/watchers.md
@@ -224,6 +224,8 @@ watch(
 
 </div>
 
+In Vue 3.5+, the `deep` option can also be a number indicating the max traversal depth - i.e. how many levels should Vue traverse an object's nested properties.
+
 :::warning Use with Caution
 Deep watch requires traversing all nested properties in the watched object, and can be expensive when used on large data structures. Use it only when necessary and beware of the performance implications.
 :::

From d0918cd7cfd5df583f69ec95bda3c6dd9c7714b3 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 15:08:04 +0800
Subject: [PATCH 05/17] 3.5: useId and app.config.idPrefix

---
 src/api/application.md | 20 ++++++++++++++++++++
 src/api/general.md     | 31 +++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/src/api/application.md b/src/api/application.md
index b3c790e6df..132c34d29a 100644
--- a/src/api/application.md
+++ b/src/api/application.md
@@ -610,3 +610,23 @@ An object for defining merging strategies for custom component options.
   ```
 
 - **See also** [Component Instance - `$options`](/api/component-instance#options)
+
+## app.config.idPrefix <sup class="vt-badge" data-text="3.5+" /> {#app-config-idprefix}
+
+Configure a prefix for all IDs generated via [useId()](/api/general#useid) inside this application.
+
+- **Type:** `string`
+
+- **Default:** `undefined`
+
+- **Example:**
+
+  ```js
+  app.config.idPrefix = 'my-app'
+  ```
+
+  ```js
+  // in a component:
+  const id1 = useId() // 'my-app:0'
+  const id2 = useId() // 'my-app:1'
+  ```
diff --git a/src/api/general.md b/src/api/general.md
index 80eec455f9..569412c552 100644
--- a/src/api/general.md
+++ b/src/api/general.md
@@ -266,3 +266,34 @@ This method accepts the same argument as [`defineComponent`](#definecomponent),
   - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
 
   - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.
+
+## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
+
+`useId()` is an API that can be used to generate unique-per-application IDs.
+
+- **Composition API only.**
+
+- **Example**
+
+  ```vue
+  <script setup>
+  import { useId } from 'vue'
+
+  const id = useId()
+  </script>
+
+  <template>
+    <form>
+      <label :for="id">Name:</label>
+      <input :id="id" type="text" />
+    </form>
+  </template>
+  ```
+
+- **Details**
+
+  IDs generated by `useId()` are unique-per-application. It can be used to generate IDs for form elements and accessibility attributes. Multiple calls in the same component will generate different IDs; multiple instances of the same component calling `useId()` will also have different IDs.
+  
+  IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
+
+  If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).

From c44739a52fcd9dece01eac1ef25837c47b9d6e6a Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 15:11:32 +0800
Subject: [PATCH 06/17] 3.5: lazy hydration

---
 src/guide/components/async.md | 99 +++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/src/guide/components/async.md b/src/guide/components/async.md
index 4927549f6a..fe786b969d 100644
--- a/src/guide/components/async.md
+++ b/src/guide/components/async.md
@@ -108,6 +108,105 @@ If a loading component is provided, it will be displayed first while the inner c
 
 If an error component is provided, it will be displayed when the Promise returned by the loader function is rejected. You can also specify a timeout to show the error component when the request is taking too long.
 
+## Lazy Hydration <sup class="vt-badge" data-text="3.5+" /> {#lazy-hydration}
+
+> This section only applies if you are using [Server-Side Rendering](/guide/scaling-up/ssr).
+
+In Vue 3.5+, async components can control when they are hydrated by providing a hydration strategy.
+
+- Vue provides a number of built-in hydration strategies. These built-in strategies need to be individually imported so they can be tree-shaken if not used.
+
+- The design is intentionally low-level for flexibility. Compiler syntax sugar can potentially be built on top of this in the future either in core or in higher level solutions (e.g. Nuxt).
+
+### Hydrate on Idle
+
+Hydrates via `requestIdleCallback`:
+
+```js
+import { defineAsyncComponent, hydrateOnIdle } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  loader: () => import('./Comp.vue'),
+  hydrate: hydrateOnIdle(/* optionally pass a max timeout */)
+})
+```
+
+### Hydrate on Visible
+
+Hydrate when element(s) become visible via `IntersectionObserver`.
+
+```js
+import { defineAsyncComponent, hydrateOnVisible } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  loader: () => import('./Comp.vue'),
+  hydrate: hydrateOnVisible()
+})
+```
+
+Can optionally pass in an options object value for the observer:
+
+```js
+hydrateOnVisible({ rootMargin: '100px' })
+```
+
+### Hydrate on Media Query
+
+Hydrates when the specified media query matches.
+
+```js
+import { defineAsyncComponent, hydrateOnMediaQuery } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  loader: () => import('./Comp.vue'),
+  hydrate: hydrateOnMediaQuery('(max-width:500px)')
+})
+```
+
+### Hydrate on Interaction
+
+Hydrates when specified event(s) are triggered on the component element(s). The event that triggered the hydration will also be replayed once hydration is complete.
+
+```js
+import { defineAsyncComponent, hydrateOnInteraction } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  loader: () => import('./Comp.vue'),
+  hydrate: hydrateOnInteraction('click')
+})
+```
+
+Can also be a list of multiple event types:
+
+```js
+hydrateOnInteraction(['wheel', 'mouseover'])
+```
+
+### Custom Strategy
+
+```ts
+import { defineAsyncComponent, type HydrationStrategy } from 'vue'
+
+const myStrategy: HydrationStrategy = (hydrate, forEachElement) => {
+  // forEachElement is a helper to iterate through all the root elememts
+  // in the component's non-hydrated DOM, since the root can be a fragment
+  // instead of a single element
+  forEachElement(el => {
+    // ...
+  })
+  // call `hydrate` when ready
+  hydrate()
+  return () => {
+    // return a teardown function if needed
+  }
+}
+
+const AsyncComp = defineAsyncComponent({
+  loader: () => import('./Comp.vue'),
+  hydrate: myStrategy
+})
+```
+
 ## Using with Suspense {#using-with-suspense}
 
 Async components can be used with the `<Suspense>` built-in component. The interaction between `<Suspense>` and async components is documented in the [dedicated chapter for `<Suspense>`](/guide/built-ins/suspense).

From caa99ca611ef18e863848d07d2249e4b8801ec36 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 15:20:44 +0800
Subject: [PATCH 07/17] 3.5: data-allow-mismatch

---
 src/api/ssr.md              | 20 ++++++++++++++++++++
 src/guide/scaling-up/ssr.md |  4 ++++
 2 files changed, 24 insertions(+)

diff --git a/src/api/ssr.md b/src/api/ssr.md
index a85101323a..a39ea41876 100644
--- a/src/api/ssr.md
+++ b/src/api/ssr.md
@@ -220,3 +220,23 @@ A runtime API used to retrieve the context object passed to `renderToString()` o
   }
   </script>
   ```
+
+## data-allow-mismatch <sup class="vt-badge" data-text="3.5+" /> {#data-allow-mismatch}
+
+A special attribute that can be used to suppress [hydration mismatch](/guide/scaling-up/ssr#hydration-mismatch) warnings.
+
+- **Example**
+
+  ```html
+  <div data-allow-mismatch="text">{{ data.toLocaleString() }}</div>
+  ```
+
+  The value can limit the allowed mismatch to a specific type. Allowed values are:
+
+  - `text`
+  - `children` (only allows mismatch for direct children)
+  - `class`
+  - `style`
+  - `attribute`
+
+  If no value is provided, all types of mismatches will be allowed.
diff --git a/src/guide/scaling-up/ssr.md b/src/guide/scaling-up/ssr.md
index 780c6c1ba0..c78ce0b7be 100644
--- a/src/guide/scaling-up/ssr.md
+++ b/src/guide/scaling-up/ssr.md
@@ -314,6 +314,10 @@ If the DOM structure of the pre-rendered HTML does not match the expected output
 
 When Vue encounters a hydration mismatch, it will attempt to automatically recover and adjust the pre-rendered DOM to match the client-side state. This will lead to some rendering performance loss due to incorrect nodes being discarded and new nodes being mounted, but in most cases, the app should continue to work as expected. That said, it is still best to eliminate hydration mismatches during development.
 
+#### Suppressing Hydration Mismatches <sup class="vt-badge" data-text="3.5+" /> {#suppressing-hydration-mismatches}
+
+In Vue 3.5+, it is possible to selectively suppress inevitable hydration mismatches by using the [`data-allow-mismatch`](/api/ssr#data-allow-mismatch) attribute.
+
 ### Custom Directives {#custom-directives}
 
 Since most custom directives involve direct DOM manipulation, they are ignored during SSR. However, if you want to specify how a custom directive should be rendered (i.e. what attributes it should add to the rendered element), you can use the `getSSRProps` directive hook:

From 43b0da63361121fa9721e26c79998f02a7c7c7d4 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 15:53:50 +0800
Subject: [PATCH 08/17] 3.5: add composition api helpers page

---
 .vitepress/config.ts               |  4 +++
 src/api/composition-api-helpers.md | 40 ++++++++++++++++++++++++++++++
 src/api/general.md                 | 31 -----------------------
 3 files changed, 44 insertions(+), 31 deletions(-)
 create mode 100644 src/api/composition-api-helpers.md

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
index dd0f10a780..41f0df0c9c 100644
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -368,6 +368,10 @@ export const sidebar: ThemeConfig['sidebar'] = {
         {
           text: 'Dependency Injection',
           link: '/api/composition-api-dependency-injection'
+        },
+        {
+          text: 'Helpers',
+          link: '/api/composition-api-helpers'
         }
       ]
     },
diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
new file mode 100644
index 0000000000..6cbe39314d
--- /dev/null
+++ b/src/api/composition-api-helpers.md
@@ -0,0 +1,40 @@
+# Composition API: Helpers {#composition-api-helpers}
+
+## useAttrs() {#useattrs}
+
+## useSlots() {#useslots}
+
+## useModel() <sup class="vt-badge" data-text="3.4+" /> {#usemodel}
+
+## useTemplateRef() <sup class="vt-badge" data-text="3.5+" /> {#usetemplateref}
+
+## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
+
+`useId()` is an API that can be used to generate unique-per-application IDs.
+
+- **Composition API only.**
+
+- **Example**
+
+  ```vue
+  <script setup>
+  import { useId } from 'vue'
+
+  const id = useId()
+  </script>
+
+  <template>
+    <form>
+      <label :for="id">Name:</label>
+      <input :id="id" type="text" />
+    </form>
+  </template>
+  ```
+
+- **Details**
+
+  IDs generated by `useId()` are unique-per-application. It can be used to generate IDs for form elements and accessibility attributes. Multiple calls in the same component will generate different IDs; multiple instances of the same component calling `useId()` will also have different IDs.
+  
+  IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
+
+  If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).
diff --git a/src/api/general.md b/src/api/general.md
index 569412c552..80eec455f9 100644
--- a/src/api/general.md
+++ b/src/api/general.md
@@ -266,34 +266,3 @@ This method accepts the same argument as [`defineComponent`](#definecomponent),
   - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
 
   - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.
-
-## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
-
-`useId()` is an API that can be used to generate unique-per-application IDs.
-
-- **Composition API only.**
-
-- **Example**
-
-  ```vue
-  <script setup>
-  import { useId } from 'vue'
-
-  const id = useId()
-  </script>
-
-  <template>
-    <form>
-      <label :for="id">Name:</label>
-      <input :id="id" type="text" />
-    </form>
-  </template>
-  ```
-
-- **Details**
-
-  IDs generated by `useId()` are unique-per-application. It can be used to generate IDs for form elements and accessibility attributes. Multiple calls in the same component will generate different IDs; multiple instances of the same component calling `useId()` will also have different IDs.
-  
-  IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
-
-  If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).

From 256b92a119116824ef6f214aa464e7612981380e Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 16:06:15 +0800
Subject: [PATCH 09/17] useAttrs, useSlots, useModel

---
 src/api/composition-api-helpers.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
index 6cbe39314d..c5757327ff 100644
--- a/src/api/composition-api-helpers.md
+++ b/src/api/composition-api-helpers.md
@@ -2,18 +2,39 @@
 
 ## useAttrs() {#useattrs}
 
+Returns the `attrs` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes the [fallthrough attributes](/guide/components/attrs#fallthrough-attributes) of the current component. This is intended to be used in `<script setup>` where the setup context object is not available.
+
 ## useSlots() {#useslots}
 
+Returns the `slots` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes parent passed slots as callable functions that return Virtual DOM nodes. This is intended to be used in `<script setup>` where the setup context object is not available.
+
+If using TypeScript, [`defineSlots()`](/api/sfc-script-setup#defineslots) should be preferred instead.
+
 ## useModel() <sup class="vt-badge" data-text="3.4+" /> {#usemodel}
 
+This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setup#definemodel). If using `<script setup>`, `defineModel()` should be preferred instead.
+
+`useModel()` can be used in non-SFC components, e.g. when using raw `setup()` function. It expects the `props` object as the first argument, and the model name as the second argument. The optional third argument can be used to declare custom getter and setter for the resulting model ref. Note that unlike `defineModel()`, you are responsible for declaring the props and emits yourself.
+
+- **Example**
+
+  ```js
+  export default {
+    props: ['count'],
+    emits: ['update:count'],
+    setup(props) {
+      const msg = useModel(props, 'count')
+      msg.value = 1
+    }
+  }
+  ```
+
 ## useTemplateRef() <sup class="vt-badge" data-text="3.5+" /> {#usetemplateref}
 
 ## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
 
 `useId()` is an API that can be used to generate unique-per-application IDs.
 
-- **Composition API only.**
-
 - **Example**
 
   ```vue

From 30e5a07e7ef2e405fa7d5e54a0a309597b3d2ee5 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 17:56:30 +0800
Subject: [PATCH 10/17] 3.5: useTemplateRef()

---
 src/api/composition-api-helpers.md      | 68 ++++++++++++++++++++-
 src/guide/essentials/template-refs.md   | 80 ++++++++++++++++++++++++-
 src/guide/typescript/composition-api.md | 57 ++++++++++--------
 3 files changed, 176 insertions(+), 29 deletions(-)

diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
index c5757327ff..acb9bb6cfc 100644
--- a/src/api/composition-api-helpers.md
+++ b/src/api/composition-api-helpers.md
@@ -4,18 +4,45 @@
 
 Returns the `attrs` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes the [fallthrough attributes](/guide/components/attrs#fallthrough-attributes) of the current component. This is intended to be used in `<script setup>` where the setup context object is not available.
 
+- **Type**
+
+  ```ts
+  function useAttrs(): Record<string, unknown>
+  ```
+
 ## useSlots() {#useslots}
 
 Returns the `slots` object from the [Setup Context](/api/composition-api-setup#setup-context), which includes parent passed slots as callable functions that return Virtual DOM nodes. This is intended to be used in `<script setup>` where the setup context object is not available.
 
 If using TypeScript, [`defineSlots()`](/api/sfc-script-setup#defineslots) should be preferred instead.
 
+- **Type**
+
+  ```ts
+  function useSlots(): Record<string, (...args: any[]) => VNode[]>
+  ```
+
 ## useModel() <sup class="vt-badge" data-text="3.4+" /> {#usemodel}
 
 This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setup#definemodel). If using `<script setup>`, `defineModel()` should be preferred instead.
 
 `useModel()` can be used in non-SFC components, e.g. when using raw `setup()` function. It expects the `props` object as the first argument, and the model name as the second argument. The optional third argument can be used to declare custom getter and setter for the resulting model ref. Note that unlike `defineModel()`, you are responsible for declaring the props and emits yourself.
 
+- **Type**
+
+  ```ts
+  function useModel(
+    props: Record<string, any>,
+    key: string,
+    options?: DefineModelOptions
+  )
+
+  type DefineModelOptions<T = any> = {
+    get?: (v: T) => any
+    set?: (v: T) => any
+  }
+  ```
+
 - **Example**
 
   ```js
@@ -31,9 +58,46 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
 
 ## useTemplateRef() <sup class="vt-badge" data-text="3.5+" /> {#usetemplateref}
 
+Returns a shallow ref whose value will be synced with the template element or component with a matching ref attribute.
+
+- **Type**
+
+  ```ts
+  function useTemplateRef<T>(key: string): Readonly<ShallowRef<T | null>>
+  ```
+
+- **Example**
+
+  ```vue
+  <script setup>
+  import { useTemplateRef, onMounted } from 'vue'
+
+  const inputRef = useTemplateRef('input')
+
+  onMounted(() => {
+    inputRef.value.focus()
+  })
+  </script>
+
+  <template>
+    <input ref="input" />
+  </template>
+  ```
+
+- **See also**
+  - [Guide - Template Refs](/guide/essentials/template-refs)
+  - [Guide - Typing Template Refs](/guide/typescript/composition-api#typing-template-refs) <sup class="vt-badge ts" />
+  - [Guide - Typing Component Template Refs](/guide/typescript/composition-api#typing-component-template-refs) <sup class="vt-badge ts" />
+
 ## useId() <sup class="vt-badge" data-text="3.5+" /> {#useid}
 
-`useId()` is an API that can be used to generate unique-per-application IDs.
+Used to generate unique-per-application IDs for accessibility attributes or form elements.
+
+- **Type**
+
+  ```ts
+  function useId(): string
+  ```
 
 - **Example**
 
@@ -55,7 +119,7 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
 - **Details**
 
   IDs generated by `useId()` are unique-per-application. It can be used to generate IDs for form elements and accessibility attributes. Multiple calls in the same component will generate different IDs; multiple instances of the same component calling `useId()` will also have different IDs.
-  
+
   IDs generated by `useId()` are also guaranteed to be stable across the server and client renders, so they can be used in SSR applications without leading to hydration mismatches.
 
   If you have more than one Vue application instance of the same page, you can avoid ID conflicts by giving each app an ID prefix via [`app.config.idPrefix`](/api/application#app-config-idprefix).
diff --git a/src/guide/essentials/template-refs.md b/src/guide/essentials/template-refs.md
index 499963255c..04624e13c8 100644
--- a/src/guide/essentials/template-refs.md
+++ b/src/guide/essentials/template-refs.md
@@ -12,7 +12,32 @@ While Vue's declarative rendering model abstracts away most of the direct DOM op
 
 <div class="composition-api">
 
-To obtain the reference with Composition API, we need to declare a ref with a name that matches the template ref attribute's value:
+To obtain the reference with Composition API, we can use the [`useTemplateRef()`](/api/composition-api-helpers#usetemplateref) <sup class="vt-badge" data-text=
+"3.5+" /> helper:
+
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+
+// the first argument must match the ref value in the template
+const input = useTemplateRef('my-input')
+
+onMounted(() => {
+  input.value.focus()
+})
+</script>
+
+<template>
+  <input ref="my-input" />
+</template>
+```
+
+When using TypeScript, Vue's IDE support and `vue-tsc` will automatically infer the type of `inputRef.value` based on what element or component the matching `ref` attribute is used on.
+
+<details>
+<summary>Usage before 3.5</summary>
+
+In versions before 3.5 where `useTemplateRef()` was not introduced, we need to declare a ref with a name that matches the template ref attribute's value:
 
 ```vue
 <script setup>
@@ -46,6 +71,8 @@ export default {
 }
 ```
 
+</details>
+
 </div>
 <div class="options-api">
 
@@ -95,6 +122,33 @@ See also: [Typing Template Refs](/guide/typescript/composition-api#typing-templa
 
 When `ref` is used inside `v-for`, the corresponding ref should contain an Array value, which will be populated with the elements after mount:
 
+```vue
+<script setup>
+import { ref, useTemplateRef, onMounted } from 'vue'
+
+const list = ref([
+  /* ... */
+])
+
+const itemRefs = useTemplateRef('items')
+
+onMounted(() => console.log(itemRefs.value))
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in list" ref="items">
+      {{ item }}
+    </li>
+  </ul>
+</template>
+```
+
+[Try it in the Playground](https://play.vuejs.org/#eNp9UsluwjAQ/ZWRLwQpDepyQoDUIg6t1EWUW91DFAZq6tiWF4oU5d87dtgqVRyyzLw3b+aN3bB7Y4ptQDZkI1dZYTw49MFMuBK10dZDAxZXOQSHC6yNLD3OY6zVsw7K4xJaWFldQ49UelxxVWnlPEhBr3GszT6uc7jJ4fazf4KFx5p0HFH+Kme9CLle4h6bZFkfxhNouAIoJVqfHQSKbSkDFnVpMhEpovC481NNVcr3SaWlZzTovJErCqgydaMIYBRk+tKfFLC9Wmk75iyqg1DJBWfRxT7pONvTAZom2YC23QsMpOg0B0l0NDh2YjnzjpyvxLrYOK1o3ckLZ5WujSBHr8YL2gxnw85lxEop9c9TynkbMD/kqy+svv/Jb9wu5jh7s+jQbpGzI+ZLu0byEuHZ+wvt6Ays9TJIYl8A5+i0DHHGjvYQ1JLGPuOlaR/TpRFqvXCzHR2BO5iKg0Zmm/ic0W2ZXrB+Gve2uEt1dJKs/QXbwePE)
+
+<details>
+<summary>Usage before 3.5</summary>
+
 ```vue
 <script setup>
 import { ref, onMounted } from 'vue'
@@ -117,7 +171,7 @@ onMounted(() => console.log(itemRefs.value))
 </template>
 ```
 
-[Try it in the Playground](https://play.vuejs.org/#eNpFjs1qwzAQhF9l0CU2uDZtb8UOlJ576bXqwaQyCGRJyCsTEHr3rGwnOehnd2e+nSQ+vW/XqMSH6JdL0J6wKIr+LK2evQuEhKCmBs5+u2hJ/SNjCm7GiV0naaW9OLsQjOZrKNrq97XBW4P3v/o51qTmHzUtd8k+e0CrqsZwRpIWGI0KVN0N7TqaqNp59JUuEt2SutKXY5elmimZT9/t2Tk1F+z0ZiTFFdBHs738Mxrry+TCIEWhQ9sttRQl0tEsK6U4HEBKW3LkfDA6o3dst3H77rFM5BtTfm/P)
+</details>
 
 </div>
 <div class="options-api">
@@ -173,6 +227,26 @@ Note we are using a dynamic `:ref` binding so we can pass it a function instead
 
 <div class="composition-api">
 
+```vue
+<script setup>
+import { useTemplateRef, onMounted } from 'vue'
+import Child from './Child.vue'
+
+const childRef = useTemplateRef('child')
+
+onMounted(() => {
+  // childRef.value will hold an instance of <Child />
+})
+</script>
+
+<template>
+  <Child ref="child" />
+</template>
+```
+
+<details>
+<summary>Usage before 3.5</summary>
+
 ```vue
 <script setup>
 import { ref, onMounted } from 'vue'
@@ -190,6 +264,8 @@ onMounted(() => {
 </template>
 ```
 
+</details>
+
 </div>
 <div class="options-api">
 
diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
index 5797e38c9b..15cc01b6b0 100644
--- a/src/guide/typescript/composition-api.md
+++ b/src/guide/typescript/composition-api.md
@@ -371,6 +371,17 @@ const foo = inject('foo') as string
 
 ## Typing Template Refs {#typing-template-refs}
 
+With Vue 3.5 and `@vue/language-tools` 2.1 (powering both the IDE language service and `vue-tsc`), the type of refs created by `useTemplateRef()` in SFCs can be **automatically inferred** for static refs based on what element the matching `ref` attribute is used on.
+
+In cases where auto-inference is not possible, you can still cast the template ref to an explicit type via the generic argument:
+
+```ts
+const el = useTemplateRef<HTMLInputElement>(null)
+```
+
+<details>
+<summary>Usage before 3.5</summary>
+
 Template refs should be created with an explicit generic type argument and an initial value of `null`:
 
 ```vue
@@ -389,50 +400,45 @@ onMounted(() => {
 </template>
 ```
 
+</details>
+
 To get the right DOM interface you can check pages like [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#technical_summary).
 
 Note that for strict type safety, it is necessary to use optional chaining or type guards when accessing `el.value`. This is because the initial ref value is `null` until the component is mounted, and it can also be set to `null` if the referenced element is unmounted by `v-if`.
 
 ## Typing Component Template Refs {#typing-component-template-refs}
 
-Sometimes you might need to annotate a template ref for a child component in order to call its public method. For example, we have a `MyModal` child component with a method that opens the modal:
-
-```vue
-<!-- MyModal.vue -->
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const isContentShown = ref(false)
-const open = () => (isContentShown.value = true)
+With Vue 3.5 and `@vue/language-tools` 2.1 (powering both the IDE language service and `vue-tsc`), the type of refs created by `useTemplateRef()` in SFCs can be **automatically inferred** for static refs based on what element or component the matching `ref` attribute is used on.
 
-defineExpose({
-  open
-})
-</script>
-```
+In cases where auto-inference is not possible (e.g. non-SFC usage or dynamic components), you can still cast the template ref to an explicit type via the generic argument.
 
-In order to get the instance type of `MyModal`, we need to first get its type via `typeof`, then use TypeScript's built-in `InstanceType` utility to extract its instance type:
+In order to get the instance type of an imported component, we need to first get its type via `typeof`, then use TypeScript's built-in `InstanceType` utility to extract its instance type:
 
 ```vue{5}
 <!-- App.vue -->
 <script setup lang="ts">
-import MyModal from './MyModal.vue'
+import { useTemplateRef } from 'vue'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
 
-const modal = ref<InstanceType<typeof MyModal> | null>(null)
+type FooType = InstanceType<typeof Foo>
+type BarType = InstanceType<typeof Bar>
 
-const openModal = () => {
-  modal.value?.open()
-}
+const compRef = useTemplateRef<FooType | BarType>('comp')
 </script>
+
+<template>
+  <component :is="Math.random() > 0.5 ? Foo : Bar" ref="comp" />
+</template>
 ```
 
 In cases where the exact type of the component isn't available or isn't important, `ComponentPublicInstance` can be used instead. This will only include properties that are shared by all components, such as `$el`:
 
 ```ts
-import { ref } from 'vue'
+import { useTemplateRef } from 'vue'
 import type { ComponentPublicInstance } from 'vue'
 
-const child = ref<ComponentPublicInstance | null>(null)
+const child = useTemplateRef<ComponentPublicInstance | null>(null)
 ```
 
 In cases where the component referenced is a [generic component](/guide/typescript/overview.html#generic-components), for instance `MyGenericModal`:
@@ -457,11 +463,11 @@ It needs to be referenced using `ComponentExposed` from the [`vue-component-type
 ```vue
 <!-- App.vue -->
 <script setup lang="ts">
+import { useTemplateRef } from 'vue'
 import MyGenericModal from './MyGenericModal.vue'
+import type { ComponentExposed } from 'vue-component-type-helpers'
 
-import type { ComponentExposed } from 'vue-component-type-helpers';
-
-const modal = ref<ComponentExposed<typeof MyModal> | null>(null)
+const modal = useTemplateRef<ComponentExposed<typeof MyModal>>(null)
 
 const openModal = () => {
   modal.value?.open('newValue')
@@ -469,3 +475,4 @@ const openModal = () => {
 </script>
 ```
 
+Note that with `@vue/language-tools` 2.1+, static template refs' types can be automatically inferred and the above is only needed in edge cases.

From 5c0ee2ba002bd8442568d874b5ffea7ad0b893b2 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 18:03:59 +0800
Subject: [PATCH 11/17] app.config.throwUnhandledErrorInProduction

---
 src/api/application.md | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/src/api/application.md b/src/api/application.md
index 132c34d29a..328f000e45 100644
--- a/src/api/application.md
+++ b/src/api/application.md
@@ -90,6 +90,18 @@ Unmounts a mounted application instance, triggering the unmount lifecycle hooks
   }
   ```
 
+## app.onUnmount() <sup class="vt-badge" data-text="3.5+" /> {#app-onunmount}
+
+Registers a callback to be called when the app is unmounted.
+
+- **Type**
+
+  ```ts
+  interface App {
+    onUnmount(callback: () => any): void
+  }
+  ```
+
 ## app.component() {#app-component}
 
 Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.
@@ -619,7 +631,7 @@ Configure a prefix for all IDs generated via [useId()](/api/general#useid) insid
 
 - **Default:** `undefined`
 
-- **Example:**
+- **Example**
 
   ```js
   app.config.idPrefix = 'my-app'
@@ -630,3 +642,21 @@ Configure a prefix for all IDs generated via [useId()](/api/general#useid) insid
   const id1 = useId() // 'my-app:0'
   const id2 = useId() // 'my-app:1'
   ```
+
+## app.config.throwUnhandledErrorInProduction <sup class="vt-badge" data-text="3.5+" /> {#app-config-throwunhandlederrorinproduction}
+
+Force unhandled errors to be thrown in production mode.
+
+- **Type:** `boolean`
+
+- **Default:** `false`
+
+- **Details**
+
+  By default, errors thrown inside a Vue application but not explicit handled have different behavior between development and production modes:
+
+  - In development, the error is thrown and can possibly crash the application. This is to make the error more prominent so that it can be noticed and fixed during development.
+
+  - In production, the error will only be logged to the console to minimize the impact to end users. However, this may prevent errors that only happen in production from being caught by error monitoring services.
+
+  By setting `app.config.throwUnhandledErrorInProduction` to `true`, unhandled errors will be thrown even in production mode.

From 6860d600a0dd6c2bcfefb699f97631ac78b2fb53 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 18:09:59 +0800
Subject: [PATCH 12/17] remove version badages for previous minors

---
 src/api/application.md                          |  4 +++-
 src/api/built-in-directives.md                  | 10 ++++++----
 src/api/compile-time-flags.md                   |  4 +++-
 src/api/composition-api-dependency-injection.md |  4 +++-
 src/api/composition-api-helpers.md              |  8 ++++++--
 src/api/general.md                              |  4 +++-
 src/api/reactivity-core.md                      |  4 ++--
 src/api/reactivity-utilities.md                 |  4 +++-
 src/api/sfc-script-setup.md                     |  4 +++-
 src/guide/best-practices/performance.md         |  4 ++--
 src/guide/essentials/template-syntax.md         |  4 +++-
 src/guide/essentials/watchers.md                |  4 +++-
 12 files changed, 40 insertions(+), 18 deletions(-)

diff --git a/src/api/application.md b/src/api/application.md
index 328f000e45..189422bcb7 100644
--- a/src/api/application.md
+++ b/src/api/application.md
@@ -283,10 +283,12 @@ Provide a value that can be injected in all descendant components within the app
   - [App-level Provide](/guide/components/provide-inject#app-level-provide)
   - [app.runWithContext()](#app-runwithcontext)
 
-## app.runWithContext()<sup class="vt-badge" data-text="3.3+" /> {#app-runwithcontext}
+## app.runWithContext() {#app-runwithcontext}
 
 Execute a callback with the current app as injection context.
 
+- Only supported in 3.3+
+
 - **Type**
 
   ```ts
diff --git a/src/api/built-in-directives.md b/src/api/built-in-directives.md
index c0a3b6e814..8afb0bfc48 100644
--- a/src/api/built-in-directives.md
+++ b/src/api/built-in-directives.md
@@ -259,7 +259,7 @@ Dynamically bind one or more attributes, or a component prop to an expression.
 
 - **Shorthand:**
   - `:` or `.` (when using `.prop` modifier)
-  - Omitting value (when attribute and bound value has the same name) <sup class="vt-badge">3.4+</sup>
+  - Omitting value (when attribute and bound value has the same name, requires 3.4+)
 
 - **Expects:** `any (with argument) | Object (without argument)`
 
@@ -268,8 +268,8 @@ Dynamically bind one or more attributes, or a component prop to an expression.
 - **Modifiers**
 
   - `.camel` - transform the kebab-case attribute name into camelCase.
-  - `.prop` - force a binding to be set as a DOM property. <sup class="vt-badge">3.2+</sup>
-  - `.attr` - force a binding to be set as a DOM attribute. <sup class="vt-badge">3.2+</sup>
+  - `.prop` - force a binding to be set as a DOM property (3.2+).
+  - `.attr` - force a binding to be set as a DOM attribute (3.2+).
 
 - **Usage**
 
@@ -468,7 +468,9 @@ Render the element and component once only, and skip future updates.
   - [Data Binding Syntax - interpolations](/guide/essentials/template-syntax#text-interpolation)
   - [v-memo](#v-memo)
 
-## v-memo <sup class="vt-badge" data-text="3.2+" /> {#v-memo}
+## v-memo {#v-memo}
+
+- Only supported in 3.2+
 
 - **Expects:** `any[]`
 
diff --git a/src/api/compile-time-flags.md b/src/api/compile-time-flags.md
index cdd59fca68..b590cad810 100644
--- a/src/api/compile-time-flags.md
+++ b/src/api/compile-time-flags.md
@@ -26,12 +26,14 @@ See [Configuration Guides](#configuration-guides) on how to configure them depen
 
   Enable / disable devtools support in production builds. This will result in more code included in the bundle, so it is recommended to only enable this for debugging purposes.
 
-## `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__` <sup class="vt-badge" data-text="3.4+" /> {#VUE_PROD_HYDRATION_MISMATCH_DETAILS}
+## `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__` {#VUE_PROD_HYDRATION_MISMATCH_DETAILS}
 
 - **Default:** `false`
 
   Enable/disable detailed warnings for hydration mismatches in production builds. This will result in more code included in the bundle, so it is recommended to only enable this for debugging purposes.
 
+- Only available in 3.4+
+
 ## Configuration Guides {#configuration-guides}
 
 ### Vite {#vite}
diff --git a/src/api/composition-api-dependency-injection.md b/src/api/composition-api-dependency-injection.md
index 32ecb19fbc..89df326578 100644
--- a/src/api/composition-api-dependency-injection.md
+++ b/src/api/composition-api-dependency-injection.md
@@ -107,10 +107,12 @@ Injects a value provided by an ancestor component or the application (via `app.p
   - [Guide - Provide / Inject](/guide/components/provide-inject)
   - [Guide - Typing Provide / Inject](/guide/typescript/composition-api#typing-provide-inject) <sup class="vt-badge ts" />
 
-## hasInjectionContext() <sup class="vt-badge" data-text="3.3+" /> {#has-injection-context}
+## hasInjectionContext() {#has-injection-context}
 
 Returns true if [inject()](#inject) can be used without warning about being called in the wrong place (e.g. outside of `setup()`). This method is designed to be used by libraries that want to use `inject()` internally without triggering a warning to the end user.
 
+- Only supported in 3.3+
+
 - **Type**
 
   ```ts
diff --git a/src/api/composition-api-helpers.md b/src/api/composition-api-helpers.md
index acb9bb6cfc..d09391857d 100644
--- a/src/api/composition-api-helpers.md
+++ b/src/api/composition-api-helpers.md
@@ -22,11 +22,11 @@ If using TypeScript, [`defineSlots()`](/api/sfc-script-setup#defineslots) should
   function useSlots(): Record<string, (...args: any[]) => VNode[]>
   ```
 
-## useModel() <sup class="vt-badge" data-text="3.4+" /> {#usemodel}
+## useModel() {#usemodel}
 
 This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setup#definemodel). If using `<script setup>`, `defineModel()` should be preferred instead.
 
-`useModel()` can be used in non-SFC components, e.g. when using raw `setup()` function. It expects the `props` object as the first argument, and the model name as the second argument. The optional third argument can be used to declare custom getter and setter for the resulting model ref. Note that unlike `defineModel()`, you are responsible for declaring the props and emits yourself.
+- Only available in 3.4+
 
 - **Type**
 
@@ -56,6 +56,10 @@ This is the underlying helper that powers [`defineModel()`](/api/sfc-script-setu
   }
   ```
 
+- **Details**
+
+  `useModel()` can be used in non-SFC components, e.g. when using raw `setup()` function. It expects the `props` object as the first argument, and the model name as the second argument. The optional third argument can be used to declare custom getter and setter for the resulting model ref. Note that unlike `defineModel()`, you are responsible for declaring the props and emits yourself.
+
 ## useTemplateRef() <sup class="vt-badge" data-text="3.5+" /> {#usetemplateref}
 
 Returns a shallow ref whose value will be synced with the template element or component with a matching ref attribute.
diff --git a/src/api/general.md b/src/api/general.md
index 80eec455f9..d526810058 100644
--- a/src/api/general.md
+++ b/src/api/general.md
@@ -129,7 +129,9 @@ A type helper for defining a Vue component with type inference.
   type FooInstance = InstanceType<typeof Foo>
   ```
 
-  ### Function Signature <sup class="vt-badge" data-text="3.3+" /> {#function-signature}
+  ### Function Signature {#function-signature}
+
+  - Only supported in 3.3+
 
   `defineComponent()` also has an alternative signature that is meant to be used with Composition API and [render functions or JSX](/guide/extras/render-function.html).
 
diff --git a/src/api/reactivity-core.md b/src/api/reactivity-core.md
index 456928c4b2..ba0cb10f32 100644
--- a/src/api/reactivity-core.md
+++ b/src/api/reactivity-core.md
@@ -112,7 +112,7 @@ Takes a [getter function](https://developer.mozilla.org/en-US/docs/Web/JavaScrip
   - [Guide - Computed Properties](/guide/essentials/computed)
   - [Guide - Computed Debugging](/guide/extras/reactivity-in-depth#computed-debugging)
   - [Guide - Typing `computed()`](/guide/typescript/composition-api#typing-computed) <sup class="vt-badge ts" />
-  - [Guide - Performance - Computed Stability](/guide/best-practices/performance#computed-stability) <sup class="vt-badge" data-text="3.4+" />
+  - [Guide - Performance - Computed Stability](/guide/best-practices/performance#computed-stability)
 
 ## reactive() {#reactive}
 
@@ -441,7 +441,7 @@ Watches one or more reactive data sources and invokes a callback function when t
   - **`deep`**: force deep traversal of the source if it is an object, so that the callback fires on deep mutations. In 3.5+, this can also be a number indicating the max traversal depth. See [Deep Watchers](/guide/essentials/watchers#deep-watchers).
   - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core#watcheffect).
   - **`onTrack / onTrigger`**: debug the watcher's dependencies. See [Watcher Debugging](/guide/extras/reactivity-in-depth#watcher-debugging).
-  - **`once`**: run the callback only once. The watcher is automatically stopped after the first callback run. <sup class="vt-badge" data-text="3.4+" />
+  - **`once`**: (3.4+) run the callback only once. The watcher is automatically stopped after the first callback run.
 
   Compared to [`watchEffect()`](#watcheffect), `watch()` allows us to:
 
diff --git a/src/api/reactivity-utilities.md b/src/api/reactivity-utilities.md
index f58034e2e7..18bce64988 100644
--- a/src/api/reactivity-utilities.md
+++ b/src/api/reactivity-utilities.md
@@ -132,12 +132,14 @@ Can also be used to create a ref for a property on a source reactive object. The
 
   When using the object property signature, `toRef()` will return a usable ref even if the source property doesn't currently exist. This makes it possible to work with optional properties, which wouldn't be picked up by [`toRefs`](#torefs).
 
-## toValue() <sup class="vt-badge" data-text="3.3+" /> {#tovalue}
+## toValue() {#tovalue}
 
 Normalizes values / refs / getters to values. This is similar to [unref()](#unref), except that it also normalizes getters. If the argument is a getter, it will be invoked and its return value will be returned.
 
 This can be used in [Composables](/guide/reusability/composables.html) to normalize an argument that can be either a value, a ref, or a getter.
 
+- Only supported in 3.3+
+
 - **Type**
 
   ```ts
diff --git a/src/api/sfc-script-setup.md b/src/api/sfc-script-setup.md
index fe955a6eaa..116233c30c 100644
--- a/src/api/sfc-script-setup.md
+++ b/src/api/sfc-script-setup.md
@@ -267,7 +267,9 @@ This will be compiled to equivalent runtime props `default` options. In addition
 Note that default values for mutable reference types (like arrays or objects) should be wrapped in functions when using `withDefaults` to avoid accidental modification and external side effects. This ensures each component instance gets its own copy of the default value. This is **not** necessary when using default values with destructure.
 :::
 
-## defineModel() <sup class="vt-badge" data-text="3.4+" /> {#definemodel}
+## defineModel() {#definemodel}
+
+- Only available in 3.4+
 
 This macro can be used to declare a two-way binding prop that can be consumed via `v-model` from the parent component. Example usage is also discussed in the [Component `v-model`](/guide/components/v-model) guide.
 
diff --git a/src/guide/best-practices/performance.md b/src/guide/best-practices/performance.md
index f66339efe5..c8ea5d9144 100644
--- a/src/guide/best-practices/performance.md
+++ b/src/guide/best-practices/performance.md
@@ -124,9 +124,9 @@ Now, for most components the `active` prop will remain the same when `activeId`
 
 `v-memo` is a built-in directive that can be used to conditionally skip the update of large sub-trees or `v-for` lists. Consult its [API reference](/api/built-in-directives#v-memo) for more details.
 
-### Computed Stability <sup class="vt-badge" data-text="3.4+" /> {#computed-stability}
+### Computed Stability {#computed-stability}
 
-Starting in 3.4, a computed property will only trigger effects when its computed value has changed from the previous one. For example, the following `isEven` computed only triggers effects if the returned value has changed from `true` to `false`, or vice-versa:
+In Vue 3.4 and above, a computed property will only trigger effects when its computed value has changed from the previous one. For example, the following `isEven` computed only triggers effects if the returned value has changed from `true` to `false`, or vice-versa:
 
 ```js
 const count = ref(0)
diff --git a/src/guide/essentials/template-syntax.md b/src/guide/essentials/template-syntax.md
index 5341076c85..c08b6f8316 100644
--- a/src/guide/essentials/template-syntax.md
+++ b/src/guide/essentials/template-syntax.md
@@ -64,7 +64,9 @@ Attributes that start with `:` may look a bit different from normal HTML, but it
 
 > For the rest of the guide, we will be using the shorthand syntax in code examples, as that's the most common usage for Vue developers.
 
-### Same-name Shorthand <sup class="vt-badge" data-text="3.4+" /> {#same-name-shorthand}
+### Same-name Shorthand {#same-name-shorthand}
+
+- Only supported in 3.4+
 
 If the attribute has the same name with the JavaScript value being bound, the syntax can be further shortened to omit the attribute value:
 
diff --git a/src/guide/essentials/watchers.md b/src/guide/essentials/watchers.md
index 45fc0742ae..9b9fe3ac53 100644
--- a/src/guide/essentials/watchers.md
+++ b/src/guide/essentials/watchers.md
@@ -274,7 +274,9 @@ watch(
 
 </div>
 
-## Once Watchers <sup class="vt-badge" data-text="3.4+" /> {#once-watchers}
+## Once Watchers {#once-watchers}
+
+- Only supported in 3.4+
 
 Watcher's callback will execute whenever the watched source changes. If you want the callback to trigger only once when the source changes, use the `once: true` option.
 

From 7c69e91e59d278501db749dcc4c97b907e5da19a Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Fri, 30 Aug 2024 18:18:58 +0800
Subject: [PATCH 13/17] 3.5: deferred teleport

---
 src/api/built-in-components.md  | 15 +++++++++++++++
 src/guide/built-ins/teleport.md | 13 +++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md
index 8be0eeb239..462f1c1eba 100644
--- a/src/api/built-in-components.md
+++ b/src/api/built-in-components.md
@@ -286,6 +286,12 @@ Renders its slot content to another part of the DOM.
      * Can be changed dynamically.
      */
     disabled?: boolean
+    /**
+     * When `true`, the Teleport will defer until other
+     * parts of the application have been mounted before
+     * resolving its target. (3.5+)
+     */
+    defer?: boolean
   }
   ```
 
@@ -307,6 +313,15 @@ Renders its slot content to another part of the DOM.
   </Teleport>
   ```
 
+  Defer target resolution <sup class="vt-badge" data-text="3.5+" />:
+
+  ```vue-html
+  <Teleport defer to="#late-div">...</Teleport>
+
+  <!-- somewhere later in the template -->
+  <div id="late-div"></div>
+  ```
+
 - **See also** [Guide - Teleport](/guide/built-ins/teleport)
 
 ## `<Suspense>` <sup class="vt-badge experimental" /> {#suspense}
diff --git a/src/guide/built-ins/teleport.md b/src/guide/built-ins/teleport.md
index e63ec654eb..4e04a17cd2 100644
--- a/src/guide/built-ins/teleport.md
+++ b/src/guide/built-ins/teleport.md
@@ -195,6 +195,19 @@ The rendered result would be:
 </div>
 ```
 
+## Deferred Teleport <sup class="vt-badge" data-text="3.5+" /> {#deferred-teleport}
+
+In Vue 3.5 and above, we can use the `defer` prop to defer the target resolving of a Teleport until other parts of the application have mounted. This allows the Teleport to target a container element that is rendered by Vue, but in a later part of the component tree:
+
+```vue-html
+<Teleport defer to="#late-div">...</Teleport>
+
+<!-- somewhere later in the template -->
+<div id="late-div"></div>
+```
+
+Note that the target element must be rendered in the same mount / update tick with the Teleport - i.e. if the `<div>` is only mounted a second later, the Teleport will still report an error. The defer works similarly to the `mounted` lifecycle hook.
+
 ---
 
 **Related**

From 1564445be4977463208e148b285147a1699aefc4 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Mon, 2 Sep 2024 17:54:50 +0800
Subject: [PATCH 14/17] 3.5: custom elements

---
 .vitepress/config.ts               |  1 +
 src/api/custom-elements.md         | 86 ++++++++++++++++++++++++++++++
 src/api/general.md                 | 43 ---------------
 src/guide/extras/web-components.md | 24 +++++++--
 4 files changed, 106 insertions(+), 48 deletions(-)
 create mode 100644 src/api/custom-elements.md

diff --git a/.vitepress/config.ts b/.vitepress/config.ts
index 41f0df0c9c..81a537fdbb 100644
--- a/.vitepress/config.ts
+++ b/.vitepress/config.ts
@@ -421,6 +421,7 @@ export const sidebar: ThemeConfig['sidebar'] = {
     {
       text: 'Advanced APIs',
       items: [
+        { text: 'Custom Elements', link: '/api/custom-elements' },
         { text: 'Render Function', link: '/api/render-function' },
         { text: 'Server-Side Rendering', link: '/api/ssr' },
         { text: 'TypeScript Utility Types', link: '/api/utility-types' },
diff --git a/src/api/custom-elements.md b/src/api/custom-elements.md
new file mode 100644
index 0000000000..aa2c9d320a
--- /dev/null
+++ b/src/api/custom-elements.md
@@ -0,0 +1,86 @@
+# Custom Elements API {#custom-elements-api}
+
+## defineCustomElement() {#definecustomelement}
+
+This method accepts the same argument as [`defineComponent`](#definecomponent), but instead returns a native [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) class constructor.
+
+- **Type**
+
+  ```ts
+  function defineCustomElement(
+    component:
+      | (ComponentOptions & CustomElementsOptions)
+      | ComponentOptions['setup'],
+    options?: CustomElementsOptions
+  ): {
+    new (props?: object): HTMLElement
+  }
+
+  interface CustomElementsOptions {
+    styles?: string[]
+
+    // the following options are 3.5+
+    configureApp?: (app: App) => void
+    shadowRoot?: boolean
+    nonce?: string
+  }
+  ```
+
+  > Type is simplified for readability.
+
+- **Details**
+
+  In addition to normal component options, `defineCustomElement()` also supports a number of options that are custom-elements-specific:
+
+  - **`styles`**: an array of inlined CSS strings for providing CSS that should be injected into the element's shadow root.
+
+  - **`configureApp`** <sup class="vt-badge" data-text="3.5+"/>: a function that can be used to configure the Vue app instance for the custom element.
+
+  - **`shadowRoot`** <sup class="vt-badge" data-text="3.5+"/>: `boolean`, defaults to `true`. Set to `false` to render the custom element without a shadow root. This means `<style>` in custom element SFCs will no longer be encapsulated.
+
+  - **`nonce`** <sup class="vt-badge" data-text="3.5+"/>: `string`, if provided, will be set as the `nonce` attribute on style tags injected to the shadow root.
+
+  Note that instead of being passed as part of the component itself, these options can also be passed via a second argument:
+
+  ```js
+  import Element from './MyElement.ce.vue'
+
+  defineCustomElement(Element, {
+    configureApp(app) {
+      // ...
+    }
+  })
+  ```
+
+  The return value is a custom element constructor that can be registered using [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
+
+- **Example**
+
+  ```js
+  import { defineCustomElement } from 'vue'
+
+  const MyVueElement = defineCustomElement({
+    /* component options */
+  })
+
+  // Register the custom element.
+  customElements.define('my-vue-element', MyVueElement)
+  ```
+
+- **See also**
+
+  - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
+
+  - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.
+
+## useHost() <sup class="vt-badge" data-text="3.5+"/> {#usehost}
+
+A Composition API helper that returns the host element of the current Vue custom element.
+
+## useShadowRoot() <sup class="vt-badge" data-text="3.5+"/> {#useshadowroot}
+
+A Composition API helper that returns the shadow root of the current Vue custom element.
+
+## this.$host <sup class="vt-badge" data-text="3.5+"/> {#this-host}
+
+An Options API property that exposes the host element of the current Vue custom element.
diff --git a/src/api/general.md b/src/api/general.md
index d526810058..53897b8108 100644
--- a/src/api/general.md
+++ b/src/api/general.md
@@ -225,46 +225,3 @@ Define an async component which is lazy loaded only when it is rendered. The arg
   ```
 
 - **See also** [Guide - Async Components](/guide/components/async)
-
-## defineCustomElement() {#definecustomelement}
-
-This method accepts the same argument as [`defineComponent`](#definecomponent), but instead returns a native [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) class constructor.
-
-- **Type**
-
-  ```ts
-  function defineCustomElement(
-    component:
-      | (ComponentOptions & { styles?: string[] })
-      | ComponentOptions['setup']
-  ): {
-    new (props?: object): HTMLElement
-  }
-  ```
-
-  > Type is simplified for readability.
-
-- **Details**
-
-  In addition to normal component options, `defineCustomElement()` also supports a special option `styles`, which should be an array of inlined CSS strings, for providing CSS that should be injected into the element's shadow root.
-
-  The return value is a custom element constructor that can be registered using [`customElements.define()`](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define).
-
-- **Example**
-
-  ```js
-  import { defineCustomElement } from 'vue'
-
-  const MyVueElement = defineCustomElement({
-    /* component options */
-  })
-
-  // Register the custom element.
-  customElements.define('my-vue-element', MyVueElement)
-  ```
-
-- **See also**
-
-  - [Guide - Building Custom Elements with Vue](/guide/extras/web-components#building-custom-elements-with-vue)
-
-  - Also note that `defineCustomElement()` requires [special config](/guide/extras/web-components#sfc-as-custom-element) when used with Single-File Components.
diff --git a/src/guide/extras/web-components.md b/src/guide/extras/web-components.md
index 001812dd01..6bf9a5de45 100644
--- a/src/guide/extras/web-components.md
+++ b/src/guide/extras/web-components.md
@@ -47,15 +47,15 @@ export default {
 ```js
 // vue.config.js
 module.exports = {
-  chainWebpack: config => {
+  chainWebpack: (config) => {
     config.module
       .rule('vue')
       .use('vue-loader')
-      .tap(options => ({
+      .tap((options) => ({
         ...options,
         compilerOptions: {
           // treat any tag that starts with ion- as custom elements
-          isCustomElement: tag => tag.startsWith('ion-')
+          isCustomElement: (tag) => tag.startsWith('ion-')
         }
       }))
   }
@@ -81,7 +81,7 @@ The primary benefit of custom elements is that they can be used with any framewo
 
 ### defineCustomElement {#definecustomelement}
 
-Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElement`](/api/general#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/general#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
+Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElement`](/api/custom-elements#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/general#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
 
 ```vue-html
 <my-vue-element></my-vue-element>
@@ -171,6 +171,20 @@ Inside the component, slots can be rendered using the `<slot/>` element as usual
 
 The [Provide / Inject API](/guide/components/provide-inject#provide-inject) and its [Composition API equivalent](/api/composition-api-dependency-injection#provide) also work between Vue-defined custom elements. However, note that this works **only between custom elements**. i.e. a Vue-defined custom element won't be able to inject properties provided by a non-custom-element Vue component.
 
+#### App Level Config <sup class="vt-badge" data-text="3.5+" /> {#app-level-config}
+
+You can configure the app instance of a Vue custom element using the `configureApp` option:
+
+```js
+defineCustomElement(MyComponent, {
+  configureApp(app) {
+    app.config.errorHandler = (err) => {
+      /* ... */
+    }
+  }
+})
+```
+
 ### SFC as Custom Element {#sfc-as-custom-element}
 
 `defineCustomElement` also works with Vue Single-File Components (SFCs). However, with the default tooling setup, the `<style>` inside the SFCs will still be extracted and merged into a single CSS file during production build. When using an SFC as a custom element, it is often desirable to inject the `<style>` tags into the custom element's shadow root instead.
@@ -242,7 +256,7 @@ export const Counter = defineCustomElement(CounterSFC)
 // register global typings
 declare module 'vue' {
   export interface GlobalComponents {
-    'Counter': typeof Counter,
+    Counter: typeof Counter
   }
 }
 ```

From a06ac21f2b5e0705fe5256bf7b77f58b03e3e05c Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Mon, 2 Sep 2024 18:07:52 +0800
Subject: [PATCH 15/17] 3.5: props destructure extras

---
 src/guide/components/props.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/guide/components/props.md b/src/guide/components/props.md
index 8d6dafc918..79f9ca0128 100644
--- a/src/guide/components/props.md
+++ b/src/guide/components/props.md
@@ -152,8 +152,34 @@ In addition, you can use JavaScript's native default value syntax to declare def
 const { foo = 'hello' } = defineProps<{ foo?: string }>()
 ```
 
+If you prefer to have more visual distinction between destructured props and normal variables in your IDE, Vue's VSCode extension provides a setting to enable inlay-hints for destructured props.
+
 ### Passing Destructured Props into Functions
 
+When we pass a destructured prop into a function, e.g.:
+
+```js
+const { foo } = defineProps(['foo'])
+
+watch(foo, /* ... */)
+```
+
+This will not work as expected because it is equivalent to `watch(props.foo, ...)` - we are passing a value instead of a reactive data source to `watch`. In fact, Vue's compiler will catch such cases and throw a warning.
+
+Similar to how we can watch a normal prop with `watch(() => props.foo, ...)`, we can watch a destructured prop also by wrapping it in a getter:
+
+```js
+watch(() => foo, /* ... */)
+```
+
+In addition, this is the recommended approach when we need to pass a destructured prop into an external function while retaining reactivity:
+
+```js
+useComposable(() => foo)
+```
+
+The external function can call the getter (or normalize it with [toValue](/api/reactivity-utilities.html#tovalue)) when it needs to track changes of the provided prop, e.g. in a computed or watcher getter.
+
 </div>
 
 ## Prop Passing Details {#prop-passing-details}

From 824deb981ea09e5005e2e148f8d4ab159de282c5 Mon Sep 17 00:00:00 2001
From: Evan You <evan@vuejs.org>
Date: Mon, 2 Sep 2024 18:18:42 +0800
Subject: [PATCH 16/17] fix dead link

---
 src/guide/essentials/watchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/essentials/watchers.md b/src/guide/essentials/watchers.md
index 9b9fe3ac53..e6558e4844 100644
--- a/src/guide/essentials/watchers.md
+++ b/src/guide/essentials/watchers.md
@@ -399,7 +399,7 @@ export default {
 
 But what if `id` changes before the request completes? When the previous request completes, it will still fire the callback with an ID value that is already stale. Ideally, we want to be able to cancel the stale request when `id` changes to a new value.
 
-We can use the [`onWatcherCleanup()`](/api/reactivity-core/#onwatchercleanup) <sup class="vt-badge" data-text="3.5+" /> API to register a cleanup function that will be called when the watcher is invalidated and is about to re-run:
+We can use the [`onWatcherCleanup()`](/api/reactivity-core#onwatchercleanup) <sup class="vt-badge" data-text="3.5+" /> API to register a cleanup function that will be called when the watcher is invalidated and is about to re-run:
 
 <div class="composition-api">
 

From ab41e36c5f1fe06d1fd613ae66376d17e0a5f0b3 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Tue, 3 Sep 2024 21:04:38 +0800
Subject: [PATCH 17/17] Update src/api/application.md

Co-authored-by: Natalia Tepluhina <tarya.se@gmail.com>
---
 src/api/application.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/application.md b/src/api/application.md
index 189422bcb7..2ff3d787fe 100644
--- a/src/api/application.md
+++ b/src/api/application.md
@@ -655,7 +655,7 @@ Force unhandled errors to be thrown in production mode.
 
 - **Details**
 
-  By default, errors thrown inside a Vue application but not explicit handled have different behavior between development and production modes:
+  By default, errors thrown inside a Vue application but not explicitly handled have different behavior between development and production modes:
 
   - In development, the error is thrown and can possibly crash the application. This is to make the error more prominent so that it can be noticed and fixed during development.