vite-plugin-taro 0.5.12 → 0.5.14

package/src/node/plugins/wx/dev/create-style-capture.ts

@@ -0,0 +1,179 @@
+import type { GetModuleInfo, Plugin } from 'rolldown'
+import { isCSSRequest } from 'vite'
+import { normalizeModuleId } from '../../../utils/modules.ts'
+import { transformWxStyle } from '../styles/transform-wx-style.ts'
+import {
+    composeGraphStyleCss,
+    createGraphStylePlan,
+    createTailwindSidecarId,
+    extractViteCss,
+    isGlobalStyleRequest
+} from '../styles/utils.ts'
+import { globalWxssFileName, writeHmrFile } from './hmr-files.ts'
+
+type ProcessedStyle = Readonly<{
+    css: string
+    isTailwindRoot: boolean
+}>
+
+type CompleteOutputFile =
+    | Readonly<{ type: 'asset'; fileName: string; source: string | Uint8Array }>
+    | Readonly<{ type: 'chunk'; fileName: string }>
+
+export type StyleCaptureAction =
+    | Readonly<{ kind: 'capture-graph'; getModuleInfo: GetModuleInfo }>
+    | Readonly<{ kind: 'capture-style'; id: string; style: ProcessedStyle }>
+
+/**
+ * Owns capture hooks, the host's style projection, and its physical WXSS publication frontier.
+ *
+ * Rolldown remains authoritative for topology through its live graph reader. Plugin hooks emit typed actions so the host can
+ * serialize captures with every other effect; only the matching capture methods mutate this projection.
+ */
+export function createStyleCapture({
+    applicationEntryIds,
+    outDir,
+    emit,
+    transformTailwindRoot
+}: {
+    applicationEntryIds: readonly string[]
+    outDir: string
+    emit: (action: StyleCaptureAction) => void
+    transformTailwindRoot: (rootId: string, requestId: string) => Promise<Readonly<{ code: string }> | null>
+}): Readonly<{
+    bindOutput: (output: readonly CompleteOutputFile[]) => void
+    captureGraph: (reader: GetModuleInfo) => void
+    captureStyle: (id: string, style: ProcessedStyle) => void
+    plugin: Plugin
+    publishChanged: (changedIds: readonly string[]) => Promise<void>
+}> {
+    /*
+     * This mutable capability is rebound by buildStart for each complete generation. Rolldown keeps the captured function live
+     * across incremental graph edits, so HMR traverses authoritative current topology without maintaining a shadow graph. It is
+     * undefined only before the first buildStart; retaining an older reader across a later complete build would bind transactions
+     * to the wrong engine generation, while snapshotting module data would require O(V + E) mutation on every edit.
+     */
+    let getModuleInfo: GetModuleInfo | undefined
+    /*
+     * This mutable Map is the CSS projection Rolldown does not retain: successful final transform hooks replace one module's
+     * processed bytes, failed transforms intentionally leave its last valid generation, and a successful multi-root Tailwind
+     * refresh commits all replacements only after every sibling resolves. Entries are not deleted when topology changes because
+     * reachability comes from the live graph plan; eager deletion would need a duplicate reverse graph and could remove CSS still
+     * shared by another App/Page root. Its size is bounded by style module identities seen during this server lifecycle.
+     */
+    const processedStyles = new Map<string, ProcessedStyle>()
+    /*
+     * This mutable value mirrors the WXSS bytes currently durable on disk. It has one owner but two real transition sources:
+     *
+     * 1. DevEngine physically writes complete output before onOutput, so bindOutput only observes and adopts that external
+     *    commit. An omitted asset means DevEngine preserved the existing file and this value must remain unchanged.
+     * 2. Incremental HMR is physically written by this host, so publishChanged advances the value only after its atomic write
+     *    succeeds (or after byte equality proves no write was needed).
+     *
+     * Combining these operations behind one generic update event would still require branching between “observe an existing
+     * write” and “perform a new write”, while hiding their different durability boundaries. A genuine single path would require
+     * preventing DevEngine from writing complete WXSS and transferring that entire output responsibility to the host, adding
+     * asset interception and ordering machinery. The two explicit methods are therefore the smallest accurate state model.
+     */
+    let publishedWxss: string | undefined
+
+    const plugin: Plugin = {
+        name: 'vpt:wx-dev-style-capture',
+        buildStart() {
+            emit({ kind: 'capture-graph', getModuleInfo: (moduleId) => this.getModuleInfo(moduleId) })
+        },
+        transform(code, id) {
+            if (!isGlobalStyleRequest(id)) {
+                return
+            }
+
+            const css = extractViteCss(code, id)
+            emit({
+                kind: 'capture-style',
+                id: normalizeModuleId(id),
+                style: {
+                    css: css,
+                    isTailwindRoot: css.includes('weapp-tailwindcss vite-generated-css:')
+                }
+            })
+        }
+    }
+
+    return {
+        bindOutput(output) {
+            /*
+             * Complete output is one of the two real physical writers. Its emitted asset is therefore the authoritative frontier
+             * when present; omission means DevEngine preserved the existing file and this state must remain unchanged.
+             */
+            const style = output.find(
+                (file): file is Extract<CompleteOutputFile, { type: 'asset' }> =>
+                    file.type === 'asset' && file.fileName === globalWxssFileName
+            )
+            if (style) {
+                publishedWxss = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+            }
+        },
+        captureGraph(reader) {
+            getModuleInfo = reader
+        },
+        captureStyle(id, style) {
+            processedStyles.set(id, style)
+        },
+        plugin: plugin,
+        async publishChanged(changedIds) {
+            const styleChanged = changedIds.some(isGlobalStyleRequest)
+            const candidatesChanged = changedIds.some((id) => !isCSSRequest(id))
+            if (!styleChanged && !candidatesChanged) {
+                return
+            }
+            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) =>
+                processedStyles.has(styleId)
+            )
+            if (candidatesChanged) {
+                await refreshTailwindStyles(styleIds, processedStyles, transformTailwindRoot)
+            }
+            const css = composeGraphStyleCss(styleIds, (styleId) => requireProcessedStyle(processedStyles, styleId).css)
+            const wxss = (await transformWxStyle(css)).css
+            if (wxss !== publishedWxss) {
+                await writeHmrFile(outDir, globalWxssFileName, wxss)
+            }
+            // HMR is the second physical writer; advance the frontier only after its atomic write succeeds or was unnecessary.
+            publishedWxss = wxss
+        }
+    }
+}
+
+/** Regenerates all reachable Tailwind roots and commits the cache only when every transform succeeds. */
+async function refreshTailwindStyles(
+    styleIds: readonly string[],
+    processedStyles: Map<string, ProcessedStyle>,
+    transformRoot: (rootId: string, requestId: string) => Promise<Readonly<{ code: string }> | null>
+): Promise<void> {
+    const roots = styleIds.filter((styleId) => requireProcessedStyle(processedStyles, styleId).isTailwindRoot)
+    const refreshedStyles = await Promise.all(
+        roots.map(async (rootId) => {
+            const requestId = createTailwindSidecarId(rootId)
+            const result = await transformRoot(rootId, requestId)
+            if (!result) {
+                throw new Error(`Tailwind sidecar transform produced no result: ${requestId}`)
+            }
+            return [rootId, { css: extractViteCss(result.code, requestId), isTailwindRoot: true }] as const
+        })
+    )
+    refreshedStyles.forEach(([rootId, style]) => {
+        processedStyles.set(rootId, style)
+    })
+}
+
+function requireProcessedStyle(processedStyles: ReadonlyMap<string, ProcessedStyle>, styleId: string): ProcessedStyle {
+    const style = processedStyles.get(styleId)
+    if (!style) {
+        throw new Error(`WX style plan references uncaptured CSS: ${styleId}`)
+    }
+    return style
+}

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

