pixifact 0.18.0 → 0.20.0

package/README.md

@@ -56,4 +56,4 @@ pixifact build --mode production
 
 - Bun
 - PixiJS v8
-- Vite 6 或更高版本
+- Vite 8 或更高版本

package/dist/compiler-node/vite.d.ts

@@ -1,6 +1,8 @@
 import { type Plugin } from 'vite';
 export type PixifactPlatform = 'web' | 'wechat' | 'douyin';
 export interface PixifactPluginOptions {
+    /** Code subpackage names mapped to project-relative TypeScript/JavaScript entries. */
+    codePackages?: Record<string, string>;
     projectRoot?: string | URL;
 }
 export interface PixifactBuildReport {

package/dist/compiler-node/vite.js

@@ -2,6 +2,7 @@ import { access, readFile, readdir, stat } from 'node:fs/promises';
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
 import { loadEnv, } from 'vite';
 import { parsePixifactProjectConfig, pixifactProjectConfigFileName, } from '../project/index.js';
 import { compileScenes, generatedSceneAssetsFileName } from '../compiler/compileScenes.js';
@@ -26,13 +27,15 @@ const descriptors = {
 const virtualPlatformId = '\0pixifact:platform';
 const virtualAssetsId = '\0pixifact:assets';
 const virtualScenesId = '\0pixifact:scenes';
+const virtualCodeLoaderId = '\0pixifact:code-loader';
 export function pixifact(options = {}) {
-    const state = {};
+    const state = { codePackages: new Map() };
     return [
         scenePlugin(state, options),
         platformPlugin(state),
         assetsPlugin(state),
         resourcePlugin(state),
+        codePackagesPlugin(state),
         miniGamePlugin(state),
     ];
 }
@@ -45,7 +48,7 @@ function scenePlugin(state, options) {
             const platform = required(state.platform);
             const output = platform === 'web'
                 ? {}
-                : miniGameBuildConfig(projectRoot, platform, config);
+                : miniGameBuildConfig(projectRoot, platform, config, state.codePackages.size > 0);
             return {
                 ...output,
                 root: projectRoot,
@@ -130,6 +133,8 @@ function resourcePlugin(state) {
             }
             if (platform !== 'web') {
                 for (const pack of localPacks(required(state.config))) {
+                    if (state.codePackages.has(pack))
+                        continue;
                     this.emitFile({
                         type: 'asset',
                         fileName: path.posix.join('subpackages', pack, 'game.js'),
@@ -140,6 +145,141 @@ function resourcePlugin(state) {
         },
     };
 }
+function codePackagesPlugin(state) {
+    return {
+        name: 'pixifact-code-packages',
+        apply: 'build',
+        enforce: 'post',
+        async buildStart(input) {
+            if (state.platform === 'web' || state.codePackages.size === 0)
+                return;
+            const entries = typeof input.input === 'string' ? [input.input]
+                : Array.isArray(input.input) ? input.input : Object.values(input.input);
+            const entryIds = await Promise.all(entries.map(async (entry) => (await this.resolve(entry))?.id));
+            for (const [name, id] of state.codePackages) {
+                if (entryIds.includes(id)) {
+                    this.error(`代码分包 ${name} 不能使用应用主入口 ${id}。`);
+                }
+                this.emitFile({ type: 'chunk', id, fileName: `subpackages/${name}/game.js`, preserveSignature: 'strict' });
+            }
+        },
+        resolveId(id) {
+            return id === virtualCodeLoaderId ? id : undefined;
+        },
+        load(id) {
+            if (id !== virtualCodeLoaderId)
+                return;
+            const api = state.platform === 'wechat' ? 'wx' : 'tt';
+            return [
+                "import { createMiniGameSubpackageLoader } from 'pixifact/internal/minigame';",
+                `export const loadCodePackage = createMiniGameSubpackageLoader(() => ${api}, ${JSON.stringify(state.platform)});`,
+            ].join('\n');
+        },
+        async transform(code, id) {
+            if (state.platform === 'web' || state.codePackages.size === 0)
+                return;
+            // Native require() loads chunks. Vite's browser preload/error helper
+            // would otherwise access Event/window and mask module exceptions.
+            if (id === '\0vite/preload-helper.js') {
+                return 'export function __vitePreload(load) { return load(); }';
+            }
+            if (!code.includes('import'))
+                return;
+            const source = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true);
+            const specifiers = new Set();
+            function visit(node) {
+                if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                    const argument = node.arguments[0];
+                    if (argument && ts.isStringLiteralLike(argument))
+                        specifiers.add(argument.text);
+                }
+                ts.forEachChild(node, visit);
+            }
+            visit(source);
+            const packagesById = new Map([...state.codePackages].map(([name, entry]) => [entry, name]));
+            const imports = new Map();
+            for (const specifier of specifiers) {
+                const resolved = await this.resolve(specifier, id);
+                const name = resolved && packagesById.get(resolved.id);
+                if (name)
+                    imports.set(specifier, name);
+            }
+            if (imports.size === 0)
+                return;
+            const result = ts.transpileModule(code, {
+                fileName: id,
+                compilerOptions: {
+                    target: ts.ScriptTarget.ESNext,
+                    module: ts.ModuleKind.ESNext,
+                    verbatimModuleSyntax: true,
+                    sourceMap: true,
+                    inlineSources: true,
+                },
+                transformers: { before: [(context) => (file) => {
+                            const factory = context.factory;
+                            const loader = factory.createUniqueName('__pixifactLoadCodePackage');
+                            const transform = (node) => {
+                                if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                                    const argument = node.arguments[0];
+                                    const name = argument && ts.isStringLiteralLike(argument) && imports.get(argument.text);
+                                    if (name) {
+                                        return factory.createCallExpression(factory.createPropertyAccessExpression(factory.createCallExpression(loader, undefined, [factory.createStringLiteral(name)]), 'then'), undefined, [factory.createArrowFunction(undefined, undefined, [], undefined, factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), node)]);
+                                    }
+                                }
+                                return ts.visitEachChild(node, transform, context);
+                            };
+                            const transformed = ts.visitEachChild(file, transform, context);
+                            return factory.updateSourceFile(transformed, [
+                                factory.createImportDeclaration(undefined, factory.createImportClause(false, undefined, factory.createNamedImports([
+                                    factory.createImportSpecifier(false, factory.createIdentifier('loadCodePackage'), loader),
+                                ])), factory.createStringLiteral(virtualCodeLoaderId)),
+                                ...transformed.statements,
+                            ]);
+                        }] },
+            });
+            return { code: result.outputText, map: result.sourceMapText };
+        },
+        buildEnd(error) {
+            if (error || state.platform === 'web' || state.codePackages.size === 0)
+                return;
+            const packagesById = new Map([...state.codePackages].map(([name, id]) => [id, name]));
+            for (const root of this.getModuleIds()) {
+                if (!this.getModuleInfo(root)?.isEntry)
+                    continue;
+                const owner = packagesById.get(root);
+                const visited = new Set();
+                const visit = (id) => {
+                    if (visited.has(id))
+                        return;
+                    visited.add(id);
+                    for (const dependency of this.getModuleInfo(id)?.importedIds ?? []) {
+                        const name = packagesById.get(dependency);
+                        if (name && name !== owner) {
+                            this.error(`不能静态引用代码分包 ${name}（${id}）；请从主包使用 import() 加载分包入口。`);
+                        }
+                        visit(dependency);
+                    }
+                };
+                visit(root);
+            }
+        },
+        generateBundle(_options, bundle) {
+            if (state.platform === 'web' || state.codePackages.size === 0)
+                return;
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type !== 'chunk')
+                    continue;
+                const owner = chunk.fileName.match(/^subpackages\/([^/]+)\//)?.[1];
+                for (const dependency of [...chunk.imports, ...chunk.dynamicImports]) {
+                    const name = dependency.match(/^subpackages\/([^/]+)\//)?.[1];
+                    if (name && owner && name !== owner) {
+                        this.error(`代码分包 ${owner} 不能引用分包 ${name}；请由主包发起分包加载。`);
+                    }
+                }
+            }
+        },
+    };
+}
 function miniGamePlugin(state) {
     return {
         name: 'pixifact-minigame',
@@ -154,9 +294,11 @@ function miniGamePlugin(state) {
             const gameJson = JSON.parse(await readFile(path.join(configDir, 'game.json'), 'utf8'));
             const projectConfig = JSON.parse(await readFile(path.join(configDir, 'project.config.json'), 'utf8'));
             if (gameJson[descriptor.subpackageProperty] !== undefined) {
-                throw new Error(`platforms/${platform}/game.json must not declare ${descriptor.subpackageProperty}; Pixifact manages resource subpackages.`);
+                throw new Error(`platforms/${platform}/game.json 的 ${descriptor.subpackageProperty} 由 Pixifact 根据资源包和代码分包生成，不能在源模板中重复声明。`);
             }
-            gameJson[descriptor.subpackageProperty] = localPacks(required(state.config)).map((name) => ({
+            gameJson[descriptor.subpackageProperty] = [...new Set([
+                    ...localPacks(required(state.config)), ...state.codePackages.keys(),
+                ])].map((name) => ({
                 name,
                 root: `subpackages/${name}`,
             }));
@@ -212,8 +354,23 @@ async function configureState(state, options, config, env) {
     state.env = loaded.env;
     state.platform = loaded.platform;
     state.config = parsePixifactProjectConfig(JSON.parse(await readFile(path.join(projectRoot, pixifactProjectConfigFileName), 'utf8')));
+    state.codePackages = new Map();
+    for (const [name, entry] of Object.entries(options.codePackages ?? {})) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) {
+            throw new Error(`代码分包名称 ${name} 只能包含字母、数字、连字符和下划线，并以字母或数字开头。`);
+        }
+        const absolute = realpathSync(path.resolve(projectRoot, entry)).replaceAll(path.sep, '/');
+        const relative = path.relative(projectRoot, absolute);
+        if (path.isAbsolute(entry) || relative.startsWith(`..${path.sep}`) || relative === '..') {
+            throw new Error(`代码分包 ${name} 的入口必须位于项目内并使用项目相对路径。`);
+        }
+        if ([...state.codePackages.values()].includes(absolute)) {
+            throw new Error(`代码分包 ${name} 重复声明入口 ${entry}。`);
+        }
+        state.codePackages.set(name, absolute);
+    }
 }
-function miniGameBuildConfig(projectRoot, platform, config) {
+function miniGameBuildConfig(projectRoot, platform, config, hasCodePackages) {
     const descriptor = descriptors[platform];
     return {
         appType: 'custom',
@@ -227,6 +384,15 @@ function miniGameBuildConfig(projectRoot, platform, config) {
             modulePreload: false,
             rollupOptions: {
                 ...config.build?.rollupOptions,
+                ...(hasCodePackages ? {
+                    preserveEntrySignatures: 'strict',
+                    // Rolldown's cross-chunk constant inlining crashes when Scene
+                    // registration and Pixi's async Application imports share CJS chunks.
+                    optimization: {
+                        ...config.build?.rollupOptions?.optimization,
+                        inlineConst: false,
+                    },
+                } : {}),
                 input: config.build?.rollupOptions?.input ?? path.join(projectRoot, 'src/main.ts'),
                 output: {
                     ...(Array.isArray(config.build?.rollupOptions?.output)
@@ -237,7 +403,12 @@ function miniGameBuildConfig(projectRoot, platform, config) {
                         `var navigator=globalThis.navigator||(globalThis.navigator={gpu:null,userAgent:${JSON.stringify(descriptor.userAgent)}});`,
                     ].join('\n'),
                     entryFileNames: 'game.js',
-                    format: 'iife',
+                    format: hasCodePackages ? 'cjs' : 'iife',
+                    ...(hasCodePackages ? {
+                        chunkFileNames: 'chunks/[name]-[hash].js',
+                        codeSplitting: true,
+                        dynamicImportInCjs: false,
+                    } : {}),
                 },
             },
             target: descriptor.ecmascriptTarget,

package/dist/platform/minigame/application.js

@@ -39,12 +39,19 @@ export async function createMiniGameApplication(api, userAgent, fetchResource, c
     const lifecycle = bindMiniGameLifecycle(api, app.ticker, {
         onHide: () => input.cancelAll(),
     });
+    const resize = (size) => {
+        runtime.width = size.windowWidth;
+        runtime.height = size.windowHeight;
+        app.renderer.resize(runtime.width, runtime.height);
+    };
+    api.onWindowResize?.(resize);
     let destroyed = false;
     const destroy = app.destroy.bind(app);
     app.destroy = ((...args) => {
         if (destroyed)
             return;
         destroyed = true;
+        api.offWindowResize?.(resize);
         lifecycle.dispose();
         input.dispose();
         destroy(...args);

package/dist/platform/minigame/fetch.d.ts

@@ -1,2 +1,4 @@
 import type { MiniGameApi, MiniGameFetch } from './types.js';
+export declare function decodeUtf8(buffer: ArrayBuffer): string;
+export declare function encodeUtf8(value: string): ArrayBuffer;
 export declare function fetchMiniGameResource(api: MiniGameApi, input: RequestInfo | URL, init: RequestInit | undefined, platformName: string): ReturnType<MiniGameFetch>;

package/dist/platform/minigame/fetch.js

@@ -7,7 +7,7 @@ class MiniGameResponseHeaders {
         return this.values.get(name.toLowerCase()) ?? null;
     }
 }
-function decodeUtf8(buffer) {
+export function decodeUtf8(buffer) {
     const bytes = new Uint8Array(buffer);
     let output = '';
     for (let index = 0; index < bytes.length;) {
@@ -34,7 +34,7 @@ function decodeUtf8(buffer) {
     }
     return output;
 }
-function encodeUtf8(value) {
+export function encodeUtf8(value) {
     const bytes = [];
     for (const character of value) {
         const codePoint = character.codePointAt(0);

package/dist/platform/minigame/runtime.js

@@ -85,19 +85,19 @@ function installEventTarget(target, nativeTypes = new Set()) {
         return !event.defaultPrevented;
     };
 }
-function installCanvasSurface(canvas, width, height) {
+function installCanvasSurface(canvas, viewport) {
     installEventTarget(canvas, new Set(['webglcontextlost', 'webglcontextrestored']));
     canvas.style ??= {};
     Object.defineProperty(canvas, 'isConnected', { configurable: true, value: true });
     Object.defineProperty(canvas, 'getBoundingClientRect', {
         configurable: true,
         value: () => ({
-            bottom: height,
-            height,
+            bottom: viewport.height,
+            height: viewport.height,
             left: 0,
-            right: width,
+            right: viewport.width,
             top: 0,
-            width,
+            width: viewport.width,
             x: 0,
             y: 0,
         }),
@@ -176,8 +176,9 @@ export function createMiniGameRuntime(api, userAgent) {
     const width = Math.max(1, Math.round(Number(info.windowWidth ?? info.screenWidth)));
     const height = Math.max(1, Math.round(Number(info.windowHeight ?? info.screenHeight)));
     const resolution = Math.min(2, Math.max(1, Number(info.pixelRatio ?? 1)));
-    installCanvasSurface(canvas, width, height);
+    const viewport = { width, height };
+    installCanvasSurface(canvas, viewport);
     installGlobals(api, canvas, userAgent);
     const { context, webGLVersion } = createContext(canvas);
-    return { canvas, context, height, resolution, userAgent, webGLVersion, width };
+    return Object.assign(viewport, { canvas, context, resolution, userAgent, webGLVersion });
 }

package/dist/platform/minigame/subpackage.js

@@ -1,3 +1,4 @@
+const subpackageStates = new WeakMap();
 export function miniGameResourceSubpackage(input) {
     const url = typeof input === 'string' ? input : (input.url ?? String(input));
     if (/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(url))
@@ -7,9 +8,14 @@ export function miniGameResourceSubpackage(input) {
 }
 export function createMiniGameSubpackageLoader(apiOrFactory, platformName) {
     const getApi = typeof apiOrFactory === 'function' ? apiOrFactory : () => apiOrFactory;
-    const loaded = new Set();
-    const loading = new Map();
     return function loadSubpackage(name) {
+        const api = getApi();
+        let state = subpackageStates.get(api);
+        if (!state) {
+            state = { loaded: new Set(), loading: new Map() };
+            subpackageStates.set(api, state);
+        }
+        const { loaded, loading } = state;
         if (loaded.has(name)) {
             return Promise.resolve();
         }
@@ -18,7 +24,7 @@ export function createMiniGameSubpackageLoader(apiOrFactory, platformName) {
             return existing;
         }
         const pending = new Promise((resolve, reject) => {
-            getApi().loadSubpackage({
+            api.loadSubpackage({
                 name,
                 fail: (error) => reject(new Error(`Failed to load ${platformName} subpackage ${name}: ${error.errMsg}`)),
                 success: resolve,

package/dist/platform/minigame/types.d.ts

@@ -96,6 +96,14 @@ export interface MiniGameApi {
     offHide?(callback: () => void): void;
     onShow(callback: () => void): void;
     offShow?(callback: () => void): void;
+    onWindowResize?(callback: (size: {
+        windowWidth: number;
+        windowHeight: number;
+    }) => void): void;
+    offWindowResize?(callback: (size: {
+        windowWidth: number;
+        windowHeight: number;
+    }) => void): void;
     onTouchStart(callback: (event: MiniGameTouchEvent) => void): void;
     offTouchStart?(callback: (event: MiniGameTouchEvent) => void): void;
     onTouchMove(callback: (event: MiniGameTouchEvent) => void): void;

package/dist/runtime-dev/runtimeClient.d.ts

@@ -1,7 +1,9 @@
 import { type Application } from 'pixi.js';
-import { type RuntimeJsonValue, type RuntimeRequest } from './protocol.js';
+import { type RuntimeJsonValue, type RuntimeRequest, type RuntimeScreenshotResult } from './protocol.js';
 export interface RegisterPixiRuntimeOptions {
     getState?: () => RuntimeJsonValue;
+    /** 为共享 Canvas 的渲染插件提供完整合成截图。 */
+    captureScreenshot?: () => Pick<RuntimeScreenshotResult, 'width' | 'height' | 'dataUrl'> | Promise<Pick<RuntimeScreenshotResult, 'width' | 'height' | 'dataUrl'>>;
 }
 export interface PixifactRuntimeHotContext {
     on(event: string, listener: (data: unknown) => void): void;

package/dist/runtime-dev/runtimeClient.js

@@ -299,6 +299,7 @@ export function createPixifactRuntimeClient(options) {
     const logs = createRuntimeLogCapture(options.console, options.window, now);
     let app;
     let getState;
+    let captureComposite;
     function descriptor() {
         return {
             runtimeId: options.runtimeId,
@@ -316,6 +317,8 @@ export function createPixifactRuntimeClient(options) {
         return app;
     }
     async function captureScreenshot(currentApp) {
+        if (captureComposite)
+            return { ...await captureComposite(), runtimeId: options.runtimeId };
         const width = Math.max(1, Math.floor(currentApp.screen.width));
         const height = Math.max(1, Math.floor(currentApp.screen.height));
         const target = RenderTexture.create({ width, height, resolution: 1 });
@@ -412,6 +415,7 @@ export function createPixifactRuntimeClient(options) {
                 throw new Error('This page already has a registered PixiJS Application.');
             app = application;
             getState = registerOptions.getState;
+            captureComposite = registerOptions.captureScreenshot;
             announce();
         },
         handleRequest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Pixifact 2D UI 和轻量游戏 Scene 语义框架。",
   "packageManager": "bun@1.3.13",
   "main": "./dist/index.js",
@@ -78,7 +78,7 @@
   },
   "peerDependencies": {
     "pixi.js": ">=8.3.0",
-    "vite": ">=6.0.0"
+    "vite": ">=8.0.0"
   },
   "dependencies": {
     "typescript": "^5.3.3"