nexfep 0.6.0 → 0.7.0

package/README-CN.md

@@ -63,19 +63,22 @@ const app = new Application();
 const app = new Application({ WindowsWebview2UserDataFolder: "C:\\custom\\webview2-data" });
 // 或指定日志文件路径
 const app = new Application({ LogFilePath: "./app.log" });
+// 或注册自定义协议代理
+const app = new Application({ localProxys: [{ protocolName: "app", localPath: "./public" }] });
 ```
 
 **构造函数参数**
 
-| 选项                            | 类型             | 默认值                                           | 说明                                |
-| ------------------------------- | ---------------- | ------------------------------------------------ | ----------------------------------- |
-| `WindowsWebview2UserDataFolder` | `string`（可选） | `%LOCALAPPDATA%\NexfepDevelopment.webview2-data` | WebView2 用户数据目录（仅 Windows） |
-| `LogFilePath`                   | `string`（可选） | 无                                               | 日志文件输出路径                    |
+| 选项                            | 类型                                                                      | 默认值                                           | 说明                                |
+| ------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------- |
+| `WindowsWebview2UserDataFolder` | `string`（可选）                                                          | `%LOCALAPPDATA%\NexfepDevelopment.webview2-data` | WebView2 用户数据目录（仅 Windows） |
+| `LogFilePath`                   | `string`（可选）                                                          | 无                                               | 日志文件输出路径                    |
+| `localProxys`                   | `Array<{ protocolName: string; localPath: string }>`（可选）              | 无                                               | 自定义协议代理，用于提供本地文件服务 |
 
 **属性**
 
 - `windows` — `WindowPool` 实例，用于管理浏览器窗口
-- `utils` — 工具方法（如桌面通知）
+- `utils` — 工具方法（如桌面通知、文件选择弹窗）
 - `logger` — `Logger` 实例，用于日志记录
 
 **方法**
@@ -84,7 +87,69 @@ const app = new Application({ LogFilePath: "./app.log" });
 - `createLocker(appName)` — 创建应用实例锁，防止多个实例运行
 - `exit()` — 退出应用
 
-### Icon
+### 基础类型
+
+Nexfep 提供了几个贯穿框架的基础类型。
+
+#### Size
+
+`Size` 表示窗口尺寸，包含宽度和高度，支持逻辑像素和物理像素。
+
+```typescript
+import { Size } from "nexfep";
+
+const size = new Size(800, 600);
+const size = new Size(800, 600, true); // 逻辑像素（默认）
+```
+
+**属性**
+
+| 属性     | 类型      | 说明                          |
+| -------- | --------- | ----------------------------- |
+| `width`  | `number`  | 宽度（像素）                  |
+| `height` | `number`  | 高度（像素）                  |
+| `logical`| `boolean` | 是否使用逻辑像素，默认 `true`  |
+
+#### Position
+
+`Position` 表示窗口在屏幕上的位置，支持逻辑像素和物理像素。
+
+```typescript
+import { Position } from "nexfep";
+
+const pos = new Position(100, 100);
+const pos = new Position(100, 100, false); // 物理像素（默认）
+```
+
+**属性**
+
+| 属性     | 类型      | 说明                           |
+| -------- | --------- | ------------------------------ |
+| `x`      | `number`  | X 坐标（像素）                 |
+| `y`      | `number`  | Y 坐标（像素）                 |
+| `logical`| `boolean` | 是否使用逻辑像素，默认 `false`  |
+
+#### WindowLevel
+
+`WindowLevel` 是一个枚举，表示窗口的 Z 轴层级。
+
+```typescript
+import { WindowLevel } from "nexfep";
+
+window.setLevel(WindowLevel.Bottommost);
+window.setLevel(WindowLevel.Normal);
+window.setLevel(WindowLevel.Topmost);
+```
+
+**值**
+
+| 值                         | 数值 | 说明     |
+| -------------------------- | ---- | -------- |
+| `WindowLevel.Bottommost`   | `-1` | 置底     |
+| `WindowLevel.Normal`       | `0`  | 正常层级 |
+| `WindowLevel.Topmost`      | `1`  | 置顶     |
+
+#### Icon
 
 `Icon` 用于表示图片资源，可被用作窗口图标、托盘图标等。
 
@@ -148,15 +213,22 @@ const locker = app.createLocker("my-app");
 try {
   // 尝试获取应用实例锁
   await locker.lock();
+  // 也可以带参数获取锁，例如：
+  // await locker.lock(process.argv[2]);
 } catch {
   // 应用实例已存在，退出应用
   app.exit();
 }
-// 在其它实例抢锁时聚焦当前实例
-locker.whenLost(() => {
+// 你可以在其它实例抢锁时聚焦当前实例
+locker.whenLost((data) => {
   if (!win.isFocused()) {
     win.focus();
   }
+  // 如果对方实例在获取锁时传递了参数，你可以使用它来执行特定操作
+  // 若没有传递，data 字段将会是 null
+  if (data) {
+    console.log("传递了参数:", data);
+  }
 });
 // 释放锁
 locker.unlock();
@@ -166,7 +238,7 @@ locker.unlock();
 
 | 方法                 | 描述                     |
 | -------------------- | ------------------------ |
-| `lock()`             | 尝试获取应用实例锁       |
+| `lock(data?)`        | 尝试获取应用实例锁       |
 | `whenLost(callback)` | 当其它实例抢锁时执行回调 |
 | `unlock()`           | 释放锁                   |
 
@@ -226,6 +298,55 @@ const notification = app.utils.notify("标题", { body: "通知内容" });
 - `options`（可选）— 配置对象
   - `body` — 通知正文
 
+### 选择文件弹窗
+
+通过 `app.utils.openFileDialog()` 打开选择文件弹窗。
+
+```typescript
+const files = await app.utils.openFileDialog({
+  multiple: true,
+  title: "选择文件",
+  filters: [
+    { name: "所有文件", extensions: ["*"] },
+    { name: "图片文件", extensions: ["jpg", "jpeg", "png"] },
+  ],
+});
+```
+
+**参数**
+
+- `multiple`（可选）— 是否允许选择多个文件
+- `title`（可选）— 弹窗标题
+- `filters`（可选）— 文件类型过滤器数组，每个元素为一个对象，包含 `name`（过滤器名称）和 `extensions`（支持的文件扩展名数组）
+
+**返回值**
+
+- `Array<string>`: 选择的文件路径数组
+
+### 本地协议代理
+
+Nexfep 支持注册自定义协议处理器，用于提供本地文件服务，从而可以通过自定义协议（如 `app://`）加载本地资源。
+
+```typescript
+const app = new Application({
+  localProxys: [
+    { protocolName: "app", localPath: "./public" },
+  ],
+});
+```
+
+注册后，即可使用自定义协议加载页面：
+
+```typescript
+await window.loadURL("app://index.html");
+```
+
+对 `app://` 的请求会被拦截，并从 `./public` 目录中提供对应的文件。MIME 类型会根据文件扩展名自动检测。
+
+**安全**
+
+协议代理使用路径解析来防止目录遍历攻击。如果请求试图访问配置的 `localPath` 之外的文件，将返回 `403 Forbidden` 响应。
+
 ### 窗口池
 
 `WindowPool` 是框架的核心管理类，负责窗口的创建和回收。
