vite-plugin-taro 0.6.2 → 0.6.3

package/README.en.md

@@ -31,12 +31,17 @@ Continue with the [Quick Start guide](https://vpt.js.org/guides/quick-start/).
 
 ## Documentation
 
+- [Quick Start](https://vpt.js.org/guides/quick-start/)
+- [Styles](https://vpt.js.org/guides/styles/)
 - [Automatic subpackages](https://vpt.js.org/guides/automatic-subpackages/)
 - [Native WeChat components](https://vpt.js.org/guides/native-components/)
 - [Hot module replacement](https://vpt.js.org/guides/hot-module-replacement/)
+- [Configuration options](https://vpt.js.org/guides/configuration/)
+- [Conditional compilation](https://vpt.js.org/guides/conditional-directives/)
 - [Skyline mode](https://vpt.js.org/guides/skyline-mode/)
 - [Migrate from Taro CLI](https://vpt.js.org/guides/migrate-from-taro/)
-- [Configuration reference](https://vpt.js.org/guides/configuration/)
+- [Module system](https://vpt.js.org/references/module-system/)
+- [Hot module replacement internals](https://vpt.js.org/references/hmr-implementation/)
 - [Repository management](https://vpt.js.org/references/repository-management/)
 
 ## License

package/README.md

@@ -32,12 +32,17 @@ npm create vite-taro@latest my-app
 
 ## 文档
 
+- [快速开始](https://vpt.js.org/guides/quick-start/)
+- [样式](https://vpt.js.org/guides/styles/)
 - [全自动分包](https://vpt.js.org/guides/automatic-subpackages/)
 - [微信原生组件](https://vpt.js.org/guides/native-components/)
 - [开发者工具热更新](https://vpt.js.org/guides/hot-module-replacement/)
+- [配置选项](https://vpt.js.org/guides/configuration/)
+- [条件编译](https://vpt.js.org/guides/conditional-directives/)
 - [Skyline 模式](https://vpt.js.org/guides/skyline-mode/)
 - [从 Taro CLI 迁移](https://vpt.js.org/guides/migrate-from-taro/)
-- [配置参考](https://vpt.js.org/guides/configuration/)
+- [模块系统](https://vpt.js.org/references/module-system/)
+- [热更新原理](https://vpt.js.org/references/hmr-implementation/)
 - [仓库维护](https://vpt.js.org/references/repository-management/)
 
 ## 许可证

package/dist/node/plugins/wx/dev/plugins.d.ts

@@ -28,18 +28,8 @@ export declare function createWxDevelopmentPlugin(options: VptOptions, applicati
  * only `assets/global.wxss`, which preserves the App heap. The serve-only plugin leaves production output unchanged.
  */
 export declare function removeDevelopmentAppWxss(bundle: Record<string, unknown>): void;
-/** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
-export declare function injectReactRefreshBootstrap(code: string): {
-    code: string;
-    map: null;
-};
-/** Connects the shared WX dev runtime to the application graph's Taro runtime instance. */
-export declare function injectTaroConnection(code: string): {
-    code: string;
-    map: null;
-};
-/** Activates development-only lifecycle handling for one plugin-owned Page capsule. */
-export declare function injectPageHmr(code: string, route: string): {
+/** Injects the retained snapshot at the exact native Page registration edge. */
+export declare function injectPageShellHmr(code: string): {
     code: string;
     map: null;
 };

package/dist/node/plugins/wx/dev/plugins.js

@@ -2,11 +2,10 @@ import { normalizePath, transformWithOxc } from 'vite';
 import { esTarget } from '../../../utils/constant.js';
 import { memoize } from '../../../utils/memoize.js';
 import { normalizeModuleId } from '../../../utils/modules.js';
-import { appCapsulePath, pageCapsulePath, rolldownRuntimeId, taroRuntimePath } from '../module/module.js';
+import { pageShellPath, rolldownRuntimeId } from '../module/module.js';
 import { createWxDevHost } from './dev-host.js';
 import { developmentAppWxssFileName } from './hmr-files.js';
 import { createWxReactRefreshTransforms } from './react-refresh.js';
-const taroRuntimeId = '@tarojs/runtime';
 /** Selects the sole Vite environment that owns the physical Mini Program development project. */
 export function isWxClientEnvironment(environment) {
     return environment.name === 'client';
@@ -28,9 +27,7 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
      */
     let host = null;
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
-    const normalizedAppCapsulePath = normalizePath(appCapsulePath);
-    const normalizedPageCapsulePath = normalizePath(pageCapsulePath);
-    const normalizedTaroRuntimePath = normalizePath(taroRuntimePath);
+    const normalizedPageShellPath = normalizePath(pageShellPath);
     return [
         {
             name: 'vpt:wx-dev',
@@ -107,41 +104,15 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
             }
         },
         {
-            name: 'vpt:wx-react-refresh-bootstrap',
+            name: 'vpt:wx-page-shell-hmr',
             apply: 'serve',
             transform: {
                 order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/app\.js(?:\?|$)/ },
+                filter: { id: /\/runtime\/wx\/native\/page\.js(?:\?|$)/ },
                 handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedAppCapsulePath)
+                    if (normalizeModuleId(id) !== normalizedPageShellPath)
                         return;
-                    return injectReactRefreshBootstrap(code);
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-page-hmr',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/page\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedPageCapsulePath)
-                        return;
-                    return injectPageHmr(code, getPageRoute(id));
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-taro-hmr',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/taro-runtime\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedTaroRuntimePath)
-                        return;
-                    return injectTaroConnection(code);
+                    return injectPageShellHmr(code);
                 }
             }
         },
@@ -166,42 +137,17 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
 export function removeDevelopmentAppWxss(bundle) {
     delete bundle[developmentAppWxssFileName];
 }
-/** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
-export function injectReactRefreshBootstrap(code) {
-    return {
-        code: `import ${JSON.stringify('/@react-refresh')};\n${code}`,
-        map: null
-    };
-}
-/** Connects the shared WX dev runtime to the application graph's Taro runtime instance. */
-export function injectTaroConnection(code) {
-    if (!/\bCurrent\b/.test(code) || !/\bdocument\b/.test(code) || !/\binjectPageInstance\b/.test(code)) {
-        throw new Error('WX Taro runtime must expose Current, document, and injectPageInstance for HMR');
+/** Injects the retained snapshot at the exact native Page registration edge. */
+export function injectPageShellHmr(code) {
+    const registration = 'Page(pageConfig)';
+    if (!code.includes(registration)) {
+        throw new Error('WX native Page shell must register pageConfig');
     }
-    const taroImport = `import { Current as __vptCurrent, document as __vptDocument, injectPageInstance as __vptInjectPageInstance } from ${JSON.stringify(taroRuntimeId)};`;
     return {
-        code: `${code}\n${taroImport}\n__rolldown_runtime__.connectTaro(__vptCurrent, __vptDocument, __vptInjectPageInstance);`,
+        code: code.replace(registration, 'Page(__rolldown_runtime__.injectPageHmr(pageConfig))'),
         map: null
     };
 }
-/** Activates development-only lifecycle handling for one plugin-owned Page capsule. */
-export function injectPageHmr(code, route) {
-    if (!/\bconst\s+config\s*=/.test(code) || !/\bexport\s+default\s+config\b/.test(code)) {
-        throw new Error('WX Page capsule must declare and default-export config before HMR injection');
-    }
-    return {
-        code: `${code}\n__rolldown_runtime__.injectPageHmr(config, ${JSON.stringify(route)});`,
-        map: null
-    };
-}
-/** Reads the stable route carried by every specialized Page capsule ID. */
-function getPageRoute(id) {
-    const queryIndex = id.indexOf('?');
-    const route = queryIndex < 0 ? null : new URLSearchParams(id.slice(queryIndex + 1)).get('route');
-    if (!route)
-        throw new Error(`WX Page capsule is missing its route: ${id}`);
-    return route;
-}
 /*
  * memoize owns a mutable one-entry-by-input cache. The assembled runtime source is byte-identical across complete generations
  * because both the Rolldown base and injected implementation are immutable for the server lifetime. Reusing its lowered result

package/dist/node/plugins/wx/dev/react-refresh.d.ts

@@ -4,8 +4,9 @@ import type { Plugin } from 'vite';
  *
  * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
  * global scope; wx has neither. Each transform adapts one piece of that contract:
- * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ * - the refresh runtime module (id-filtered): the runtime reads and assigns
  *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation;
+ * - React Reconciler: its renderer injection statically depends on the refresh runtime, fixing cold-start order;
  * - react-family modules (filtered on free references): the DevTools hook is read as a free
  *   variable, which the WeChat runtime scope never resolves against `global` — every free
  *   reference becomes an explicit member access;
@@ -13,10 +14,15 @@ import type { Plugin } from 'vite';
  *   needed because the transform generates local wrappers over the imported refresh
  *   runtime, so the guard that checks for the global is removed.
  *
- * Each transform's filter is its routing: the three domains are disjoint, so a module is
- * transformed by at most one of them, and modules outside all three never reach a handler.
+ * Filters route every adaptation directly. The Reconciler intentionally receives the renderer dependency first and the
+ * global-hook rewrite second; modules outside these explicit domains never reach a handler.
  */
 export declare function createWxReactRefreshTransforms(): Plugin[];
+/** Makes renderer hook injection statically depend on the refresh runtime. */
+export declare function injectReactRefreshRendererDependency(code: string): {
+    code: string;
+    map: null;
+};
 export declare function transformRefreshRuntime({ code, id }: {
     code: string;
     id: string;

package/dist/node/plugins/wx/dev/react-refresh.js

@@ -1,6 +1,8 @@
 import { isReferenceIdentifier } from 'oxc-walker';
 import { memoize } from '../../../utils/memoize.js';
+import { normalizeModuleId } from '../../../utils/modules.js';
 import { transformWithOxcWalker } from '../../../utils/oxc-transform.js';
+import { reactReconcilerRoot } from '../module/module.js';
 /** The React DevTools hook protocol name; free references must target `global` in wx. */
 const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__';
 /**
@@ -10,7 +12,7 @@ const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__';
  * - `__getReactRefreshIgnoredExports` is an optional extension point read while validating a refresh boundary.
  *   Leaving that read on the nonexistent `window` crashes every update validation pass.
  *
- * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the vendored runtime
+ * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the refresh runtime
  * gains new code. Any future React Refresh protocol addition therefore requires a deliberate compatibility decision.
  */
 const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__getReactRefreshIgnoredExports'];
@@ -19,8 +21,9 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *
  * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
  * global scope; wx has neither. Each transform adapts one piece of that contract:
- * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ * - the refresh runtime module (id-filtered): the runtime reads and assigns
  *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation;
+ * - React Reconciler: its renderer injection statically depends on the refresh runtime, fixing cold-start order;
  * - react-family modules (filtered on free references): the DevTools hook is read as a free
  *   variable, which the WeChat runtime scope never resolves against `global` — every free
  *   reference becomes an explicit member access;
@@ -28,8 +31,8 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *   needed because the transform generates local wrappers over the imported refresh
  *   runtime, so the guard that checks for the global is removed.
  *
- * Each transform's filter is its routing: the three domains are disjoint, so a module is
- * transformed by at most one of them, and modules outside all three never reach a handler.
+ * Filters route every adaptation directly. The Reconciler intentionally receives the renderer dependency first and the
+ * global-hook rewrite second; modules outside these explicit domains never reach a handler.
  */
 export function createWxReactRefreshTransforms() {
     return [
@@ -38,13 +41,27 @@ export function createWxReactRefreshTransforms() {
             apply: 'serve',
             transform: {
                 order: 'post',
-                // The vendored refresh runtime module; id-filtered, so no code scan.
+                // The refresh runtime module is id-filtered, so no code scan is needed.
                 filter: { id: /^\/@react-refresh(?:\?|$)/ },
                 handler(code, id) {
                     return fixRefreshRuntime({ code, id });
                 }
             }
         },
+        {
+            name: 'vpt:wx-react-refresh-renderer-dependency',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                filter: { id: /\/react-reconciler\/cjs\/react-reconciler\.development\.js(?:\?|$)/ },
+                handler(code, id) {
+                    const rendererId = `${reactReconcilerRoot}/cjs/react-reconciler.development.js`;
+                    if (normalizeModuleId(id) !== rendererId)
+                        return;
+                    return injectReactRefreshRendererDependency(code);
+                }
+            }
+        },
         {
             name: 'vpt:wx-react-devtools-hook',
             apply: 'serve',
@@ -86,7 +103,8 @@ export function createWxReactRefreshTransforms() {
  * The protocol name is unique, but only reference identifiers are rewritten. Declaration
  * keys and explicit members such as `global.__REACT_DEVTOOLS_GLOBAL_HOOK__` must remain
  * untouched; rewriting those would either produce invalid syntax or double-prefix the hook.
- * The eagerly evaluated refresh runtime creates the hook on `global` before the renderer loads.
+ * The Reconciler's injected static dependency orders hook injection before renderer initialization independently of Rolldown's
+ * final chunking decision.
  */
 function createReactDevtoolsHookVisitor(editor) {
     return function enter(node, parent) {
@@ -133,7 +151,7 @@ function createRefreshRuntimeVisitor(editor) {
             node.property.type === 'Identifier' &&
             refreshRuntimeWindowGlobals.some((globalName) => globalName === node.property.name)) {
             // `global` is the shared wx App heap used by the dev runtime and hook injection. Only
-            // replacing the object range preserves the vendored runtime byte-for-byte otherwise
+            // replacing the object range preserves the upstream runtime byte-for-byte otherwise
             // and prevents unrelated `window` expressions from being silently adapted.
             editor.overwrite(node.object.start, node.object.end, 'global');
         }
@@ -169,6 +187,16 @@ function createRefreshPreambleGuardVisitor(editor) {
         this.skip();
     };
 }
+/** Makes renderer hook injection statically depend on the refresh runtime. */
+export function injectReactRefreshRendererDependency(code) {
+    if (!/\bhook\.inject\(internals\)/.test(code)) {
+        throw new Error('React Reconciler must inject its renderer into the DevTools hook');
+    }
+    return {
+        code: `import '/@react-refresh'\n${code}`,
+        map: null
+    };
+}
 export function transformRefreshRuntime({ code, id }) {
     return transformWithOxcWalker({
         code,

package/dist/node/plugins/wx/dev/wx-dev-options.js

@@ -105,7 +105,7 @@ function ensureSingleOutput(rolldownOptions) {
 /**
  * Prepends entry banners after Rolldown's analysis so their native requires remain physical dependencies rather than chunk
  * graph edges. The App initializes the runtime identity, while every Page explicitly applies the watched patch data before its
- * capsule import continues.
+ * native Page registration.
  */
 function createEntryBanner(pageFiles) {
     return (chunk) => {
@@ -114,8 +114,7 @@ function createEntryBanner(pageFiles) {
         }
         if (pageFiles.has(chunk.name)) {
             const patchesPath = path.posix.relative(path.posix.dirname(chunk.fileName), 'hmr/patches.js');
-            const route = chunk.name.slice(0, -'.js'.length);
-            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'), ${JSON.stringify(route)});\n`;
+            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'));\n`;
         }
         return '';
     };

package/dist/node/plugins/wx/resolve/resolver.js

@@ -3,11 +3,11 @@ import { normalizeModuleId, resolveAppComponentPath, resolvePageComponentPath }
 import { createAppConfig } from '../../../utils/project-config.js';
 import { appComponentId } from '../../client/constant.js';
 import { appCapsulePath, appShellFileName, appShellPath, bootstrapPath, componentCapsulePath, componentShellFileName, componentShellPath, pageCapsuleId, pageCapsulePath, pageComponentId, pageShellPath, transportPath, vitePreloadId } from '../module/module.js';
-import { specializeBootstrap } from './specialize-bootstrap.js';
+import { specializeAppCapsule } from './specialize-app-capsule.js';
 import { specializePageCapsule } from './specialize-page-capsule.js';
 /** Creates the resolver and source specializer for the wx module graph. */
 export function createResolver(options) {
-    const normalizedBootstrapPath = normalizePath(bootstrapPath);
+    const normalizedAppCapsulePath = normalizePath(appCapsulePath);
     const normalizedPageCapsulePath = normalizePath(pageCapsulePath);
     // Construct output input and application traversal roots together once so style order cannot drift from route order.
     const entryGraph = createEntryGraph(options.pages);
@@ -42,8 +42,8 @@ export function createResolver(options) {
         },
         specialize(code, id, sourcemap = true) {
             const normalizedId = normalizeModuleId(id);
-            if (normalizedId === normalizedBootstrapPath) {
-                return specializeBootstrap({ code, id, appConfig: createAppConfig(options), sourcemap });
+            if (normalizedId === normalizedAppCapsulePath) {
+                return specializeAppCapsule({ code, id, appConfig: createAppConfig(options), sourcemap });
             }
             if (normalizedId === normalizedPageCapsulePath) {
                 return specializePageCapsule({

package/dist/node/plugins/wx/resolve/{specialize-bootstrap.d.ts → specialize-app-capsule.d.ts}

@@ -1,7 +1,7 @@
 import type { VptJsonObject } from '../../../../options.ts';
 import { type AstTransformResult } from '../../../utils/transform.ts';
-/** Specializes the amphibious bootstrap with the shared App configuration. */
-export declare function specializeBootstrap({ code, id, appConfig, sourcemap }: {
+/** Specializes the App capsule with its normalized native configuration. */
+export declare function specializeAppCapsule({ code, id, appConfig, sourcemap }: {
     code: string;
     id: string;
     appConfig: VptJsonObject;

package/dist/node/plugins/wx/resolve/{specialize-bootstrap.js → specialize-app-capsule.js}

@@ -1,8 +1,8 @@
 import * as types from '@babel/types';
 import { replaceWithAst } from '../../../utils/transform.js';
 const appConfigPlaceholder = '__VPT_APP_CONFIG__';
-/** Specializes the amphibious bootstrap with the shared App configuration. */
-export function specializeBootstrap({ code, id, appConfig, sourcemap = true }) {
+/** Specializes the App capsule with its normalized native configuration. */
+export function specializeAppCapsule({ code, id, appConfig, sourcemap = true }) {
     return replaceWithAst(code, id, {
         [appConfigPlaceholder]: types.valueToNode(appConfig)
     }, sourcemap);

package/dist/runtime/wx/amphibious/bootstrap.d.ts

@@ -1,4 +1,2 @@
 import '../systemjs/system-core.js';
-/** Shares one App configuration object between the specialized bootstrap and App capsule. */
-export declare const appConfig: Record<string, unknown>;
 export declare const __vitePreload: <Value>(load: () => Value) => Value;

package/dist/runtime/wx/amphibious/bootstrap.js

@@ -1,8 +1,6 @@
 // Install the minimal SystemJS loader and its synchronous-import extension before any native entry requests a capsule.
 import '../systemjs/system-core.js';
 import { transport } from './transport.js';
-/** Shares one App configuration object between the specialized bootstrap and App capsule. */
-export const appConfig = __VPT_APP_CONFIG__;
 // WX has no modulepreload transport. Genuine application import() boundaries retain System.import() and may load
 // asynchronous subpackage or top-level-await graphs through this identity wrapper.
 export const __vitePreload = (load) => load();

package/dist/runtime/wx/capsule/app.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
-export default _default;
+declare const config: any;
+export default config;

package/dist/runtime/wx/capsule/app.js

@@ -1,7 +1,7 @@
 // biome-ignore assist/source/organizeImports: Taro must initialize before the App component.
 import { createReactApp, ReactDOM } from './taro-runtime.js';
 import React from 'react';
-import { appConfig } from '../amphibious/bootstrap.js';
 // @ts-expect-error: The wx build resolves this private App component.
 import AppComponent from '\0vpt:app-component';
-export default createReactApp(AppComponent, React, ReactDOM, appConfig);
+const config = createReactApp(AppComponent, React, ReactDOM, __VPT_APP_CONFIG__);
+export default config;

package/dist/runtime/wx/dev/dev-runtime.js

@@ -5,16 +5,13 @@
 // The `DevRuntime` base class is injected into the chunk by Rolldown's dev-mode
 // transform, so the WX host only extends it.
 //
-// Every Page explicitly passes the inert hmr/patches.js export here before importing its capsule. The runtime applies that
+// Every Page explicitly passes the inert hmr/patches.js export here before native Page registration. The runtime applies that
 // cumulative suffix synchronously, reports its successful application frontier, and ignores sequences replayed by other Pages.
-/** Forwards a native lifecycle with its original Page receiver. */
-function forward(handler, receiver, args) {
+const pageHmrStateKey = Symbol('vpt.pageHmrState');
+/** Calls a native lifecycle with the same Page bound to `this` and the same arguments. */
+function forward(handler, page, args) {
     if (typeof handler === 'function')
-        handler.apply(receiver, args);
-}
-/** Narrows the untyped element returned across the Taro connection boundary. */
-function isTaroRoot(value) {
-    return typeof value === 'object' && value !== null && 'ctx' in value;
+        handler.apply(page, args);
 }
 /** Shared no-op CSS contract because physical rebuilds replace styles wholesale. */
 const hotContextInternals = Object.freeze({
@@ -168,92 +165,76 @@ class WxDevRuntime extends DevRuntime {
             return;
         this.session = { ...info, appliedSeq: 0 };
     }
-    /**
-     * One-shot bridge to the application's Taro singleton. It cannot be imported into this
-     * separately bundled global runtime without creating a second Taro identity. Undefined
-     * only before the serve-only facade connection; route transactions share its lifetime.
-     */
-    taro;
-    /** Connects HMR to the same Taro singleton used by the application module graph. */
-    connectTaro(current, document, injectPageInstance) {
-        if (this.taro) {
-            return;
+    /** Tracks the mounted native Page and prepares its static config for HMR re-registration. */
+    injectPageHmr(config) {
+        const existingState = config[pageHmrStateKey];
+        if (existingState) {
+            const mountedPage = existingState.mountedPage;
+            /*
+             * The static config can outlive a native Page instance. Before its first ordinary onLoad, or after a real onUnload,
+             * there is no mounted Page or current view-model to carry into another registration. Leave the lifecycle gate
+             * unarmed and preserve the config's existing initial data so a future real onLoad still enters Taro normally.
+             */
+            if (!mountedPage) {
+                return config;
+            }
+            /*
+             * Arm the lifecycle wrappers on this exact static config before it is passed back to `Page(config)`. DevTools then
+             * triggers an unload/load/show sequence for that native re-registration: unload and load observe `true` and return
+             * before entering Taro, preserving the mounted React tree and its original Page connection; show consumes the
+             * one-shot gate by restoring `false`. Ordinary navigation never enters this branch, and every Page config owns an
+             * independent state object, so no route map, global phase, or Page identity comparison participates in the decision.
+             */
+            existingState.isReregistering = true;
+            /*
+             * `Page(config)` reads `config.data` as the initial native view-model for this registration. Supplying the mounted
+             * Page's latest data before that call prevents the temporary Page used for re-registration callbacks from starting
+             * empty. This is an O(1) reference assignment in vpt: it does not clone the recursive data tree, call `setData`, move
+             * React state, or rebind Taro. The ordinary Taro lifecycle remains suppressed until re-registration onShow, so its
+             * React tree and output connection stay attached to `mountedPage`; every later registration reads its latest data.
+             */
+            config.data = mountedPage.data;
+            return config;
         }
-        this.taro = {
-            current,
-            document,
-            injectPageInstance,
-            pageReplacements: new Map()
-        };
-    }
-    /** Injects snapshot-preserving behavior into one route-specific Taro Page configuration. */
-    injectPageHmr(config, route) {
         const originalOnUnload = config.onUnload;
         const originalOnLoad = config.onLoad;
         const originalOnShow = config.onShow;
-        const runtime = this;
+        const state = {
+            isReregistering: false,
+            mountedPage: undefined
+        };
+        /*
+         * Attach the one mutable HMR state object to this exact static config. The lifecycle wrappers below close over the same
+         * object, while a later `injectPageHmr(config)` call finds it through the symbol and knows wrapping is already complete.
+         * A symbol cannot collide with WeChat or Taro's string-named Page options, and config-local ownership avoids route maps,
+         * a runtime-wide WeakMap, or state shared by two Page configs. The state becomes unreachable together with the config.
+         */
+        config[pageHmrStateKey] = state;
         config.onUnload = function (...args) {
-            const taro = runtime.requireTaro();
-            if (taro.pageReplacements.has(route)) {
-                taro.pageReplacements.set(route, {
-                    $taroPath: this.$taroPath,
-                    $taroParams: this.$taroParams,
-                    // WeChat owns this serializable view-model. Keeping its reference is O(1),
-                    // unlike cloning the complete recursive projection before every edit.
-                    data: this.data
-                });
+            if (state.isReregistering) {
                 return;
             }
             forward(originalOnUnload, this, args);
+            state.mountedPage = undefined;
         };
         config.onLoad = function (...args) {
-            const taro = runtime.requireTaro();
-            const snapshot = taro.pageReplacements.get(route);
-            if (snapshot) {
-                // Replace the transaction before native work so exceptions cannot retain the
-                // large data snapshot while the route waits for its synthetic onShow.
-                taro.pageReplacements.set(route, null);
-                // Snapshot paint is the first bridge operation and removes the empty-page gap.
-                this.setData(snapshot.data);
-                this.$taroPath = snapshot.$taroPath;
-                this.$taroParams = snapshot.$taroParams;
-                runtime.bindPage(this, snapshot.$taroPath);
+            if (state.isReregistering) {
                 return;
             }
             forward(originalOnLoad, this, args);
+            state.mountedPage = this;
         };
         config.onShow = function (...args) {
-            if (runtime.requireTaro().pageReplacements.delete(route)) {
-                // Synthetic shows must not repeat requests or reset application state.
+            if (state.isReregistering) {
+                state.isReregistering = false;
                 return;
             }
             forward(originalOnShow, this, args);
         };
+        return config;
     }
-    /** Returns the Taro connection or fails at the first incorrectly ordered use. */
-    requireTaro() {
-        if (!this.taro)
-            throw new Error('[vpt] WX HMR used before the Taro runtime was connected');
-        return this.taro;
-    }
-    /** Returns a retained Taro root after normal Page mount has created it. */
-    findRoot(path) {
-        const root = this.requireTaro().document.getElementById(path);
-        return isTaroRoot(root) ? root : undefined;
-    }
-    /** Rebinds a retained Taro tree to one replacement native Page without repainting. */
-    bindPage(instance, path) {
-        const taro = this.requireTaro();
-        taro.injectPageInstance(instance, path);
-        taro.current.page = instance;
-        const pageElement = this.findRoot(path);
-        if (!pageElement) {
-            throw new Error(`[vpt] retained Taro page not found: ${path}`);
-        }
-        pageElement.ctx = instance;
-    }
-    /** Applies one Page-delivered payload and arms its route for native replacement. */
-    applyPatches(payload, route) {
+    /** Applies one Page-delivered payload before its native shell registers the static route configuration. */
+    applyPatches(payload) {
         // The initial physical dependency exports undefined until the host has a patch range.
         if (!payload)
             return;
@@ -262,11 +243,6 @@ class WxDevRuntime extends DevRuntime {
             console.warn('[vpt] patches for a stale build');
             return;
         }
-        // A replayed payload still causes DevTools to replace this physical Page. Arm the
-        // route independently of whether this App heap already applied its patch sequence.
-        if (route) {
-            this.requireTaro().pageReplacements.set(route, null);
-        }
         // Apply synchronously: the page's imports below the require resolve against the
         // freshly registered modules, so the re-executed Page evaluates with the new code.
         if (this.applyPatchBatch(session, payload.patches)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -75,8 +75,8 @@
     "rxjs": "^7.8.2",
     "tailwindcss": "^4.3.3",
     "weapp-tailwindcss": "^5.2.11",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.2",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.2"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.3",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/plugins/wx/dev/plugins.ts

@@ -3,13 +3,11 @@ import type { VptOptions } from '../../../../options.ts'
 import { esTarget } from '../../../utils/constant.ts'
 import { memoize } from '../../../utils/memoize.ts'
 import { normalizeModuleId } from '../../../utils/modules.ts'
-import { appCapsulePath, pageCapsulePath, rolldownRuntimeId, taroRuntimePath } from '../module/module.ts'
+import { pageShellPath, rolldownRuntimeId } from '../module/module.ts'
 import { createWxDevHost, type WxDevHost } from './dev-host.ts'
 import { developmentAppWxssFileName } from './hmr-files.ts'
 import { createWxReactRefreshTransforms } from './react-refresh.ts'
 
-const taroRuntimeId = '@tarojs/runtime'
-
 /** Selects the sole Vite environment that owns the physical Mini Program development project. */
 export function isWxClientEnvironment(environment: Readonly<{ name: string }>): boolean {
     return environment.name === 'client'
@@ -32,9 +30,7 @@ export function createWxDevelopmentPlugin(options: VptOptions, applicationEntryI
      */
     let host: WxDevHost | null = null
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
-    const normalizedAppCapsulePath = normalizePath(appCapsulePath)
-    const normalizedPageCapsulePath = normalizePath(pageCapsulePath)
-    const normalizedTaroRuntimePath = normalizePath(taroRuntimePath)
+    const normalizedPageShellPath = normalizePath(pageShellPath)
 
     return [
         {
@@ -116,38 +112,14 @@ export function createWxDevelopmentPlugin(options: VptOptions, applicationEntryI
             }
         },
         {
-            name: 'vpt:wx-react-refresh-bootstrap',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/app\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedAppCapsulePath) return
-                    return injectReactRefreshBootstrap(code)
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-page-hmr',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/page\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedPageCapsulePath) return
-                    return injectPageHmr(code, getPageRoute(id))
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-taro-hmr',
+            name: 'vpt:wx-page-shell-hmr',
             apply: 'serve',
             transform: {
                 order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/taro-runtime\.js(?:\?|$)/ },
+                filter: { id: /\/runtime\/wx\/native\/page\.js(?:\?|$)/ },
                 handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedTaroRuntimePath) return
-                    return injectTaroConnection(code)
+                    if (normalizeModuleId(id) !== normalizedPageShellPath) return
+                    return injectPageShellHmr(code)
                 }
             }
         },
@@ -174,48 +146,19 @@ export function removeDevelopmentAppWxss(bundle: Record<string, unknown>): void
     delete bundle[developmentAppWxssFileName]
 }
 
-/** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
-export function injectReactRefreshBootstrap(code: string): { code: string; map: null } {
-    return {
-        code: `import ${JSON.stringify('/@react-refresh')};\n${code}`,
-        map: null
-    }
-}
-
-/** Connects the shared WX dev runtime to the application graph's Taro runtime instance. */
-export function injectTaroConnection(code: string): { code: string; map: null } {
-    if (!/\bCurrent\b/.test(code) || !/\bdocument\b/.test(code) || !/\binjectPageInstance\b/.test(code)) {
-        throw new Error('WX Taro runtime must expose Current, document, and injectPageInstance for HMR')
-    }
-
-    const taroImport = `import { Current as __vptCurrent, document as __vptDocument, injectPageInstance as __vptInjectPageInstance } from ${JSON.stringify(taroRuntimeId)};`
-
-    return {
-        code: `${code}\n${taroImport}\n__rolldown_runtime__.connectTaro(__vptCurrent, __vptDocument, __vptInjectPageInstance);`,
-        map: null
-    }
-}
-
-/** Activates development-only lifecycle handling for one plugin-owned Page capsule. */
-export function injectPageHmr(code: string, route: string): { code: string; map: null } {
-    if (!/\bconst\s+config\s*=/.test(code) || !/\bexport\s+default\s+config\b/.test(code)) {
-        throw new Error('WX Page capsule must declare and default-export config before HMR injection')
+/** Injects the retained snapshot at the exact native Page registration edge. */
+export function injectPageShellHmr(code: string): { code: string; map: null } {
+    const registration = 'Page(pageConfig)'
+    if (!code.includes(registration)) {
+        throw new Error('WX native Page shell must register pageConfig')
     }
 
     return {
-        code: `${code}\n__rolldown_runtime__.injectPageHmr(config, ${JSON.stringify(route)});`,
+        code: code.replace(registration, 'Page(__rolldown_runtime__.injectPageHmr(pageConfig))'),
         map: null
     }
 }
 
-/** Reads the stable route carried by every specialized Page capsule ID. */
-function getPageRoute(id: string): string {
-    const queryIndex = id.indexOf('?')
-    const route = queryIndex < 0 ? null : new URLSearchParams(id.slice(queryIndex + 1)).get('route')
-    if (!route) throw new Error(`WX Page capsule is missing its route: ${id}`)
-    return route
-}
-
 /*
  * memoize owns a mutable one-entry-by-input cache. The assembled runtime source is byte-identical across complete generations
  * because both the Rolldown base and injected implementation are immutable for the server lifetime. Reusing its lowered result

package/src/node/plugins/wx/dev/react-refresh.ts

@@ -2,7 +2,9 @@ import { isReferenceIdentifier, type WalkerEnter } from 'oxc-walker'
 import type { RolldownMagicString } from 'rolldown'
 import type { Plugin } from 'vite'
 import { memoize } from '../../../utils/memoize.ts'
+import { normalizeModuleId } from '../../../utils/modules.ts'
 import { transformWithOxcWalker } from '../../../utils/oxc-transform.ts'
+import { reactReconcilerRoot } from '../module/module.ts'
 
 /** The React DevTools hook protocol name; free references must target `global` in wx. */
 const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__'
@@ -14,7 +16,7 @@ const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__'
  * - `__getReactRefreshIgnoredExports` is an optional extension point read while validating a refresh boundary.
  *   Leaving that read on the nonexistent `window` crashes every update validation pass.
  *
- * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the vendored runtime
+ * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the refresh runtime
  * gains new code. Any future React Refresh protocol addition therefore requires a deliberate compatibility decision.
  */
 const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__getReactRefreshIgnoredExports'] as const
@@ -24,8 +26,9 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *
  * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
  * global scope; wx has neither. Each transform adapts one piece of that contract:
- * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ * - the refresh runtime module (id-filtered): the runtime reads and assigns
  *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation;
+ * - React Reconciler: its renderer injection statically depends on the refresh runtime, fixing cold-start order;
  * - react-family modules (filtered on free references): the DevTools hook is read as a free
  *   variable, which the WeChat runtime scope never resolves against `global` — every free
  *   reference becomes an explicit member access;
@@ -33,8 +36,8 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *   needed because the transform generates local wrappers over the imported refresh
  *   runtime, so the guard that checks for the global is removed.
  *
- * Each transform's filter is its routing: the three domains are disjoint, so a module is
- * transformed by at most one of them, and modules outside all three never reach a handler.
+ * Filters route every adaptation directly. The Reconciler intentionally receives the renderer dependency first and the
+ * global-hook rewrite second; modules outside these explicit domains never reach a handler.
  */
 export function createWxReactRefreshTransforms(): Plugin[] {
     return [
@@ -43,13 +46,26 @@ export function createWxReactRefreshTransforms(): Plugin[] {
             apply: 'serve',
             transform: {
                 order: 'post',
-                // The vendored refresh runtime module; id-filtered, so no code scan.
+                // The refresh runtime module is id-filtered, so no code scan is needed.
                 filter: { id: /^\/@react-refresh(?:\?|$)/ },
                 handler(code, id) {
                     return fixRefreshRuntime({ code, id })
                 }
             }
         },
+        {
+            name: 'vpt:wx-react-refresh-renderer-dependency',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                filter: { id: /\/react-reconciler\/cjs\/react-reconciler\.development\.js(?:\?|$)/ },
+                handler(code, id) {
+                    const rendererId = `${reactReconcilerRoot}/cjs/react-reconciler.development.js`
+                    if (normalizeModuleId(id) !== rendererId) return
+                    return injectReactRefreshRendererDependency(code)
+                }
+            }
+        },
         {
             name: 'vpt:wx-react-devtools-hook',
             apply: 'serve',
@@ -92,7 +108,8 @@ export function createWxReactRefreshTransforms(): Plugin[] {
  * The protocol name is unique, but only reference identifiers are rewritten. Declaration
  * keys and explicit members such as `global.__REACT_DEVTOOLS_GLOBAL_HOOK__` must remain
  * untouched; rewriting those would either produce invalid syntax or double-prefix the hook.
- * The eagerly evaluated refresh runtime creates the hook on `global` before the renderer loads.
+ * The Reconciler's injected static dependency orders hook injection before renderer initialization independently of Rolldown's
+ * final chunking decision.
  */
 function createReactDevtoolsHookVisitor(editor: RolldownMagicString): WalkerEnter {
     return function enter(node, parent) {
@@ -146,7 +163,7 @@ function createRefreshRuntimeVisitor(editor: RolldownMagicString): WalkerEnter {
             refreshRuntimeWindowGlobals.some((globalName) => globalName === node.property.name)
         ) {
             // `global` is the shared wx App heap used by the dev runtime and hook injection. Only
-            // replacing the object range preserves the vendored runtime byte-for-byte otherwise
+            // replacing the object range preserves the upstream runtime byte-for-byte otherwise
             // and prevents unrelated `window` expressions from being silently adapted.
             editor.overwrite(node.object.start, node.object.end, 'global')
         }
@@ -187,6 +204,18 @@ function createRefreshPreambleGuardVisitor(editor: RolldownMagicString): WalkerE
     }
 }
 
+/** Makes renderer hook injection statically depend on the refresh runtime. */
+export function injectReactRefreshRendererDependency(code: string): { code: string; map: null } {
+    if (!/\bhook\.inject\(internals\)/.test(code)) {
+        throw new Error('React Reconciler must inject its renderer into the DevTools hook')
+    }
+
+    return {
+        code: `import '/@react-refresh'\n${code}`,
+        map: null
+    }
+}
+
 export function transformRefreshRuntime({ code, id }: { code: string; id: string }) {
     return transformWithOxcWalker({
         code,

package/src/node/plugins/wx/dev/wx-dev-options.ts

@@ -145,7 +145,7 @@ function ensureSingleOutput(rolldownOptions: BundledDevRolldownOptions): OutputO
 /**
  * Prepends entry banners after Rolldown's analysis so their native requires remain physical dependencies rather than chunk
  * graph edges. The App initializes the runtime identity, while every Page explicitly applies the watched patch data before its
- * capsule import continues.
+ * native Page registration.
  */
 function createEntryBanner(pageFiles: ReadonlySet<string>): (chunk: { name: string; fileName: string }) => string {
     return (chunk) => {
@@ -154,8 +154,7 @@ function createEntryBanner(pageFiles: ReadonlySet<string>): (chunk: { name: stri
         }
         if (pageFiles.has(chunk.name)) {
             const patchesPath = path.posix.relative(path.posix.dirname(chunk.fileName), 'hmr/patches.js')
-            const route = chunk.name.slice(0, -'.js'.length)
-            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'), ${JSON.stringify(route)});\n`
+            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'));\n`
         }
         return ''
     }

package/src/node/plugins/wx/resolve/resolver.ts

@@ -18,7 +18,7 @@ import {
     transportPath,
     vitePreloadId
 } from '../module/module.ts'
-import { specializeBootstrap } from './specialize-bootstrap.ts'
+import { specializeAppCapsule } from './specialize-app-capsule.ts'
 import { specializePageCapsule } from './specialize-page-capsule.ts'
 
 /** Resolves one exact plugin-private ID using its importer and configured project root. */
@@ -26,7 +26,7 @@ type PrivateIdResolver = (importer: string | undefined, projectRoot: string) =>
 
 /** Creates the resolver and source specializer for the wx module graph. */
 export function createResolver(options: VptOptions) {
-    const normalizedBootstrapPath = normalizePath(bootstrapPath)
+    const normalizedAppCapsulePath = normalizePath(appCapsulePath)
     const normalizedPageCapsulePath = normalizePath(pageCapsulePath)
 
     // Construct output input and application traversal roots together once so style order cannot drift from route order.
@@ -70,8 +70,8 @@ export function createResolver(options: VptOptions) {
         specialize(code: string, id: string, sourcemap = true) {
             const normalizedId = normalizeModuleId(id)
 
-            if (normalizedId === normalizedBootstrapPath) {
-                return specializeBootstrap({ code, id, appConfig: createAppConfig(options), sourcemap })
+            if (normalizedId === normalizedAppCapsulePath) {
+                return specializeAppCapsule({ code, id, appConfig: createAppConfig(options), sourcemap })
             }
 
             if (normalizedId === normalizedPageCapsulePath) {

package/src/node/plugins/wx/resolve/{specialize-bootstrap.ts → specialize-app-capsule.ts}

@@ -4,8 +4,8 @@ import { type AstTransformResult, replaceWithAst } from '../../../utils/transfor
 
 const appConfigPlaceholder = '__VPT_APP_CONFIG__'
 
-/** Specializes the amphibious bootstrap with the shared App configuration. */
-export function specializeBootstrap({
+/** Specializes the App capsule with its normalized native configuration. */
+export function specializeAppCapsule({
     code,
     id,
     appConfig,

package/src/runtime/wx/amphibious/bootstrap.ts

@@ -2,11 +2,6 @@
 import '../systemjs/system-core.js'
 import { transport } from './transport.ts'
 
-declare const __VPT_APP_CONFIG__: Record<string, unknown>
-
-/** Shares one App configuration object between the specialized bootstrap and App capsule. */
-export const appConfig = __VPT_APP_CONFIG__
-
 // WX has no modulepreload transport. Genuine application import() boundaries retain System.import() and may load
 // asynchronous subpackage or top-level-await graphs through this identity wrapper.
 export const __vitePreload = <Value>(load: () => Value): Value => load()

package/src/runtime/wx/capsule/app.ts

@@ -1,9 +1,12 @@
 // biome-ignore assist/source/organizeImports: Taro must initialize before the App component.
 import { createReactApp, ReactDOM } from './taro-runtime.ts'
 import React from 'react'
-import { appConfig } from '../amphibious/bootstrap.ts'
 
 // @ts-expect-error: The wx build resolves this private App component.
 import AppComponent from '\0vpt:app-component'
 
-export default createReactApp(AppComponent, React, ReactDOM, appConfig)
+declare const __VPT_APP_CONFIG__: Record<string, unknown>
+
+const config = createReactApp(AppComponent, React, ReactDOM, __VPT_APP_CONFIG__)
+
+export default config

package/src/runtime/wx/dev/dev-runtime.ts

@@ -5,7 +5,7 @@
 // The `DevRuntime` base class is injected into the chunk by Rolldown's dev-mode
 // transform, so the WX host only extends it.
 //
-// Every Page explicitly passes the inert hmr/patches.js export here before importing its capsule. The runtime applies that
+// Every Page explicitly passes the inert hmr/patches.js export here before native Page registration. The runtime applies that
 // cumulative suffix synchronously, reports its successful application frontier, and ignores sequences replayed by other Pages.
 
 import type { DevRuntime as RolldownDevRuntime } from 'rolldown/experimental/runtime-types'
@@ -54,54 +54,30 @@ type HmrUpdate = Readonly<{
 
 type AcceptCallback = (moduleExports: unknown) => void
 
-type PageSnapshot = Readonly<{
-    $taroPath: string
-    $taroParams: Record<string, unknown>
-    data: Record<string, unknown>
-}>
-
 type NativePage = {
-    $taroPath: string
-    $taroParams: Record<string, unknown>
     data: Record<string, unknown>
-    setData(data: Record<string, unknown>): void
+}
+
+const pageHmrStateKey: unique symbol = Symbol('vpt.pageHmrState')
+
+type PageHmrState = {
+    /** True only across the unload/load/show sequence triggered by one native re-registration. */
+    isReregistering: boolean
+    /** The Page bound to `this` by ordinary onLoad, retained until ordinary onUnload. */
+    mountedPage: NativePage | undefined
 }
 
 type HmrPageConfig = {
+    data: Record<string, unknown>
     onUnload?: unknown
     onLoad?: unknown
     onShow?: unknown
+    [pageHmrStateKey]?: PageHmrState
 }
 
-type TaroRoot = {
-    ctx: unknown
-}
-
-/** Immutable bridge references plus replacement transactions owned by one Taro singleton. */
-type TaroState = {
-    /** Taro's existing current-page source of truth; replacement onLoad switches its receiver. */
-    readonly current: { page: NativePage | null }
-    /** Taro's virtual document, used to find the retained root by its preserved unique path. */
-    readonly document: { getElementById(path: string): unknown }
-    /** Replaces Taro's native lifecycle receiver without remounting the retained React subtree. */
-    readonly injectPageInstance: (instance: unknown, path: string) => void
-    /**
-     * Short-lived route transactions. Absence means ordinary lifecycle; null means armed
-     * before onUnload or snapshot-consumed before onShow; a snapshot exists only between
-     * replacement onUnload and onLoad. The large data reference is therefore released in
-     * onLoad, while the null marker remains just long enough to suppress synthetic onShow.
-     */
-    readonly pageReplacements: Map<string, PageSnapshot | null>
-}
-
-/** Forwards a native lifecycle with its original Page receiver. */
-function forward(handler: unknown, receiver: unknown, args: unknown[]): void {
-    if (typeof handler === 'function') handler.apply(receiver, args)
-}
-
-/** Narrows the untyped element returned across the Taro connection boundary. */
-function isTaroRoot(value: unknown): value is TaroRoot {
-    return typeof value === 'object' && value !== null && 'ctx' in value
+/** Calls a native lifecycle with the same Page bound to `this` and the same arguments. */
+function forward(handler: unknown, page: unknown, args: unknown[]): void {
+    if (typeof handler === 'function') handler.apply(page, args)
 }
 
 /** Shared no-op CSS contract because physical rebuilds replace styles wholesale. */
@@ -285,109 +261,90 @@ class WxDevRuntime extends DevRuntime {
         this.session = { ...info, appliedSeq: 0 }
     }
 
-    /**
-     * One-shot bridge to the application's Taro singleton. It cannot be imported into this
-     * separately bundled global runtime without creating a second Taro identity. Undefined
-     * only before the serve-only facade connection; route transactions share its lifetime.
-     */
-    private taro: TaroState | undefined
-
-    /** Connects HMR to the same Taro singleton used by the application module graph. */
-    connectTaro(
-        current: TaroState['current'],
-        document: TaroState['document'],
-        injectPageInstance: TaroState['injectPageInstance']
-    ): void {
-        if (this.taro) {
-            return
-        }
+    /** Tracks the mounted native Page and prepares its static config for HMR re-registration. */
+    injectPageHmr(config: HmrPageConfig): HmrPageConfig {
+        const existingState = config[pageHmrStateKey]
+
+        if (existingState) {
+            const mountedPage = existingState.mountedPage
+            /*
+             * The static config can outlive a native Page instance. Before its first ordinary onLoad, or after a real onUnload,
+             * there is no mounted Page or current view-model to carry into another registration. Leave the lifecycle gate
+             * unarmed and preserve the config's existing initial data so a future real onLoad still enters Taro normally.
+             */
+            if (!mountedPage) {
+                return config
+            }
 
-        this.taro = {
-            current,
-            document,
-            injectPageInstance,
-            pageReplacements: new Map()
+            /*
+             * Arm the lifecycle wrappers on this exact static config before it is passed back to `Page(config)`. DevTools then
+             * triggers an unload/load/show sequence for that native re-registration: unload and load observe `true` and return
+             * before entering Taro, preserving the mounted React tree and its original Page connection; show consumes the
+             * one-shot gate by restoring `false`. Ordinary navigation never enters this branch, and every Page config owns an
+             * independent state object, so no route map, global phase, or Page identity comparison participates in the decision.
+             */
+            existingState.isReregistering = true
+            /*
+             * `Page(config)` reads `config.data` as the initial native view-model for this registration. Supplying the mounted
+             * Page's latest data before that call prevents the temporary Page used for re-registration callbacks from starting
+             * empty. This is an O(1) reference assignment in vpt: it does not clone the recursive data tree, call `setData`, move
+             * React state, or rebind Taro. The ordinary Taro lifecycle remains suppressed until re-registration onShow, so its
+             * React tree and output connection stay attached to `mountedPage`; every later registration reads its latest data.
+             */
+            config.data = mountedPage.data
+
+            return config
         }
-    }
 
-    /** Injects snapshot-preserving behavior into one route-specific Taro Page configuration. */
-    injectPageHmr(config: HmrPageConfig, route: string): void {
         const originalOnUnload = config.onUnload
         const originalOnLoad = config.onLoad
         const originalOnShow = config.onShow
-        const runtime = this
+
+        const state: PageHmrState = {
+            isReregistering: false,
+            mountedPage: undefined
+        }
+
+        /*
+         * Attach the one mutable HMR state object to this exact static config. The lifecycle wrappers below close over the same
+         * object, while a later `injectPageHmr(config)` call finds it through the symbol and knows wrapping is already complete.
+         * A symbol cannot collide with WeChat or Taro's string-named Page options, and config-local ownership avoids route maps,
+         * a runtime-wide WeakMap, or state shared by two Page configs. The state becomes unreachable together with the config.
+         */
+        config[pageHmrStateKey] = state
 
         config.onUnload = function (this: NativePage, ...args: unknown[]) {
-            const taro = runtime.requireTaro()
-            if (taro.pageReplacements.has(route)) {
-                taro.pageReplacements.set(route, {
-                    $taroPath: this.$taroPath,
-                    $taroParams: this.$taroParams,
-                    // WeChat owns this serializable view-model. Keeping its reference is O(1),
-                    // unlike cloning the complete recursive projection before every edit.
-                    data: this.data
-                })
+            if (state.isReregistering) {
                 return
             }
+
             forward(originalOnUnload, this, args)
+            state.mountedPage = undefined
         }
 
         config.onLoad = function (this: NativePage, ...args: unknown[]) {
-            const taro = runtime.requireTaro()
-            const snapshot = taro.pageReplacements.get(route)
-            if (snapshot) {
-                // Replace the transaction before native work so exceptions cannot retain the
-                // large data snapshot while the route waits for its synthetic onShow.
-                taro.pageReplacements.set(route, null)
-
-                // Snapshot paint is the first bridge operation and removes the empty-page gap.
-                this.setData(snapshot.data)
-                this.$taroPath = snapshot.$taroPath
-                this.$taroParams = snapshot.$taroParams
-                runtime.bindPage(this, snapshot.$taroPath)
+            if (state.isReregistering) {
                 return
             }
+
             forward(originalOnLoad, this, args)
+            state.mountedPage = this
         }
 
         config.onShow = function (this: NativePage, ...args: unknown[]) {
-            if (runtime.requireTaro().pageReplacements.delete(route)) {
-                // Synthetic shows must not repeat requests or reset application state.
+            if (state.isReregistering) {
+                state.isReregistering = false
                 return
             }
 
             forward(originalOnShow, this, args)
         }
-    }
-
-    /** Returns the Taro connection or fails at the first incorrectly ordered use. */
-    private requireTaro(): TaroState {
-        if (!this.taro) throw new Error('[vpt] WX HMR used before the Taro runtime was connected')
-        return this.taro
-    }
-
-    /** Returns a retained Taro root after normal Page mount has created it. */
-    private findRoot(path: string): TaroRoot | undefined {
-        const root = this.requireTaro().document.getElementById(path)
-        return isTaroRoot(root) ? root : undefined
-    }
-
-    /** Rebinds a retained Taro tree to one replacement native Page without repainting. */
-    private bindPage(instance: NativePage, path: string): void {
-        const taro = this.requireTaro()
-        taro.injectPageInstance(instance, path)
-        taro.current.page = instance
-
-        const pageElement = this.findRoot(path)
-        if (!pageElement) {
-            throw new Error(`[vpt] retained Taro page not found: ${path}`)
-        }
 
-        pageElement.ctx = instance
+        return config
     }
 
-    /** Applies one Page-delivered payload and arms its route for native replacement. */
-    applyPatches(payload: PatchPayload | undefined, route?: string): void {
+    /** Applies one Page-delivered payload before its native shell registers the static route configuration. */
+    applyPatches(payload: PatchPayload | undefined): void {
         // The initial physical dependency exports undefined until the host has a patch range.
         if (!payload) return
 
@@ -397,12 +354,6 @@ class WxDevRuntime extends DevRuntime {
             return
         }
 
-        // A replayed payload still causes DevTools to replace this physical Page. Arm the
-        // route independently of whether this App heap already applied its patch sequence.
-        if (route) {
-            this.requireTaro().pageReplacements.set(route, null)
-        }
-
         // Apply synchronously: the page's imports below the require resolve against the
         // freshly registered modules, so the re-executed Page evaluates with the new code.
         if (this.applyPatchBatch(session, payload.patches)) {

package/src/runtime/wx/wechat.d.ts

@@ -8,8 +8,7 @@ type WeChatGlobal = object
 /** The App-global Rolldown dev runtime; present only in wx development builds. */
 declare const __rolldown_runtime__:
     | {
-          connectTaro(current: object, document: object, injectPageInstance: (...args: unknown[]) => unknown): void
-          injectPageHmr(config: object, route: string): void
+          injectPageHmr(config: object): object
       }
     | undefined