vite-plugin-taro 0.5.12 → 0.5.13

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

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises'
 import path from 'node:path'
 import type { BindingClientHmrUpdate } from 'rolldown/experimental'
 
+export const developmentAppWxssFileName = 'app.wxss'
 export const hmrInfoFileName = 'hmr/info.js'
 export const hmrPatchesFileName = 'hmr/patches.js'
 
@@ -28,6 +29,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.
  *

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

@@ -1,11 +1,11 @@
-import type { PluginOption } from 'vite'
-import { transformWithOxc } from 'vite'
+import { type PluginOption, transformWithOxc } from 'vite'
 import type { VitePluginTaroOptions } from '../../../../options.ts'
 import { esTarget } from '../../../utils/constant.ts'
 import { memoize } from '../../../utils/memoize.ts'
 import { normalizeModuleId } from '../../../utils/modules.ts'
 import { appCapsulePath, pageCapsulePath, rolldownRuntimeId, taroRuntimePath } from '../module.ts'
 import { createWxDevHost, type WxDevHost } from './dev-host.ts'
+import { developmentAppWxssFileName } from './hmr-files.ts'
 import { createWxReactRefreshTransforms } from './react-refresh.ts'
 
 const taroRuntimeId = '@tarojs/runtime'
@@ -13,8 +13,15 @@ const taroRuntimeId = '@tarojs/runtime'
 /**
  * Adds the serve-only bundled-development plugin set for the wx target: the dev adapter,
  * Page HMR activation, and React Refresh adaptation transforms.
+ *
+ * The ordered application entries cross this configuration boundary unchanged so the host can compose global CSS without
+ * reconstructing the resolver's App/Page ownership policy from unrelated Rolldown shell and transport entries.
  */
-export function createWxDevelopmentPlugin(options: VitePluginTaroOptions): PluginOption[] {
+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.
     let host: WxDevHost | null = null
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
     const normalizedAppCapsulePath = normalizeModuleId(appCapsulePath)
@@ -54,7 +61,21 @@ export function createWxDevelopmentPlugin(options: VitePluginTaroOptions): Plugi
                 // asks bundledDev to create its hard-coded skip-write DevEngine.
                 order: 'post',
                 async handler(server) {
-                    host = await createWxDevHost({ server, options })
+                    host = await createWxDevHost({
+                        server: server,
+                        options: options,
+                        applicationEntryIds: applicationEntryIds
+                    })
+                }
+            },
+
+            generateBundle: {
+                order: 'post',
+                handler(_, bundle) {
+                    // `vpt:wx` emits the production App wrapper during every complete build: initial startup and each
+                    // recovery build, not just once when this plugin instance is created. Development transfers that file
+                    // to the host so its only physical write happens after the matching build identity is durable.
+                    removeDevelopmentAppWxss(bundle)
                 }
             },
 
@@ -123,6 +144,25 @@ export function createWxDevelopmentPlugin(options: VitePluginTaroOptions): Plugi
     ]
 }
 
+/**
+ * Transfers development ownership of `app.wxss` from complete output to the dev host.
+ *
+ * The ordinary WX output hook emits the static production wrapper during every complete build. In development, the existing
+ * physical wrapper instead contains the previous build ID. If the static asset remained in this bundle, the DevEngine would:
+ *
+ * 1. replace the versioned wrapper with static production bytes while JavaScript and HMR metadata are still being finalized;
+ * 2. let DevTools observe that root-style change and reload the App against the previous build identity;
+ * 3. let the host replace the wrapper again with the new build ID, causing a second App reload.
+ *
+ * Deleting only the in-memory bundle entry avoids both premature writes. Development sets `emptyOutDir: false`, so the prior
+ * physical `app.wxss` remains available while the complete output is written. The host replaces it exactly once after
+ * `hmr/patches.js` and `hmr/info.js` are durable. Incremental HMR never enters this complete-output hook and continues changing
+ * only `assets/global.wxss`, which preserves the App heap. The serve-only plugin leaves production output unchanged.
+ */
+export function removeDevelopmentAppWxss(bundle: Record<string, unknown>): void {
+    delete bundle[developmentAppWxssFileName]
+}
+
 /** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
 export function injectReactRefreshBootstrap(code: string): { code: string; map: null } {
     return {

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

@@ -0,0 +1,34 @@
+import type { GetModuleInfo, Plugin } from 'rolldown'
+import { normalizeModuleId } from '../../../../utils/modules.ts'
+import { extractViteCss, isGlobalStyleRequest } from '../../styles/utils.ts'
+
+export type ProcessedStyle = Readonly<{
+    css: string
+    isTailwindRoot: boolean
+}>
+
+type StyleCaptureOptions = Readonly<{
+    captureGraph: (getModuleInfo: GetModuleInfo) => void
+    captureStyle: (id: string, style: ProcessedStyle) => void
+}>
+
+/** Captures Vite's final development CSS and Rolldown's live graph without running the style pipeline twice. */
+export function createStyleCapturePlugin({ captureGraph, captureStyle }: StyleCaptureOptions): Plugin {
+    return {
+        name: 'vpt:wx-dev-style-capture',
+        buildStart() {
+            captureGraph((moduleId) => this.getModuleInfo(moduleId))
+        },
+        transform(code, id) {
+            if (!isGlobalStyleRequest(id)) {
+                return
+            }
+
+            const css = extractViteCss(code, id)
+            captureStyle(normalizeModuleId(id), {
+                css: css,
+                isTailwindRoot: css.includes('weapp-tailwindcss vite-generated-css:')
+            })
+        }
+    }
+}

