vite-plugin-taro 0.5.13 → 0.5.14

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

@@ -2,14 +2,16 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import colors from 'picocolors';
 import { dev } from 'rolldown/experimental';
-import { isCSSRequest } from 'vite';
-import { SerializedTaskQueue } from '../../../utils/serialized-task-queue.js';
-import { createGraphStylePlan, isGlobalStyleRequest } from '../styles/utils.js';
+import { asyncScheduler } from 'rxjs';
+import { createHmrResultsStream } from './create-hmr-results-stream.js';
+import { createStyleCapture } from './create-style-capture.js';
 import { developmentAppWxssFileName, hmrControlPath, hmrInfoFileName, hmrPatchesFileName, renderDevelopmentAppWxss, renderHmrInfo, renderInitialHmrPatches, writeHmrFile } from './hmr-files.js';
+import { createHostActions } from './host-actions.js';
 import { PatchPublisher } from './patch-publisher.js';
-import { createStyleCapturePlugin } from './styles/create-style-capture-plugin.js';
-import { globalWxssFileName, publishStyleHmr, refreshTailwindStyles } from './styles/publish-style-hmr.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;
 /**
  * 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
@@ -21,45 +23,70 @@ import { installWxDevOptions, requireSingleOutput } from './wx-dev-options.js';
  */
 export async function createWxDevHost({ server, options, applicationEntryIds }) {
     const bundledDev = getBundledDev(server);
-    // This is the host's mutable style projection: CSS absent from Rolldown, the live graph capability rebound by each
-    // complete build, and the last durable WXSS bytes used only to suppress identical filesystem publications. Style capture
-    // remains O(1); derived order and reachability stay local to each HMR transaction.
-    const styleState = {
-        getModuleInfo: undefined,
-        processedStyles: new Map(),
-        publishedWxss: undefined
-    };
-    const styleCapturePlugin = createStyleCapturePlugin({
-        captureGraph(reader) {
-            styleState.getModuleInfo = reader;
-        },
-        captureStyle(id, style) {
-            styleState.processedStyles.set(id, style);
+    // All callbacks admit typed actions through this edge; concatMap is the sole owner of effect ordering and mutable host state.
+    const hostActions = createHostActions(applyHostAction, (action, error) => logWxError(server.config.logger, `wx HMR ${action.kind} failed`, error));
+    const styleCapture = createStyleCapture({
+        applicationEntryIds: applicationEntryIds,
+        outDir: server.config.build.outDir,
+        // Capture hooks run only after engine.run, when the host action subscription and all reducer dependencies are ready.
+        emit: (action) => hostActions.next(action),
+        transformTailwindRoot: async (rootId, requestId) => {
+            // The capture contains generated CSS, while the sidecar must re-run from raw Tailwind directives. Vite exposes no
+            // raw source in its live module graph, so this read is the authoritative source generation rather than a read-back.
+            return server.environments.client.pluginContainer.transform(await readFile(rootId, 'utf8'), requestId);
         }
     });
-    // Rolldown invokes output callbacks without awaiting their promises. This queue is the single owner of mutable HMR host
-    // state and physical metadata writes, preventing a later patch or build identity from being overwritten by older work.
-    const hostTasks = new SerializedTaskQueue((operation, error) => logWxError(server.config.logger, operation, error));
     const publisher = new PatchPublisher((content) => writeHmrFile(server.config.build.outDir, hmrPatchesFileName, content));
-    // DevEngine does not reject run() after an initial plugin failure. The options layer owns a first-build buildEnd barrier
-    // and exposes only its result; later build errors continue independently through onOutput and onHmrUpdates.
-    const initialBuild = installWxDevOptions({ bundledDev, server, options, hostPlugins: [styleCapturePlugin] });
+    // Option installation now configures only Rolldown. Build lifecycle results enter through the engine's output action below.
+    installWxDevOptions({ bundledDev, server, options, hostPlugins: [styleCapture.plugin] });
     const engine = await createEngine();
-    // The wx dev host owns the only DevEngine. Vite's default listen() would create a second
-    // skip-write engine that renders into memory for browser HMR; instead the physical
-    // engine's initial build must finish before the HTTP server becomes ready, because
-    // DevTools opens the output directory directly and the app requires its files on disk.
+    const hmrResults = createHmrResultsStream(hmrSettleMilliseconds, asyncScheduler, (result) => {
+        // One reduced window becomes one existing host transaction: style preparation, one cumulative patch write, then
+        // ordered delivery notifications for every original Rolldown payload retained by the stream.
+        hostActions.next({ kind: 'publish', result: result });
+    }, (error) => {
+        /*
+         * Invalid syntax is a normal intermediate editor generation. Rolldown produced no patch, so neither the published
+         * nor applied runtime frontier needs repair. Triggering a complete build here would immediately compile the same
+         * invalid source and empirically wedges that DevEngine generation. Admit only the diagnostic; when the user saves
+         * valid source, the watch engine emits an ordinary successful callback and resumes the normal publication path.
+         */
+        hostActions.next({ kind: 'error', error: error });
+    });
+    const runtimeReports = createRuntimeReportsStream(hmrSettleMilliseconds, asyncScheduler, (reports) => {
+        // ACK conflation happens before admission, but publisher validation and mutation remain ordered with patch writes and
+        // build rotation. Reports arriving during publication therefore execute only after that physical transaction commits.
+        hostActions.next({ kind: 'reports', reports: reports });
+    });
+    /*
+     * BundledDev is Vite's mutable environment adapter. Transfer its engine slot to the one physical writer created above so
+     * Vite middleware and close() address the same engine; leaving the slot untouched would make listen() create a second,
+     * skip-write browser engine with a divergent graph. Disable Vite's access-triggered regeneration because runtime reports and
+     * Rolldown HMR results now own every rebuild decision. Finally replace listen so readiness waits for physical initial output
+     * instead of Vite's in-memory bundle. These assignments are installation-time ownership transfer, never per-update state.
+     */
     bundledDev._devEngine = engine;
     bundledDev.triggerBundleRegenerationIfStale = async () => false;
     bundledDev.listen = async () => {
-        await Promise.all([engine.run(), initialBuild]);
+        /*
+         * Subscribe before run because DevEngine intentionally fulfills run() after an initial plugin failure and emits that
+         * Error through onOutput. Observing the existing action edge preserves the exact failure without a second buildEnd
+         * Promise or forwarding Subject; waitForAction does not consume the action from concatMap's reducer subscription.
+         */
+        const initialOutput = hostActions.waitForAction((action) => action.kind === 'output');
+        await engine.run();
+        const { result } = await initialOutput;
+        if (result instanceof Error) {
+            throw result;
+        }
         await engine.ensureCurrentBuildFinish();
     };
     // Vite binds the port only after initServer (and therefore the initial build) completes, so
     // the actual port is not observable while onOutput runs for the first build. The App metadata
     // is written once the port is real; later full builds rewrite it from onOutput.
     server.httpServer?.once('listening', () => {
-        hostTasks.enqueue('wx HMR initialization failed', rotateBuildSession);
+        // Port availability is lifecycle data, so initial identity rotation follows prior output/capture actions in the reducer.
+        hostActions.next({ kind: 'listening' });
     });
     // The runtime's metadata-only reports land on the control path; the buildId in each report
     // IS the Rolldown client ID.
@@ -67,8 +94,13 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
     installDevToolsPrinter(server);
     return {
         close: async () => {
-            await hostTasks.waitForIdle();
-            await engine.close();
+            // Quiet-window completion first admits final HMR publications and rebuild reports into the serialized action edge.
+            hmrResults.complete();
+            runtimeReports.complete();
+            await hostActions.waitForIdle();
+            // Keep the action edge open until the final generation has admitted all capture and output callbacks.
+            await engine.ensureCurrentBuildFinish();
+            await hostActions.complete();
         }
     };
     /** Rotates the build identity and materializes the App metadata for it. */
@@ -86,6 +118,10 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
         await engine.registerClient(buildId);
         await publishBuildMetadata(server, buildId, port);
     }
+    /**
+     * Mutates only the request-local HTTP response: unsupported methods become 404, malformed bounded bodies become 400, and a
+     * valid report is admitted before the default 200 response ends. No response object or parser state crosses requests.
+     */
     async function handleReport(req, res) {
         if (req.method !== 'POST') {
             res.statusCode = 404;
@@ -94,7 +130,7 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
         }
         try {
             const report = JSON.parse(await readBody(req));
-            await hostTasks.run(() => processReport(report));
+            runtimeReports.next(report);
             res.end();
         }
         catch (e) {
@@ -103,6 +139,36 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
             res.end();
         }
     }
+    /** Reduces one merged source action through the existing authoritative host state. */
+    function applyHostAction(action) {
+        switch (action.kind) {
+            case 'capture-graph':
+                // The buildStart reader is a live capability; replacing it only here makes the reducer own build rebinding.
+                styleCapture.captureGraph(action.getModuleInfo);
+                return;
+            case 'capture-style':
+                // A failed upstream transform emits no action, intentionally retaining the last valid processed CSS generation.
+                styleCapture.captureStyle(action.id, action.style);
+                return;
+            case 'publish':
+                return publishUpdates(action.result);
+            case 'error':
+                logWxError(server.config.logger, 'wx HMR update failed', action.error);
+                return;
+            case 'reports':
+                action.reports.forEach(processReport);
+                return;
+            case 'output':
+                if (action.result instanceof Error) {
+                    logWxError(server.config.logger, 'wx dev build failed', action.result);
+                    return;
+                }
+                styleCapture.bindOutput(action.result.output);
+                return rotateBuildSession();
+            case 'listening':
+                return 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.
@@ -111,8 +177,7 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
         }
         switch (report.kind) {
             case 'rebuild': {
-                server.config.logger.info(`[vpt] wx runtime requested a full rebuild: ${report.reason}`);
-                engine.triggerFullBuild();
+                requestFullBuild(report.reason);
                 return;
             }
             case 'applied': {
@@ -126,73 +191,67 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
         const rolldownOptions = await bundledDev.getRolldownOptions();
         const output = requireSingleOutput(rolldownOptions);
         return dev(rolldownOptions, output, {
-            onHmrUpdates: handleHmrUpdates,
-            onOutput: handleDevOutput,
+            /**
+             * Admits Rolldown's non-awaited callback without starting asynchronous host work on the binding callback stack.
+             * The Subject retains Error values as control events and successful values as lossless patch data until its quiet edge.
+             */
+            onHmrUpdates: (result) => {
+                hmrResults.next(result);
+            },
+            // Initial and later complete builds share one admission path; startup merely observes the first OutputAction.
+            onOutput: (result) => {
+                hostActions.next({ kind: 'output', result: result });
+            },
             rebuildStrategy: 'never',
-            watch: { skipWrite: false }
+            watch: {
+                // Rolldown must observe every source generation and emit every incremental factory: later patches do not
+                // reconstruct modules changed only by an earlier callback. RxJS conflates publication after compilation,
+                // preserving the complete patch sequence while avoiding repeated physical DevTools notifications.
+                skipWrite: false,
+                useDebounce: false
+            }
         });
     }
-    /** Converts Rolldown's non-awaited callback into one ordered host publication task. */
-    function handleHmrUpdates(result) {
-        if (result instanceof Error) {
-            logWxError(server.config.logger, 'wx HMR update failed', result);
-            return;
-        }
-        hostTasks.enqueue('wx HMR publication failed', () => publishUpdates(result));
+    /** Centralizes the one diagnostic and DevEngine command used by every rebuild authority. */
+    function requestFullBuild(reason) {
+        server.config.logger.info(`[vpt] wx full rebuild required${reason ? `: ${reason}` : ''}`);
+        engine.triggerFullBuild();
     }
-    /** Publishes only the active client's patches or requests the complete build required by Rolldown. */
+    /** Selects active updates and publishes their resulting host transaction. */
     async function publishUpdates(result) {
-        const batch = [];
+        /*
+         * This transaction-local array preserves every patch in one pass and permits immediate rebuild dominance. It never escapes
+         * the serialized action. A filter/find/flatMap pipeline would scan a large burst repeatedly and allocate an intermediate.
+         */
+        const patches = [];
         for (const { clientId, update } of result.updates) {
             if (!publisher.isCurrentBuild(clientId) || update.type === 'Noop') {
                 continue;
             }
             if (update.type === 'Patch') {
-                batch.push(update);
+                patches.push(update);
                 continue;
             }
-            server.config.logger.info(`[vpt] wx full rebuild required${update.reason ? `: ${update.reason}` : ''}`);
-            engine.triggerFullBuild();
+            requestFullBuild(update.reason);
             return;
         }
-        if (batch.length === 0) {
+        await publishPatchBatch(patches);
+    }
+    /** Publishes one coherent WXSS, patch-file, and Rolldown-frontier transaction. */
+    async function publishPatchBatch(patches) {
+        if (patches.length === 0) {
             return;
         }
         // `onHmrUpdates` is the transaction boundary after every affected transform has updated graph and candidate state.
         // Every non-CSS edit may alter imports or Tailwind classes; rendering broadly and comparing finalized bytes avoids
         // source scanning while preventing unrelated JavaScript edits from notifying DevTools through an identical rename.
-        await publishChangedStyles(batch);
+        await styleCapture.publishChanged(patches.flatMap((patch) => patch.changedIds));
         // 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(batch);
-        await commitPublishedBatch(batch);
-    }
-    /** Publishes the style projection for one completed patch transaction when its source or topology may have changed. */
-    async function publishChangedStyles(batch) {
-        const changedIds = batch.flatMap((patch) => patch.changedIds);
-        const styleChanged = changedIds.some(isGlobalStyleRequest);
-        const candidatesChanged = changedIds.some((id) => !isCSSRequest(id));
-        if (!styleChanged && !candidatesChanged) {
-            return;
-        }
-        // buildStart installs this reader before Rolldown can produce either a complete output or an incremental batch.
-        const getModuleInfo = styleState.getModuleInfo;
-        if (!getModuleInfo) {
-            throw new Error('WX style graph is unavailable before HMR publication');
-        }
-        // Traverse topology exactly once; root refresh and final rendering consume this immutable transaction plan.
-        const styleIds = createGraphStylePlan(applicationEntryIds, getModuleInfo, (styleId) => styleState.processedStyles.has(styleId));
-        if (candidatesChanged) {
-            await refreshTailwindStyles(styleIds, styleState.processedStyles, async (rootId, requestId) => server.environments.client.pluginContainer.transform(await readFile(rootId, 'utf8'), requestId));
-        }
-        styleState.publishedWxss = await publishStyleHmr({
-            styleIds: styleIds,
-            outDir: server.config.build.outDir,
-            processedStyles: styleState.processedStyles,
-            publishedWxss: styleState.publishedWxss
-        });
+        await publisher.produce(patches);
+        await commitPublishedBatch(patches);
     }
     /**
      * Advances Rolldown's published frontier in the same sequence order materialized in the cumulative physical file.
@@ -209,19 +268,6 @@ export async function createWxDevHost({ server, options, applicationEntryIds })
             await engine.notifyPayloadDelivered(patch.filename);
         }
     }
-    /** Rotates metadata after each successful complete output. */
-    function handleDevOutput(result) {
-        if (result instanceof Error) {
-            logWxError(server.config.logger, 'wx dev build failed', result);
-            return;
-        }
-        hostTasks.enqueue('wx dev build finalization failed', finalizeDevOutput);
-    }
-    /** Rebinds the byte frontier after a complete build replaces the physical stylesheet outside HMR publication. */
-    async function finalizeDevOutput() {
-        styleState.publishedWxss = await readFile(path.join(server.config.build.outDir, globalWxssFileName), 'utf8');
-        await rotateBuildSession();
-    }
 }
 /** The bound HTTP port, or undefined before Vite's server is listening. */
 function boundPort(server) {
@@ -252,6 +298,12 @@ async function publishBuildMetadata(server, buildId, port) {
 }
 /** Replaces browser server URLs with the physical project directory consumed by WeChat DevTools. */
 function installDevToolsPrinter(server) {
+    /*
+     * Vite exposes printing as a mutable server callback because URLs are unknown until startup. WX serves control reports over
+     * HTTP but users open the physical output directory, so retaining the browser printer advertises unusable navigation URLs.
+     * Replacing only this presentation callback leaves resolved URLs and server routing untouched and naturally dies with the
+     * server instance; logging elsewhere would duplicate Vite's one readiness notification.
+     */
     server.printUrls = () => {
         server.config.logger.info(`  ${colors.green('➜')}  ${colors.bold('WeChat DevTools')}: ${colors.cyan(relativeToViteConfig(server.config.build.outDir, server.config.configFile, server.config.root))}`);
     };
@@ -279,6 +331,12 @@ function logWxError(logger, prefix, error) {
 const maximumBodyBytes = 64 * 1024;
 function readBody(req) {
     return new Promise((resolve, reject) => {
+        /*
+         * Node delivers one HTTP body through multiple callback invocations, so this request-local mutable string is the minimal
+         * state that joins chunks in wire order. The 64 KiB bound caps both retained memory and repeated-concatenation work; the
+         * value is parsed once on end and then discarded. Parsing per chunk is invalid because JSON tokens may cross boundaries,
+         * while retaining request bodies in host state would couple unrelated Page reports and leak across the server lifecycle.
+         */
         let body = '';
         req.on('data', (chunk) => {
             body += chunk.toString('utf8');

package/dist/node/plugins/wx/dev/hmr-files.d.ts

@@ -1,5 +1,6 @@
 import type { BindingClientHmrUpdate } from 'rolldown/experimental';
 export declare const developmentAppWxssFileName = "app.wxss";
+export declare const globalWxssFileName = "assets/global.wxss";
 export declare const hmrInfoFileName = "hmr/info.js";
 export declare const hmrPatchesFileName = "hmr/patches.js";
 /** Report endpoint path served by the wx dev control edge. */

package/dist/node/plugins/wx/dev/hmr-files.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 export const developmentAppWxssFileName = 'app.wxss';
+export const globalWxssFileName = 'assets/global.wxss';
 export const hmrInfoFileName = 'hmr/info.js';
 export const hmrPatchesFileName = 'hmr/patches.js';
 /** Report endpoint path served by the wx dev control edge. */

package/dist/node/plugins/wx/dev/host-actions.d.ts

@@ -0,0 +1,16 @@
+export type HostActions<Action> = Readonly<{
+    complete: () => Promise<void>;
+    next: (action: Action) => void;
+    waitForAction: <Selected extends Action>(select: (action: Action) => action is Selected) => Promise<Selected>;
+    waitForIdle: () => Promise<void>;
+}>;
+/**
+ * Executes semantic host actions one at a time while keeping source admission synchronous.
+ *
+ * `concatMap` is the sole effect serializer: each deferred reducer call starts only after the prior Promise settles. Errors are
+ * converted to empty inner streams so one failed physical transaction is reported without terminating later host actions.
+ * Barrier envelopes participate in the same ordering but run no effect; resolving one proves every action admitted before it
+ * has settled. `waitForAction` observes this same admission edge for lifecycle gates without introducing a forwarding Subject.
+ * Completing the source drains already-admitted effects and gives shutdown one Promise for final quiescence.
+ */
+export declare function createHostActions<Action>(apply: (action: Action) => void | Promise<void>, reportError: (action: Action, error: unknown) => void): HostActions<Action>;

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

@@ -0,0 +1,58 @@
+import { catchError, concatMap, defer, EMPTY, filter, firstValueFrom, lastValueFrom, map, Subject } from 'rxjs';
+/**
+ * Executes semantic host actions one at a time while keeping source admission synchronous.
+ *
+ * `concatMap` is the sole effect serializer: each deferred reducer call starts only after the prior Promise settles. Errors are
+ * converted to empty inner streams so one failed physical transaction is reported without terminating later host actions.
+ * Barrier envelopes participate in the same ordering but run no effect; resolving one proves every action admitted before it
+ * has settled. `waitForAction` observes this same admission edge for lifecycle gates without introducing a forwarding Subject.
+ * Completing the source drains already-admitted effects and gives shutdown one Promise for final quiescence.
+ */
+export function createHostActions(apply, reportError) {
+    /*
+     * This Subject is the host's only mutable admission edge. Independent callback stacks synchronously append semantic actions
+     * or barriers; concatMap owns the queued ordering and admits exactly one asynchronous effect at a time. A Promise chain would
+     * require mutation at every producer and is permanently rejected after one failure, while mergeMap could overlap physical
+     * writes and build rotation. The Subject retains no business frontier itself and is completed only after all external sources
+     * are quiescent, allowing lastValueFrom to prove the final queued effect settled.
+     */
+    const envelopes = new Subject();
+    const completion = lastValueFrom(envelopes.pipe(concatMap((envelope) => {
+        if (envelope.kind === 'barrier') {
+            return defer(() => {
+                envelope.resolve();
+                return EMPTY;
+            });
+        }
+        return defer(() => Promise.resolve(apply(envelope.action))).pipe(catchError((error) => {
+            reportError(envelope.action, error);
+            return EMPTY;
+        }));
+    })), { defaultValue: undefined });
+    return {
+        complete: async () => {
+            envelopes.complete();
+            await completion;
+        },
+        next(action) {
+            envelopes.next({ kind: 'action', action: action });
+        },
+        waitForAction(select) {
+            /*
+             * Subscribe to the multicast admission Subject rather than creating another lifecycle source. Barrier envelopes are
+             * internal ordering controls, so expose only semantic actions and let the caller's type guard select its milestone.
+             * firstValueFrom unsubscribes after the match; concatMap's independent subscription still applies the same action.
+             */
+            return firstValueFrom(envelopes.pipe(filter((envelope) => envelope.kind === 'action'), map((envelope) => envelope.action), filter(select)));
+        },
+        waitForIdle() {
+            /*
+             * The resolver is one transaction-local mutable latch. Enqueuing it behind ordinary actions makes resolution mean
+             * every earlier effect settled, without completing the shared source needed by final DevEngine output callbacks.
+             */
+            const barrier = Promise.withResolvers();
+            envelopes.next({ kind: 'barrier', resolve: barrier.resolve });
+            return barrier.promise;
+        }
+    };
+}

package/dist/node/plugins/wx/dev/patch-publisher.d.ts

@@ -1,6 +1,6 @@
 import { type PatchUpdate } from './hmr-files.ts';
 /** Abstracts the physical patches write; the engine owns the file destination. */
-export type WritePatches = (content: string) => Promise<void>;
+type WritePatches = (content: string) => Promise<void>;
 /**
  * Owns the cumulative sequence range between the host's published frontier and the runtime's applied frontier.
  *
@@ -17,7 +17,6 @@ export type WritePatches = (content: string) => Promise<void>;
 export declare class PatchPublisher {
     private readonly writePatches;
     private buildId;
-    /** Executable updates retained until the runtime confirms successful application. */
     private readonly pendingPatches;
     constructor(writePatches: WritePatches);
     /** True when the buildId belongs to the current full build. */
@@ -40,3 +39,4 @@ export declare class PatchPublisher {
      */
     acknowledge(seq: number): void;
 }
+export {};

package/dist/node/plugins/wx/dev/patch-publisher.js

@@ -15,8 +15,20 @@ import { renderHmrPatches } from './hmr-files.js';
  */
 export class PatchPublisher {
     writePatches;
+    /*
+     * This mutable identity is the sole session authority for runtime reports and per-client Rolldown updates. startBuild rotates
+     * it only after a successful complete output reaches the serialized host reducer. Delayed reports retain their original ID
+     * and therefore fail isCurrentBuild instead of pruning or rebuilding the new session. An immutable constructor value cannot
+     * represent full-build rotation, while deriving identity from patches would leave empty builds without a client ID.
+     */
     buildId;
-    /** Executable updates retained until the runtime confirms successful application. */
+    /*
+     * This mutable ordered suffix bridges two independent frontiers: Rolldown payloads become published immediately after the
+     * cumulative file is durable, but entries remain here until the runtime acknowledges applying their sequence. Appending is
+     * lossless because later patches are deltas; prefix removal is the only valid mutation because acknowledgements are monotonic
+     * frontiers. A Set, latest-only value, or immutable reconstruction would either lose duplicate filenames/order or copy the
+     * complete unapplied history for every burst.
+     */
     pendingPatches = [];
     // Explicit field assignment: node --test strips types and does not support parameter properties.
     constructor(writePatches) {
@@ -52,6 +64,10 @@ export class PatchPublisher {
      * retaining the gap between published and applied frontiers is what lets DevTools safely miss intermediate file events.
      */
     acknowledge(seq) {
+        /*
+         * This local counter scans the monotonic prefix without allocating or invoking a callback for each patch. It exists only
+         * long enough to supply splice's prefix length; pendingPatches remains the sole durable frontier and is mutated once.
+         */
         let appliedCount = 0;
         while (appliedCount < this.pendingPatches.length && this.pendingPatches[appliedCount].seq <= seq) {
             appliedCount++;

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

@@ -1,5 +1,9 @@
 import { type PluginOption } from 'vite';
 import type { VitePluginTaroOptions } from '../../../../options.ts';
+/** Selects the sole Vite environment that owns the physical Mini Program development project. */
+export declare function isWxClientEnvironment(environment: Readonly<{
+    name: string;
+}>): boolean;
 /**
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.

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

@@ -1,4 +1,4 @@
-import { transformWithOxc } from 'vite';
+import { normalizePath, transformWithOxc } from 'vite';
 import { esTarget } from '../../../utils/constant.js';
 import { memoize } from '../../../utils/memoize.js';
 import { normalizeModuleId } from '../../../utils/modules.js';
@@ -7,6 +7,10 @@ import { createWxDevHost } from './dev-host.js';
 import { developmentAppWxssFileName } from './hmr-files.js';
 import { createWxReactRefreshTransforms } from './react-refresh.js';
 const taroRuntimeId = '@tarojs/runtime';
+/** Selects the sole Vite environment that owns the physical Mini Program development project. */
+export function isWxClientEnvironment(environment) {
+    return environment.name === 'client';
+}
 /**
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.
@@ -15,16 +19,25 @@ const taroRuntimeId = '@tarojs/runtime';
  * reconstructing the resolver's App/Page ownership policy from unrelated Rolldown shell and transport entries.
  */
 export function createWxDevelopmentPlugin(options, applicationEntryIds) {
-    // This mutable handle transfers ownership from configureServer to closeBundle; at most one host exists per plugin instance.
+    /*
+     * 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
+     * assigns it after asynchronous construction, and closeBundle reads it to drain the same engine. Environment scoping ensures
+     * only the client hook pair participates. Capturing a construction Promise would start too early, while recreating the host
+     * in closeBundle would lose every live action, patch, style, and client frontier owned by the running instance.
+     */
     let host = null;
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
-    const normalizedAppCapsulePath = normalizeModuleId(appCapsulePath);
-    const normalizedPageCapsulePath = normalizeModuleId(pageCapsulePath);
-    const normalizedTaroRuntimePath = normalizeModuleId(taroRuntimePath);
+    const normalizedAppCapsulePath = normalizePath(appCapsulePath);
+    const normalizedPageCapsulePath = normalizePath(pageCapsulePath);
+    const normalizedTaroRuntimePath = normalizePath(taroRuntimePath);
     return [
         {
             name: 'vpt:wx-dev',
             apply: 'serve',
+            // The physical WX DevEngine is a client build. Native environment scoping gives its shared host exactly one
+            // generate/close lifecycle instead of admitting hooks from Vite's unrelated SSR environment.
+            applyToEnvironment: isWxClientEnvironment,
             config() {
                 return {
                     build: {
@@ -189,9 +202,12 @@ function getPageRoute(id) {
         throw new Error(`WX Page capsule is missing its route: ${id}`);
     return route;
 }
-// The assembled runtime chunk is byte-identical on every build (the base runtime and the
-// bundled implement are immutable for the server's lifetime), so the lowering runs once
-// and every build reuses it.
+/*
+ * 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
+ * avoids repeating the only large Oxc transform on every rebuild; keying by source still invalidates correctly if a future Vite
+ * generation changes the runtime, unlike a module-global cached string detached from its actual input.
+ */
 const fixRolldownRuntime = memoize((code) => {
     return transformWithOxc(code, rolldownRuntimeId, {
         lang: 'js',

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

@@ -193,7 +193,11 @@ export function removeRefreshPreambleGuard({ code, id }) {
         createVisitor: createRefreshPreambleGuardVisitor
     });
 }
-// The refresh runtime module and the react-family modules are immutable for the server's
-// lifetime, so their Oxc parses run once per module and every build reuses the output.
+/*
+ * Each memoized transform owns a mutable cache keyed only by source bytes. The matching runtime/react-family modules are
+ * immutable between complete generations, so reparsing them would repeat O(source bytes) Oxc work without observing new state.
+ * Source keys still create a fresh result after a dependency upgrade or real module edit, unlike a once-only cache keyed by ID;
+ * keeping separate caches prevents identical text in different transform domains from sharing the wrong adaptation.
+ */
 const fixRefreshRuntime = memoize(transformRefreshRuntime, { getCacheKey: ({ code }) => code });
 const fixReactDevtoolsHook = memoize(transformReactDevtoolsHook, { getCacheKey: ({ code }) => code });

package/dist/node/plugins/wx/dev/runtime-reports.d.ts

@@ -0,0 +1,27 @@
+import { type SchedulerLike, Subject } from 'rxjs';
+type AppliedReport = Readonly<{
+    kind: 'applied';
+    buildId: string;
+    seq: number;
+}>;
+/** The runtime hit an unrecoverable state and needs a complete build. */
+type RebuildReport = Readonly<{
+    kind: 'rebuild';
+    buildId: string;
+    reason: string;
+}>;
+export type RuntimeReport = AppliedReport | RebuildReport;
+/**
+ * Conflates runtime receipts without weakening their build identity or recovery semantics.
+ *
+ * Reports are metadata frontiers rather than executable deltas: for one build, the highest applied sequence subsumes lower and
+ * duplicate acknowledgements. A rebuild does not subsume reports from a different build, because delayed Pages may still POST
+ * after session rotation, but it dominates every acknowledgement for its own build. The host validates each retained build ID
+ * against the physical publisher only when its serialized task executes, preserving rotation order.
+ *
+ * Completing the Subject flushes the active window synchronously so shutdown can include its host task before closing Rolldown.
+ * Reduction is O(reports) time and O(distinct builds) retained space per quiet window.
+ */
+export declare function createRuntimeReportsStream(settleMilliseconds: number, scheduler: SchedulerLike, publish: (reports: readonly RuntimeReport[]) => void): Subject<RuntimeReport>;
+export declare function reduceRuntimeReportWindow(window: readonly RuntimeReport[]): readonly RuntimeReport[];
+export {};