@next2d/builder 0.4.8 → 0.4.9

package/dist/electron-config.d.ts

@@ -13,6 +13,7 @@ export interface IElectronMiniConfig {
     anchor: ElectronMiniAnchor;
     margin: number;
     alwaysOnTop: boolean;
+    transparent: boolean;
 }
 export interface IElectronConfig {
     nativeBridge?: INativeBridgeConfig;

package/dist/electron-config.js

@@ -80,8 +80,8 @@ export const readElectronConfig = (root) => {
         if (!mini || typeof mini !== "object" || Array.isArray(mini)) {
             throw new Error("electron.config.json window.mini must be an object.");
         }
-        config.window.mini = { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true, ...mini };
-        const { width, height, anchor, margin, alwaysOnTop } = config.window.mini;
+        config.window.mini = { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true, "transparent": false, ...mini };
+        const { width, height, anchor, margin, alwaysOnTop, transparent } = config.window.mini;
         for (const dimension of [width, height]) {
             if (!Number.isInteger(dimension) || dimension < 1 || dimension > 16384) {
                 throw new Error("electron.config.json window.mini.width/height must be integers between 1 and 16384.");
@@ -96,6 +96,9 @@ export const readElectronConfig = (root) => {
         if (typeof alwaysOnTop !== "boolean") {
             throw new Error("electron.config.json window.mini.alwaysOnTop must be a boolean.");
         }
+        if (typeof transparent !== "boolean") {
+            throw new Error("electron.config.json window.mini.transparent must be a boolean.");
+        }
         // The overlay already is the small always-on-top window, and it never takes keyboard focus.
         if (config.window.overlay?.enabled) {
             throw new Error("electron.config.json window.mini cannot be combined with window.overlay.enabled.");

package/docs/steam.md

@@ -118,7 +118,7 @@ Linuxの透明表示はコンポジタが必要です。
 ```json
 "window": {
   "width": 1920, "height": 1080, "fullscreen": true,
-  "mini": { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true }
+  "mini": { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true, "transparent": false }
 }
 ```
 
@@ -128,6 +128,7 @@ Linuxの透明表示はコンポジタが必要です。
 | `anchor` | 初めて小窓にしたときの位置。`"bottom-right"`（既定）/ `"bottom-left"` / `"top-right"` / `"top-left"`。窓のある画面の作業領域（タスクバー・Dockを除く）の隅 |
 | `margin` | 隅からの間隔（px）。既定 `16` |
 | `alwaysOnTop` | `true`（既定）で小窓を最前面に置く（macOSは全ワークスペース・全画面アプリ上にも表示） |
+| `transparent` | `true` で背景が透明・枠なしの小窓にする（既定 `false`。下の「透明な小窓」） |
 
 小窓は通常の窓のまま（タイトルバーあり。タイトルバーで動かせる）で、キー入力も受け取ります。リサイズ・最大化・全画面はできません。動かした位置は、アプリを終了するまで次の小窓で使います。通常の窓に戻すと、小窓にする前の位置・大きさ・最大化・全画面に戻ります。小窓の間は F11／Alt+Enter／Esc で全画面を切り替えません（Esc はゲームに届きます）。
 
@@ -143,6 +144,27 @@ await window.next2dWindow.quit();
 
 `width` / `height` は窓の中身の大きさ（CSS ピクセル）です。Next2D のステージは縦横比を保ったまま窓に合わせて縮むため、1920×1080 のステージを 720×180 の小窓で表示すると、ステージの範囲は高さ 180・幅 320 になります（`options.fullScreen: true` なら、左右のステージの外も描かれます）。小窓用の表示は、この大きさに合わせてゲーム側で配置してください。
 
+##### 透明な小窓（`transparent: true`）
+
+`window.mini.transparent: true`（既定 `false`。`false` なら上の動作のまま）にすると、小窓が「背景が透明・枠なし・影なし」の窓になり、船などの絵だけがデスクトップに浮かびます。透明は窓の作成時にしか決められず（Windows では透明な窓を最大化・全画面にできません）、同じ窓の切り替えでは実現できないため、`setMode` は**窓を作り直します**。
+
+- `setMode("mini")`：透明・枠なし・リサイズ不可の新しい窓を `width`×`height` で `anchor`/`margin`（前回動かした位置があればそこ）に作って同じ URL を読み込み、通常の窓の状態（位置・大きさ・最大化・全画面）を記憶して閉じます。最前面（`alwaysOnTop: true`）、macOS は全ワークスペースに表示、キー入力は受け取ります（F10 などで戻せます）。
+- `setMode("full")`：記憶した状態（全画面を含む）の通常の窓を作り直し、小窓を閉じます。
+- ページは作り直しで破棄されます。**ゲームは切り替える前に自分で保存してください**（localStorage は同じ origin のまま引き継がれます）。新しいページは起動時に `getMode()` で今のモードを読んで表示を決めます（アプリ起動時は常に `"full"`）。
+- `setMode` の Promise は、新しい窓の読み込みが終わってから `{ mode, width, height }` で解決します。
+
+透明な小窓（`mode === "mini"`）の間だけ、次の API が `window.next2dWindow` に加わります（`transparent: false` では公開されません）。
+
+```ts
+// 作成直後は ignore=true：透明な部分は下のアプリへクリックを通し、マウスの移動だけページに届く。
+// 船の上にポインタがあるときだけ false にして、クリック・ドラッグを受け取る。
+await window.next2dWindow.setIgnoreMouseEvents(false);
+// 枠がないので、ゲーム側のドラッグで窓を動かす。作業領域の外には出ない。位置は次の小窓にも使う。
+await window.next2dWindow.moveBy(dx, dy);
+```
+
+Windows でスリープから復帰してもマウス転送が切れないよう、重ね表示と同様に転送フックを張り直します。Linux の透明表示にはコンポジタが必要です。
+
 ### STEP4：認証を用意する
 
 #### macOSの署名・公証
@@ -372,7 +394,7 @@ At run time the game can switch between its normal window (fullscreen included)
 ```json
 "window": {
   "width": 1920, "height": 1080, "fullscreen": true,
-  "mini": { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true }
+  "mini": { "width": 720, "height": 180, "anchor": "bottom-right", "margin": 16, "alwaysOnTop": true, "transparent": false }
 }
 ```
 
@@ -382,6 +404,7 @@ At run time the game can switch between its normal window (fullscreen included)
 | `anchor` | Where the small window first appears: `"bottom-right"` (default), `"bottom-left"`, `"top-right"` or `"top-left"` corner of the work area (taskbar/Dock excluded) of the display the window is on. |
 | `margin` | Distance from that corner in px. Default `16`. |
 | `alwaysOnTop` | `true` (default) keeps the small window on top (on macOS also on every workspace and above fullscreen apps). |
+| `transparent` | `true` makes it a transparent, frameless window (default `false`; see "Transparent small window" below). |
 
 The small window stays a normal window: it has a title bar (drag it to move the window) and takes keyboard input. It cannot be resized, maximized or made fullscreen. Where the player moves it is used for the next small window until the app quits. Switching back restores the position, size, maximized and fullscreen state from before. In the small window F11 / Alt+Enter / Escape do not toggle fullscreen (Escape reaches the game).
 
@@ -397,6 +420,27 @@ await window.next2dWindow.quit();
 
 `width` / `height` are the content size in CSS pixels. The Next2D stage keeps its aspect ratio when it is fitted into the window, so a 1920×1080 stage shown in a 720×180 window covers 320×180 (with `options.fullScreen: true` the area left and right of the stage is drawn too). Lay out the small-window view for that size in the game.
 
+##### Transparent small window (`transparent: true`)
+
+With `window.mini.transparent: true` (default `false`; `false` keeps the behaviour above) the small window becomes transparent, frameless and shadowless, so only what the game draws (a ship, say) floats on the desktop. Transparency can only be chosen when a window is created (and on Windows a transparent window cannot be maximized or made fullscreen), so one window cannot be reshaped into it: `setMode` **rebuilds the window**.
+
+- `setMode("mini")`: builds a new transparent, frameless, non-resizable window of `width`×`height` at `anchor`/`margin` (or where it was last moved), loads the same URL, remembers the state of the normal window (position, size, maximized, fullscreen) and closes it. It is always on top (`alwaysOnTop: true`), on every workspace on macOS, and takes keys (so a key such as F10 can switch back).
+- `setMode("full")`: rebuilds the normal window in the remembered state (fullscreen included) and closes the small one.
+- The page is destroyed by the rebuild, so **the game must save before switching** (localStorage carries over: same origin). The new page reads the current mode with `getMode()` at startup (the app always starts in `"full"`).
+- The promise of `setMode` resolves with `{ mode, width, height }` after the new window has finished loading.
+
+Only while the transparent small window is shown (`mode === "mini"`), `window.next2dWindow` also has these (not exposed when `transparent` is `false`):
+
+```ts
+// ignore=true right after creation: transparent parts let clicks fall through to the app below, and only mouse
+// moves reach the page. Set it to false while the pointer is over the ship to receive clicks and drags.
+await window.next2dWindow.setIgnoreMouseEvents(false);
+// There is no frame, so the game drags the window itself. It stays inside the work area; the position is reused by the next small window.
+await window.next2dWindow.moveBy(dx, dy);
+```
+
+Like the overlay, the mouse-forwarding hook is installed again after Windows resumes from sleep. 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.4.8",
+  "version": "0.4.9",
   "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",
@@ -43,12 +43,12 @@
     "@eslint/eslintrc": "^3.3.7",
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.6.6",
-    "@typescript-eslint/eslint-plugin": "^8.72.1",
-    "@typescript-eslint/parser": "^8.72.1",
+    "@typescript-eslint/eslint-plugin": "^8.72.2",
+    "@typescript-eslint/parser": "^8.72.2",
     "eslint": "^10.14.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^17.14.0",
     "typescript": "^6.0.3",
-    "vite": "^8.3.5"
+    "vite": "^8.3.8"
   }
 }

package/templates/electron/index.js

@@ -36,12 +36,17 @@ const startURL = "next2d://game/index.html";
 const overlay = config.window.overlay?.enabled ? config.window.overlay : null;
 // The game can switch between its normal window ("full") and a small always-on-top window ("mini") at run time.
 const mini = !overlay && config.window.mini ? config.window.mini : null;
+// mini.transparent: the small window is a different window (transparent, frameless), so a mode change builds a new
+// one instead of reshaping the same one. The page is gone after a change; the game saves before it switches.
+const miniTransparent = Boolean(mini?.transparent);
 let mainWindow;
 let windowMode = "full";
 // How the window looked before it became small, to put it back exactly (position, size, maximized, fullscreen).
 let fullState = null;
 // Where the player last left the small window (it has a title bar and can be moved).
 let miniPosition = null;
+// Transparent mini only: true while the window lets clicks fall through (mouse moves are still forwarded to the page).
+let miniIgnore = true;
 // Mode changes are applied one after another (leaving fullscreen is animated on macOS).
 let modeQueue = Promise.resolve();
 const alive = () => Boolean(mainWindow && !mainWindow.isDestroyed());
@@ -65,9 +70,7 @@ const setFullScreenAndWait = (win, value) => new Promise((resolve) => {
     win.once(value ? "enter-full-screen" : "leave-full-screen", finish);
     win.setFullScreen(value);
 });
-const cornerOf = (win) => {
-    const { width, height } = win.getBounds();
-    const { workArea } = screen.getDisplayMatching(win.getBounds());
+const cornerIn = (workArea, width, height) => {
     const right = mini.anchor.endsWith("right");
     const bottom = mini.anchor.startsWith("bottom");
     return {
@@ -75,6 +78,24 @@ const cornerOf = (win) => {
         y: bottom ? workArea.y + workArea.height - height - mini.margin : workArea.y + mini.margin
     };
 };
+const cornerOf = (win) => {
+    const { width, height } = win.getBounds();
+    return cornerIn(screen.getDisplayMatching(win.getBounds()).workArea, width, height);
+};
+// Transparent mini: a frameless window has no title bar, so its outer size is mini.width x mini.height.
+const miniWindowBounds = (display) => {
+    const { x, y } = miniPosition ?? cornerIn(display.workArea, mini.width, mini.height);
+    return { x, y, width: mini.width, height: mini.height };
+};
+// Keep the small window inside the work area of the display it is on.
+const clampToWorkArea = (bounds) => {
+    const { workArea } = screen.getDisplayMatching(bounds);
+    return {
+        ...bounds,
+        x: Math.round(Math.max(workArea.x, Math.min(bounds.x, workArea.x + workArea.width - bounds.width))),
+        y: Math.round(Math.max(workArea.y, Math.min(bounds.y, workArea.y + workArea.height - bounds.height)))
+    };
+};
 const toMini = async () => {
     const win = mainWindow;
     fullState = { bounds: win.getNormalBounds(), maximized: win.isMaximized(), fullScreen: win.isFullScreen() };
@@ -112,10 +133,42 @@ const toFull = async () => {
     win.focus();
     windowMode = "full";
 };
+// Transparent mini: build the other kind of window first (so the app never has zero windows), then close the old one.
+const swapWindow = async (mode) => {
+    const old = mainWindow;
+    const previous = windowMode;
+    if (mode === "mini") {
+        fullState = { bounds: old.getNormalBounds(), maximized: old.isMaximized(), fullScreen: old.isFullScreen() };
+        // Do not close a window that is in a fullscreen Space on macOS.
+        if (old.isFullScreen()) await setFullScreenAndWait(old, false);
+        miniIgnore = true;
+    } else {
+        const [x, y] = old.getPosition();
+        miniPosition = { x, y };
+    }
+    // The new page reads the mode with getMode() when it starts.
+    windowMode = mode;
+    const retire = (win) => {
+        if (win.isDestroyed()) return;
+        // Closing on purpose: do not treat the page going away as a crash.
+        win.webContents.removeAllListeners("render-process-gone");
+        win.destroy();
+    };
+    try {
+        await createWindow();
+    } catch (error) {
+        windowMode = previous;
+        const failed = mainWindow;
+        mainWindow = old;
+        if (failed && failed !== old) retire(failed);
+        throw error;
+    }
+    retire(old);
+};
 const setWindowMode = (mode) => {
     modeQueue = modeQueue.then(async () => {
         if (!alive() || mode === windowMode) return;
-        await (mode === "mini" ? toMini() : toFull());
+        await (miniTransparent ? swapWindow(mode) : mode === "mini" ? toMini() : toFull());
         mainWindow.webContents.send("next2d:window:mode", modeInfo());
     }).catch((error) => console.error("Window mode change failed:", error));
     return modeQueue.then(() => (alive() ? modeInfo() : { mode: windowMode, width: 0, height: 0 }));
@@ -147,7 +200,8 @@ const keepOnTop = () => {
 // when forwarding switches on. After sleep (closing the lid) the hook can be gone while Electron still thinks it is
 // installed, so the page never sees the pointer. Switching forwarding off and on again installs a fresh hook.
 const refreshForwarding = () => {
-    if (!overlayIgnore || !mainWindow || mainWindow.isDestroyed()) return;
+    const forwarding = overlay ? overlayIgnore : miniTransparent && windowMode === "mini" && miniIgnore;
+    if (!forwarding || !mainWindow || mainWindow.isDestroyed()) return;
     mainWindow.setIgnoreMouseEvents(false);
     mainWindow.setIgnoreMouseEvents(true, { forward: true });
 };
@@ -211,17 +265,21 @@ const recreateWindow = async () => {
 };
 const createWindow = async () => {
     const { width, height } = screen.getPrimaryDisplay().workAreaSize;
+    const miniWindow = miniTransparent && windowMode === "mini";
+    // Coming back to the normal window after a transparent mini: put it back as it was.
+    const restore = miniTransparent && windowMode === "full" ? fullState : null;
     // 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"] : []),
-        ...(mini ? ["--next2d-window-mode"] : [])
+        ...(mini ? ["--next2d-window-mode"] : []),
+        ...(miniWindow ? ["--next2d-mini-transparent"] : [])
     ];
     mainWindow = new BrowserWindow({
         width: Math.min(config.window.width, width),
         height: Math.min(config.window.height, height),
         title: config.appName,
-        fullscreen: overlay ? false : config.window.fullscreen,
+        fullscreen: overlay || miniWindow ? false : restore ? restore.fullScreen : config.window.fullscreen,
         ...(config.icon ? { icon: path.join(assetRoot, config.icon) } : {}),
         useContentSize: true,
         backgroundColor: "#000000",
@@ -233,12 +291,35 @@ const createWindow = async () => {
             // The overlay must never take keyboard focus or activation from the apps under it (Word etc.).
             focusable: false
         } : {}),
+        ...(miniWindow ? {
+            ...miniWindowBounds(screen.getDisplayMatching(mainWindow && !mainWindow.isDestroyed() ? mainWindow.getBounds() : screen.getPrimaryDisplay().bounds)),
+            transparent: true, frame: false, resizable: false, maximizable: false, hasShadow: false,
+            fullscreenable: false, backgroundColor: "#00000000",
+            // Unlike the overlay it takes keys (the game's key to go back to the normal window).
+            focusable: true
+        } : {}),
         webPreferences: {
             nodeIntegration: false, contextIsolation: true, sandbox: true,
             ...(preloadFlags.length ? { preload: path.join(__dirname, "preload.cjs"), additionalArguments: preloadFlags } : {}),
             ...(config.nativeBridge ? { backgroundThrottling: config.nativeBridge.backgroundThrottling ?? false } : {})
         }
     });
+    if (restore) {
+        mainWindow.setBounds(restore.bounds);
+        if (restore.maximized) mainWindow.maximize();
+    }
+    if (miniWindow) {
+        if (mini.alwaysOnTop) {
+            mainWindow.setAlwaysOnTop(true, "floating");
+            if (process.platform === "darwin") mainWindow.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
+        }
+        mainWindow.setIgnoreMouseEvents(true, { forward: true });
+        if (process.platform === "win32") {
+            const timer = setInterval(() => { if (mini.alwaysOnTop) keepOnTop(); refreshForwarding(); }, 3000);
+            timer.unref?.();
+            mainWindow.once("closed", () => clearInterval(timer));
+        }
+    }
     if (overlay) {
         mainWindow.setAlwaysOnTop(true, "floating");
         if (process.platform === "darwin") {
@@ -375,6 +456,29 @@ app.whenReady().then(async () => {
             return setWindowMode(mode);
         });
     }
+    if (miniTransparent) {
+        const inTransparentMini = () => {
+            if (windowMode !== "mini") throw new Error("Only available in the transparent mini window");
+        };
+        ipcMain.handle("next2d:window:set-ignore-mouse-events", (event, ignore) => {
+            trusted(event);
+            inTransparentMini();
+            if (typeof ignore !== "boolean") throw new TypeError("ignore must be a boolean");
+            miniIgnore = ignore;
+            mainWindow.setIgnoreMouseEvents(ignore, ignore ? { forward: true } : undefined);
+        });
+        ipcMain.handle("next2d:window:move-by", (event, dx, dy) => {
+            trusted(event);
+            inTransparentMini();
+            if (!Number.isFinite(dx) || !Number.isFinite(dy)) throw new TypeError("dx and dy must be finite numbers");
+            const bounds = mainWindow.getBounds();
+            const next = clampToWorkArea({ ...bounds, x: bounds.x + Math.round(dx), y: bounds.y + Math.round(dy) });
+            mainWindow.setBounds(next);
+            miniPosition = { x: next.x, y: next.y };
+        });
+        // After sleep the forwarding hook can be gone (Windows); install it again.
+        for (const name of ["resume", "unlock-screen"]) powerMonitor.on(name, () => setTimeout(refreshForwarding, 1000));
+    }
     if (overlay) {
         ipcMain.handle("next2d:window:set-ignore-mouse-events", (event, ignore) => {
             trusted(event);

package/templates/electron/preload.cjs

@@ -36,6 +36,17 @@ if (flags.has("--next2d-overlay")) {
 // Never set together with the overlay (the config is rejected), so the two never expose next2dWindow twice.
 if (flags.has("--next2d-window-mode")) {
     contextBridge.exposeInMainWorld("next2dWindow", {
+        // Only in the transparent mini window (window.mini.transparent): click-through and moving the frameless window.
+        ...(flags.has("--next2d-mini-transparent") ? {
+            setIgnoreMouseEvents: async (ignore) => {
+                if (typeof ignore !== "boolean") throw new TypeError("Expected boolean");
+                await ipcRenderer.invoke("next2d:window:set-ignore-mouse-events", ignore);
+            },
+            moveBy: async (dx, dy) => {
+                if (!Number.isFinite(dx) || !Number.isFinite(dy)) throw new TypeError("Expected finite numbers");
+                await ipcRenderer.invoke("next2d:window:move-by", dx, dy);
+            }
+        } : {}),
         getMode: () => ipcRenderer.invoke("next2d:window:get-mode"),
         setMode: async (mode) => {
             if (mode !== "full" && mode !== "mini") throw new TypeError("Expected \"full\" or \"mini\"");