vite-plugin-taro 0.5.16 → 0.6.1

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

@@ -0,0 +1,60 @@
+import type { Plugin, Rolldown } from 'vite';
+import { type GeneratedSubpackage, type PackageLocation } from './placement.ts';
+export type { GeneratedSubpackage, Placement } from './placement.ts';
+/** Placement services consumed by the later `vpt:wx` rendering and output hooks. */
+export type WxPlacementPlugin = Plugin & Readonly<{
+    getPackageLocation(chunk: Rolldown.RenderedChunk | Rolldown.OutputChunk): PackageLocation;
+    getPhysicalChunkId(chunk: Rolldown.RenderedChunk): string;
+    getLoadMode(chunk: Rolldown.RenderedChunk): 'sync' | 'async';
+    getSubpackages(): readonly GeneratedSubpackage[];
+}>;
+/**
+ * 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 declare 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: {
+        /**
+         * 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: Rolldown.PreRenderedChunk): string;
+        /**
+         * 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: string;
+        /**
+         * 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: string;
+    };
+    /**
+     * 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 declare function createWxPlacementPlugin(): WxPlacementPlugin;

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

@@ -0,0 +1,123 @@
+import { getWxExecutionKind, isTransportModule } from '../module.js';
+import { getNativeComponentAssetBytes } from '../native/native-component-assets.js';
+import { createPlacement } from './placement.js';
+/**
+ * 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: {
+        /**
+         * 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.d.ts

@@ -1,4 +1,4 @@
 import type { PluginOption } from 'vite';
-import type { VitePluginTaroOptions } from '../../../options.ts';
+import type { VptOptions } from '../../../options.ts';
 /** Creates the complete plugin set for the wx target. */
-export declare function createWxTargetPlugins(options: VitePluginTaroOptions): PluginOption[];
+export declare function createWxTargetPlugins(options: VptOptions): PluginOption[];

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

@@ -4,9 +4,8 @@ import { clientTaroNativeId } from '../client/constant.js';
 import { createWxDevelopmentPlugin } from './dev/plugins.js';
 import { getWxExecutionKind, isTransportModule } from './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-wrapper.js

@@ -1,5 +1,5 @@
 import { types } from '@babel/core';
