vite-plugin-taro 0.6.2 → 0.6.5

package/README.en.md

@@ -1,4 +1,4 @@
-# vite-plugin-taro
+# VPT
 
 [![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
 ![Vite](https://img.shields.io/npm/dependency-version/vite-plugin-taro/peer/vite?label=Vite)
@@ -20,7 +20,7 @@ Continue with the [Quick Start guide](https://vpt.js.org/guides/quick-start/).
 
 ### React Hot Reload in WeChat DevTools
 
-<video src="https://github.com/user-attachments/assets/cb93daf5-1827-496a-bb74-8397975accf6" controls autoplay muted loop playsinline width="100%"></video>
+<video src="https://github.com/user-attachments/assets/c8289e1e-d8ad-429f-a0d9-a40656b4962a" controls autoplay muted loop playsinline width="100%"></video>
 
 - **Vite 8 + React 19** Build one codebase for WeChat Mini Program and Web with the Vite ecosystem.
 - **Hot reload** Preserve App data, the active page, React component state, and input state while editing.
@@ -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

@@ -1,4 +1,4 @@
-# vite-plugin-taro
+# VPT
 
 [![npm version](https://img.shields.io/npm/v/vite-plugin-taro.svg)](https://www.npmjs.com/package/vite-plugin-taro)
 ![Vite](https://img.shields.io/npm/dependency-version/vite-plugin-taro/peer/vite?label=Vite)
@@ -21,7 +21,7 @@ npm create vite-taro@latest my-app
 
 ### 已支持微信开发者工具的 React 热更新
 
-<video src="https://github.com/user-attachments/assets/cb93daf5-1827-496a-bb74-8397975accf6" controls autoplay muted loop playsinline width="100%"></video>
+<video src="https://github.com/user-attachments/assets/c8289e1e-d8ad-429f-a0d9-a40656b4962a" controls autoplay muted loop playsinline width="100%"></video>
 
 - **Vite 8 + React 19** 基于 Vite 生态，一份代码覆盖微信小程序与 Web。
 - **热更新** 编辑代码时保留 App 数据、当前页面、React 组件状态与输入状态。
@@ -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/dev-host.d.ts

@@ -1,5 +1,6 @@
 import type { ViteDevServer } from 'vite';
 import type { VptOptions } from '../../../../options.ts';
+import type { WxStylePlugin } from '../styles/plugins.ts';
 export type WxDevHost = Readonly<{
     close: () => Promise<void>;
 }>;
@@ -9,11 +10,11 @@ export type WxDevHost = Readonly<{
  * engine writes directly to the Mini Program output directory instead of serving browser
  * HMR over HTTP.
  *
- * `applicationEntryIds` is the resolver's immutable cascade policy, not a second graph: it selects the App capsule followed
- * by configured Page capsules from Rolldown's larger entry set. Rolldown remains the authority for every live import edge.
+ * The shared style plugin carries the resolver's immutable App/Page cascade policy while Rolldown remains authoritative for
+ * every live import edge.
  */
-export declare function createWxDevHost({ server, options, applicationEntryIds }: {
+export declare function createWxDevHost({ server, options, styles }: {
     server: ViteDevServer;
     options: VptOptions;
-    applicationEntryIds: readonly string[];
+    styles: WxStylePlugin;
 }): Promise<WxDevHost>;

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

@@ -1,11 +1,9 @@
-import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import colors from 'picocolors';
 import { dev } from 'rolldown/experimental';
 import { asyncScheduler } from 'rxjs';
 import { createHmrResultsStream } from './create-hmr-results-stream.js';
-import { createStyleCapture } from './create-style-capture.js';
-import { developmentAppWxssFileName, hmrControlPath, hmrInfoFileName, hmrPatchesFileName, renderDevelopmentAppWxss, renderHmrInfo, renderInitialHmrPatches, writeHmrFile } from './hmr-files.js';
+import { developmentAppWxssFileName, globalWxssFileName, hmrControlPath, hmrInfoFileName, hmrPatchesFileName, renderDevelopmentAppWxss, renderHmrInfo, renderInitialHmrPatches, writeHmrFile } from './hmr-files.js';
 import { createHostActions } from './host-actions.js';
 import { PatchPublisher } from './patch-publisher.js';
 import { createRuntimeReportsStream } from './runtime-reports.js';
@@ -18,27 +16,16 @@ const hmrSettleMilliseconds = 16;
  * engine writes directly to the Mini Program output directory instead of serving browser
  * HMR over HTTP.
  *
- * `applicationEntryIds` is the resolver's immutable cascade policy, not a second graph: it selects the App capsule followed
- * by configured Page capsules from Rolldown's larger entry set. Rolldown remains the authority for every live import edge.
+ * The shared style plugin carries the resolver's immutable App/Page cascade policy while Rolldown remains authoritative for
+ * every live import edge.
  */
-export async function createWxDevHost({ server, options, applicationEntryIds }) {
+export async function createWxDevHost({ server, options, styles }) {
     const bundledDev = getBundledDev(server);
     // All callbacks admit typed actions through this edge; concatMap is the sole owner of effect ordering and mutable host state.
     const hostActions = createHostActions(applyHostAction, (action, error) => logWxError(server.config.logger, `wx HMR ${action.kind} failed`, error));
-    const styleCapture = createStyleCapture({
-        applicationEntryIds: applicationEntryIds,
-        outDir: server.config.build.outDir,
-        // Capture hooks run only after engine.run, when the host action subscription and all reducer dependencies are ready.
-        emit: (action) => hostActions.next(action),
-        transformTailwindRoot: async (rootId, requestId) => {
-            // The capture contains generated CSS, while the sidecar must re-run from raw Tailwind directives. Vite exposes no
-            // raw source in its live module graph, so this read is the authoritative source generation rather than a read-back.
-            return server.environments.client.pluginContainer.transform(await readFile(rootId, 'utf8'), requestId);
-        }
-    });
     const publisher = new PatchPublisher((content) => writeHmrFile(server.config.build.outDir, hmrPatchesFileName, content));
     // Option installation now configures only Rolldown. Build lifecycle results enter through the engine's output action below.
-    installWxDevOptions({ bundledDev, server, options, hostPlugins: [styleCapture.plugin] });
+    installWxDevOptions({ bundledDev, server, options });
     const engine = await createEngine();
     const hmrResults = createHmrResultsStream(hmrSettleMilliseconds, asyncScheduler, (result) => {
         // One reduced window becomes one existing host transaction: style preparation, one cumulative patch write, then
@@ -98,11 +85,15 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
             hmrResults.complete();
             runtimeReports.complete();
             await hostActions.waitForIdle();
-            // Keep the action edge open until the final generation has admitted all capture and output callbacks.
+            // Keep the action edge open until the final generation has admitted every output callback.
             await engine.ensureCurrentBuildFinish();
             await hostActions.complete();
         }
     };
+    /** Atomically materializes the style plugin's prepared global artifact. */
+    async function writeGlobalStyle(wxss) {
+        await writeHmrFile(server.config.build.outDir, globalWxssFileName, wxss);
+    }
     /** Rotates the build identity and materializes the App metadata for it. */
     async function rotateBuildSession() {
         const port = boundPort(server);
@@ -142,14 +133,6 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
     /** Reduces one merged source action through the existing authoritative host state. */
     function applyHostAction(action) {
         switch (action.kind) {
-            case 'capture-graph':
-                // The buildStart reader is a live capability; replacing it only here makes the reducer own build rebinding.
-                styleCapture.captureGraph(action.getModuleInfo);
-                return;
-            case 'capture-style':
-                // A failed upstream transform emits no action, intentionally retaining the last valid processed CSS generation.
-                styleCapture.captureStyle(action.id, action.style);
-                return;
             case 'publish':
                 return publishUpdates(action.result);
             case 'error':
@@ -163,20 +146,14 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
                     logWxError(server.config.logger, 'wx dev build failed', action.result);
                     return;
                 }
-                return reconcileCompleteOutput(action.result.output);
+                return publishCompleteStyles();
             case 'listening':
                 return rotateBuildSession();
         }
     }
-    /**
-     * Reconciles graph-complete styles before rotating the App-visible build identity.
-     *
-     * DevEngine has already written its compiler asset when onOutput fires, but bundled development may have omitted CSS Modules
-     * from that asset. Awaiting reconciliation inside the serialized reducer guarantees the subsequent app.wxss rotation—the
-     * event that refreshes DevTools—can only expose a generation whose global WXSS already represents the complete App/Page graph.
-     */
-    async function reconcileCompleteOutput(output) {
-        await styleCapture.reconcileComplete(output);
+    /** Publishes graph-complete styles before rotating the App-visible build identity. */
+    async function publishCompleteStyles() {
+        await styles.finalizeUpdate([], writeGlobalStyle);
         await rotateBuildSession();
     }
     /** Applies one runtime receipt to the active physical patch history. */
@@ -252,16 +229,15 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
         if (patches.length === 0) {
             return;
         }
-        // `onHmrUpdates` is the transaction boundary after every affected transform has updated graph and candidate state.
-        // Every non-CSS edit may alter imports or Tailwind classes; rendering broadly and comparing finalized bytes avoids
-        // source scanning while preventing unrelated JavaScript edits from notifying DevTools through an identical rename.
-        await styleCapture.publishChanged(patches.flatMap((patch) => patch.changedIds));
+        // `onHmrUpdates` runs after every affected transform has updated captured CSS and the live import graph. The style
+        // boundary finalizes every factory before atomically publishing their matching WXSS.
+        const finalizedPatches = await styles.finalizeUpdate(patches, writeGlobalStyle);
         // Publish global.wxss before the matching JavaScript patch so DevTools observes a coherent HMR transaction.
         // The physical file must exist before Rolldown advances: once committed, later patches may be generated relative to
         // this batch even if DevTools has not observed its file event yet. PatchPublisher keeps the unapplied range cumulative,
         // so any later file generation still carries every factory needed to bridge the runtime's older application frontier.
-        await publisher.produce(patches);
-        await commitPublishedBatch(patches);
+        await publisher.produce(finalizedPatches);
+        await commitPublishedBatch(finalizedPatches);
     }
     /**
      * Advances Rolldown's published frontier in the same sequence order materialized in the cumulative physical file.

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

@@ -1,5 +1,6 @@
 import { type PluginOption } from 'vite';
 import type { VptOptions } from '../../../../options.ts';
+import type { WxStylePlugin } from '../styles/plugins.ts';
 /** Selects the sole Vite environment that owns the physical Mini Program development project. */
 export declare function isWxClientEnvironment(environment: Readonly<{
     name: string;
@@ -8,10 +9,10 @@ export declare function isWxClientEnvironment(environment: Readonly<{
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.
  *
- * The ordered application entries cross this configuration boundary unchanged so the host can compose global CSS without
- * reconstructing the resolver's App/Page ownership policy from unrelated Rolldown shell and transport entries.
+ * The shared style pipeline already owns the resolver's ordered App/Page cascade policy, so the host does not reconstruct it
+ * from unrelated Rolldown shell and transport entries.
  */
-export declare function createWxDevelopmentPlugin(options: VptOptions, applicationEntryIds: readonly string[]): PluginOption[];
+export declare function createWxDevelopmentPlugin(options: VptOptions, styles: WxStylePlugin): PluginOption[];
 /**
  * Transfers development ownership of `app.wxss` from complete output to the dev host.
  *
@@ -28,18 +29,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';
@@ -15,10 +14,10 @@ export function isWxClientEnvironment(environment) {
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.
  *
- * The ordered application entries cross this configuration boundary unchanged so the host can compose global CSS without
- * reconstructing the resolver's App/Page ownership policy from unrelated Rolldown shell and transport entries.
+ * The shared style pipeline already owns the resolver's ordered App/Page cascade policy, so the host does not reconstruct it
+ * from unrelated Rolldown shell and transport entries.
  */
-export function createWxDevelopmentPlugin(options, applicationEntryIds) {
+export function createWxDevelopmentPlugin(options, styles) {
     /*
      * Vite creates this plugin descriptor before a server or DevEngine exists, then invokes configureServer and closeBundle on
      * different lifecycle stacks. This mutable handle transfers the one client-owned host between those hooks: configureServer
@@ -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',
@@ -68,7 +65,7 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
                     host = await createWxDevHost({
                         server: server,
                         options: options,
-                        applicationEntryIds: applicationEntryIds
+                        styles: styles
                     });
                 }
             },
@@ -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.d.ts

@@ -1,4 +1,4 @@
-import type { InputOptions, OutputOptions, Plugin } from 'rolldown';
+import type { InputOptions, OutputOptions } from 'rolldown';
 import { type DevEngine } from 'rolldown/experimental';
 import type { ViteDevServer } from 'vite';
 import type { VptOptions } from '../../../../options.ts';
@@ -19,11 +19,10 @@ export type BundledDev = {
  * Installs physical WX output and runtime conventions over Vite's browser-oriented bundled-development options.
  * Build completion deliberately remains outside this options adapter: DevEngine onOutput is the single lifecycle authority.
  */
-export declare function installWxDevOptions({ bundledDev, server, options, hostPlugins }: {
+export declare function installWxDevOptions({ bundledDev, server, options }: {
     bundledDev: BundledDev;
     server: ViteDevServer;
     options: VptOptions;
-    hostPlugins: Plugin[];
 }): void;
 /** Returns the configured output after rejecting states unsupported by the physical WX engine. */
 export declare function requireSingleOutput(rolldownOptions: BundledDevRolldownOptions): OutputOptions;

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

@@ -8,7 +8,7 @@ import { appShellFileName } from '../module/module.js';
  * Installs physical WX output and runtime conventions over Vite's browser-oriented bundled-development options.
  * Build completion deliberately remains outside this options adapter: DevEngine onOutput is the single lifecycle authority.
  */
-export function installWxDevOptions({ bundledDev, server, options, hostPlugins }) {
+export function installWxDevOptions({ bundledDev, server, options }) {
     /*
      * Vite owns this mutable adapter method and calls it later when constructing DevEngine. Replacing that one seam preserves
      * Vite's resolved graph while applying WX physical-output conventions to every options generation. Capturing and mutating one
@@ -78,10 +78,10 @@ export function installWxDevOptions({ bundledDev, server, options, hostPlugins }
         };
         /*
          * The plugin list is mutable configuration consumed once by this engine generation. Replace the top-level reference with
-         * an ordered composite rather than pushing into Vite's potentially shared nested array: existing transforms run first,
-         * host capture observes their final values, and the reporter observes final output without mutating either input list.
+         * an ordered composite rather than pushing into Vite's potentially shared nested array; the reporter observes final output
+         * without mutating Vite's retained input list.
          */
-        rolldownOptions.plugins = [rolldownOptions.plugins, hostPlugins, createViteReporter(server)];
+        rolldownOptions.plugins = [rolldownOptions.plugins, createViteReporter(server)];
         disableViteOxcSourcemap(rolldownOptions.plugins);
         return rolldownOptions;
     };
@@ -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/plugins.js

@@ -10,19 +10,15 @@ import { renderCapsule } from './render/capsule.js';
 import { renderNative } from './render/native.js';
 import { materializeTransport } from './render/transport.js';
 import { createResolver } from './resolve/resolver.js';
-import { createWxStylePlugins } from './styles/plugins.js';
+import { createWxStylePlugin } from './styles/plugins.js';
 /** Creates the complete plugin set for the wx target. */
 export function createWxTargetPlugins(options) {
     const resolver = createResolver(options);
     // Reuse the resolver instance's ordered application subset. Rolldown's complete input also contains bootstrap, transport,
     // shell, and component entries; entry membership alone cannot recover which roots define the App/Page CSS cascade.
     const placement = createWxPlacementPlugin();
-    return [
-        placement,
-        createWxStylePlugins(),
-        createWxPlugin(options, resolver, placement),
-        createWxDevelopmentPlugin(options, resolver.applicationEntryIds)
-    ];
+    const styles = createWxStylePlugin(resolver.applicationEntryIds);
+    return [placement, styles, createWxPlugin(options, resolver, placement), createWxDevelopmentPlugin(options, styles)];
 }
 /** Configures the complete wx target build pipeline. */
 function createWxPlugin(options, resolver, placement) {
@@ -106,10 +102,8 @@ function createWxPlugin(options, resolver, placement) {
         },
         generateBundle: {
             /*
-             * This hook is registered after createWxStylePlugins() and shares hook-level `order: 'post'` with the adapted
-             * upstream hooks and VPT style finalizer. Registration order therefore guarantees that the imported global
-             * stylesheet is complete before native Page/component companions are emitted. Without this order, the finalizer
-             * could consume incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
+             * Registration after the style pipeline makes the compiler stylesheet final before native Page and component
+             * companions are emitted. The style finalizer therefore cannot mistake native WXSS for application CSS.
              */
             order: 'post',
             async handler(_, bundle) {