@next2d/builder 0.1.11 → 0.3.0

package/dist/xbox.js

@@ -1,12 +1,12 @@
 // Xbox (GDK ネイティブ) ビルド。V8 に Next2D の JS を載せ、Dawn(WebGPU/D3D12)で
 // 描画する C++ ホストを、テンプレートのスキャフォールド → 資材配置 → pak 埋め込み →
 // CMake/GDK ビルドの順で書き出す。
-import pc from "picocolors";
+import pc from "./colors.js";
 import fs from "fs";
 import os from "os";
 import path from "path";
 import cp from "child_process";
-import { minifySync } from "vite";
+import { loadProjectVite } from "./project-vite.js";
 import { ctx } from "./context.js";
 import { getTemplateDir } from "./utils.js";
 import { XBOX_DIR_NAME, XBOX_CONFIG_NAME, XBOX_V8_VERSION, XBOX_V8_REVISION, XBOX_SCAFFOLD_EXCLUDES } from "./constants.js";
@@ -184,9 +184,15 @@ export const renderAssetsRc = (pakAbsPath) => {
  * @method
  * @public
  */
-export const minifyJs = (name, code) => {
+export const minifyJs = async (name, code) => {
     try {
-        const result = minifySync(name, code);
+        const vite = await loadProjectVite();
+        if (typeof vite.minifySync !== "function") {
+            // Vite 7 exposes esbuild rather than the Oxc minifier used by Vite 8.
+            const result = await vite.transformWithEsbuild(code, name, { "minify": true, "legalComments": "none" });
+            return result.code;
+        }
+        const result = vite.minifySync(name, code);
         if (result.errors && result.errors.length > 0) {
             const msg = result.errors[0]?.message ?? String(result.errors[0]);
             console.log(pc.yellow(`Xbox: minify skipped for ${name} (${msg}); embedding as-is.`));
@@ -215,62 +221,59 @@ export const minifyJs = (name, code) => {
  * @method
  * @private
  */
-const embedXboxAssets = () => {
-    return new Promise((resolve, reject) => {
-        const xboxDir = `${process.cwd()}/${XBOX_DIR_NAME}`;
-        const pakPath = `${xboxDir}/assets.pak`;
-        const rcPath = `${xboxDir}/assets.rc`;
-        try {
-            // 収集: assets/app 一式 (キーは app 基準) + host スクリプト (js/ 基準)。
-            const entries = [];
-            entries.push(...walkFiles(`${xboxDir}/assets/app`, ""));
-            const bootstrap = `${xboxDir}/js/bootstrap.js`;
-            if (fs.existsSync(bootstrap)) {
-                entries.push(["js/bootstrap.js", bootstrap]);
-            }
-            const selftest = `${xboxDir}/js/selftest.js`;
-            if (fs.existsSync(selftest)) {
-                entries.push(["js/selftest.js", selftest]);
-            }
-            if (entries.length === 0) {
-                return reject("No Xbox assets found to embed (assets/app is empty).");
-            }
-            // (key, データ) を読み込み、pak バイナリへ直列化する。
-            // js/ のホストスクリプト(bootstrap.js/selftest.js)は minify + 難読化する。
-            // assets/app の JS は vite が本番ビルドで minify 済みのためそのまま。
-            let minified = 0;
-            const pakEntries = entries.map(([key, abs]) => {
-                if (key.startsWith("js/") && key.endsWith(".js")) {
-                    const src = fs.readFileSync(abs, { "encoding": "utf8" });
-                    const out = minifyJs(key, src);
-                    if (out.length < src.length) {
-                        ++minified;
-                    }
-                    return [key, Buffer.from(out, "utf8")];
+const embedXboxAssets = async () => {
+    const xboxDir = `${process.cwd()}/${XBOX_DIR_NAME}`;
+    const pakPath = `${xboxDir}/assets.pak`;
+    const rcPath = `${xboxDir}/assets.rc`;
+    try {
+        // 収集: assets/app 一式 (キーは app 基準) + host スクリプト (js/ 基準)。
+        const entries = [];
+        entries.push(...walkFiles(`${xboxDir}/assets/app`, ""));
+        const bootstrap = `${xboxDir}/js/bootstrap.js`;
+        if (fs.existsSync(bootstrap)) {
+            entries.push(["js/bootstrap.js", bootstrap]);
+        }
+        const selftest = `${xboxDir}/js/selftest.js`;
+        if (fs.existsSync(selftest)) {
+            entries.push(["js/selftest.js", selftest]);
+        }
+        if (entries.length === 0) {
+            throw new Error("No Xbox assets found to embed (assets/app is empty).");
+        }
+        // (key, データ) を読み込み、pak バイナリへ直列化する。
+        // js/ のホストスクリプト(bootstrap.js/selftest.js)は minify + 難読化する。
+        // assets/app の JS は vite が本番ビルドで minify 済みのためそのまま。
+        let minified = 0;
+        const pakEntries = await Promise.all(entries.map(async ([key, abs]) => {
+            if (key.startsWith("js/") && key.endsWith(".js")) {
+                const src = fs.readFileSync(abs, { "encoding": "utf8" });
+                const out = await minifyJs(key, src);
+                if (out.length < src.length) {
+                    ++minified;
                 }
-                return [key, fs.readFileSync(abs)];
-            });
-            const pak = buildPak(pakEntries);
-            if (minified > 0) {
-                console.log(pc.green(`Minified ${minified} host script(s) before embedding.`));
+                return [key, Buffer.from(out, "utf8")];
             }
-            fs.writeFileSync(pakPath, pak);
-            // rc.exe が assets.pak を RCDATA "N2DASSETS" として取り込む .rc を生成する。
-            fs.writeFileSync(rcPath, renderAssetsRc(path.resolve(pakPath)), "utf8");
-            console.log(pc.green(`Embedded ${entries.length} Xbox asset file(s) into assets.pak `
-                + `(${(pak.length / 1024 / 1024).toFixed(2)} MB).`));
-            // 埋め込み済みの平文 `assets/`・`js/` は書き出し一覧から除外する。
-            // これらは assets.pak (=exe 内 RCDATA) に格納済みで、CMake も埋め込みモードでは
-            // exe 隣へステージしないため、xbox/ 直下に残しても不要かつ平文流出になる。
-            fs.rmSync(`${xboxDir}/assets`, { "recursive": true, "force": true });
-            fs.rmSync(`${xboxDir}/js`, { "recursive": true, "force": true });
-            console.log(pc.green("Excluded plaintext `assets/` and `js/` from the export (embedded in exe)."));
-            resolve();
-        }
-        catch (error) {
-            reject(`Failed to embed Xbox assets. ${error}`);
+            return [key, fs.readFileSync(abs)];
+        }));
+        const pak = buildPak(pakEntries);
+        if (minified > 0) {
+            console.log(pc.green(`Minified ${minified} host script(s) before embedding.`));
         }
-    });
+        fs.writeFileSync(pakPath, pak);
+        // rc.exe が assets.pak を RCDATA "N2DASSETS" として取り込む .rc を生成する。
+        fs.writeFileSync(rcPath, renderAssetsRc(path.resolve(pakPath)), "utf8");
+        console.log(pc.green(`Embedded ${entries.length} Xbox asset file(s) into assets.pak `
+            + `(${(pak.length / 1024 / 1024).toFixed(2)} MB).`));
+        // 埋め込み済みの平文 `assets/`・`js/` は書き出し一覧から除外する。
+        // これらは assets.pak (=exe 内 RCDATA) に格納済みで、CMake も埋め込みモードでは
+        // exe 隣へステージしないため、xbox/ 直下に残しても不要かつ平文流出になる。
+        fs.rmSync(`${xboxDir}/assets`, { "recursive": true, "force": true });
+        fs.rmSync(`${xboxDir}/js`, { "recursive": true, "force": true });
+        console.log(pc.green("Excluded plaintext `assets/` and `js/` from the export (embedded in exe)."));
+    }
+    catch (error) {
+        throw new Error(`Failed to embed Xbox assets. ${error}`);
+    }
 };
 /**
  * @description Xbox ビルドに使う V8 のパスを解決する。優先順:

package/docs/capacitor.md

@@ -0,0 +1,201 @@
+# iOS / Android（Capacitor）
+
+[日本語](#日本語) | [English](#english)
+
+## 日本語
+
+### STEP1：対象OSのIDE・SDKを用意する
+
+| 対象 | ユーザーが用意するもの |
+|---|---|
+| iOS | macOS、Xcode本体とiOS SDK。Xcodeを初回起動してセットアップを完了する。 |
+| Android | Android Studio、Android SDK、使用するCapacitorに対応したJDK。 |
+| 実機・配布ビルド | 対象端末と、その配布方法に必要な署名証明書・プロビジョニング設定またはAndroidの署名鍵。 |
+
+使用するCapacitorのバージョンはbuilderの `src/tool-packages.ts` で固定している。
+対応するネイティブ環境は[Capacitorの開発フロー](https://capacitorjs.com/docs/basics/workflow)から確認する。
+Capacitorの `cli`・`core`・`ios`・`android` はbuilderが同じバージョンで取得するため、手動インストールは不要。
+
+#### iOS：Xcodeの選択を確認する
+
+```sh
+xcode-select -p
+xcodebuild -version
+```
+
+`/Library/Developer/CommandLineTools` が選択されていると、IPA生成時に `xcodebuild requires Xcode` で失敗する。
+今回のシェルだけXcodeを指定する場合は、次を設定してからSTEP3へ進む:
+
+```sh
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+xcodebuild -version
+```
+
+システム全体の既定を変える場合は、代わりに次を使う:
+
+```sh
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+xcodebuild -version
+```
+
+Xcodeの配置先が異なる場合はパスを変更する。builderは呼び出し元の `DEVELOPER_DIR` を引き継ぐ。
+[Appleのコマンドラインツール設定](https://developer.apple.com/documentation/xcode/configuring-command-line-tools-settings)
+
+### STEP2：アプリ設定とプラグインを用意する
+
+ゲームルートの `capacitor.config.json` にアプリ固有の値を設定する。
+
+```json
+{
+  "appId": "app.example.game",
+  "appName": "My Game",
+  "webDir": "dist/ios/prd/"
+}
+```
+
+| 項目 | 設定・管理方法 |
+|---|---|
+| `appId` / `appName` | 自分のアプリ識別子・表示名に変更する。 |
+| `webDir` | builderが今回のWeb出力先に更新するため、OSごとの手動切り替えは不要。 |
+| `ios.path` / `android.path` | 必要な場合だけネイティブプロジェクトのカスタム出力先を指定する。 |
+| ゲーム固有のCapacitor/Cordovaプラグイン | ゲームの依存として管理する。ゲーム側のフックも引き続き使用する。 |
+| `@capacitor/core` | ゲームのJavaScriptで直接importする場合だけ、builderのCapacitorと互換性のあるバージョンをゲームの直接依存に追加する。 |
+
+その他の項目は[Capacitor設定](https://capacitorjs.com/docs/config)を参照。
+
+### STEP3：ネイティブプロジェクトを開き、署名・アイコンを設定する
+
+対象OSのコマンドを実行する。
+
+```sh
+npx @next2d/builder --platform ios --env prd --open
+npx @next2d/builder --platform android --env prd --open
+```
+
+未作成の `ios/` / `android/` を生成し、Web資産とネイティブ依存を同期してIDEを開く。
+Xcode / Android Studioで、アプリのアイコン・署名・配布方法に必要な設定を行う。
+これらのネイティブプロジェクトはゲーム側で保持する。再実行時も既存の設定・ネイティブコードを維持する。
+
+### STEP4：ビルドして対象環境で確認する
+
+```sh
+npx @next2d/builder --platform ios --env prd --build
+npx @next2d/builder --platform android --env prd --build
+```
+
+実行前にWeb資産・ネイティブ依存を再同期する。対象端末やシミュレーター／エミュレーターで起動・入力・保存を確認する。
+Capacitorの `cap run` を使う場合は `--build` を `--preview` に置き換える。
+途中のコマンドが失敗した場合はbuilderも失敗する。
+
+テンプレートのnpmスクリプト `open:ios` / `open:android` / `build:ios` / `build:android` も使用できる。
+環境指定は `npm run build:ios -- --env prd` のように渡す。
+
+### 補足：既存プロジェクトの移行とSDKキャッシュ
+
+1. ゲームから不要になった `@capacitor/cli`・`@capacitor/ios`・`@capacitor/android` の直接依存を外す。
+   `@capacitor/core` とゲーム固有プラグインはSTEP2の条件に従う。
+2. 設定と `ios/` / `android/` は保持し、STEP3でネイティブ依存の参照先を再同期する。
+
+builderはゲームルートでCapacitor CLIを実行し、取得したSDKのパスを子プロセスの `NODE_PATH` に追加する。
+通常・ネストされたnpm依存配置や `file:../builder` に対応し、ゲーム側の補助スクリプトやSDKシンボリックリンクは不要。
+SDKキャッシュは書き出し後もGradle / CocoaPodsが参照するため保持する。
+npxキャッシュを削除した場合は、STEP3またはSTEP4で参照先を再同期する。
+
+## English
+
+### STEP1: Prepare the platform IDE and SDK
+
+| Target | What you need to prepare |
+|---|---|
+| iOS | macOS, the full Xcode application and the iOS SDK. Complete Xcode's first-launch setup. |
+| Android | Android Studio, the Android SDK and a JDK compatible with the Capacitor version in use. |
+| Device and distribution builds | Target devices and signing certificates/provisioning settings or an Android signing key, as required by the distribution method. |
+
+The builder pins the Capacitor version in `src/tool-packages.ts`.
+Check the corresponding native environment through the [Capacitor development workflow](https://capacitorjs.com/docs/basics/workflow).
+The builder acquires matching versions of Capacitor's `cli`, `core`, `ios` and `android`; no manual installation is needed.
+
+#### iOS: Check the selected Xcode
+
+```sh
+xcode-select -p
+xcodebuild -version
+```
+
+If `/Library/Developer/CommandLineTools` is selected, IPA generation fails with `xcodebuild requires Xcode`.
+To select Xcode for the current shell, set this before STEP3:
+
+```sh
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+xcodebuild -version
+```
+
+Alternatively, to change the system-wide default:
+
+```sh
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+xcodebuild -version
+```
+
+Adjust the path if Xcode is installed elsewhere. The builder inherits the caller's `DEVELOPER_DIR`.
+[Apple's command-line tools settings](https://developer.apple.com/documentation/xcode/configuring-command-line-tools-settings)
+
+### STEP2: Prepare app configuration and plugins
+
+Set game-specific values in `capacitor.config.json` at the game root.
+
+```json
+{
+  "appId": "app.example.game",
+  "appName": "My Game",
+  "webDir": "dist/ios/prd/"
+}
+```
+
+| Setting | Configuration / ownership |
+|---|---|
+| `appId` / `appName` | Replace with your app identifier and display name. |
+| `webDir` | The builder updates this to the current web output directory; no manual switching between operating systems is needed. |
+| `ios.path` / `android.path` | Set only when using custom native project locations. |
+| Game-specific Capacitor/Cordova plugins | Keep them in the game's dependencies. Game hooks continue to work. |
+| `@capacitor/core` | Add a compatible version as a direct game dependency only when the game's JavaScript imports it directly. |
+
+See [Capacitor configuration](https://capacitorjs.com/docs/config) for other settings.
+
+### STEP3: Open the native project and configure signing and icons
+
+Run the command for your target OS:
+
+```sh
+npx @next2d/builder --platform ios --env prd --open
+npx @next2d/builder --platform android --env prd --open
+```
+
+The builder creates missing `ios/` / `android/` projects, synchronizes web assets and native dependencies, then opens the IDE.
+Configure app icons, signing and distribution-specific settings in Xcode / Android Studio.
+Keep these native projects in the game. Subsequent runs preserve existing settings and native code.
+
+### STEP4: Build and verify on the target environment
+
+```sh
+npx @next2d/builder --platform ios --env prd --build
+npx @next2d/builder --platform android --env prd --build
+```
+
+Web assets and native dependencies are synchronized before building. Verify launch, input and saved data on target devices or simulators/emulators.
+Replace `--build` with `--preview` to use Capacitor's `cap run`.
+If any command fails, the builder fails as well.
+
+Template npm scripts `open:ios` / `open:android` / `build:ios` / `build:android` are also available.
+Pass the environment as in `npm run build:ios -- --env prd`.
+
+### Reference: Existing project migration and SDK cache
+
+1. Remove direct dependencies on `@capacitor/cli`, `@capacitor/ios` and `@capacitor/android` that are no longer needed by the game.
+   Follow STEP2 for `@capacitor/core` and game-specific plugins.
+2. Keep the configuration and `ios/` / `android/`, then use STEP3 to resynchronize native dependency paths.
+
+The builder runs the Capacitor CLI from the game root and adds acquired SDK paths to the child process's `NODE_PATH`.
+Regular and nested npm dependency layouts and `file:../builder` are supported; no game-side helper scripts or SDK symlinks are needed.
+Keep the SDK cache after export because Gradle / CocoaPods reference it.
+If you delete the npx cache, use STEP3 or STEP4 to resynchronize those paths.

package/docs/native-bridge.md

@@ -0,0 +1,147 @@
+# ネイティブ機能の拡張（Electron Native Bridge）
+
+Next2Dのデスクトップアプリから、OS APIや任意のネイティブSDKを利用するための汎用拡張です。EOS専用ではありません。ネイティブ機能はアプリ側が用意する実行ファイル（sidecar）に実装し、builderが起動・通信・同梱を担当します。
+
+対象はElectronのmacOS／Windows／LinuxとSteamデスクトップ出力です。WebブラウザやiOS／AndroidにはこのAPIは提供されません。モバイルは [Capacitorガイド](capacitor.md) を参照してください。
+
+## 責務と構成
+
+```text
+Next2Dアプリ → window.next2dNative → Electron IPC → ネイティブ実行ファイル
+                                                    └ OS API / 任意のSDK
+```
+
+- builder: CPU別ファイルの同梱、メソッド許可リスト、要求／応答・イベント通信、プロセス終了処理。
+- アプリ: ネイティブ処理と入力検証、各OS向けコンパイル、SDKの初期化・後始末、ライセンスと権限設定。
+- SDKの取得、ソースの自動コンパイル、認証・オンラインサービスの実装はbuilderの機能ではありません。
+- `nativeBridge` 未設定ならプロセスを起動せず、`window.next2dNative` も公開しません。
+
+## 1. ネイティブ実行ファイルを用意する
+
+後述のSidecarプロトコルを実装した実行ファイルを、アプリ側でOS・CPUごとに用意します。使用言語はC++／Rust／Swiftなどから選べます。以下の `native-helper` と `system.info` は設定・通信の説明用の名前であり、実装サンプルは同梱していません。
+
+## 2. electron.config.json に設定する
+
+既存のアプリ設定に追加します。
+
+```json
+{
+  "architectures": { "macos": "arm64" },
+  "nativeBridge": {
+    "methods": ["system.info"],
+    "backgroundThrottling": true,
+    "targets": {
+      "macos-arm64": { "directory": "native/macos-arm64", "executable": "native-helper" }
+    }
+  }
+}
+```
+
+| 設定 | 内容 |
+|---|---|
+| `methods` | rendererから許可するメソッド名。英字開始、英数字・`_`・`.`、最大64文字 |
+| `targets` | ビルドするOS・CPUに対応するネイティブファイル群 |
+| `directory` | プロジェクトルート基準のディレクトリ。絶対パスも可能。全体を同梱 |
+| `executable` | ディレクトリ直下の実行ファイル名。パスやシェルコマンドは不可 |
+| `backgroundThrottling` | `true` は非アクティブ時のrendererの処理抑制を許可。リアルタイム用途では `false`。既存利用との互換性のため省略時は `false` |
+
+バックグラウンド設定はrendererのタイマー・描画の指定であり、OS全体の省電力設定やsidecarのスケジューリングを変更しません。
+
+対応キーは `macos-arm64`／`macos-x64`／`macos-universal`／`windows-x64`／`windows-arm64`／`linux-x64`／`linux-arm64`。未用意のターゲットへの出力はエラーになります。macOS既定値はuniversalなので、上例はarm64を明示しています。universalは実行ファイルと依存ライブラリすべてが両CPU対応である必要があります。builderはCPU形式を検査・変換しません。
+
+専用ディレクトリには実行ファイルと必要なdylib／DLL／so、配布可能なデータだけを置きます。ソース、秘密鍵、管理者資格情報を置かないでください。シンボリックリンクと特殊ファイルは拒否します。
+
+## 3. Next2Dアプリから呼び出す
+
+```js
+const native = window.next2dNative;
+if (native) {
+    const unsubscribe = native.onEvent(({ event, data }) => {
+        if (event === "system.ready") console.log("Native helper ready", data);
+        if (event === "bridge.closed") console.error("Native helper closed", data);
+    });
+    try {
+        const info = await native.request("system.info", {});
+        console.log(info.platform, info.logicalProcessors);
+    } catch (error) {
+        console.error("Native request failed", error);
+    } finally {
+        unsubscribe(); // 継続監視する場合は画面・サービスの破棄時に解除
+    }
+}
+```
+
+`request(method, params)` は応答を返すPromise、`onEvent(listener)` は解除関数を返します。アプリの通信・デバイス操作層にラップし、UIとは分離してください。Node API・任意パス・汎用IPC・シェル実行はrendererへ公開しません。sandbox／contextIsolationを維持し、IPCはアプリのメインフレームに限定します。引数はsidecarでも検証してください。
+
+## 4. ビルド・配布
+
+```sh
+npx @next2d/builder --platform macos --arch arm64 --env local --preview
+npx @next2d/builder --platform macos --arch arm64 --env prd
+```
+
+ローカルのbuilderでは `npm run build` 後、ゲームプロジェクトから `node ../builder/dist/index.js ...` で実行できます。
+
+ネイティブファイルはASAR外の `process.resourcesPath/native`（macOSでは `.app/Contents/Resources/native`）へ配置され、Web配信する `resources` とは分離されます。共有ライブラリは実行ファイル相対で解決できるようにビルドしてください。最初の `request` で同梱実行ファイルが起動します。
+
+署名・公証は [デスクトップガイド](steam.md) の設定を使用し、実行ファイルと依存ライブラリを含む完成アプリで検証します。利用するOS機能に応じた説明文・権限・entitlement等は別途必要です。例えばLANアクセスでは `macos.localNetworkUsageDescription` を設定できます。単純なOS情報取得の例では必要ありません。
+
+ビルド専用設定は `NEXT2D_ELECTRON_CONFIG_FILE=/absolute/path/to/config.json` で指定可能です。存在しない指定先はエラーになります。一時設定はアプリ側で管理し、配布ディレクトリには混ぜないでください。同梱ファイルを秘密にする保証はありません。
+
+## Sidecarプロトコル v1
+
+stdin／stdoutでUTF-8 JSONを1行ずつ交換します。stdoutはプロトコル専用とし、各行をflushしてください。
+
+```json
+{"id":1,"method":"system.info","params":{}}
+{"id":1,"result":{"platform":"macos","logicalProcessors":8}}
+{"id":2,"error":"Unsupported method"}
+{"event":"system.ready","data":{"protocol":1}}
+```
+
+要求の整数IDを応答にそのまま返します。エラーは文字列の `error`、イベントは `event` と `data` を使います。`bridge.closed` はbuilder予約名です。業務エラーはその要求だけを失敗させます。
+
+- 1行最大256KiB、同時要求128件、応答待ち15秒。SDK用途に固有のメソッドは予約しません。
+- タイムアウトはネイティブ処理のキャンセルではありません。再試行・重複防止はアプリ側で設計します。
+- プロトコル違反・プロセス終了で待機中の要求を失敗させ、`bridge.closed` を通知。自動再起動はしません。
+- ブリッジの終了処理はstdinを閉じ、EOFでsidecarの後始末を促し、4秒後の強制終了を予約します。ただしElectron本体を4秒間終了待ちにする仕組みではなく、本体が先に終了するとタイマーは実行されません。必ずstdin EOFで速やかに終了する設計にしてください。プロトコル違反等では即時強制終了します。rendererクラッシュ時も終了処理を行いますが、強制終了・OS異常時の後始末は保証できません。
+- 外部サービスの切断・保存等は必要に応じて終了前に独自のメソッドで行います。別の常駐プロセスを起動せず、stdin EOFでも終了するよう実装してください。
+- stderrは読み捨て、rendererには転送しません。必要な診断ログはsidecar側で秘匿情報を除いて記録します。大量のイベントは発行元で制限・集約してください。
+
+現状は1アプリにつき1つのsidecarです。複数SDKを使う場合はその実行ファイル内でメソッドを振り分けます。動的な任意実行や複数プロセスのプラグイン管理機構ではありません。
+
+## ビルド時の準備スクリプト（任意）
+
+`nativeBridge.prepare` にプロジェクト相対の `.js` / `.mjs` / `.cjs` を指定すると、通常のデスクトップ／Steam書き出しで、ネイティブ同梱前にNode.jsスクリプトを実行します。CLI・環境名・出力先は変わりません。未指定の場合は従来どおり `targets` のディレクトリ全体をコピーします。
+
+```json
+{ "nativeBridge": {
+  "prepare": "scripts/prepare-native.mjs",
+  "methods": ["system.info"],
+  "targets": { "windows-x64": { "directory": "native/windows-x64", "executable": "helper.exe" } }
+} }
+```
+
+実行契約：`node <script> --target <OS-CPU> --source <絶対パス> --destination <絶対パス>`。cwdはプロジェクトルート。出力先はビルド専用の一時フォルダで、スクリプトが実行ファイル・ライブラリ・必要な設定だけを書き込みます。元ディレクトリがまだ存在しない場合のコンパイルもスクリプト側で行えます。プロセスの環境変数を継承し、シェルは介しません。終了コード非0・120秒タイムアウト・シンボリックリンク・実行ファイル欠落でビルドを停止します。
+
+このスクリプトはVite設定同様、信頼するプロジェクトのコードとして実行されます。OS権限を制限するサンドボックスではありません。スクリプト自体はプロジェクト外へ解決されるパスを拒否します。準備スクリプトのパスはrendererへ渡さず、準備済みファイルはWebアセットと分離します。一時フォルダは成功・失敗時に削除します。秘密情報をstdout/stderrへ出さないでください。
+
+## 応用例: Epic Online Services（EOS）
+
+EOSも上記と同じ汎用プロトコルを利用する一例です。builder内にEOS SDK・認証情報・Lobby/P2P実装はありません。
+
+```json
+{
+  "nativeBridge": {
+    "methods": ["eos.status", "match.open", "match.close", "lobby.create", "lobby.join", "p2p.send"],
+    "backgroundThrottling": false,
+    "targets": {
+      "macos-arm64": { "directory": "native/eos/macos-arm64", "executable": "eos-sidecar" }
+    }
+  }
+}
+```
+
+これらのメソッド名はアプリ側が定義する例で、builderの組み込みAPIではありません。アプリ側でEOS SDKを使うsidecarと各OS向けバイナリを作り、サービス設定・認証・退出・切断処理を実装します。rendererでは例えば `native.request("match.open", { protocol: 1, provider: "eos" })` をアプリ側の契約に合わせて呼び出します。
+
+SDKによるネイティブ処理とゲーム固有の同期・命中・勝敗処理は分離します。サービス設定・利用条件・認証方式、複数端末接続、切断時の処理はアプリ側で検証が必要です。管理者やサーバー用の資格情報を同梱しないでください。この設定だけで別の通信方式がEOSへ自動移行することはありません。