@playcraft/build 0.0.57 → 0.0.58

package/README.md

@@ -177,7 +177,7 @@ const adapter = createPlatformAdapter({
 });
 
 console.log(adapter.getName());          // "Facebook"
-console.log(adapter.getSizeLimit());     // 2097152 (2MB)
+console.log(adapter.getSizeLimit());     // 5242880 (5MB)
 console.log(adapter.getDefaultFormat()); // "html"
 ```
 
@@ -209,4 +209,4 @@ console.log(adapter.getDefaultFormat()); // "html"
 
 - `@playcraft/cli`：CLI 工具
 - `@playcraft/worker`：队列消费与异步构建
-- `@playcraft/backend`：类型定义用于参数校验
+- `@playcraft/backend-business-server`：类型定义用于参数校验

package/dist/engines/playable-scripts-adapter.d.ts

@@ -153,8 +153,18 @@ export declare class PlayableScriptsAdapter {
     /**
      * 是否对 playable-scripts 使用 --zip。
      * 双格式渠道默认 HTML；仅在请求或配置显式选择 ZIP 时传递 --zip。
+     *
+     * 例外：Facebook 在 devkit（Phaser / playable-scripts）路径下产物固定为 ZIP，
+     * 因此无论请求的 format 一律传递 --zip。
+     * 该规则只作用于 devkit 路径，PlayCanvas 渠道构建不受影响。
      */
     private isZipOutput;
+    /**
+     * 是否为 Facebook 渠道的 devkit 构建
+     * （devkit = Phaser / playable-scripts 路径，仅该路径会走到本适配器；
+     *   渠道来源与产物校验保持一致：validation.channel 优先，其次 playableScriptsConfig.channels）
+     */
+    private isFacebookDevkitChannel;
     /**
      * 获取平台默认的文件名格式
      */
@@ -165,6 +175,23 @@ export declare class PlayableScriptsAdapter {
      * 普通构建链由对应 PlatformAdapter 处理。
      */
     private applyChannelLifecycleBridges;
+    /**
+     * 兜底：渠道要求 ZIP，但第三方（devkit）只产出了单文件 HTML 时，现场把 HTML 打成
+     * `playable.zip`（根目录 `index.html`），并删除原始 HTML。
+     *
+     * 为什么必须在适配器里做：下游（沙箱 runner / worker）是**按产物后缀**决定
+     * manifest.format 的，留有 .html 就一定会被判成 html；只有让 outputDir 里只剩
+     * `playable.zip`，format 才会正确地是 zip。
+     */
+    private ensureZipFallbackArtifacts;
+    /**
+     * 从产物路径反推渠道：
+     * 1. 单渠道构建：产物直接落在 outputDir 下，取 `config.channels[0]`
+     * 2. 批量构建：路径形如 `outputDir/<channel>/<file>`，按目录名（含渠道映射名）匹配
+     * 3. 退化：`options.validation.channel`（沙箱 runner / worker / CLI 都会传本次渠道），
+     *    保证 `channels` 缺失时兜底不会静默失效
+     */
+    private resolveArtifactChannel;
     private getValidationChannels;
     private isSupportedValidationChannel;
     private pickArtifactForChannel;

package/dist/engines/playable-scripts-adapter.js

@@ -20,15 +20,30 @@ const CHANNEL_MAP = {
     playcraft: 'preview',
 };
 /**
- * PlayCraft 不支持的渠道（playable-scripts 不认识的 PlayCraft 平台）
+ * devkit（playable-scripts）不支持的渠道——这些渠道会被从 `--channels` 中剔除。
+ *
+ * 目前为空：devkit 已覆盖 PlayCraft 全部渠道（含 remerge，产物为 ZIP）。
+ * 若将来新增 PlayCraft 有、devkit 无的渠道，在此登记即可恢复过滤行为。
  */
-const UNSUPPORTED_CHANNELS = new Set(['remerge']);
+const UNSUPPORTED_CHANNELS = new Set([]);
 /**
  * 将 PlayCraft 平台名映射为 playable-scripts 渠道名
  */
 function mapChannel(playcraftPlatform) {
     return CHANNEL_MAP[playcraftPlatform] ?? playcraftPlatform;
 }
+/**
+ * 需要「HTML → ZIP」兜底的渠道：交付与后端校验（PlatformValidatorService）都要求 ZIP，
+ * 但 devkit（第三方）可能只产出单文件 HTML。
+ *
+ * 背景：产物格式由下游按**产物后缀**判定（runner.cjs / worker main.js 的 devkit 分支），
+ * 一旦 devkit 漏出 .html，就会与「remerge 必须 ZIP」的硬规则冲突，报
+ * `平台要求 ZIP 格式，但输出为 HTML`（FORMAT_MISMATCH）。
+ *
+ * 注意：bigo / snapchat 不在此列 —— 它们的 HTML→ZIP 兜底在 runner / worker 的
+ * htmlBackedZip 分支完成（还要额外注入 config.json 的 orientation），不能在这里简单打包。
+ */
+const ZIP_FALLBACK_CHANNELS = new Set(['remerge']);
 /**
  * PlayableScripts 构建工具适配器
  *
@@ -132,7 +147,10 @@ export class PlayableScriptsAdapter {
         // 7. 复制产物到 PlayCraft outputDir
         const files = await this.copyToOutputDir(outputs);
         await this.applyChannelLifecycleBridges(files);
+        // 校验放在兜底打包之前：渠道规则（size / external-resource 等）都在 html-artifact 阶段，
+        // 若先打成 ZIP，校验会因产物是 ZIP 而跳过这些规则，等于丢掉校验覆盖。
         await this.runDevkitOutputValidation(files);
+        await this.ensureZipFallbackArtifacts(files);
         // 7. 构建元数据
         const metadata = {
             mode: 'classic',
@@ -301,7 +319,7 @@ export class PlayableScriptsAdapter {
         // 输出目录 - 统一使用 dist，与 PlayCraft 标准一致
         const outputDir = config.outputDir ?? 'dist';
         args.push('--out-dir', outputDir);
-        // ZIP 输出：显式 config.zip 或构建请求 format=zip（如 Google / Facebook / TikTok 等选 ZIP）
+        // ZIP 输出：显式 config.zip、Facebook（devkit 下恒为 ZIP）或构建请求 format=zip
         const isZipFormat = this.isZipOutput();
         if (isZipFormat) {
             args.push('--zip');
@@ -1245,15 +1263,30 @@ export class PlayableScriptsAdapter {
     /**
      * 是否对 playable-scripts 使用 --zip。
      * 双格式渠道默认 HTML；仅在请求或配置显式选择 ZIP 时传递 --zip。
+     *
+     * 例外：Facebook 在 devkit（Phaser / playable-scripts）路径下产物固定为 ZIP，
+     * 因此无论请求的 format 一律传递 --zip。
+     * 该规则只作用于 devkit 路径，PlayCanvas 渠道构建不受影响。
      */
     isZipOutput() {
         const config = this.config ?? {};
         if (config.zip === true) {
             return true;
         }
+        if (this.isFacebookDevkitChannel()) {
+            return true;
+        }
         const fmt = this.options.format;
         return fmt === 'zip';
     }
+    /**
+     * 是否为 Facebook 渠道的 devkit 构建
+     * （devkit = Phaser / playable-scripts 路径，仅该路径会走到本适配器；
+     *   渠道来源与产物校验保持一致：validation.channel 优先，其次 playableScriptsConfig.channels）
+     */
+    isFacebookDevkitChannel() {
+        return this.getValidationChannels().some((channel) => mapChannel(channel) === 'facebook');
+    }
     /**
      * 获取平台默认的文件名格式
      */
@@ -1351,6 +1384,61 @@ export class PlayableScriptsAdapter {
         archive[htmlEntry] = strToU8(injectBigoLifecycleBridge(strFromU8(archive[htmlEntry])));
         await fs.writeFile(artifact, zipSync(archive, { level: 9 }));
     }
+    /**
+     * 兜底：渠道要求 ZIP，但第三方（devkit）只产出了单文件 HTML 时，现场把 HTML 打成
+     * `playable.zip`（根目录 `index.html`），并删除原始 HTML。
+     *
+     * 为什么必须在适配器里做：下游（沙箱 runner / worker）是**按产物后缀**决定
+     * manifest.format 的，留有 .html 就一定会被判成 html；只有让 outputDir 里只剩
+     * `playable.zip`，format 才会正确地是 zip。
+     */
+    async ensureZipFallbackArtifacts(files) {
+        const htmlArtifacts = files.assets.filter((artifact) => artifact.toLowerCase().endsWith('.html'));
+        if (htmlArtifacts.length === 0) {
+            return;
+        }
+        for (const htmlPath of htmlArtifacts) {
+            const channel = this.resolveArtifactChannel(htmlPath);
+            if (!channel || !ZIP_FALLBACK_CHANNELS.has(channel)) {
+                continue;
+            }
+            const zipPath = path.join(path.dirname(htmlPath), 'playable.zip');
+            const htmlBuffer = await fs.readFile(htmlPath);
+            await fs.writeFile(zipPath, zipSync({ 'index.html': new Uint8Array(htmlBuffer) }, { level: 9 }));
+            await fs.unlink(htmlPath);
+            files.assets = files.assets.filter((artifact) => artifact !== htmlPath);
+            files.assets.push(zipPath);
+            if (files.html === htmlPath) {
+                files.html = '';
+            }
+            console.log(`[PlayableScriptsAdapter] ${channel} 交付要求 ZIP，但 devkit 产出单文件 HTML；` +
+                `已兜底打包: ${path.relative(this.projectDir, zipPath)}（原始 HTML 已移除）`);
+        }
+    }
+    /**
+     * 从产物路径反推渠道：
+     * 1. 单渠道构建：产物直接落在 outputDir 下，取 `config.channels[0]`
+     * 2. 批量构建：路径形如 `outputDir/<channel>/<file>`，按目录名（含渠道映射名）匹配
+     * 3. 退化：`options.validation.channel`（沙箱 runner / worker / CLI 都会传本次渠道），
+     *    保证 `channels` 缺失时兜底不会静默失效
+     */
+    resolveArtifactChannel(artifactPath) {
+        const channels = this.config?.channels ?? [];
+        if (channels.length === 1) {
+            return channels[0];
+        }
+        if (channels.length > 1) {
+            const normalized = artifactPath.replace(/\\/g, '/').toLowerCase();
+            const matched = channels.find((channel) => {
+                const mapped = mapChannel(channel).toLowerCase();
+                return (normalized.includes(`/${channel.toLowerCase()}/`) || normalized.includes(`/${mapped}/`));
+            });
+            if (matched) {
+                return matched;
+            }
+        }
+        return this.options.validation?.channel;
+    }
     getValidationChannels() {
         if (this.options.validation?.channel) {
             return [this.options.validation.channel];

package/dist/platforms/facebook.js

@@ -4,10 +4,12 @@ export class FacebookAdapter extends PlatformAdapter {
         return 'Facebook';
     }
     getSizeLimit() {
-        // Facebook: HTML 5MB, ZIP 5MB（HTML 文件需 < 2MB 由校验处理）
+        // Facebook: 制品上限 5MB（HTML / ZIP 均为 5MB；ZIP 内的 index.html 不单独限制）
         return 5 * 1024 * 1024;
     }
     getDefaultFormat() {
+        // 渠道默认产物为单文件 HTML；Phaser（playable-scripts devkit）路径固定输出 ZIP，
+        // 由 devkit 输入侧的打包配置决定，见 playable-scripts-adapter.ts 的 isZipOutput()。
         return 'html';
     }
     async modifyHTML(html, assets) {

package/dist/platforms/remerge.js

@@ -8,7 +8,9 @@ export class RemergeAdapter extends PlatformAdapter {
         return 5 * 1024 * 1024;
     }
     getDefaultFormat() {
-        return 'html';
+        // Remerge 交付 ZIP（devkit 与 Vite 两条路径一致），与后端
+        // PlatformValidatorService / phaser-size-estimate.model 的渠道格式表保持一致。
+        return 'zip';
     }
     async modifyHTML(html, assets) {
         // Remerge 使用 FbPlayableAd API（与 Facebook/Moloco 相同）
@@ -29,7 +31,7 @@ export class RemergeAdapter extends PlatformAdapter {
     `;
         const remergeScript = await this.minifyPlatformScript(remergeScriptCode, 'remerge-api');
         const meta = `<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">`;
