# app.json 配置

## 功能
`app.json` 是 `bt_app` 的桌面应用配置文件。它描述应用名称、窗口、入口、运行模式、图标、主脚本和打包资源。

`app.json` 是唯一配置来源。项目根目录不存在 `app.json` 但存在 `index.html` 时，`bt_app` 会自动写入默认 `app.json` 后再启动；`index.html` 中的 `<title>` 和自定义标签不会覆盖应用配置。

## 完整示例
```json
{
  "app": {
    "name": "Diary",
    "title": "我的日记本",
    "version": "1.0.0",
    "description": "BT 桌面日记本示例",
    "copyright": "Copyright 2026 BT",
    "mode": "static",
    "entry": "index.html",
    "icon": "icon.ico",
    "main": "main.bt"
  },
  "window": {
    "width": 900,
    "height": 700,
    "resizable": true,
    "fullscreen": false,
    "hide_titlebar": false,
    "always_on_top": false
  },
  "dev": {
    "watch": true,
    "delay": 500,
    "devtools": true,
    "console": true
  },
  "resources": [
    "app.json",
    "index.html",
    "icon.ico",
    "main.bt",
    "assets/**"
  ],
  "exclude": [
    "assets/test/**",
    "assets/*.bak"
  ]
}
```

## app 字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `app.name` | string | 否 | `BTApp` | 应用内部名称，也是默认打包输出文件名。只能是单个文件名片段，不能包含路径或 Windows 文件名非法字符。 |
| `app.title` | string | 否 | `BT 桌面应用` | 窗口标题。用户看到的应用名称通常写在这里。 |
| `app.version` | string | 否 | `1.0.0` | 应用版本。当前主要用于配置记录。 |
| `app.description` | string | 否 | 无 | 应用说明。Windows 打包时写入 exe 的 `FileDescription` 元信息。 |
| `app.copyright` | string | 否 | 无 | 版权说明。Windows 打包时写入 exe 的 `LegalCopyright` 元信息。 |
| `app.mode` | string | 否 | `static` | 运行模式，只能是 `static`、`server`、`remote`。 |
| `app.entry` | string | 否 | 按模式决定 | 窗口入口。`static` 默认 `index.html`，`server` 默认 `http://127.0.0.1:18280`，`remote` 默认 `https://example.com`。 |
| `app.icon` | string | 否 | 内置图标 | 项目内相对路径，当前只支持 `.ico` 文件。用于运行窗口图标和 Windows 打包 exe 图标。 |
| `app.main` | string/boolean/null | 否 | 自动尝试 `main.bt` | 前端 `bt.call()` 可调用的 BT 主脚本。字符串表示指定脚本；`false` 或空字符串表示不执行；`true`、`null` 或省略表示自动查找 `main.bt`。 |

## window 字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `window.width` | number | 否 | `800` | 主窗口初始宽度，单位为逻辑像素。写 `0` 会回退到默认值。 |
| `window.height` | number | 否 | `500` | 主窗口初始高度，单位为逻辑像素。写 `0` 会回退到默认值。 |
| `window.resizable` | boolean | 否 | `true` | 是否允许用户调整窗口大小。 |
| `window.fullscreen` | boolean | 否 | `false` | 是否全屏启动。 |
| `window.hide_titlebar` | boolean | 否 | `false` | 是否隐藏系统标题栏。隐藏后需要页面自己提供拖动、关闭等交互。 |
| `window.always_on_top` | boolean | 否 | `false` | 是否置顶窗口，适合悬浮工具、监控面板等场景。 |

## dev 字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `dev.watch` | boolean | 否 | `true` | 开发目录运行时是否监听资源变化并自动刷新页面。打包后的 Bundle 运行不生效。 |
| `dev.delay` | number | 否 | `500` | 文件变化后的防抖时间，单位为毫秒。连续保存多个文件只刷新一次。 |
| `dev.devtools` | boolean | 否 | `false` | 是否允许打开 WebView 开发者工具。建议只在开发阶段开启；文件变化热重载不会自动弹出开发者工具。 |
| `dev.console` | boolean | 否 | `true` | 是否启用调试控制台。打包时为 `false` 会把 Windows exe 改为 GUI 子系统，双击时不弹控制台。 |