package/src/node/plugins/wx/dev/styles/publish-style-hmr.ts

@@ -0,0 +1,71 @@
+import { transformWxStyle } from '../../styles/transform-wx-style.ts'
+import { composeGraphStyleCss, createTailwindSidecarId, extractViteCss } from '../../styles/utils.ts'
+import { writeHmrFile } from '../hmr-files.ts'
+import type { ProcessedStyle } from './create-style-capture-plugin.ts'
+
+export const globalWxssFileName = 'assets/global.wxss'
+
+type StyleHmrOptions = Readonly<{
+    styleIds: readonly string[]
+    outDir: string
+    processedStyles: ReadonlyMap<string, ProcessedStyle>
+    publishedWxss: string | undefined
+}>
+
+/** Regenerates reachable Tailwind roots concurrently from upstream's current candidate state. */
+export 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
+        })
+    )
+    // Commit the cache generation only after every independent root succeeds; a failed sibling cannot leave a mixed snapshot.
+    refreshedStyles.forEach(([rootId, style]) => {
+        processedStyles.set(rootId, style)
+    })
+}
+
+/**
+ * Materializes one host-owned style snapshot for a completed HMR transaction.
+ *
+ * Rolldown owns topology but does not retain Vite's final CSS module payload, while `processedStyles` owns those payloads but
+ * deliberately retains no topology. The caller supplies the transaction's one ordered graph plan; both Tailwind refresh and
+ * this renderer consume that same snapshot, so sidecar generation cannot cause a second topology traversal.
+ *
+ * Ordinary CSS is never transformed again here: capture already observed it after Vite/PostCSS. The composed stylesheet alone
+ * receives the same final WX conversion as complete builds. Byte equality with the host's physical publication frontier skips
+ * an atomic rename that would otherwise notify DevTools despite no style change. The returned bytes advance that frontier only
+ * after any required write succeeds. The caller awaits this before exposing the corresponding JavaScript patch.
+ * Complexity is O(styles + CSS bytes), after the caller's O(V + E) plan traversal.
+ */
+export async function publishStyleHmr({
+    styleIds,
+    outDir,
+    processedStyles,
+    publishedWxss
+}: StyleHmrOptions): Promise<string> {
+    const css = composeGraphStyleCss(styleIds, (styleId) => requireProcessedStyle(processedStyles, styleId).css)
+    const wxss = (await transformWxStyle(css)).css
+    if (wxss !== publishedWxss) {
+        await writeHmrFile(outDir, globalWxssFileName, wxss)
+    }
+    return wxss
+}
+
+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/wx-dev-options.ts

