vite-plugin-taro 0.3.2 → 0.4.0

package/dist/node/plugins/wx/native/native-component-interface.js

@@ -0,0 +1,201 @@
+import path from 'node:path';
+import { RolldownMagicString } from 'rolldown';
+import { parseAst } from 'rolldown/parseAst';
+import { normalizeModuleId } from '../../../utils/modules.js';
+import { clientTaroNativeId } from '../../client/constant.js';
+/** Replaces native component interface calls with source-folder names and returns their static metadata. */
+export function transformNativeComponentInterfaces(code, id, sourcemap) {
+    const moduleId = normalizeModuleId(id);
+    const program = parseAst(code, {
+        astType: 'ts',
+        lang: 'tsx',
+        preserveParens: false,
+        sourceType: 'module'
+    }, moduleId);
+    const declaredInterfaces = collectInterfaceDeclarations(program);
+    const macroImports = collectMacroImports(program);
+    const importedMacroNames = new Set(macroImports.flatMap((item) => item.names));
+    const calls = collectTopLevelMacroCalls(program, importedMacroNames);
+    const replacements = calls.map((call) => {
+        const definition = parseDefinition(call, moduleId, declaredInterfaces, (message) => createTransformError(message, moduleId, code, call.start));
+        return { call, definition };
+    });
+    // This transform-local mutable buffer applies non-overlapping AST edits without regenerating untouched source.
+    const transformed = new RolldownMagicString(code, { filename: moduleId });
+    replacements.forEach(({ call, definition }) => {
+        transformed.overwrite(call.start, call.end, JSON.stringify(path.posix.basename(definition.folder)));
+    });
+    macroImports.forEach(({ declaration }) => {
+        transformed.remove(declaration.start, declaration.end);
+    });
+    return {
+        code: transformed.toString(),
+        map: sourcemap ? createSourceMap(transformed, moduleId) : null,
+        definitions: replacements.map(({ definition }) => definition)
+    };
+}
+/** Normalizes Rolldown's native source-map object to the public plugin source-map shape. */
+function createSourceMap(transformed, moduleId) {
+    const sourceMap = transformed.generateMap({
+        hires: 'boundary',
+        includeContent: true,
+        source: moduleId
+    });
+    return {
+        file: sourceMap.file,
+        mappings: sourceMap.mappings,
+        names: sourceMap.names,
+        sources: sourceMap.sources,
+        sourcesContent: sourceMap.sourcesContent,
+        version: sourceMap.version
+    };
+}
+/** Finds named imports of the compile-time macro and records their local aliases. */
+function collectMacroImports(program) {
+    return program.body.flatMap((statement) => {
+        if (statement.type !== 'ImportDeclaration' || statement.source.value !== clientTaroNativeId) {
+            return [];
+        }
+        const names = statement.specifiers.flatMap((specifier) => {
+            if (specifier.type !== 'ImportSpecifier' || getStaticName(specifier.imported) !== 'defineNativeComponent') {
+                return [];
+            }
+            return [specifier.local.name];
+        });
+        return names.length === 0 ? [] : [{ declaration: statement, names }];
+    });
+}
+/** Collects direct module-level macro calls, excluding calls inside nested scopes. */
+function collectTopLevelMacroCalls(program, importedMacroNames) {
+    return program.body.flatMap((statement) => {
+        if (statement.type === 'ExpressionStatement') {
+            return isImportedMacroCall(statement.expression, importedMacroNames) ? [statement.expression] : [];
+        }
+        if (statement.type === 'ExportDefaultDeclaration') {
+            return isImportedMacroCall(statement.declaration, importedMacroNames) ? [statement.declaration] : [];
+        }
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+        if (declaration?.type !== 'VariableDeclaration') {
+            return [];
+        }
+        return declaration.declarations.flatMap(({ init }) => {
+            return isImportedMacroCall(init, importedMacroNames) ? [init] : [];
+        });
+    });
+}
+/** Matches a direct call to one of the macro's module-level import bindings. */
+function isImportedMacroCall(node, importedMacroNames) {
+    return (node?.type === 'CallExpression' && node.callee.type === 'Identifier' && importedMacroNames.has(node.callee.name));
+}
+/** Parses one native entry loader and its optional TypeScript interface. */
+function parseDefinition(call, moduleId, declaredInterfaces, buildError) {
+    if (call.arguments.length !== 1) {
+        throw buildError('defineNativeComponent() requires exactly one entry loader');
+    }
+    const entryReference = readStaticEntryImport(call.arguments[0]);
+    if (!entryReference) {
+        throw buildError('Native component entry must use () => import(...) with a static relative .js path');
+    }
+    const entryPath = normalizeModuleId(path.resolve(path.dirname(moduleId), entryReference));
+    return {
+        folder: path.posix.dirname(entryPath),
+        entry: path.posix.basename(entryPath, '.js'),
+        fields: readInterfaceFields(call.typeArguments, declaredInterfaces, buildError)
+    };
+}
+/** Collects non-generic local object aliases and interfaces as native template field declarations. */
+function collectInterfaceDeclarations(program) {
+    // This module-local map supports nearby declarations without constructing a TypeScript type-checker program.
+    const declarations = new Map();
+    for (const statement of program.body) {
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+        if (declaration?.type === 'TSTypeAliasDeclaration' &&
+            !declaration.typeParameters &&
+            declaration.typeAnnotation.type === 'TSTypeLiteral') {
+            declarations.set(declaration.id.name, declaration.typeAnnotation.members);
+            continue;
+        }
+        if (declaration?.type === 'TSInterfaceDeclaration' &&
+            !declaration.typeParameters &&
+            declaration.extends.length === 0) {
+            declarations.set(declaration.id.name, declaration.body.body);
+        }
+    }
+    return declarations;
+}
+/** Resolves an inline type or a non-generic object declaration from the current module. */
+function resolveInterfaceMembers(typeNode, declarations) {
+    if (typeNode.type === 'TSTypeLiteral') {
+        return typeNode.members;
+    }
+    if (typeNode.type === 'TSTypeReference' && typeNode.typeName.type === 'Identifier' && !typeNode.typeArguments) {
+        return declarations.get(typeNode.typeName.name);
+    }
+}
+/** Reads native template field names without resolving or validating their TypeScript value types. */
+function readInterfaceFields(typeArguments, declaredInterfaces, buildError) {
+    if (!typeArguments) {
+        return [];
+    }
+    if (typeArguments.params.length !== 1) {
+        throw buildError('Native component interface must be one TypeScript object type');
+    }
+    const firstType = typeArguments.params[0];
+    const members = firstType ? resolveInterfaceMembers(firstType, declaredInterfaces) : undefined;
+    if (!members) {
+        throw buildError('Native component interface must be inline or declared in the same module');
+    }
+    // This local set preserves declaration order while rejecting ambiguous duplicate template fields.
+    const names = new Set();
+    for (const member of members) {
+        if (member.type !== 'TSPropertySignature' && member.type !== 'TSMethodSignature') {
+            throw buildError('Native component interface must contain only static fields');
+        }
+        if (member.computed) {
+            throw buildError('Native component interface contains a computed field');
+        }
+        const name = getStaticName(member.key);
+        if (!name) {
+            throw buildError('Native component interface contains a computed field');
+        }
+        if (names.has(name)) {
+            throw buildError(`Duplicate native component interface field: ${name}`);
+        }
+        names.add(name);
+    }
+    return [...names].filter((name) => name !== 'children');
+}
+/** Reads an identifier or string-literal key. */
+function getStaticName(node) {
+    if (node.type === 'Identifier') {
+        return node.name;
+    }
+    if (node.type === 'Literal' && typeof node.value === 'string') {
+        return node.value;
+    }
+}
+/** Reads a zero-argument entry loader containing one statically resolvable native `.js` import. */
+function readStaticEntryImport(node) {
+    if (node?.type !== 'ArrowFunctionExpression' || node.params.length !== 0 || node.body.type !== 'ImportExpression') {
+        return undefined;
+    }
+    const importExpression = node.body;
+    if (importExpression.source.type !== 'Literal' ||
+        typeof importExpression.source.value !== 'string' ||
+        importExpression.options !== null ||
+        !isLocalJavaScriptEntry(importExpression.source.value)) {
+        return undefined;
+    }
+    return importExpression.source.value;
+}
+/** Limits component entries to JavaScript files reachable from their interface module. */
+function isLocalJavaScriptEntry(entry) {
+    return (entry.startsWith('./') || entry.startsWith('../')) && path.posix.extname(entry) === '.js';
+}
+/** Adds a stable source location to semantic errors reported after parsing. */
+function createTransformError(message, moduleId, code, offset) {
+    const prefix = code.slice(0, offset);
+    const line = prefix.split('\n').length;
+    const column = offset - prefix.lastIndexOf('\n');
+    return new Error(`${message}\n${moduleId}:${line}:${column}`);
+}

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

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

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