@@ -253,22 +374,22 @@ const win = await pool.createWindow({
   title: "我的应用", // 窗口标题，默认 "Nexfep Window"
   icon: iconInstance, // 窗口图标，Icon 实例，可选
   resizable: true, // 是否可调整大小，默认 true
-  width: 800, // 窗口宽度，默认 800
-  height: 600, // 窗口高度，默认 600
+  size: new Size(800, 600), // 窗口尺寸，可选
+  position: new Position(100, 100), // 窗口位置，可选
 });
 ```
 
 **参数说明**
 
-| 选项         | 类型      | 默认值            | 说明                                                                |
-| ------------ | --------- | ----------------- | ------------------------------------------------------------------- |
-| `visible`    | `boolean` | `true`            | 是否立即显示窗口                                                    |
-| `decoration` | `boolean` | `true`            | 是否使用系统窗口装饰。设为 `false` 时，窗口无边框，需要自定义标题栏 |
-| `title`      | `string`  | `"Nexfep Window"` | 窗口标题                                                            |
-| `icon`       | `Icon`    | 无                | 窗口图标                                                            |
-| `resizable`  | `boolean` | `true`            | 窗口是否可调整大小                                                  |
-| `width`      | `number`  | `800`             | 窗口宽度（像素）                                                    |
-| `height`     | `number`  | `600`             | 窗口高度（像素）                                                    |
+| 选项         | 类型        | 默认值            | 说明                                                                |
+| ------------ | ----------- | ----------------- | ------------------------------------------------------------------- |
+| `visible`    | `boolean`   | `true`            | 是否立即显示窗口                                                    |
+| `decoration` | `boolean`   | `true`            | 是否使用系统窗口装饰。设为 `false` 时，窗口无边框，需要自定义标题栏 |
+| `title`      | `string`    | `"Nexfep Window"` | 窗口标题                                                            |
+| `icon`       | `Icon`      | 无                | 窗口图标                                                            |
+| `resizable`  | `boolean`   | `true`            | 窗口是否可调整大小                                                  |
+| `size`       | `Size`      | 无                | 窗口尺寸，可选                                                      |
+| `position`   | `Position`  | 无                | 窗口位置，可选                                                      |
 
 ### 窗口操作
 
@@ -280,7 +401,8 @@ window.minimize();
 window.close();
 window.focus();
 window.setTitle("新标题");
-window.setSize(800, 600);
+window.setSize(new Size(800, 600));
+window.setPosition(new Position(100, 100));
 window.openDevTools();
 ```
 
@@ -404,6 +526,12 @@ window.addEventListener("user-login", (event) => {
 });
 ```
 
+特别地，主进程可以通过 `pool.broadcast` 向所有打开的窗口发送事件，参数与页面中的 `window.broadcast` 相同：
+
+```typescript
+pool.broadcast("user-login", { userId: 123 });
+```
+
 #### 定向发送
 
 通过 `window.tell` 向指定 ID 的窗口发送消息：
@@ -432,6 +560,12 @@ window.addEventListener("custom-message", (event) => {
 console.log("当前窗口 ID:", window.id);
 ```
 
+主进程也可通过 `win.tell` 向该窗口发送消息：
+
+```typescript
+win.tell("custom-message", { text: `你好，窗口 ${win.id}` });
+```
+
 ### 自定义消息
 
 #### 发送消息
@@ -621,11 +755,12 @@ nexfep build -u 7
 
 | 方法/属性               | 参数                                               | 返回值      | 说明             |
 | ----------------------- | -------------------------------------------------- | ----------- | ---------------- |
-| `constructor(options?)` | `{ WindowsWebview2UserDataFolder?, LogFilePath? }` | Application | 创建应用实例     |
+| `constructor(options?)` | `{ WindowsWebview2UserDataFolder?, LogFilePath?, localProxys? }` | Application | 创建应用实例     |
 | `windows`               | /                                                  | WindowPool  | 窗口池实例       |
-| `utils`                 | /                                                  | \_\_Utils   | 工具方法（通知） |
+| `utils`                 | /                                                  | \_\_Utils   | 工具方法（通知、文件选择弹窗） |
 | `logger`                | /                                                  | Logger      | 日志实例         |
 | `createTray(options)`   | 见 Tray 章节                                       | Tray        | 创建系统托盘图标 |
+| `createLocker(appName)` | `appName`: string                                  | Locker      | 创建应用实例锁   |
 | `exit()`                | 无                                                 | void        | 退出应用         |
 
 ### WindowPool
@@ -637,7 +772,8 @@ nexfep build -u 7
 | `unhandle(event, callback)` | `event`: string, `callback`: (data: any) => any | 无                | 取消监听指定事件         |
 | `global`                    | /                                               | Map\<string, any> | 全局变量 Map             |
 | `closeWindow(window)`       | `window`: Window                                | Promise\<void>    | 关闭指定窗口并回收至池中 |
