@yufengtadian/freedom-cli 1.12.1 → 1.12.12

package/README.md

@@ -1,10 +1,22 @@
 # freedom-cli
 
-Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.12.1）。
+Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌面应用（v1.13.0）。
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
-**v1.12.0 核心升级**：标题栏默认改为完全无边框（`frameless`）——标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘融入 UI（模板已内置自绘标题栏示例），不再依赖 Windows 原生按钮。`freedom titlebar` 仍可随时切回 `native` / `hidden`。
+**v1.12.12 三平台 frameless 彻底修复**：macOS / Linux 无边框窗口不再残留原生标题栏——
+- 壳层向 webview_go 新增 `set_decorated` / `window_control` 原生窗口控制 API（GTK 走 `gtk_window_set_decorated` / `gtk_window_*`，Cocoa 走隐藏标题栏 + `performMiniaturize:` / `zoom:` / `performClose:` / `isZoomed`），mac/linux 的 frameless 从"空实现回退原生标题栏"修复为真无边框，UI 上方不再残留未清理的原生标题栏；
+- 自绘三按钮（最小化 / 最大化 / 关闭）在 macOS / Linux 上接入原生窗口控制，双击最大化 / 还原、`isMaximized` 状态查询真实可用（此前 mac/linux 窗口控制为静默空转、`isMaximized` 恒 false）；
+- 最大化语义统一为"铺满工作区"的正常窗口最大化：Windows 经 `WM_GETMINMAXINFO` 限定到监视器工作区（rcWork），macOS 走 `zoom:`、Linux 走 `gtk_window_maximize`，均非 F11 式整屏全屏；
+- 打包流程全程仍不依赖 Go 工具链（`freedom build` 直接复制预编译壳，详见 v1.1.11 说明）。
+
+**v1.12.11 标题栏优化**：自绘标题栏（frameless）增强——
+- 标题栏左侧显示应用图标，图标直接从 exe 内嵌图标（PE 资源 ID=1）提取为 PNG data URL，**不再依赖 resources 资源文件夹**里的任何图标文件，跨平台无 resources 依赖；
+- 双击标题栏空白区最大化 / 还原；
+- 右键标题栏弹出系统菜单（还原 / 最小化 / 最大化 / 关闭），并按窗口状态自动置灰；
+- 标题栏拖动改由 `window.freedom.window.startDrag()` 原生发起，保留双击与右键事件（`-webkit-app-region: drag` 会吞掉页面事件）。
+
+**v1.12.0 核心升级**：标题栏默认改为完全无边框（`frameless`）——标题栏不存在，关闭 / 最大化 / 最小化按钮由前端自绘融入 UI（模板已内置自绘标题栏示例），不再依赖 Windows 原生按钮。`freedom titlebar` 仍可随时切回 `native`。
 
 **v1.12.x 修复与加固**：
 - 修复 close 按钮缺陷：窗口关闭改走 `PostMessage(WM_CLOSE)`（原 `CloseWindow` 语义为最小化，导致点关闭只最小化）；
@@ -13,7 +25,7 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 - 壳进程启用 DPI 感知，高 DPI 屏幕下窗口坐标 / 渲染 / 鼠标自动化定位一致，内容更清晰；
 - `freedom config set` 兼容双引号配置写法；依赖变更检测改用 `package-lock.json` 作基准。
 