@@ -0,0 +1,12 @@
+import { createNativeComponentOutput } from '../native/create-native-component-output.js';
+import { createJsonAssets } from './json.js';
+import { createTemplateAssets } from './templates.js';
+/** Creates every native companion file derived from the final Rolldown bundle. */
+export async function createOutputFiles({ bundle, options, subpackages, getModuleInfo }) {
+    const nativeOutput = await createNativeComponentOutput({ bundle, getModuleInfo });
+    return [
+        ...createJsonAssets({ options, subpackages, nativeComponents: nativeOutput.registrations }),
+        ...createTemplateAssets(bundle, options, nativeOutput.registrations),
+        ...nativeOutput.files
+    ];
+}

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

@@ -0,0 +1,14 @@
+import type { Rolldown } from 'vite';
+import type { JsonObject, VitePluginTaroOptions } from '../../../../options.ts';
+import type { GeneratedSubpackage } from '../placement/placer.ts';
+/** Creates every configured native JSON asset. */
+export declare function createJsonAssets({ options, subpackages, nativeComponents }: {
+    options: VitePluginTaroOptions;
+    subpackages: readonly GeneratedSubpackage[];
+    nativeComponents: readonly {
+        name: string;
+        componentPath: string;
+    }[];
+}): Rolldown.EmittedAsset[];
+/** Serializes one native JSON object with stable formatting. */
+export declare function renderJson(value: JsonObject): string;

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