-| `onCustomMessage`           | `(window: Window, data: string) => void`        | 无                | 自定义消息回调函数       |
+| `onCustomMessage`           | `(window: Window, message: string, data: any) => void` | 无                | 自定义消息回调函数                                       |
+| `broadcast(event, data)`    | `event`: string, `data`: any                           | 无                | 向所有打开的窗口发送事件                                 |
 
 ### Window
 
@@ -655,19 +791,20 @@ nexfep build -u 7
 | `setTitle(title)`                       | `title`: string                                                   | void                              | 设置窗口标题                                                  |
 | `setDecorated(isDecorated)`             | `isDecorated`: boolean                                            | void                              | 设置窗口是否带边框和标题栏                                    |
 | `setResizable(resizable)`               | `resizable`: boolean                                              | void                              | 设置窗口是否可调整大小                                        |
-| `setLevel(level)`                       | `level`: `-1` \| `0` \| `1`                                       | void                              | 设置窗口层级：-1=置底，0=正常，1=置顶                         |
+| `setLevel(level)`                     | `level`: `WindowLevel`                                            | void                              | 设置窗口层级：Bottommost、Normal、Topmost                                                  |
 | `setFullScreen(isFullScreen, options?)` | `isFullScreen`: `boolean`, `options?`: `{ borderless?: boolean }` | void                              | 设置全屏模式。`borderless: true` 为无边框全屏，否则为独占全屏 |
 | `setIcon(icon)`                         | `icon`: `Icon`                                                    | void                              | 设置窗口图标                                                  |
-| `setSize(width, height)`                | `width`: number, `height`: number                                 | void                              | 设置窗口尺寸（像素）                                          |
-| `getSize()`                             | 无                                                                | { width: number, height: number } | 获取窗口尺寸（像素）                                          |
-| `setPosition(x, y)`                     | `x`: number, `y`: number                                          | void                              | 设置窗口位置（像素）                                          |
-| `getPosition()`                         | 无                                                                | { x: number, y: number }          | 获取窗口位置（像素）                                          |
+| `setSize(size)`                         | `size`: `Size`                                                    | void                              | 设置窗口尺寸                                                  |
+| `getSize(logical?)`                    | `logical?`: `boolean`                                             | { width: number, height: number } | 获取窗口尺寸（像素）                                          |
+| `setPosition(position)`                 | `position`: `Position`                                            | void                              | 设置窗口位置                                                  |
+| `getPosition(logical?)`                | `logical?`: `boolean`                                             | { x: number, y: number }          | 获取窗口位置（像素）                                          |
 | `focus()`                               | 无                                                                | void                              | 窗口获取焦点                                                  |
 | `isFocused()`                           | 无                                                                | boolean                           | 是否有焦点                                                    |
 | `isMaximized()`                         | 无                                                                | boolean                           | 是否最大化                                                    |
 | `isMinimized()`                         | 无                                                                | boolean                           | 是否最小化                                                    |
 | `toggleMaximize()`                      | 无                                                                | void                              | 切换最大化状态                                                |
 | `toggleMinimize()`                      | 无                                                                | void                              | 切换最小化状态                                                |
+| `tell(message, data)`                   | `message`: string, `data`: any                                    | void                              | 从主进程向该窗口发送消息                                      |
 | `openDevTools()`                        | 无                                                                | void                              | 打开开发者工具                                                |
 | `closeDevTools()`                       | 无                                                                | void                              | 关闭开发者工具                                                |
 | `id`                                    | 无                                                                | number                            | 窗口唯一标识，自增编号                                        |

package/README.md

@@ -63,19 +63,22 @@ const app = new Application();
 const app = new Application({ WindowsWebview2UserDataFolder: "C:\\custom\\webview2-data" });
 // or with log file path
 const app = new Application({ LogFilePath: "./app.log" });
