vite-plugin-taro 0.6.0 → 0.6.2

package/README.en.md

@@ -36,7 +36,7 @@ Continue with the [Quick Start guide](https://vpt.js.org/guides/quick-start/).
 - [Hot module replacement](https://vpt.js.org/guides/hot-module-replacement/)
 - [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/references/configuration/)
+- [Configuration reference](https://vpt.js.org/guides/configuration/)
 - [Repository management](https://vpt.js.org/references/repository-management/)
 
 ## License

package/README.md

@@ -37,7 +37,7 @@ npm create vite-taro@latest my-app
 - [开发者工具热更新](https://vpt.js.org/guides/hot-module-replacement/)
 - [Skyline 模式](https://vpt.js.org/guides/skyline-mode/)
 - [从 Taro CLI 迁移](https://vpt.js.org/guides/migrate-from-taro/)
-- [配置参考](https://vpt.js.org/references/configuration/)
+- [配置参考](https://vpt.js.org/guides/configuration/)
 - [仓库维护](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.js

@@ -2,7 +2,7 @@ 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 { appCapsulePath, pageCapsulePath, rolldownRuntimeId, taroRuntimePath } from '../module/module.js';
 import { createWxDevHost } from './dev-host.js';
 import { developmentAppWxssFileName } from './hmr-files.js';
 import { createWxReactRefreshTransforms } from './react-refresh.js';

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.
@@ -35,12 +35,26 @@ export function installWxDevOptions({ bundledDev, server, options, hostPlugins }
          * mutating configuredOutput itself would leak development normalization back into the user's resolved Vite config.
          */
         Object.assign(output, configured, {
+            // Development output is overwritten in place after every complete build. Strip hash placeholders from the
+            // configured asset pattern so old files cannot accumulate and native JSON/WXML references remain stable.
             assetFileNames: createStableFileNames(configured.assetFileNames, 'assets/[name][extname]'),
+            // Banners create physical CommonJS edges after graph analysis: App initializes the dev runtime and each Page
+            // consumes the stable patch journal without allowing those host-only files into the application chunk graph.
             banner: createEntryBanner(pageFiles),
+            // Preserve the configured directory/name shape while removing content hashes. Stable chunk paths let DevTools
+            // overwrite executable files and let cumulative HMR patches address one persistent physical module identity.
             chunkFileNames: createStableFileNames(configured.chunkFileNames, 'assets/[name].js'),
+            // Native entry paths are public Mini Program routes (`app.js`, `pages/.../index.js`); development must never hash
+            // or relocate them because DevTools determines App/Page reload behavior from those exact filenames.
             entryFileNames: createStableFileNames(configured.entryFileNames, '[name]'),
+            // Keep ESM until the existing WX renderChunk pipeline classifies each final chunk and converts capsules to
+            // System.register data or native/amphibious entries to CommonJS. Choosing CommonJS here would erase that boundary.
             format: 'es',
+            // Bundled development emits complete physical output repeatedly. Minifying bounds disk transfer and DevTools
+            // compile work; source-level HMR diagnostics still come from Vite/Rolldown before this final output pass.
             minify: true,
+            // DevTools executes physical WX files and HMR applies module factories rather than browser source maps. Disabling
+            // maps avoids extra output files and prevents Vite's Oxc sourcemap transform from touching generated host code.
             sourcemap: false
         });
         /*
@@ -50,9 +64,16 @@ export function installWxDevOptions({ bundledDev, server, options, hostPlugins }
         rolldownOptions.experimental ??= {};
         const existingDevMode = rolldownOptions.experimental.devMode;
         rolldownOptions.experimental.devMode = {
+            // Retain unknown user/forward-compatible devMode fields while the three explicit WX invariants below win.
             ...(typeof existingDevMode === 'object' ? existingDevMode : {}),
+            // Install the WX-adapted self-contained Rolldown runtime. It consumes physical patch journals and reports
+            // acknowledgements/rebuild requests through the host bridge instead of relying on browser globals or sockets.
             implement: await bundleRuntimeSource(),
+            // Produce a complete output graph on the initial build. Lazy per-request compilation cannot establish the closed
+            // App/Page graph, native companions, style sidecars, and build identity required before any patch is admitted.
             lazy: false,
+            // Keep Rolldown's common runtime injection because generated application factories call its module registry and
+            // HMR primitives. Skipping it would leave the custom implementation without the runtime surface it extends.
             skipCommonRuntimeInjection: false
         };
         /*

package/dist/node/plugins/wx/module/chunk-path.d.ts

@@ -0,0 +1,8 @@
+/** Physical directory in which Rolldown writes generated JavaScript chunks inside each native package. */
+export declare const generatedChunkDirectory = "assets";
+/** Projects one Rolldown-owned physical candidate path into the package-neutral SystemJS identity. */
+export declare function toLogicalChunkId(physicalChunkId: string): string;
+/** Resolves one relative Rolldown-generated import to its preliminary physical chunk path. */
+export declare function resolvePhysicalChunkReference(importerChunkId: string, reference: string): string;
+/** Projects one relative Rolldown-generated import into its package-neutral SystemJS identity. */
+export declare function resolveLogicalChunkReference(importerChunkId: string, reference: string): string;

package/dist/node/plugins/wx/module/chunk-path.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+/** Physical directory in which Rolldown writes generated JavaScript chunks inside each native package. */
+export const generatedChunkDirectory = 'assets';
+/** Projects one Rolldown-owned physical candidate path into the package-neutral SystemJS identity. */
+export function toLogicalChunkId(physicalChunkId) {
+    return path.posix.relative(generatedChunkDirectory, physicalChunkId);
+}
+/** Resolves one relative Rolldown-generated import to its preliminary physical chunk path. */
+export function resolvePhysicalChunkReference(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);
+}
+/** Projects one relative Rolldown-generated import into its package-neutral SystemJS identity. */
+export function resolveLogicalChunkReference(importerChunkId, reference) {
+    return toLogicalChunkId(resolvePhysicalChunkReference(importerChunkId, reference));
+}

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/native/create-native-component-output.d.ts

@@ -1,10 +1,12 @@
 import type { Rolldown } from 'vite';
+import type { PackageLocation } from '../placer/placement.ts';
 /** Creates opaque native files and their registrations from each surviving JSX interface module. */
-export declare function createNativeComponentOutput({ bundle, getModuleInfo }: {
+export declare function createNativeComponentOutput({ bundle, getModuleInfo, getPackageLocation }: {
     bundle: Rolldown.OutputBundle;
     getModuleInfo: (moduleId: string) => {
         meta: Rolldown.CustomPluginOptions;
     } | null;
+    getPackageLocation(chunk: Rolldown.OutputChunk): PackageLocation;
 }): Promise<{
     files: Rolldown.EmittedAsset[];
     registrations: {

package/dist/node/plugins/wx/native/create-native-component-output.js

@@ -1,9 +1,8 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { isGeneratedSubpackageFile } from '../placement/plan.js';
 import { getNativeComponentSources } from './native-component-assets.js';
 /** Creates opaque native files and their registrations from each surviving JSX interface module. */
-export async function createNativeComponentOutput({ bundle, getModuleInfo }) {
+export async function createNativeComponentOutput({ bundle, getModuleInfo, getPackageLocation }) {
     // Files and registrations accumulate in final chunk order for deterministic output.
     const files = [];
     const registrations = [];
@@ -11,9 +10,8 @@ export async function createNativeComponentOutput({ bundle, getModuleInfo }) {
         if (output.type !== 'chunk') {
             continue;
         }
-        const packageRoot = isGeneratedSubpackageFile(output.fileName)
-            ? path.posix.dirname(path.posix.dirname(output.fileName))
-            : undefined;
+        const location = getPackageLocation(output);
+        const packageRoot = location.kind === 'subpackage' ? location.root : undefined;
         for (const moduleId of output.moduleIds) {
             const sources = getNativeComponentSources(getModuleInfo(moduleId)?.meta);
             for (const source of sources) {

package/dist/node/plugins/wx/output/files.d.ts

@@ -1,12 +1,13 @@
 import type { Rolldown } from 'vite';
 import type { VptOptions } from '../../../../options.ts';
-import type { GeneratedSubpackage } from '../placement/placer.ts';
+import type { GeneratedSubpackage, PackageLocation } from '../placer/placement.ts';
 /** Creates every compiler-owned WX file derived from the final Rolldown bundle. */
-export declare function createOutputFiles({ bundle, options, subpackages, getModuleInfo }: {
+export declare function createOutputFiles({ bundle, options, subpackages, getModuleInfo, getPackageLocation }: {
     bundle: Rolldown.OutputBundle;
     options: VptOptions;
     subpackages: readonly GeneratedSubpackage[];
     getModuleInfo: (moduleId: string) => {
         meta: Rolldown.CustomPluginOptions;
     } | null;
+    getPackageLocation(chunk: Rolldown.OutputChunk): PackageLocation;
 }): Promise<Rolldown.EmittedFile[]>;

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

@@ -2,8 +2,8 @@ import { createNativeComponentOutput } from '../native/create-native-component-o
 import { createJsonAssets } from './json.js';
 import { createTemplateAssets } from './templates.js';
 /** Creates every compiler-owned WX file derived from the final Rolldown bundle. */
-export async function createOutputFiles({ bundle, options, subpackages, getModuleInfo }) {
-    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo });
+export async function createOutputFiles({ bundle, options, subpackages, getModuleInfo, getPackageLocation }) {
+    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo, getPackageLocation });
     return [
         {
             type: 'asset',

package/dist/node/plugins/wx/output/json.d.ts

@@ -1,6 +1,6 @@
 import type { Rolldown } from 'vite';
 import type { VptJsonObject, VptOptions } from '../../../../options.ts';
-import type { GeneratedSubpackage } from '../placement/placer.ts';
+import { type GeneratedSubpackage } from '../placer/placement.ts';
 /** Creates every configured native JSON asset. */
 export declare function createJsonAssets({ options, subpackages, nativeComponents }: {
     options: VptOptions;

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

@@ -1,5 +1,5 @@
 import { createAppConfig } from '../../../utils/project-config.js';
-import { isGeneratedSubpackageFile } from '../placement/plan.js';
+import { isGeneratedSubpackageFile } from '../placer/placement.js';
 import { toRootRelativePath } from './relative-root.js';
 /** Creates every configured native JSON asset. */
 export function createJsonAssets({ options, subpackages, nativeComponents }) {

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

@@ -0,0 +1,51 @@
+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. */
+    kind: 'subpackage';
+    /** Native subpackage root relative to the Mini Program output directory. */
+    root: string;
+};
+/** Physical package ownership for one final Rolldown chunk. */
+export type PackageLocation = {
+    kind: 'main';
+} | SubpackageLocation;
+/** Native app.json declaration for one generated code-only subpackage. */
+export type GeneratedSubpackage = {
+    /** Stable native alias derived from the generated root hash. */
+    name: string;
+    /** Physical directory containing this subpackage's emitted capsules. */
+    root: string;
+    /** Marks this as a code-only subpackage with no native Page routes. */
+    pages: readonly [];
+};
+/** Immutable ownership and materialization operations for one complete final-chunk graph. */
+export type Placement = Readonly<{
+    getPackageLocation(chunk: Rolldown.RenderedChunk | Rolldown.OutputChunk): PackageLocation;
+    getPhysicalChunkId(chunk: Rolldown.RenderedChunk): string;
+    getLoadMode(chunk: Rolldown.RenderedChunk): 'sync' | 'async';
+    finalize(bundle: Rolldown.OutputBundle): readonly GeneratedSubpackage[];
+}>;
+/**
+ * Applies Load-Transition Hypergraph Partitioning to Rolldown's final preliminary chunk graph:
+ *
+ * 1. Sort preliminary filenames to remove callback and object-enumeration order from every later decision.
+ * 2. Reserve every explicit entry and its complete static closure in main because native startup must load it synchronously.
+ * 3. Treat each dynamic-import edge as one load transition; the target's static closure is that transition's hyperedge.
+ *    Nested dynamic edges remain separate transitions rather than being folded into the parent closure.
+ * 4. Index every lazy chunk by all transitions requiring it. Shared chunks therefore carry global demand rather than being
+ *    assigned according to the first source module or dynamic root that happens to visit them.
+ * 5. Order chunks by transition demand, estimated emitted bytes, then preliminary filename. Place each chunk once into the
+ *    fitting bin with maximum transition overlap, using best-fit remaining capacity only as a tie-breaker.
+ * 6. Hash each bin's sorted preliminary filenames into a deterministic physical package root and return unique ownership.
+ *
+ * Analysis costs the sum of transition static-closure traversals. Packing scans fitting bins and intersects sparse
+ * transition sets; its worst case is O(CBT), while practical graphs have few bins and sparse transition membership.
+ */
+export declare function createPlacement({ chunks, getAdditionalModuleBytes }: {
+    chunks: Readonly<Record<string, Rolldown.RenderedChunk>>;
+    getAdditionalModuleBytes(moduleId: string): number;
+}): Placement;
+/** Tests the plugin-owned output prefix that physically identifies every generated subpackage. */
+export declare function isGeneratedSubpackageFile(fileName: string): boolean;

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

@@ -0,0 +1,245 @@
+import { createHash } from 'node:crypto';
+// Leave headroom below WeChat's 2M subpackage limit for rendered wrappers and native assets.
+export const subpackagePlanningBudget = 1_900_000;
+const generatedSubpackageRootPrefix = 'sub/p_';
+/** Shared main-package value used for every synchronously reachable chunk. */
+const mainPackage = { kind: 'main' };
+/**
+ * Applies Load-Transition Hypergraph Partitioning to Rolldown's final preliminary chunk graph:
+ *
+ * 1. Sort preliminary filenames to remove callback and object-enumeration order from every later decision.
+ * 2. Reserve every explicit entry and its complete static closure in main because native startup must load it synchronously.
+ * 3. Treat each dynamic-import edge as one load transition; the target's static closure is that transition's hyperedge.
+ *    Nested dynamic edges remain separate transitions rather than being folded into the parent closure.
+ * 4. Index every lazy chunk by all transitions requiring it. Shared chunks therefore carry global demand rather than being
+ *    assigned according to the first source module or dynamic root that happens to visit them.
+ * 5. Order chunks by transition demand, estimated emitted bytes, then preliminary filename. Place each chunk once into the
+ *    fitting bin with maximum transition overlap, using best-fit remaining capacity only as a tie-breaker.
+ * 6. Hash each bin's sorted preliminary filenames into a deterministic physical package root and return unique ownership.
+ *
+ * Analysis costs the sum of transition static-closure traversals. Packing scans fitting bins and intersects sparse
+ * transition sets; its worst case is O(CBT), while practical graphs have few bins and sparse transition membership.
+ */
+export function createPlacement({ chunks, getAdditionalModuleBytes }) {
+    const chunkById = new Map(Object.entries(chunks).sort(([left], [right]) => left.localeCompare(right)));
+    const mainChunkIds = findMainChunkIds(chunkById);
+    const transitionsByChunk = collectTransitionsByChunk({ chunks: chunkById, mainChunkIds: mainChunkIds });
+    const placeableChunks = [...chunkById]
+        .filter(([chunkId]) => !mainChunkIds.has(chunkId))
+        .map(([chunkId, chunk]) => ({
+        chunkId: chunkId,
+        estimatedBytes: estimateChunkBytes(chunk) +
+            chunk.moduleIds.reduce((bytes, moduleId) => bytes + getAdditionalModuleBytes(moduleId), 0),
+        transitions: transitionsByChunk.get(chunkId) ?? new Set()
+    }));
+    const subpackages = packChunks({
+        chunks: placeableChunks,
+        planningBudgetBytes: subpackagePlanningBudget
+    }).map(createPackedSubpackage);
+    // This local map accumulates the immutable plan returned to output materialization.
+    const locationByChunk = new Map();
+    for (const chunkId of mainChunkIds) {
+        locationByChunk.set(chunkId, mainPackage);
+    }
+    for (const subpackage of subpackages) {
+        for (const chunkId of subpackage.chunkIds) {
+            locationByChunk.set(chunkId, subpackage);
+        }
+    }
+    function getLocation(chunkId) {
+        const location = locationByChunk.get(chunkId);
+        if (!location) {
+            throw new Error(`wx placement is missing final chunk: ${chunkId}`);
+        }
+        return location;
+    }
+    /** Resolves typed ownership from Rolldown's preliminary physical filename before or after finalization. */
+    function getPackageLocation(chunk) {
+        return getLocation('preliminaryFileName' in chunk ? chunk.preliminaryFileName : chunk.fileName);
+    }
+    return {
+        getPackageLocation: getPackageLocation,
+        /** Adds the planned package root to a physical preliminary path without changing the chunk's SystemJS identity. */
+        getPhysicalChunkId(chunk) {
+            const location = getPackageLocation(chunk);
+            return location.kind === 'main' ? chunk.fileName : `${location.root}/${chunk.fileName}`;
+        },
+        /** Selects the native loading API directly from typed package ownership. */
+        getLoadMode(chunk) {
+            return getPackageLocation(chunk).kind === 'subpackage' ? 'async' : 'sync';
+        },
+        /** Assigns each final chunk's Rolldown-owned physical filename and declares typed owners that survived output. */
+        finalize(bundle) {
+            const outputChunks = Object.values(bundle).filter((output) => output.type === 'chunk');
+            // This local mutable set deduplicates typed package owners that retain at least one final output chunk.
+            const roots = new Set();
+            for (const chunk of outputChunks) {
+                // OutputChunk.fileName contains the resolved content hash. preliminaryFileName preserves the exact physical
+                // candidate with placeholders that identified this chunk when placement was created during renderChunk.
+                const location = getLocation(chunk.preliminaryFileName);
+                if (location.kind !== 'subpackage') {
+                    continue;
+                }
+                // OutputChunk is mutable in generateBundle. Assigning fileName makes Rolldown retain all chunk metadata and
+                // write that same chunk at its physical package path; deleting bundle keys or re-emitting would lose identity.
+                chunk.fileName = `${location.root}/${chunk.fileName}`;
+                roots.add(location.root);
+            }
+            return [...roots].sort().map((root) => ({
+                name: root.slice(root.lastIndexOf('/') + 1),
+                root: root,
+                pages: []
+            }));
+        }
+    };
+}
+/** Keeps every explicit output entry and its complete static chunk closure in main. */
+function findMainChunkIds(chunks) {
+    const mainChunkIds = new Set();
+    // The worklist avoids recursion and visits every eager static edge once.
+    const pending = [...chunks].filter(([, chunk]) => chunk.isEntry).map(([chunkId]) => chunkId);
+    while (pending.length > 0) {
+        const chunkId = pending.pop();
+        if (!chunkId || mainChunkIds.has(chunkId)) {
+            continue;
+        }
+        const chunk = chunks.get(chunkId);
+        if (!chunk) {
+            continue;
+        }
+        mainChunkIds.add(chunkId);
+        pending.push(...chunk.imports);
+    }
+    return mainChunkIds;
+}
+/** Creates every load-transition hyperedge and indexes its static closure by chunk. */
+function collectTransitionsByChunk({ chunks, mainChunkIds }) {
+    const transitionsByChunk = new Map();
+    let transitionId = 0;
+    for (const chunk of chunks.values()) {
+        for (const targetId of [...chunk.dynamicImports].sort()) {
+            if (!chunks.has(targetId) || mainChunkIds.has(targetId)) {
+                continue;
+            }
+            for (const chunkId of collectStaticClosure({
+                rootId: targetId,
+                chunks: chunks,
+                mainChunkIds: mainChunkIds
+            })) {
+                const transitions = transitionsByChunk.get(chunkId) ?? new Set();
+                transitions.add(transitionId);
+                transitionsByChunk.set(chunkId, transitions);
+            }
+            transitionId++;
+        }
+    }
+    return transitionsByChunk;
+}
+/** Collects one transition's static closure; nested dynamic imports remain independent transitions. */
+function collectStaticClosure({ rootId, chunks, mainChunkIds }) {
+    const closure = new Set();
+    // The worklist follows static edges only; the visited set terminates cycles.
+    const pending = [rootId];
+    while (pending.length > 0) {
+        const chunkId = pending.pop();
+        if (!chunkId || closure.has(chunkId) || mainChunkIds.has(chunkId)) {
+            continue;
+        }
+        const chunk = chunks.get(chunkId);
+        if (!chunk) {
+            continue;
+        }
+        closure.add(chunkId);
+        pending.push(...chunk.imports);
+    }
+    return [...closure].sort();
+}
+/** Partitions final chunks by transition overlap before best-fit capacity. */
+function packChunks({ chunks, planningBudgetBytes }) {
+    const bins = [];
+    const orderedChunks = [...chunks].sort(compareChunks);
+    for (const chunk of orderedChunks) {
+        const bin = chunk.estimatedBytes <= planningBudgetBytes
+            ? (findBestBin({ bins: bins, chunk: chunk, planningBudgetBytes: planningBudgetBytes }) ??
+                createBin(bins))
+            : createBin(bins);
+        placeChunk(bin, chunk);
+    }
+    return bins;
+}
+/** Gives globally shared transition demand priority, then size and stable preliminary filename. */
+function compareChunks(left, right) {
+    return (right.transitions.size - left.transitions.size ||
+        right.estimatedBytes - left.estimatedBytes ||
+        left.chunkId.localeCompare(right.chunkId));
+}
+/** Chooses maximum transition overlap, then the fullest fitting package and stable creation order. */
+function findBestBin({ bins, chunk, planningBudgetBytes }) {
+    let best;
+    for (const bin of bins) {
+        if (bin.estimatedBytes + chunk.estimatedBytes > planningBudgetBytes) {
+            continue;
+        }
+        const candidate = {
+            bin: bin,
+            overlap: countOverlap(bin.transitions, chunk.transitions),
+            remainingBytes: planningBudgetBytes - bin.estimatedBytes - chunk.estimatedBytes
+        };
+        if (!best ||
+            candidate.overlap > best.overlap ||
+            (candidate.overlap === best.overlap && candidate.remainingBytes < best.remainingBytes)) {
+            best = candidate;
+        }
+    }
+    return best?.bin;
+}
+/** Counts transition-package incidences removed by one candidate placement. */
+function countOverlap(left, right) {
+    const [smaller, larger] = left.size <= right.size ? [left, right] : [right, left];
+    let overlap = 0;
+    for (const transition of smaller) {
+        if (larger.has(transition)) {
+            overlap++;
+        }
+    }
+    return overlap;
+}
+/** Creates one planner-local mutable package. */
+function createBin(bins) {
+    const bin = {
+        chunkIds: [],
+        estimatedBytes: 0,
+        transitions: new Set()
+    };
+    bins.push(bin);
+    return bin;
+}
+/** Applies one irreversible, non-duplicating final chunk assignment. */
+function placeChunk(bin, chunk) {
+    bin.chunkIds.push(chunk.chunkId);
+    bin.estimatedBytes += chunk.estimatedBytes;
+    for (const transition of chunk.transitions) {
+        bin.transitions.add(transition);
+    }
+}
+/** Estimates final output bytes from tree-shaken modules plus a bounded generated-chunk allowance. */
+function estimateChunkBytes(chunk) {
+    const renderedModuleBytes = Object.values(chunk.modules).reduce((bytes, module) => bytes + (module.code ? Buffer.byteLength(module.code, 'utf8') : 0), 0);
+    const moduleWrapperBytes = chunk.moduleIds.length * 64;
+    const referenceBytes = (chunk.imports.length + chunk.dynamicImports.length) * 32;
+    return renderedModuleBytes + moduleWrapperBytes + referenceBytes + 64;
+}
+/** Freezes membership and derives a stable root from sorted preliminary filenames. */
+function createPackedSubpackage(bin) {
+    const chunkIds = [...bin.chunkIds].sort();
+    const hash = createHash('sha256').update(chunkIds.join('\0')).digest('hex').slice(0, 8);
+    return {
+        kind: 'subpackage',
+        root: `${generatedSubpackageRootPrefix}${hash}`,
+        chunkIds: chunkIds
+    };
+}
+/** Tests the plugin-owned output prefix that physically identifies every generated subpackage. */
+export function isGeneratedSubpackageFile(fileName) {
+    return fileName.startsWith(generatedSubpackageRootPrefix);
+}

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

@@ -0,0 +1,76 @@
+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;
+    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: {
+        /**
+         * 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:
+         * 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;