@@ -0,0 +1,52 @@
+import { createAppConfig } from '../../../utils/project-config.js';
+import { isGeneratedSubpackageFile } from '../placement/plan.js';
+import { toRootRelativePath } from './relative-root.js';
+/** Creates every configured native JSON asset. */
+export function createJsonAssets({ options, subpackages, nativeComponents }) {
+    return [
+        createJsonAsset('app.json', {
+            ...createAppConfig(options),
+            ...(subpackages.length > 0 ? { subPackages: subpackages } : {})
+        }),
+        ...options.pages.map((page) => createJsonAsset(`${page.path}.json`, createPageJson(page, nativeComponents))),
+        createJsonAsset('project.config.json', options.projectConfigJson),
+        ...(options.projectPrivateConfigJson
+            ? [createJsonAsset('project.private.config.json', options.projectPrivateConfigJson)]
+            : []),
+        createJsonAsset('sitemap.json', options.sitemapJson)
+    ];
+}
+/** Creates Page JSON with generated Taro and native component registrations. */
+function createPageJson(page, nativeComponents) {
+    const usingComponents = isJsonObject(page.config.usingComponents) ? page.config.usingComponents : {};
+    // Cross-package components require a placeholder while WeChat downloads their generated subpackage. Paths are
+    // root-absolute, so remove the leading slash before testing the output-relative subpackage prefix.
+    // https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html
+    // https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/placeholder.html
+    const placeholderEntries = nativeComponents.flatMap(({ name, componentPath }) => isGeneratedSubpackageFile(componentPath.slice(1)) ? [[name, 'view']] : []);
+    return {
+        ...page.config,
+        ...(placeholderEntries.length > 0 ? { componentPlaceholder: Object.fromEntries(placeholderEntries) } : {}),
+        usingComponents: {
+            ...usingComponents,
+            ...Object.fromEntries(nativeComponents.map(({ name, componentPath }) => [name, componentPath])),
+            comp: toRootRelativePath(page.path, 'comp')
+        }
+    };
+}
+/** Tests whether a configured JSON value can be merged as an object. */
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Serializes one native JSON object with stable formatting. */
+export function renderJson(value) {
+    return `${JSON.stringify(value, null, 4)}\n`;
+}
+/** Creates one native JSON asset. */
+function createJsonAsset(fileName, value) {
+    return {
+        type: 'asset',
+        fileName,
+        source: renderJson(value)
+    };
+}

