@next2d/builder 0.3.1 → 0.4.1

package/README.md

@@ -31,7 +31,7 @@ Xbox対応は試作・開発段階です。
 
 | ガイド | 内容 |
 |---|---|
-| [Electron / Steam](docs/steam.md#日本語) | デスクトップ書き出し、アイコン、CPU、署名、Steam Depot、アップロード、ベータテスト |
+| [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#日本語) | 開発状況、ホスト生成、ビルド環境、検証範囲 |
@@ -82,7 +82,7 @@ These guides cover platform-specific configuration, dependencies, builds and dis
 
 | Guide | Contents |
 |---|---|
-| [Electron / Steam](docs/steam.md#english) | Desktop exports, icons, architectures, signing, Steam depots, uploads and beta testing |
+| [Electron / Steam](docs/steam.md#english) | Desktop exports, icons, architectures, overlay windows, 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 |

package/dist/electron-config.d.ts

@@ -1,5 +1,10 @@
 import type { INativeBridgeConfig } from "./electron-native.js";
 export type ElectronOS = "windows" | "macos" | "linux";
+export interface IElectronOverlayConfig {
+    enabled: boolean;
+    anchor: "bottom";
+    clickThrough: boolean;
+}
 export interface IElectronConfig {
     nativeBridge?: INativeBridgeConfig;
     appId: string;
@@ -13,6 +18,7 @@ export interface IElectronConfig {
         width: number;
         height: number;
         fullscreen: boolean;
+        overlay?: IElectronOverlayConfig;
     };
     steam?: {
         appId: string | null;

package/dist/electron-config.js

@@ -56,6 +56,24 @@ export const readElectronConfig = (root) => {
             throw new Error("Electron fullscreen/sign/notarize options must be booleans.");
         }
     }
+    const overlay = config.window.overlay;
+    if (overlay !== undefined) {
+        if (!overlay || typeof overlay !== "object" || Array.isArray(overlay)) {
+            throw new Error("electron.config.json window.overlay must be an object.");
+        }
+        config.window.overlay = { "enabled": false, "anchor": "bottom", "clickThrough": false, ...overlay };
+        const { enabled, anchor, clickThrough } = config.window.overlay;
+        if (typeof enabled !== "boolean" || typeof clickThrough !== "boolean") {
+            throw new Error("electron.config.json window.overlay.enabled/clickThrough must be booleans.");
+        }
+        if (anchor !== "bottom") {
+            throw new Error("electron.config.json window.overlay.anchor must be \"bottom\".");
+        }
+        // A transparent desktop overlay is never a fullscreen game window.
+        if (enabled) {
+            config.window.fullscreen = false;
+        }
+    }
     if (config.macos.notarize && !config.macos.sign) {
         throw new Error("macos.notarize requires macos.sign.");
     }

package/docs/steam.md

@@ -78,6 +78,33 @@ Steamは複数Depotに対応。builderは各OSに1 IDまでで、一部OSだけ
 | `macos.sign` / `macos.notarize` | ローカル検証は `false`、配布時は両方 `true`。 |
 | `macos.localNetworkUsageDescription` | LAN通信の利用目的。指定時のみ、メインアプリとElectron HelperのInfo.plistへ`NSLocalNetworkUsageDescription`を設定する。macOSの許可操作はユーザーが行う。 |
 
+#### オーバーレイウィンドウ
+
+デスクトップ上に常駐するマスコット等向けに、透明・枠なし・最前面のウィンドウを作れます。`window.overlay` 未指定または `enabled: false` なら従来どおりです。
+
+```json
+"window": {
+  "width": 1920, "height": 420, "fullscreen": false,
+  "overlay": { "enabled": true, "anchor": "bottom", "clickThrough": true }
+}
+```
+
+| 項目 | 内容 |
+|---|---|
+| `enabled` | `true` で透明・枠なし・リサイズ不可・影なし・最前面（macOSは全ワークスペース・全画面アプリ上にも表示）。タスクバーには表示。`fullscreen` は `false` 扱い、F11／Alt+Enterは無効。既定 `false` |
+| `anchor` | `"bottom"` のみ（既定）。主ディスプレイの作業領域（タスクバー・Dockを除く）の下端・水平中央に配置。幅・高さは作業領域を超えない。ディスプレイ構成の変更時に再配置 |
+| `clickThrough` | `true` で起動時からクリック透過（マウス移動は届く）。既定 `false` |
+
+有効時のみ、rendererへ `window.next2dWindow` を公開します（アプリのメインフレームのみ）。
+
+```ts
+await window.next2dWindow?.setIgnoreMouseEvents(false); // キャラクター上では操作を受け付ける
+const { x, y, width, height, scaleFactor } = await window.next2dWindow.getBounds();
+await window.next2dWindow.quit();
+```
+
+Linuxの透明表示はコンポジタが必要です。
+
 ### STEP4：認証を用意する
 
 #### macOSの署名・公証
@@ -267,6 +294,33 @@ Edit the configuration at the game root. The version comes from the root `packag
 | `steam.branch` | Target branch; defaults to `internal`. |
 | `macos.sign` / `macos.notarize` | Both `false` for local testing; both `true` for distribution. |
 
+#### Overlay window
+
+Creates a transparent, frameless, always-on-top window for desktop companions and similar apps. Without `window.overlay`, or with `enabled: false`, the window behaves as before.
+
+```json
+"window": {
+  "width": 1920, "height": 420, "fullscreen": false,
+  "overlay": { "enabled": true, "anchor": "bottom", "clickThrough": true }
+}
+```
+
+| Field | Behaviour |
+|---|---|
+| `enabled` | `true` makes the window transparent, frameless, non-resizable, shadowless and always on top (on macOS also on every workspace and above fullscreen apps). It stays in the taskbar. `fullscreen` is treated as `false`; F11 / Alt+Enter are disabled. Default `false`. |
+| `anchor` | Only `"bottom"` (default): bottom edge of the primary display's work area (excluding taskbar/Dock), centred horizontally, never larger than the work area. Repositioned when displays change. |
+| `clickThrough` | `true` starts with mouse clicks passing through (mouse moves are still forwarded). Default `false`. |
+
+Only when enabled, the renderer gets `window.next2dWindow` (app main frame only):
+
+```ts
+await window.next2dWindow?.setIgnoreMouseEvents(false); // accept input while over the character
+const { x, y, width, height, scaleFactor } = await window.next2dWindow.getBounds();
+await window.next2dWindow.quit();
+```
+
+Transparency on Linux requires a compositor.
+
 ### STEP4: Prepare credentials
 
 #### macOS signing and notarization

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next2d/builder",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Multi-platform builder for Next2d Framework, supporting export to various platforms such as macOS, Windows, iOS, Android and Web(HTML)",
   "author": "Toshiyuki Ienaga <ienaga@next2d.app>",
   "license": "MIT",
@@ -42,13 +42,13 @@
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.7",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^26.6.4",
-    "@typescript-eslint/eslint-plugin": "^8.71.0",
-    "@typescript-eslint/parser": "^8.71.0",
-    "eslint": "^10.11.0",
+    "@types/node": "^26.6.6",
+    "@typescript-eslint/eslint-plugin": "^8.72.1",
+    "@typescript-eslint/parser": "^8.72.1",
+    "eslint": "^10.14.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^17.13.0",
     "typescript": "^6.0.3",
-    "vite": "^8.3.2"
+    "vite": "^8.3.5"
   }
 }

package/templates/electron/index.js

@@ -24,25 +24,65 @@ protocol.registerSchemesAsPrivileged([{
 }]);
 
 const startURL = "next2d://game/index.html";
+const overlay = config.window.overlay?.enabled ? config.window.overlay : null;
 let mainWindow;
+// Bottom anchor: flush with the primary display's work area (above the taskbar/Dock), centred.
+const overlayBounds = () => {
+    const { workArea } = screen.getPrimaryDisplay();
+    const width = Math.min(config.window.width, workArea.width);
+    const height = Math.min(config.window.height, workArea.height);
+    return {
+        x: workArea.x + Math.floor((workArea.width - width) / 2),
+        y: workArea.y + workArea.height - height,
+        width, height
+    };
+};
+const placeOverlay = () => {
+    if (mainWindow && !mainWindow.isDestroyed()) mainWindow.setBounds(overlayBounds());
+};
 const createWindow = async () => {
     const { width, height } = screen.getPrimaryDisplay().workAreaSize;
+    // The preload reads these flags; each API is exposed only when its feature is configured.
+    const preloadFlags = [
+        ...(config.nativeBridge ? ["--next2d-native-bridge"] : []),
+        ...(overlay ? ["--next2d-overlay"] : [])
+    ];
     mainWindow = new BrowserWindow({
         width: Math.min(config.window.width, width),
         height: Math.min(config.window.height, height),
         title: config.appName,
-        fullscreen: config.window.fullscreen,
+        fullscreen: overlay ? false : config.window.fullscreen,
         ...(config.icon ? { icon: path.join(assetRoot, config.icon) } : {}),
         useContentSize: true,
         backgroundColor: "#000000",
         autoHideMenuBar: true,
         show: false,
+        ...(overlay ? {
+            ...overlayBounds(), transparent: true, frame: false, resizable: false, hasShadow: false,
+            fullscreenable: false, skipTaskbar: false, backgroundColor: "#00000000",
+            // The overlay must never take keyboard focus or activation from the apps under it (Word etc.).
+            focusable: false
+        } : {}),
         webPreferences: {
             nodeIntegration: false, contextIsolation: true, sandbox: true,
-            ...(config.nativeBridge ? { preload: path.join(__dirname, "preload.cjs"),
-                backgroundThrottling: config.nativeBridge.backgroundThrottling ?? false } : {})
+            ...(preloadFlags.length ? { preload: path.join(__dirname, "preload.cjs"), additionalArguments: preloadFlags } : {}),
+            ...(config.nativeBridge ? { backgroundThrottling: config.nativeBridge.backgroundThrottling ?? false } : {})
         }
     });
+    if (overlay) {
+        mainWindow.setAlwaysOnTop(true, "floating");
+        if (process.platform === "darwin") {
+            mainWindow.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+        }
+        if (overlay.clickThrough) {
+            mainWindow.setIgnoreMouseEvents(true, { forward: true });
+        }
+        const events = ["display-metrics-changed", "display-added", "display-removed"];
+        for (const name of events) screen.on(name, placeOverlay);
+        mainWindow.once("closed", () => {
+            for (const name of events) screen.removeListener(name, placeOverlay);
+        });
+    }
     mainWindow.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
     mainWindow.webContents.on("will-navigate", (event, url) => {
         if (!resolveAssetPath(assetRoot, url)) {
@@ -50,7 +90,7 @@ const createWindow = async () => {
         }
     });
     mainWindow.webContents.on("before-input-event", (event, input) => {
-        if (input.type !== "keyDown") {
+        if (input.type !== "keyDown" || overlay) {
             return;
         }
         if (input.key === "F11" || (input.alt && input.key === "Enter")) {
@@ -66,7 +106,7 @@ const createWindow = async () => {
         closeNativeBridge();
         app.exit(1);
     });
-    mainWindow.once("ready-to-show", () => mainWindow.show());
+    mainWindow.once("ready-to-show", () => (overlay ? mainWindow.showInactive() : mainWindow.show()));
     await mainWindow.loadURL(startURL);
 };
 
@@ -75,9 +115,9 @@ app.whenReady().then(async () => {
         { role: "appMenu" }, { role: "editMenu" }, { role: "windowMenu" }
     ]) : null);
     session.defaultSession.setPermissionRequestHandler((_contents, permission, callback) => {
-        callback(permission === "fullscreen");
+        callback(!overlay && permission === "fullscreen");
     });
-    session.defaultSession.setPermissionCheckHandler((_contents, permission) => permission === "fullscreen");
+    session.defaultSession.setPermissionCheckHandler((_contents, permission) => !overlay && permission === "fullscreen");
     protocol.handle("next2d", async (request) => {
         let asset = resolveAssetPath(assetRoot, request.url);
         if (!asset || request.method !== "GET") {
@@ -109,6 +149,26 @@ app.whenReady().then(async () => {
             return nativeBridge.request(method, params);
         });
     }
+    if (overlay) {
+        const trusted = (event) => {
+            if (!isTrustedSender(event, mainWindow)) throw new Error("Window API access denied");
+        };
+        ipcMain.handle("next2d:window:set-ignore-mouse-events", (event, ignore) => {
+            trusted(event);
+            if (typeof ignore !== "boolean") throw new TypeError("ignore must be a boolean");
+            mainWindow.setIgnoreMouseEvents(ignore, ignore ? { forward: true } : undefined);
+        });
+        ipcMain.handle("next2d:window:get-bounds", (event) => {
+            trusted(event);
+            const bounds = mainWindow.getBounds();
+            return { ...bounds, scaleFactor: screen.getDisplayMatching(bounds).scaleFactor };
+        });
+        ipcMain.handle("next2d:window:quit", (event) => {
+            trusted(event);
+            // Reply before the window is torn down.
+            setImmediate(() => app.quit());
+        });
+    }
     await createWindow();
 }).catch((error) => {
     console.error(error);

package/templates/electron/preload.cjs

@@ -1,11 +1,26 @@
 const { contextBridge, ipcRenderer } = require("electron");
+// Set by the main process through webPreferences.additionalArguments.
+const flags = new Set(process.argv);
 
-contextBridge.exposeInMainWorld("next2dNative", {
-    request: (method, params) => ipcRenderer.invoke("next2d:native:request", method, params),
-    onEvent: (listener) => {
-        if (typeof listener !== "function") throw new TypeError("Expected event listener");
-        const handler = (_event, message) => listener(message);
-        ipcRenderer.on("next2d:native:event", handler);
-        return () => ipcRenderer.removeListener("next2d:native:event", handler);
-    }
-});
+if (flags.has("--next2d-native-bridge")) {
+    contextBridge.exposeInMainWorld("next2dNative", {
+        request: (method, params) => ipcRenderer.invoke("next2d:native:request", method, params),
+        onEvent: (listener) => {
+            if (typeof listener !== "function") throw new TypeError("Expected event listener");
+            const handler = (_event, message) => listener(message);
+            ipcRenderer.on("next2d:native:event", handler);
+            return () => ipcRenderer.removeListener("next2d:native:event", handler);
+        }
+    });
+}
+
+if (flags.has("--next2d-overlay")) {
+    contextBridge.exposeInMainWorld("next2dWindow", {
+        setIgnoreMouseEvents: async (ignore) => {
+            if (typeof ignore !== "boolean") throw new TypeError("Expected boolean");
+            await ipcRenderer.invoke("next2d:window:set-ignore-mouse-events", ignore);
+        },
+        getBounds: () => ipcRenderer.invoke("next2d:window:get-bounds"),
+        quit: async () => { await ipcRenderer.invoke("next2d:window:quit"); }
+    });
+}