vite-plugin-taro 0.5.14 → 0.5.16

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

@@ -1,8 +1,11 @@
 import type { GetModuleInfo, Plugin } from 'rolldown';
+/** 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;
@@ -20,10 +23,19 @@ export type StyleCaptureAction = Readonly<{
     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 declare function createStyleCapture({ applicationEntryIds, outDir, emit, transformTailwindRoot }: {
     applicationEntryIds: readonly string[];
@@ -33,10 +45,10 @@ export declare function createStyleCapture({ applicationEntryIds, outDir, emit,
         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>;
 }>;
 export {};

package/dist/node/plugins/wx/dev/create-style-capture.js

@@ -4,50 +4,39 @@ import { transformWxStyle } from '../styles/transform-wx-style.js';
 import { composeGraphStyleCss, createGraphStylePlan, createTailwindSidecarId, extractViteCss, isGlobalStyleRequest } from '../styles/utils.js';
 import { globalWxssFileName, writeHmrFile } from './hmr-files.js';
 /**
- * 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, outDir, emit, transformTailwindRoot }) {
-    /*
-     * 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;
-    /*
-     * 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();
-    /*
-     * 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;
+    const projection = createStyleProjection({
+        applicationEntryIds: applicationEntryIds,
+        transformTailwindRoot: transformTailwindRoot
+    });
+    const publication = createStylePublication(outDir);
     const 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) {
             if (!isGlobalStyleRequest(id)) {
                 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',
@@ -60,48 +49,107 @@ export function createStyleCapture({ applicationEntryIds, outDir, emit, transfor
         }
     };
     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.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 }) {
+    /*
+     * 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;
+    /*
+     * 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();
+    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) {
+    /*
+     * 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;
+    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.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, processedStyles, transformRoot) {
     const roots = styleIds.filter((styleId) => requireProcessedStyle(processedStyles, styleId).isTailwindRoot);
     const refreshedStyles = await Promise.all(roots.map(async (rootId) => {

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

@@ -11,7 +11,7 @@ import { PatchPublisher } from './patch-publisher.js';
 import { createRuntimeReportsStream } from './runtime-reports.js';
 import { installWxDevOptions, requireSingleOutput } from './wx-dev-options.js';
 /** 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
  * with dev(...)) and the patch publisher, and replaces Vite's bundledDev.listen so the
@@ -163,12 +163,22 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
                     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) {
+        await styleCapture.reconcileComplete(output);
+        await rotateBuildSession();
+    }
     /** Applies one runtime receipt to the active physical patch history. */
     function processReport(report) {
         // Delayed reports from older builds must never prune the live build's cumulative patch history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "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/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.16",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.16"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -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
@@ -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.