package/dist/node/plugins/wx/output/relative-root.d.ts

@@ -0,0 +1,2 @@
+/** Creates a Page-relative path to a file emitted at the wx output root. */
+export declare function toRootRelativePath(pagePath: string, rootFileName: string): string;

package/dist/node/plugins/wx/output/relative-root.js

@@ -0,0 +1,6 @@
+import path from 'node:path';
+/** Creates a Page-relative path to a file emitted at the wx output root. */
+export function toRootRelativePath(pagePath, rootFileName) {
+    const relativePath = path.posix.relative(path.posix.dirname(pagePath), rootFileName);
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}

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

@@ -0,0 +1,7 @@
+import type { Rolldown } from 'vite';
+import type { VitePluginTaroOptions } from '../../../../options.ts';
+/** Creates Taro's shared WeChat templates and native WXML/WXSS companions for every Page. */
+export declare function createTemplateAssets(bundle: Rolldown.OutputBundle, options: VitePluginTaroOptions, nativeComponents: readonly {
+    name: string;
+    fields: readonly string[];
+}[]): Rolldown.EmittedAsset[];

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

@@ -0,0 +1,100 @@
+import { recursiveMerge } from '@tarojs/helper';
+import { Weapp as WxPlatform } from '@tarojs/plugin-platform-weapp';
+import { normalizeModuleId } from '../../../utils/modules.js';
+import { packageRequire } from '../../../utils/packages.js';
+import { renderJson } from './json.js';
+import { toRootRelativePath } from './relative-root.js';
+const taroComponentsModulePath = packageRequire.resolve('@tarojs/plugin-platform-weapp/dist/components-react');
+/** Creates Taro's shared WeChat templates and native WXML/WXSS companions for every Page. */
+export function createTemplateAssets(bundle, options, nativeComponents) {
+    const templateBuilder = createTemplateBuilder();
+    return [
+        createAsset('base.wxml', templateBuilder.buildTemplate(collectTemplateComponentConfig(bundle, nativeComponents))),
+        createAsset('utils.wxs', templateBuilder.buildXScript()),
+        createAsset('comp.wxml', templateBuilder.buildBaseComponentTemplate('.wxml')),
+        createAsset('comp.json', renderJson(createComponentJson())),
+        ...options.pages.flatMap((page) => [
+            createAsset(`${page.path}.wxml`, templateBuilder.buildPageTemplate(toRootRelativePath(page.path, 'base.wxml'), {
+                content: page.config,
+                path: page.path
+            })),
+            createAsset(`${page.path}.wxss`, '')
+        ])
+    ];
+}
+/** Creates the Taro WeChat template builder without invoking its Webpack integration. */
+function createTemplateBuilder() {
+    const platform = new WxPlatform({
+        helper: {
+            recursiveMerge
+        },
+        modifyWebpackChain() { },
+        registerPlatform() { }
+    }, {}, {});
+    platform.modifyTemplate({});
+    return platform.template;
+}
+/** Creates template metadata from reachable Taro hosts and native component JSX fields. */
+function collectTemplateComponentConfig(bundle, nativeComponents) {
+    // This local config accumulates names in output order before the template builder consumes it.
+    const config = {
+        includes: new Set([
+            'view',
+            'catch-view',
+            'static-view',
+            'pure-view',
+            'click-view',
+            'scroll-view',
+            'image',
+            'static-image',
+            'text',
+            'static-text'
+        ]),
+        exclude: new Set(),
+        thirdPartyComponents: new Map(),
+        includeAll: false
+    };
+    const components = findBundleModule(bundle, taroComponentsModulePath);
+    for (const name of components?.renderedExports ?? []) {
+        config.includes.add(toDashed(name));
+    }
+    for (const component of nativeComponents) {
+        config.thirdPartyComponents.set(component.name, new Set(component.fields));
+    }
+    return config;
+}
+/** Finds one module in the final chunk metadata. */
+function findBundleModule(bundle, resolvedId) {
+    const normalizedResolvedId = normalizeModuleId(resolvedId);
+    for (const output of Object.values(bundle)) {
+        if (output.type !== 'chunk') {
+            continue;
+        }
+        const found = Object.entries(output.modules).find(([id]) => normalizeModuleId(id) === normalizedResolvedId);
+        if (found) {
+            return found[1];
+        }
+    }
+}
+/** Converts a React component export to Taro's dashed host-component name. */
+function toDashed(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/** Creates the recursive component configuration expected by Taro's templates. */
+function createComponentJson() {
+    return {
+        component: true,
+        styleIsolation: 'apply-shared',
+        usingComponents: {
+            comp: './comp'
+        }
+    };
+}
+/** Creates one emitted template or style asset. */
+function createAsset(fileName, source) {
+    return {
+        type: 'asset',
+        fileName,
+        source
+    };
+}

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

@@ -0,0 +1,78 @@
+import type { Rolldown } from 'vite';
+import { type ModuleGraph } from './plan.ts';
+/** 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 [];
+};
+/**
+ * Creates the stateful adapter between graph planning and Rolldown's output lifecycle:
+ *
+ * - renderStart analyzes transformed modules before chunking.
+ * - codeSplitting prevents modules assigned to different packages from being merged.
+ * - filename callbacks materialize planned subpackage roots.
+ * - renderChunk derives native loading mode from those physical paths.
+ * - generateBundle reconciles the plan with chunks that survived tree shaking.
+ */
+export declare function createPlacer(): {
+    /** Assigns every transformed module to main or one generated, size-bounded subpackage. */
+    analyze(graph: ModuleGraph): void;
+    /**
+     * Complete Rolldown fragment required to preserve package placement and native entry semantics.
+     *
+     * ```text
+     * native App/Page/Component shell entry
+     *   └─ static import / runtime importSync() ─▶ explicit capsule entry + static closure [main, no TLA]
+     *                                                └─ System.import() ─▶ lazy-a [package A, TLA allowed]
+     *                                                                      └─ static import ─▶ lazy-b [package B]
+     *
+     * name()                              assigns lazy-a and lazy-b to their planned package groups
+     * includeDependenciesRecursively      false: does not pull lazy-b back into package A
+     * preserveEntrySignatures             allows cross-chunk bindings without weakening native entry exports
+     *
+     * package A capsule
+     *   └─ SystemJS dependency ─▶ package B capsule
+     *                                ▲
+     *                                └─ main transport obtains registration with require.async()
+     * ```
+     *
+     * Explicit entries preserve the shell/capsule rendering boundary while their static edge executes synchronously
+     * from main. Once a dynamic boundary is crossed, physical fetches may be asynchronous and modules may use
+     * top-level await. SystemJS still links that complete static lazy graph before execution, even across packages.
+     */
+    rolldownOptions: {
+        output: {
+            /**
+             * Gives every generated subpackage a distinct Rolldown chunk group. Recursive dependency capture must
+             * stay disabled: lazy static dependencies may belong to other subpackages and SystemJS links them
+             * asynchronously.
+             */
+            codeSplitting: {
+                groups: {
+                    name(moduleId: string): string | null;
+                    includeDependenciesRecursively: boolean;
+                }[];
+            };
+            /** Preserves exact native shell paths while hashing transport and explicit capsule entries. */
+            entryFileNames(chunk: Rolldown.PreRenderedChunk): string;
+            /** Converts the planned owner into its physical main or generated subpackage filename template. */
+            chunkFileNames(chunk: Rolldown.PreRenderedChunk): string;
+            assetFileNames: string;
+        };
+        preserveEntrySignatures: 'allow-extension';
+    };
+    /**
+     * Selects loading mode from physical output rather than graph intent. Transport executes in main, so main files
+     * use require() and every generated subpackage file uses require.async().
+     */
+    getLoadMode(chunk: Rolldown.RenderedChunk): 'sync' | 'async';
+    /**
+     * Reconciles planned ownership with final chunks through module IDs. Tree-shaken subpackages disappear naturally,
+     * while roots are deduplicated and sorted before becoming deterministic app.json declarations.
+     */
+    getSubpackages(bundle: Rolldown.OutputBundle): GeneratedSubpackage[];
+};

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

@@ -0,0 +1,145 @@
+import { getWxExecutionKind, isTransportModule } from '../module.js';
+import { createPlacementPlan, getSubpackageName, isGeneratedSubpackageFile, mainPackage } from './plan.js';
+/**
+ * Creates the stateful adapter between graph planning and Rolldown's output lifecycle:
+ *
+ * - renderStart analyzes transformed modules before chunking.
+ * - codeSplitting prevents modules assigned to different packages from being merged.
+ * - filename callbacks materialize planned subpackage roots.
+ * - renderChunk derives native loading mode from those physical paths.
+ * - generateBundle reconciles the plan with chunks that survived tree shaking.
+ */
+export function createPlacer() {
+    // Filename and output callbacks run after analyze and read this immutable plan through their shared closure.
+    let plan = new Map();
+    /**
+     * Reduces module ownership to one package for filename generation. Unknown Rolldown-generated modules default to
+     * main, empty chunks default to main, and a chunk containing multiple known owners is rejected before paths diverge.
+     */
+    function getChunkLocation(chunk) {
+        let location;
+        for (const moduleId of chunk.moduleIds) {
+            const moduleLocation = plan.get(moduleId) ?? mainPackage;
+            if (!location) {
+                location = moduleLocation;
+                continue;
+            }
+            if (!hasSameLocation(location, moduleLocation)) {
+                throw new Error(`wx chunk mixes package owners: ${chunk.moduleIds.join(', ')}`);
+            }
+        }
+        return location ?? mainPackage;
+    }
+    return {
+        /** Assigns every transformed module to main or one generated, size-bounded subpackage. */
+        analyze(graph) {
+            plan = createPlacementPlan(graph);
+        },
+        /**
+         * Complete Rolldown fragment required to preserve package placement and native entry semantics.
+         *
+         * ```text
+         * native App/Page/Component shell entry
+         *   └─ static import / runtime importSync() ─▶ explicit capsule entry + static closure [main, no TLA]
+         *                                                └─ System.import() ─▶ lazy-a [package A, TLA allowed]
+         *                                                                      └─ static import ─▶ lazy-b [package B]
+         *
+         * name()                              assigns lazy-a and lazy-b to their planned package groups
+         * includeDependenciesRecursively      false: does not pull lazy-b back into package A
+         * preserveEntrySignatures             allows cross-chunk bindings without weakening native entry exports
+         *
+         * package A capsule
+         *   └─ SystemJS dependency ─▶ package B capsule
+         *                                ▲
+         *                                └─ main transport obtains registration with require.async()
+         * ```
+         *
+         * Explicit entries preserve the shell/capsule rendering boundary while their static edge executes synchronously
+         * from main. Once a dynamic boundary is crossed, physical fetches may be asynchronous and modules may use
+         * top-level await. SystemJS still links that complete static lazy graph before execution, even across packages.
+         */
+        rolldownOptions: {
+            output: {
+                /**
+                 * Gives every generated subpackage a distinct Rolldown chunk group. Recursive dependency capture must
+                 * stay disabled: lazy static dependencies may belong to other subpackages and SystemJS links them
+                 * asynchronously.
+                 */
+                codeSplitting: {
+                    groups: [
+                        {
+                            name(moduleId) {
+                                const location = plan.get(moduleId);
+                                return location?.kind === 'subpackage' ? getSubpackageName(location.root) : null;
+                            },
+                            // Do not let Rolldown pull a lazy group's static closure into one chunk. Past the nested dynamic
+                            // boundary, transport may obtain registrations from several packages asynchronously before
+                            // SystemJS links and executes the original graph, including cycles and top-level await.
+                            includeDependenciesRecursively: false
+                        }
+                    ]
+                },
+                // strictExecutionOrder deliberately has no plugin default. When an application enables it through normal
+                // Rolldown output options, the generated helper runtime becomes amphibious: CommonJS evaluates it once and
+                // transport publishes that cached namespace to SystemJS.
+                /** Preserves exact native shell paths while hashing transport and explicit capsule entries. */
+                entryFileNames(chunk) {
+                    return getWxExecutionKind(chunk) === 'native' && !isTransportModule(chunk)
+                        ? '[name]'
+                        : 'assets/[name]-[hash].js';
+                },
+                /** Converts the planned owner into its physical main or generated subpackage filename template. */
+                chunkFileNames(chunk) {
+                    const location = getChunkLocation(chunk);
+                    if (location.kind === 'main') {
+                        return 'assets/[name]-[hash].js';
+                    }
+                    // The containing subpackage already supplies a stable identity. Do not leak the Rolldown group name
+                    // into every physical chunk filename; content identity alone is sufficient beneath that root.
+                    return `${location.root}/assets/[hash].js`;
+                },
+                // Keep generic assets independent of stylesheet conventions. The CSS adapter sees Tailwind's final
+                // mutation and owns the exact global `app.wxss` identity without confusing native Page companions.
+                assetFileNames: 'assets/[name]-[hash][extname]'
+            },
+            // Rolldown rejects strict entry signatures when code-splitting groups disable recursive dependency capture.
+            // allow-extension retains required native-entry exports while permitting the extra cross-chunk bindings used
+            // to split lazy static closures across physical packages.
+            preserveEntrySignatures: 'allow-extension'
+        },
+        /**
+         * Selects loading mode from physical output rather than graph intent. Transport executes in main, so main files
+         * use require() and every generated subpackage file uses require.async().
+         */
+        getLoadMode(chunk) {
+            return isGeneratedSubpackageFile(chunk.fileName) ? 'async' : 'sync';
+        },
+        /**
+         * Reconciles planned ownership with final chunks through module IDs. Tree-shaken subpackages disappear naturally,
+         * while roots are deduplicated and sorted before becoming deterministic app.json declarations.
+         */
+        getSubpackages(bundle) {
+            const emittedSubpackageRoots = new Set();
+            for (const output of Object.values(bundle)) {
+                if (output.type !== 'chunk') {
+                    continue;
+                }
+                for (const moduleId of output.moduleIds) {
+                    const location = plan.get(moduleId);
+                    if (location?.kind === 'subpackage') {
+                        emittedSubpackageRoots.add(location.root);
+                    }
+                }
+            }
+            return [...emittedSubpackageRoots].sort().map((root) => ({
+                name: getSubpackageName(root),
+                root,
+                pages: []
+            }));
+        }
+    };
+}
+/** Compares main by discriminant and generated subpackages by their unique physical root. */
+function hasSameLocation(left, right) {
+    return left.kind === 'main' ? right.kind === 'main' : right.kind === 'subpackage' && left.root === right.root;
+}