-**v1.11.0 核心升级**：支持自定义应用图标 + 默认隐藏 Windows 原生标题栏。配置 `freedom.config.js` 的 `icon`（Windows 用 `.ico`，macOS 用 `.icns`），`freedom build` 时自动把图标注入到 exe 的 PE 资源（RT_ICON / RT_GROUP_ICON）或 `.app/Contents/Resources`，无需任何资源编译器；`freedom icon <path>` 可一键设置。标题栏默认值由 `native` 调整为 `hidden`——保留 Windows 原生最小化 / 最大化 / 关闭按钮，隐藏标题栏视觉（DWM 扩展实现），默认不再占用窗口顶部空间。
+**v1.11.0 核心升级**：支持自定义应用图标 + 无边框标题栏。配置 `freedom.config.js` 的 `icon`（Windows 用 `.ico`，macOS 用 `.icns`），`freedom build` 时自动把图标注入到 exe 的 PE 资源（RT_ICON / RT_GROUP_ICON）或 `.app/Contents/Resources`，无需任何资源编译器；`freedom icon <path>` 可一键设置。标题栏默认使用无边框（`frameless`），窗口控制按钮由前端自绘，不再占用窗口顶部空间。
 
 **v1.10.12 核心升级**：macOS 产物升级为标准 .app 应用包，直接产出 `.app.zip`（mac 用户解压即得 `.app`，拖入 /Applications 即可使用）；在 macOS 上执行 `freedom dmg` 可再用系统 hdiutil 生成 `.dmg`。全程仍不依赖 Go 工具链。
 
@@ -21,7 +33,7 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 
 **v1.11.0 新特性**：
 - 自定义应用图标：`icon` 配置 + `freedom icon <path>` 命令，Windows 构建时用 rcedit 注入 `.ico` 到 exe 资源（支持多尺寸，资源管理器 / 任务栏 / 快捷方式统一显示），macOS 构建时把 `.icns` 放入 `.app` 并写入 Info.plist；
-- 标题栏默认改为 `hidden`：默认隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮；仍可用 `freedom titlebar` 随时切回 `native` / `frameless`。
+- 标题栏默认无边框（`frameless`）：标题栏与 Windows 原生最小化 / 最大化 / 关闭按钮均不存在，由前端自绘；仍可用 `freedom titlebar` 随时切回 `native`。
 
 **v1.10.12 新特性**：
 - macOS 产物打包为标准 `.app` bundle + `.app.zip`：壳复制进 `Contents/MacOS/`，resources 与前端/后端随包，解压即用，无需任何语言运行时；
@@ -54,7 +66,6 @@ freedom tui
 
 # 3. 调整标题栏（可选，随时可改；默认 frameless：标题栏不存在，关闭/最大化/最小化按钮由前端自绘融入 UI）
 freedom titlebar native      # 保留系统原生标题栏
-freedom titlebar hidden      # 隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
 freedom titlebar frameless   # 完全无边框，标题栏不存在，三按钮由前端自绘（默认，模板已内置示例）
 
 # 3.5 设置应用图标（可选；Windows 用 .ico，macOS 用 .icns）
@@ -64,7 +75,7 @@ freedom icon icon.ico
 freedom build                        # 默认当前平台
 freedom build --platform all         # 三平台全量（win + mac + linux）
 freedom build --platform win-x64     # 仅 Windows
