docs: update experimental docs (#31388)

docs/1.getting-started/12.upgrade.md

@@ -224,6 +224,31 @@ export default defineNuxtConfig({
 })
 ```
 
+#### Deduplication of Route Metadata
+
+🚦 **Impact Level**: Minimal
+
+##### What Changed
+
+It's possible to set some route metadata using `definePageMeta`, such as the `name`, `path`, and so on. Previously these were available both on the route and on route metadata (for example, `route.name` and `route.meta.name`).
+
+Now, they are only accessible on the route object.
+
+##### Reasons for Change
+
+This is a result of enabling `experimental.scanPageMeta` by default, and is a performance optimization.
+
+##### Migration Steps
+
+The migration should be straightforward:
+
+```diff
+  const route = useRoute()
+  
+- console.log(route.meta.name)
++ console.log(route.name)
+```
+
 #### Normalized Component Names
 
 🚦 **Impact Level**: Moderate

docs/2.guide/3.going-further/1.experimental-features.md

@@ -477,6 +477,84 @@ Alternatively, you can render the template alongside the Nuxt app root by settin
 
 This avoids a white flash when hydrating a client-only page.
 
+## browserDevtoolsTiming
+
+Enables performance markers for Nuxt hooks in browser devtools. This adds performance markers that you can track in the Performance tab of Chromium-based browsers, which is useful for debugging and optimizing performance.
+
+This is enabled by default in development mode. If you need to disable this feature, it is possible to do so:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    browserDevtoolsTiming: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/29922" target="_blank"}
+See PR #29922 for implementation details.
+::
+
+::read-more{icon="i-simple-icons-googlechrome" color="gray" to="https://developer.chrome.com/docs/devtools/performance/extension#tracks" target="_blank"}
+Learn more about Chrome DevTools Performance API.
+::
+
+## debugModuleMutation
+
+Records mutations to `nuxt.options` in module context, helping to debug configuration changes made by modules during the Nuxt initialization phase.
+
+This is enabled by default when `debug` mode is enabled. If you need to disable this feature, it is possible to do so:
+
+To enable it explicitly:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    debugModuleMutation: true
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/30555" target="_blank"}
+See PR #30555 for implementation details.
+::
+
+## lazyHydration
+
+This enables hydration strategies for `<Lazy>` components, which improves performance by deferring hydration of components until they're needed.
+
+Lazy hydration is enabled by default, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    lazyHydration: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="/docs/guide/directory-structure/components#delayed-or-lazy-hydration"}
+Read more about lazy hydration.
+::
+
+## templateImportResolution
+
+Controls how imports in Nuxt templates are resolved. By default, Nuxt attempts to resolve imports in templates relative to the module that added them.
+
+This is enabled by default, so if you're experiencing resolution conflicts in certain environments, you can disable this behavior:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    templateImportResolution: false
+  }
+})
+```
+
+::read-more{icon="i-simple-icons-github" color="gray" to="https://github.com/nuxt/nuxt/pull/31175" target="_blank"}
+See PR #31175 for implementation details.
+::
+
 ## decorators
 
 This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).

packages/schema/src/config/experimental.ts

@@ -464,14 +464,46 @@ export default defineResolvers({
     /**
      * Enable timings for Nuxt application hooks in the performance panel of Chromium-based browsers.
      *
-     * @see [the Chrome DevTools extensibility API](https://developer.chrome.com/docs/devtools/performance/extension#tracks)
+     * This feature adds performance markers for Nuxt hooks, allowing you to track their execution time
+     * in the browser's Performance tab. This is particularly useful for debugging performance issues.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   experimental: {
+     *     // Enable performance markers for Nuxt hooks in browser devtools
+     *     browserDevtoolsTiming: true
+     *   }
+     * })
+     * ```
+     *
+     * @see [PR #29922](https://github.com/nuxt/nuxt/pull/29922)
+     * @see [Chrome DevTools Performance API](https://developer.chrome.com/docs/devtools/performance/extension#tracks)
      */
     browserDevtoolsTiming: {
       $resolve: async (val, get) => typeof val === 'boolean' ? val : await get('dev'),
     },
 
     /**
-     * Record mutations to `nuxt.options` in module context
+     * Record mutations to `nuxt.options` in module context, helping to debug configuration changes
+     * made by modules during the Nuxt initialization phase.
+     *
+     * When enabled, Nuxt will track which modules modify configuration options, making it
+     * easier to trace unexpected configuration changes.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   experimental: {
+     *     // Enable tracking of config mutations by modules
+     *     debugModuleMutation: true
+     *   }
+     * })
+     * ```
+     *
+     * @see [PR #30555](https://github.com/nuxt/nuxt/pull/30555)
      */
     debugModuleMutation: {
       $resolve: async (val, get) => {
@@ -481,6 +513,29 @@ export default defineResolvers({
 
     /**
      * Enable automatic configuration of hydration strategies for `<Lazy>` components.
+     *
+     * This feature intelligently determines when to hydrate lazy components based on
+     * visibility, idle time, or other triggers, improving performance by deferring
+     * hydration of components until they're needed.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   experimental: {
+     *     lazyHydration: true // Enable smart hydration strategies for Lazy components
+     *   }
+     * })
+     *
+     * // In your Vue components
+     * <template>
+     *   <Lazy>
+     *     <ExpensiveComponent />
+     *   </Lazy>
+     * </template>
+     * ```
+     *
+     * @see [PR #26468](https://github.com/nuxt/nuxt/pull/26468)
      */
     lazyHydration: {
       $resolve: (val) => {
@@ -490,6 +545,23 @@ export default defineResolvers({
 
     /**
      * Disable resolving imports into Nuxt templates from the path of the module that added the template.
+     *
+     * By default, Nuxt attempts to resolve imports in templates relative to the module that added them.
+     * Setting this to `false` disables this behavior, which may be useful if you're experiencing
+     * resolution conflicts in certain environments.
+     *
+     * @example
+     * ```ts
+     * // nuxt.config.ts
+     * export default defineNuxtConfig({
+     *   experimental: {
+     *     // Disable template import resolution from module path
+     *     templateImportResolution: false
+     *   }
+     * })
+     * ```
+     *
+     * @see [PR #31175](https://github.com/nuxt/nuxt/pull/31175)
      */
     templateImportResolution: true,
   },