vite-plugin-taro 0.6.2 → 0.6.5

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.5",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -57,6 +57,7 @@
     "@oxc-project/types": "0.143.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "@tailwindcss-mangle/engine": "0.2.0",
+    "@tailwindcss/oxide": "4.3.3",
     "@tarojs/components": "4.2.0",
     "@tarojs/helper": "4.2.0",
     "@tarojs/plugin-platform-h5": "4.2.0",
@@ -75,8 +76,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.5",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.5"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -1,4 +1,3 @@
-import { readFile } from 'node:fs/promises'
 import type { ServerResponse } from 'node:http'
 import path from 'node:path'
 import colors from 'picocolors'
@@ -6,10 +5,11 @@ import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
 import { asyncScheduler } from 'rxjs'
 import type { Connect, ViteDevServer } from 'vite'
 import type { VptOptions } from '../../../../options.ts'
+import type { WxStylePlugin } from '../styles/plugins.ts'
 import { createHmrResultsStream } from './create-hmr-results-stream.ts'
-import { createStyleCapture, type StyleCaptureAction } from './create-style-capture.ts'
 import {
     developmentAppWxssFileName,
+    globalWxssFileName,
     type HmrInfo,
     hmrControlPath,
     hmrInfoFileName,
@@ -36,7 +36,6 @@ type DevOutputResult = Parameters<NonNullable<DevOptions['onOutput']>>[0]
 type OutputAction = Readonly<{ kind: 'output'; result: DevOutputResult }>
 
 type HostAction =
-    | StyleCaptureAction
     | Readonly<{ kind: 'publish'; result: HmrUpdates }>
     | Readonly<{ kind: 'error'; error: Error }>
     | Readonly<{ kind: 'reports'; reports: readonly RuntimeReport[] }>
@@ -52,17 +51,17 @@ 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
+    styles
 }: {
     server: ViteDevServer
     options: VptOptions
-    applicationEntryIds: readonly string[]
+    styles: WxStylePlugin
 }): Promise<WxDevHost> {
     const bundledDev = getBundledDev(server)
 
@@ -71,23 +70,12 @@ export async function createWxDevHost({
         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: DevEngine = await createEngine()
 
     const hmrResults = createHmrResultsStream(
@@ -158,12 +146,17 @@ export async function createWxDevHost({
             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: string): Promise<void> {
+        await writeHmrFile(server.config.build.outDir, globalWxssFileName, wxss)
+    }
+
     /** Rotates the build identity and materializes the App metadata for it. */
     async function rotateBuildSession(): Promise<void> {
         const port = boundPort(server)
@@ -207,14 +200,6 @@ export async function createWxDevHost({
     /** Reduces one merged source action through the existing authoritative host state. */
     function applyHostAction(action: HostAction): void | Promise<void> {
         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':
@@ -228,21 +213,15 @@ export async function createWxDevHost({
                     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: Exclude<DevOutputResult, Error>['output']): Promise<void> {
-        await styleCapture.reconcileComplete(output)
+    /** Publishes graph-complete styles before rotating the App-visible build identity. */
+    async function publishCompleteStyles(): Promise<void> {
+        await styles.finalizeUpdate([], writeGlobalStyle)
         await rotateBuildSession()
     }
 
@@ -329,18 +308,17 @@ export async function createWxDevHost({
             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 publisher.produce(finalizedPatches)
 
-        await commitPublishedBatch(patches)
+        await commitPublishedBatch(finalizedPatches)
     }
 
     /**

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

@@ -3,13 +3,12 @@ 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 type { WxStylePlugin } from '../styles/plugins.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'
@@ -19,10 +18,10 @@ export function isWxClientEnvironment(environment: Readonly<{ name: string }>):
  * 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: VptOptions, applicationEntryIds: readonly string[]): PluginOption[] {
+export function createWxDevelopmentPlugin(options: VptOptions, styles: WxStylePlugin): PluginOption[] {
     /*
      * 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
@@ -32,9 +31,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 [
         {
@@ -75,7 +72,7 @@ export function createWxDevelopmentPlugin(options: VptOptions, applicationEntryI
                     host = await createWxDevHost({
                         server: server,
                         options: options,
-                        applicationEntryIds: applicationEntryIds
+                        styles: styles
                     })
                 }
             },
@@ -116,38 +113,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 +147,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,