-freedom build --platform mac-arm64   # 仅 macOS Apple Silicon
+freedom build --platform darwin-arm64   # 仅 macOS Apple Silicon
 freedom build --platform linux-x64   # 仅 Linux
 freedom build --no-cache             # 忽略前端构建缓存，强制重建
 ```
@@ -91,7 +102,7 @@ mac 用户解压 `.app.zip` 即得 `.app`，拖入 `/Applications` 即可直接
 
 **壳二进制平台校验**：`freedom build` 在分发前会读取壳二进制文件头，校验其确为目标平台的真实格式（Windows PE / macOS Mach-O / Linux ELF）。若某平台壳缺失或格式不匹配（例如误用其它平台的二进制顶替），会**明确报错并给出修复指引**，绝不静默产出无法运行的假产物。
 
-**预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。仓库已提供 `.github/workflows/build-shell.yml`：在 win / mac（Intel / Apple Silicon）/ linux runner 上分别编译真实壳并上传到 GitHub Release，供 `freedom shell download` 拉取。发布新版本时：先 `npm publish`，再创建同名 GitHub Release，手动触发 `build-shell` workflow（或直接发 Release 自动触发）即自动补齐各平台壳资产。
+**预编译壳的来源与 CI**：`webview_go` 依赖各系统自带 WebView 框架，**无法交叉编译**，三平台壳必须在对应平台本机编译。仓库已提供 `.github/workflows/build-shell.yml`：在 win / mac（Apple Silicon）/ linux runner 上分别编译真实壳并上传到 GitHub Release，供 `freedom shell download` 拉取（Intel Mac 已不支持，见 `nativePlatform()` 的明确报错）。发布新版本时：先 `npm publish`，再创建同名 GitHub Release，手动触发 `build-shell` workflow（或直接发 Release 自动触发）即自动补齐各平台壳资产。
 
 产物目录可在 `freedom.config.js` 的 `outDir` 中调整：默认 `'dist'`，设为 `'.'` 则直接输出到项目根目录（dist 的上级），设为任意相对 / 绝对路径亦可。输出到项目根目录时会自动跳过 `index.html` 副本，避免覆盖项目源文件。
 
@@ -104,11 +115,10 @@ freedom config set outDir dist  # 恢复默认 dist/
 
 | 模式 | 说明 |
 | --- | --- |
-| `native` | 保留系统原生标题栏 |
-| `hidden` | 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮（DWM 扩展实现） |
-| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例） |
+| `native` | 保留系统原生标题栏，标题栏图标与 exe 图标一致 |
+| `frameless` | 完全无边框，标题栏不存在，客户区铺满窗口，关闭 / 最大化 / 最小化按钮由前端自绘（默认，模板已内置示例）。当前仅 Windows 完整实现；macOS / Linux 由系统窗口管理器托管，回退为原生标题栏且窗口控制动作返回明确错误 |
 
-`hidden` / `frameless` 模式下，前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例。
+`frameless` 模式下（Windows），前端可通过注入的 `window.freedom.window` API 控制窗口（`minimize` / `maximize` / `toggleMaximize` / `close` / `isMaximized` / `isFrameless`），模板已内置自绘标题栏示例；macOS / Linux 上这些动作会 reject，前端应捕获并提示。
 
 ## 配置（freedom.config.js）
 
@@ -121,7 +131,7 @@ export default {
   minHeight: 300,
   center: true,          // 启动居中
   debug: false,          // 开发者工具
-  titlebar: 'frameless', // frameless（默认，标题栏不存在，三按钮由前端自绘）| native | hidden
+  titlebar: 'frameless', // frameless（默认，标题栏不存在，三按钮由前端自绘）| native
   icon: undefined,       // 应用图标：Windows 用 .ico（推荐多尺寸），macOS 用 .icns
   outDir: 'dist',        // 产物目录：'dist'（默认）| '.'（项目根目录）| 任意路径
   // backend: { command: 'node', args: ['backend/main.mjs'] },  // 任意语言后端进程
@@ -155,8 +165,8 @@ window.freedom.window.minimize();                       // 窗口控制
 ```
 freedom tui                          # 交互式终端界面
 freedom init <目录> [--force]
-freedom build [--platform win-x64|mac-arm64|linux-x64|all] [--no-cache]
-freedom titlebar <native|hidden|frameless>
+freedom build [--platform win-x64|darwin-arm64|linux-x64|all] [--no-cache]
+freedom titlebar <native|frameless>
 freedom icon <path>                    # 设置应用图标（Windows 用 .ico，macOS 用 .icns）
 freedom config [get|set]
 freedom shell list|download <platform>|build <platform>

package/lib/cli.js

@@ -19,7 +19,7 @@ freedom - Freedom 桌面壳打包工具 v${VERSION}
   freedom build [--platform <p>]       前端打包并分发桌面应用（默认当前平台）
       --platform win|mac|linux|all     指定目标平台（all = 三平台全量）
       --no-cache                       忽略前端构建缓存，强制重新打包
-  freedom titlebar <native|hidden|frameless>
+  freedom titlebar <native|frameless>
                                        一键切换标题栏策略
   freedom icon <path>                  设置应用图标（Windows 需 .ico，macOS 需 .icns）
   freedom shell list                   列出本地已就绪的预编译壳
@@ -42,9 +42,9 @@ macOS 产物说明：
   在 macOS 上执行 freedom dmg 用系统 hdiutil 生成。
 
 标题栏策略说明：
