vite-plugin-taro 0.5.1 → 0.5.4

package/dist/node/plugins/wx/plugins.js

@@ -36,8 +36,11 @@ function createWxPlugin(options) {
                 },
                 build: {
                     modulePreload: false,
+                    // Mini Program styles are intentionally global. This guarantees one compiler stylesheet for the CSS
+                    // finalizer; enabling splitting would require Page ownership and must not be silently flattened.
                     cssCodeSplit: false,
-                    // Let weapp-tailwindcss own final WXSS transformation.
+                    // Preserve readable source for the final WX compatibility pass; browser minification can emit syntax
+                    // unsupported by WeChat and would make the subsequent whole-file conversion harder to reason about.
                     cssMinify: false,
                     // No base64 assets: Taro warns on image srcs above ~2KB, and inlined
                     // images bloat the JS bundle toward the mini program package limit.
@@ -99,6 +102,12 @@ function createWxPlugin(options) {
             }
         },
         generateBundle: {
+            /*
+             * This hook is registered after createCssPlugins() and shares hook-level `order: 'post'` with the adapted
+             * upstream hooks and VPT style finalizer. Registration order therefore guarantees that app.wxss is complete
+             * before native Page/component companions are emitted. Without this order, the CSS finalizer could consume
+             * incomplete Tailwind output or mistake native WXSS companions for additional compiler styles.
+             */
             order: 'post',
             async handler(_, bundle) {
                 const subpackages = placer.getSubpackages(bundle);

package/dist/node/vite-plugin.js

@@ -8,7 +8,7 @@ import { createWxTargetPlugins } from './plugins/wx/plugins.js';
 export default function vitePluginTaro(options) {
     return [
         createConditionalDirectivePlugin(options.target),
-        createClientTaroPlugin(),
+        createClientTaroPlugin(options.target),
         ...createCssPlugins(options.target),
         ...react(),
         ...(options.target === 'wx' ? createWxTargetPlugins(options) : []),

package/dist/runtime/client/taro/api.d.ts

@@ -1,4 +1,3 @@
-import '@tarojs/plugin-framework-react/dist/runtime';
-import Taro from '@tarojs/taro';
+import taro from '@tarojs/taro';
 export * from '@tarojs/taro';
-export default Taro;
+export default taro;

package/dist/runtime/client/taro/api.js

@@ -1,9 +1,10 @@
-import '@tarojs/plugin-framework-react/dist/runtime';
-import { hooks } from '@tarojs/runtime';
-import Taro from '@tarojs/taro';
-if (hooks.isExist('initNativeApi')) {
-    hooks.call('initNativeApi', Taro);
-}
-// @ts-expect-error @tarojs/taro declares export= types, but the facade also exposes its runtime named exports.
+/*
+ * This physical module is the shared facade, not the generic Taro implementation. Its own `@tarojs/taro` request is
+ * resolved by the client plugin to the selected platform APIs, while application requests resolve back to this facade.
+ * React's API loader then extends this same object with framework lifecycle hooks.
+ */
+import taro from '@tarojs/taro';
+// Re-export platform APIs while preserving object identity for the framework loader's lifecycle assignments.
+// @ts-expect-error @tarojs/taro uses export= types while Rolldown exposes its runtime properties as named exports.
 export * from '@tarojs/taro';
-export default Taro;
+export default taro;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.5.1",
+  "version": "0.5.4",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/sep2/vite-plugin-taro/issues"
   },
-  "homepage": "https://github.com/sep2/vite-plugin-taro/tree/main/packages/vite-plugin-taro#readme",
+  "homepage": "https://vpt.js.org",
   "main": "./dist/vite.js",
   "module": "./dist/vite.js",
   "types": "./dist/vite.d.ts",
@@ -58,24 +58,24 @@
     "@babel/plugin-transform-modules-systemjs": "^7.29.8",
     "@rolldown/plugin-babel": "^0.2.3",
     "@tailwindcss-mangle/engine": "0.2.0",
-    "@tarojs/components": "^4.2.0",
-    "@tarojs/helper": "^4.2.0",
-    "@tarojs/plugin-platform-h5": "^4.2.0",
-    "@tarojs/plugin-platform-weapp": "^4.2.0",
-    "@tarojs/router": "^4.2.0",
-    "@tarojs/runtime": "^4.2.0",
-    "@tarojs/taro": "^4.2.0",
+    "@tarojs/components": "4.2.0",
+    "@tarojs/helper": "4.2.0",
+    "@tarojs/plugin-platform-h5": "4.2.0",
+    "@tarojs/plugin-platform-weapp": "4.2.0",
+    "@tarojs/router": "4.2.0",
+    "@tarojs/runtime": "4.2.0",
+    "@tarojs/taro": "4.2.0",
     "@vitejs/plugin-react": "^6.0.5",
     "@weapp-tailwindcss/postcss": "3.2.8",
-    "babel-plugin-transform-taroapi": "^4.2.0",
+    "babel-plugin-transform-taroapi": "4.2.0",
     "picocolors": "^1.1.1",
     "react-reconciler": "0.33.0",
     "react-refresh": "^0.18.0",
     "rolldown": "1.2.3",
     "tailwindcss": "^4.3.3",
     "weapp-tailwindcss": "^5.2.11",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.1",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.1"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.5.4",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.5.4"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/node/plugins/client/client-taro.ts

@@ -1,23 +1,71 @@
 import type { Plugin } from 'vite'
+import type { VitePluginTaroTarget } from '../../../options.ts'
+import { normalizeModuleId } from '../../utils/modules.ts'
 import { resolvePackageFile } from '../../utils/packages.ts'
 import { clientTaroNativeId } from './constant.ts'
+import { injectTaroFrameworkApis } from './inject-taro-framework-apis.ts'
 
+/*
+ * Taro API resolution uses one public facade while avoiding a recursive `@tarojs/taro` import:
+ *
+ * 1. Application imports of `virtual:taro/api` or `@tarojs/taro` resolve to the physical `api.js` facade.
+ * 2. The facade itself imports `@tarojs/taro`; its importer identifies that request as the platform implementation.
+ * 3. H5 receives `@tarojs/plugin-platform-h5` APIs, while WX receives the generic `@tarojs/taro` implementation.
+ * 4. React's framework API loader transforms the facade, assigning lifecycle hooks such as `useLaunch` to the same
+ *    platform object and exposing them as named exports.
+ *
+ * The importer-sensitive second step removes the need for another public-looking virtual module while retaining one
+ * facade object for platform APIs and framework lifecycles.
+ */
+/** Public facade used by transformed application API imports. */
 export const clientTaroApiId = 'virtual:taro/api'
+
+const clientTaroApiPath = resolvePackageFile('dist/runtime/client/taro/api.js')
+const normalizedClientTaroApiPath = normalizeModuleId(clientTaroApiPath)
+
 const clientTaroComponentId = 'virtual:taro/components'
+
 const clientTaroModules = new Map([
-    [clientTaroApiId, resolvePackageFile('dist/runtime/client/taro/api.js')],
+    [clientTaroApiId, clientTaroApiPath],
     [clientTaroComponentId, resolvePackageFile('dist/runtime/client/taro/component.js')],
     [clientTaroNativeId, resolvePackageFile('dist/runtime/client/taro/define-native-component.js')]
 ])
 
-/** Creates the target-neutral Taro facade plugin. */
-export function createClientTaroPlugin(): Plugin {
+/** Creates the shared Taro facade backed by the selected target's API implementation. */
+export function createClientTaroPlugin(target: VitePluginTaroTarget): Plugin {
+    const platformTaroId = resolvePlatformTaroId(target)
+
     return {
         name: 'vpt:client-taro',
         enforce: 'pre',
 
-        resolveId(id) {
+        async resolveId(id, importer) {
+            if (id === '@tarojs/taro') {
+                if (!isClientTaroFacade(importer)) {
+                    return clientTaroApiPath
+                }
+
+                // Delegate the platform backend to Vite instead of returning an absolute dependency path. H5 marks this
+                // backend as an optimization root, so delegation lets Vite substitute its prebundled facade. Removing it
+                // bypasses CommonJS interop and exposes backend details such as base64-js directly to the browser.
+                return this.resolve(platformTaroId, importer, { skipSelf: true })
+            }
             return clientTaroModules.get(id)
+        },
+
+        // Taro's framework loader transforms source code, so apply it only to the shared physical facade.
+        transform(code, id) {
+            if (normalizeModuleId(id) === normalizedClientTaroApiPath) {
+                return injectTaroFrameworkApis(code)
+            }
         }
     }
 }
+
+function resolvePlatformTaroId(target: VitePluginTaroTarget): string {
+    return target === 'h5' ? '@tarojs/plugin-platform-h5/dist/runtime/apis' : '@tarojs/taro'
+}
+
+function isClientTaroFacade(importer: string | undefined): boolean {
+    return importer !== undefined && normalizeModuleId(importer) === normalizedClientTaroApiPath
+}

package/src/node/plugins/client/inject-taro-framework-apis.ts

@@ -0,0 +1,11 @@
+import { packageRequire } from '../../utils/packages.ts'
+
+const apiLoader: (source: string) => string = packageRequire('@tarojs/plugin-framework-react/dist/api-loader')
+
+/**
+ * Applies Taro React's standard source-to-source API loader. It imports the framework lifecycle hooks, assigns them to
+ * the facade's `taro` object, and emits matching named exports; keeping the hook inventory owned by Taro avoids drift.
+ */
+export function injectTaroFrameworkApis(source: string): string {
+    return apiLoader(source)
+}

package/src/node/plugins/css/plugins.ts

@@ -5,10 +5,24 @@ import { WeappTailwindcss } from 'weapp-tailwindcss/vite'
 import type { VitePluginTaroTarget } from '../../../options.ts'
 import { packageRequire } from '../../utils/packages.ts'
 
-// Keep the Vite plugin and the compatibility finalizer on identical WX conversion settings. A difference here can
-// make the second pass preserve browser units or apply a transformation that the first pass did not expect.
+/*
+ * CSS output order for WX:
+ *
+ *   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. `alignWxGenerateBundleOrder` removes only that broader phase from upstream output hooks.
+ */
+
+// Tailwind belongs to VPT, not necessarily to the application. Resolving from VPT keeps strict package managers and
+// bundled development from looking for Tailwind in the application's node_modules.
 const tailwindcssBasedir = path.dirname(packageRequire.resolve('tailwindcss/package.json'))
 
+// Both upstream generation and VPT's final whole-file pass use one conversion policy. If these options diverge, the
+// second pass can preserve browser units or reinterpret syntax that the first pass generated.
 const wxStyleOptions = {
     cssCalc: false,
     autoprefixer: false,
@@ -16,84 +30,106 @@ const wxStyleOptions = {
     px2rpx: true
 } as const
 
-const transformWxss = createStyleHandler(wxStyleOptions)
-
-/** Completes the final compatibility pass required by generated WXSS. */
-export async function adaptWxss(source: string): Promise<string> {
-    return (await transformWxss(source)).css
-}
+// The handler is immutable and reusable across builds; only each emitted asset's source is replaced.
+const transformWxStyle = createStyleHandler(wxStyleOptions)
 
-/** Creates the target-aware Tailwind CSS plugins. */
+/** Creates the target-aware Tailwind pipeline. */
 export function createCssPlugins(target: VitePluginTaroTarget): PluginOption[] {
     const wx = target === 'wx'
 
-    return [
-        ...(WeappTailwindcss({
+    const tailwindPlugins =
+        WeappTailwindcss({
+            // VPT is a custom Vite compiler. Using Taro's adapter would import Taro-specific CSS ownership rules.
             appType: 'weapp-vite',
-            // WX must enable this for split Tailwind imports such as `tailwindcss/theme.css`. Otherwise Vite's
-            // PostCSS resolver tries to resolve those imports from the application and fails when Tailwind is owned
-            // by vpt. The web generator consumes the imports before that resolver runs, so H5 keeps the
-            // upstream default.
+            // 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: wx,
-            // Tailwind is a plugin dependency, not an application dependency. Give weapp-tailwindcss the owning package
-            // directory explicitly so bundled development and strict package managers resolve split CSS imports equally.
+            platform: wx ? 'weapp' : 'web',
             tailwindcssBasedir,
             generator: {
                 target: wx ? 'weapp' : 'web'
-                // webCompat: {
-                //     preset: 'legacy-web'
-                // }
             },
             cssOptions: {
                 ...wxStyleOptions,
+                // Browser output still needs vendor prefixes; WXSS does not support or need that browser pass.
                 autoprefixer: !wx
             },
             logLevel: 'warn'
-        }) ?? []),
-        wx ? createWxssCompatibilityFinalizer() : undefined
+        }) ?? []
+
+    return [
+        ...(wx ? tailwindPlugins.map(alignWxGenerateBundleOrder) : tailwindPlugins),
+        wx ? createWxStyleFinalizer() : undefined
     ]
 }
 
 /**
- * Completes WXSS adaptation that weapp-tailwindcss leaves pending after rewriting split Tailwind imports.
+ * Finalizes the one global stylesheet after upstream Tailwind generation.
  *
- * `rewriteCssImports: true` makes the early Vite transform generate the Tailwind CSS, but the non-web generator
- * also defers CSS adaptation. The generated asset is consequently browser-shaped
- * CSS containing values and syntax such as `rem`, escaped class selectors, and `@property`. It is then recorded as a
- * processed Vite asset, so the upstream output finalizer does not perform the missing complete WXSS adaptation.
- *
- * This plugin runs after the upstream finalizer, repeats only the compatibility transform, and restores the captured
- * global asset to WeChat's required `app.wxss` path. Exact path correlation leaves Page WXSS companions untouched.
- * Remove it when upstream both completes adaptation and preserves the bundler-selected filename.
+ * `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 gives it the root `app.wxss` identity required by
+ * WeChat. 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 createWxssCompatibilityFinalizer(): Plugin {
+function createWxStyleFinalizer(): Plugin {
     return {
-        name: 'vpt:wxss-compatibility-finalizer',
-        enforce: 'post',
+        name: 'vpt:wx-style-finalizer',
         generateBundle: {
             order: 'post',
             async handler(_, bundle) {
-                // With cssCodeSplit: false the global style is the only asset with a logical
-                // .css source name, even when an earlier hook already changed its final suffix.
-                const globalStyleAsset = Object.values(bundle).find(
-                    (output): output is Rolldown.OutputAsset =>
-                        output.type === 'asset' &&
-                        (output.fileName.replaceAll('\\', '/').endsWith('.css') ||
-                            output.names.some((name) => name.replaceAll('\\', '/').endsWith('.css')))
-                )
-                if (!globalStyleAsset) return
-
-                // Both finalizers use a post-ordered generateBundle hook. Array order places this hook after the
-                // upstream finalizer, where the single Vite global style asset has its final contents and filename.
-                const source =
-                    typeof globalStyleAsset.source === 'string'
-                        ? globalStyleAsset.source
-                        : new TextDecoder().decode(globalStyleAsset.source)
-                if (source.length > 0) {
-                    globalStyleAsset.source = await adaptWxss(source)
+                const styles = Object.values(bundle).filter(isStyleAsset)
+                // More than one compiler style means cssCodeSplit was re-enabled. Choosing one would silently lose CSS.
+                if (styles.length > 1) {
+                    throw new Error('WX builds require one global compiler-emitted stylesheet')
                 }
-                globalStyleAsset.fileName = 'app.wxss'
+                // CSS is optional; applications without styles do not need an empty app.wxss.
+                if (styles.length === 0) return
+
+                const [style] = styles
+                const source = typeof style.source === 'string' ? style.source : new TextDecoder().decode(style.source)
+                // generateBundle exposes the final asset as mutable so conversion and native placement remain atomic.
+                // Without the compatibility pass, browser-only selectors, escaped classes, rem and @property can reach
+                // WeChat. Without the rename, bundled development writes paths such as src/app.wxss, which WeChat does
+                // not load as the application's global stylesheet.
+                style.source = (await transformWxStyle(source)).css
+                style.fileName = 'app.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. H5 descriptors remain untouched.
+ */
+function alignWxGenerateBundleOrder(pluginOption: PluginOption): PluginOption {
+    // PluginOption permits nested arrays. Preserve their shape while adapting every concrete plugin recursively.
+    if (Array.isArray(pluginOption)) return pluginOption.map(alignWxGenerateBundleOrder)
+
+    if (
+        !pluginOption ||
+        typeof pluginOption !== 'object' ||
+        !('enforce' in pluginOption) ||
+        pluginOption.enforce !== 'post' ||
+        !('generateBundle' in pluginOption) ||
+        pluginOption.generateBundle === undefined
+    ) {
+        return pluginOption
+    }
+
+    // Clone rather than mutate: upstream may retain or reuse the descriptor returned by its factory.
+    return { ...pluginOption, 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/h5/create-stencil-client-adapter.ts

@@ -0,0 +1,109 @@
+import type { types as BabelTypes } from '@babel/core'
+import { type NodePath, type PluginObj, transformAsync, types } from '@babel/core'
+import type { Plugin } from 'vite'
+import { normalizeModuleId } from '../../utils/modules.ts'
+import { packageRequire } from '../../utils/packages.ts'
+
+const stencilClientPath = packageRequire.resolve('@stencil/core/internal/client', {
+    paths: [packageRequire.resolve('@tarojs/components/package.json')]
+})
+const normalizedStencilClientPath = normalizeModuleId(stencilClientPath)
+
+/**
+ * Creates the compiler-owned adaptation of Stencil's client style insertion.
+ *
+ * Taro components inject their styles through this internal client. Its default insertion point places those styles
+ * after application CSS, allowing component defaults to override application rules. The adapter is registered in both
+ * Vite's application pipeline and the independent dependency-optimization build: removing either registration leaves
+ * production or development with an unadapted client. This explicit dual registration removes the former optimization
+ * exclusion while keeping one transformation implementation.
+ */
+export function createStencilClientAdapter(): Plugin {
+    return {
+        name: 'vpt:h5-stencil-client',
+        transform: adaptStencilClient
+    }
+}
+
+/** Applies the shared Stencil adaptation in either the application or dependency-optimization pipeline. */
+export async function adaptStencilClient(code: string, id: string) {
+    if (normalizeModuleId(id) !== normalizedStencilClientPath) {
+        return
+    }
+
+    const transformed = await transformAsync(code, {
+        babelrc: false,
+        configFile: false,
+        filename: stencilClientPath,
+        plugins: [rewriteStencilStyleInsertion],
+        sourceFileName: stencilClientPath,
+        sourceMaps: true
+    })
+
+    if (transformed?.code === undefined || transformed.code === null) {
+        throw new Error(`Failed to adapt Stencil client: ${stencilClientPath}`)
+    }
+
+    return {
+        code: transformed.code,
+        map: transformed.map
+    }
+}
+
+/** Keeps Stencil-injected Taro component styles before application stylesheets. */
+function rewriteStencilStyleInsertion(): PluginObj {
+    return {
+        name: 'vpt:rewrite-stencil-style-insertion',
+        visitor: {
+            CallExpression(callPath) {
+                if (!isStencilStyleInsertBeforeCall(callPath)) {
+                    return
+                }
+
+                callPath
+                    .get('arguments.1')
+                    .replaceWith(
+                        types.conditionalExpression(
+                            types.callExpression(
+                                types.memberExpression(types.identifier('scopeId'), types.identifier('startsWith')),
+                                [types.stringLiteral('sc-taro-')]
+                            ),
+                            createStyleQuery('style,link[rel="stylesheet"]'),
+                            createStyleQuery('link')
+                        )
+                    )
+            }
+        }
+    }
+}
+
+/** Identifies Stencil's default component-style insertion call. */
+function isStencilStyleInsertBeforeCall(callPath: NodePath<BabelTypes.CallExpression>): boolean {
+    const { callee, arguments: callArguments } = callPath.node
+    return (
+        types.isMemberExpression(callee) &&
+        types.isIdentifier(callee.object, { name: 'styleContainerNode' }) &&
+        types.isIdentifier(callee.property, { name: 'insertBefore' }) &&
+        types.isIdentifier(callArguments[0], { name: 'styleElm' }) &&
+        isStyleQuery(callArguments[1], 'link')
+    )
+}
+
+/** Identifies one style-container querySelector call. */
+function isStyleQuery(node: BabelTypes.Node | null | undefined, selector: string): boolean {
+    return (
+        types.isCallExpression(node) &&
+        types.isMemberExpression(node.callee) &&
+        types.isIdentifier(node.callee.object, { name: 'styleContainerNode' }) &&
+        types.isIdentifier(node.callee.property, { name: 'querySelector' }) &&
+        types.isStringLiteral(node.arguments[0], { value: selector })
+    )
+}
+
+/** Creates one style-container querySelector call. */
+function createStyleQuery(selector: string): ReturnType<typeof types.callExpression> {
+    return types.callExpression(
+        types.memberExpression(types.identifier('styleContainerNode'), types.identifier('querySelector')),
+        [types.stringLiteral(selector)]
+    )
+}

package/src/node/plugins/h5/plugins.ts

@@ -1,5 +1,3 @@
-import type { types as BabelTypes } from '@babel/core'
-import { type NodePath, type PluginObj, types } from '@babel/core'
 import babel from '@rolldown/plugin-babel'
 import type { HtmlTagDescriptor, Plugin, PluginOption } from 'vite'
 import type { VitePluginTaroOptions } from '../../../options.ts'
@@ -8,6 +6,7 @@ import { toViteFileImportPath } from '../../utils/modules.ts'
 import { packageRequire } from '../../utils/packages.ts'
 import { clientTaroApiId } from '../client/client-taro.ts'
 import { h5AppPath } from './constant.ts'
+import { createStencilClientAdapter } from './create-stencil-client-adapter.ts'
 import { createModuleResolver } from './resolver/module-resolver.ts'
 
 /** Creates the plugins that own the H5 target. */
@@ -28,12 +27,6 @@ function createH5TargetPlugin(options: VitePluginTaroOptions): Plugin {
                 resolve: {
                     mainFields: ['main:h5', 'browser', 'module', 'jsnext:main', 'jsnext'],
                     alias: [
-                        {
-                            find: /^@stencil\/core\/internal\/client$/,
-                            replacement: packageRequire.resolve('@stencil/core/internal/client', {
-                                paths: [packageRequire.resolve('@tarojs/components/package.json')]
-                            })
-                        },
                         {
                             find: /^@tarojs\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/lib/react')
@@ -41,15 +34,19 @@ function createH5TargetPlugin(options: VitePluginTaroOptions): Plugin {
                         {
                             find: /^@tarojs\/components\/dist\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/dist/components')
-                        },
-                        {
-                            find: /^@tarojs\/taro$/,
-                            replacement: packageRequire.resolve('@tarojs/plugin-platform-h5/dist/runtime/apis')
                         }
                     ]
                 },
                 optimizeDeps: {
-                    exclude: ['@stencil/core/internal/client']
+                    // The compiler-owned H5 app and Taro facade are injected after Vite's initial HTML scan. Prebundle
+                    // the facade's platform backend as one boundary so its CommonJS implementation details receive
+                    // interop without duplicating their package list. ReactDOM needs the same treatment for the H5 app.
+                    include: ['@tarojs/plugin-platform-h5/dist/runtime/apis', 'react-dom/client'],
+                    // Dependency optimization is its own Rolldown build and does not run application transform plugins.
+                    // Register the same adapter there so optimized Taro components cannot embed Stencil's original client.
+                    rolldownOptions: {
+                        plugins: [createStencilClientAdapter()]
+                    }
                 },
                 build: {
                     target: esTarget
@@ -105,11 +102,7 @@ function createH5IndexHtmlTags(): HtmlTagDescriptor[] {
 /** Creates H5-only Babel transforms for Stencil CSS ordering and Taro API imports. */
 function createH5SupportPlugins(): PluginOption[] {
     return [
-        babel({
-            include: /[\\/]@stencil[\\/]core[\\/]internal[\\/]client[\\/]index\.js(?:\?.*)?$/,
-            exclude: [],
-            plugins: [rewriteStencilStyleInsertion]
-        }),
+        createStencilClientAdapter(),
         babel({
             plugins: [
                 [
@@ -126,64 +119,6 @@ function createH5SupportPlugins(): PluginOption[] {
     ]
 }
 
-/** Keeps Stencil-injected Taro component styles before application stylesheets. */
-function rewriteStencilStyleInsertion(): PluginObj {
-    return {
-        name: 'vpt:rewrite-stencil-style-insertion',
-        visitor: {
-            CallExpression(callPath) {
-                if (!isStencilStyleInsertBeforeCall(callPath)) {
-                    return
-                }
-
-                callPath
-                    .get('arguments.1')
-                    .replaceWith(
-                        types.conditionalExpression(
-                            types.callExpression(
-                                types.memberExpression(types.identifier('scopeId'), types.identifier('startsWith')),
-                                [types.stringLiteral('sc-taro-')]
-                            ),
-                            createStyleQuery('style,link[rel="stylesheet"]'),
-                            createStyleQuery('link')
-                        )
-                    )
-            }
-        }
-    }
-}
-
-/** Identifies Stencil's default component-style insertion call. */
-function isStencilStyleInsertBeforeCall(callPath: NodePath<BabelTypes.CallExpression>): boolean {
-    const { callee, arguments: callArguments } = callPath.node
-    return (
-        types.isMemberExpression(callee) &&
-        types.isIdentifier(callee.object, { name: 'styleContainerNode' }) &&
-        types.isIdentifier(callee.property, { name: 'insertBefore' }) &&
-        types.isIdentifier(callArguments[0], { name: 'styleElm' }) &&
-        isStyleQuery(callArguments[1], 'link')
-    )
-}
-
-/** Identifies one style-container querySelector call. */
-function isStyleQuery(node: BabelTypes.Node | null | undefined, selector: string): boolean {
-    return (
-        types.isCallExpression(node) &&
-        types.isMemberExpression(node.callee) &&
-        types.isIdentifier(node.callee.object, { name: 'styleContainerNode' }) &&
-        types.isIdentifier(node.callee.property, { name: 'querySelector' }) &&
-        types.isStringLiteral(node.arguments[0], { value: selector })
-    )
-}
-
-/** Creates one style-container querySelector call. */
-function createStyleQuery(selector: string): ReturnType<typeof types.callExpression> {
-    return types.callExpression(
-        types.memberExpression(types.identifier('styleContainerNode'), types.identifier('querySelector')),
-        [types.stringLiteral(selector)]
-    )
-}
-
 /** Creates H5 Taro compile-time constants. */
 function createH5Defines(): Record<string, string> {
     return {