@@ -28,11 +28,13 @@ export type BundledDev = {
 export function installWxDevOptions({
     bundledDev,
     server,
-    options
+    options,
+    hostPlugins
 }: {
     bundledDev: BundledDev
     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.
@@ -83,7 +85,12 @@ export function installWxDevOptions({
 
         // 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, reportInitialBuildPlugin, createViteReporter(server)]
+        rolldownOptions.plugins = [
+            rolldownOptions.plugins,
+            hostPlugins,
+            reportInitialBuildPlugin,
+            createViteReporter(server)
+        ]
         disableViteOxcSourcemap(rolldownOptions.plugins)
 
         return rolldownOptions

package/src/node/plugins/wx/output/files.ts

@@ -5,7 +5,7 @@ import type { GeneratedSubpackage } from '../placement/placer.ts'
 import { createJsonAssets } from './json.ts'
 import { createTemplateAssets } from './templates.ts'
 
-/** Creates every native companion file derived from the final Rolldown bundle. */
+/** Creates every compiler-owned WX file derived from the final Rolldown bundle. */
 export async function createOutputFiles({
     bundle,
     options,
@@ -20,6 +20,11 @@ export async function createOutputFiles({
     const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo })
 
     return [
+        {
+            type: 'asset',
+            fileName: 'app.wxss',
+            source: '@import "./assets/global.wxss";\n'
+        },
         ...createJsonAssets({ options, subpackages, nativeComponents: nativeOutput.registrations }),
         ...createTemplateAssets(bundle, options, nativeOutput.registrations),
         ...nativeOutput.files

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

@@ -13,15 +13,25 @@ import { renderCapsule } from './render/capsule.ts'
 import { renderNative } from './render/native.ts'
 import { materializeTransport } from './render/transport.ts'
 import { createResolver } from './resolve/resolver.ts'
+import { createWxStylePlugins } from './styles/plugins.ts'
+
+type WxResolver = ReturnType<typeof createResolver>
 
 /** Creates the complete plugin set for the wx target. */
 export function createWxTargetPlugins(options: VitePluginTaroOptions): PluginOption[] {
-    return [createWxPlugin(options), createWxDevelopmentPlugin(options)]
+    const resolver = createResolver(options)
+
+    // Reuse the resolver instance's ordered application subset. Rolldown's complete input also contains bootstrap, transport,
+    // shell, and component entries; entry membership alone cannot recover which roots define the App/Page CSS cascade.
+    return [
+        createWxStylePlugins(),
+        createWxPlugin(options, resolver),
+        createWxDevelopmentPlugin(options, resolver.applicationEntryIds)
+    ]
 }
 
 /** Configures the complete wx target build pipeline. */
-function createWxPlugin(options: VitePluginTaroOptions): Plugin {
-    const resolver = createResolver(options)
+function createWxPlugin(options: VitePluginTaroOptions, resolver: WxResolver): Plugin {
     const placer = createPlacer()
 
     return {
@@ -127,10 +137,10 @@ function createWxPlugin(options: VitePluginTaroOptions): Plugin {
 
         generateBundle: {
             /*
-             * This hook is registered after createCssPlugins() and shares hook-level `order: 'post'` with the adapted
+             * This hook is registered after createWxStylePlugins() and shares hook-level `order: 'post'` with the adapted
              * upstream hooks and VPT style finalizer. Registration order therefore guarantees that the imported global
-             * stylesheet is complete before native Page/component companions are emitted. Without this order, the finalizer could consume
-             * incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
+             * stylesheet is complete before native Page/component companions are emitted. Without this order, the finalizer
+             * could consume incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
              */
             order: 'post',
             async handler(_, bundle) {

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

@@ -28,6 +28,9 @@ export function createResolver(options: VitePluginTaroOptions) {
     const normalizedBootstrapPath = normalizeModuleId(bootstrapPath)
     const normalizedPageCapsulePath = normalizeModuleId(pageCapsulePath)
 
+    // Construct output input and application traversal roots together once so style order cannot drift from route order.
+    const entryGraph = createEntryGraph(options.pages)
+
     // Provide constant-time route validation and access to each configured Page JSON object.
     const pageByPath = new Map(options.pages.map((page) => [page.path, page]))
 
@@ -56,7 +59,7 @@ export function createResolver(options: VitePluginTaroOptions) {
     ])
 
     return {
-        input: createInput(options.pages),
+        ...entryGraph,
 
         resolveId(id: string, importer: string | undefined, projectRoot: string): string | undefined {
             // Unknown IDs fall through so Vite and other plugins retain normal resolution.
@@ -82,22 +85,35 @@ export function createResolver(options: VitePluginTaroOptions) {
     }
 }
 
-/** Declares native shells, infrastructure, and capsules as independent output entries. */
-function createInput(pages: readonly VitePluginTaroPageOption[]): Record<string, string> {
-    return Object.fromEntries([
-        ['bootstrap', bootstrapPath],
-        ['transport', transportPath],
-        [appShellFileName, appShellPath],
-        ['app-capsule', appCapsulePath],
-        [componentShellFileName, componentShellPath],
-        ['component-capsule', componentCapsulePath],
-        ...pages.flatMap((page) => {
-            return [
-                [`${page.path}.js`, createRouteModuleId({ moduleId: pageShellPath, pagePath: page.path })],
-                [`${page.path}-capsule`, createRouteModuleId({ moduleId: pageCapsulePath, pagePath: page.path })]
-            ]
-        })
-    ])
+/** Declares output entries and the ordered application subset that can own user styles. */
+function createEntryGraph(pages: readonly VitePluginTaroPageOption[]) {
+    const pageEntries = pages.map((page) => {
+        return {
+            capsuleId: createRouteModuleId({ moduleId: pageCapsulePath, pagePath: page.path }),
+            capsuleName: `${page.path}-capsule`,
+            shellId: createRouteModuleId({ moduleId: pageShellPath, pagePath: page.path }),
+            shellName: `${page.path}.js`
+        }
+    })
+
+    return {
+        // The App owns the first global cascade layer; configured Pages follow in their declared route order.
+        applicationEntryIds: [appCapsulePath, ...pageEntries.map((entry) => entry.capsuleId)],
+        input: Object.fromEntries([
+            ['bootstrap', bootstrapPath],
+            ['transport', transportPath],
+            [appShellFileName, appShellPath],
+            ['app-capsule', appCapsulePath],
+            [componentShellFileName, componentShellPath],
+            ['component-capsule', componentCapsulePath],
+            ...pageEntries.flatMap((entry) => {
+                return [
+                    [entry.shellName, entry.shellId],
+                    [entry.capsuleName, entry.capsuleId]
+                ]
+            })
+        ])
+    }
 }
 
 /** Creates one route-qualified module ID. */

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

@@ -0,0 +1,105 @@
+import type { Plugin, PluginOption, Rolldown } from 'vite'
+import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
+import { transformVitePlugin } from '../../../utils/vite.ts'
+import { tailwindcssBasedir } from '../../tailwind/tailwind-css.ts'
+import { transformWxStyle, wxStyleOptions } from './transform-wx-style.ts'
+
+/*
+ * WX style output order:
+ *
+ *   weapp-tailwindcss output hooks
+ *       → vpt:wx-style-finalizer
+ *       → vpt:wx native companion emission
+ *
+ * All three generateBundle hooks retain hook-level `order: 'post'` and therefore execute in registration order. The
+ * upstream plugin normally also uses plugin-level `enforce: 'post'`, which would move it behind both VPT plugins and
+ * break this sequence. `alignGenerateBundleOrder` removes only that broader phase from upstream output hooks.
+ */
+
+/** Creates the complete WX Tailwind and global-style pipeline. */
+export function createWxStylePlugins(): PluginOption[] {
+    const tailwindPlugins =
+        WeappTailwindcss({
+            // VPT is a custom Vite compiler.
+            // Using Taro's adapter would import Taro-specific CSS ownership rules which we don't need.
+            appType: 'weapp-vite',
+            // WX generation rewrites Tailwind's split package imports before Vite tries to resolve them in the app.
+            // Without this, strict workspaces fail on imports such as `tailwindcss/theme.css`.
+            rewriteCssImports: true,
+            platform: 'weapp',
+            tailwindcssBasedir,
+            generator: {
+                target: 'weapp'
+            },
+            cssOptions: wxStyleOptions,
+            logLevel: 'warn'
+        }) ?? []
+
+    return [transformVitePlugin(tailwindPlugins, alignGenerateBundleOrder), createWxStyleFinalizer(transformWxStyle)]
+}
+
+/**
+ * Finalizes the one global stylesheet after upstream Tailwind generation.
+ *
+ * `cssCodeSplit: false` makes the compiler style global, but upstream can name it `.css` or `.wxss` depending on build
+ * mode. This hook converts its complete final contents once and renames that compiler asset to `assets/global.wxss`. An
+ * application without styles receives an empty global asset at the same stable path. Running earlier loses CSS from
+ * dynamic chunks; running after native companion emission would also see Page and native-component WXSS files that must
+ * remain opaque.
+ */
+function createWxStyleFinalizer(transformStyle: typeof transformWxStyle): Plugin {
+    return {
+        name: 'vpt:wx-style-finalizer',
+        generateBundle: {
+            order: 'post',
+            async handler(_, bundle) {
+                const styles = Object.values(bundle).filter(isStyleAsset)
+
+                // Multiple compiler styles mean cssCodeSplit was re-enabled. Choosing one would silently lose CSS.
+                if (styles.length > 1) {
+                    throw new Error('WX builds support at most one compiler-emitted stylesheet')
+                }
+
+                if (styles.length === 0) {
+                    this.emitFile({ type: 'asset', fileName: 'assets/global.wxss', source: '' })
+                    return
+                }
+
+                const [style] = styles
+                const source = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+                const transformedResult = await transformStyle(source)
+
+                // Preserve the compiler stylesheet as the real global asset so its bundle metadata and ownership remain
+                // intact. Only its finalized contents and stable WXSS identity change.
+                style.source = transformedResult.css
+                style.fileName = 'assets/global.wxss'
+            }
+        }
+    }
+}
+
+/**
+ * Adapts upstream plugin descriptors without mutating `weapp-tailwindcss` or patching node_modules.
+ *
+ * Vite first groups whole plugins by `enforce`, then orders individual hooks. Upstream's output plugins specify both
+ * `enforce: 'post'` and `generateBundle.order: 'post'`. The plugin-level phase overrides their earlier registration and
+ * places them after VPT's normal plugins, so VPT observes incomplete CSS. Making all of VPT post-enforced would fix that
+ * one hook while unnecessarily reordering resolution and transforms.
+ *
+ * For upstream plugins that actually own generateBundle, clone the descriptor without plugin-level enforcement. Keep
+ * hook-level `order: 'post'`: it still waits for ordinary bundle generation, while registration order becomes the sole
+ * tie-breaker between upstream generation, VPT finalization and native output.
+ */
+function alignGenerateBundleOrder(plugin: Plugin): Plugin {
+    if (plugin.enforce !== 'post' || plugin.generateBundle === undefined) {
+        return plugin
+    }
+
+    // Clone rather than mutate: upstream may retain or reuse the descriptor returned by its factory.
+    return { ...plugin, enforce: undefined }
+}
+
+/** Selects only the compiler stylesheet; native WXSS assets are emitted by the later WX hook. */
+function isStyleAsset(output: Rolldown.OutputBundle[string]): output is Rolldown.OutputAsset {
+    return output.type === 'asset' && /\.(?:css|wxss)$/.test(output.fileName)
+}

package/src/node/plugins/wx/styles/transform-wx-style.ts

@@ -0,0 +1,11 @@
+import { createStyleHandler } from '@weapp-tailwindcss/postcss'
+
+export const wxStyleOptions = {
+    cssCalc: false,
+    autoprefixer: false,
+    rem2rpx: true,
+    px2rpx: true
+} as const
+
+/** Shared finalization policy for complete builds and host-owned style HMR. */
+export const transformWxStyle = createStyleHandler(wxStyleOptions)

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

@@ -0,0 +1,119 @@
+import { isCSSRequest } from 'vite'
+import { normalizeModuleId } from '../../../utils/modules.ts'
+
+const nonRuntimeStyleQueries = ['direct', 'inline', 'inline-css', 'raw', 'style-attr', 'transform-only', 'url'] as const
+
+/**
+ * Creates an auxiliary style request without replacing the physical Rolldown graph module.
+ *
+ * `weapp-vite-sidecar` is an upstream protocol marker, not a cache-busting nonce. `weapp-tailwindcss` detects the query
+ * key, strips the complete query when resolving the physical CSS pipeline file, and excludes this synthetic request from
+ * transformed-source candidate collection. That lets the request use the latest candidate state without feeding generated
+ * CSS back into Tailwind's source memory. The descriptive `style` value is stable; upstream treats the presence of the key
+ * as the protocol contract.
+ */
+export function createTailwindSidecarId(rootId: string): string {
+    return `${rootId}?weapp-vite-sidecar=style`
+}
+
+/** Selects imported style modules whose Vite development output owns a runtime CSS payload. */
+export function isGlobalStyleRequest(id: string): boolean {
+    if (!isCSSRequest(id)) {
+        return false
+    }
+
+    const queryStart = id.indexOf('?')
+    if (queryStart < 0) {
+        return true
+    }
+
+    const fragmentStart = id.indexOf('#', queryStart)
+    const query = id.slice(queryStart + 1, fragmentStart < 0 ? undefined : fragmentStart)
+    const parameters = new URLSearchParams(query)
+
+    return (
+        !parameters.has('weapp-vite-sidecar') && nonRuntimeStyleQueries.every((parameter) => !parameters.has(parameter))
+    )
+}
+
+/**
+ * Creates the ordered style plan for one completed HMR transaction.
+ *
+ * `entryIds` carries semantic cascade ownership from the WX resolver: the App capsule first, followed by Page capsules in
+ * configured route order. Each entry is traversed depth-first. Static imports retain source order and precede dynamic imports;
+ * dynamic branches are included because WX cannot inject lazy CSS at browser runtime. A style follows its dependencies,
+ * matching evaluation order.
+ *
+ * Graph IDs may contain queries while `hasStyle` reads physical IDs. Normalization lets aliases share one captured style.
+ * JavaScript and non-runtime CSS requests remain traversal nodes but do not enter the plan. All mutable traversal state is
+ * transaction-local, so import additions and removals need no invalidation bookkeeping. Complexity is O(modules + edges),
+ * with O(modules + styles) temporary memory.
+ */
+export function createGraphStylePlan(
+    entryIds: readonly string[],
+    getModuleInfo: (
+        moduleId: string
+    ) => Readonly<{ importedIds: readonly string[]; dynamicallyImportedIds: readonly string[] }> | null,
+    hasStyle: (styleId: string) => boolean
+): readonly string[] {
+    // These local collections collapse cycles, shared modules, and aliases without retaining derived topology between batches.
+    const visitedModuleIds = new Set<string>()
+    const visitedStyleIds = new Set<string>()
+    const styleIds: string[] = []
+
+    const visit = (moduleId: string): void => {
+        if (visitedModuleIds.has(moduleId)) {
+            return
+        }
+        visitedModuleIds.add(moduleId)
+
+        const moduleInfo = getModuleInfo(moduleId)
+        if (!moduleInfo) {
+            return
+        }
+
+        moduleInfo.importedIds.forEach(visit)
+        moduleInfo.dynamicallyImportedIds.forEach(visit)
+
+        const styleId = normalizeModuleId(moduleId)
+        if (hasStyle(styleId) && !visitedStyleIds.has(styleId)) {
+            visitedStyleIds.add(styleId)
+            styleIds.push(styleId)
+        }
+    }
+
+    entryIds.forEach(visit)
+    return styleIds
+}
+
+/** Renders one immutable graph plan after any Tailwind roots in that same plan have been refreshed. */
+export function composeGraphStyleCss(styleIds: readonly string[], getStyleCss: (styleId: string) => string): string {
+    return styleIds.map(getStyleCss).join('\n')
+}
+
+/**
+ * Extracts Vite's final CSS payload from the development module without evaluating its browser HMR code.
+ *
+ * Remove this parser when either Vite exposes a supported plugin-container API that returns final CSS directly, or
+ * `weapp-tailwindcss` exposes generated root CSS after candidate updates. Until then the sidecar receives Vite's JavaScript
+ * style module, so this function isolates the version-specific `__vite__css` serialization contract.
+ */
+export function extractViteCss(moduleCode: string, rootId: string): string {
+    const assignmentPrefix = 'const __vite__css = '
+    const assignmentStart = moduleCode.indexOf(assignmentPrefix)
+    if (assignmentStart < 0) {
+        throw new Error(`Vite CSS transform for ${rootId} did not expose __vite__css`)
+    }
+
+    // Vite serializes the payload with JSON.stringify on one assignment line. Parse that literal so quotes, escapes, and
+    // embedded CSS newlines are decoded by JSON rather than by a second, subtly different unescaping implementation.
+    const valueStart = assignmentStart + assignmentPrefix.length
+    const lineEnd = moduleCode.indexOf('\n', valueStart)
+    const serializedCss = moduleCode.slice(valueStart, lineEnd < 0 ? moduleCode.length : lineEnd)
+    const css: unknown = JSON.parse(serializedCss)
+    if (typeof css !== 'string') {
+        throw new Error(`Vite CSS transform for ${rootId} exposed a non-string __vite__css value`)
+    }
+
+    return css
+}