vite-plugin-taro 0.6.0 → 0.6.2

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

@@ -0,0 +1,147 @@
+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.
+ */
+export const placementRolldownOptions = {
+    /**
+     * Output-stage naming remains under Rolldown's ownership. These options establish physical candidates and hash
+     * 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:
+         * application chunks import its content-hashed path, so it belongs with hashed runtime/capsule entries. `[hash]`
+         * remains a Rolldown placeholder here and is resolved only after renderChunk transforms finish.
+         */
+        entryFileNames(chunk) {
+            return getWxExecutionKind(chunk) === 'native' && !isTransportModule(chunk)
+                ? '[name]'
+                : 'assets/[name]-[hash].js';
+        },
+        /**
+         * Leaves chunk identity and collision handling entirely to Rolldown. This package-neutral physical pattern deliberately
+         * contains no LTHP owner; generateBundle adds only the selected package root to the existing Rolldown filename.
+         */
+        chunkFileNames: 'assets/[name]-[hash].js',
+        /**
+         * Emits generic Rolldown assets under one collision-resistant hashed namespace. Native-component folders are not
+         * governed by this option: createNativeComponentOutput preserves their required relative filenames and relocates the
+         * complete folder beside its owning JavaScript chunk after LTHP finalization.
+         */
+        assetFileNames: 'assets/[name]-[hash][extname]'
+    },
+    /**
+     * Keeps every native entry's required exports while allowing Rolldown to add cross-chunk bindings created by natural code
+     * splitting. `strict` can reject those extensions; `exports-only` can merge away native boundaries; `allow-extension`
+     * preserves the shell/capsule contract without forcing source-module placement groups.
+     */
+    preserveEntrySignatures: 'allow-extension'
+};
+/**
+ * Creates the `vpt:wx-placer` lifecycle owner:
+ *
+ * 1. Its config hook installs package-neutral Rolldown names and entry-signature semantics.
+ * 2. `renderStart` atomically starts a generation in `awaiting-chunks`; no stale placement remains reachable.
+ * 3. Its first pre-order `renderChunk` creates one immutable LTHP placement from the complete tree-shaken graph.
+ * 4. `vpt:wx` asks this plugin only for package ownership, physical relocation, and native loading mode.
+ * 5. Its pre-order `generateBundle` assigns each OutputChunk its package-qualified filename and publishes app.json declarations.
+ *
+ * The discriminated state is the only generation-local mutation: `idle → awaiting-chunks → planned → finalized`. Each hook
+ * performs one whole-state transition, so stale graph state, duplicate planning, and partially reset generations are
+ * unrepresentable.
+ */
+export function createWxPlacementPlugin() {
+    // This one mutable cell is the output-generation state machine described above; hooks replace it atomically by phase.
+    let state = { phase: 'idle' };
+    function requirePlacement() {
+        if (state.phase === 'idle' || state.phase === 'awaiting-chunks') {
+            throw new Error('wx placement is unavailable before Rolldown exposes the final chunk graph');
+        }
+        return state.placement;
+    }
+    return {
+        name: 'vpt:wx-placer',
+        config() {
+            return {
+                build: {
+                    rolldownOptions: placementRolldownOptions
+                }
+            };
+        },
+        renderStart() {
+            state = { phase: 'awaiting-chunks' };
+        },
+        renderChunk: {
+            order: 'pre',
+            handler(_code, _chunk, _outputOptions, meta) {
+                if (state.phase === 'planned') {
+                    return;
+                }
+                if (state.phase !== 'awaiting-chunks') {
+                    throw new Error(`wx placement received final chunks during the ${state.phase} phase`);
+                }
+                state = {
+                    phase: 'planned',
+                    placement: createPlacement({
+                        chunks: meta.chunks,
+                        getAdditionalModuleBytes: (moduleId) => getNativeComponentAssetBytes(this.getModuleInfo(moduleId)?.meta)
+                    })
+                };
+            }
+        },
+        generateBundle: {
+            order: 'pre',
+            handler(_outputOptions, bundle) {
+                const placement = requirePlacement();
+                state = {
+                    phase: 'finalized',
+                    placement: placement,
+                    subpackages: placement.finalize(bundle)
+                };
+            }
+        },
+        getPackageLocation(chunk) {
+            return requirePlacement().getPackageLocation(chunk);
+        },
+        getPhysicalChunkId(chunk) {
+            return requirePlacement().getPhysicalChunkId(chunk);
+        },
+        getLoadMode(chunk) {
+            return requirePlacement().getLoadMode(chunk);
+        },
+        getSubpackages() {
+            if (state.phase !== 'finalized') {
+                throw new Error('wx subpackages are unavailable before output finalization');
+            }
+            return state.subpackages;
+        }
+    };
+}

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

