@next2d/builder 0.1.11 → 0.3.0

package/README.md

@@ -1,77 +1,110 @@
-Multi-platform Builder
-=============
+# Multi-platform Builder
 
 [![CodeQL](https://github.com/Next2D/builder/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/Next2D/builder/actions/workflows/github-code-scanning/codeql)
 [![Lint](https://github.com/Next2D/builder/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/Next2D/builder/actions/workflows/lint.yml)
 [![release](https://img.shields.io/github/v/release/Next2D/builder)](https://github.com/Next2D/builder/releases)
 [![license](https://img.shields.io/github/license/Next2D/builder)](https://github.com/Next2D/builder/blob/main/LICENSE)
 
-[日本語]\
-1つのプロジェクトから多種多様なプラットフォーム向けのアプリケーションを作成するマルチプラットフォームビルダー。  
-
-* Steam：Steamに対応したWindows版、macOS版、Linux版のアプリケーションの書き出しが可能。
-* デスクトップ：デスクトップ環境向けに、Windows、macOS、Linux向けのアプリケーションを出力できます。
-* スマートフォン：iOSおよびAndroidに対応したスマートフォン用アプリケーションとしての書き出しもサポート。
-* Web（HTML）：ブラウザ上で動作するHTML形式のコンテンツも簡単に生成可能。
-
-Next2D Frameworkを使えば、1つのソースコードから多様なデバイスやOSに最適化されたアプリケーションを効率的に開発・展開することができます。
-
-[English]\
-Multi-platform builder to create applications for a wide variety of platforms from a single project.  
-
-* Steam: Allows export of applications for Windows, macOS, and Linux versions that are compatible with Steam.
-* Desktop: Export of applications for Windows, macOS, and Linux for desktop environments is supported.
-* Smartphone: Export as smartphone applications compatible with iOS and Android is also supported.
-* Web (HTML): Easily generate HTML-format content that runs in a browser.
-
-With Next2D Framework, you can efficiently develop and deploy applications optimized for diverse devices and operating systems from a single source code.
-
-## Supported
-
-| platform        | detail                              |
-|-----------------|-------------------------------------|
-| Windows         | Export an exe file                  |
-| macOS           | Export dmg, app file                |
-| Linux           | Export deb file                     |
-| Steam:Windows   | Export an exe file                  |
-| Steam:macOS     | Export dmg, app file                |
-| Steam:Linux     | Export deb file                     |
-| web             | Export minfy'd JS files             |
-| iOS             | open Xcode, and Export ipa          |
-| iOS             | open Android Studio, and Export apk |
-| Xbox            | GDK native title (V8 + Dawn/WebGPU) |
-
-Xbox exports a GDK native title that runs the Next2D JavaScript on the V8 engine and
-renders with Dawn (WebGPU → D3D12), packaged as a C++ executable (no Electron/WebView).
-Building the GDK package requires Windows + Visual Studio 2022 + Microsoft GDK + a devkit.
-On other platforms the builder scaffolds the host project and stages assets only.
-See the generated `xbox/README.md` for full build steps.
-
-```bat
-npx @next2d/builder --platform xbox --env prd
+[日本語](#日本語) | [English](#english)
+
+## 日本語
+
+Next2D Frameworkの1つのプロジェクトから、複数のプラットフォーム向けにアプリケーションを書き出すビルダーです。
+Steamおよびデスクトップ向けのWindows / macOS / Linux、スマートフォン向けのiOS / Android、Web（HTML）に対応しています。
+Xbox対応は試作・開発段階です。
+
+### 対応プラットフォーム
+
+| プラットフォーム | 出力・対応状況 |
+|---|---|
+| Steam:Windows | 実行ファイル（.exe）と必要なリソース |
+| Steam:macOS | アプリケーションバンドル（.app） |
+| Steam:Linux | 実行ファイルと必要なリソース |
+| Web | 最適化されたJavaScriptとWebアセット |
+| iOS | Xcodeプロジェクトを開く、IPAを書き出す |
+| Android | Android Studioプロジェクトを開く、APKを書き出す |
+| Xbox | GDKネイティブホストの試作・開発段階 |
+
+### プラットフォーム別ガイド
+
+設定、依存ツール、書き出し・配布手順の詳細は、以下のドキュメントにまとめています。
+
+| ガイド | 内容 |
+|---|---|
+| [Electron / Steam](docs/steam.md#日本語) | デスクトップ書き出し、アイコン、CPU、署名、Steam Depot、アップロード、ベータテスト |
+| [ネイティブ機能の拡張](docs/native-bridge.md) | OS API・任意SDKとの連携、設定、プロトコル、実装例（OS情報取得・EOS） |
+| [iOS / Android（Capacitor）](docs/capacitor.md#日本語) | ネイティブ設定、SDK、プラグイン、ビルドコマンド、移行、Xcodeの設定 |
+| [Xbox（試作）](docs/xbox.md#日本語) | 開発状況、ホスト生成、ビルド環境、検証範囲 |
+
+### 今後の対応予定
+
+| プラットフォーム |
+|---|
+| Nintendo Switch |
+
+### ビルド例
+
+```sh
+npx @next2d/builder --platform web --env prd
 ```
 
-The prebuilt V8 engine is downloaded automatically on the first Xbox build
-(published from the `build-v8` workflow). To use your own build, pass
-`--v8-root C:\path\to\v8`.
+### プレビュー例
 
-### Scheduled introduction
+```sh
+npx @next2d/builder --preview --platform web --env prd
+```
+
+### ライセンス
+
+このプロジェクトは[MIT License](https://opensource.org/licenses/MIT)で公開しています。詳細は[LICENSE](LICENSE)を参照してください。
+
+## English
+
+Build applications for multiple platforms from a single Next2D Framework project.
+The builder supports Windows / macOS / Linux for Steam and desktop distribution, iOS / Android for mobile devices, and Web (HTML).
+Xbox support is a prototype under development.
+
+### Supported platforms
 
-| platform        | 
-|-----------------|
+| Platform | Output / status |
+|---|---|
+| Steam:Windows | Executable (.exe) and required resources |
+| Steam:macOS | Application bundle (.app) |
+| Steam:Linux | Executable and required resources |
+| Web | Optimized JavaScript and web assets |
+| iOS | Open the Xcode project and export an IPA |
+| Android | Open the Android Studio project and export an APK |
+| Xbox | Prototype GDK native host; under development |
+
+### Platform guides
+
+These guides cover platform-specific configuration, dependencies, builds and distribution.
+
+| Guide | Contents |
+|---|---|
+| [Electron / Steam](docs/steam.md#english) | Desktop exports, icons, architectures, signing, Steam depots, uploads and beta testing |
+| [Native extensions (Japanese)](docs/native-bridge.md) | OS APIs and SDK integration, configuration, protocol, and examples (system information / EOS) |
+| [iOS / Android (Capacitor)](docs/capacitor.md#english) | Native configuration, SDKs, plugins, build commands, migration and Xcode setup |
+| [Xbox (prototype)](docs/xbox.md#english) | Development status, host generation, build environment and validation scope |
+
+### Planned support
+
+| Platform |
+|---|
 | Nintendo Switch |
 
-### build example.
+### Build example
 
-```linux
+```sh
 npx @next2d/builder --platform web --env prd
 ```
 
-### preview example.
+### Preview example
 
-```linux
+```sh
 npx @next2d/builder --preview --platform web --env prd
 ```
 
-## License
-This project is licensed under the [MIT License](https://opensource.org/licenses/MIT) - see the [LICENSE](LICENSE) file for details.
+### License
+
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). See [LICENSE](LICENSE) for details.

package/dist/cli.d.ts

@@ -17,6 +17,13 @@ export interface ParsedArgs {
     open: boolean;
     build: boolean;
     v8Root: string;
+    arch: string;
+    steamManifest: boolean;
+    steamUpload: boolean;
+    steamBranch: string;
+    steamRoot: string;
+    steamComment: string;
+    dryRun: boolean;
     hasHelp: boolean;
 }
 /**

package/dist/cli.js

@@ -1,5 +1,5 @@
 // CLI 引数の解析とヘルプ表示。process.argv を読み取り ctx を初期化する。
-import pc from "picocolors";
+import pc from "./colors.js";
 import { ctx } from "./context.js";
 import { RECOMMENDED_NODE_VERSION } from "./constants.js";
 /**
@@ -24,6 +24,11 @@ export const echoHelp = () => {
     console.log("For Xbox build example (prebuilt V8 is downloaded automatically):");
     console.log("npx @next2d/builder --platform xbox --env prd");
     console.log("To use your own V8 build: --v8-root C:\\path\\to\\v8");
+    console.log("Steam: --platform steam:windows|steam:macos|steam:linux --env prd");
+    console.log("Electron: --arch x64|arm64|universal (default: macOS universal, others x64)");
+    console.log("Combine existing Steam packages only: --platform steam:macos --env prd --steam-manifest");
+    console.log("Upload existing packages: --steam-upload --env prd [--steam-branch internal] [--steam-root dist/steam] [--steam-comment \"Build comment\"] [--dry-run]");
+    console.log("Steam upload uses STEAM_USERNAME and optional STEAMCMD (executable path); no --platform is needed.");
     console.log();
     process.exit(1);
 };
@@ -54,10 +59,45 @@ export const parseArgv = (argv) => {
         "open": false,
         "build": false,
         "v8Root": "",
+        "arch": "",
+        "steamManifest": false,
+        "steamUpload": false,
+        "steamBranch": "",
+        "steamRoot": "",
+        "steamComment": "",
+        "dryRun": false,
         "hasHelp": false
     };
     for (let idx = 0; idx < argv.length; ++idx) {
         switch (argv[idx]) {
+            case "--steam-upload":
+                result.steamUpload = true;
+                break;
+            case "--dry-run":
+                result.dryRun = true;
+                break;
+            case "--steam-branch":
+            case "--steam-root":
+            case "--steam-comment": {
+                const flag = argv[idx];
+                const value = argv[++idx] || "";
+                if (!value || value.startsWith("--")) {
+                    result.hasHelp = true;
+                }
+                if (flag === "--steam-branch") {
+                    result.steamBranch = value;
+                }
+                else if (flag === "--steam-root") {
+                    result.steamRoot = value;
+                }
+                else {
+                    result.steamComment = value;
+                }
+                break;
+            }
+            case "--steam-manifest":
+                result.steamManifest = true;
+                break;
             case "--preview":
                 result.preview = true;
                 break;
@@ -81,14 +121,32 @@ export const parseArgv = (argv) => {
                 // Xbox ビルドで使う prebuilt V8 monolith のパス (環境変数 V8_ROOT より優先)
                 result.v8Root = argv[++idx] || "";
                 break;
+            case "--arch":
+                result.arch = argv[++idx] || "";
+                if (!result.arch || result.arch.startsWith("--")) {
+                    result.hasHelp = true;
+                }
+                break;
             default:
+                if (argv.includes("--steam-upload") && argv[idx].startsWith("-")) {
+                    result.hasHelp = true;
+                }
                 break;
         }
         if (result.hasHelp) {
             break;
         }
     }
-    if (!result.platform || !result.environment) {
+    if (!result.platform && !result.steamUpload || !result.environment || result.environment.startsWith("--")) {
+        result.hasHelp = true;
+    }
+    if (result.steamManifest && (!result.platform.startsWith("steam:") || result.preview || result.open || result.build || result.arch)) {
+        result.hasHelp = true;
+    }
+    if (result.steamUpload && (result.platform || result.steamManifest || result.preview || result.open || result.build || result.arch || result.v8Root)) {
+        result.hasHelp = true;
+    }
+    if (!result.steamUpload && (result.steamBranch || result.steamRoot || result.steamComment || result.dryRun)) {
         result.hasHelp = true;
     }
     return result;
@@ -131,7 +189,14 @@ Please update your version of Node.`);
     ctx.open = parsed.open;
     ctx.build = parsed.build;
     ctx.v8Root = parsed.v8Root;
-    if (parsed.hasHelp || !SUPPORTED_PLATFORMS.has(ctx.platform)) {
+    ctx.arch = parsed.arch;
+    ctx.steamManifest = parsed.steamManifest;
+    ctx.steamUpload = parsed.steamUpload;
+    ctx.steamBranch = parsed.steamBranch;
+    ctx.steamRoot = parsed.steamRoot;
+    ctx.steamComment = parsed.steamComment;
+    ctx.dryRun = parsed.dryRun;
+    if (parsed.hasHelp || !ctx.steamUpload && !SUPPORTED_PLATFORMS.has(ctx.platform)) {
         echoHelp();
     }
     ctx.platformDir = derivePlatformDir(ctx.platform);

package/dist/colors.d.ts

@@ -0,0 +1,6 @@
+declare const _default: {
+    red: (value: unknown) => string;
+    green: (value: unknown) => string;
+    yellow: (value: unknown) => string;
+};
+export default _default;

package/dist/colors.js

@@ -0,0 +1,7 @@
+// Node handles TTY detection, NO_COLOR and FORCE_COLOR without a logging dependency.
+import { styleText } from "node:util";
+export default {
+    "red": (value) => styleText("red", String(value)),
+    "green": (value) => styleText("green", String(value)),
+    "yellow": (value) => styleText("yellow", String(value))
+};

package/dist/context.d.ts

@@ -14,8 +14,17 @@ export interface BuildContext {
     build: boolean;
     /** --v8-root (Xbox) */
     v8Root: string;
+    /** Electron CPU architecture (--arch); empty selects a platform default. */
+    arch: string;
+    /** Generate shared Steam depot manifests from existing packages only. */
+    steamManifest: boolean;
+    steamUpload: boolean;
+    steamBranch: string;
+    steamRoot: string;
+    steamComment: string;
+    dryRun: boolean;
     /** vite の loadConfigFromFile 結果 */
-    configObject: any | null;
+    configObject: Awaited<ReturnType<typeof import("vite").loadConfigFromFile>>;
     /** ビルド出力ディレクトリ (dist/<platformDir>/<env>) */
     buildDir: string;
     /** vite build.outDir (既定 "dist") */

package/dist/context.js

@@ -12,6 +12,13 @@ export const ctx = {
     "open": false,
     "build": false,
     "v8Root": "",
+    "arch": "",
+    "steamManifest": false,
+    "steamUpload": false,
+    "steamBranch": "",
+    "steamRoot": "",
+    "steamComment": "",
+    "dryRun": false,
     "configObject": null,
     "buildDir": "",
     "outDir": "dist",

package/dist/description.d.ts

@@ -0,0 +1,2 @@
+/** An explicit empty string is intentional; null/undefined use package metadata. */
+export declare const resolveDescription: (description: unknown, fallback: unknown) => string;

package/dist/description.js

@@ -0,0 +1,8 @@
+/** An explicit empty string is intentional; null/undefined use package metadata. */
+export const resolveDescription = (description, fallback) => {
+    const value = description ?? fallback ?? "";
+    if (typeof value !== "string") {
+        throw new Error("App description must be a string.");
+    }
+    return value;
+};

package/dist/electron-config.d.ts

@@ -0,0 +1,62 @@
+import type { INativeBridgeConfig } from "./electron-native.js";
+export type ElectronOS = "windows" | "macos" | "linux";
+export interface IElectronConfig {
+    nativeBridge?: INativeBridgeConfig;
+    appId: string;
+    appName: string;
+    description: string;
+    executableName: string;
+    companyName: string;
+    icons: Partial<Record<ElectronOS, string>>;
+    architectures: Partial<Record<ElectronOS, string>>;
+    window: {
+        width: number;
+        height: number;
+        fullscreen: boolean;
+    };
+    steam?: {
+        appId: string | null;
+        depots: Partial<Record<ElectronOS, string | null>>;
+        branch?: string;
+    };
+    macos: {
+        sign: boolean;
+        notarize: boolean;
+        localNetworkUsageDescription?: string;
+    };
+}
+export declare const validateSteamId: (value: unknown) => string;
+export declare const readElectronConfig: (root: string) => IElectronConfig;
+/** JSON is the source of game metadata; secrets stay in the environment/keychain. */
+export declare const createElectronPackagerOptions: (root: string, config: IElectronConfig, os: ElectronOS, resources: string) => {
+    osxNotarize?: {
+        keychainProfile: string;
+    } | undefined;
+    osxSign?: {
+        identity: string | undefined;
+        continueOnError: boolean;
+        ignore: string[];
+        optionsForFile: () => {
+            hardenedRuntime: boolean;
+            entitlements: string;
+        };
+    } | undefined;
+    extendInfo?: {
+        NSLocalNetworkUsageDescription: string;
+    } | undefined;
+    extendHelperInfo?: {
+        NSLocalNetworkUsageDescription: string;
+    } | undefined;
+    icon?: string | undefined;
+    name: string;
+    executableName: string;
+    appBundleId: string;
+    appVersion: any;
+    win32metadata: {
+        CompanyName: string;
+        FileDescription: string;
+    };
+    asar: boolean;
+    extraResource: string[];
+    ignore: RegExp[];
+};

package/dist/electron-config.js

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getTemplateDir } from "./utils.js";
+import { resolveDescription } from "./description.js";
+import { validateNativeBridge } from "./electron-native.js";
+export const validateSteamId = (value) => {
+    const id = String(value);
+    if (!/^[1-9][0-9]*$/.test(id) || !Number.isSafeInteger(Number(id)) || Number(id) > 4294967295) {
+        throw new Error("Steam App ID and Depot IDs must be positive 32-bit integers.");
+    }
+    return id;
+};
+export const readElectronConfig = (root) => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const file = path.resolve(root, process.env.NEXT2D_ELECTRON_CONFIG_FILE || "electron.config.json");
+    if (process.env.NEXT2D_ELECTRON_CONFIG_FILE && !fs.existsSync(file)) {
+        throw new Error("NEXT2D_ELECTRON_CONFIG_FILE does not exist.");
+    }
+    const input = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : {};
+    const config = {
+        "appId": input.appId ?? `app.next2d.${pkg.name}`,
+        "appName": input.appName ?? pkg.name,
+        "description": resolveDescription(input.description, pkg.description),
+        "executableName": input.executableName ?? pkg.name,
+        "companyName": input.companyName ?? pkg.author?.name ?? input.appName ?? pkg.name,
+        "icons": {
+            "windows": path.join(getTemplateDir("electron"), "icons/icon.ico"),
+            "macos": path.join(getTemplateDir("electron"), "icons/icon.icns"),
+            "linux": path.join(getTemplateDir("electron"), "icons/icon.png"),
+            ...input.icons
+        },
+        "architectures": input.architectures ?? {},
+        "window": { "width": 1280, "height": 720, "fullscreen": false, ...input.window },
+        "macos": { "sign": false, "notarize": false, ...input.macos },
+        "steam": input.steam,
+        "nativeBridge": input.nativeBridge
+    };
+    if (typeof config.appId !== "string" || !/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(config.appId)) {
+        throw new Error("electron.config.json appId must be a reverse-domain bundle identifier.");
+    }
+    for (const [key, value] of [["appName", config.appName], ["executableName", config.executableName]]) {
+        if (typeof value !== "string" || !value.trim() || /[<>:"/\\|?*\x00-\x1f]/.test(value) || /[. ]$/.test(value) || value === "..") {
+            throw new Error(`electron.config.json ${key} must be a valid portable file name.`);
+        }
+    }
+    if (typeof config.companyName !== "string" || !config.companyName.trim()) {
+        throw new Error("electron.config.json companyName must be a nonempty string.");
+    }
+    for (const dimension of [config.window.width, config.window.height]) {
+        if (!Number.isInteger(dimension) || dimension < 1 || dimension > 16384) {
+            throw new Error("Electron window width/height must be integers between 1 and 16384.");
+        }
+    }
+    for (const value of [config.window.fullscreen, config.macos.sign, config.macos.notarize]) {
+        if (typeof value !== "boolean") {
+            throw new Error("Electron fullscreen/sign/notarize options must be booleans.");
+        }
+    }
+    if (config.macos.notarize && !config.macos.sign) {
+        throw new Error("macos.notarize requires macos.sign.");
+    }
+    const localNetwork = config.macos.localNetworkUsageDescription;
+    if (localNetwork !== undefined && (typeof localNetwork !== "string" || !localNetwork.trim()
+        || localNetwork.length > 1000 || localNetwork.includes("\0"))) {
+        throw new Error("macos.localNetworkUsageDescription must be a nonempty string of at most 1000 characters.");
+    }
+    for (const os of ["windows", "macos", "linux"]) {
+        const icon = config.icons[os];
+        if (icon !== undefined) {
+            const extension = { "windows": ".ico", "macos": ".icns", "linux": ".png" }[os];
+            if (typeof icon !== "string" || path.extname(icon).toLowerCase() !== extension || !fs.statSync(path.resolve(root, icon), { "throwIfNoEntry": false })?.isFile()) {
+                throw new Error(`electron.config.json icons.${os} must point to an existing ${extension} file (relative to the project root).`);
+            }
+        }
+        const arch = config.architectures[os];
+        if (arch !== undefined && !(os === "macos" ? ["x64", "arm64", "universal"] : ["x64", "arm64"]).includes(arch)) {
+            throw new Error(`Invalid electron.config.json architectures.${os}.`);
+        }
+    }
+    if (config.steam) {
+        config.steam.appId = config.steam.appId === null || config.steam.appId === undefined ? null : validateSteamId(config.steam.appId);
+        const depots = config.steam.depots ?? {};
+        const ids = Object.values(depots).filter((value) => value !== null).map(validateSteamId);
+        if (ids.length && !config.steam.appId) {
+            throw new Error("Set steam.appId before configuring Steam Depot IDs.");
+        }
+        config.steam.depots = depots;
+    }
+    validateNativeBridge(config.nativeBridge);
+    return config;
+};
+/** JSON is the source of game metadata; secrets stay in the environment/keychain. */
+export const createElectronPackagerOptions = (root, config, os, resources) => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const release = process.env.NEXT2D_STEAM_RELEASE === "1";
+    const sign = config.macos.sign || release;
+    const notarize = config.macos.notarize || release;
+    if (os === "macos" && sign && !process.env.APPLE_SIGNING_IDENTITY) {
+        throw new Error("macOS signing requires APPLE_SIGNING_IDENTITY.");
+    }
+    if (os === "macos" && notarize && !process.env.APPLE_NOTARY_PROFILE) {
+        throw new Error("macOS notarization requires APPLE_NOTARY_PROFILE (notarytool keychain profile).");
+    }
+    return {
+        "name": config.appName,
+        "executableName": config.executableName,
+        "appBundleId": config.appId,
+        "appVersion": pkg.version,
+        "win32metadata": { "CompanyName": config.companyName, "FileDescription": config.description },
+        "asar": true,
+        "extraResource": [resources, ...config.nativeBridge ? [path.join(path.dirname(resources), "native")] : []],
+        "ignore": [/^\/native(?:\/|$)/, /^\/resources(?:\/|$)/, /^\/icons(?:\/|$)/, /^\/forge\.config\.[cm]?js$/, /^\/entitlements\.plist$/, /(?:^|\/)steam_appid\.txt$/],
+        ...os !== "linux" && config.icons[os] ? { "icon": path.resolve(root, config.icons[os]) } : {},
+        ...os === "macos" && config.macos.localNetworkUsageDescription ? {
+            "extendInfo": { "NSLocalNetworkUsageDescription": config.macos.localNetworkUsageDescription },
+            "extendHelperInfo": { "NSLocalNetworkUsageDescription": config.macos.localNetworkUsageDescription }
+        } : {},
+        ...os === "macos" && sign ? {
+            "osxSign": {
+                "identity": process.env.APPLE_SIGNING_IDENTITY,
+                // Packager otherwise swallows signing failures and attempts notarization.
+                "continueOnError": false,
+                // Static web/localization data is sealed by its enclosing bundle.
+                // Keep native sidecars and libraries outside these exclusions.
+                "ignore": ["/Contents/Resources/resources/", "\\.lproj/locale\\.pak$"],
+                "optionsForFile": () => ({
+                    "hardenedRuntime": true,
+                    "entitlements": path.join(getTemplateDir("electron"), "entitlements.plist")
+                })
+            }
+        } : {},
+        ...os === "macos" && notarize ? { "osxNotarize": { "keychainProfile": process.env.APPLE_NOTARY_PROFILE } } : {}
+    };
+};

package/dist/electron-host.d.ts

@@ -0,0 +1,7 @@
+import type { IElectronConfig } from "./electron-config.js";
+/** Packager cleans its temporary root; never share that root with concurrent builds. */
+export declare const withElectronPackagerTemp: <T>(use: (directory: string) => Promise<T>) => Promise<T>;
+/** The builder pins the runtime; games need neither Electron nor its npm dependency tree. */
+export declare const getElectronVersion: () => string;
+/** No user files are written or removed. Each build gets an isolated, disposable host. */
+export declare const withElectronHost: <T>(root: string, resources: string, config: IElectronConfig, use: (directory: string) => Promise<T>, target?: string) => Promise<T>;

package/dist/electron-host.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getTemplateDir } from "./utils.js";
+import { stageNativeBridge } from "./electron-native.js";
+/** Packager cleans its temporary root; never share that root with concurrent builds. */
+export const withElectronPackagerTemp = async (use) => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "next2d-packager-"));
+    try {
+        return await use(dir);
+    }
+    finally {
+        fs.rmSync(dir, { "recursive": true, "force": true });
+    }
+};
+/** The builder pins the runtime; games need neither Electron nor its npm dependency tree. */
+export const getElectronVersion = () => {
+    const pkg = JSON.parse(fs.readFileSync(path.join(getTemplateDir("electron"), "package.json"), "utf8"));
+    const version = pkg.devDependencies.electron;
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) {
+        throw new Error("The builder's Electron template must pin an exact runtime version.");
+    }
+    return version;
+};
+/** No user files are written or removed. Each build gets an isolated, disposable host. */
+export const withElectronHost = async (root, resources, config, use, target) => {
+    if (!fs.statSync(path.join(resources, "index.html"), { "throwIfNoEntry": false })?.isFile()) {
+        throw new Error(`Electron web entry point is missing: ${resources}/index.html`);
+    }
+    const game = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "next2d-electron-"));
+    try {
+        for (const file of ["index.js", "local-assets.cjs", "native-bridge.cjs", "preload.cjs"]) {
+            fs.copyFileSync(path.join(getTemplateDir("electron"), file), path.join(dir, file));
+        }
+        const pkg = {
+            "name": game.name, "version": game.version, "description": config.description,
+            "private": true, "type": "commonjs", "main": "index.js"
+        };
+        fs.writeFileSync(path.join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+        fs.cpSync(resources, path.join(dir, "resources"), { "recursive": true });
+        const nativeBridge = config.nativeBridge ? stageNativeBridge(root, dir, config.nativeBridge, target ?? "") : undefined;
+        const runtime = { "appId": config.appId, "appName": config.appName, "window": config.window, "icon": "", nativeBridge };
+        if (config.icons.linux) {
+            fs.copyFileSync(path.resolve(root, config.icons.linux), path.join(dir, "resources/desktop-icon.png"));
+            runtime.icon = "desktop-icon.png";
+        }
+        fs.writeFileSync(path.join(dir, "runtime-config.json"), `${JSON.stringify(runtime, null, 2)}\n`);
+        return await use(dir);
+    }
+    finally {
+        fs.rmSync(dir, { "recursive": true, "force": true });
+    }
+};

package/dist/electron-native.d.ts

@@ -0,0 +1,15 @@
+export interface INativeBridgeConfig {
+    methods: string[];
+    targets: Record<string, {
+        directory: string;
+        executable: string;
+    }>;
+    backgroundThrottling?: boolean;
+    prepare?: string;
+}
+export declare const validateNativeBridge: (value: INativeBridgeConfig | undefined) => void;
+export declare const stageNativeBridge: (root: string, host: string, config: INativeBridgeConfig, target: string) => {
+    backgroundThrottling?: boolean | undefined;
+    executable: string;
+    methods: string[];
+};