vite-plugin-taro 0.5.12 → 0.5.14

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

@@ -1,41 +1,92 @@
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import colors from 'picocolors';
 import { dev } from 'rolldown/experimental';
-import { SerializedTaskQueue } from '../../../utils/serialized-task-queue.js';
-import { hmrControlPath, hmrInfoFileName, hmrPatchesFileName, renderHmrInfo, renderInitialHmrPatches, writeHmrFile } from './hmr-files.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 { 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
  * engine writes directly to the Mini Program output directory instead of serving browser
  * HMR over HTTP.
+ *
+ * `applicationEntryIds` is the resolver's immutable cascade policy, not a second graph: it selects the App capsule followed
+ * by configured Page capsules from Rolldown's larger entry set. Rolldown remains the authority for every live import edge.
  */
-export async function createWxDevHost({ server, options }) {
+export async function createWxDevHost({ server, options, applicationEntryIds }) {
     const bundledDev = getBundledDev(server);
-    // 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));
+    // All callbacks admit typed actions through this edge; concatMap is the sole owner of effect ordering and mutable host state.
+    const hostActions = createHostActions(applyHostAction, (action, error) => logWxError(server.config.logger, `wx HMR ${action.kind} failed`, error));
+    const styleCapture = createStyleCapture({
+        applicationEntryIds: applicationEntryIds,
+        outDir: server.config.build.outDir,
+        // Capture hooks run only after engine.run, when the host action subscription and all reducer dependencies are ready.
+        emit: (action) => hostActions.next(action),
+        transformTailwindRoot: async (rootId, requestId) => {
+            // The capture contains generated CSS, while the sidecar must re-run from raw Tailwind directives. Vite exposes no
+            // raw source in its live module graph, so this read is the authoritative source generation rather than a read-back.
+            return server.environments.client.pluginContainer.transform(await readFile(rootId, 'utf8'), requestId);
+        }
+    });
     const publisher = new PatchPublisher((content) => writeHmrFile(server.config.build.outDir, hmrPatchesFileName, content));
-    // 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 });
+    // 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.
@@ -43,8 +94,13 @@ export async function createWxDevHost({ server, options }) {
     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. */
@@ -62,6 +118,10 @@ export async function createWxDevHost({ server, options }) {
         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;
@@ -70,7 +130,7 @@ export async function createWxDevHost({ server, options }) {
         }
         try {
             const report = JSON.parse(await readBody(req));
-            await hostTasks.run(() => processReport(report));
+            runtimeReports.next(report);
             res.end();
         }
         catch (e) {
@@ -79,6 +139,36 @@ export async function createWxDevHost({ server, options }) {
             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.
@@ -87,8 +177,7 @@ export async function createWxDevHost({ server, options }) {
         }
         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': {
@@ -102,43 +191,67 @@ export async function createWxDevHost({ server, options }) {
         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 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);
+        await publisher.produce(patches);
+        await commitPublishedBatch(patches);
     }
     /**
      * Advances Rolldown's published frontier in the same sequence order materialized in the cumulative physical file.
@@ -155,14 +268,6 @@ export async function createWxDevHost({ server, options }) {
             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', rotateBuildSession);
-    }
 }
 /** The bound HTTP port, or undefined before Vite's server is listening. */
 function boundPort(server) {
@@ -176,7 +281,7 @@ function boundPort(server) {
     }
     return address.port;
 }
-/** Resets physical patches before exposing the matching immutable build identity to a new App heap. */
+/** Resets physical patches and then exposes one coherent build identity to a freshly compiled App heap. */
 async function publishBuildMetadata(server, buildId, port) {
     const info = {
         buildId,
@@ -184,9 +289,21 @@ async function publishBuildMetadata(server, buildId, port) {
     };
     await writeHmrFile(server.config.build.outDir, hmrPatchesFileName, renderInitialHmrPatches());
     await writeHmrFile(server.config.build.outDir, hmrInfoFileName, renderHmrInfo(info));
+    // `removeDevelopmentAppWxss` kept the previous physical wrapper in place while the complete output was written. Replace
+    // it only now, after the empty patch frontier and matching identity are durable. DevTools treats `app.wxss` as an App root,
+    // so this write intentionally causes the one full refresh allowed at a complete-build boundary; the refreshed App reads
+    // the new info above. Incremental updates must never write this file because an App refresh could destroy the heap while
+    // its JavaScript patch is being acknowledged. They publish only the imported `assets/global.wxss` stylesheet instead.
+    await writeHmrFile(server.config.build.outDir, developmentAppWxssFileName, renderDevelopmentAppWxss(buildId));
 }
 /** 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))}`);
     };
@@ -214,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,4 +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. */
@@ -16,6 +18,14 @@ export type PatchUpdate = Extract<BindingClientHmrUpdate['update'], {
 export declare function renderHmrInfo(info: HmrInfo): string;
 /** Provides a valid dependency before the host has a patch range to publish. */
 export declare function renderInitialHmrPatches(): string;
+/**
+ * Renders the native App style entry for one complete development build.
+ *
+ * Imported global CSS can change while the entry remains byte-identical. DevTools may then reuse an older persistent compile
+ * cache after it restarts. Tying this inert comment to the build identity invalidates that cache once per complete build,
+ * while incremental style updates continue changing only the imported file and therefore preserve the App heap.
+ */
+export declare function renderDevelopmentAppWxss(buildId: string): string;
 /**
  * Renders the cumulative patch suffix as inert CommonJS data.
  *

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

@@ -1,6 +1,8 @@
 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. */
@@ -13,6 +15,16 @@ export function renderHmrInfo(info) {
 export function renderInitialHmrPatches() {
     return 'module.exports = undefined;\n';
 }
+/**
+ * Renders the native App style entry for one complete development build.
+ *
+ * Imported global CSS can change while the entry remains byte-identical. DevTools may then reuse an older persistent compile
+ * cache after it restarts. Tying this inert comment to the build identity invalidates that cache once per complete build,
+ * while incremental style updates continue changing only the imported file and therefore preserve the App heap.
+ */
+export function renderDevelopmentAppWxss(buildId) {
+    return `@import "./assets/global.wxss";\n/* vpt-build:${buildId} */\n`;
+}
 /**
  * Renders the cumulative patch suffix as inert CommonJS data.
  *

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,10 +1,33 @@
-import type { PluginOption } from 'vite';
+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.
+ *
+ * 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 declare function createWxDevelopmentPlugin(options: VitePluginTaroOptions): PluginOption[];
+export declare function createWxDevelopmentPlugin(options: VitePluginTaroOptions, applicationEntryIds: readonly string[]): PluginOption[];
+/**
+ * Transfers development ownership of `app.wxss` from complete output to the dev host.
+ *
+ * The ordinary WX output hook emits the static production wrapper during every complete build. In development, the existing
+ * physical wrapper instead contains the previous build ID. If the static asset remained in this bundle, the DevEngine would:
+ *
+ * 1. replace the versioned wrapper with static production bytes while JavaScript and HMR metadata are still being finalized;
+ * 2. let DevTools observe that root-style change and reload the App against the previous build identity;
+ * 3. let the host replace the wrapper again with the new build ID, causing a second App reload.
+ *
+ * Deleting only the in-memory bundle entry avoids both premature writes. Development sets `emptyOutDir: false`, so the prior
+ * physical `app.wxss` remains available while the complete output is written. The host replaces it exactly once after
+ * `hmr/patches.js` and `hmr/info.js` are durable. Incremental HMR never enters this complete-output hook and continues changing
+ * only `assets/global.wxss`, which preserves the App heap. The serve-only plugin leaves production output unchanged.
+ */
+export declare function removeDevelopmentAppWxss(bundle: Record<string, unknown>): void;
 /** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
 export declare function injectReactRefreshBootstrap(code: string): {
     code: string;