vite-plugin-taro 0.5.4 → 0.5.6

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

@@ -1,14 +1,10 @@
 import path from 'node:path';
 import colors from 'picocolors';
-import { build } from 'rolldown';
-import { dev, viteReporterPlugin } from 'rolldown/experimental';
-import { once } from '../../../utils/once.js';
-import { resolvePackageFile } from '../../../utils/packages.js';
-import { appShellFileName } from '../module.js';
-import { createWxDevMode } from './create-wx-dev-mode.js';
-import { emptyOutputDirectory } from './empty-output-directory.js';
+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 { PatchPublisher } from './patch-publisher.js';
+import { installWxDevOptions, requireSingleOutput } from './wx-dev-options.js';
 /**
  * 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
@@ -17,20 +13,13 @@ import { PatchPublisher } from './patch-publisher.js';
  */
 export async function createWxDevHost({ server, options }) {
     const bundledDev = getBundledDev(server);
-    // DevEngine does not reject run() after an initial plugin failure, so settle startup from its first buildEnd result.
-    // Later build errors belong to the running server and continue through onOutput/onHmrUpdates.
-    const initialBuild = Promise.withResolvers();
-    const settleInitialBuild = once((error) => {
-        if (error) {
-            initialBuild.reject(error);
-        }
-        else {
-            initialBuild.resolve();
-        }
-    });
+    // 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));
-    // Must install rolldown options before create engine
-    installRolldownOptions();
+    // 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 });
     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
@@ -39,30 +28,27 @@ export async function createWxDevHost({ server, options }) {
     bundledDev._devEngine = engine;
     bundledDev.triggerBundleRegenerationIfStale = async () => false;
     bundledDev.listen = async () => {
-        await Promise.all([engine.run(), initialBuild.promise]);
+        await Promise.all([engine.run(), initialBuild]);
         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', startFreshBuild);
+    server.httpServer?.once('listening', () => {
+        hostTasks.enqueue('wx HMR initialization failed', rotateBuildSession);
+    });
     // The runtime's metadata-only reports land on the control path; the buildId in each report
     // IS the Rolldown client ID.
     server.middlewares.use(hmrControlPath, (req, res) => void handleReport(req, res));
-    // Append the DevTools project directory line after Vite's own startup banner: DevTools
-    // opens the output directory directly, so the printed path is the one to select.
-    const originalPrintUrls = server.printUrls.bind(server);
-    server.printUrls = () => {
-        originalPrintUrls();
-        server.config.logger.info(`  ${colors.green('➜')}  ${colors.bold('WeChat DevTools')}: ${colors.cyan(relativeToViteConfig(server.config.build.outDir, server.config.configFile, server.config.root))}`);
-    };
+    installDevToolsPrinter(server);
     return {
         close: async () => {
+            await hostTasks.waitForIdle();
             await engine.close();
         }
     };
     /** Rotates the build identity and materializes the App metadata for it. */
-    async function startFreshBuild() {
+    async function rotateBuildSession() {
         const port = boundPort(server);
         if (port === undefined) {
             // The initial output finishes before Vite binds its port. The listening listener
@@ -74,10 +60,7 @@ export async function createWxDevHost({ server, options }) {
             await engine.removeClient(previousBuildId);
         }
         await engine.registerClient(buildId);
-        // Publish info last: a heap that observes the new identity is guaranteed to see the
-        // matching reset patch file.
-        await writeHmrFile(server.config.build.outDir, hmrPatchesFileName, renderInitialHmrPatches());
-        await writeHmrInfo(server, buildId, port);
+        await publishBuildMetadata(server, buildId, port);
     }
     async function handleReport(req, res) {
         if (req.method !== 'POST') {
@@ -87,21 +70,7 @@ export async function createWxDevHost({ server, options }) {
         }
         try {
             const report = JSON.parse(await readBody(req));
-            // Only the current build's reports can advance physical delivery;
-            // delayed reports from older builds are ignored so they can never influence the
-            // live build.
-            if (!publisher.isCurrentBuild(report.buildId)) {
-                res.end();
-                return;
-            }
-            if (report.kind === 'rebuild') {
-                engine.triggerFullBuild();
-                res.end();
-                return;
-            }
-            // Commit every newly acknowledged Rolldown payload to this client's ship map.
-            const deliveredFiles = publisher.acknowledge(report.seq);
-            await Promise.all(deliveredFiles.map((fileName) => engine.notifyPayloadDelivered(fileName)));
+            await hostTasks.run(() => processReport(report));
             res.end();
         }
         catch (e) {
@@ -110,105 +79,89 @@ export async function createWxDevHost({ server, options }) {
             res.end();
         }
     }
+    /** 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.
+        if (!publisher.isCurrentBuild(report.buildId)) {
+            return;
+        }
+        switch (report.kind) {
+            case 'rebuild': {
+                server.config.logger.info(`[vpt] wx runtime requested a full rebuild: ${report.reason}`);
+                engine.triggerFullBuild();
+                return;
+            }
+            case 'applied': {
+                publisher.acknowledge(report.seq);
+                return;
+            }
+        }
+    }
     /** Creates the physical DevEngine with the wx dev host hooks. */
     async function createEngine() {
         const rolldownOptions = await bundledDev.getRolldownOptions();
-        if (!rolldownOptions.output || Array.isArray(rolldownOptions.output)) {
-            throw new Error('wx development requires exactly one Rolldown output.');
-        }
-        return dev(rolldownOptions, rolldownOptions.output, {
-            onHmrUpdates: async (result) => {
-                if (result instanceof Error) {
-                    logWxError(server.config.logger, 'wx HMR update failed', result);
-                    return;
-                }
-                // Collect the current client's batch first: one HMR event can carry several
-                // client envelopes, while only the active build may enter its patch history.
-                const batch = [];
-                for (const { clientId, update } of result.updates) {
-                    // Removed and delayed client sessions can still appear in a completed
-                    // engine batch; they must never enter the current build's patch history.
-                    if (!publisher.isCurrentBuild(clientId) || update.type === 'Noop') {
-                        continue;
-                    }
-                    if (update.type === 'Patch') {
-                        batch.push(update);
-                        continue;
-                    }
-                    server.config.logger.info(`[vpt] wx full rebuild required${update.reason ? `: ${update.reason}` : ''}`);
-                    engine.triggerFullBuild();
-                    return;
-                }
-                if (batch.length > 0) {
-                    await publisher.produce(batch);
-                    // server.config.logger.info('[vpt] wx patch produced')
-                }
-            },
-            onOutput: async (result) => {
-                if (result instanceof Error) {
-                    logWxError(server.config.logger, 'wx dev build failed', result);
-                    return;
-                }
-                // A fresh build identity per complete physical build; the App runtime reads it
-                // from hmr/info.js before any module registers.
-                await startFreshBuild();
-            },
+        const output = requireSingleOutput(rolldownOptions);
+        return dev(rolldownOptions, output, {
+            onHmrUpdates: handleHmrUpdates,
+            onOutput: handleDevOutput,
             rebuildStrategy: 'never',
             watch: { skipWrite: false }
         });
     }
-    /** Restores physical Mini Program output conventions after Vite applies browser bundled-dev defaults. */
-    function installRolldownOptions() {
-        const original = bundledDev.getRolldownOptions.bind(bundledDev);
-        bundledDev.getRolldownOptions = async () => {
-            const rolldownOptions = await original();
-            if (Array.isArray(rolldownOptions.output)) {
-                throw new Error('wx development requires one configured Rolldown output.');
+    /** 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));
+    }
+    /** Publishes only the active client's patches or requests the complete build required by Rolldown. */
+    async function publishUpdates(result) {
+        const batch = [];
+        for (const { clientId, update } of result.updates) {
+            if (!publisher.isCurrentBuild(clientId) || update.type === 'Noop') {
+                continue;
             }
-            rolldownOptions.output ??= {};
-            const output = rolldownOptions.output;
-            const configuredOutput = server.config.build.rolldownOptions.output;
-            if (Array.isArray(configuredOutput)) {
-                throw new Error('wx development supports one configured Rolldown output.');
+            if (update.type === 'Patch') {
+                batch.push(update);
+                continue;
             }
-            // Every page entry must depend on hmr/patches.js: DevTools classifies a changed Page
-            // dependency as Page JavaScript hot reload and re-executes live Pages, which is the only
-            // trigger that delivers physical patches while keeping the App heap alive.
-            const pageFiles = new Set(options.pages.map((page) => `${page.path}.js`));
-            const configured = (configuredOutput ?? {});
-            Object.assign(output, configured, {
-                assetFileNames: createStableFileNames(configured.assetFileNames, 'assets/[name][extname]'),
-                banner: createEntryBanner(pageFiles),
-                chunkFileNames: createStableFileNames(configured.chunkFileNames, 'assets/[name].js'),
-                entryFileNames: createStableFileNames(configured.entryFileNames, '[name]'),
-                format: 'es',
-                minify: true,
-                sourcemap: false
-            });
-            rolldownOptions.experimental ??= {};
-            rolldownOptions.experimental.devMode = createWxDevMode(rolldownOptions.experimental.devMode, await bundleRuntimeSource());
-            const emptyOutputDirectoryPlugin = {
-                name: 'vpt:wx-empty-output-directory',
-                renderStart: {
-                    order: 'pre',
-                    // DevEngine bypasses Vite's build-only output preparation. Clear stale files before every complete
-                    // physical render while retaining the directory watched by WeChat DevTools.
-                    handler: () => emptyOutputDirectory(server.config.build.outDir)
-                }
-            };
-            const reportInitialBuildPlugin = {
-                name: 'vpt:wx-report-initial-build',
-                buildEnd: settleInitialBuild
-            };
-            rolldownOptions.plugins = [
-                emptyOutputDirectoryPlugin,
-                rolldownOptions.plugins,
-                reportInitialBuildPlugin,
-                createViteReporter(server)
-            ];
-            disableViteOxcSourcemap(rolldownOptions.plugins);
-            return rolldownOptions;
-        };
+            server.config.logger.info(`[vpt] wx full rebuild required${update.reason ? `: ${update.reason}` : ''}`);
+            engine.triggerFullBuild();
+            return;
+        }
+        if (batch.length === 0) {
+            return;
+        }
+        // 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);
+    }
+    /**
+     * Advances Rolldown's published frontier in the same sequence order materialized in the cumulative physical file.
+     *
+     * Given a batch [5, 6], publisher.produce has already made factories [5, 6] visible in hmr/patches.js. This method then
+     * commits payload 5 followed by payload 6. If DevTools observes neither event before sequence 7 is published, the next
+     * physical file contains [5, 6, 7], while Rolldown is free to generate 7 relative to its already-published sequence 6.
+     */
+    async function commitPublishedBatch(batch) {
+        // Do not use Promise.all or deduplicate filenames. Multiple sequential payloads may target the same output filename,
+        // and each notification commits one distinct Rolldown payload. Awaiting in order preserves the exact frontier encoded
+        // by PatchUpdate.seq and prevents a later payload from becoming visible to the engine before its predecessor.
+        for (const patch of batch) {
+            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. */
@@ -223,14 +176,23 @@ function boundPort(server) {
     }
     return address.port;
 }
-/** Writes the immutable App metadata every full build starts from. */
-async function writeHmrInfo(server, buildId, port) {
+/** Resets physical patches before exposing the matching immutable build identity to a new App heap. */
+async function publishBuildMetadata(server, buildId, port) {
     const info = {
         buildId,
         endpoint: `${server.config.server.https ? 'https' : 'http'}://${resolveEndpointHost(server)}:${port}${hmrControlPath}`
     };
+    await writeHmrFile(server.config.build.outDir, hmrPatchesFileName, renderInitialHmrPatches());
     await writeHmrFile(server.config.build.outDir, hmrInfoFileName, renderHmrInfo(info));
 }
+/** Appends the physical project directory after Vite's normal server URLs. */
+function installDevToolsPrinter(server) {
+    const originalPrintUrls = server.printUrls.bind(server);
+    server.printUrls = () => {
+        originalPrintUrls();
+        server.config.logger.info(`  ${colors.green('➜')}  ${colors.bold('WeChat DevTools')}: ${colors.cyan(relativeToViteConfig(server.config.build.outDir, server.config.configFile, server.config.root))}`);
+    };
+}
 /**
  * The project directory shown in the DevTools banner, relative to the Vite config:
  * `dist/wx` instead of the absolute output path, so it can be pasted into DevTools.
@@ -251,20 +213,6 @@ function logWxError(logger, prefix, error) {
         logger.error(`[vpt] ${prefix} with unknown error: ${error}`);
     }
 }
-// The runtime source is immutable for the host's lifetime (it changes only when the
-// plugin is rebuilt), so the nested bundle runs once and every build reuses it.
-const bundleRuntimeSource = once(
-/** Bundles the runtime host and state machine into one plain script for injection. */
-async function bundleRuntimeSource() {
-    // write: false — only the code is consumed; without it rolldown drops the bundle into
-    // the default dist/ of the running project.
-    const result = await build({
-        input: resolvePackageFile('dist/runtime/wx/dev/dev-runtime.js'),
-        output: { format: 'iife', minify: true, sourcemap: false },
-        write: false
-    });
-    return result.output[0].code;
-});
 const maximumBodyBytes = 64 * 1024;
 function readBody(req) {
     return new Promise((resolve, reject) => {
@@ -292,67 +240,6 @@ function resolveEndpointHost(server) {
     }
     return address.address.includes(':') ? `[${address.address}]` : address.address;
 }
-/**
- * Prepends entry banners. Banners are plain text appended after Rolldown's analysis, so the
- * requires never become chunk dependencies (a bare require inside the injected runtime source
- * would stall the build), and the wx render pipeline keeps this text after the hoisted chunk
- * requires — so the runtime chunk exists before these run:
- * - the app entry loads hmr/info.js and initializes the runtime before any module registers;
- * - every page requires hmr/patches.js, the changed dependency that makes DevTools re-execute
- *   live Pages and thereby load physical updates.
- */
-function createEntryBanner(pageFiles) {
-    return (chunk) => {
-        if (chunk.name === appShellFileName) {
-            return "__rolldown_runtime__.initialize(require('./hmr/info.js'));\n";
-        }
-        if (pageFiles.has(chunk.name)) {
-            // Page files live at `pages/<route>/index.js`, so the dependency path must be
-            // computed relative to each page's own directory.
-            const patchesPath = path.posix.relative(path.posix.dirname(chunk.fileName), 'hmr/patches.js');
-            return `require('${patchesPath}');\n`;
-        }
-        return '';
-    };
-}
-function createStableFileNames(addon, fallback) {
-    if (typeof addon === 'function') {
-        return (value) => toStableFileName(String(addon(value)));
-    }
-    return toStableFileName(typeof addon === 'string' ? addon : fallback);
-}
-function toStableFileName(fileName) {
-    return fileName
-        .replace(/(^|\/)\[hash(?::\d+)?\](?=\.|$)/g, '$1[name]')
-        .replace(/[-_.]\[hash(?::\d+)?\]/g, '')
-        .replace(/\[hash(?::\d+)?\]/g, '[name]');
-}
-function disableViteOxcSourcemap(pluginOption) {
-    if (Array.isArray(pluginOption)) {
-        pluginOption.forEach(disableViteOxcSourcemap);
-        return;
-    }
-    if (!pluginOption || typeof pluginOption !== 'object') {
-        return;
-    }
-    const plugin = pluginOption;
-    if (plugin.name === 'builtin:vite-transform' && plugin._options?.transformOptions) {
-        plugin._options.transformOptions.sourcemap = false;
-    }
-}
-function createViteReporter(server) {
-    const { build, logger, root } = server.config;
-    return viteReporterPlugin({
-        assetsDir: path.join(build.assetsDir, '/'),
-        chunkLimit: 2000,
-        isLib: Boolean(build.lib),
-        isTty: Boolean(process.stdout.isTTY && !process.env.CI),
-        logInfo: (message) => logger.info(message),
-        reportCompressedSize: false,
-        root,
-        warnLargeChunks: false
-    });
-}
 function getBundledDev(server) {
     const bundledDev = server.environments.client.bundledDev;
     if (!bundledDev) {

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

@@ -17,12 +17,11 @@ 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 missing patch suffix as a passive physical delivery module.
+ * Renders the cumulative patch suffix as inert CommonJS data.
  *
- * DevTools re-executes the Page because this file changed. The module only stores the literal
- * Rolldown factories in the persistent App runtime; storePatches applies them synchronously,
- * so the Page's imports below the require resolve against the freshly registered modules.
+ * DevTools re-executes the Page because this dependency changed. The Page entry passes the exported payload to the persistent
+ * App runtime synchronously before importing its capsule, keeping delivery explicit and leaving this file free of side effects.
  */
 export declare function renderHmrPatches(buildId: string, patches: readonly PatchUpdate[]): string;
-/** Publishes one physical HMR file (direct write; atomic rename is reserved for later analysis). */
+/** Atomically publishes one physical HMR module so DevTools can observe only complete JavaScript generations. */
 export declare function writeHmrFile(outDir: string, fileName: string, source: string): Promise<void>;

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

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 export const hmrInfoFileName = 'hmr/info.js';
@@ -13,22 +14,31 @@ export function renderInitialHmrPatches() {
     return 'module.exports = undefined;\n';
 }
 /**
- * Renders the missing patch suffix as a passive physical delivery module.
+ * Renders the cumulative patch suffix as inert CommonJS data.
  *
- * DevTools re-executes the Page because this file changed. The module only stores the literal
- * Rolldown factories in the persistent App runtime; storePatches applies them synchronously,
- * so the Page's imports below the require resolve against the freshly registered modules.
+ * DevTools re-executes the Page because this dependency changed. The Page entry passes the exported payload to the persistent
+ * App runtime synchronously before importing its capsule, keeping delivery explicit and leaving this file free of side effects.
  */
 export function renderHmrPatches(buildId, patches) {
     if (patches.length === 0) {
         throw new Error('Cannot render an empty WX patch range.');
     }
     const rendered = patches.map((patch) => `{seq: ${patch.seq}, changedIds: ${JSON.stringify(patch.changedIds)}, factory: () => {\n${patch.code}\n}}`);
-    return `__rolldown_runtime__.storePatches({buildId: ${JSON.stringify(buildId)}, patches: [${rendered.join(',')}]});\n`;
+    return `module.exports = {buildId: ${JSON.stringify(buildId)}, patches: [${rendered.join(',')}]};\n`;
 }
-/** Publishes one physical HMR file (direct write; atomic rename is reserved for later analysis). */
+/** Atomically publishes one physical HMR module so DevTools can observe only complete JavaScript generations. */
 export async function writeHmrFile(outDir, fileName, source) {
     const filePath = path.join(outDir, fileName);
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, source);
+    const directory = path.dirname(filePath);
+    await fs.mkdir(directory, { recursive: true });
+    const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.txt`);
+    try {
+        // DevTools ignores the temporary .txt file; keeping it beside the destination guarantees a same-filesystem rename.
+        await fs.writeFile(temporaryPath, source);
+        await fs.rename(temporaryPath, filePath);
+    }
+    finally {
+        // rename removes the source path on success; force cleanup covers interrupted writes and failed replacements.
+        await fs.rm(temporaryPath, { force: true });
+    }
 }

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

@@ -1,11 +1,23 @@
 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>;
-/** Owns one build's unacknowledged patches and physical publish decision. */
+/**
+ * Owns the cumulative sequence range between the host's published frontier and the runtime's applied frontier.
+ *
+ * For example, if the runtime has applied sequence 4:
+ *
+ * 1. produce([5, 6]) writes [5, 6];
+ * 2. produce([7]) before an application report writes [5, 6, 7], so DevTools may miss the first file event safely;
+ * 3. acknowledge(6) retains [7];
+ * 4. produce([8]) then writes [7, 8], exactly the suffix the runtime still needs.
+ *
+ * The host may advance Rolldown's published frontier through 8 immediately after those writes, but this history is pruned only
+ * through 6 until the runtime reports successful application. Published sequence and applied sequence are deliberately distinct.
+ */
 export declare class PatchPublisher {
     private readonly writePatches;
     private buildId;
-    /** Executable updates retained only until the runtime acknowledges physical delivery. */
+    /** 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. */
@@ -15,8 +27,16 @@ export declare class PatchPublisher {
         buildId: string;
         previousBuildId: string | undefined;
     }>;
-    /** Appends a Rolldown batch and publishes every unacknowledged patch. */
+    /**
+     * Appends a Rolldown batch and publishes the complete range not yet applied by the runtime.
+     *
+     * Resolution means the cumulative JavaScript generation is physically visible. The host may then advance Rolldown's
+     * published frontier immediately; pendingPatches remains intact until an application report proves the runtime caught up.
+     */
     produce(patches: readonly PatchUpdate[]): Promise<void>;
-    /** Removes the pending prefix covered by the runtime's Rolldown sequence receipt. */
-    acknowledge(seq: number): string[];
+    /**
+     * Removes only the prefix covered by the runtime's successful application frontier. Publication alone never calls this:
+     * retaining the gap between published and applied frontiers is what lets DevTools safely miss intermediate file events.
+     */
+    acknowledge(seq: number): void;
 }

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

@@ -1,10 +1,22 @@
 import { randomUUID } from 'node:crypto';
 import { renderHmrPatches } from './hmr-files.js';
-/** Owns one build's unacknowledged patches and physical publish decision. */
+/**
+ * Owns the cumulative sequence range between the host's published frontier and the runtime's applied frontier.
+ *
+ * For example, if the runtime has applied sequence 4:
+ *
+ * 1. produce([5, 6]) writes [5, 6];
+ * 2. produce([7]) before an application report writes [5, 6, 7], so DevTools may miss the first file event safely;
+ * 3. acknowledge(6) retains [7];
+ * 4. produce([8]) then writes [7, 8], exactly the suffix the runtime still needs.
+ *
+ * The host may advance Rolldown's published frontier through 8 immediately after those writes, but this history is pruned only
+ * through 6 until the runtime reports successful application. Published sequence and applied sequence are deliberately distinct.
+ */
 export class PatchPublisher {
     writePatches;
     buildId;
-    /** Executable updates retained only until the runtime acknowledges physical delivery. */
+    /** Executable updates retained until the runtime confirms successful application. */
     pendingPatches = [];
     // Explicit field assignment: node --test strips types and does not support parameter properties.
     constructor(writePatches) {
@@ -22,19 +34,28 @@ export class PatchPublisher {
         this.pendingPatches.length = 0;
         return { buildId, previousBuildId };
     }
-    /** Appends a Rolldown batch and publishes every unacknowledged patch. */
+    /**
+     * Appends a Rolldown batch and publishes the complete range not yet applied by the runtime.
+     *
+     * Resolution means the cumulative JavaScript generation is physically visible. The host may then advance Rolldown's
+     * published frontier immediately; pendingPatches remains intact until an application report proves the runtime caught up.
+     */
     async produce(patches) {
-        if (this.buildId === undefined || patches.length === 0)
+        if (this.buildId === undefined || patches.length === 0) {
             return;
+        }
         this.pendingPatches.push(...patches);
         await this.writePatches(renderHmrPatches(this.buildId, this.pendingPatches));
     }
-    /** Removes the pending prefix covered by the runtime's Rolldown sequence receipt. */
+    /**
+     * Removes only the prefix covered by the runtime's successful application frontier. Publication alone never calls this:
+     * retaining the gap between published and applied frontiers is what lets DevTools safely miss intermediate file events.
+     */
     acknowledge(seq) {
-        let deliveredCount = 0;
-        while (deliveredCount < this.pendingPatches.length && this.pendingPatches[deliveredCount].seq <= seq) {
-            deliveredCount++;
+        let appliedCount = 0;
+        while (appliedCount < this.pendingPatches.length && this.pendingPatches[appliedCount].seq <= seq) {
+            appliedCount++;
         }
-        return this.pendingPatches.splice(0, deliveredCount).map((patch) => patch.filename);
+        this.pendingPatches.splice(0, appliedCount);
     }
 }

package/dist/node/plugins/wx/dev/react-refresh.d.ts

@@ -18,3 +18,15 @@ import type { Plugin } from 'vite';
  * transformed by at most one of them, and modules outside all three never reach a handler.
  */
 export declare function createWxReactRefreshTransforms(): Plugin[];
+export declare function transformRefreshRuntime({ code, id }: {
+    code: string;
+    id: string;
+}): import("../../../utils/transform.ts").AstTransformResult;
+export declare function transformReactDevtoolsHook({ code, id }: {
+    code: string;
+    id: string;
+}): import("../../../utils/transform.ts").AstTransformResult;
+export declare function removeRefreshPreambleGuard({ code, id }: {
+    code: string;
+    id: string;
+}): import("../../../utils/transform.ts").AstTransformResult;