-import { resolveChunkReference } from '../../../utils/modules.js';
+import { resolveLogicalChunkReference } from '../chunk-path.js';
 /** Wraps System.register as an inert CommonJS capsule tuple with canonical final dependency IDs. */
 export function wrapCapsulePlugin(fileName) {
     return {
@@ -54,11 +54,11 @@ function canonicalizeStaticReference(reference, fileName) {
     if (!types.isStringLiteral(reference)) {
         throw new Error(`Expected a literal System.register dependency in ${fileName}`);
     }
-    reference.value = resolveChunkReference(fileName, reference.value);
+    reference.value = resolveLogicalChunkReference(fileName, reference.value);
 }
 /** Resolves application literals while preserving runtime-computed IDs injected by the development runtime. */
 function canonicalizeDynamicReference(reference, fileName) {
     if (types.isStringLiteral(reference) && (reference.value.startsWith('./') || reference.value.startsWith('../'))) {
-        reference.value = resolveChunkReference(fileName, reference.value);
+        reference.value = resolveLogicalChunkReference(fileName, reference.value);
     }
 }

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

@@ -1,7 +1,7 @@
 import { types } from '@babel/core';
 import transformModulesCommonjs from '@babel/plugin-transform-modules-commonjs';
-import { resolveChunkReference } from '../../../utils/modules.js';
 import { transformWithBabel } from '../../../utils/transform.js';
+import { resolveLogicalChunkReference, resolvePhysicalChunkReference } from '../chunk-path.js';
 import { getWxEntryRole } from '../module.js';
 /** Renders a native module while activating its statically imported capsules through SystemJS. */
 export function renderNative({ code, chunk, chunks, sourcemap }) {
@@ -17,8 +17,8 @@ function connectNativeCapsulesPlugin(fileName, chunks) {
                 if (!reference.startsWith('./') && !reference.startsWith('../')) {
                     return;
                 }
-                const chunkId = resolveChunkReference(fileName, reference);
-                const importedChunk = chunks[chunkId];
+                const physicalChunkId = resolvePhysicalChunkReference(fileName, reference);
+                const importedChunk = chunks[physicalChunkId];
                 if (!importedChunk || getWxEntryRole(importedChunk) !== 'capsule') {
                     return;
                 }
@@ -26,12 +26,12 @@ function connectNativeCapsulesPlugin(fileName, chunks) {
                 if (importPath.node.specifiers.length !== 1 ||
                     !specifier ||
                     types.isImportNamespaceSpecifier(specifier)) {
-                    throw new Error(`Expected one capsule value import from ${chunkId} in ${fileName}`);
+                    throw new Error(`Expected one capsule value import from ${physicalChunkId} in ${fileName}`);
                 }
                 const imported = types.isImportDefaultSpecifier(specifier)
                     ? types.identifier('default')
                     : specifier.imported;
-                const importedConfig = types.memberExpression(createSyncImport(chunkId), types.cloneNode(imported), types.isStringLiteral(imported));
+                const importedConfig = types.memberExpression(createSyncImport(resolveLogicalChunkReference(fileName, reference)), types.cloneNode(imported), types.isStringLiteral(imported));
                 importPath.replaceWith(types.variableDeclaration('const', [
                     types.variableDeclarator(types.cloneNode(specifier.local), importedConfig)
                 ]));

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

@@ -1,17 +1,21 @@
 import type { Rolldown } from 'vite';
 import { type AstTransformResult } from '../../../utils/transform.ts';
 /**
- * Materializes transport while Rolldown's preliminary hash placeholders are still active, so every injected physical
- * reference participates in final hash calculation instead of changing code after its filename has been fixed.
+ * Materializes transport while Rolldown's preliminary hash placeholders are still active. Each switch case deliberately has
+ * two IDs: the package-neutral preliminary filename without its `assets/` directory becomes the SystemJS registration
+ * identity, while the LTHP-selected assets/package-qualified filename becomes the literal native require path. Rolldown
+ * substitutes both hashes after this transform, so the
+ * generated transport code and its own content hash describe the exact files that `generateBundle` later materializes.
  *
  * This intentionally creates broad hash invalidation: changing one capsule can rename transport, then bootstrap, then
  * chunks that import bootstrap. A Mini Program ships one application package rather than independently cached HTTP
  * chunks, so honest content hashes and automatic graph linking are more valuable than minimizing that hash fan-out.
  */
-export declare function materializeTransport({ code, transportChunk, chunks, getLoadMode, sourcemap }: {
+export declare function materializeTransport({ code, transportChunk, chunks, getLoadMode, getPhysicalChunkId, sourcemap }: {
     code: string;
     transportChunk: Rolldown.RenderedChunk;
     chunks: Readonly<Record<string, Rolldown.RenderedChunk>>;
     getLoadMode(chunk: Rolldown.RenderedChunk): 'sync' | 'async';
+    getPhysicalChunkId?: (chunk: Rolldown.RenderedChunk) => string;
     sourcemap?: boolean;
 }): Promise<AstTransformResult>;

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

@@ -1,19 +1,24 @@
 import path from 'node:path';
 import { types } from '@babel/core';
 import { replaceWithAst } from '../../../utils/transform.js';
+import { toLogicalChunkId } from '../chunk-path.js';
 import { getWxExecutionKind } from '../module.js';
-const transportPlaceholder = '__VITE_PLUGIN_TARO_TRANSPORT__';
+const transportPlaceholder = '__VPT_TRANSPORT__';
 const moduleIdParameter = 'moduleId';
 const exportBindingParameter = 'exportBinding';
 /**
- * Materializes transport while Rolldown's preliminary hash placeholders are still active, so every injected physical
- * reference participates in final hash calculation instead of changing code after its filename has been fixed.
+ * Materializes transport while Rolldown's preliminary hash placeholders are still active. Each switch case deliberately has
+ * two IDs: the package-neutral preliminary filename without its `assets/` directory becomes the SystemJS registration
+ * identity, while the LTHP-selected assets/package-qualified filename becomes the literal native require path. Rolldown
+ * substitutes both hashes after this transform, so the
+ * generated transport code and its own content hash describe the exact files that `generateBundle` later materializes.
  *
  * This intentionally creates broad hash invalidation: changing one capsule can rename transport, then bootstrap, then
  * chunks that import bootstrap. A Mini Program ships one application package rather than independently cached HTTP
  * chunks, so honest content hashes and automatic graph linking are more valuable than minimizing that hash fan-out.
  */
-export async function materializeTransport({ code, transportChunk, chunks, getLoadMode, sourcemap = true }) {
+export async function materializeTransport({ code, transportChunk, chunks, getLoadMode, getPhysicalChunkId = (chunk) => chunk.fileName, sourcemap = true }) {
+    const physicalTransportId = getPhysicalChunkId(transportChunk);
     // Babel constructs and safely serializes an expression shaped like:
     // (moduleId) => {
     //     switch (moduleId) {
@@ -28,12 +33,16 @@ export async function materializeTransport({ code, transportChunk, chunks, getLo
         .sort((left, right) => left.chunk.fileName.localeCompare(right.chunk.fileName))
         .map(({ chunk, kind }) => {
         const loadMode = getLoadMode(chunk);
+        const logicalChunkId = toLogicalChunkId(chunk.fileName);
+        // Only native loading crosses the logical/physical boundary and receives the assets/package-qualified path.
+        const physicalChunkId = getPhysicalChunkId(chunk);
         if (kind === 'amphibious' && loadMode !== 'sync') {
             throw new Error(`Amphibious wx module must be in the main package: ${chunk.fileName}`);
         }
         return createTransportCase({
-            chunkId: chunk.fileName,
-            transportFileName: transportChunk.fileName,
+            chunkId: logicalChunkId,
+            transportFileName: physicalTransportId,
+            physicalChunkId: physicalChunkId,
             loadMode,
             kind
         });
@@ -58,9 +67,9 @@ function getTransportedChunks(chunks) {
     }
     return transportedChunks;
 }
-/** Creates one canonical-ID switch case while keeping its native require argument literal. */
-function createTransportCase({ chunkId, transportFileName, loadMode, kind }) {
-    const requirePath = toNativeRequirePath(transportFileName, chunkId);
+/** Creates one logical-ID switch case while keeping its physical native require argument literal. */
+function createTransportCase({ chunkId, transportFileName, loadMode, kind, physicalChunkId }) {
+    const requirePath = toNativeRequirePath(transportFileName, physicalChunkId);
     const requireCallee = loadMode === 'sync'
         ? types.identifier('require')
         : types.memberExpression(types.identifier('require'), types.identifier('async'));

package/dist/node/plugins/wx/resolve/resolver.d.ts

@@ -1,6 +1,6 @@
-import type { VitePluginTaroOptions } from '../../../../options.ts';
+import type { VptOptions } from '../../../../options.ts';
 /** Creates the resolver and source specializer for the wx module graph. */
-export declare function createResolver(options: VitePluginTaroOptions): {
+export declare function createResolver(options: VptOptions): {
     resolveId(id: string, importer: string | undefined, projectRoot: string): string | undefined;
     specialize(code: string, id: string, sourcemap?: boolean): Promise<import("../../../utils/transform.ts").AstTransformResult> | undefined;
     applicationEntryIds: string[];

package/dist/node/plugins/wx/resolve/specialize-bootstrap.d.ts

@@ -1,9 +1,9 @@
-import type { JsonObject } from '../../../../options.ts';
+import type { VptJsonObject } from '../../../../options.ts';
 import { type AstTransformResult } from '../../../utils/transform.ts';
 /** Specializes the amphibious bootstrap with the shared App configuration. */
 export declare function specializeBootstrap({ code, id, appConfig, sourcemap }: {
     code: string;
     id: string;
-    appConfig: JsonObject;
+    appConfig: VptJsonObject;
     sourcemap?: boolean;
 }): Promise<AstTransformResult>;

package/dist/node/plugins/wx/resolve/specialize-bootstrap.js

@@ -1,6 +1,6 @@
 import { types } from '@babel/core';
 import { replaceWithAst } from '../../../utils/transform.js';
-const appConfigPlaceholder = '__VITE_PLUGIN_TARO_APP_CONFIG__';
+const appConfigPlaceholder = '__VPT_APP_CONFIG__';
 /** Specializes the amphibious bootstrap with the shared App configuration. */
 export function specializeBootstrap({ code, id, appConfig, sourcemap = true }) {
     return replaceWithAst(code, id, {

package/dist/node/plugins/wx/resolve/specialize-page-capsule.d.ts

@@ -1,9 +1,9 @@
-import type { VitePluginTaroPageOption } from '../../../../options.ts';
+import type { VptPageOption } from '../../../../options.ts';
 import { type AstTransformResult } from '../../../utils/transform.ts';
 /** Specializes the Page capsule for one configured route. */
 export declare function specializePageCapsule({ code, id, page, sourcemap }: {
     code: string;
     id: string;
-    page: VitePluginTaroPageOption;
+    page: VptPageOption;
     sourcemap?: boolean;
 }): Promise<AstTransformResult>;

package/dist/node/plugins/wx/resolve/specialize-page-capsule.js

@@ -1,7 +1,7 @@
 import { types } from '@babel/core';
 import { replaceWithAst } from '../../../utils/transform.js';
-const pagePathPlaceholder = '__VITE_PLUGIN_TARO_PAGE_PATH__';
-const pageConfigPlaceholder = '__VITE_PLUGIN_TARO_PAGE_CONFIG__';
+const pagePathPlaceholder = '__VPT_PAGE_PATH__';
+const pageConfigPlaceholder = '__VPT_PAGE_CONFIG__';
 /** Specializes the Page capsule for one configured route. */
 export function specializePageCapsule({ code, id, page, sourcemap = true }) {
     return replaceWithAst(code, id, {

package/dist/node/utils/modules.d.ts

@@ -6,8 +6,6 @@ type PageComponentPathOptions = {
     pagePath: string;
     projectRoot: string;
 };
-/** Resolves a final relative reference to the canonical output chunk ID used by the WX module registry. */
-export declare function resolveChunkReference(importerChunkId: string, reference: string): string;
 /** Resolves the source file for the configured App component. */
 export declare function resolveAppComponentPath({ appPath, projectRoot }: AppComponentPathOptions): string;
 /** Resolves the source file for one configured Page component. */

package/dist/node/utils/modules.js

@@ -1,12 +1,5 @@
 import path from 'node:path';
 import { normalizePath } from 'vite';
-/** Resolves a final relative reference to the canonical output chunk ID used by the WX module registry. */
-export function resolveChunkReference(importerChunkId, reference) {
-    if (!reference.startsWith('./') && !reference.startsWith('../')) {
-        throw new Error(`Expected a relative chunk reference in ${importerChunkId}: ${reference}`);
-    }
-    return path.posix.join(path.posix.dirname(importerChunkId), reference);
-}
 /** Resolves the source file for the configured App component. */
 export function resolveAppComponentPath({ appPath, projectRoot }) {
     return path.resolve(projectRoot, appPath);

package/dist/node/utils/project-config.d.ts

@@ -1,3 +1,3 @@
-import type { JsonObject, VitePluginTaroOptions } from '../../options.ts';
+import type { VptJsonObject, VptOptions } from '../../options.ts';
 /** Creates shared App configuration with configured Page order as the authoritative value. */
-export declare function createAppConfig(options: VitePluginTaroOptions): JsonObject;
+export declare function createAppConfig(options: VptOptions): VptJsonObject;

package/dist/node/vpt.d.ts

@@ -0,0 +1,4 @@
+import type { PluginOption } from 'vite';
+import type { VptOptions } from '../options.ts';
+/** Creates the Vite plugins for one Taro target. */
+export default function vpt(options: VptOptions): PluginOption[];

package/dist/node/{vite-plugin.js → vpt.js}

@@ -4,7 +4,7 @@ import { createConditionalDirectivePlugin } from './plugins/conditional/conditio
 import { createH5TargetPlugins } from './plugins/h5/plugins.js';
 import { createWxTargetPlugins } from './plugins/wx/plugins.js';
 /** Creates the Vite plugins for one Taro target. */
-export default function vitePluginTaro(options) {
+export default function vpt(options) {
     return [
         createConditionalDirectivePlugin(options.target),
         createClientTaroPlugin(options.target),

package/dist/options.d.ts

@@ -1,20 +1,72 @@
 /** A JSON object used by generated target configs. */
-export type JsonObject = Record<string, unknown>;
+export type VptJsonObject = Record<string, unknown>;
 /** Build target handled by this plugin. */
-export type VitePluginTaroTarget = 'wx' | 'h5';
+export type VptTarget = 'wx' | 'h5';
 /** Configures one Taro page. */
-export type VitePluginTaroPageOption = {
-    /** Taro route and output path without a file extension. */
+export type VptPageOption = {
+    /**
+     * Taro route and output path without a file extension.
+     *
+     * The plugin resolves the page component from `src/${path}.tsx`, relative to the Vite project root. For example,
+     * `pages/home/index` resolves to `src/pages/home/index.tsx` and is emitted under `pages/home/index` for `wx`.
+     */
     path: string;
-    config: JsonObject;
+    /**
+     * Target-independent Taro page configuration.
+     *
+     * For `wx`, these values form the generated `<path>.json`; the plugin augments `usingComponents` with its generated
+     * component registrations. For `h5`, the values are added to the corresponding Taro router entry.
+     */
+    config: VptJsonObject;
 };
-/** Configures the Vite Taro plugin. */
-export interface VitePluginTaroOptions {
-    target: VitePluginTaroTarget;
+/** Configures vpt for one build target. */
+export interface VptOptions {
+    /**
+     * Platform produced by the current Vite invocation.
+     *
+     * Use `wx` to emit a WeChat Mini Program or `h5` to emit a browser application. The selected target controls Taro
+     * module resolution, conditional compilation, runtime bootstrapping, style processing, and output generation.
+     */
+    target: VptTarget;
+    /**
+     * Source module that default-exports the root React application component.
+     *
+     * Relative paths are resolved from Vite's project root, for example `src/app.tsx`. The component wraps the active
+     * page through its `children` prop and is the appropriate place to import application-wide styles.
+     */
     app: string;
-    pages: VitePluginTaroPageOption[];
-    appJson: JsonObject;
-    projectConfigJson: JsonObject;
-    projectPrivateConfigJson?: JsonObject;
-    sitemapJson: JsonObject;
+    /**
+     * Complete ordered list of application pages.
+     *
+     * The declared order becomes the `pages` order in the generated `app.json`, the H5 route order, and the Page order
+     * in the application style cascade. Each Page source is resolved according to its `path`.
+     */
+    pages: VptPageOption[];
+    /**
+     * Target-independent Taro application configuration.
+     *
+     * For `wx`, these values form the generated `app.json`. For `h5`, they configure the Taro application and router.
+     * The plugin always derives `pages` from {@link pages}; caller-provided `pages`, `subPackages`, and `subpackages`
+     * values are discarded because the build pipeline owns page order and generated package placement.
+     */
+    appJson: VptJsonObject;
+    /**
+     * WeChat DevTools project configuration written to `project.config.json` without merging.
+     *
+     * This option is required so one configuration shape can be shared between targets, but it is only emitted for a
+     * `wx` build and is ignored for `h5`.
+     */
+    projectConfigJson: VptJsonObject;
+    /**
+     * Local WeChat DevTools overrides written to `project.private.config.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    projectPrivateConfigJson?: VptJsonObject;
+    /**
+     * WeChat Mini Program indexing rules written to `sitemap.json` without merging.
+     *
+     * The file is emitted only when this value is provided for a `wx` build. It is ignored for `h5`.
+     */
+    sitemapJson?: VptJsonObject;
 }

package/dist/runtime/h5/app.js

@@ -5,9 +5,9 @@ import ReactDOM from 'react-dom/client';
 // @ts-expect-error: The H5 build resolves this private App component.
 import AppComponent from '\0vpt:app-component';
 const browserWindow = window;
-const config = __VITE_PLUGIN_TARO_H5_APP_CONFIG__;
+const config = __VPT_H5_APP_CONFIG__;
 browserWindow.__taroAppConfig = config;
-config.routes = __VITE_PLUGIN_TARO_H5_ROUTES__;
+config.routes = __VPT_H5_ROUTES__;
 const app = createReactApp(AppComponent, React, ReactDOM, config);
 const history = createHashHistory({ window: browserWindow });
 handleAppMount(config, history);

package/dist/runtime/wx/amphibious/bootstrap.js

@@ -2,7 +2,7 @@
 import '../systemjs/system-core.js';
 import { transport } from './transport.js';
 /** Shares one App configuration object between the specialized bootstrap and App capsule. */
-export const appConfig = __VITE_PLUGIN_TARO_APP_CONFIG__;
+export const appConfig = __VPT_APP_CONFIG__;
 // WX has no modulepreload transport. Genuine application import() boundaries retain System.import() and may load
 // asynchronous subpackage or top-level-await graphs through this identity wrapper.
 export const __vitePreload = (load) => load();