vite-plugin-taro 0.5.14 → 0.6.0

package/dist/options.d.ts

@@ -1,20 +1,72 @@
 /** A JSON object used by generated target configs. */
-export type JsonObject = Record<string, unknown>;
+export type VptJsonObject = Record<string, unknown>;
 /** Build target handled by this plugin. */
-export type VitePluginTaroTarget = 'wx' | 'h5';
+export type VptTarget = 'wx' | 'h5';
 /** Configures one Taro page. */
-export type VitePluginTaroPageOption = {
-    /** Taro route and output path without a file extension. */
+export type VptPageOption = {
+    /**
+     * Taro route and output path without a file extension.
+     *
+     * The plugin resolves the page component from `src/${path}.tsx`, relative to the Vite project root. For example,
+     * `pages/home/index` resolves to `src/pages/home/index.tsx` and is emitted under `pages/home/index` for `wx`.
+     */
     path: string;
-    config: JsonObject;
+    /**
+     * Target-independent Taro page configuration.
+     *
+     * For `wx`, these values form the generated `<path>.json`; the plugin augments `usingComponents` with its generated
+     * component registrations. For `h5`, the values are added to the corresponding Taro router entry.
+     */
+    config: VptJsonObject;
 };
-/** Configures the Vite Taro plugin. */
-export interface VitePluginTaroOptions {
-    target: VitePluginTaroTarget;
+/** Configures vpt for one build target. */
+export interface VptOptions {
+    /**
+     * Platform produced by the current Vite invocation.
+     *
+     * Use `wx` to emit a WeChat Mini Program or `h5` to emit a browser application. The selected target controls Taro
+     * module resolution, conditional compilation, runtime bootstrapping, style processing, and output generation.
+     */
+    target: VptTarget;
+    /**
+     * Source module that default-exports the root React application component.
+     *
+     * Relative paths are resolved from Vite's project root, for example `src/app.tsx`. The component wraps the active
+     * page through its `children` prop and is the appropriate place to import application-wide styles.
+     */
     app: string;
-    pages: VitePluginTaroPageOption[];
-    appJson: JsonObject;
-    projectConfigJson: JsonObject;
-    projectPrivateConfigJson?: JsonObject;
-    sitemapJson: JsonObject;
+    /**
+     * Complete ordered list of application pages.
+     *
+     * The declared order becomes the `pages` order in the generated `app.json`, the H5 route order, and the Page order
+     * in the application style cascade. Each Page source is resolved according to its `path`.
+     */
+    pages: VptPageOption[];
+    /**
+     * Target-independent Taro application configuration.
+     *
+     * For `wx`, these values form the generated `app.json`. For `h5`, they configure the Taro application and router.
+     * The plugin always derives `pages` from {@link pages}; caller-provided `pages`, `subPackages`, and `subpackages`
+     * values are discarded because the build pipeline owns page order and generated package placement.
+     */
+    appJson: VptJsonObject;
+    /**
+     * WeChat DevTools project configuration written to `project.config.json` without merging.
+     *
+     * This option is required so one configuration shape can be shared between targets, but it is only emitted for a
+     * `wx` build and is ignored for `h5`.
+     */
+    projectConfigJson: VptJsonObject;
+    /**
+     * Local WeChat DevTools overrides written to `project.private.config.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    projectPrivateConfigJson?: VptJsonObject;
+    /**
+     * WeChat Mini Program indexing rules written to `sitemap.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    sitemapJson?: VptJsonObject;
 }

package/dist/runtime/h5/app.js

@@ -5,9 +5,9 @@ import ReactDOM from 'react-dom/client';
 // @ts-expect-error: The H5 build resolves this private App component.
 import AppComponent from '\0vpt:app-component';
 const browserWindow = window;
-const config = __VITE_PLUGIN_TARO_H5_APP_CONFIG__;
+const config = __VPT_H5_APP_CONFIG__;
 browserWindow.__taroAppConfig = config;
-config.routes = __VITE_PLUGIN_TARO_H5_ROUTES__;
+config.routes = __VPT_H5_ROUTES__;
 const app = createReactApp(AppComponent, React, ReactDOM, config);
 const history = createHashHistory({ window: browserWindow });
 handleAppMount(config, history);

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

@@ -2,7 +2,7 @@
 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 = __VITE_PLUGIN_TARO_APP_CONFIG__;
+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/amphibious/transport.js

@@ -1,4 +1,4 @@
 // Transport itself executes only as native CommonJS. It lives beside bootstrap because together they implement the
 // amphibious boundary that publishes native namespaces to SystemJS without re-evaluating their module bodies.
 /** Dispatches to one generated literal require and bridges amphibious CommonJS namespaces inline. */
-export const transport = __VITE_PLUGIN_TARO_TRANSPORT__;
+export const transport = __VPT_TRANSPORT__;

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

@@ -3,5 +3,5 @@ import './app.js';
 // @ts-expect-error: The wx build replaces this private import with the configured Page component.
 import PageComponent from '\0vpt:page-component';
 import { createPageConfig } from './taro-runtime.js';
-const config = createPageConfig(PageComponent, __VITE_PLUGIN_TARO_PAGE_PATH__, { root: { cn: [] } }, __VITE_PLUGIN_TARO_PAGE_CONFIG__);
+const config = createPageConfig(PageComponent, __VPT_PAGE_PATH__, { root: { cn: [] } }, __VPT_PAGE_CONFIG__);
 export default config;

package/dist/vite.d.ts

@@ -1,2 +1,2 @@
-export { default } from './node/vite-plugin.ts';
-export type { VitePluginTaroOptions, VitePluginTaroPageOption, VitePluginTaroTarget } from './options.ts';
+export { default } from './node/vpt.ts';
+export type { VptJsonObject, VptOptions, VptPageOption, VptTarget } from './options.ts';

package/dist/vite.js

@@ -1 +1 @@
-export { default } from './node/vite-plugin.js';
+export { default } from './node/vpt.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.5.14",
+  "version": "0.6.0",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -76,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.5.14",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.14"
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.0",
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/plugins/client/client-taro.ts

@@ -1,5 +1,5 @@
 import { normalizePath, type Plugin } from 'vite'
-import type { VitePluginTaroTarget } from '../../../options.ts'
+import type { VptTarget } from '../../../options.ts'
 import { normalizeModuleId } from '../../utils/modules.ts'
 import { resolvePackageFile } from '../../utils/packages.ts'
 import { clientTaroNativeId } from './constant.ts'
@@ -32,7 +32,7 @@ const clientTaroModules = new Map([
 ])
 
 /** Creates the shared Taro facade backed by the selected target's API implementation. */
-export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
+export function createClientTaroPlugin(target: VptTarget): Plugin {
     const platformTaroId = resolvePlatformTaroId(target)
 
     return {
@@ -62,7 +62,7 @@ export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
     }
 }
 
-function resolvePlatformTaroId(target: VitePluginTaroTarget): string {
+function resolvePlatformTaroId(target: VptTarget): string {
     return target === 'h5' ? '@tarojs/plugin-platform-h5/dist/runtime/apis' : '@tarojs/taro'
 }
 

package/src/node/plugins/conditional/conditional-directives.ts

@@ -1,9 +1,9 @@
 import type { Plugin } from 'vite'
-import type { VitePluginTaroTarget } from '../../../options.ts'
+import type { VptTarget } from '../../../options.ts'
 import { normalizeModuleId } from '../../utils/modules.ts'
 
 /** Creates source-level target conditional handling shared by H5 and WX. */
-export function createConditionalDirectivePlugin(target: VitePluginTaroTarget): Plugin {
+export function createConditionalDirectivePlugin(target: VptTarget): Plugin {
     return {
         name: 'vpt:conditional-directives',
         enforce: 'pre',
@@ -37,7 +37,7 @@ type DirectiveFrame = {
 }
 
 /** Keeps only the source branches active for one build target. */
-function transformConditionalDirectives(code: string, target: VitePluginTaroTarget): string {
+function transformConditionalDirectives(code: string, target: VptTarget): string {
     const lines = code.match(/[^\n]*(?:\n|$)/g) ?? []
     const frames: DirectiveFrame[] = []
     let transformed = ''

package/src/node/plugins/h5/plugins.ts

@@ -1,7 +1,7 @@
 import babel, { defineRolldownBabelPreset } from '@rolldown/plugin-babel'
 import type { HtmlTagDescriptor, Plugin, PluginOption } from 'vite'
 import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
-import type { VitePluginTaroOptions } from '../../../options.ts'
+import type { VptOptions } from '../../../options.ts'
 import { esTarget } from '../../utils/constant.ts'
 import { toViteFileImportPath } from '../../utils/modules.ts'
 import { packageRequire } from '../../utils/packages.ts'
@@ -12,7 +12,7 @@ import { createStencilClientAdapter } from './create-stencil-client-adapter.ts'
 import { createModuleResolver } from './resolver/module-resolver.ts'
 
 /** Creates the plugins that own the H5 target. */
-export function createH5TargetPlugins(options: VitePluginTaroOptions): PluginOption[] {
+export function createH5TargetPlugins(options: VptOptions): PluginOption[] {
     return [
         WeappTailwindcss({
             appType: 'weapp-vite',
@@ -36,7 +36,7 @@ export function createH5TargetPlugins(options: VitePluginTaroOptions): PluginOpt
 }
 
 /** Configures H5 resolution and supplies the specialized physical application entry. */
-function createH5TargetPlugin(options: VitePluginTaroOptions): Plugin {
+function createH5TargetPlugin(options: VptOptions): Plugin {
     const moduleResolver = createModuleResolver(options)
 
     return {

package/src/node/plugins/h5/resolver/module-resolver.ts

@@ -1,12 +1,12 @@
 import { normalizePath } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { normalizeModuleId, resolveAppComponentPath } from '../../../utils/modules.ts'
 import { appComponentId } from '../../client/constant.ts'
 import { h5AppPath } from '../constant.ts'
 import { transformH5App } from '../transform-app.ts'
 
 /** Creates H5 application module resolution and specialization. */
-export function createModuleResolver(options: VitePluginTaroOptions) {
+export function createModuleResolver(options: VptOptions) {
     return {
         resolveId({ id, projectRoot }: { id: string; projectRoot: string }): string | undefined {
             if (id === appComponentId) {

package/src/node/plugins/h5/transform-app.ts

@@ -1,11 +1,11 @@
 import { types } from '@babel/core'
-import type { VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../options.ts'
+import type { VptOptions, VptPageOption } from '../../../options.ts'
 import { createPageComponentImportPath } from '../../utils/modules.ts'
 import { createAppConfig } from '../../utils/project-config.ts'
 import { type AstTransformResult, replaceWithAst } from '../../utils/transform.ts'
 
-const appConfigPlaceholder = '__VITE_PLUGIN_TARO_H5_APP_CONFIG__'
-const routesPlaceholder = '__VITE_PLUGIN_TARO_H5_ROUTES__'
+const appConfigPlaceholder = '__VPT_H5_APP_CONFIG__'
+const routesPlaceholder = '__VPT_H5_ROUTES__'
 
 /** Specializes the physical H5 App for one configured project. */
 export async function transformH5App({
@@ -17,7 +17,7 @@ export async function transformH5App({
 }: {
     code: string
     id: string
-    options: VitePluginTaroOptions
+    options: VptOptions
     projectRoot: string
     sourcemap?: boolean
 }): Promise<AstTransformResult> {
@@ -56,7 +56,7 @@ function createRoute({
     page,
     projectRoot
 }: {
-    page: VitePluginTaroPageOption
+    page: VptPageOption
     projectRoot: string
 }): ReturnType<typeof types.objectExpression> {
     const pageComponentPath = createPageComponentImportPath({ pagePath: page.path, projectRoot })

package/src/node/plugins/wx/dev/create-style-capture.ts

@@ -11,11 +11,14 @@ import {
 } from '../styles/utils.ts'
 import { globalWxssFileName, writeHmrFile } from './hmr-files.ts'
 
+/** Final CSS extracted from Vite's transformed style module, before the shared WX compatibility pass. */
 type ProcessedStyle = Readonly<{
     css: string
+    /** Marks roots whose generated utilities must be refreshed when JavaScript changes Tailwind candidates. */
     isTailwindRoot: boolean
 }>
 
+/** Minimal structural view of DevEngine output; style reconciliation does not own chunks or other asset metadata. */
 type CompleteOutputFile =
     | Readonly<{ type: 'asset'; fileName: string; source: string | Uint8Array }>
     | Readonly<{ type: 'chunk'; fileName: string }>
@@ -25,10 +28,19 @@ export type StyleCaptureAction =
     | Readonly<{ kind: 'capture-style'; id: string; style: ProcessedStyle }>
 
 /**
- * Owns capture hooks, the host's style projection, and its physical WXSS publication frontier.
+ * Captures final Vite CSS and composes the graph projection with its durable WXSS publisher.
  *
- * Rolldown remains authoritative for topology through its live graph reader. Plugin hooks emit typed actions so the host can
- * serialize captures with every other effect; only the matching capture methods mutate this projection.
+ * Rolldown remains authoritative for topology. Plugin hooks emit typed actions so the host serializes capture mutations with
+ * output and HMR publication; the projection and publisher below each own only one mutable concern.
+ *
+ * Complete-build path:
+ *   final transform captures → DevEngine output write → graph reconciliation → App build rotation
+ *
+ * Incremental path:
+ *   final transform captures → optional Tailwind root refresh → graph rendering → WXSS write → JavaScript patch publication
+ *
+ * Both paths render the same ordered App/Page graph projection. This prevents complete builds and HMR from implementing two
+ * subtly different CSS ownership policies, while keeping physical byte equality and atomic writes out of graph state.
  */
 export function createStyleCapture({
     applicationEntryIds,
@@ -41,45 +53,23 @@ export function createStyleCapture({
     emit: (action: StyleCaptureAction) => void
     transformTailwindRoot: (rootId: string, requestId: string) => Promise<Readonly<{ code: string }> | null>
 }): Readonly<{
-    bindOutput: (output: readonly CompleteOutputFile[]) => void
     captureGraph: (reader: GetModuleInfo) => void
     captureStyle: (id: string, style: ProcessedStyle) => void
     plugin: Plugin
     publishChanged: (changedIds: readonly string[]) => Promise<void>
+    reconcileComplete: (output: readonly CompleteOutputFile[]) => Promise<void>
 }> {
-    /*
-     * This mutable capability is rebound by buildStart for each complete generation. Rolldown keeps the captured function live
-     * across incremental graph edits, so HMR traverses authoritative current topology without maintaining a shadow graph. It is
-     * undefined only before the first buildStart; retaining an older reader across a later complete build would bind transactions
-     * to the wrong engine generation, while snapshotting module data would require O(V + E) mutation on every edit.
-     */
-    let getModuleInfo: GetModuleInfo | undefined
-    /*
-     * This mutable Map is the CSS projection Rolldown does not retain: successful final transform hooks replace one module's
-     * processed bytes, failed transforms intentionally leave its last valid generation, and a successful multi-root Tailwind
-     * refresh commits all replacements only after every sibling resolves. Entries are not deleted when topology changes because
-     * reachability comes from the live graph plan; eager deletion would need a duplicate reverse graph and could remove CSS still
-     * shared by another App/Page root. Its size is bounded by style module identities seen during this server lifecycle.
-     */
-    const processedStyles = new Map<string, ProcessedStyle>()
-    /*
-     * This mutable value mirrors the WXSS bytes currently durable on disk. It has one owner but two real transition sources:
-     *
-     * 1. DevEngine physically writes complete output before onOutput, so bindOutput only observes and adopts that external
-     *    commit. An omitted asset means DevEngine preserved the existing file and this value must remain unchanged.
-     * 2. Incremental HMR is physically written by this host, so publishChanged advances the value only after its atomic write
-     *    succeeds (or after byte equality proves no write was needed).
-     *
-     * Combining these operations behind one generic update event would still require branching between “observe an existing
-     * write” and “perform a new write”, while hiding their different durability boundaries. A genuine single path would require
-     * preventing DevEngine from writing complete WXSS and transferring that entire output responsibility to the host, adding
-     * asset interception and ordering machinery. The two explicit methods are therefore the smallest accurate state model.
-     */
-    let publishedWxss: string | undefined
+    const projection = createStyleProjection({
+        applicationEntryIds: applicationEntryIds,
+        transformTailwindRoot: transformTailwindRoot
+    })
+    const publication = createStylePublication(outDir)
 
     const plugin: Plugin = {
         name: 'vpt:wx-dev-style-capture',
         buildStart() {
+            // Capture a live reader rather than a graph snapshot. Rolldown updates the capability as imports change, and a later
+            // complete generation replaces it through the host action queue before that generation can publish output.
             emit({ kind: 'capture-graph', getModuleInfo: (moduleId) => this.getModuleInfo(moduleId) })
         },
         transform(code, id) {
@@ -87,6 +77,8 @@ export function createStyleCapture({
                 return
             }
 
+            // This host plugin runs after Vite's CSS transform, so `code` is the JavaScript wrapper containing final PostCSS and
+            // CSS-Module output. Capturing source CSS instead would lose generated class names and framework transformations.
             const css = extractViteCss(code, id)
             emit({
                 kind: 'capture-style',
@@ -100,55 +92,132 @@ export function createStyleCapture({
     }
 
     return {
-        bindOutput(output) {
-            /*
-             * Complete output is one of the two real physical writers. Its emitted asset is therefore the authoritative frontier
-             * when present; omission means DevEngine preserved the existing file and this state must remain unchanged.
-             */
-            const style = output.find(
-                (file): file is Extract<CompleteOutputFile, { type: 'asset' }> =>
-                    file.type === 'asset' && file.fileName === globalWxssFileName
-            )
-            if (style) {
-                publishedWxss = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+        captureGraph: projection.captureGraph,
+        captureStyle: projection.captureStyle,
+        plugin: plugin,
+        async publishChanged(changedIds) {
+            // A CSS edit already carries updated processed bytes. Any non-CSS edit can alter both imports and Tailwind class
+            // candidates, so it requires a fresh graph plan and Tailwind-root generation even when no .css ID changed directly.
+            const styleChanged = changedIds.some(isGlobalStyleRequest)
+            const candidatesChanged = changedIds.some((id) => !isCSSRequest(id))
+            if (!styleChanged && !candidatesChanged) {
+                return
             }
+            await publication.publish(await projection.render(candidatesChanged))
         },
+        async reconcileComplete(output) {
+            // Bundled development can omit CSS Modules from the compiler asset even with cssCodeSplit disabled. Observe the
+            // physical output first, then reconcile the same graph projection used by incremental HMR before App rotation.
+            publication.observeOutput(output)
+            await publication.publish(await projection.render(false))
+        }
+    }
+}
+
+/**
+ * Owns the live graph capability and final transformed bytes for every observed style module.
+ *
+ * Rendering is O(V + E + C): graph planning visits each reachable module and edge once, then composition and WX conversion
+ * process C CSS bytes once. The only persistent memory is one processed byte string per style identity observed by the server.
+ */
+function createStyleProjection({
+    applicationEntryIds,
+    transformTailwindRoot
+}: {
+    applicationEntryIds: readonly string[]
+    transformTailwindRoot: (rootId: string, requestId: string) => Promise<Readonly<{ code: string }> | null>
+}): Readonly<{
+    captureGraph: (reader: GetModuleInfo) => void
+    captureStyle: (id: string, style: ProcessedStyle) => void
+    render: (refreshTailwind: boolean) => Promise<string>
+}> {
+    /*
+     * This mutable capability is rebound by buildStart for each complete generation. Rolldown keeps the function live across
+     * incremental graph edits, so rendering uses authoritative topology without maintaining a shadow graph.
+     */
+    let getModuleInfo: GetModuleInfo | undefined
+    /*
+     * This mutable projection stores final CSS bytes that Rolldown does not retain. Successful transforms replace one entry;
+     * unreachable entries can remain because every render filters them through the current graph plan. Its size is bounded by
+     * style module identities observed during this server lifecycle.
+     */
+    const processedStyles = new Map<string, ProcessedStyle>()
+
+    return {
         captureGraph(reader) {
             getModuleInfo = reader
         },
         captureStyle(id, style) {
             processedStyles.set(id, style)
         },
-        plugin: plugin,
-        async publishChanged(changedIds) {
-            const styleChanged = changedIds.some(isGlobalStyleRequest)
-            const candidatesChanged = changedIds.some((id) => !isCSSRequest(id))
-            if (!styleChanged && !candidatesChanged) {
-                return
-            }
+        async render(refreshTailwind) {
             if (!getModuleInfo) {
-                throw new Error('WX style graph is unavailable before HMR publication')
+                throw new Error('WX style graph is unavailable before publication')
             }
 
-            // Traverse topology exactly once; root refresh and final rendering consume this immutable transaction plan.
+            // App first and configured Pages afterward define one deterministic global cascade. The plan also removes stale map
+            // entries implicitly: styles no longer reachable from these roots never enter composition.
             const styleIds = createGraphStylePlan(applicationEntryIds, getModuleInfo, (styleId) =>
                 processedStyles.has(styleId)
             )
-            if (candidatesChanged) {
+            if (refreshTailwind) {
                 await refreshTailwindStyles(styleIds, processedStyles, transformTailwindRoot)
             }
+
+            // Compose browser-facing transformed CSS first, then run one whole-file WX pass. Transforming modules independently
+            // would change cross-module cascade behavior and duplicate compatibility work.
             const css = composeGraphStyleCss(styleIds, (styleId) => requireProcessedStyle(processedStyles, styleId).css)
-            const wxss = (await transformWxStyle(css)).css
+            return (await transformWxStyle(css)).css
+        }
+    }
+}
+
+/**
+ * Owns the physical WXSS frontier independently from graph capture and rendering.
+ *
+ * DevEngine writes complete output itself; incremental HMR does not. Observing complete output before publishing the projection
+ * gives both writers one byte frontier, so equality avoids redundant filesystem notifications without pretending the host owns
+ * the compiler's write transaction.
+ */
+function createStylePublication(outDir: string): Readonly<{
+    observeOutput: (output: readonly CompleteOutputFile[]) => void
+    publish: (wxss: string) => Promise<void>
+}> {
+    /*
+     * This mutable value mirrors bytes durable on disk. Complete output adopts the compiler's external write before graph
+     * reconciliation; host publication advances it only after an atomic write succeeds or byte equality proves none is needed.
+     */
+    let publishedWxss: string | undefined
+
+    return {
+        observeOutput(output) {
+            // Missing WXSS means DevEngine intentionally reused the existing physical asset. Do not reset the frontier: doing so
+            // would force an identical rewrite and a spurious DevTools style event on every omitted complete generation.
+            const style = output.find(
+                (file): file is Extract<CompleteOutputFile, { type: 'asset' }> =>
+                    file.type === 'asset' && file.fileName === globalWxssFileName
+            )
+            if (style) {
+                publishedWxss = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+            }
+        },
+        async publish(wxss) {
             if (wxss !== publishedWxss) {
+                // writeHmrFile uses atomic replacement; advance the frontier only after durability so a failed write leaves the
+                // last known physical generation available for the next reconciliation attempt.
                 await writeHmrFile(outDir, globalWxssFileName, wxss)
             }
-            // HMR is the second physical writer; advance the frontier only after its atomic write succeeds or was unnecessary.
             publishedWxss = wxss
         }
     }
 }
 
-/** Regenerates all reachable Tailwind roots and commits the cache only when every transform succeeds. */
+/**
+ * Regenerates all reachable Tailwind roots and commits the cache only when every transform succeeds.
+ *
+ * Roots run concurrently because they are independent derivations of the same candidate generation. Results remain local until
+ * Promise.all fulfills; one failed root therefore preserves every prior root together instead of publishing a mixed generation.
+ */
 async function refreshTailwindStyles(
     styleIds: readonly string[],
     processedStyles: Map<string, ProcessedStyle>,

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

@@ -5,7 +5,7 @@ import colors from 'picocolors'
 import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
 import { asyncScheduler } from 'rxjs'
 import type { Connect, ViteDevServer } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { createHmrResultsStream } from './create-hmr-results-stream.ts'
 import { createStyleCapture, type StyleCaptureAction } from './create-style-capture.ts'
 import {
@@ -44,7 +44,7 @@ type HostAction =
     | Readonly<{ kind: 'listening' }>
 
 /** One short trailing-edge window absorbs editor bursts before style preparation and physical Page notification. */
-const hmrSettleMilliseconds = 32
+const hmrSettleMilliseconds = 16
 
 /**
  * Creates the wx dev host: the adapter that owns the physical Rolldown DevEngine (created
@@ -61,7 +61,7 @@ export async function createWxDevHost({
     applicationEntryIds
 }: {
     server: ViteDevServer
-    options: VitePluginTaroOptions
+    options: VptOptions
     applicationEntryIds: readonly string[]
 }): Promise<WxDevHost> {
     const bundledDev = getBundledDev(server)
@@ -228,13 +228,24 @@ export async function createWxDevHost({
                     logWxError(server.config.logger, 'wx dev build failed', action.result)
                     return
                 }
-                styleCapture.bindOutput(action.result.output)
-                return rotateBuildSession()
+                return reconcileCompleteOutput(action.result.output)
             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)
+        await rotateBuildSession()
+    }
+
     /** Applies one runtime receipt to the active physical patch history. */
     function processReport(report: RuntimeReport): void {
         // Delayed reports from older builds must never prune the live build's cumulative patch history.

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

@@ -1,5 +1,5 @@
 import { normalizePath, type PluginOption, transformWithOxc } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { esTarget } from '../../../utils/constant.ts'
 import { memoize } from '../../../utils/memoize.ts'
 import { normalizeModuleId } from '../../../utils/modules.ts'
@@ -22,10 +22,7 @@ export function isWxClientEnvironment(environment: Readonly<{ name: string }>):
  * 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.
  */
-export function createWxDevelopmentPlugin(
-    options: VitePluginTaroOptions,
-    applicationEntryIds: readonly string[]
-): PluginOption[] {
+export function createWxDevelopmentPlugin(options: VptOptions, applicationEntryIds: readonly string[]): 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

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

@@ -3,7 +3,7 @@ import type { InputOptions, OutputOptions, Plugin } from 'rolldown'
 import { build } from 'rolldown'
 import { type DevEngine, viteReporterPlugin } from 'rolldown/experimental'
 import type { ViteDevServer } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { once } from '../../../utils/once.ts'
 import { resolvePackageFile } from '../../../utils/packages.ts'
 import { appShellFileName } from '../module.ts'
@@ -35,7 +35,7 @@ export function installWxDevOptions({
 }: {
     bundledDev: BundledDev
     server: ViteDevServer
-    options: VitePluginTaroOptions
+    options: VptOptions
     hostPlugins: Plugin[]
 }): void {
     /*

package/src/node/plugins/wx/output/files.ts

@@ -1,5 +1,5 @@
 import type { Rolldown } from 'vite'
-import type { VitePluginTaroOptions } from '../../../../options.ts'
+import type { VptOptions } from '../../../../options.ts'
 import { createNativeComponentOutput } from '../native/create-native-component-output.ts'
 import type { GeneratedSubpackage } from '../placement/placer.ts'
 import { createJsonAssets } from './json.ts'
@@ -13,7 +13,7 @@ export async function createOutputFiles({
     getModuleInfo
 }: {
     bundle: Rolldown.OutputBundle
-    options: VitePluginTaroOptions
+    options: VptOptions
     subpackages: readonly GeneratedSubpackage[]
     getModuleInfo: (moduleId: string) => { meta: Rolldown.CustomPluginOptions } | null
 }): Promise<Rolldown.EmittedFile[]> {