-        const comment = `<!-- Remerge: 单文件 HTML <5MB, CTA 无参数调用 -->`;
+        const comment = `<!-- Remerge: ZIP 交付包 <5MB, CTA 无参数调用 -->`;
         // 在 </head> 之前插入平台特定的 API
         html = html.replace('</head>', `${remergeScript}${comment}${meta}</head>`);
         // 注入统一的 CTA 适配器
@@ -49,8 +51,8 @@ export class RemergeAdapter extends PlatformAdapter {
     `;
     }
     validateOptions() {
-        if (this.options.format && this.options.format !== 'html') {
-            console.warn('警告: Remerge 使用单文件 HTML 格式');
+        if (this.options.format && this.options.format !== 'zip') {
+            console.warn('警告: Remerge 交付 ZIP 格式');
         }
     }
 }

package/dist/validation/profiles.js

@@ -197,10 +197,10 @@ export const CHANNEL_RULE_PROFILES = {
         requiredPatternRule('adikteev', 'click-pixel-url.required', 'Adikteev requires AK_CLICK_PIXEL_URL exposure.', 'AK_CLICK_PIXEL_URL|AK CLICK PIXEL URL', 'Expose the Adikteev click pixel URL variable.'),
         manualRule('adikteev', 'runtime.cdn-responsive.manual', 'CDN resource loading and responsive layout need runtime review.', 'Verify separated assets load from Adikteev CDN and remain responsive.'),
     ], { optionalStages: ['delivery-package', 'runtime-manual'], deliveryPackageFormat: 'fragment-assets' }),
-    remerge: profile('remerge', 'Remerge', 'single-html', [
+    remerge: profile('remerge', 'Remerge', 'zip', [
         externalResourceRule('remerge'),
         forbiddenPatternRule('remerge', 'redirect.auto.forbidden', 'Remerge creatives should not auto-redirect to the store.', '\\blocation\\.(href|assign|replace)\\b', 'Keep store jumps behind a user CTA.'),
-    ]),
+    ], { optionalStages: ['delivery-package'], deliveryPackageFormat: 'zip' }),
     mintegral: profile('mintegral', 'Mintegral', 'mixed', [
         sourcePresenceRule('mintegral', 'lifecycle.game-end.required', 'Mintegral requires a gameplay finish signal.', 'Call sdk.playcraftFinish() when gameplay reaches a win or end state.'),
         requiredPatternRule('mintegral', 'lifecycle.game-end.required', 'Mintegral creatives should call window.gameEnd() after gameplay ends.', 'window\\.gameEnd\\s*\\(', 'Map the gameplay finish signal to window.gameEnd().'),

package/dist/vite/platform-configs.js

@@ -36,7 +36,7 @@ export const PLATFORM_CONFIGS = {
         },
     },
     facebook: {
-        sizeLimit: 5 * 1024 * 1024, // 5MB（HTML/ZIP 总包体）
+        sizeLimit: 5 * 1024 * 1024, // 5MB（HTML/ZIP 总包体；Phaser 产物为 ZIP）
         outputFormat: 'html',
         minifyCSS: true,
         minifyJS: true,
@@ -388,7 +388,8 @@ export const PLATFORM_CONFIGS = {
     },
     remerge: {
         sizeLimit: 5 * 1024 * 1024, // 5MB
-        outputFormat: 'html',
+        // Remerge 交付 ZIP（与 devkit 产物一致）
+        outputFormat: 'zip',
         minifyCSS: true,
         minifyJS: true,
         compressImages: false, // 禁用图片压缩，原图输出效果更好

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/build",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",