vite-plugin-taro 0.5.13 → 0.5.14

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) {

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

@@ -1,4 +1,4 @@
-import { type PluginOption, transformWithOxc } from 'vite'
+import { normalizePath, type PluginOption, transformWithOxc } from 'vite'
 import type { VitePluginTaroOptions } from '../../../../options.ts'
 import { esTarget } from '../../../utils/constant.ts'
 import { memoize } from '../../../utils/memoize.ts'
@@ -10,6 +10,11 @@ import { createWxReactRefreshTransforms } from './react-refresh.ts'
 
 const taroRuntimeId = '@tarojs/runtime'
 
+/** Selects the sole Vite environment that owns the physical Mini Program development project. */
+export function isWxClientEnvironment(environment: Readonly<{ name: string }>): boolean {
+    return environment.name === 'client'
+}
+
 /**
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.
@@ -21,17 +26,26 @@ export function createWxDevelopmentPlugin(
     options: VitePluginTaroOptions,
     applicationEntryIds: readonly string[]
 ): PluginOption[] {
-    // This mutable handle transfers ownership from configureServer to closeBundle; at most one host exists per plugin instance.
+    /*
+     * Vite creates this plugin descriptor before a server or DevEngine exists, then invokes configureServer and closeBundle on
+     * different lifecycle stacks. This mutable handle transfers the one client-owned host between those hooks: configureServer
+     * assigns it after asynchronous construction, and closeBundle reads it to drain the same engine. Environment scoping ensures
+     * only the client hook pair participates. Capturing a construction Promise would start too early, while recreating the host
+     * in closeBundle would lose every live action, patch, style, and client frontier owned by the running instance.
+     */
     let host: WxDevHost | null = null
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
-    const normalizedAppCapsulePath = normalizeModuleId(appCapsulePath)
-    const normalizedPageCapsulePath = normalizeModuleId(pageCapsulePath)
-    const normalizedTaroRuntimePath = normalizeModuleId(taroRuntimePath)
+    const normalizedAppCapsulePath = normalizePath(appCapsulePath)
+    const normalizedPageCapsulePath = normalizePath(pageCapsulePath)
+    const normalizedTaroRuntimePath = normalizePath(taroRuntimePath)
 
     return [
         {
             name: 'vpt:wx-dev',
             apply: 'serve',
+            // The physical WX DevEngine is a client build. Native environment scoping gives its shared host exactly one
+            // generate/close lifecycle instead of admitting hooks from Vite's unrelated SSR environment.
+            applyToEnvironment: isWxClientEnvironment,
 
             config() {
                 return {
@@ -205,9 +219,12 @@ function getPageRoute(id: string): string {
     return route
 }
 
-// The assembled runtime chunk is byte-identical on every build (the base runtime and the
-// bundled implement are immutable for the server's lifetime), so the lowering runs once
-// and every build reuses it.
+/*
+ * memoize owns a mutable one-entry-by-input cache. The assembled runtime source is byte-identical across complete generations
+ * because both the Rolldown base and injected implementation are immutable for the server lifetime. Reusing its lowered result
+ * avoids repeating the only large Oxc transform on every rebuild; keying by source still invalidates correctly if a future Vite
+ * generation changes the runtime, unlike a module-global cached string detached from its actual input.
+ */
 const fixRolldownRuntime = memoize((code: string) => {
     return transformWithOxc(code, rolldownRuntimeId, {
         lang: 'js',

package/src/node/plugins/wx/dev/react-refresh.ts

@@ -214,7 +214,11 @@ export function removeRefreshPreambleGuard({ code, id }: { code: string; id: str
     })
 }
 
-// The refresh runtime module and the react-family modules are immutable for the server's
-// lifetime, so their Oxc parses run once per module and every build reuses the output.
+/*
+ * Each memoized transform owns a mutable cache keyed only by source bytes. The matching runtime/react-family modules are
+ * immutable between complete generations, so reparsing them would repeat O(source bytes) Oxc work without observing new state.
+ * Source keys still create a fresh result after a dependency upgrade or real module edit, unlike a once-only cache keyed by ID;
+ * keeping separate caches prevents identical text in different transform domains from sharing the wrong adaptation.
+ */
 const fixRefreshRuntime = memoize(transformRefreshRuntime, { getCacheKey: ({ code }) => code })
 const fixReactDevtoolsHook = memoize(transformReactDevtoolsHook, { getCacheKey: ({ code }) => code })

package/src/node/plugins/wx/dev/runtime-reports.ts

@@ -0,0 +1,70 @@
+import { buffer, debounceTime, filter, type SchedulerLike, Subject } from 'rxjs'
+
+type AppliedReport = Readonly<{
+    kind: 'applied'
+    buildId: string
+    seq: number
+}>
+
+/** The runtime hit an unrecoverable state and needs a complete build. */
+type RebuildReport = Readonly<{
+    kind: 'rebuild'
+    buildId: string
+    reason: string
+}>
+
+export type RuntimeReport = AppliedReport | RebuildReport
+
+/**
+ * Conflates runtime receipts without weakening their build identity or recovery semantics.
+ *
+ * Reports are metadata frontiers rather than executable deltas: for one build, the highest applied sequence subsumes lower and
+ * duplicate acknowledgements. A rebuild does not subsume reports from a different build, because delayed Pages may still POST
+ * after session rotation, but it dominates every acknowledgement for its own build. The host validates each retained build ID
+ * against the physical publisher only when its serialized task executes, preserving rotation order.
+ *
+ * Completing the Subject flushes the active window synchronously so shutdown can include its host task before closing Rolldown.
+ * Reduction is O(reports) time and O(distinct builds) retained space per quiet window.
+ */
+export function createRuntimeReportsStream(
+    settleMilliseconds: number,
+    scheduler: SchedulerLike,
+    publish: (reports: readonly RuntimeReport[]) => void
+): Subject<RuntimeReport> {
+    /*
+     * This Subject is the sole mutable HTTP admission edge. Requests append reports synchronously and finish their responses;
+     * buffer then owns the short-lived window while debounceTime supplies only its quiet-edge signal. Reports are metadata rather
+     * than executable deltas, so the window may be reduced before entering hostActions. Directly mutating PatchPublisher from the
+     * request stack would race patch writes and build rotation; retaining every raw receipt beyond the window would grow with Page
+     * count and duplicate acknowledgements. Completion flushes the final window during phased shutdown.
+     */
+    const reports = new Subject<RuntimeReport>()
+
+    reports
+        .pipe(
+            buffer(reports.pipe(debounceTime(settleMilliseconds, scheduler))),
+            filter((window) => window.length > 0)
+        )
+        .subscribe((window) => publish(reduceRuntimeReportWindow(window)))
+    return reports
+}
+
+export function reduceRuntimeReportWindow(window: readonly RuntimeReport[]): readonly RuntimeReport[] {
+    /*
+     * This transaction-local mutable Map is bounded by distinct build IDs in one quiet window. Insertion order preserves causal
+     * build order, while replacing a value conflates only that build's monotonic acknowledgement frontier; rebuild becomes its
+     * terminal value. A single global latest report would let delayed Pages erase another build, and retaining the raw window
+     * would make downstream work proportional to duplicate report volume. The Map is discarded immediately after reduction.
+     */
+    const reportsByBuild = new Map<string, RuntimeReport>()
+    for (const report of window) {
+        const previous = reportsByBuild.get(report.buildId)
+        if (previous?.kind === 'rebuild') {
+            continue
+        }
+        if (report.kind === 'rebuild' || previous === undefined || report.seq > previous.seq) {
+            reportsByBuild.set(report.buildId, report)
+        }
+    }
+    return [...reportsByBuild.values()]
+}

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

@@ -7,9 +7,8 @@ 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'
 
-export type BundledDevRolldownOptions = InputOptions & {
+type BundledDevRolldownOptions = InputOptions & {
     experimental?: {
         [key: string]: unknown
         devMode?: boolean | Record<string, unknown>
@@ -24,7 +23,10 @@ export type BundledDev = {
     triggerBundleRegenerationIfStale(): Promise<boolean>
 }
 
-/** Installs the physical WX output and runtime conventions over Vite's browser-oriented bundled-development options. */
+/**
+ * Installs physical WX output and runtime conventions over Vite's browser-oriented bundled-development options.
+ * Build completion deliberately remains outside this options adapter: DevEngine onOutput is the single lifecycle authority.
+ */
 export function installWxDevOptions({
     bundledDev,
     server,
@@ -35,17 +37,13 @@ export function installWxDevOptions({
     server: ViteDevServer
     options: VitePluginTaroOptions
     hostPlugins: Plugin[]
-}): Promise<void> {
-    // The buildEnd hook and its one-shot result belong to the same abstraction. Consumers can await startup without receiving
-    // a resolver capable of settling it externally.
-    const initialBuild = Promise.withResolvers<void>()
-    const settleInitialBuild = once((error: Error | undefined): void => {
-        if (error) {
-            initialBuild.reject(error)
-        } else {
-            initialBuild.resolve()
-        }
-    })
+}): void {
+    /*
+     * Vite owns this mutable adapter method and calls it later when constructing DevEngine. Replacing that one seam preserves
+     * Vite's resolved graph while applying WX physical-output conventions to every options generation. Capturing and mutating one
+     * options object here would be stale on later complete builds; creating a second engine would duplicate watchers and graphs.
+     * The bound original remains immutable and is invoked exactly once per delegated options request.
+     */
     const original = bundledDev.getRolldownOptions.bind(bundledDev)
 
     bundledDev.getRolldownOptions = async () => {
@@ -59,9 +57,16 @@ export function installWxDevOptions({
         const configured = configuredOutput ?? {}
 
         // 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 physical patch trigger that preserves the App heap.
-        const pageFiles = new Set(options.pages.map((page) => `${page.path}.js`))
-
+        // hot reload and re-executes live Pages, which is the only physical patch trigger that preserves the App heap. Although
+        // Set provides O(1) membership, exposing it as ReadonlySet prevents mutation after this options generation is resolved.
+        const pageFiles: ReadonlySet<string> = new Set(options.pages.map((page) => `${page.path}.js`))
+
+        /*
+         * Rolldown passes this mutable output object onward by identity, and nested Vite plugins may already retain it. Mutating
+         * that single object preserves their references while atomically replacing browser-oriented naming and format fields with
+         * stable physical WX conventions. Cloning only our fields would leave retained references on stale hashed filenames;
+         * mutating configuredOutput itself would leak development normalization back into the user's resolved Vite config.
+         */
         Object.assign(output, configured, {
             assetFileNames: createStableFileNames(configured.assetFileNames, 'assets/[name][extname]'),
             banner: createEntryBanner(pageFiles),
@@ -72,31 +77,29 @@ export function installWxDevOptions({
             sourcemap: false
         })
 
+        /*
+         * experimental belongs to this transaction-local Rolldown options generation. Materialize it only when absent, then
+         * replace devMode with a new object so user fields survive without mutating a possibly shared configured sub-object.
+         */
         rolldownOptions.experimental ??= {}
-        rolldownOptions.experimental.devMode = createWxDevMode(
-            rolldownOptions.experimental.devMode,
-            await bundleRuntimeSource()
-        )
-
-        const reportInitialBuildPlugin: Plugin = {
-            name: 'vpt:wx-report-initial-build',
-            buildEnd: settleInitialBuild
+        const existingDevMode = rolldownOptions.experimental.devMode
+        rolldownOptions.experimental.devMode = {
+            ...(typeof existingDevMode === 'object' ? existingDevMode : {}),
+            implement: await bundleRuntimeSource(),
+            lazy: false,
+            skipCommonRuntimeInjection: false
         }
 
-        // Preserve the physical paths watched by WeChat DevTools across host restarts; the complete build overwrites every
-        // active output without disrupting the hot-reload watcher.
-        rolldownOptions.plugins = [
-            rolldownOptions.plugins,
-            hostPlugins,
-            reportInitialBuildPlugin,
-            createViteReporter(server)
-        ]
+        /*
+         * The plugin list is mutable configuration consumed once by this engine generation. Replace the top-level reference with
+         * an ordered composite rather than pushing into Vite's potentially shared nested array: existing transforms run first,
+         * host capture observes their final values, and the reporter observes final output without mutating either input list.
+         */
+        rolldownOptions.plugins = [rolldownOptions.plugins, hostPlugins, createViteReporter(server)]
         disableViteOxcSourcemap(rolldownOptions.plugins)
 
         return rolldownOptions
     }
-
-    return initialBuild.promise
 }
 
 /** Returns the configured output after rejecting states unsupported by the physical WX engine. */
@@ -113,6 +116,7 @@ function ensureSingleOutput(rolldownOptions: BundledDevRolldownOptions): OutputO
     if (Array.isArray(rolldownOptions.output)) {
         throw new Error('wx development requires one configured Rolldown output.')
     }
+    // Rolldown needs the created object attached to input options by identity; returning a detached fallback would be ignored.
     rolldownOptions.output ??= {}
     return rolldownOptions.output
 }
@@ -164,6 +168,11 @@ function disableViteOxcSourcemap(pluginOption: unknown): void {
 
     const plugin = pluginOption as ViteTransformPlugin
     if (plugin.name === 'builtin:vite-transform' && plugin._options?.transformOptions) {
+        /*
+         * Vite's private builtin retains this mutable transform options object and does not expose a public replacement hook.
+         * Updating its one sourcemap flag prevents Oxc from allocating maps that final WX output always discards; cloning the
+         * descriptor would not update the builtin closure that reads the original object during transforms.
+         */
         plugin._options.transformOptions.sourcemap = false
     }
 }
@@ -182,7 +191,12 @@ function createViteReporter(server: ViteDevServer) {
     })
 }
 
-// The runtime source is immutable for the host's lifetime, so the nested bundle is shared by every complete build.
+/*
+ * once owns a mutable cached Promise, justified because getRolldownOptions may run for multiple complete generations while the
+ * runtime input and build options remain immutable for the process lifetime. Sharing the in-flight/result Promise prevents
+ * concurrent options requests from launching duplicate nested builds; caching source instead of a Rolldown output object avoids
+ * leaking mutable bundle metadata between engines.
+ */
 const bundleRuntimeSource = once(async function bundleRuntimeSource(): Promise<string> {
     // write: false keeps this nested helper build from creating a second dist directory in the application project.
     const result = await build({

package/src/node/plugins/wx/module.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { Rolldown } from 'vite'
+import { normalizePath, type Rolldown } from 'vite'
 import { normalizeModuleId } from '../../utils/modules.ts'
 import { packageRequire, resolvePackageFile } from '../../utils/packages.ts'
 
@@ -7,9 +7,7 @@ import { packageRequire, resolvePackageFile } from '../../utils/packages.ts'
 export const rolldownRuntimeId = '\0rolldown/runtime.js'
 
 /** Resolves the direct React Reconciler dependency without assuming pnpm's layout. */
-export const reactReconcilerRoot = normalizeModuleId(
-    path.dirname(packageRequire.resolve('react-reconciler/package.json'))
-)
+export const reactReconcilerRoot = normalizePath(path.dirname(packageRequire.resolve('react-reconciler/package.json')))
 
 /** Identifies the amphibious bootstrap that initializes SystemJS and serves every native shell. */
 export const bootstrapPath = resolvePackageFile('dist/runtime/wx/amphibious/bootstrap.js')

package/src/node/plugins/wx/native/compile-native-component-interface.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { normalizePath } from 'vite'
 import { normalizeModuleId } from '../../../utils/modules.ts'
 import { collectNativeComponentAssets, nativeComponentMetaKey } from './native-component-assets.ts'
 import { transformNativeComponentInterfaces } from './native-component-interface.ts'
@@ -26,7 +27,7 @@ export async function compileNativeComponentInterface({
         addWatchFile(source.folder)
 
         source.assets.forEach((asset) => {
-            addWatchFile(normalizeModuleId(path.join(source.folder, asset.relativePath)))
+            addWatchFile(normalizePath(path.join(source.folder, asset.relativePath)))
         })
     })
 

package/src/node/plugins/wx/native/create-native-component-output.ts

@@ -43,6 +43,8 @@ export async function createNativeComponentOutput({
                 })
 
                 for (const asset of source.assets) {
+                    // Native folders are intentionally opaque to Rolldown, so no bundle asset contains these bytes to reuse.
+                    // Read each planned source once here to transfer it into the compiler-owned output bundle.
                     files.push({
                         type: 'asset',
                         fileName: path.posix.join(outputFolder, asset.relativePath),

package/src/node/plugins/wx/native/native-component-assets.ts

@@ -1,7 +1,6 @@
 import { readdir, stat } from 'node:fs/promises'
 import path from 'node:path'
-import type { Rolldown } from 'vite'
-import { normalizeModuleId } from '../../../utils/modules.ts'
+import { normalizePath, type Rolldown } from 'vite'
 import type { NativeComponentDefinition } from './native-component-interface.ts'
 
 type NativeComponentAsset = {
@@ -46,7 +45,7 @@ export async function collectNativeComponentAssets(
 
     // This mutable accumulator is local to one traversal and avoids repeatedly copying growing asset arrays.
     const assets: NativeComponentAsset[] = []
-    await collectDirectory(definition.folder, [], assets, normalizeModuleId(interfacePath))
+    await collectDirectory(definition.folder, [], assets, normalizePath(interfacePath))
 
     return { ...definition, assets }
 }
@@ -103,7 +102,7 @@ async function collectDirectory(
             continue
         }
         const sourcePath = path.join(folder, ...entrySegments)
-        if (normalizeModuleId(sourcePath) === interfacePath) {
+        if (normalizePath(sourcePath) === interfacePath) {
             continue
         }
         assets.push({

package/src/node/plugins/wx/native/native-component-interface.ts

@@ -3,6 +3,7 @@ import type { ExistingRawSourceMap } from 'rolldown'
 import { RolldownMagicString } from 'rolldown'
 import { parseAst } from 'rolldown/parseAst'
 import type { ESTree } from 'rolldown/utils'
+import { normalizePath } from 'vite'
 import { normalizeModuleId } from '../../../utils/modules.ts'
 import { clientTaroNativeId } from '../../client/constant.ts'
 
@@ -138,7 +139,7 @@ function parseDefinition(
         throw buildError('Native component entry must use () => import(...) with a static relative .js path')
     }
 
-    const entryPath = normalizeModuleId(path.resolve(path.dirname(moduleId), entryReference))
+    const entryPath = normalizePath(path.resolve(path.dirname(moduleId), entryReference))
     return {
         folder: path.posix.dirname(entryPath),
         entry: path.posix.basename(entryPath, '.js'),

package/src/node/plugins/wx/resolve/resolver.ts

@@ -1,3 +1,4 @@
+import { normalizePath } from 'vite'
 import type { VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../../options.ts'
 import { normalizeModuleId, resolveAppComponentPath, resolvePageComponentPath } from '../../../utils/modules.ts'
 import { createAppConfig } from '../../../utils/project-config.ts'
@@ -25,8 +26,8 @@ type PrivateIdResolver = (importer: string | undefined, projectRoot: string) =>
 
 /** Creates the resolver and source specializer for the wx module graph. */
 export function createResolver(options: VitePluginTaroOptions) {
-    const normalizedBootstrapPath = normalizeModuleId(bootstrapPath)
-    const normalizedPageCapsulePath = normalizeModuleId(pageCapsulePath)
+    const normalizedBootstrapPath = normalizePath(bootstrapPath)
+    const normalizedPageCapsulePath = normalizePath(pageCapsulePath)
 
     // Construct output input and application traversal roots together once so style order cannot drift from route order.
     const entryGraph = createEntryGraph(options.pages)

package/src/node/plugins/wx/styles/plugins.ts

@@ -48,6 +48,15 @@ export function createWxStylePlugins(): PluginOption[] {
  * remain opaque.
  */
 function createWxStyleFinalizer(transformStyle: typeof transformWxStyle): Plugin {
+    /*
+     * DevEngine can omit an unchanged stylesheet from later complete output generations. Absence therefore has two meanings:
+     * the first clean output genuinely has no styles, or a later output is reusing the physical stylesheet already on disk.
+     * The Vite server creates a fresh plugin instance on a clean start, so this one lifecycle bit distinguishes those cases and
+     * resets naturally on restart. Deliberately retain no CSS bytes or graph projection here: memory remains O(1), changed CSS
+     * still arrives as a normal asset, and the dev host remains the only owner of incremental style preparation.
+     */
+    let hasFinalizedOutput = false
+
     return {
         name: 'vpt:wx-style-finalizer',
         generateBundle: {
@@ -61,7 +70,17 @@ function createWxStyleFinalizer(transformStyle: typeof transformWxStyle): Plugin
                 }
 
                 if (styles.length === 0) {
-                    this.emitFile({ type: 'asset', fileName: 'assets/global.wxss', source: '' })
+                    /*
+                     * A clean first output must materialize the stable import target imported by app.wxss. On later complete
+                     * outputs, DevEngine's physical writer preserves files omitted from the bundle; emitting the same empty
+                     * placeholder would instead overwrite valid unchanged WXSS. Emit nothing in that later case. A source or
+                     * configuration change that really removes all styles is already published as empty by ordinary style HMR,
+                     * while a clean server restart reaches this first-output branch and also clears any stale prior file.
+                     */
+                    if (!hasFinalizedOutput) {
+                        this.emitFile({ type: 'asset', fileName: 'assets/global.wxss', source: '' })
+                    }
+                    hasFinalizedOutput = true
                     return
                 }
 
@@ -73,6 +92,7 @@ function createWxStyleFinalizer(transformStyle: typeof transformWxStyle): Plugin
                 // intact. Only its finalized contents and stable WXSS identity change.
                 style.source = transformedResult.css
                 style.fileName = 'assets/global.wxss'
+                hasFinalizedOutput = true
             }
         }
     }

package/src/node/utils/modules.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { normalizePath } from 'vite'
 
 type AppComponentPathOptions = {
     appPath: string
@@ -33,12 +34,12 @@ export function createPageComponentImportPath(options: PageComponentPathOptions)
     return toViteFileImportPath(resolvePageComponentPath(options))
 }
 
-/** Normalizes a file-backed Vite module ID for stable comparisons. */
+/** Converts a file-backed Vite request ID to its normalized physical path for stable comparisons. */
 export function normalizeModuleId(id: string): string {
-    return id.replaceAll('\\', '/').replace(/\?.*$/, '')
+    return normalizePath(id.replace(/\?.*$/, ''))
 }
 
 /** Converts a local file path into Vite's portable file-system import form. */
 export function toViteFileImportPath(filePath: string): string {
-    return `/@fs/${normalizeModuleId(path.resolve(filePath))}`
+    return `/@fs/${normalizePath(path.resolve(filePath))}`
 }

package/src/node/utils/packages.ts

@@ -1,11 +1,11 @@
 import { createRequire } from 'node:module'
 import path from 'node:path'
-import { normalizeModuleId } from './modules.ts'
+import { normalizePath } from 'vite'
 
 export const packageRequire = createRequire(import.meta.url)
 const packageRoot = path.dirname(packageRequire.resolve('vite-plugin-taro/package.json'))
 
 /** Resolves a file shipped by this package as a portable Vite module ID. */
 export function resolvePackageFile(...segments: string[]): string {
-    return normalizeModuleId(path.join(packageRoot, ...segments))
+    return normalizePath(path.join(packageRoot, ...segments))
 }

package/dist/node/plugins/wx/dev/create-wx-dev-mode.d.ts

@@ -1,6 +0,0 @@
-import type { InputOptions } from 'rolldown';
-type DevMode = NonNullable<NonNullable<InputOptions['experimental']>['devMode']>;
-type DevModeOptions = Exclude<DevMode, boolean>;
-/** Installs the custom WX runtime while restoring Rolldown's common runtime base. */
-export declare function createWxDevMode(devMode: DevMode | undefined, implement: string): DevModeOptions;
-export {};

package/dist/node/plugins/wx/dev/create-wx-dev-mode.js

@@ -1,9 +0,0 @@
-/** Installs the custom WX runtime while restoring Rolldown's common runtime base. */
-export function createWxDevMode(devMode, implement) {
-    return {
-        ...(typeof devMode === 'object' ? devMode : {}),
-        implement,
-        lazy: false,
-        skipCommonRuntimeInjection: false
-    };
-}