@@ -2,11 +2,10 @@ 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 { getNativeComponentAssetBytes } from './native/native-component-assets.js';
 import { createOutputFiles } from './output/files.js';
-import { createPlacer } from './placement/placer.js';
+import { createWxPlacementPlugin } from './placer/placer.js';
 import { renderCapsule } from './render/capsule.js';
 import { renderNative } from './render/native.js';
 import { materializeTransport } from './render/transport.js';
@@ -17,15 +16,16 @@ export function createWxTargetPlugins(options) {
     const resolver = createResolver(options);
     // Reuse the resolver instance's ordered application subset. Rolldown's complete input also contains bootstrap, transport,
     // shell, and component entries; entry membership alone cannot recover which roots define the App/Page CSS cascade.
+    const placement = createWxPlacementPlugin();
     return [
+        placement,
         createWxStylePlugins(),
-        createWxPlugin(options, resolver),
+        createWxPlugin(options, resolver, placement),
         createWxDevelopmentPlugin(options, resolver.applicationEntryIds)
     ];
 }
 /** Configures the complete wx target build pipeline. */
-function createWxPlugin(options, resolver) {
-    const placer = createPlacer();
+function createWxPlugin(options, resolver, placement) {
     return {
         name: 'vpt:wx',
         config(_config, _env) {
@@ -54,7 +54,8 @@ function createWxPlugin(options, resolver) {
                     assetsInlineLimit: 0,
                     target: esTarget,
                     rolldownOptions: {
-                        ...placer.rolldownOptions,
+                        // The dedicated vpt:wx-placer plugin owns output naming and entry-signature semantics. This plugin owns
+                        // only the closed named input set of native shells, lifecycle capsules, bootstrap, and transport entries.
                         input: resolver.input
                     }
                 }
@@ -78,16 +79,10 @@ function createWxPlugin(options, resolver) {
                 return resolver.specialize(code, id, sourcemap);
             }
         },
-        renderStart() {
-            placer.analyze({
-                moduleIds: this.getModuleIds(),
-                getModuleInfo: (moduleId) => this.getModuleInfo(moduleId),
-                getAdditionalModuleBytes: (info) => getNativeComponentAssetBytes(info.meta)
-            });
-        },
         renderChunk: {
             order: 'post',
             async handler(code, chunk, outputOptions, meta) {
+                // vpt:wx-placer runs first and has already created immutable placement from this complete chunk graph.
                 const executionKind = getWxExecutionKind(chunk);
                 const sourcemap = Boolean(outputOptions.sourcemap);
                 if (executionKind === 'capsule') {
@@ -101,7 +96,8 @@ function createWxPlugin(options, resolver) {
                         code: native.code,
                         transportChunk: chunk,
                         chunks: meta.chunks,
-                        getLoadMode: placer.getLoadMode,
+                        getLoadMode: placement.getLoadMode,
+                        getPhysicalChunkId: placement.getPhysicalChunkId,
                         sourcemap
                     });
                 }
@@ -117,12 +113,16 @@ function createWxPlugin(options, resolver) {
              */
             order: 'post',
             async handler(_, bundle) {
-                const subpackages = placer.getSubpackages(bundle);
+                // LTHP joins OutputChunks to their preliminary logical IDs and assigns Rolldown-owned physical filenames.
+                // createOutputFiles then observes those paths to relocate native component folders, emit placeholders, and
+                // declare only surviving package roots in app.json. No JavaScript chunk is manually emitted or copied.
+                const subpackages = placement.getSubpackages();
                 const outputFiles = await createOutputFiles({
                     bundle,
                     options,
                     subpackages,
-                    getModuleInfo: (moduleId) => this.getModuleInfo(moduleId)
+                    getModuleInfo: (moduleId) => this.getModuleInfo(moduleId),
+                    getPackageLocation: placement.getPackageLocation
                 });
                 outputFiles.forEach((file) => {
                     this.emitFile(file);

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;