+// or with custom protocol proxy
+const app = new Application({ localProxys: [{ protocolName: "app", localPath: "./public" }] });
 ```
 
 **Constructor Options**
 
-| Option                          | Type                | Default                                          | Description                                 |
-| ------------------------------- | ------------------- | ------------------------------------------------ | ------------------------------------------- |
-| `WindowsWebview2UserDataFolder` | `string` (optional) | `%LOCALAPPDATA%\NexfepDevelopment.webview2-data` | WebView2 user data directory (Windows only) |
-| `LogFilePath`                   | `string` (optional) | none                                             | File path for log output                    |
+| Option                          | Type                                                                  | Default                                          | Description                                 |
+| ------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------- |
+| `WindowsWebview2UserDataFolder` | `string` (optional)                                                   | `%LOCALAPPDATA%\NexfepDevelopment.webview2-data` | WebView2 user data directory (Windows only) |
+| `LogFilePath`                   | `string` (optional)                                                   | none                                             | File path for log output                    |
+| `localProxys`                   | `Array<{ protocolName: string; localPath: string }>` (optional)       | none                                             | Custom protocol proxies for serving local files |
 
 **Properties**
 
 - `windows` — The `WindowPool` instance for managing browser windows
-- `utils` — Utility methods (e.g., desktop notifications)
+- `utils` — Utility methods (e.g., desktop notifications, file dialogs)
 - `logger` — The `Logger` instance for logging
 
 **Methods**
@@ -84,7 +87,69 @@ const app = new Application({ LogFilePath: "./app.log" });
 - `createLocker(appName)` — Create an application instance lock to prevent multiple instances
 - `exit()` — Exit the application
 
-### Icon
+### Basic Types
+
+Nexfep provides several basic types that are used throughout the framework.
+
+#### Size
+
+`Size` represents a window size with width and height, supporting both logical and physical pixels.
+
+```typescript
+import { Size } from "nexfep";
+
+const size = new Size(800, 600);
+const size = new Size(800, 600, true); // logical pixels (default)
+```
+
+**Properties**
+
+| Property | Type     | Description                                             |
+| -------- | -------- | ------------------------------------------------------- |
+| `width`  | `number` | Width in pixels                                         |
+| `height` | `number` | Height in pixels                                        |
+| `logical`| `boolean`| Whether to use logical pixels (DPI-aware), default `true` |
+
+#### Position
+
+`Position` represents a window position on screen, supporting both logical and physical pixels.
+
+```typescript
+import { Position } from "nexfep";
+
+const pos = new Position(100, 100);
+const pos = new Position(100, 100, false); // physical pixels (default)
+```
+
+**Properties**
+
+| Property | Type     | Description                                              |
+| -------- | -------- | -------------------------------------------------------- |
+| `x`      | `number` | X position in pixels                                     |
+| `y`      | `number` | Y position in pixels                                     |
+| `logical`| `boolean`| Whether to use logical pixels (DPI-aware), default `false` |
+
+#### WindowLevel
+
+`WindowLevel` is an enum representing the window z-order level.
+
+```typescript
+import { WindowLevel } from "nexfep";
+
+window.setLevel(WindowLevel.Bottommost);
+window.setLevel(WindowLevel.Normal);
+window.setLevel(WindowLevel.Topmost);
+```
+
+**Values**
+
+| Value                       | Numeric | Description       |
+| --------------------------- | ------- | ----------------- |
+| `WindowLevel.Bottommost`    | `-1`    | Always on bottom  |
+| `WindowLevel.Normal`        | `0`     | Normal level      |
+| `WindowLevel.Topmost`       | `1`     | Always on top     |
+
+#### Icon
 
 `Icon` represents an image resource that can be used as a window icon, tray icon, etc.
 
@@ -148,15 +213,22 @@ const locker = app.createLocker("my-app");
 try {
   // Try to acquire the lock
   await locker.lock();
+  // You can also pass data to the other instance when acquiring the lock
+  // await locker.lock(process.argv[2]);
 } catch {
   // Instance already exists, exit the application
   app.exit();
 }
 // Focus the current instance when other instances acquire the lock
-locker.whenLost(() => {
+locker.whenLost((data) => {
   if (!win.isFocused()) {
     win.focus();
   }
+  // If the other instance passed data, you can use it to perform specific actions
+  // If no data was passed, data will be null
+  if (data) {
+    console.log("Other instance passed data:", data);
+  }
 });
 // Release the lock
 locker.unlock();
@@ -164,7 +236,7 @@ locker.unlock();
 
 **Methods**
 
-- `lock()` — Try to acquire the lock
+- `lock(data?)` — Try to acquire the lock
 - `whenLost(callback)` — Register a callback to be called when other instances acquire the lock
 - `unlock()` — Release the lock
 
@@ -224,6 +296,55 @@ const notification = app.utils.notify("Title", { body: "Notification body" });
 - `options` (optional) — Configuration object
   - `body` — Notification body text
 
+### File Selection Dialog
+
+Open the file selection dialog using `app.utils.openFileDialog()`.
+
+```typescript
+const files = await app.utils.openFileDialog({
+  multiple: true,
+  title: "Select Files",
+  filters: [
+    { name: "All Files", extensions: ["*"] },
+    { name: "Image Files", extensions: ["jpg", "jpeg", "png"] },
+  ],
+});
+```
+
+**Parameters**
+
+- `multiple` (Optional) — Allow selection of multiple files
+- `title` (Optional) — Title of the dialog
+- `filters` (Optional) — Array of file type filters, each object has `name` (filter name) and `extensions` (supported file extensions array)
+
+**Return Value**
+
+- `Array<string>`: Array of selected file paths
+
+### Local Protocol Proxy
+
+Nexfep supports registering custom protocol handlers to serve local files, allowing you to load local resources using custom protocols like `app://`.
+
+```typescript
+const app = new Application({
+  localProxys: [
+    { protocolName: "app", localPath: "./public" },
+  ],
+});
+```
+
+After registration, you can load pages using the custom protocol:
+
+```typescript
+await window.loadURL("app://index.html");
+```
+
+Requests to `app://` will be intercepted and the corresponding files from the `./public` directory will be served. The MIME type is automatically detected based on the file extension.
+
+**Security**
+
+The proxy uses path resolution to prevent directory traversal attacks. If a request tries to access files outside the configured `localPath`, it will return a `403 Forbidden` response.
+
 ### Window Pool
 
 `WindowPool` is the core management class of the framework, responsible for window creation and recycling.
@@ -251,22 +372,22 @@ const win = await pool.createWindow({
   title: "My App", // Window title, default "Nexfep Window"
   icon: iconInstance, // Window icon, Icon instance, optional
   resizable: true, // Whether the window is resizable, default true
-  width: 800, // Window width, default 800
-  height: 600, // Window height, default 600
+  size: new Size(800, 600), // Window size, optional
+  position: new Position(100, 100), // Window position, optional
 });
 ```
 
 **Parameters**
 
-| Option       | Type      | Default           | Description                                                                                                      |
-| ------------ | --------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `visible`    | `boolean` | `true`            | Whether to immediately show the window                                                                           |
-| `decoration` | `boolean` | `true`            | Whether to use system window decorations. When `false`, the window has no border and requires a custom title bar |
-| `title`      | `string`  | `"Nexfep Window"` | Window title                                                                                                     |
-| `icon`       | `Icon`    | none              | Window icon                                                                                                      |
-| `resizable`  | `boolean` | `true`            | Whether the window is resizable                                                                                  |
-| `width`      | `number`  | `800`             | Window width in pixels                                                                                           |
-| `height`     | `number`  | `600`             | Window height in pixels                                                                                          |
+| Option       | Type        | Default           | Description                                                                                                      |
+| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `visible`    | `boolean`   | `true`            | Whether to immediately show the window                                                                           |
+| `decoration` | `boolean`   | `true`            | Whether to use system window decorations. When `false`, the window has no border and requires a custom title bar |
+| `title`      | `string`    | `"Nexfep Window"` | Window title                                                                                                     |
+| `icon`       | `Icon`      | none              | Window icon                                                                                                      |
+| `resizable`  | `boolean`   | `true`            | Whether the window is resizable                                                                                  |
+| `size`       | `Size`      | none              | Window size, optional                                                                               |
+| `position`   | `Position`  | none              | Window position, optional                                                                                        |
 
 ### Window Operations
 
@@ -278,7 +399,8 @@ window.minimize();
 window.close();
 window.focus();
 window.setTitle("New Title");
-window.setSize(800, 600);
+window.setSize(new Size(800, 600));
+window.setPosition(new Position(100, 100));
 window.openDevTools();
 ```
 
