vite-plugin-taro 0.5.13 → 0.5.16

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

@@ -2,12 +2,12 @@ import { readFile } from 'node:fs/promises'
 import type { ServerResponse } from 'node:http'
 import path from 'node:path'
 import colors from 'picocolors'
-import type { GetModuleInfo } from 'rolldown'
 import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
-import { type Connect, isCSSRequest, type ViteDevServer } from 'vite'
+import { asyncScheduler } from 'rxjs'
+import type { Connect, ViteDevServer } from 'vite'
 import type { VitePluginTaroOptions } from '../../../../options.ts'
-import { SerializedTaskQueue } from '../../../utils/serialized-task-queue.ts'
-import { createGraphStylePlan, isGlobalStyleRequest } from '../styles/utils.ts'
+import { createHmrResultsStream } from './create-hmr-results-stream.ts'
+import { createStyleCapture, type StyleCaptureAction } from './create-style-capture.ts'
 import {
     developmentAppWxssFileName,
     type HmrInfo,
@@ -20,32 +20,31 @@ import {
     renderInitialHmrPatches,
     writeHmrFile
 } from './hmr-files.ts'
+import { createHostActions } from './host-actions.ts'
 import { PatchPublisher } from './patch-publisher.ts'
-import { createStyleCapturePlugin, type ProcessedStyle } from './styles/create-style-capture-plugin.ts'
-import { globalWxssFileName, publishStyleHmr, refreshTailwindStyles } from './styles/publish-style-hmr.ts'
+import { createRuntimeReportsStream, type RuntimeReport } from './runtime-reports.ts'
 import { type BundledDev, installWxDevOptions, requireSingleOutput } from './wx-dev-options.ts'
 
 export type WxDevHost = Readonly<{
     close: () => Promise<void>
 }>
 
-type AppliedReport = Readonly<{
-    kind: 'applied'
-    buildId: string
-    seq: number
-}>
-
-/** The runtime hit an unrecoverable state (e.g. a corrupted patch range) and needs a full rebuild. */
-type RebuildReport = Readonly<{
-    kind: 'rebuild'
-    buildId: string
-    reason: string
-}>
-
-type HmrReport = AppliedReport | RebuildReport
 type HmrUpdatesResult = Parameters<NonNullable<DevOptions['onHmrUpdates']>>[0]
 type HmrUpdates = Exclude<HmrUpdatesResult, Error>
 type DevOutputResult = Parameters<NonNullable<DevOptions['onOutput']>>[0]
+/** A complete build callback is a host action whether it carries durable output or an initial/later build failure. */
+type OutputAction = Readonly<{ kind: 'output'; result: DevOutputResult }>
+
+type HostAction =
+    | StyleCaptureAction
+    | Readonly<{ kind: 'publish'; result: HmrUpdates }>
+    | Readonly<{ kind: 'error'; error: Error }>
+    | Readonly<{ kind: 'reports'; reports: readonly RuntimeReport[] }>
+    | OutputAction
+    | Readonly<{ kind: 'listening' }>
+
+/** One short trailing-edge window absorbs editor bursts before style preparation and physical Page notification. */
+const hmrSettleMilliseconds = 16
 
 /**
  * Creates the wx dev host: the adapter that owns the physical Rolldown DevEngine (created
@@ -66,48 +65,76 @@ export async function createWxDevHost({
     applicationEntryIds: readonly string[]
 }): Promise<WxDevHost> {
     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: GetModuleInfo | undefined
-        processedStyles: Map<string, ProcessedStyle>
-        publishedWxss: string | undefined
-    } = {
-        getModuleInfo: undefined,
-        processedStyles: new Map(),
-        publishedWxss: undefined
-    }
-    const styleCapturePlugin = createStyleCapturePlugin({
-        captureGraph(reader) {
-            styleState.getModuleInfo = reader
-        },
-        captureStyle(id, style) {
-            styleState.processedStyles.set(id, style)
-        }
-    })
 
-    // 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<HostAction>(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, 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: DevEngine = 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 is OutputAction => action.kind === 'output')
+        await engine.run()
+        const { result } = await initialOutput
+        if (result instanceof Error) {
+            throw result
+        }
         await engine.ensureCurrentBuildFinish()
     }
 
@@ -115,7 +142,8 @@ export async function createWxDevHost({
     // 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
@@ -126,8 +154,13 @@ export async function createWxDevHost({
 
     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()
         }
     }
 
@@ -149,6 +182,10 @@ export async function createWxDevHost({
         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: Connect.IncomingMessage, res: ServerResponse): Promise<void> {
         if (req.method !== 'POST') {
             res.statusCode = 404
@@ -157,8 +194,8 @@ export async function createWxDevHost({
         }
 
         try {
-            const report = JSON.parse(await readBody(req)) as HmrReport
-            await hostTasks.run(() => processReport(report))
+            const report = JSON.parse(await readBody(req)) as RuntimeReport
+            runtimeReports.next(report)
             res.end()
         } catch (e) {
             logWxError(server.config.logger, 'wx HMR report failed', e)
@@ -167,8 +204,50 @@ export async function createWxDevHost({
         }
     }
 
+    /** Reduces one merged source action through the existing authoritative host state. */
+    function applyHostAction(action: HostAction): void | Promise<void> {
+        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
+                }
+                return reconcileCompleteOutput(action.result.output)
+            case 'listening':
+                return rotateBuildSession()
+        }
+    }
+
+    /**
+     * Reconciles graph-complete styles before rotating the App-visible build identity.
+     *
+     * DevEngine has already written its compiler asset when onOutput fires, but bundled development may have omitted CSS Modules
+     * from that asset. Awaiting reconciliation inside the serialized reducer guarantees the subsequent app.wxss rotation—the
+     * event that refreshes DevTools—can only expose a generation whose global WXSS already represents the complete App/Page graph.
+     */
+    async function reconcileCompleteOutput(output: Exclude<DevOutputResult, Error>['output']): Promise<void> {
+        await styleCapture.reconcileComplete(output)
+        await rotateBuildSession()
+    }
+
     /** Applies one runtime receipt to the active physical patch history. */
