vite-plugin-taro 0.6.1 → 0.6.3

package/README.en.md

@@ -31,12 +31,17 @@ Continue with the [Quick Start guide](https://vpt.js.org/guides/quick-start/).
 
 ## Documentation
 
+- [Quick Start](https://vpt.js.org/guides/quick-start/)
+- [Styles](https://vpt.js.org/guides/styles/)
 - [Automatic subpackages](https://vpt.js.org/guides/automatic-subpackages/)
 - [Native WeChat components](https://vpt.js.org/guides/native-components/)
 - [Hot module replacement](https://vpt.js.org/guides/hot-module-replacement/)
+- [Configuration options](https://vpt.js.org/guides/configuration/)
+- [Conditional compilation](https://vpt.js.org/guides/conditional-directives/)
 - [Skyline mode](https://vpt.js.org/guides/skyline-mode/)
 - [Migrate from Taro CLI](https://vpt.js.org/guides/migrate-from-taro/)
-- [Configuration reference](https://vpt.js.org/guides/configuration/)
+- [Module system](https://vpt.js.org/references/module-system/)
+- [Hot module replacement internals](https://vpt.js.org/references/hmr-implementation/)
 - [Repository management](https://vpt.js.org/references/repository-management/)
 
 ## License

package/README.md

@@ -32,12 +32,17 @@ npm create vite-taro@latest my-app
 
 ## 文档
 
+- [快速开始](https://vpt.js.org/guides/quick-start/)
+- [样式](https://vpt.js.org/guides/styles/)
 - [全自动分包](https://vpt.js.org/guides/automatic-subpackages/)
 - [微信原生组件](https://vpt.js.org/guides/native-components/)
 - [开发者工具热更新](https://vpt.js.org/guides/hot-module-replacement/)
+- [配置选项](https://vpt.js.org/guides/configuration/)
+- [条件编译](https://vpt.js.org/guides/conditional-directives/)
 - [Skyline 模式](https://vpt.js.org/guides/skyline-mode/)
 - [从 Taro CLI 迁移](https://vpt.js.org/guides/migrate-from-taro/)
-- [配置参考](https://vpt.js.org/guides/configuration/)
+- [模块系统](https://vpt.js.org/references/module-system/)
+- [热更新原理](https://vpt.js.org/references/hmr-implementation/)
 - [仓库维护](https://vpt.js.org/references/repository-management/)
 
 ## 许可证

package/dist/node/plugins/h5/transform-app.js

@@ -1,4 +1,4 @@
-import { types } from '@babel/core';
+import * as types from '@babel/types';
 import { createPageComponentImportPath } from '../../utils/modules.js';
 import { createAppConfig } from '../../utils/project-config.js';
 import { replaceWithAst } from '../../utils/transform.js';

package/dist/node/plugins/wx/dev/plugins.d.ts

@@ -28,18 +28,8 @@ export declare function createWxDevelopmentPlugin(options: VptOptions, applicati
  * only `assets/global.wxss`, which preserves the App heap. The serve-only plugin leaves production output unchanged.
  */
 export declare function removeDevelopmentAppWxss(bundle: Record<string, unknown>): void;
-/** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
-export declare function injectReactRefreshBootstrap(code: string): {
-    code: string;
-    map: null;
-};
-/** Connects the shared WX dev runtime to the application graph's Taro runtime instance. */
-export declare function injectTaroConnection(code: string): {
-    code: string;
-    map: null;
-};
-/** Activates development-only lifecycle handling for one plugin-owned Page capsule. */
-export declare function injectPageHmr(code: string, route: string): {
+/** Injects the retained snapshot at the exact native Page registration edge. */
+export declare function injectPageShellHmr(code: string): {
     code: string;
     map: null;
 };

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

@@ -2,11 +2,10 @@ import { normalizePath, transformWithOxc } from 'vite';
 import { esTarget } from '../../../utils/constant.js';
 import { memoize } from '../../../utils/memoize.js';
 import { normalizeModuleId } from '../../../utils/modules.js';
-import { appCapsulePath, pageCapsulePath, rolldownRuntimeId, taroRuntimePath } from '../module.js';
+import { pageShellPath, rolldownRuntimeId } from '../module/module.js';
 import { createWxDevHost } from './dev-host.js';
 import { developmentAppWxssFileName } from './hmr-files.js';
 import { createWxReactRefreshTransforms } from './react-refresh.js';
-const taroRuntimeId = '@tarojs/runtime';
 /** Selects the sole Vite environment that owns the physical Mini Program development project. */
 export function isWxClientEnvironment(environment) {
     return environment.name === 'client';
@@ -28,9 +27,7 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
      */
     let host = null;
     // Portable hook filters stay broad; these exact identities exclude similarly named user modules.
-    const normalizedAppCapsulePath = normalizePath(appCapsulePath);
-    const normalizedPageCapsulePath = normalizePath(pageCapsulePath);
-    const normalizedTaroRuntimePath = normalizePath(taroRuntimePath);
+    const normalizedPageShellPath = normalizePath(pageShellPath);
     return [
         {
             name: 'vpt:wx-dev',
@@ -107,41 +104,15 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
             }
         },
         {
-            name: 'vpt:wx-react-refresh-bootstrap',
+            name: 'vpt:wx-page-shell-hmr',
             apply: 'serve',
             transform: {
                 order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/app\.js(?:\?|$)/ },
+                filter: { id: /\/runtime\/wx\/native\/page\.js(?:\?|$)/ },
                 handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedAppCapsulePath)
+                    if (normalizeModuleId(id) !== normalizedPageShellPath)
                         return;
-                    return injectReactRefreshBootstrap(code);
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-page-hmr',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/page\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedPageCapsulePath)
-                        return;
-                    return injectPageHmr(code, getPageRoute(id));
-                }
-            }
-        },
-        {
-            name: 'vpt:wx-taro-hmr',
-            apply: 'serve',
-            transform: {
-                order: 'post',
-                filter: { id: /\/runtime\/wx\/capsule\/taro-runtime\.js(?:\?|$)/ },
-                handler(code, id) {
-                    if (normalizeModuleId(id) !== normalizedTaroRuntimePath)
-                        return;
-                    return injectTaroConnection(code);
+                    return injectPageShellHmr(code);
                 }
             }
         },
@@ -166,42 +137,17 @@ export function createWxDevelopmentPlugin(options, applicationEntryIds) {
 export function removeDevelopmentAppWxss(bundle) {
     delete bundle[developmentAppWxssFileName];
 }
-/** Ensures the Refresh hook exists before React's renderer evaluates and injects itself. */
-export function injectReactRefreshBootstrap(code) {
-    return {
-        code: `import ${JSON.stringify('/@react-refresh')};\n${code}`,
-        map: null
-    };
-}
-/** Connects the shared WX dev runtime to the application graph's Taro runtime instance. */
-export function injectTaroConnection(code) {
-    if (!/\bCurrent\b/.test(code) || !/\bdocument\b/.test(code) || !/\binjectPageInstance\b/.test(code)) {
-        throw new Error('WX Taro runtime must expose Current, document, and injectPageInstance for HMR');
+/** Injects the retained snapshot at the exact native Page registration edge. */
+export function injectPageShellHmr(code) {
+    const registration = 'Page(pageConfig)';
+    if (!code.includes(registration)) {
+        throw new Error('WX native Page shell must register pageConfig');
     }
-    const taroImport = `import { Current as __vptCurrent, document as __vptDocument, injectPageInstance as __vptInjectPageInstance } from ${JSON.stringify(taroRuntimeId)};`;
     return {
-        code: `${code}\n${taroImport}\n__rolldown_runtime__.connectTaro(__vptCurrent, __vptDocument, __vptInjectPageInstance);`,
+        code: code.replace(registration, 'Page(__rolldown_runtime__.injectPageHmr(pageConfig))'),
         map: null
     };
 }
-/** Activates development-only lifecycle handling for one plugin-owned Page capsule. */
-export function injectPageHmr(code, route) {
-    if (!/\bconst\s+config\s*=/.test(code) || !/\bexport\s+default\s+config\b/.test(code)) {
-        throw new Error('WX Page capsule must declare and default-export config before HMR injection');
-    }
-    return {
-        code: `${code}\n__rolldown_runtime__.injectPageHmr(config, ${JSON.stringify(route)});`,
-        map: null
-    };
-}
-/** Reads the stable route carried by every specialized Page capsule ID. */
-function getPageRoute(id) {
-    const queryIndex = id.indexOf('?');
-    const route = queryIndex < 0 ? null : new URLSearchParams(id.slice(queryIndex + 1)).get('route');
-    if (!route)
-        throw new Error(`WX Page capsule is missing its route: ${id}`);
-    return route;
-}
 /*
  * memoize owns a mutable one-entry-by-input cache. The assembled runtime source is byte-identical across complete generations
  * because both the Rolldown base and injected implementation are immutable for the server lifetime. Reusing its lowered result

package/dist/node/plugins/wx/dev/react-refresh.d.ts

@@ -4,8 +4,9 @@ import type { Plugin } from 'vite';
  *
  * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
  * global scope; wx has neither. Each transform adapts one piece of that contract:
- * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ * - the refresh runtime module (id-filtered): the runtime reads and assigns
  *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation;
+ * - React Reconciler: its renderer injection statically depends on the refresh runtime, fixing cold-start order;
  * - react-family modules (filtered on free references): the DevTools hook is read as a free
  *   variable, which the WeChat runtime scope never resolves against `global` — every free
  *   reference becomes an explicit member access;
@@ -13,10 +14,15 @@ import type { Plugin } from 'vite';
  *   needed because the transform generates local wrappers over the imported refresh
  *   runtime, so the guard that checks for the global is removed.
  *
- * Each transform's filter is its routing: the three domains are disjoint, so a module is
- * transformed by at most one of them, and modules outside all three never reach a handler.
+ * Filters route every adaptation directly. The Reconciler intentionally receives the renderer dependency first and the
+ * global-hook rewrite second; modules outside these explicit domains never reach a handler.
  */
 export declare function createWxReactRefreshTransforms(): Plugin[];
+/** Makes renderer hook injection statically depend on the refresh runtime. */
+export declare function injectReactRefreshRendererDependency(code: string): {
+    code: string;
+    map: null;
+};
 export declare function transformRefreshRuntime({ code, id }: {
     code: string;
     id: string;

package/dist/node/plugins/wx/dev/react-refresh.js

@@ -1,6 +1,8 @@
 import { isReferenceIdentifier } from 'oxc-walker';
 import { memoize } from '../../../utils/memoize.js';
+import { normalizeModuleId } from '../../../utils/modules.js';
 import { transformWithOxcWalker } from '../../../utils/oxc-transform.js';
+import { reactReconcilerRoot } from '../module/module.js';
 /** The React DevTools hook protocol name; free references must target `global` in wx. */
 const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__';
 /**
@@ -10,7 +12,7 @@ const reactDevtoolsHookProtocol = '__REACT_DEVTOOLS_GLOBAL_HOOK__';
  * - `__getReactRefreshIgnoredExports` is an optional extension point read while validating a refresh boundary.
  *   Leaving that read on the nonexistent `window` crashes every update validation pass.
  *
- * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the vendored runtime
+ * Keeping this list explicit prevents the adapter from rewriting unrelated browser accesses if the refresh runtime
  * gains new code. Any future React Refresh protocol addition therefore requires a deliberate compatibility decision.
  */
 const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__getReactRefreshIgnoredExports'];
@@ -19,8 +21,9 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *
  * @vitejs/plugin-react's generated refresh code assumes the web HTML preamble and a browser
  * global scope; wx has neither. Each transform adapts one piece of that contract:
- * - the refresh runtime module (id-filtered): the vendored runtime reads and assigns
+ * - the refresh runtime module (id-filtered): the runtime reads and assigns
  *   `window` protocol globals (rewritten to `global`) and must inject itself at evaluation;
+ * - React Reconciler: its renderer injection statically depends on the refresh runtime, fixing cold-start order;
  * - react-family modules (filtered on free references): the DevTools hook is read as a free
  *   variable, which the WeChat runtime scope never resolves against `global` — every free
  *   reference becomes an explicit member access;
@@ -28,8 +31,8 @@ const refreshRuntimeWindowGlobals = ['__registerBeforePerformReactRefresh', '__g
  *   needed because the transform generates local wrappers over the imported refresh
  *   runtime, so the guard that checks for the global is removed.
  *
- * Each transform's filter is its routing: the three domains are disjoint, so a module is
- * transformed by at most one of them, and modules outside all three never reach a handler.
+ * Filters route every adaptation directly. The Reconciler intentionally receives the renderer dependency first and the
+ * global-hook rewrite second; modules outside these explicit domains never reach a handler.
  */
 export function createWxReactRefreshTransforms() {
     return [
@@ -38,13 +41,27 @@ export function createWxReactRefreshTransforms() {
             apply: 'serve',
             transform: {
                 order: 'post',
-                // The vendored refresh runtime module; id-filtered, so no code scan.
+                // The refresh runtime module is id-filtered, so no code scan is needed.
                 filter: { id: /^\/@react-refresh(?:\?|$)/ },
                 handler(code, id) {
                     return fixRefreshRuntime({ code, id });
                 }
             }
         },
+        {
+            name: 'vpt:wx-react-refresh-renderer-dependency',
+            apply: 'serve',
+            transform: {
+                order: 'post',
+                filter: { id: /\/react-reconciler\/cjs\/react-reconciler\.development\.js(?:\?|$)/ },
+                handler(code, id) {
+                    const rendererId = `${reactReconcilerRoot}/cjs/react-reconciler.development.js`;
+                    if (normalizeModuleId(id) !== rendererId)
+                        return;
+                    return injectReactRefreshRendererDependency(code);
+                }
+            }
+        },
         {
             name: 'vpt:wx-react-devtools-hook',
             apply: 'serve',
@@ -86,7 +103,8 @@ export function createWxReactRefreshTransforms() {
  * The protocol name is unique, but only reference identifiers are rewritten. Declaration
  * keys and explicit members such as `global.__REACT_DEVTOOLS_GLOBAL_HOOK__` must remain
  * untouched; rewriting those would either produce invalid syntax or double-prefix the hook.
- * The eagerly evaluated refresh runtime creates the hook on `global` before the renderer loads.
+ * The Reconciler's injected static dependency orders hook injection before renderer initialization independently of Rolldown's
+ * final chunking decision.
  */
 function createReactDevtoolsHookVisitor(editor) {
     return function enter(node, parent) {
@@ -133,7 +151,7 @@ function createRefreshRuntimeVisitor(editor) {
             node.property.type === 'Identifier' &&
             refreshRuntimeWindowGlobals.some((globalName) => globalName === node.property.name)) {
             // `global` is the shared wx App heap used by the dev runtime and hook injection. Only
-            // replacing the object range preserves the vendored runtime byte-for-byte otherwise
+            // replacing the object range preserves the upstream runtime byte-for-byte otherwise
             // and prevents unrelated `window` expressions from being silently adapted.
             editor.overwrite(node.object.start, node.object.end, 'global');
         }
@@ -169,6 +187,16 @@ function createRefreshPreambleGuardVisitor(editor) {
         this.skip();
     };
 }
+/** Makes renderer hook injection statically depend on the refresh runtime. */
+export function injectReactRefreshRendererDependency(code) {
+    if (!/\bhook\.inject\(internals\)/.test(code)) {
+        throw new Error('React Reconciler must inject its renderer into the DevTools hook');
+    }
+    return {
+        code: `import '/@react-refresh'\n${code}`,
+        map: null
+    };
+}
 export function transformRefreshRuntime({ code, id }) {
     return transformWithOxcWalker({
         code,

package/dist/node/plugins/wx/dev/wx-dev-options.js

@@ -3,7 +3,7 @@ import { build } from 'rolldown';
 import { viteReporterPlugin } from 'rolldown/experimental';
 import { once } from '../../../utils/once.js';
 import { resolvePackageFile } from '../../../utils/packages.js';
-import { appShellFileName } from '../module.js';
+import { appShellFileName } from '../module/module.js';
 /**
  * Installs physical WX output and runtime conventions over Vite's browser-oriented bundled-development options.
  * Build completion deliberately remains outside this options adapter: DevEngine onOutput is the single lifecycle authority.
@@ -105,7 +105,7 @@ function ensureSingleOutput(rolldownOptions) {
 /**
  * Prepends entry banners after Rolldown's analysis so their native requires remain physical dependencies rather than chunk
  * graph edges. The App initializes the runtime identity, while every Page explicitly applies the watched patch data before its
- * capsule import continues.
+ * native Page registration.
  */
 function createEntryBanner(pageFiles) {
     return (chunk) => {
@@ -114,8 +114,7 @@ function createEntryBanner(pageFiles) {
         }
         if (pageFiles.has(chunk.name)) {
             const patchesPath = path.posix.relative(path.posix.dirname(chunk.fileName), 'hmr/patches.js');
-            const route = chunk.name.slice(0, -'.js'.length);
-            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'), ${JSON.stringify(route)});\n`;
+            return `__rolldown_runtime__.applyPatches(require('${patchesPath}'));\n`;
         }
         return '';
     };

package/dist/node/plugins/wx/{module.js → module/module.js}

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { normalizePath } from 'vite';
-import { normalizeModuleId } from '../../utils/modules.js';
-import { packageRequire, resolvePackageFile } from '../../utils/packages.js';
+import { normalizeModuleId } from '../../../utils/modules.js';
+import { packageRequire, resolvePackageFile } from '../../../utils/packages.js';
 /** Identifies Rolldown's generated helper module independently of its unstable output filename. */
 export const rolldownRuntimeId = '\0rolldown/runtime.js';
 /** Resolves the direct React Reconciler dependency without assuming pnpm's layout. */

package/dist/node/plugins/wx/placer/placement.d.ts

@@ -1,4 +1,5 @@
 import type { Rolldown } from 'vite';
+export declare const subpackagePlanningBudget = 1900000;
 /** Identifies one generated code-only subpackage by its physical output root. */
 export type SubpackageLocation = {
     /** Discriminates generated subpackages from main. */

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

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 // Leave headroom below WeChat's 2M subpackage limit for rendered wrappers and native assets.
-const subpackagePlanningBudget = 1_900_000;
+export const subpackagePlanningBudget = 1_900_000;
 const generatedSubpackageRootPrefix = 'sub/p_';
 /** Shared main-package value used for every synchronously reachable chunk. */
 const mainPackage = { kind: 'main' };

package/dist/node/plugins/wx/placer/placer.d.ts

@@ -1,6 +1,8 @@
-import type { Plugin, Rolldown } from 'vite';
+import { type Plugin, type Rolldown } from 'vite';
 import { type GeneratedSubpackage, type PackageLocation } from './placement.ts';
 export type { GeneratedSubpackage, Placement } from './placement.ts';
+/** Selects the explicit React/Taro roots whose complete dependency closure forms the framework vendor chunk. */
+export declare function isWxFrameworkVendorModule(moduleId: string): boolean;
 /** Placement services consumed by the later `vpt:wx` rendering and output hooks. */
 export type WxPlacementPlugin = Plugin & Readonly<{
     getPackageLocation(chunk: Rolldown.RenderedChunk | Rolldown.OutputChunk): PackageLocation;
@@ -18,6 +20,20 @@ export declare const placementRolldownOptions: {
      * participation only; LTHP mutates the resulting OutputChunk filenames later without replacing the chunks.
      */
     output: {
+        /**
+         * React and Taro form one stable framework boundary shared by the App and every Page capsule. Keeping their complete
+         * dependency closure together prevents application edits from invalidating framework chunk identity and makes later
+         * development generations eligible to reuse the unchanged vendor. All remaining modules use Rolldown's automatic
+         * chunking; physical WX package placement operates on those final chunks without imposing another split strategy.
+         */
+        codeSplitting: {
+            groups: {
+                name: string;
+                test: typeof isWxFrameworkVendorModule;
+                priority: number;
+                includeDependenciesRecursively: boolean;
+            }[];
+        };
         /**
          * Native App/Page/Component shells are files addressed directly by WeChat and must retain the exact names configured
          * in `input`, such as `app.js` and `pages/home/index.js`. Transport is excluded even though it is CommonJS:

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

@@ -1,6 +1,14 @@
-import { getWxExecutionKind, isTransportModule } from '../module.js';
+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)\//;
+/** Selects the explicit React/Taro roots whose complete dependency closure forms the framework vendor chunk. */
+export function isWxFrameworkVendorModule(moduleId) {
+    const normalizedId = normalizePath(moduleId);
+    return pnpmFrameworkPackagePattern.test(normalizedId) || workspaceFrameworkPackagePattern.test(normalizedId);
+}
 /**
  * Rolldown options owned by WX placement. Every field enforces a distinct output invariant. The plugin returns this object
  * from its config hook, while direct Rolldown integration tests reuse the same value to exercise the identical lifecycle.
@@ -11,6 +19,22 @@ export const placementRolldownOptions = {
      * participation only; LTHP mutates the resulting OutputChunk filenames later without replacing the chunks.
      */
     output: {
+        /**
+         * React and Taro form one stable framework boundary shared by the App and every Page capsule. Keeping their complete
+         * dependency closure together prevents application edits from invalidating framework chunk identity and makes later
+         * development generations eligible to reuse the unchanged vendor. All remaining modules use Rolldown's automatic
+         * chunking; physical WX package placement operates on those final chunks without imposing another split strategy.
+         */
+        codeSplitting: {
+            groups: [
+                {
+                    name: 'vendor',
+                    test: isWxFrameworkVendorModule,
+                    priority: 100,
+                    includeDependenciesRecursively: true
+                }
+            ]
+        },
         /**
          * Native App/Page/Component shells are files addressed directly by WeChat and must retain the exact names configured
          * in `input`, such as `app.js` and `pages/home/index.js`. Transport is excluded even though it is CommonJS:

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

@@ -2,7 +2,7 @@ import { esTarget } from '../../utils/constant.js';
 import { packageRequire } from '../../utils/packages.js';
 import { clientTaroNativeId } from '../client/constant.js';
 import { createWxDevelopmentPlugin } from './dev/plugins.js';
-import { getWxExecutionKind, isTransportModule } from './module.js';
+import { getWxExecutionKind, isTransportModule } from './module/module.js';
 import { compileNativeComponentInterface } from './native/compile-native-component-interface.js';
 import { createOutputFiles } from './output/files.js';
 import { createWxPlacementPlugin } from './placer/placer.js';

package/dist/node/plugins/wx/render/capsule.d.ts

@@ -1,4 +1,36 @@
 import type { Rolldown } from 'vite';
-import { type AstTransformResult } from '../../../utils/transform.ts';
-/** Renders one ESM chunk as an inert SystemJS capsule. */
-export declare function renderCapsule(code: string, chunk: Rolldown.RenderedChunk, sourcemap?: boolean): AstTransformResult;
+import type { AstTransformResult } from '../../../utils/transform.ts';
+/**
+ * Converts one final Rolldown ESM chunk into the inert registration consumed by the WX module runtime.
+ *
+ * Why this boundary exists:
+ *
+ * - Rolldown produces an ESM chunk graph, but a Mini Program loads emitted JavaScript through native `require` and
+ *   `require.async`; it does not provide the browser ESM loader that normally links Vite chunks.
+ * - Native App, Page, and Component shells must start through WeChat's synchronous lifecycle APIs, while their application
+ *   graph still needs ESM linking semantics such as cycles, live exports, dynamic imports, `import.meta`, and top-level await.
+ * - The plugin therefore keeps native lifecycle shells as CommonJS and executes application "capsules" through the bundled
+ *   SystemJS runtime. Native shells enter that graph with `global.System.importSync`, and genuine asynchronous boundaries use
+ *   the same runtime through `System.import`.
+ *
+ * What this renderer emits:
+ *
+ * The result is CommonJS source whose `module.exports` is a SystemJS registration tuple:
+ * `[logicalDependencyIds, declaration]`. Requiring a capsule only returns this inert tuple; it does not execute application
+ * code or call a global `System.register`. The generated transport can consequently load the physical file from either the
+ * main package or a subpackage, then hand its registration to the loader. The loader owns linking, setter invocation,
+ * execution order, cycle handling, and export publication.
+ *
+ * Why references are rewritten:
+ *
+ * Rolldown imports name physical output files whose relative paths include placement directories and content hashes. The
+ * SystemJS registry instead uses package-neutral logical chunk IDs. Canonicalizing both static and literal dynamic references
+ * here lets transport independently map a stable module identity to the physical `require` path selected by WX placement.
+ * Runtime-computed dynamic IDs cannot be canonicalized and are intentionally preserved.
+ *
+ * This function runs on final Rolldown output rather than arbitrary source modules. `transformSystemJs` accepts only the
+ * normalized final-chunk grammar required by this pipeline and fails the build on unsupported forms instead of risking a
+ * partial or semantically incorrect capsule. Source maps remain optional because WX development output deliberately disables
+ * them on this startup-critical path.
+ */
+export declare function renderCapsule(code: string, chunk: Rolldown.RenderedChunk, sourcemap: boolean): AstTransformResult;

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

@@ -1,13 +1,54 @@
-import transformDynamicImport from '@babel/plugin-transform-dynamic-import';
-import transformModulesSystemjs from '@babel/plugin-transform-modules-systemjs';
-import { transformWithBabel } from '../../../utils/transform.js';
-import { wrapCapsulePlugin } from './capsule-wrapper.js';
-/** Renders one ESM chunk as an inert SystemJS capsule. */
-export function renderCapsule(code, chunk, sourcemap = true) {
-    return transformWithBabel(code, chunk.fileName, [
-        transformDynamicImport,
-        // Erase Babel's internal plugin pass type.
-        transformModulesSystemjs,
-        wrapCapsulePlugin(chunk.fileName)
-    ], sourcemap);
+import { resolveLogicalChunkReference } from '../module/chunk-path.js';
+import { transformSystemJs } from './system-js/system-js.js';
+/**
+ * Converts one final Rolldown ESM chunk into the inert registration consumed by the WX module runtime.
+ *
+ * Why this boundary exists:
+ *
+ * - Rolldown produces an ESM chunk graph, but a Mini Program loads emitted JavaScript through native `require` and
+ *   `require.async`; it does not provide the browser ESM loader that normally links Vite chunks.
+ * - Native App, Page, and Component shells must start through WeChat's synchronous lifecycle APIs, while their application
+ *   graph still needs ESM linking semantics such as cycles, live exports, dynamic imports, `import.meta`, and top-level await.
+ * - The plugin therefore keeps native lifecycle shells as CommonJS and executes application "capsules" through the bundled
+ *   SystemJS runtime. Native shells enter that graph with `global.System.importSync`, and genuine asynchronous boundaries use
+ *   the same runtime through `System.import`.
+ *
+ * What this renderer emits:
+ *
+ * The result is CommonJS source whose `module.exports` is a SystemJS registration tuple:
+ * `[logicalDependencyIds, declaration]`. Requiring a capsule only returns this inert tuple; it does not execute application
+ * code or call a global `System.register`. The generated transport can consequently load the physical file from either the
+ * main package or a subpackage, then hand its registration to the loader. The loader owns linking, setter invocation,
+ * execution order, cycle handling, and export publication.
+ *
+ * Why references are rewritten:
+ *
+ * Rolldown imports name physical output files whose relative paths include placement directories and content hashes. The
+ * SystemJS registry instead uses package-neutral logical chunk IDs. Canonicalizing both static and literal dynamic references
+ * here lets transport independently map a stable module identity to the physical `require` path selected by WX placement.
+ * Runtime-computed dynamic IDs cannot be canonicalized and are intentionally preserved.
+ *
+ * This function runs on final Rolldown output rather than arbitrary source modules. `transformSystemJs` accepts only the
+ * normalized final-chunk grammar required by this pipeline and fails the build on unsupported forms instead of risking a
+ * partial or semantically incorrect capsule. Source maps remain optional because WX development output deliberately disables
+ * them on this startup-critical path.
+ */
+export function renderCapsule(code, chunk, sourcemap) {
+    return transformSystemJs({
+        code,
+        filename: chunk.fileName,
+        // Native require must return registration data without executing or globally registering the capsule.
+        format: 'commonjs-registration',
+        sourcemap,
+        // Bind every compile-time chunk edge to the same logical identity understood by transport and SystemJS.
+        resolveReference(reference, kind) {
+            return resolveCapsuleReference(chunk.fileName, reference, kind);
+        }
+    });
+}
+/** Canonicalizes physical chunk paths while preserving runtime-computed and package-like dynamic IDs. */
+function resolveCapsuleReference(fileName, reference, kind) {
+    if (kind === 'dynamic' && !reference.startsWith('./') && !reference.startsWith('../'))
+        return reference;
+    return resolveLogicalChunkReference(fileName, reference);
 }

package/dist/node/plugins/wx/render/native.d.ts

@@ -1,6 +1,24 @@
 import type { Rolldown } from 'vite';
-import { type AstTransformResult } from '../../../utils/transform.ts';
-/** Renders a native module while activating its statically imported capsules through SystemJS. */
+import type { AstTransformResult } from '../../../utils/transform.ts';
+/**
+ * Materializes one final native/amphibious Rolldown chunk as executable WX CommonJS.
+ *
+ * The transform performs four semantic operations:
+ *
+ * 1. Static ESM imports are hoisted into source-order `require` calls. Named imports remain property reads from the required
+ *    namespace so they observe current values. Default and namespace imports receive Babel-compatible CommonJS interop.
+ * 2. An import whose target owns a capsule entry is not passed to native `require`. It becomes
+ *    `global.System.importSync(logicalChunkId)`, synchronously linking the capsule before the native lifecycle call.
+ * 3. Local exports are published at declaration and mutation points. Imported re-exports use getters, while assignments and
+ *    updates notify every alias without changing expression completion values or accidentally matching shadowed bindings.
+ * 4. ESM top-level `this` becomes `undefined`. Direct imported calls and tags are explicitly unbound so converting an import
+ *    into a namespace property does not introduce a false CommonJS receiver.
+ *
+ * Static dependency loading is emitted before the untouched module body because ESM evaluates dependencies before body
+ * statements regardless of where import declarations appear textually. Generated helper names are allocated against every
+ * source identifier. Source maps use the same range edits when requested; WX development disables them and keeps this path
+ * focused on startup latency.
+ */
 export declare function renderNative({ code, chunk, chunks, sourcemap }: {
     code: string;
     chunk: Rolldown.RenderedChunk;