vite-plugin-taro 0.5.4 → 0.5.6

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

@@ -1,16 +1,10 @@
 import type { ServerResponse } from 'node:http'
 import path from 'node:path'
 import colors from 'picocolors'
-import type { InputOptions, OutputOptions, Plugin } from 'rolldown'
-import { build } from 'rolldown'
-import { type DevEngine, dev, viteReporterPlugin } from 'rolldown/experimental'
+import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
 import type { Connect, ViteDevServer } from 'vite'
 import type { VitePluginTaroOptions } from '../../../../options.ts'
-import { once } from '../../../utils/once.ts'
-import { resolvePackageFile } from '../../../utils/packages.ts'
-import { appShellFileName } from '../module.ts'
-import { createWxDevMode } from './create-wx-dev-mode.ts'
-import { emptyOutputDirectory } from './empty-output-directory.ts'
+import { SerializedTaskQueue } from '../../../utils/serialized-task-queue.ts'
 import {
     type HmrInfo,
     hmrControlPath,
@@ -22,13 +16,14 @@ import {
     writeHmrFile
 } from './hmr-files.ts'
 import { PatchPublisher } from './patch-publisher.ts'
+import { type BundledDev, installWxDevOptions, requireSingleOutput } from './wx-dev-options.ts'
 
 export type WxDevHost = Readonly<{
     close: () => Promise<void>
 }>
 
-type DeliveryReport = Readonly<{
-    kind: 'delivery'
+type AppliedReport = Readonly<{
+    kind: 'applied'
     buildId: string
     seq: number
 }>
@@ -37,8 +32,14 @@ type DeliveryReport = Readonly<{
 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]
+
 /**
  * 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
@@ -53,23 +54,17 @@ export async function createWxDevHost({
     options: VitePluginTaroOptions
 }): Promise<WxDevHost> {
     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<void>()
-    const settleInitialBuild = once((error: Error | undefined): void => {
-        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: DevEngine = await createEngine()
 
     // The wx dev host owns the only DevEngine. Vite's default listen() would create a second
@@ -79,37 +74,32 @@ export async function createWxDevHost({
     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(): Promise<void> {
+    async function rotateBuildSession(): Promise<void> {
         const port = boundPort(server)
         if (port === undefined) {
             // The initial output finishes before Vite binds its port. The listening listener
@@ -123,10 +113,7 @@ export async function createWxDevHost({
         }
         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: Connect.IncomingMessage, res: ServerResponse): Promise<void> {
@@ -137,22 +124,8 @@ export async function createWxDevHost({
         }
 
         try {
-            const report = JSON.parse(await readBody(req)) as DeliveryReport | RebuildReport
-            // 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)))
+            const report = JSON.parse(await readBody(req)) as HmrReport
+            await hostTasks.run(() => processReport(report))
             res.end()
         } catch (e) {
             logWxError(server.config.logger, 'wx HMR report failed', e)
@@ -161,120 +134,102 @@ export async function createWxDevHost({
         }
     }
 
+    /** Applies one runtime receipt to the active physical patch history. */
+    function processReport(report: HmrReport): void {
+        // 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(): Promise<DevEngine> {
         const rolldownOptions = await bundledDev.getRolldownOptions()
-        if (!rolldownOptions.output || Array.isArray(rolldownOptions.output)) {
-            throw new Error('wx development requires exactly one Rolldown output.')
-        }
+        const output = requireSingleOutput(rolldownOptions)
 
-        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: PatchUpdate[] = []
-                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()
-            },
+        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(): void {
-        const original = bundledDev.getRolldownOptions.bind(bundledDev)
+    /** 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))
+    }
 
-        bundledDev.getRolldownOptions = async () => {
-            const rolldownOptions = await original()
-            if (Array.isArray(rolldownOptions.output)) {
-                throw new Error('wx development requires one configured Rolldown output.')
-            }
-            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.')
+    /** Publishes only the active client's patches or requests the complete build required by Rolldown. */
+    async function publishUpdates(result: HmrUpdates): Promise<void> {
+        const batch: PatchUpdate[] = []
+        for (const { clientId, update } of result.updates) {
+            if (!publisher.isCurrentBuild(clientId) || update.type === 'Noop') {
+                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 ?? {}) as Record<string, unknown>
-            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: Plugin = {
-                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: Plugin = {
-                name: 'vpt:wx-report-initial-build',
-                buildEnd: settleInitialBuild
+            if (update.type === 'Patch') {
+                batch.push(update)
+                continue
             }
 
-            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: readonly PatchUpdate[]): Promise<void> {
+        // 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: DevOutputResult): void {
+        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. */
@@ -290,16 +245,28 @@ function boundPort(server: ViteDevServer): number | undefined {
     return address.port
 }
 
-/** Writes the immutable App metadata every full build starts from. */
-async function writeHmrInfo(server: ViteDevServer, buildId: string, port: number): Promise<void> {
+/** Resets physical patches before exposing the matching immutable build identity to a new App heap. */
+async function publishBuildMetadata(server: ViteDevServer, buildId: string, port: number): Promise<void> {
     const info: HmrInfo = {
         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: ViteDevServer): void {
+    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.
@@ -320,22 +287,6 @@ function logWxError(logger: ViteDevServer['config']['logger'], prefix: string, e
     }
 }
 
-// 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(): Promise<string> {
-        // 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: Connect.IncomingMessage): Promise<string> {
@@ -366,92 +317,6 @@ function resolveEndpointHost(server: ViteDevServer): string {
     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: ReadonlySet<string>): (chunk: { name: string; fileName: string }) => string {
-    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<Value>(addon: unknown, fallback: string): string | ((value: Value) => string) {
-    if (typeof addon === 'function') {
-        return (value) => toStableFileName(String(addon(value)))
-    }
-    return toStableFileName(typeof addon === 'string' ? addon : fallback)
-}
-
-function toStableFileName(fileName: string): string {
-    return fileName
-        .replace(/(^|\/)\[hash(?::\d+)?\](?=\.|$)/g, '$1[name]')
-        .replace(/[-_.]\[hash(?::\d+)?\]/g, '')
-        .replace(/\[hash(?::\d+)?\]/g, '[name]')
-}
-
-type ViteTransformPlugin = {
-    _options?: { transformOptions?: { sourcemap?: boolean } }
-    name?: string
-}
-
-function disableViteOxcSourcemap(pluginOption: unknown): void {
-    if (Array.isArray(pluginOption)) {
-        pluginOption.forEach(disableViteOxcSourcemap)
-        return
-    }
-    if (!pluginOption || typeof pluginOption !== 'object') {
-        return
-    }
-    const plugin = pluginOption as ViteTransformPlugin
-    if (plugin.name === 'builtin:vite-transform' && plugin._options?.transformOptions) {
-        plugin._options.transformOptions.sourcemap = false
-    }
-}
-
-function createViteReporter(server: ViteDevServer) {
-    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
-    })
-}
-
-type BundledDevRolldownOptions = InputOptions & {
-    experimental?: {
-        [key: string]: unknown
-        devMode?: boolean | Record<string, unknown>
-    }
-    output?: OutputOptions | OutputOptions[]
-}
-
-type BundledDev = {
-    _devEngine?: DevEngine
-    getRolldownOptions(): Promise<BundledDevRolldownOptions>
-    listen(): Promise<void>
-    triggerBundleRegenerationIfStale(): Promise<boolean>
-}
-
 function getBundledDev(server: ViteDevServer): BundledDev {
     const bundledDev = server.environments.client.bundledDev as unknown as BundledDev | undefined
     if (!bundledDev) {

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

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { BindingClientHmrUpdate } from 'rolldown/experimental'
@@ -28,11 +29,10 @@ export 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 function renderHmrPatches(buildId: string, patches: readonly PatchUpdate[]): string {
     if (patches.length === 0) {
@@ -44,12 +44,24 @@ export function renderHmrPatches(buildId: string, patches: readonly PatchUpdate[
             `{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: string, fileName: string, source: string): Promise<void> {
     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/src/node/plugins/wx/dev/patch-publisher.ts

@@ -4,12 +4,24 @@ 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>
 
-/** 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 {
     private readonly writePatches: WritePatches
     private buildId: string | undefined
 
-    /** Executable updates retained only until the runtime acknowledges physical delivery. */
+    /** Executable updates retained until the runtime confirms successful application. */
     private readonly pendingPatches: PatchUpdate[] = []
 
     // Explicit field assignment: node --test strips types and does not support parameter properties.
@@ -31,19 +43,33 @@ export class PatchPublisher {
         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: readonly PatchUpdate[]): Promise<void> {
-        if (this.buildId === undefined || patches.length === 0) return
+        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. */
-    acknowledge(seq: number): string[] {
-        let deliveredCount = 0
-        while (deliveredCount < this.pendingPatches.length && this.pendingPatches[deliveredCount].seq <= seq) {
-            deliveredCount++
+    /**
+     * 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 {
+        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)
     }
 }