-    function processReport(report: HmrReport): void {
+    function processReport(report: RuntimeReport): void {
         // Delayed reports from older builds must never prune the live build's cumulative patch history.
         if (!publisher.isCurrentBuild(report.buildId)) {
             return
@@ -176,8 +255,7 @@ export async function createWxDevHost({
 
         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': {
@@ -193,87 +271,76 @@ export async function createWxDevHost({
         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: HmrUpdatesResult) => {
+                hmrResults.next(result)
+            },
+            // Initial and later complete builds share one admission path; startup merely observes the first OutputAction.
+            onOutput: (result: DevOutputResult) => {
+                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: HmrUpdatesResult): void {
-        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: string | undefined): void {
+        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: HmrUpdates): Promise<void> {
-        const batch: PatchUpdate[] = []
+        /*
+         * 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: PatchUpdate[] = []
         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: readonly PatchUpdate[]): Promise<void> {
+        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: readonly PatchUpdate[]): Promise<void> {
-        const changedIds = batch.flatMap((patch) => patch.changedIds)
-        const styleChanged = changedIds.some(isGlobalStyleRequest)
-        const candidatesChanged = changedIds.some((id) => !isCSSRequest(id))
-        if (!styleChanged && !candidatesChanged) {
-            return
-        }
+        await publisher.produce(patches)
 
-        // 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 commitPublishedBatch(patches)
     }
 
     /**
@@ -291,21 +358,6 @@ export async function createWxDevHost({
             await engine.notifyPayloadDelivered(patch.filename)
         }
     }
-
-    /** Rotates metadata after each successful complete output. */
-    function handleDevOutput(result: DevOutputResult): void {
-        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(): Promise<void> {
-        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. */
@@ -340,6 +392,12 @@ async function publishBuildMetadata(server: ViteDevServer, buildId: string, port
 
 /** Replaces browser server URLs with the physical project directory consumed by WeChat DevTools. */
 function installDevToolsPrinter(server: ViteDevServer): void {
+    /*
+     * 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))}`
@@ -371,6 +429,12 @@ const maximumBodyBytes = 64 * 1024
 
 function readBody(req: Connect.IncomingMessage): Promise<string> {
     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: Buffer) => {
             body += chunk.toString('utf8')

package/src/node/plugins/wx/dev/hmr-files.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import type { BindingClientHmrUpdate } from 'rolldown/experimental'
 
 export const developmentAppWxssFileName = 'app.wxss'
+export const globalWxssFileName = 'assets/global.wxss'
 export const hmrInfoFileName = 'hmr/info.js'
 export const hmrPatchesFileName = 'hmr/patches.js'
 

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

@@ -0,0 +1,88 @@
+import { catchError, concatMap, defer, EMPTY, filter, firstValueFrom, lastValueFrom, map, Subject } from 'rxjs'
+
+type ActionEnvelope<Action> =
+    | Readonly<{ kind: 'action'; action: Action }>
+    | Readonly<{ kind: 'barrier'; resolve: () => void }>
+
+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 function createHostActions<Action>(
+    apply: (action: Action) => void | Promise<void>,
+    reportError: (action: Action, error: unknown) => void
+): HostActions<Action> {
+    /*
+     * 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<ActionEnvelope<Action>>()
+
+    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: unknown) => {
+                        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<void>()
+            envelopes.next({ kind: 'barrier', resolve: barrier.resolve })
+            return barrier.promise
+        }
+    }
+}

package/src/node/plugins/wx/dev/patch-publisher.ts

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { type PatchUpdate, renderHmrPatches } 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.
@@ -19,9 +19,22 @@ export type WritePatches = (content: string) => Promise<void>
  */
 export class PatchPublisher {
     private readonly writePatches: 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.
+     */
     private buildId: string | undefined
 
-    /** 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.
+     */
     private readonly pendingPatches: PatchUpdate[] = []
 
     // Explicit field assignment: node --test strips types and does not support parameter properties.
@@ -64,6 +77,10 @@ export class PatchPublisher {
      * retaining the gap between published and applied frontiers is what lets DevTools safely miss intermediate file events.
      */
     acknowledge(seq: number): void {
+        /*
+         * 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) {