vite-plugin-taro 0.6.6 → 0.6.8

package/dist/node/plugins/h5/plugins.js

@@ -28,11 +28,11 @@ export function createH5TargetPlugins(options) {
             logLevel: 'warn'
         }),
         ...createH5SupportPlugins(),
-        createH5TargetPlugin(options)
+        createH5Plugin(options)
     ];
 }
 /** Configures H5 resolution and supplies the specialized physical application entry. */
-function createH5TargetPlugin(options) {
+function createH5Plugin(options) {
     const moduleResolver = createModuleResolver(options);
     return {
         name: 'vpt:h5',
@@ -42,6 +42,10 @@ function createH5TargetPlugin(options) {
                 resolve: {
                     mainFields: ['main:h5', 'browser', 'module', 'jsnext:main', 'jsnext'],
                     alias: [
+                        {
+                            find: /^@tarojs\/runtime$/,
+                            replacement: packageRequire.resolve('@tarojs/runtime/dist/runtime.esm.js')
+                        },
                         {
                             find: /^@tarojs\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/lib/react')
@@ -53,10 +57,13 @@ function createH5TargetPlugin(options) {
                     ]
                 },
                 optimizeDeps: {
-                    // 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'],
+                    /*
+                     * The compiler-owned H5 app and Taro facade are injected after Vite's initial HTML scan, so declare their
+                     * optimization entries explicitly. The platform backend needs CommonJS interop, ReactDOM is imported by
+                     * the hidden app, and @tarojs/runtime must be a first-class entry so subsequently discovered Taro packages
+                     * share its Current singleton instead of embedding private copies in their optimized chunks.
+                     */
+                    include: ['@tarojs/plugin-platform-h5/dist/runtime/apis', '@tarojs/runtime', '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: {

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

@@ -4,11 +4,8 @@ import { toRootRelativePath } from './relative-root.js';
 /** Creates every configured native JSON asset. */
 export function createJsonAssets({ options, subpackages, nativeComponents }) {
     return [
-        createJsonAsset('app.json', {
-            ...createAppConfig(options),
-            ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
-        }),
-        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page, nativeComponents))),
+        createJsonAsset('app.json', createAppJson({ options: options, subpackages: subpackages, nativeComponents: nativeComponents })),
+        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page))),
         createJsonAsset('project.config.json', options.projectConfigJson),
         ...(options.projectPrivateConfigJson
             ? [createJsonAsset('project.private.config.json', options.projectPrivateConfigJson)]
@@ -16,20 +13,43 @@ export function createJsonAssets({ options, subpackages, nativeComponents }) {
         ...(options.sitemapJson ? [createJsonAsset('sitemap.json', options.sitemapJson)] : [])
     ];
 }
-/** Creates Page JSON with generated Taro and native component registrations. */
-function createPageJson(page, nativeComponents) {
-    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {};
+/** Creates App JSON with globally inherited native registrations and generated subpackages. */
+function createAppJson({ options, subpackages, nativeComponents }) {
+    const appConfig = createAppConfig(options);
+    const nativeUsingComponents = nativeComponents.map(({ name, componentPath }) => [name, componentPath]);
     // Cross-package components require a placeholder while WeChat downloads their generated subpackage. Paths are
     // root-absolute, so remove the leading slash before testing the output-relative subpackage prefix.
     // https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html
     // https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/placeholder.html
-    const placeholderEntries = nativeComponents.flatMap(({ name, componentPath }) => isGeneratedSubpackageFile(componentPath.slice(1)) ? [[name, 'view']] : []);
+    const componentPlaceholders = nativeComponents.flatMap(({ name, componentPath }) => isGeneratedSubpackageFile(componentPath.slice(1)) ? [[name, 'view']] : []);
+    return {
+        ...appConfig,
+        ...(nativeUsingComponents.length > 0
+            ? {
+                usingComponents: {
+                    ...(isJsonObject(appConfig.usingComponents) ? appConfig.usingComponents : {}),
+                    ...Object.fromEntries(nativeUsingComponents)
+                }
+            }
+            : {}),
+        ...(componentPlaceholders.length > 0
+            ? {
+                componentPlaceholder: {
+                    ...(isJsonObject(appConfig.componentPlaceholder) ? appConfig.componentPlaceholder : {}),
+                    ...Object.fromEntries(componentPlaceholders)
+                }
+            }
+            : {}),
+        ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
+    };
+}
+/** Preserves configured Page JSON and registers only Taro's local recursive component entry. */
+function createPageJson(page) {
+    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {};
     return {
         ...page.config,
-        ...(placeholderEntries.length > 0 ? { componentPlaceholder: Object.fromEntries(placeholderEntries) } : {}),
         usingComponents: {
             ...usingComponents,
-            ...Object.fromEntries(nativeComponents.map(({ name, componentPath }) => [name, componentPath])),
             comp: toRootRelativePath(page.path, 'comp')
         }
     };

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

@@ -9,7 +9,7 @@ const taroComponentsModulePath = packageRequire.resolve('@tarojs/plugin-platform
 export function createTemplateAssets(bundle, options, nativeComponents) {
     const templateBuilder = createTemplateBuilder();
     return [
-        createAsset('base.wxml', templateBuilder.buildTemplate(collectTemplateComponentConfig(bundle, nativeComponents))),
+        createAsset('base.wxml', templateBuilder.buildBaseTemplate(collectTemplateComponentConfig(bundle, nativeComponents))),
         createAsset('utils.wxs', templateBuilder.buildXScript()),
         createAsset('comp.wxml', templateBuilder.buildBaseComponentTemplate('.wxml')),
         createAsset('comp.json', renderJson(createComponentJson())),
@@ -22,7 +22,106 @@ export function createTemplateAssets(bundle, options, nativeComponents) {
         ])
     ];
 }
-/** Creates the Taro WeChat template builder without invoking its Webpack integration. */
+/**
+ * Adapts Taro's stock template builder to the WXML half of WX App wrapping without changing its recursive renderer.
+ *
+ * End-to-end contract
+ * -------------------
+ * React and Taro retain one in-memory ownership tree:
+ *
+ * App React root
+ *   -> App host records
+ *      -> vpt_page_outlet host at App {children}
+ *         -> independently scheduled Taro Page roots
+ *
+ * The patched WX document makes the singleton App host a TaroRootElement. App host mutations therefore batch under app.*
+ * and fan out to every mounted native Page. Each Page root remains its own TaroRootElement and emits only page.*. The React
+ * host renderer marks the outlet and its App ancestors with an ordinary compact `vo` prop after each commit, while patched
+ * hydrate() stops at vpt_page_outlet. Page roots remain attached for React Context, lifecycle, events, removal, refs, effects,
+ * and HMR without entering app data.
+ *
+ * Build-time output
+ * -----------------
+ * createTemplateAssets still asks one builder for the normal five products: shared base.wxml, utils.wxs, comp.wxml,
+ * comp.json, and each Page WXML. This adapter specializes only the two products that own the native join:
+ *
+ * - shared base.wxml receives branch-local slot forwarding plus vpt_fragment and vpt_page_outlet template definitions;
+ * - each Page WXML replaces Taro's root:root entry with one generic comp bound to app and one caller-owned taro_tmpl bound
+ *   to page as that component's default slot.
+ *
+ * utils.wxs remains Taro's normal compact-node dispatcher. comp.wxml and comp.json remain Taro's generic depth-reset
+ * component and still know only i, l, virtual-host behavior, and eh event dispatch. There is one shared template namespace,
+ * no Page-specific base file, no App/Page mode property, and no Page object threaded through App template data.
+ *
+ * First native Page
+ * -----------------
+ * createPageConfig starts the native Page with:
+ *
+ *     app  = { nn: 'vpt_fragment', cn: [] }
+ *     page = { cn: [] }
+ *
+ * nn lets unchanged comp dispatch one input object even though App JSX may produce one or many root hosts. The record
+ * is WXML-only rather than a Taro host, so it needs no sid. After React commits the Page root below the outlet, the framework
+ * queues a lazy hydrate(AppRoot).cn value beside the Page root's already-pending page.* payloads. Taro drains both through the
+ * native Page's existing first setData, making App wrapping and Page content appear atomically.
+ *
+ * Native WXML execution
+ * ---------------------
+ * Data/slot ownership and named-template ownership intentionally travel through different scopes:
+ *
+ * Page WXML (owns app, page, Page eh, and Page-content light DOM)
+ *   -> <comp i="{{app}}"> (crosses into a virtual custom-component scope)
+ *      -> comp.wxml (owns App eh, imports unchanged utils.wxs and shared base.wxml)
+ *         -> tmpl_0_vpt_fragment (iterates the real App compact roots in app.cn)
+ *            -> stock Taro templates (render App hosts and recurse through their cn arrays)
+ *               -> depth-reset <comp i="{{i}}" l="{{l}}">
+ *                    -> forwards <slot /> only when this compact subtree root has i.vo
+ *               -> tmpl_0_vpt_page_outlet at React's exact {children} position
+ *                  -> <slot />
+ *                     -> caller-owned <template is="taro_tmpl" data="{{root:page}}" />
+ *                        -> stock Taro templates render this native Page's page.cn records
+ *
+ * The virtual comp and both private templates add no native layout node. `vo` is part of the existing compact node i, not a
+ * component property or template context. App events execute through comp.eh; slotted Page events retain the native Page's
+ * eh. Both resolve the original Taro sid through the same event source.
+ *
+ * Named-template scope
+ * --------------------
+ * Slots transfer caller-owned light DOM only. They do not transfer the caller's named-template table or WXS modules. App
+ * dispatch runs inside comp.wxml, so vpt_fragment and vpt_page_outlet must live in base.wxml imported by that component.
+ * Putting those definitions in buildPageTemplate produces Page WXML that compiles, but component runtime dispatch fails with
+ * `Template tmpl_0_vpt_fragment not found`. Shared base.wxml makes the names visible in the root and every depth-reset comp
+ * scope and emits them once rather than once per Page.
+ *
+ * Projection-spine ownership
+ * --------------------------
+ * React's host renderer runs after the final commit tree exists and caches the outlet-to-root Taro host ancestor array. It
+ * skips the unchanged root-side suffix, gives old leaf-side nodes the ordinary host prop vo=false, and gives new ones vo=true.
+ * Taro's existing lazy structural hydration runs later and therefore serializes those props without projection-specific
+ * scheduler or hydrate behavior. If React replaces the outlet host while moving it, the renderer finds the unique new marker
+ * once and caches its new ancestor array. At a depth reset, i.vo makes forwarding an O(1) local decision; WXML never searches
+ * descendants, and Page trees instantiate no unnamed slot.
+ *
+ * Steady-state updates and navigation
+ * -----------------------------------
+ * A page.* setData updates only the caller-owned Page template inside the slot. app is not passed through that template and
+ * comp.i does not change, so Page updates cannot invalidate App recursion. Ordinary app.* payloads and outlet-spine marker
+ * changes remain in Taro's granular batch before it fans out to every retained native Page. Adding or removing a React Page
+ * root mutates the outlet only in memory, and the runtime suppresses that marker's native child update. A newly pushed Page
+ * receives the latest complete App snapshot in its initial batch, while existing and hidden Pages require no navigation
+ * synchronization.
+ *
+ * Method responsibilities
+ * -----------------------
+ * 1. buildBaseTemplate wraps Taro's buildTemplate output, preserves every stock host template, guards the slot at Taro's
+ *    existing depth-reset call site with i.vo, and adds the two private definitions to the shared namespace.
+ * 2. buildPageTemplate owns only the Page boundary: app binding, page binding, and the single Page-content slot.
+ * 3. buildXScript delegates unchanged because routing metadata already travels inside compact node i.
+ * 4. buildBaseComponentTemplate delegates unchanged so recursive comp remains generic and feature-independent.
+ *
+ * H5 never calls this WX output builder. Its App continues to receive ordinary Fragment children and none of these native
+ * data roots, templates, custom-component boundaries, or slot rules enter the browser build.
+ */
 function createTemplateBuilder() {
     const platform = new WxPlatform({
         helper: {
@@ -32,7 +131,96 @@ function createTemplateBuilder() {
         registerPlatform() { }
     }, {}, {});
     platform.modifyTemplate({});
-    return platform.template;
+    const taroTemplateBuilder = platform.template;
+    /**
+     * Replaces one pinned Taro fragment so an upstream template change cannot silently break the coordinated
+     * framework/runtime/WXML boundary or partially apply the feature.
+     */
+    function replaceExactlyOnce(source, current, replacement, description) {
+        const firstIndex = source.indexOf(current);
+        const duplicateIndex = firstIndex === -1 ? -1 : source.indexOf(current, firstIndex + current.length);
+        if (firstIndex === -1 || duplicateIndex !== -1) {
+            throw new Error(`Expected one ${description}, found ${firstIndex === -1 ? 0 : 'multiple'}`);
+        }
+        return `${source.slice(0, firstIndex)}${replacement}${source.slice(firstIndex + current.length)}`;
+    }
+    return {
+        buildBaseTemplate: (componentConfig) => {
+            const source = taroTemplateBuilder.buildTemplate(componentConfig);
+            /*
+             * Taro inserts recursive comp only when template depth resets. App {children} may be below any number of those
+             * boundaries, so each boundary reads the renderer-maintained vo marker on its compact subtree root before forwarding
+             * the caller's default slot. No App/Page mode or Page data is threaded through template scopes: Page recursion
+             * and unrelated App branches have no marker, while the outlet spine carries the one Page-owned slot.
+             */
+            const slotTransparentRecursion = replaceExactlyOnce(source, '<comp i="{{i}}" l="{{l}}" />', `<comp i="{{i}}" l="{{l}}"><slot wx:if="{{i.vo}}" /></comp>`, 'recursive comp call');
+            /*
+             * These definitions belong in shared base.wxml rather than buildPageTemplate. Although native data is Page-owned,
+             * the dynamic calls that render App records execute after crossing into comp.wxml's component scope. WXML slots
+             * transfer caller-owned light DOM, not the caller's named-template table or WXS modules. comp.wxml can therefore
+             * resolve only its own definitions and those imported from base.wxml.
+             *
+             * Defining the two names in Page WXML is not merely redundant: WeChat accepts that Page file at compile time, then
+             * comp.wxml's runtime dispatch fails with `Template tmpl_0_vpt_fragment not found` because component template
+             * resolution never searches the caller Page. Shared base.wxml is already imported by comp.wxml, makes both names
+             * visible at every depth-reset component scope, and emits them once instead of once per generated Page.
+             *
+             * Page WXML can give generic comp one i object, whereas App output is a root collection. vpt_fragment bridges
+             * those contracts without becoming a native or Taro host: its nn is only a template discriminator and its
+             * template emits each real cn record directly. Keeping the collection behind one comp is important because that
+             * component owns exactly one Page slot regardless of whether App rendered zero, one, or many top-level hosts.
+             * The synthetic record itself is not keyed or event-addressable, so it deliberately has no sid. Its cn items are
+             * different: they are real hydrated Taro elements, text nodes, or the outlet, and every one has Taro's stable sid.
+             * wx:key="sid" matches Taro's stock root.cn loop so insertion/reordering preserves native-component instances,
+             * sibling identity, and event-source routing instead of reusing children only by array position.
+             *
+             * vpt_page_outlet is the matching terminal. The patched runtime retains Page roots below that marker in memory
+             * and serializes no children into app data, while React's host renderer marks its compact ancestor spine with vo.
+             * The slot inserts the parent Page's separate page data at the same visual position and adds no native layout
+             * wrapper.
+             */
+            return `${slotTransparentRecursion}
+<template name="tmpl_0_vpt_fragment">
+  <template
+    is="{{xs.a(0, item.nn, '')}}"
+    data="{{i:item,c:1,l:xs.f('',item.nn)}}"
+    wx:for="{{i.cn}}"
+    wx:key="sid"
+  />
+</template>
+<template name="tmpl_0_vpt_page_outlet"><slot /></template>
+`;
+        },
+        buildXScript: () => {
+            // Alias selection and compact paths are unchanged; both App and Page records use Taro's normal node vocabulary,
+            // and projection ownership already travels on the current i object as vo.
+            return taroTemplateBuilder.buildXScript();
+        },
+        buildBaseComponentTemplate: (ext) => {
+            /*
+             * Keep comp generic. i is the current compact node dispatched through i.nn. l is Taro's lineage of selected
+             * special/native aliases: xs.f records bounded/nestable ancestors and xs.a uses that history when choosing a
+             * generated template level on non-recursive WXML platforms. The current comp.wxml restarts its local lineage from
+             * i.nn, but l remains part of Taro's intentional depth-reset component contract and platform variants may consume
+             * it. Preserve that upstream binding; only the new Page-root comp starts with the property's empty default. Slot
+             * forwarding lives at this base.wxml call site, and vo already belongs to i, so comp still needs no App/Page mode,
+             * projection property, or Page data.
+             */
+            return taroTemplateBuilder.buildBaseComponentTemplate(ext);
+        },
+        buildPageTemplate: (baseTempPath, page) => {
+            const source = taroTemplateBuilder.buildPageTemplate(baseTempPath, page);
+            /*
+             * The native Page owns both data bindings. app is the transparent single-node adapter rendered by unchanged
+             * comp; the caller-owned taro_tmpl still reads only page and becomes comp's one default slot. A page.* update
+             * therefore cannot enter App template scopes or a component property, while App recursion can place the Page
+             * exactly at {children} by consuming the slot at vpt_page_outlet. The root call omits l because this native comp
+             * starts a fresh lineage scope and its generic property already defaults to the empty string. It also emits no id:
+             * no runtime lookup, event dispatch, ref, or selector addresses this virtual boundary.
+             */
+            return replaceExactlyOnce(source, '<template is="taro_tmpl" data="{{root:root}}" />', `<comp i="{{app}}"><template is="taro_tmpl" data="{{root:page}}" /></comp>`, 'Page template entry');
+        }
+    };
 }
 /** Creates template metadata from reachable Taro hosts and native component JSX fields. */
 function collectTemplateComponentConfig(bundle, nativeComponents) {

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

@@ -2,8 +2,8 @@ import { normalizePath } from 'vite';
 import { getWxExecutionKind, isTransportModule } from '../module/module.js';
 import { getNativeComponentAssetBytes } from '../native/native-component-assets.js';
 import { createPlacement } from './placement.js';
-const pnpmFrameworkPackagePattern = /\/node_modules\/\.pnpm\/(?:@tarojs\+|react(?:-dom|-reconciler)?@|scheduler@)/;
-const workspaceFrameworkPackagePattern = /\/packages\/(?:taro-react|taro-plugin-framework-react)\//;
+const pnpmFrameworkPackagePattern = /\/node_modules\/\.pnpm\/(?:@tarojs\+|vite-plugin-taro-runtime@|react(?:-dom|-reconciler)?@|scheduler@)/;
+const workspaceFrameworkPackagePattern = /\/packages\/(?:taro-react|taro-plugin-framework-react|taro-runtime)\//;
 /** Selects the explicit React/Taro roots whose complete dependency closure forms the framework vendor chunk. */
 export function isWxFrameworkVendorModule(moduleId) {
     const normalizedId = normalizePath(moduleId);

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

@@ -31,6 +31,10 @@ function createWxPlugin(options, resolver, placement) {
                 oxc: { target: esTarget },
                 resolve: {
                     alias: [
+                        {
+                            find: /^@tarojs\/runtime$/,
+                            replacement: packageRequire.resolve('@tarojs/runtime/dist/index.js')
+                        },
                         {
                             find: /^@tarojs\/components$/,
                             replacement: packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react')
@@ -127,7 +131,7 @@ function createWxPlugin(options, resolver, placement) {
 }
 /** Creates the build-time constants required by Taro's legacy feature gates. */
 function createTaroDefines() {
-    const taroVersion = String(packageRequire('@tarojs/runtime/package.json').version);
+    const taroVersion = String(packageRequire('@tarojs/taro/package.json').version);
     return {
         'process.env.FRAMEWORK': JSON.stringify('react'),
         'process.env.SUPPORT_TARO_POLYFILL': JSON.stringify('disabled'),

package/dist/runtime/wx/capsule/page.js

@@ -3,5 +3,16 @@ import './app.js';
 // @ts-expect-error: The wx build replaces this private import with the configured Page component.
 import PageComponent from '\0vpt:page-component';
 import { createPageConfig } from './taro-runtime.js';
-const config = createPageConfig(PageComponent, __VPT_PAGE_PATH__, { root: { cn: [] } }, __VPT_PAGE_CONFIG__);
+/*
+ * Generated Page WXML invokes Taro's unchanged recursive comp, whose input contract is one compact node selected by i.nn.
+ * App JSX does not have that cardinality: it may return one or many top-level hosts, and the private Page outlet may
+ * occur at any depth within them. vpt_fragment is therefore a WXML-only collection adapter. Its fixed nn selects a
+ * transparent template that iterates cn while one surrounding comp owns the Page's default slot. Runtime projection markers
+ * relay that slot only through the App branch containing the outlet. Without the fragment, Page WXML would need one comp—and
+ * one potential copy of the Page slot—for every App root, or comp would need an App-specific collection mode.
+ *
+ * This record is not a Taro host: it has no Fiber, event source, ref, lifecycle, native element, or keyed parent collection.
+ * It consequently needs no sid. Only cn is seeded and updated; nn remains the stable generic-template discriminator.
+ */
+const config = createPageConfig(PageComponent, __VPT_PAGE_PATH__, { app: { nn: 'vpt_fragment', cn: [] }, page: { cn: [] } }, __VPT_PAGE_CONFIG__);
 export default config;

package/dist/runtime/wx/capsule/taro-runtime.d.ts

@@ -3,4 +3,4 @@
 import '@tarojs/plugin-platform-weapp/dist/runtime.js';
 export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime';
 export { default as ReactDOM } from '@tarojs/react';
-export { createPageConfig, createRecursiveComponentConfig, Current, document, injectPageInstance } from '@tarojs/runtime';
+export { createPageConfig, createRecursiveComponentConfig } from '@tarojs/runtime';

package/dist/runtime/wx/capsule/taro-runtime.js

@@ -3,4 +3,4 @@
 import '@tarojs/plugin-platform-weapp/dist/runtime.js';
 export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime';
 export { default as ReactDOM } from '@tarojs/react';
-export { createPageConfig, createRecursiveComponentConfig, Current, document, injectPageInstance } from '@tarojs/runtime';
+export { createPageConfig, createRecursiveComponentConfig } from '@tarojs/runtime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-taro",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "author": "sep2",
   "description": "Vite 8 plugin for building one React/Taro codebase for WeChat Mini Program and H5 targets.",
   "type": "module",
@@ -63,7 +63,6 @@
     "@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",
@@ -76,8 +75,9 @@
     "rxjs": "^7.8.2",
     "tailwindcss": "^4.3.3",
     "weapp-tailwindcss": "^5.2.11",
-    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.6",
-    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.6"
+    "@tarojs/plugin-framework-react": "npm:vite-plugin-taro-plugin-framework-react@0.6.8",
+    "@tarojs/react": "npm:vite-plugin-taro-react@0.6.8",
+    "@tarojs/runtime": "npm:vite-plugin-taro-runtime@0.6.8"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -31,12 +31,12 @@ export function createH5TargetPlugins(options: VptOptions): PluginOption[] {
             logLevel: 'warn'
         }),
         ...createH5SupportPlugins(),
-        createH5TargetPlugin(options)
+        createH5Plugin(options)
     ]
 }
 
 /** Configures H5 resolution and supplies the specialized physical application entry. */
-function createH5TargetPlugin(options: VptOptions): Plugin {
+function createH5Plugin(options: VptOptions): Plugin {
     const moduleResolver = createModuleResolver(options)
 
     return {
@@ -48,6 +48,10 @@ function createH5TargetPlugin(options: VptOptions): Plugin {
                 resolve: {
                     mainFields: ['main:h5', 'browser', 'module', 'jsnext:main', 'jsnext'],
                     alias: [
+                        {
+                            find: /^@tarojs\/runtime$/,
+                            replacement: packageRequire.resolve('@tarojs/runtime/dist/runtime.esm.js')
+                        },
                         {
                             find: /^@tarojs\/components$/,
                             replacement: packageRequire.resolve('@tarojs/components/lib/react')
@@ -59,10 +63,13 @@ function createH5TargetPlugin(options: VptOptions): Plugin {
                     ]
                 },
                 optimizeDeps: {
-                    // 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'],
+                    /*
+                     * The compiler-owned H5 app and Taro facade are injected after Vite's initial HTML scan, so declare their
+                     * optimization entries explicitly. The platform backend needs CommonJS interop, ReactDOM is imported by
+                     * the hidden app, and @tarojs/runtime must be a first-class entry so subsequently discovered Taro packages
+                     * share its Current singleton instead of embedding private copies in their optimized chunks.
+                     */
+                    include: ['@tarojs/plugin-platform-h5/dist/runtime/apis', '@tarojs/runtime', '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: {

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

@@ -15,12 +15,12 @@ export function createJsonAssets({
     nativeComponents: readonly { name: string; componentPath: string }[]
 }): Rolldown.EmittedAsset[] {
     return [
-        createJsonAsset('app.json', {
-            ...createAppConfig(options),
-            ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
-        }),
+        createJsonAsset(
+            'app.json',
+            createAppJson({ options: options, subpackages: subpackages, nativeComponents: nativeComponents })
+        ),
 
-        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page, nativeComponents))),
+        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page))),
 
         createJsonAsset('project.config.json', options.projectConfigJson),
 
@@ -32,27 +32,58 @@ export function createJsonAssets({
     ]
 }
 
-/** Creates Page JSON with generated Taro and native component registrations. */
-function createPageJson(
-    page: VptPageOption,
+/** Creates App JSON with globally inherited native registrations and generated subpackages. */
+function createAppJson({
+    options,
+    subpackages,
+    nativeComponents
+}: {
+    options: VptOptions
+    subpackages: readonly GeneratedSubpackage[]
     nativeComponents: readonly { name: string; componentPath: string }[]
-): VptJsonObject {
-    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {}
+}): VptJsonObject {
+    const appConfig = createAppConfig(options)
+
+    const nativeUsingComponents = nativeComponents.map(({ name, componentPath }) => [name, componentPath])
 
     // Cross-package components require a placeholder while WeChat downloads their generated subpackage. Paths are
     // root-absolute, so remove the leading slash before testing the output-relative subpackage prefix.
     // https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html
     // https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/placeholder.html
-    const placeholderEntries = nativeComponents.flatMap(({ name, componentPath }) =>
+    const componentPlaceholders = nativeComponents.flatMap(({ name, componentPath }) =>
         isGeneratedSubpackageFile(componentPath.slice(1)) ? ([[name, 'view']] as const) : []
     )
 
+    return {
+        ...appConfig,
+        ...(nativeUsingComponents.length > 0
+            ? {
+                  usingComponents: {
+                      ...(isJsonObject(appConfig.usingComponents) ? appConfig.usingComponents : {}),
+                      ...Object.fromEntries(nativeUsingComponents)
+                  }
+              }
+            : {}),
+        ...(componentPlaceholders.length > 0
+            ? {
+                  componentPlaceholder: {
+                      ...(isJsonObject(appConfig.componentPlaceholder) ? appConfig.componentPlaceholder : {}),
+                      ...Object.fromEntries(componentPlaceholders)
+                  }
+              }
+            : {}),
+        ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
+    }
+}
+
+/** Preserves configured Page JSON and registers only Taro's local recursive component entry. */
+function createPageJson(page: VptPageOption): VptJsonObject {
+    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {}
+
     return {
         ...page.config,
-        ...(placeholderEntries.length > 0 ? { componentPlaceholder: Object.fromEntries(placeholderEntries) } : {}),
         usingComponents: {
             ...usingComponents,
-            ...Object.fromEntries(nativeComponents.map(({ name, componentPath }) => [name, componentPath])),
             comp: toRootRelativePath(page.path, 'comp')
         }
     }

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

@@ -30,7 +30,7 @@ export function createTemplateAssets(
     return [
         createAsset(
             'base.wxml',
-            templateBuilder.buildTemplate(collectTemplateComponentConfig(bundle, nativeComponents))
+            templateBuilder.buildBaseTemplate(collectTemplateComponentConfig(bundle, nativeComponents))
         ),
         createAsset('utils.wxs', templateBuilder.buildXScript()),
         createAsset('comp.wxml', templateBuilder.buildBaseComponentTemplate('.wxml')),
@@ -48,7 +48,106 @@ export function createTemplateAssets(
     ]
 }
 
-/** Creates the Taro WeChat template builder without invoking its Webpack integration. */
+/**
+ * Adapts Taro's stock template builder to the WXML half of WX App wrapping without changing its recursive renderer.
+ *
+ * End-to-end contract
+ * -------------------
+ * React and Taro retain one in-memory ownership tree:
+ *
+ * App React root
+ *   -> App host records
+ *      -> vpt_page_outlet host at App {children}
+ *         -> independently scheduled Taro Page roots
+ *
+ * The patched WX document makes the singleton App host a TaroRootElement. App host mutations therefore batch under app.*
+ * and fan out to every mounted native Page. Each Page root remains its own TaroRootElement and emits only page.*. The React
+ * host renderer marks the outlet and its App ancestors with an ordinary compact `vo` prop after each commit, while patched
+ * hydrate() stops at vpt_page_outlet. Page roots remain attached for React Context, lifecycle, events, removal, refs, effects,
+ * and HMR without entering app data.
+ *
+ * Build-time output
+ * -----------------
+ * createTemplateAssets still asks one builder for the normal five products: shared base.wxml, utils.wxs, comp.wxml,
+ * comp.json, and each Page WXML. This adapter specializes only the two products that own the native join:
+ *
+ * - shared base.wxml receives branch-local slot forwarding plus vpt_fragment and vpt_page_outlet template definitions;
+ * - each Page WXML replaces Taro's root:root entry with one generic comp bound to app and one caller-owned taro_tmpl bound
+ *   to page as that component's default slot.
+ *
+ * utils.wxs remains Taro's normal compact-node dispatcher. comp.wxml and comp.json remain Taro's generic depth-reset
+ * component and still know only i, l, virtual-host behavior, and eh event dispatch. There is one shared template namespace,
+ * no Page-specific base file, no App/Page mode property, and no Page object threaded through App template data.
+ *
+ * First native Page
+ * -----------------
+ * createPageConfig starts the native Page with:
+ *
+ *     app  = { nn: 'vpt_fragment', cn: [] }
+ *     page = { cn: [] }
+ *
+ * nn lets unchanged comp dispatch one input object even though App JSX may produce one or many root hosts. The record
+ * is WXML-only rather than a Taro host, so it needs no sid. After React commits the Page root below the outlet, the framework
+ * queues a lazy hydrate(AppRoot).cn value beside the Page root's already-pending page.* payloads. Taro drains both through the
+ * native Page's existing first setData, making App wrapping and Page content appear atomically.
+ *
+ * Native WXML execution
+ * ---------------------
+ * Data/slot ownership and named-template ownership intentionally travel through different scopes:
+ *
+ * Page WXML (owns app, page, Page eh, and Page-content light DOM)
+ *   -> <comp i="{{app}}"> (crosses into a virtual custom-component scope)
+ *      -> comp.wxml (owns App eh, imports unchanged utils.wxs and shared base.wxml)
+ *         -> tmpl_0_vpt_fragment (iterates the real App compact roots in app.cn)
+ *            -> stock Taro templates (render App hosts and recurse through their cn arrays)
+ *               -> depth-reset <comp i="{{i}}" l="{{l}}">
+ *                    -> forwards <slot /> only when this compact subtree root has i.vo
+ *               -> tmpl_0_vpt_page_outlet at React's exact {children} position
+ *                  -> <slot />
+ *                     -> caller-owned <template is="taro_tmpl" data="{{root:page}}" />
+ *                        -> stock Taro templates render this native Page's page.cn records
+ *
+ * The virtual comp and both private templates add no native layout node. `vo` is part of the existing compact node i, not a
+ * component property or template context. App events execute through comp.eh; slotted Page events retain the native Page's
+ * eh. Both resolve the original Taro sid through the same event source.
+ *
+ * Named-template scope
+ * --------------------
+ * Slots transfer caller-owned light DOM only. They do not transfer the caller's named-template table or WXS modules. App
+ * dispatch runs inside comp.wxml, so vpt_fragment and vpt_page_outlet must live in base.wxml imported by that component.
+ * Putting those definitions in buildPageTemplate produces Page WXML that compiles, but component runtime dispatch fails with
+ * `Template tmpl_0_vpt_fragment not found`. Shared base.wxml makes the names visible in the root and every depth-reset comp
+ * scope and emits them once rather than once per Page.
+ *
+ * Projection-spine ownership
+ * --------------------------
+ * React's host renderer runs after the final commit tree exists and caches the outlet-to-root Taro host ancestor array. It
+ * skips the unchanged root-side suffix, gives old leaf-side nodes the ordinary host prop vo=false, and gives new ones vo=true.
+ * Taro's existing lazy structural hydration runs later and therefore serializes those props without projection-specific
+ * scheduler or hydrate behavior. If React replaces the outlet host while moving it, the renderer finds the unique new marker
+ * once and caches its new ancestor array. At a depth reset, i.vo makes forwarding an O(1) local decision; WXML never searches
+ * descendants, and Page trees instantiate no unnamed slot.
+ *
+ * Steady-state updates and navigation
+ * -----------------------------------
+ * A page.* setData updates only the caller-owned Page template inside the slot. app is not passed through that template and
+ * comp.i does not change, so Page updates cannot invalidate App recursion. Ordinary app.* payloads and outlet-spine marker
+ * changes remain in Taro's granular batch before it fans out to every retained native Page. Adding or removing a React Page
+ * root mutates the outlet only in memory, and the runtime suppresses that marker's native child update. A newly pushed Page
+ * receives the latest complete App snapshot in its initial batch, while existing and hidden Pages require no navigation
+ * synchronization.
+ *
+ * Method responsibilities
+ * -----------------------
+ * 1. buildBaseTemplate wraps Taro's buildTemplate output, preserves every stock host template, guards the slot at Taro's
+ *    existing depth-reset call site with i.vo, and adds the two private definitions to the shared namespace.
+ * 2. buildPageTemplate owns only the Page boundary: app binding, page binding, and the single Page-content slot.
+ * 3. buildXScript delegates unchanged because routing metadata already travels inside compact node i.
+ * 4. buildBaseComponentTemplate delegates unchanged so recursive comp remains generic and feature-independent.
+ *
+ * H5 never calls this WX output builder. Its App continues to receive ordinary Fragment children and none of these native
+ * data roots, templates, custom-component boundaries, or slot rules enter the browser build.
+ */
 function createTemplateBuilder() {
     const platform = new WxPlatform(
         {
@@ -62,7 +161,110 @@ function createTemplateBuilder() {
         {}
     )
     platform.modifyTemplate({})
-    return platform.template
+    const taroTemplateBuilder = platform.template
+
+    /**
+     * Replaces one pinned Taro fragment so an upstream template change cannot silently break the coordinated
+     * framework/runtime/WXML boundary or partially apply the feature.
+     */
+    function replaceExactlyOnce(source: string, current: string, replacement: string, description: string): string {
+        const firstIndex = source.indexOf(current)
+        const duplicateIndex = firstIndex === -1 ? -1 : source.indexOf(current, firstIndex + current.length)
+        if (firstIndex === -1 || duplicateIndex !== -1) {
+            throw new Error(`Expected one ${description}, found ${firstIndex === -1 ? 0 : 'multiple'}`)
+        }
+        return `${source.slice(0, firstIndex)}${replacement}${source.slice(firstIndex + current.length)}`
+    }
+
+    return {
+        buildBaseTemplate: (componentConfig: TemplateComponentConfig) => {
+            const source = taroTemplateBuilder.buildTemplate(componentConfig)
+            /*
+             * Taro inserts recursive comp only when template depth resets. App {children} may be below any number of those
+             * boundaries, so each boundary reads the renderer-maintained vo marker on its compact subtree root before forwarding
+             * the caller's default slot. No App/Page mode or Page data is threaded through template scopes: Page recursion
+             * and unrelated App branches have no marker, while the outlet spine carries the one Page-owned slot.
+             */
+            const slotTransparentRecursion = replaceExactlyOnce(
+                source,
+                '<comp i="{{i}}" l="{{l}}" />',
+                `<comp i="{{i}}" l="{{l}}"><slot wx:if="{{i.vo}}" /></comp>`,
+                'recursive comp call'
+            )
+
+            /*
+             * These definitions belong in shared base.wxml rather than buildPageTemplate. Although native data is Page-owned,
+             * the dynamic calls that render App records execute after crossing into comp.wxml's component scope. WXML slots
+             * transfer caller-owned light DOM, not the caller's named-template table or WXS modules. comp.wxml can therefore
+             * resolve only its own definitions and those imported from base.wxml.
+             *
+             * Defining the two names in Page WXML is not merely redundant: WeChat accepts that Page file at compile time, then
+             * comp.wxml's runtime dispatch fails with `Template tmpl_0_vpt_fragment not found` because component template
+             * resolution never searches the caller Page. Shared base.wxml is already imported by comp.wxml, makes both names
+             * visible at every depth-reset component scope, and emits them once instead of once per generated Page.
+             *
+             * Page WXML can give generic comp one i object, whereas App output is a root collection. vpt_fragment bridges
+             * those contracts without becoming a native or Taro host: its nn is only a template discriminator and its
+             * template emits each real cn record directly. Keeping the collection behind one comp is important because that
+             * component owns exactly one Page slot regardless of whether App rendered zero, one, or many top-level hosts.
+             * The synthetic record itself is not keyed or event-addressable, so it deliberately has no sid. Its cn items are
+             * different: they are real hydrated Taro elements, text nodes, or the outlet, and every one has Taro's stable sid.
+             * wx:key="sid" matches Taro's stock root.cn loop so insertion/reordering preserves native-component instances,
+             * sibling identity, and event-source routing instead of reusing children only by array position.
+             *
+             * vpt_page_outlet is the matching terminal. The patched runtime retains Page roots below that marker in memory
+             * and serializes no children into app data, while React's host renderer marks its compact ancestor spine with vo.
+             * The slot inserts the parent Page's separate page data at the same visual position and adds no native layout
+             * wrapper.
+             */
+            return `${slotTransparentRecursion}
+<template name="tmpl_0_vpt_fragment">
+  <template
+    is="{{xs.a(0, item.nn, '')}}"
+    data="{{i:item,c:1,l:xs.f('',item.nn)}}"
+    wx:for="{{i.cn}}"
+    wx:key="sid"
+  />
+</template>
+<template name="tmpl_0_vpt_page_outlet"><slot /></template>
+`
+        },
+        buildXScript: () => {
+            // Alias selection and compact paths are unchanged; both App and Page records use Taro's normal node vocabulary,
+            // and projection ownership already travels on the current i object as vo.
+            return taroTemplateBuilder.buildXScript()
+        },
+        buildBaseComponentTemplate: (ext: string) => {
+            /*
+             * Keep comp generic. i is the current compact node dispatched through i.nn. l is Taro's lineage of selected
+             * special/native aliases: xs.f records bounded/nestable ancestors and xs.a uses that history when choosing a
+             * generated template level on non-recursive WXML platforms. The current comp.wxml restarts its local lineage from
+             * i.nn, but l remains part of Taro's intentional depth-reset component contract and platform variants may consume
+             * it. Preserve that upstream binding; only the new Page-root comp starts with the property's empty default. Slot
+             * forwarding lives at this base.wxml call site, and vo already belongs to i, so comp still needs no App/Page mode,
+             * projection property, or Page data.
+             */
+            return taroTemplateBuilder.buildBaseComponentTemplate(ext)
+        },
+        buildPageTemplate: (baseTempPath: string, page: Record<string, unknown>) => {
+            const source = taroTemplateBuilder.buildPageTemplate(baseTempPath, page)
+
+            /*
+             * The native Page owns both data bindings. app is the transparent single-node adapter rendered by unchanged
+             * comp; the caller-owned taro_tmpl still reads only page and becomes comp's one default slot. A page.* update
+             * therefore cannot enter App template scopes or a component property, while App recursion can place the Page
+             * exactly at {children} by consuming the slot at vpt_page_outlet. The root call omits l because this native comp
+             * starts a fresh lineage scope and its generic property already defaults to the empty string. It also emits no id:
+             * no runtime lookup, event dispatch, ref, or selector addresses this virtual boundary.
+             */
+            return replaceExactlyOnce(
+                source,
+                '<template is="taro_tmpl" data="{{root:root}}" />',
+                `<comp i="{{app}}"><template is="taro_tmpl" data="{{root:page}}" /></comp>`,
+                'Page template entry'
+            )
+        }
+    }
 }
 
 /** Creates template metadata from reachable Taro hosts and native component JSX fields. */

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

@@ -5,8 +5,9 @@ import { createPlacement, type GeneratedSubpackage, type PackageLocation, type P
 
 export type { GeneratedSubpackage, Placement } from './placement.ts'
 
-const pnpmFrameworkPackagePattern = /\/node_modules\/\.pnpm\/(?:@tarojs\+|react(?:-dom|-reconciler)?@|scheduler@)/
-const workspaceFrameworkPackagePattern = /\/packages\/(?:taro-react|taro-plugin-framework-react)\//
+const pnpmFrameworkPackagePattern =
+    /\/node_modules\/\.pnpm\/(?:@tarojs\+|vite-plugin-taro-runtime@|react(?:-dom|-reconciler)?@|scheduler@)/
+const workspaceFrameworkPackagePattern = /\/packages\/(?:taro-react|taro-plugin-framework-react|taro-runtime)\//
 
 /** Selects the explicit React/Taro roots whose complete dependency closure forms the framework vendor chunk. */
 export function isWxFrameworkVendorModule(moduleId: string): boolean {

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

@@ -43,6 +43,10 @@ function createWxPlugin(options: VptOptions, resolver: WxResolver, placement: Wx
 
                 resolve: {
                     alias: [
+                        {
+                            find: /^@tarojs\/runtime$/,
+                            replacement: packageRequire.resolve('@tarojs/runtime/dist/index.js')
+                        },
                         {
                             find: /^@tarojs\/components$/,
                             replacement: packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react')
@@ -157,7 +161,7 @@ function createWxPlugin(options: VptOptions, resolver: WxResolver, placement: Wx
 
 /** Creates the build-time constants required by Taro's legacy feature gates. */
 function createTaroDefines(): Record<string, string> {
-    const taroVersion = String((packageRequire('@tarojs/runtime/package.json') as { version: string }).version)
+    const taroVersion = String((packageRequire('@tarojs/taro/package.json') as { version: string }).version)
 
     return {
         'process.env.FRAMEWORK': JSON.stringify('react'),

package/src/runtime/wx/capsule/page.ts

@@ -8,6 +8,22 @@ import { createPageConfig } from './taro-runtime.ts'
 declare const __VPT_PAGE_PATH__: string
 declare const __VPT_PAGE_CONFIG__: Record<string, unknown>
 
-const config = createPageConfig(PageComponent, __VPT_PAGE_PATH__, { root: { cn: [] } }, __VPT_PAGE_CONFIG__)
+/*
+ * Generated Page WXML invokes Taro's unchanged recursive comp, whose input contract is one compact node selected by i.nn.
+ * App JSX does not have that cardinality: it may return one or many top-level hosts, and the private Page outlet may
+ * occur at any depth within them. vpt_fragment is therefore a WXML-only collection adapter. Its fixed nn selects a
+ * transparent template that iterates cn while one surrounding comp owns the Page's default slot. Runtime projection markers
+ * relay that slot only through the App branch containing the outlet. Without the fragment, Page WXML would need one comp—and
+ * one potential copy of the Page slot—for every App root, or comp would need an App-specific collection mode.
+ *
+ * This record is not a Taro host: it has no Fiber, event source, ref, lifecycle, native element, or keyed parent collection.
+ * It consequently needs no sid. Only cn is seeded and updated; nn remains the stable generic-template discriminator.
+ */
+const config = createPageConfig(
+    PageComponent,
+    __VPT_PAGE_PATH__,
+    { app: { nn: 'vpt_fragment', cn: [] }, page: { cn: [] } },
+    __VPT_PAGE_CONFIG__
+)
 
 export default config

package/src/runtime/wx/capsule/taro-runtime.ts

@@ -5,10 +5,4 @@ import '@tarojs/plugin-platform-weapp/dist/runtime.js'
 
 export { createReactApp } from '@tarojs/plugin-framework-react/dist/runtime'
 export { default as ReactDOM } from '@tarojs/react'
-export {
-    createPageConfig,
-    createRecursiveComponentConfig,
-    Current,
-    document,
-    injectPageInstance
-} from '@tarojs/runtime'
+export { createPageConfig, createRecursiveComponentConfig } from '@tarojs/runtime'

package/src/runtime/wx/wechat.d.ts

@@ -31,6 +31,14 @@ declare const wx: {
     request(options: WeChatRequestOptions): void
 }
 
+/** Native Page surface used by the singleton App-data scheduler. */
+type WeChatPage = {
+    setData(data: Readonly<Record<string, unknown>>, callback?: () => void): void
+}
+
+/** Returns every mounted native Page in stack order. */
+declare function getCurrentPages(): WeChatPage[]
+
 /** Registers the native WeChat Mini Program application. */
 declare function App(options: object): void