@@ -402,6 +524,12 @@ window.addEventListener("user-login", (event) => {
 });
 ```
 
+The main process can send events to all open windows via `pool.broadcast`, with parameters identical to those of `window.broadcast` in the page:
+
+```typescript
+pool.broadcast("user-login", { userId: 123 });
+```
+
 #### Tell
 
 Send a message to a specific window by its ID via `window.tell`:
@@ -430,6 +558,12 @@ Each window's ID can be accessed via `window.id`:
 console.log("This window ID:", window.id);
 ```
 
+The main process can also send messages to this window through `win.tell`:
+
+```typescript
+win.tell("custom-message", { text: `Hello Window ${win.id}` });
+```
+
 ### Custom Messages
 
 #### Send Messages
@@ -619,11 +753,12 @@ Please do not include the outer `metadata` field, just the internal fields. Like
 
 | Method/Property         | Parameters                                         | Return Value | Description                      |
 | ----------------------- | -------------------------------------------------- | ------------ | -------------------------------- |
-| `constructor(options?)` | `{ WindowsWebview2UserDataFolder?, LogFilePath? }` | Application  | Creates the application instance |
+| `constructor(options?)` | `{ WindowsWebview2UserDataFolder?, LogFilePath?, localProxys? }` | Application  | Creates the application instance |
 | `windows`               | /                                                  | WindowPool   | The window pool instance         |
-| `utils`                 | /                                                  | \_\_Utils    | Utility methods (notifications)  |
+| `utils`                 | /                                                  | \_\_Utils    | Utility methods (notifications, file dialogs) |
 | `logger`                | /                                                  | Logger       | The logger instance              |
 | `createTray(options)`   | see Tray section                                   | Tray         | Creates a system tray icon       |
+| `createLocker(appName)` | `appName`: string                                  | Locker       | Creates an application lock      |
 | `exit()`                | None                                               | void         | Exits the application            |
 
 ### WindowPool
@@ -635,7 +770,8 @@ Please do not include the outer `metadata` field, just the internal fields. Like
 | `unhandle(event, callback)` | `event`: string, `callback`: (data: any) => any        | None              | Removes the specified event listener                   |
 | `global`                    | /                                                      | Map\<string, any> | A global variable map                                  |
 | `closeWindow(window)`       | `window`: Window                                       | Promise\<void>    | Closes the specified window and returns it to the pool |
-| `onCustomMessage`           | `(window: Window, data: string) => void`               | None              | Custom message callback                                |
+| `onCustomMessage`           | `(window: Window, message: string, data: any) => void` | None              | Custom message callback                                |
+| `broadcast(event, data)`    | `event`: string, `data`: any                           | None              | Sends an event to all open windows                     |
 
 ### Window
 
@@ -653,19 +789,20 @@ Please do not include the outer `metadata` field, just the internal fields. Like
 | `setTitle(title)`                       | `title`: string                                                   | void                              | Sets the window title                                                                              |
 | `setDecorated(isDecorated)`             | `isDecorated`: boolean                                            | void                              | Sets whether the window has borders and title bar                                                  |
 | `setResizable(resizable)`               | `resizable`: boolean                                              | void                              | Sets whether the window is resizable                                                               |
-| `setLevel(level)`                       | `level`: `-1` \| `0` \| `1`                                       | void                              | Sets window level: -1=bottom, 0=normal, 1=top                                                      |
+| `setLevel(level)`                     | `level`: `WindowLevel`                                            | void                              | Sets window level: Bottommost, Normal, Topmost                                                  |
 | `setFullScreen(isFullScreen, options?)` | `isFullScreen`: `boolean`, `options?`: `{ borderless?: boolean }` | void                              | Sets fullscreen mode. `borderless: true` for borderless fullscreen, otherwise exclusive fullscreen |
 | `setIcon(icon)`                         | `icon`: `Icon`                                                    | void                              | Sets the window icon                                                                               |
-| `setSize(width, height)`                | `width`: number, `height`: number                                 | void                              | Sets the window size in pixels                                                                     |
-| `getSize()`                             | None                                                              | { width: number, height: number } | Gets the window size in pixels                                                                     |
-| `setPosition(x, y)`                     | `x`: number, `y`: number                                          | void                              | Sets the window position in pixels                                                                 |
-| `getPosition()`                         | None                                                              | { x: number, y: number }          | Gets the window position in pixels                                                                 |
+| `setSize(size)`                         | `size`: `Size`                                                    | void                              | Sets the window size                                                                               |
+| `getSize(logical?)`                    | `logical?`: `boolean`                                             | { width: number, height: number } | Gets the window size in pixels                                                                     |
+| `setPosition(position)`                 | `position`: `Position`                                            | void                              | Sets the window position                                                                           |
+| `getPosition(logical?)`                | `logical?`: `boolean`                                             | { x: number, y: number }          | Gets the window position in pixels                                                                 |
 | `focus()`                               | None                                                              | void                              | Focuses the window                                                                                 |
 | `isFocused()`                           | None                                                              | boolean                           | Whether the window has focus                                                                       |
 | `isMaximized()`                         | None                                                              | boolean                           | Whether the window is maximized                                                                    |
 | `isMinimized()`                         | None                                                              | boolean                           | Whether the window is minimized                                                                    |
 | `toggleMaximize()`                      | None                                                              | void                              | Toggles the window maximized state                                                                 |
 | `toggleMinimize()`                      | None                                                              | void                              | Toggles the window minimized state                                                                 |