开发模式支持 `F5`、`Ctrl+R` 和 `Cmd+R` 刷新当前页面。`dev.watch=true` 时，`resources - exclude` 命中的文件保存、新增、删除或重命名后会自动刷新页面。`dev.watch=false` 时不会监听普通资源变化，但仍会监听 `app.json`，以便修改配置后自动恢复。

开发目录运行时遇到 `app.json` 解析失败、入口文件缺失、`app.main` 缺失或脚本执行异常时，会在窗口内显示统一错误页并继续监听文件变化；修复后会自动重新加载。热重载错误状态会沿用上一次有效配置中的控制台设置，不会因为进入错误页而强制弹出控制台。

## resources 字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `resources` | string[] | 否 | `[]` | 打包时进入 Bundle 的资源规则，支持普通相对文件、glob 和 `assets/**` 这类递归目录规则。 |
| `exclude` | string[] | 否 | `[]` | 排除打包与开发监听的资源规则，优先级高于 `resources`。 |

构建时还会自动补齐必要资源：

- 当前目录存在 `app.json` 时自动加入 `app.json`。
- `static` 模式自动加入 `app.entry` 指向的入口文件。
- `app.main` 自动模式下如果存在 `main.bt`，自动加入 `main.bt`。
- 指定 `app.main` 字符串时自动加入该脚本。
- 当前目录存在 `server.bt` 时自动加入 `server.bt`。
- 配置了 `app.icon` 时自动加入图标文件。

最终资源集合按 `resources - exclude` 计算，该规则同时用于打包和开发模式文件监听。`resources` 和 `exclude` 只能写项目内相对路径，不能写绝对路径，不能包含 `..`。普通文件不存在会打包失败；普通目录会递归收集目录内文件；`assets/**` 会递归收集目录内文件。

## 默认生成的 app.json
项目根目录没有 `app.json`，但存在 `index.html` 时，会生成以下默认配置：

```json
{
  "app": {
    "name": "BT-APP",
    "title": "BT-APP",
    "version": "1.0.0",
    "description": "BT桌面软件",
    "copyright": "Copyright 2026 BT",
    "mode": "static",
    "entry": "index.html",
    "main": "main.bt"
  },
  "window": {
    "width": 800,
    "height": 500,
    "resizable": true,
    "fullscreen": false,
    "hide_titlebar": false,
    "always_on_top": false
  },
  "dev": {
    "watch": true,
    "delay": 500,
    "devtools": true,
    "console": true
  },
  "resources": [
    "app.json",
    "index.html"
  ],
  "exclude": []
}
```

默认配置中的 `app.main` 指向 `main.bt`。如果目录中还没有 `main.bt`，运行器会创建一个空文件，确保项目可以直接启动。需要打包 `style.css`、`main.js`、图片等额外资源时，请手动把它们写入 `resources`，bt_app 不再从 HTML 标签中自动扫描资源。

## mode运行模式

### static
该模式为静态HTML加载方式，需要配置`app.entry`为入口 HTML 文件路径，例如 index.html。

### server
该模式会执行当前目录的 `server.bt` 脚本，并启动Web服务，需要配置 `app.entry` 为该Web服务的完整URL，例如 `http://127.0.0.1:18280`。
提示：请确保 `server.bt` 脚本文件存在，并能正确启动 BT Web 服务。

### remote
该模式会直接打开远程URL，需要配置 `app.entry` 为远程URL，例如 `https://example.com`。

### 运行机制
以上三种运行模式都会自动执行当前目录的 `app.main` 脚本，并注入 `window.bt` 对象，用于与BT脚本进行交互。
- 如果 `app.main` 配置为 `false`，则不会执行该脚本。
- 如果 `app.main` 配置不存在，则自动查找当前目录的 `main.bt` 脚本并执行。

## 注意事项
- `app.name` 和 `app.title` 不同：`name` 为打包输出的文件名，`title` 为程序窗口的标题。
- `app.icon` 只接受 `.ico` 格式的图标文件。
- `index.html` 只作为页面入口，不承担配置职责。