@@ -1,80 +1,140 @@
+import { readFile } from 'node:fs/promises'
 import type { ServerResponse } from 'node:http'
 import path from 'node:path'
 import colors from 'picocolors'
 import { type DevEngine, type DevOptions, dev } from 'rolldown/experimental'
+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 { createHmrResultsStream } from './create-hmr-results-stream.ts'
+import { createStyleCapture, type StyleCaptureAction } from './create-style-capture.ts'
 import {
+    developmentAppWxssFileName,
     type HmrInfo,
     hmrControlPath,
     hmrInfoFileName,
     hmrPatchesFileName,
     type PatchUpdate,
+    renderDevelopmentAppWxss,
     renderHmrInfo,
     renderInitialHmrPatches,
     writeHmrFile
 } from './hmr-files.ts'
+import { createHostActions } from './host-actions.ts'
 import { PatchPublisher } from './patch-publisher.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 = 32
 
 /**
  * Creates the wx dev host: the adapter that owns the physical Rolldown DevEngine (created
  * with dev(...)) and the patch publisher, and replaces Vite's bundledDev.listen so the
  * engine writes directly to the Mini Program output directory instead of serving browser
  * HMR over HTTP.
+ *
+ * `applicationEntryIds` is the resolver's immutable cascade policy, not a second graph: it selects the App capsule followed
+ * by configured Page capsules from Rolldown's larger entry set. Rolldown remains the authority for every live import edge.
  */
 export async function createWxDevHost({
     server,
-    options
+    options,
+    applicationEntryIds
 }: {
     server: ViteDevServer
     options: VitePluginTaroOptions
+    applicationEntryIds: readonly string[]
 }): Promise<WxDevHost> {
     const bundledDev = getBundledDev(server)
-    // Rolldown invokes output callbacks without awaiting their promises. This queue is the single owner of mutable HMR host
-    // state and physical metadata writes, preventing a later patch or build identity from being overwritten by older work.
-    const hostTasks = new SerializedTaskQueue((operation, error) => logWxError(server.config.logger, operation, error))
 
+    // All callbacks admit typed actions through this edge; concatMap is the sole owner of effect ordering and mutable host state.
+    const hostActions = createHostActions<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 })
+    // 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()
     }
 