+| `tell(message, data)`                   | `message`: string, `data`: any                                    | void                              | Sends a message to the window from the main process                                                |
 | `openDevTools()`                        | None                                                              | void                              | Opens developer tools                                                                              |
 | `closeDevTools()`                       | None                                                              | void                              | Closes developer tools                                                                             |
 | `id`                                    | None                                                              | number                            | Unique window identifier, auto-incrementing                                                        |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexfep",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A desktop application framework based on @webviewjs/webview",
   "keywords": [
     "@webviewjs/webview",
@@ -41,8 +41,8 @@
     "src/Logger.d.ts",
     "src/SingleInstance.js",
     "src/SingleInstance.d.ts",
-    "src/Icon.js",
-    "src/Icon.d.ts",
+    "src/Basics.js",
+    "src/Basics.d.ts",
     "frontend/index.d.ts"
   ],
   "type": "module",
@@ -65,8 +65,9 @@
     "lint:fix": "oxlint --fix"
   },
   "dependencies": {
-    "@nexfteam/single-instance": "^0.0.7",
-    "@webviewjs/webview": "0.4.1"
+    "@nexfteam/single-instance": "0.0.8",
+    "@webviewjs/webview": "0.4.3",
+    "mrmime": "^2.0.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/Application.d.ts

@@ -3,13 +3,21 @@ import { WindowPool } from "./WindowManager.js";
 import { Tray } from "./Tray.js";
 import { Logger } from "./Logger.js";
 import { Locker } from "./SingleInstance.js";
-import { Icon } from "./Icon.js";
+import { Icon } from "./Basics.js";
 declare class __Utils {
-    app: WebviewApplication;
-    constructor(app: WebviewApplication);
+    app: Application;
+    constructor(app: Application);
     notify(title: string, options?: {
         body?: string;
     }): Notification;
+    openFileDialog(options?: {
+        multiple?: boolean;
+        title?: string;
+        filters?: Array<{
+            name: string;
+            extensions: Array<string>;
+        }>;
+    }): Promise<string[]>;
 }
 declare class Application {
     app: WebviewApplication;
@@ -19,6 +27,10 @@ declare class Application {
     constructor(options?: {
         WindowsWebview2UserDataFolder?: string;
         LogFilePath?: string;
+        localProxys?: Array<{
+            protocolName: string;
+            localPath: string;
+        }>;
     });
     createTray(options: {
         id: string;
@@ -32,4 +44,5 @@ declare class Application {
     createLocker(appName: string): Locker;
     exit(): void;
 }
-export { Application, Icon };
+export { Application };
+export * from "./Basics.js";

package/src/Application.js

@@ -3,7 +3,6 @@ import { WindowPool } from "./WindowManager.js";
 import { Tray } from "./Tray.js";
 import { Logger } from "./Logger.js";
 import { Locker } from "./SingleInstance.js";
-import { Icon } from "./Icon.js";
 class __Utils {
     app;
     constructor(app) {
@@ -13,6 +12,12 @@ class __Utils {
         const notification = new Notification(title, { body: options?.body });
         return notification;
     }
+    async openFileDialog(options) {
+        const tempWin = await this.app.windows.createWindow({ visible: false });
+        const result = tempWin.window.openFileDialog(options);
+        tempWin.close();
+        return result;
+    }
 }
 class Application {
     app;
@@ -21,11 +26,12 @@ class Application {
     utils;
     constructor(options = {}) {
         this.app = new WebviewApplication();
-        this.utils = new __Utils(this.app);
+        this.utils = new __Utils(this);
         this.logger = new Logger(options.LogFilePath);
         const poolOptions = {
             WindowsWebview2UserDataFolder: options.WindowsWebview2UserDataFolder,
             logger: this.logger,
+            localProxys: options.localProxys,
         };
         this.windows = new WindowPool(this.app, poolOptions);
         this.app.whenReady();
@@ -40,4 +46,5 @@ class Application {
         this.app.exit();
     }
 }
-export { Application, Icon };
+export { Application };
+export * from "./Basics.js";

package/src/{Icon.d.ts → Basics.d.ts}

@@ -16,4 +16,21 @@ declare class Icon {
     toTrayIconImage(): TrayIconImage;
     toBuffer(): Buffer;
 }
-export { Icon };
+declare class Size {
+    width: number;
+    height: number;
+    logical: boolean;
+    constructor(width: number, height: number, logical?: boolean);
+}
+declare class Position {
+    x: number;
+    y: number;
+    logical: boolean;
+    constructor(x: number, y: number, logical?: boolean);
+}
+declare enum WindowLevel {
+    Bottommost = -1,
+    Normal = 0,
+    Topmost = 1
+}
+export { Icon, Size, Position, WindowLevel };

package/src/{Icon.js → Basics.js}

@@ -33,4 +33,30 @@ class Icon {
         return Buffer.from(this.data);
     }
 }
-export { Icon };
+class Size {
+    width;
+    height;
+    logical;
+    constructor(width, height, logical) {
+        this.width = width;
+        this.height = height;
+        this.logical = logical ?? true;
+    }
+}
+class Position {
+    x;
+    y;
+    logical;
+    constructor(x, y, logical) {
+        this.x = x;
+        this.y = y;
+        this.logical = logical ?? false;
+    }
+}
+var WindowLevel;
+(function (WindowLevel) {
+    WindowLevel[WindowLevel["Bottommost"] = -1] = "Bottommost";
+    WindowLevel[WindowLevel["Normal"] = 0] = "Normal";
+    WindowLevel[WindowLevel["Topmost"] = 1] = "Topmost";
+})(WindowLevel || (WindowLevel = {}));
+export { Icon, Size, Position, WindowLevel };

package/src/SingleInstance.d.ts

@@ -2,8 +2,8 @@ import { SingleInstance } from "@nexfteam/single-instance";
 declare class Locker {
     locker: SingleInstance;
     constructor(appName: string);
-    lock(): Promise<void>;
+    lock(data?: string): Promise<void>;
     unlock(): Promise<void>;
-    whenLost(callback: () => void): void;
+    whenLost(callback: (data?: string) => void): void;
 }
 export { Locker };

package/src/SingleInstance.js

@@ -4,8 +4,8 @@ class Locker {
     constructor(appName) {
         this.locker = new SingleInstance(appName);
     }
-    lock() {
-        return this.locker.lock();
+    lock(data) {
+        return this.locker.lock(data);
     }
     unlock() {
         return this.locker.unlock();

package/src/Tray.d.ts

@@ -1,5 +1,5 @@
 import { Application, TrayIcon } from "@webviewjs/webview";
-import { Icon } from "./Icon.js";
+import { Icon } from "./Basics.js";
 declare class Tray {
     app: Application;
     tray: TrayIcon;

package/src/WindowManager.d.ts

@@ -1,6 +1,6 @@
 import { Application, BrowserWindow, Webview } from "@webviewjs/webview";
 import { Logger } from "./Logger.js";
-import { Icon } from "./Icon.js";
+import { Icon, Size, Position, WindowLevel } from "./Basics.js";
 declare class Window {
     window: BrowserWindow;
     webview: Webview;
@@ -10,7 +10,7 @@ declare class Window {
     id: number;
     private myPool;
     constructor(window: BrowserWindow, webview: Webview, id: number, myPool: WindowPool);
-    setLevel(level: -1 | 0 | 1): void;
+    setLevel(level: WindowLevel): void;
     setFullScreen(isFullScreen: boolean, options?: {
         borderless?: boolean;
     }): void;
@@ -28,12 +28,13 @@ declare class Window {
     openDevTools(): void;
     closeDevTools(): void;
     setIcon(icon: Icon): void;
-    setSize(width: number, height: number): void;
-    getSize(): import("@webviewjs/webview").Dimensions;
-    setPosition(x: number, y: number): void;
-    getPosition(): import("@webviewjs/webview").Position;
+    setSize(size: Size): void;
+    getSize(logical?: boolean): import("@webviewjs/webview").Dimensions;
+    setPosition(position: Position): void;
+    getPosition(logical?: boolean): import("@webviewjs/webview").Position;
     isFocused(): boolean;
     focus(): void;
+    tell(message: string, data: any): void;
     hide(): void;
     show(): void;
     close(): void;
@@ -49,11 +50,17 @@ declare class WindowPool {
     private injectCount;
     private windowCount;
     private freeWindowCount;
+    private localProxys;
     global: Map<string, any>;
     constructor(app: Application, options: {
         WindowsWebview2UserDataFolder?: string;
         logger?: Logger;
+        localProxys?: Array<{
+            protocolName: string;
+            localPath: string;
+        }>;
     });
+    __registryLocalProxy(window: BrowserWindow, protocolName: string, localPath: string): void;
     __injectCode(window: Window, code: string): Promise<void>;
     __injectControlFunctions(windowObj: Window): Promise<void>;
     __createNewWindowObj(): Promise<Window>;
@@ -63,11 +70,12 @@ declare class WindowPool {
         title?: string;
         icon?: Icon;
         resizable?: boolean;
-        width?: number;
-        height?: number;
+        size?: Size;
+        position?: Position;
     }): Promise<Window>;
     closeWindow(window: Window): Promise<void>;
     handle(event: string, callback: (data: any) => any): Promise<void>;
     unhandle(event: string, callback: (data: any) => any): Promise<void>;
+    broadcast(event: string, data: any): Promise<void>;
 }
 export { WindowPool, Window };

package/src/WindowManager.js

@@ -1,7 +1,9 @@
 import { Logger } from "./Logger.js";
+import { WindowLevel } from "./Basics.js";
 import os from "os";
 import path from "path";
 import fs from "fs";
+import { lookup } from "mrmime";
 class Window {
     window;
     webview;
@@ -20,17 +22,17 @@ class Window {
         this.id = id;
     }
     setLevel(level) {
-        if (level == -1) {
+        if (level == WindowLevel.Bottommost) {
             this.window.setAlwaysOnTop(false);
             this.window.setAlwaysOnBottom(true);
             return;
         }
-        else if (level == 0) {
+        else if (level == WindowLevel.Normal) {
             this.window.setAlwaysOnTop(false);
             this.window.setAlwaysOnBottom(false);
             return;
         }
-        else if (level == 1) {
+        else if (level == WindowLevel.Topmost) {
             this.window.setAlwaysOnTop(true);
             this.window.setAlwaysOnBottom(false);
             return;
@@ -102,17 +104,17 @@ class Window {
     setIcon(icon) {
         this.window.setWindowIcon(icon.data, icon.width, icon.height);
     }
-    setSize(width, height) {
-        this.window.setSize(width, height);
+    setSize(size) {
+        this.window.setSize(size.width, size.height, size.logical);
     }
-    getSize() {
-        return this.window.getInnerSize();
+    getSize(logical) {
+        return this.window.getInnerSize(logical);
     }
-    setPosition(x, y) {
-        this.window.setPosition(x, y);
+    setPosition(position) {
+        this.window.setPosition(position.x, position.y, position.logical);
     }
-    getPosition() {
-        return this.window.getPosition();
+    getPosition(logical) {
+        return this.window.getPosition(logical);
     }
     isFocused() {
         return this.window.isFocused();
@@ -121,6 +123,9 @@ class Window {
         this.unMinimize();
         this.window.focus();
     }
+    tell(message, data) {
+        this.webview.evaluateScript(`window.dispatchEvent(new CustomEvent('${message}', { detail: ${JSON.stringify(data)} }));`);
+    }
     hide() {
         this.window.hide();
         this.isShow = false;
@@ -150,6 +155,7 @@ class WindowPool {
     injectCount;
     windowCount;
     freeWindowCount;
+    localProxys;
     global;
     constructor(app, options) {
         if (os.platform() === "win32") {
@@ -171,6 +177,36 @@ class WindowPool {
         this.freeWindowCount = 0;
         this.global = new Map();
         this.logger = options.logger || new Logger();
+        this.localProxys = options.localProxys || [];
+    }
+    __registryLocalProxy(window, protocolName, localPath) {
+        const basePath = path.resolve(localPath);
+        console.log(window.registerProtocol);
+        window.registerProtocol(protocolName, async (request) => {
+            try {
+                const url = new URL(request.url);
+                let relativePath = url.pathname;
+                if (relativePath === "/" || relativePath === "") {
+                    relativePath = "/index.html";
+                }
+                const absolutePath = path.join(basePath, relativePath);
+                const resolvedPath = path.resolve(absolutePath);
+                if (!resolvedPath.startsWith(basePath)) {
+                    return new Response("Forbidden", { status: 403 });
+                }
+                const content = fs.readFileSync(resolvedPath);
+                const mimeType = lookup(resolvedPath) || "application/octet-stream";
+                return new Response(content, {
+                    status: 200,
+                    headers: {
+                        "Content-Type": mimeType,
+                    },
+                });
+            }
+            catch {
+                return new Response("Not Found", { status: 404 });
+            }
+        });
     }
     async __injectCode(window, code) {
         await window.webview.evaluateScript(code);
@@ -362,6 +398,9 @@ class WindowPool {
                     visible: false,
                     focused: false,
                 });
+                this.localProxys.forEach((proxy) => {
+                    this.__registryLocalProxy(window, proxy.protocolName, proxy.localPath);
+                });
                 this.freeWindowCount++;
                 const webview = window.createWebview();
                 const windowObj = new Window(window, webview, ++this.windowCount, this);
@@ -370,13 +409,14 @@ class WindowPool {
                     const dataText = data.body.toString();
                     const dataObj = JSON.parse(dataText);
                     if (dataObj.type == "NexfepBeforeUnload") {
-                        webview.evaluateScript(`if(window?.isNexfepLoadDone){
-                            const MessageBody = { type: 'NexfepBeforeUnload' }
-                            window.ipc.postMessage(JSON.stringify(MessageBody));
-                        }else{
-                            const MessageBody = { type: 'NexfepLoadFalse' }
-                            window.ipc.postMessage(JSON.stringify(MessageBody));
-                        }`);
+                        webview.evaluateScript(`
+              if(window?.isNexfepLoadDone){
+                const MessageBody = { type: 'NexfepBeforeUnload' }
+                window.ipc.postMessage(JSON.stringify(MessageBody));
+              }else{
+                const MessageBody = { type: 'NexfepLoadFalse' }
+                window.ipc.postMessage(JSON.stringify(MessageBody));
+              }`);
                     }
                     else if (dataObj.type == "NexfepLoadFalse") {
                         this.__injectControlFunctions(windowObj);
@@ -416,14 +456,10 @@ class WindowPool {
                         handlers.forEach(async (handler) => {
                             const result = await handler(dataObj.data);
                             if (result) {
-                                webview.evaluateScript(`
-                                    window.dispatchEvent(new CustomEvent('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: ${JSON.stringify(result)} }));
-                                `);
+                                webview.evaluateScript(`window.dispatchEvent(new CustomEvent('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: ${JSON.stringify(result)} }));`);
                             }
                             else {
-                                webview.evaluateScript(`
-                                    window.dispatchEvent(new CustomEvent('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: undefined }));
-                                `);
+                                webview.evaluateScript(`window.dispatchEvent(new CustomEvent('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: undefined }));`);
                             }
                         });
                     }
@@ -432,16 +468,12 @@ class WindowPool {
                     }
                     else if (dataObj.type == "NexfepGetGlobal") {
                         const value = this.global.get(dataObj.name);
-                        webview.evaluateScript(`
-                            window.dispatchEvent(new CustomEvent('nexfep-get-global-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: ${JSON.stringify(value)} }));
-                        `);
+                        webview.evaluateScript(`window.dispatchEvent(new CustomEvent('nexfep-get-global-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: ${JSON.stringify(value)} }));`);
                     }
                     else if (dataObj.type == "NexfepBroadcast") {
                         this.windows.forEach(async (w) => {
                             if (w != windowObj && w.isOpen) {
-                                w.webview.evaluateScript(`
-                                    window.dispatchEvent(new CustomEvent('${dataObj.name}', { detail: ${JSON.stringify(dataObj.data)} }));
-                                `);
+                                w.webview.evaluateScript(`window.dispatchEvent(new CustomEvent('${dataObj.name}', { detail: ${JSON.stringify(dataObj.data)} }));`);
                             }
                         });
                     }
@@ -451,9 +483,7 @@ class WindowPool {
                         }
                         this.windows.forEach(async (w) => {
                             if (w.id == dataObj.to) {
-                                w.webview.evaluateScript(`
-                                    window.dispatchEvent(new CustomEvent('${dataObj.message}', { detail: ${JSON.stringify(dataObj.data)} }));
-                                `);
+                                w.webview.evaluateScript(`window.dispatchEvent(new CustomEvent('${dataObj.message}', { detail: ${JSON.stringify(dataObj.data)} }));`);
                             }
                         });
                     }
@@ -492,7 +522,12 @@ class WindowPool {
                 window.setIcon(options?.icon);
             }
             window.setResizable(options?.resizable ?? true);
-            window.setSize(options?.width ?? 800, options?.height ?? 600);
+            if (options?.size) {
+                window.setSize(options?.size);
+            }
+            if (options?.position) {
+                window.setPosition(options?.position);
+            }
         }
         if (this.freeWindowCount == 0) {
             this.__createNewWindowObj();
@@ -518,5 +553,12 @@ class WindowPool {
     async unhandle(event, callback) {
         this.handlers.set(event, (this.handlers.get(event) || []).filter((c) => c !== callback));
     }
+    async broadcast(event, data) {
+        this.windows.forEach(async (w) => {
+            if (w.isOpen) {
+                w.webview.evaluateScript(`window.dispatchEvent(new CustomEvent('${event}', { detail: ${JSON.stringify(data)} }));`);
+            }
+        });
+    }
 }
 export { WindowPool, Window };