-  native    保留系统原生标题栏
-  hidden    隐藏标题栏视觉，仅保留 Windows 原生最小化/最大化/关闭按钮
-  frameless 完全无边框，标题栏不存在，关闭/最大化/最小化按钮由前端自绘（默认，模板已内置示例）
+  native    保留系统原生标题栏，标题栏图标与 exe 图标一致
+  frameless 完全无边框，标题栏与 Windows 原生最小化/最大化/关闭按钮均不存在，
+            关闭/最大化/最小化按钮由前端自绘（默认，模板已内置示例）
 
 图标说明：
   Windows exe 图标：在 freedom.config.js 配置 icon（.ico 路径），构建时自动注入；
@@ -107,8 +107,8 @@ async function run(argv) {
 
     case 'titlebar': {
       const mode = rest[0];
-      if (!['native', 'hidden', 'frameless'].includes(mode)) {
-        console.error('[freedom] 用法：freedom titlebar <native|hidden|frameless>');
+      if (!['native', 'frameless'].includes(mode)) {
+        console.error('[freedom] 用法：freedom titlebar <native|frameless>');
         return 1;
       }
       setConfig(process.cwd(), 'titlebar', mode);

package/lib/config.js

@@ -4,51 +4,114 @@ const fs = require('fs');
 const path = require('path');
 const { loadConfig, hasConfig } = require('./utils');
 
-// 配置文件中可安全写入的字段及其默认值（用于渲染或回填）。
-const KNOWN_KEYS = {
-  name: 'freedom-app',
-  width: 1024,
-  height: 720,
-  minWidth: 400,
-  minHeight: 300,
-  center: true,
-  debug: false,
-  titlebar: 'frameless',
-  icon: undefined,
-  outDir: 'dist',
+// 配置文件中可安全写入的字段：类型约束（写入前校验，防止坏值延迟到 build 才爆）。
+const KEY_TYPES = {
+  name: 'string',
+  width: 'int',
+  height: 'int',
+  minWidth: 'int',
+  minHeight: 'int',
+  center: 'bool',
+  debug: 'bool',
+  titlebar: 'titlebar',
+  icon: 'string',
+  outDir: 'string',
 };
 
-// 把配置写回 freedom.config.js（保留注释，只替换已知键的取值）。
+// 把 CLI/TUI 传入的值规范化为配置语义上的目标值；非法即抛错。
+function normalizeValue(key, value) {
+  const t = KEY_TYPES[key];
+  if (t === 'string') return String(value);
+  if (t === 'int') {
+    const n = Number(value);
+    if (!Number.isInteger(n)) {
+      throw new Error(`配置项 ${key} 需要整数值，收到：${JSON.stringify(value)}`);
+    }
+    return n;
+  }
+  if (t === 'bool') {
+    if (typeof value !== 'boolean') {
+      throw new Error(`配置项 ${key} 仅接受 true / false`);
+    }
+    return value;
+  }
+  if (t === 'titlebar') {
+    const s = String(value);
+    if (!['native', 'frameless'].includes(s)) {
+      throw new Error('titlebar 取值必须为：native / frameless。');
+    }
+    return s;
+  }
+  // 扩展键（如 backend）：字符串命令简写转 {command,args} 对象，
+  // 与 build.js renderConfigJSON 的契约对齐（纯字符串形态不会被打包为后端进程）。
+  if (key === 'backend') {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (typeof value === 'string') {
+      const parts = value.trim().split(/\s+/);
+      return { command: parts[0], args: parts.slice(1) };
+    }
+    return value; // 对象/数组形式原样写入
+  }
+  return value;
+}
+
+// 把值渲染为合法 JS 字面量。统一走 JSON.stringify：
+// 反斜杠 / 引号自动转义，且不存在 $ 替换模式注入面（配合函数式 replace 使用）。
+function renderLiteral(v) {
+  if (v === undefined) return 'undefined';
+  if (v === null) return 'null';
+  return JSON.stringify(v, null, typeof v === 'object' ? 2 : 0);
+}
+
+// 统计一行内 { 与 } 的差值，用于把多行对象字面量并入替换范围
+//（启发式实现；配置值内含花括号字符串的场景需手动编辑配置文件）。
+function braceDelta(line) {
+  let d = 0;
+  for (const ch of line) {
+    if (ch === '{') d++;
+    else if (ch === '}') d--;
+  }
+  return d;
+}
+
+// 把配置写回 freedom.config.js（保留注释与格式，只替换目标键所在行）。
+// 逐行定位且跳过注释行：模板中被注释的示例键（如 // backend: undefined,）不会被误改。
 function setConfig(dir, key, value) {
   const cfgPath = path.join(dir, 'freedom.config.js');
   if (!fs.existsSync(cfgPath)) {
     throw new Error('未找到 freedom.config.js。');
   }
   const text = fs.readFileSync(cfgPath, 'utf8');
+  const norm = normalizeValue(key, value);
+  const rendered = renderLiteral(norm);
 
-  if (key === 'titlebar') {
-    const modes = ['native', 'hidden', 'frameless'];
-    if (!modes.includes(value)) {
-      throw new Error(`titlebar 取值必须为：${modes.join(' / ')}。`);
+  const lines = text.split('\n');
+  const keyRe = new RegExp(`^(\\s*)${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:(.*)$`);
+  let replaced = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().startsWith('//')) continue; // 注释行不参与匹配与改写
+    const m = lines[i].match(keyRe);
+    if (!m) continue;
+    // 值为多行对象时吞并后续行直到花括号闭合，避免残留孤儿括号
+    let j = i;
+    let depth = braceDelta(lines[i]);
+    while (depth > 0 && j + 1 < lines.length) {
+      j++;
+      depth += braceDelta(lines[j]);
     }
+    const trailing = /,\s*$/.test(m[2]) ? ',' : '';
+    lines.splice(i, j - i + 1, `${m[1]}${key}: ${rendered}${trailing}`);
+    replaced = true;
+    break;
   }
-
-  // 同时兼容单引号与双引号字符串写法（模板统一单引号，用户手写可能用双引号）。
-  const regex = new RegExp(`(${key}\\s*:\\s*)(\"[^\"]*\"|'[^']*'|\\d+|true|false|undefined|null)`, 'g');
-  if (!regex.test(text)) {
-    throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到，请手动添加。`);
-  }
-
-  let rendered = String(value);
-  if (typeof value === 'string') {
-    rendered = `'${value.replace(/'/g, "\\'")}'`;
+  if (!replaced) {
+    throw new Error(`配置项 ${key} 未在 freedom.config.js 中找到（注释行不参与修改），请手动添加。`);
   }
-
-  const updated = text.replace(regex, `$1${rendered}`);
-  fs.writeFileSync(cfgPath, updated, 'utf8');
-  return value;
+  fs.writeFileSync(cfgPath, lines.join('\n'), 'utf8');
+  return norm;
 }
 
+
 async function getConfig(dir) {
   if (!hasConfig(dir)) {
     throw new Error('当前目录不是 Freedom 项目（缺少 freedom.config.js）。');
@@ -57,6 +120,27 @@ async function getConfig(dir) {
   return cfg;
 }
 
+// 配置文件中可安全写入的字段及其默认值（用于渲染或回填）。
+const KNOWN_KEYS = {
+  name: 'freedom-app',
+  width: 1024,
+  height: 720,
+  minWidth: 400,
+  minHeight: 300,
+  center: true,
+  debug: false,
+  titlebar: 'frameless',
+  icon: undefined,
+  outDir: 'dist',
+};
+
+async function getConfig(dir) {
+  if (!hasConfig(dir)) {
+    throw new Error('当前目录不是 Freedom 项目（缺少 freedom.config.js）。');
+  }
+  return loadConfig(dir);
+}
+
 async function showConfig(dir) {
   const cfg = await loadConfig(dir);
   const lines = Object.keys(KNOWN_KEYS).map((k) => {

package/lib/tui.js

@@ -192,7 +192,7 @@ const CONFIG_KEYS = [
   ['minHeight', '窗口最小高度'],
   ['center', '启动居中（true/false）'],
   ['debug', '开发者工具（true/false）'],
-  ['titlebar', '标题栏：native | hidden | frameless'],
+  ['titlebar', '标题栏：native | frameless'],
   ['icon', '应用图标：.ico（Windows）/ .icns（macOS）路径'],
   ['outDir', '产物目录：dist（默认）| .（项目根）| 任意路径'],
   ['backend', '任意语言后端进程（JSON）'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yufengtadian/freedom-cli",
-  "version": "1.12.1",
+  "version": "1.12.12",
   "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
   "keywords": [
     "desktop",

package/templates/go/err.txt

@@ -0,0 +1,2 @@
+# freedom-cli-shell/pkg/freedom
+pkg\freedom\freedom.go:212:16: cannot use a.backend.Handle(method, params) (value of type interface{}) as json.RawMessage value in assignment: need type assertion

package/templates/go/err4.txt

@@ -0,0 +1 @@
+github.com/webview/webview_go: build constraints exclude all Go files in D:\dev\自研desktop exe打包框架\freedom-cli\templates\go\webview_go

package/templates/go/go.mod

@@ -3,3 +3,9 @@ module freedom-cli-shell
 go 1.22
 
 require github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6
+
+require golang.org/x/sys v0.28.0
+
+// Freedom fork: 使用随包分发的本地 webview_go（标题栏图标与 exe 图标一致、
+// 无边框窗口最大化限定工作区、彻底清理非客户区等定制），避免拉取上游被覆盖。
+replace github.com/webview/webview_go => ./webview_go

package/templates/go/go.mod.bak_gbk

@@ -0,0 +1,11 @@
+module freedom-cli-shell
+
+go 1.22
+
+require github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6
+
+require golang.org/x/sys v0.28.0
+
+// Freedom fork: 使用随包分发的本地 webview_go（标题栏图标与 exe 图标一致等定制），
+// 避免拉取上游被覆盖。
+replace github.com/webview/webview_go => ./webview_go

package/templates/go/go.sum

@@ -1,2 +1,2 @@
-github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6 h1:VQpB2SpK88C6B5lPHTuSZKb2Qee1QWwiFlC5CKY4AW0=
-github.com/webview/webview_go v0.0.0-20240831120633-6173450d4dd6/go.mod h1:yE65LFCeWf4kyWD5re+h4XNvOHJEXOCOuJZ4v8l5sgk=
+golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
+golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

package/templates/go/pkg/freedom/assets/freedom.js

@@ -52,10 +52,16 @@
       minimize: function () { return windowAction('minimize'); },
       maximize: function () { return windowAction('maximize'); },
       unmaximize: function () { return windowAction('unmaximize'); },
+      restore: function () { return windowAction('unmaximize'); },
       toggleMaximize: function () { return windowAction('toggleMaximize'); },
       close: function () { return windowAction('close'); },
       isMaximized: function () { return windowAction('isMaximized'); },
       isFrameless: function () { return windowAction('isFrameless'); },
+      // 应用图标（data URL）。从 exe 内嵌图标提取，供自绘标题栏显示，不依赖 resources 资源文件夹。
+      appIcon: function () { return windowAction('appIcon'); },
+      // 标题栏 JS 拖动（WM_NCLBUTTONDOWN + HTCAPTION），比 -webkit-app-region: drag
+      // 更稳（保留双击最大化 / 右键菜单等页面事件）。非 Windows 平台为 no-op。
+      startDrag: function () { return windowAction('startDrag'); },
     },
   };
 

package/templates/go/pkg/freedom/assets/index.html

@@ -45,7 +45,7 @@
     font-size: 13px;
   }
 
-  /* 无边框模式：前端自绘标题栏（hidden / frameless 时显示） */
+  /* 无边框模式：前端自绘标题栏（frameless 时显示） */
   .titlebar {
     display: none;
     height: 36px;

package/templates/go/pkg/freedom/configfile.go

@@ -69,8 +69,6 @@ func (a *App) loadRuntimeConfig() error {
 	switch rc.TitleBar {
 	case "native":
 		a.cfg.TitleBar = TitleBarNative
-	case "hidden":
-		a.cfg.TitleBar = TitleBarHidden
 	case "frameless":
 		a.cfg.TitleBar = TitleBarFrameless
 	}

package/templates/go/pkg/freedom/freedom.go

@@ -29,14 +29,11 @@ import (
 type TitleBarMode string
 
 const (
-	// TitleBarNative 保留系统原生标题栏（默认）。
+	// TitleBarNative 保留系统原生标题栏（默认），标题栏图标与 exe 图标一致。
 	TitleBarNative TitleBarMode = "native"
-	// TitleBarHidden 隐藏标题栏视觉，但保留系统原生最小化 / 最大化 / 关闭按钮。
-	// 当前仅 Windows 生效（基于 DWM 扩展实现）；macOS / Linux 上回退为原生标题栏。
-	TitleBarHidden TitleBarMode = "hidden"
 	// TitleBarFrameless 完全无边框，客户区铺满整个窗口。
-	// 最小化 / 最大化 / 关闭按钮需由前端自绘（通过 window.freedom.window.* 控制），
-	// 三平台行为一致。
+	// 标题栏与系统原生最小化 / 最大化 / 关闭按钮均不存在，
+	// 需由前端自绘（通过 window.freedom.window.* 控制），三平台行为一致。
 	TitleBarFrameless TitleBarMode = "frameless"
 )
 
@@ -162,6 +159,7 @@ func (a *App) Run() {
 	}
 	a.applyCenter()
 	a.applyTitleBar()
+	a.setWindowIcon()
 
 	// 注入前端 SDK：window.freedom 全局对象。
 	w.Init(jsSDK)
@@ -195,7 +193,15 @@ func (a *App) Run() {
 // bridge 是前端调用后端的统一入口（JSON-RPC 风格）。
 // 前端 SDK 通过 window.__freedom_bridge(method, paramsJson) 调用，
 // 桥接层把请求转发给当前绑定的后端（内嵌 Go 方法或任意语言进程）。
-func (a *App) bridge(method string, paramsJSON string) (json.RawMessage, error) {
+func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage, err error) {
+	// 防御后端方法 panic 导致整个窗口崩溃：统一转为错误回传前端。
+	defer func() {
+		if r := recover(); r != nil {
+			result = nil
+			err = fmt.Errorf("freedom: method %q panicked: %v", method, r)
+		}
+	}()
+
 	var params []json.RawMessage
 	if len(paramsJSON) > 0 && paramsJSON != "null" {
 		if err := json.Unmarshal([]byte(paramsJSON), &params); err != nil {
@@ -203,11 +209,11 @@ func (a *App) bridge(method string, paramsJSON string) (json.RawMessage, error)
 		}
 	}
 
-	result, err := a.backend.Handle(method, params)
+	raw, err := a.backend.Handle(method, params)
 	if err != nil {
 		return nil, err
 	}
-	data, err := json.Marshal(result)
+	data, err := json.Marshal(raw)
 	if err != nil {
 		return nil, fmt.Errorf("freedom: method %q: cannot marshal result: %w", method, err)
 	}
@@ -251,7 +257,7 @@ func (a *App) WindowHandle() uintptr {
 // windowControl 处理前端 window.freedom.window.* 的窗口控制请求。
 // 具体实现按平台分文件：window_windows.go（Windows）/ window_other.go（macOS、Linux）。
 func (a *App) windowControl(action string) (interface{}, error) {
-	return windowControl(a.WindowHandle(), action, a.cfg.TitleBar)
+	return windowControl(a, action)
 }
 
 // resolveHTML 依据配置返回页面内容。

package/templates/go/pkg/freedom/window_other.go

@@ -2,24 +2,72 @@
 
 package freedom
 
-import "fmt"
+import (
+	"fmt"
 
-// applyTitleBar 在 macOS / Linux 上为空实现：
-// 原生标题栏由窗口管理器接管，hidden / frameless 模式暂回退为原生标题栏，
-// 前端仍可通过 window.freedom.window.isFrameless() 感知当前是否无边框。
-func (a *App) applyTitleBar() {}
+	webview "github.com/webview/webview_go"
+)
 
-// windowControl 处理前端 window.freedom.window.* 请求（macOS / Linux 占位实现）。
-func windowControl(hwnd uintptr, action string, mode TitleBarMode) (interface{}, error) {
+// applyTitleBar 在 macOS / Linux 上通过 webview 层的 set_decorated 控制原生标题栏：
+//   - frameless：GTK 走 gtk_window_set_decorated(FALSE)，Cocoa 走隐藏标题栏 + 透明标题栏
+//     + 移除原生最小化/关闭按钮，彻底去除"UI 上方残留原生标题栏"问题；
+//   - native：恢复系统原生标题栏。
+//
+// 窗口在 webview.New() 时已创建，故此处可安全调用（须在 UI 线程，即 Run 流程内）。
+func (a *App) applyTitleBar() {
+	if a.view == nil {
+		return
+	}
+	a.view.SetDecorated(a.cfg.TitleBar != TitleBarFrameless)
+}
+
+// setWindowIcon 在 macOS / Linux 上为空实现（图标由应用包 / 窗口管理器决定）。
+func (a *App) setWindowIcon() {}
+
+// windowControl 处理前端 window.freedom.window.* 请求（macOS / Linux 实现）。
+//
+// 窗口控制类动作（最小化/最大化/还原/关闭/查询）直接转发到 webview 层的原生
+// 窗口控制（GTK GtkWindow / Cocoa NSWindow），前端自绘标题栏三按钮因此可用：
+//   - GTK: gtk_window_iconify / maximize / unmaximize / close / is_maximized
+//   - Cocoa: performMiniaturize: / zoom: / performClose: / isZoomed
+//
+// 注意：webview 层窗口控制动作在 UI 线程执行（前端桥接本身运行于 UI 线程回调中，
+// webview_go 的 binding 回调在主线程派发），无需额外 Dispatch。
+func windowControl(a *App, action string) (interface{}, error) {
+	if a.view == nil {
+		return nil, fmt.Errorf("window not ready")
+	}
+	var act webview.WindowAction
 	switch action {
-	case "isFrameless":
-		return mode == TitleBarFrameless || mode == TitleBarHidden, nil
+	case "minimize":
+		act = webview.WindowMinimize
+	case "maximize":
+		act = webview.WindowMaximize
+	case "unmaximize", "restore":
+		act = webview.WindowRestore
+	case "toggleMaximize":
+		act = webview.WindowToggleMaximize
+	case "close":
+		act = webview.WindowClose
 	case "isMaximized":
-		return false, nil
-	case "minimize", "maximize", "unmaximize", "restore", "toggleMaximize", "close":
-		// 非 Windows 平台暂不提供底层窗口控制，前端自绘按钮可对事件静默处理
+		act = webview.WindowIsMaximized
+	case "isFrameless":
+		return a.cfg.TitleBar == TitleBarFrameless, nil
+	case "appIcon":
+		// macOS / Linux 暂不提供 exe 内嵌图标提取，前端隐藏标题栏图标。
+		return "", nil
+	case "startDrag":
+		// macOS / Linux 上无边框窗口通过 WebKit 的 -webkit-app-region: drag 拖动，
+		// 前端已在 CSS 中声明拖动区域；此处无需原生实现。
 		return nil, nil
 	default:
 		return nil, fmt.Errorf("unknown window action %q", action)
 	}
+	if act == webview.WindowIsMaximized {
+		return a.view.WindowControl(act) == 1, nil
+	}
+	if r := a.view.WindowControl(act); r != 0 {
+		return nil, fmt.Errorf("window action %q is not supported on this platform", action)
+	}
+	return nil, nil
 }