@@ -82,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
@@ -93,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()
         }
     }
 
@@ -116,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
@@ -124,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)
@@ -134,8 +204,39 @@ 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
+                }
+                styleCapture.bindOutput(action.result.output)
+                return rotateBuildSession()
+            case 'listening':
+                return 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
@@ -143,8 +244,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': {
@@ -160,50 +260,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 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 publisher.produce(patches)
 
-        await commitPublishedBatch(batch)
+        await commitPublishedBatch(patches)
     }
 
     /**
@@ -221,15 +347,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', rotateBuildSession)
-    }
 }
 
 /** The bound HTTP port, or undefined before Vite's server is listening. */
@@ -245,7 +362,7 @@ function boundPort(server: ViteDevServer): number | undefined {
     return address.port
 }
 
-/** Resets physical patches before exposing the matching immutable build identity to a new App heap. */
+/** Resets physical patches and then exposes one coherent build identity to a freshly compiled App heap. */
 async function publishBuildMetadata(server: ViteDevServer, buildId: string, port: number): Promise<void> {
     const info: HmrInfo = {
         buildId,
@@ -254,10 +371,22 @@ async function publishBuildMetadata(server: ViteDevServer, buildId: string, port
 
     await writeHmrFile(server.config.build.outDir, hmrPatchesFileName, renderInitialHmrPatches())
     await writeHmrFile(server.config.build.outDir, hmrInfoFileName, renderHmrInfo(info))
+    // `removeDevelopmentAppWxss` kept the previous physical wrapper in place while the complete output was written. Replace
+    // it only now, after the empty patch frontier and matching identity are durable. DevTools treats `app.wxss` as an App root,
+    // so this write intentionally causes the one full refresh allowed at a complete-build boundary; the refreshed App reads
+    // the new info above. Incremental updates must never write this file because an App refresh could destroy the heap while
+    // its JavaScript patch is being acknowledged. They publish only the imported `assets/global.wxss` stylesheet instead.
+    await writeHmrFile(server.config.build.outDir, developmentAppWxssFileName, renderDevelopmentAppWxss(buildId))
 }
 
 /** Replaces browser server URLs with the physical project directory consumed by WeChat DevTools. */
 function installDevToolsPrinter(server: 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))}`
@@ -289,6 +418,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

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