@yufengtadian/freedom-cli 1.12.17 → 1.13.0

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

@@ -7,10 +7,10 @@
 //     编译三平台。
 //   - backend：后端抽象。任意时刻绑定一个后端，前端 window.freedom.call 全部路由过去。
 //     内置两种实现：
-//       * EmbedBackend：Go 方法直接注册在壳进程内（app.Bind，兼容 v1 用法）。
-//       * ProcBackend：后端是任意语言实现的独立进程（Go/Rust/Python/Node/Java…），
-//         通过 stdin/stdout 上的 NDJSON/JSON-RPC 与壳通信。协议语言无关，
-//         换一种后端语言无需改壳与前端。
+//   - EmbedBackend：Go 方法直接注册在壳进程内（app.Bind，兼容 v1 用法）。
+//   - ProcBackend：后端是任意语言实现的独立进程（Go/Rust/Python/Node/Java…），
+//     通过 stdin/stdout 上的 NDJSON/JSON-RPC 与壳通信。协议语言无关，
+//     换一种后端语言无需改壳与前端。
 //   - ipc：双向桥接。前端 window.freedom.call(method, ...args) -> Promise；
 //     后端 app.Emit(event, data) 向所有前端监听器推送事件。
 //   - assets：前端编译产物（Vite 单文件 HTML）通过 go:embed 嵌入二进制，运行时
@@ -19,22 +19,31 @@ package freedom
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
+	"os"
 	"sync"
-	"unsafe"
+	"sync/atomic"
 
 	webview "github.com/webview/webview_go"
 )
 
+// Version 是应用版本号，构建期经 -ldflags "-X freedom.Version=x.y.z" 注入
+// （见 build.ps1/build.sh 的 -Version/VERSION）。前端经 os.info 的 appVersion 读取。
+var Version = "dev"
+
 // TitleBarMode 描述窗口标题栏策略。
 type TitleBarMode string
 
 const (
-	// TitleBarNative 保留系统原生标题栏（默认），标题栏图标与 exe 图标一致。
+	// TitleBarNative 保留系统原生标题栏（非默认；默认见 TitleBarFrameless）。
 	TitleBarNative TitleBarMode = "native"
+	// TitleBarHidden 隐藏标题栏视觉，但保留系统原生最小化 / 最大化 / 关闭按钮。
+	// 当前仅 Windows 生效（基于 DWM 扩展实现）；macOS / Linux 上回退为原生标题栏。
+	TitleBarHidden TitleBarMode = "hidden"
 	// TitleBarFrameless 完全无边框，客户区铺满整个窗口。
-	// 标题栏与系统原生最小化 / 最大化 / 关闭按钮均不存在，
-	// 需由前端自绘（通过 window.freedom.window.* 控制），三平台行为一致。
+	// 最小化 / 最大化 / 关闭按钮需由前端自绘（通过 window.freedom.window.* 控制），
+	// 三平台行为一致。
 	TitleBarFrameless TitleBarMode = "frameless"
 )
 
@@ -42,14 +51,15 @@ const (
 type Config struct {
 	// Title 是窗口标题。
 	Title string
-	// TitleBar 指定标题栏策略（默认 TitleBarNative）。可通过 freedom CLI 一键切换。
+	// TitleBar 指定标题栏策略（默认 TitleBarFrameless）。可通过 freedom CLI 一键切换。
 	TitleBar TitleBarMode
 	// Width / Height 是窗口初始尺寸（像素）。
 	Width  int
 	Height int
 	// Center 为 true 时窗口在屏幕居中（Windows 生效；macOS/Linux 由窗口管理器决定）。
 	Center bool
-	// MinWidth / MinHeight 为窗口最小尺寸（<=0 表示不限制）。
+	// MinWidth / MinHeight 为窗口最小尺寸。两个字段均 >0 时作为一组约束生效
+	//（webview 的 HintMin 按整组应用）；任一 <=0 表示不启用最小尺寸限制。
 	MinWidth  int
 	MinHeight int
 	// Debug 为 true 时开启 WebView 开发者工具（目标平台支持时）。
@@ -59,17 +69,86 @@ type Config struct {
 	// HTML 返回要加载到窗口的前端页面内容（内存加载，无本地端口）。
 	// 为 nil 时使用框架内置的默认占位页。
 	HTML func() (string, error)
+	// AppID 是应用标识，决定数据/配置目录名与单实例窗口类标题。
+	// 为空时回退可执行文件名（去扩展名）。一经发布不要更改，否则用户数据"丢失"。
+	AppID string
+	// RememberWindowState 为 true 时窗口位置/尺寸/最大化状态跨启动记忆
+	// （存于 <dataDir>/window-state.json；Windows 生效，其他平台暂不持久化）。
+	RememberWindowState bool
+	// Update 配置自动更新（ed25519 验签 manifest + sha256 校验产物）。
+	// 为 nil 时更新能力关闭。见 updater.go。
+	Update *UpdateConfig
+	// Capabilities 收口前端 sys/tray/window 三桥的可调用面（M3）。
+	// nil（默认）全开；语义见 capability.go。os.info 回显生效配置。
+	Capabilities *Capabilities
 }
 
 // App 是 Freedom 应用实例。
 type App struct {
-	cfg             Config
-	viewMu          sync.Mutex // 保护 view 字段（Run 写 / Emit·Quit·WindowHandle 任意 goroutine 读）
-	view            webview.WebView
-	backend         Backend
-	backendExplicit bool // 调用方是否显式指定了后端（外部 config.json 不应覆盖显式绑定）
-	onReady         func(a *App)
-	secure          bool // high 安全模式：资源加密 + 反调试 + 强制关闭 devtools（loadRuntimeConfig 置位）
+	cfg     Config
+	view    webview.WebView
+	viewMu  sync.RWMutex // 保护 view：Emit/Quit/WindowHandle 承诺可从任意 goroutine 调用
+	wsMu    sync.Mutex   // 串行化 window-state 落盘（拖拽异步保存可与销毁保存交叠）
+	backend Backend
+	onReady func(a *App)
+
+	// 运行时资源覆盖（resources.go）：secure = high 模式（app.bin 解密成功），
+	// backendExplicit = 用户经 Bind 显式使用内嵌后端（config.json 的 backend 不得再替换）。
+	secure          bool
+	backendExplicit bool
+
+	// upMu 保护 upPending：CheckUpdate 验签通过的更新条目，install 桥接只认它
+	//（前端无法注入未验签的 URL/哈希）。见 updater.go。
+	upMu         sync.Mutex
+	upPending    *UpdateInfo
+	upInstalling bool // 单飞：并发 update.install 只放行一个换装
+
+	// M2 多窗口注册表：windows 含 "main"，次级窗口关闭后自行摘除。
+	// winMu 同时保护 map、winSeq 与 running 标志（runningMu 并入，减少锁面）。
+	winMu   sync.Mutex
+	windows map[string]*Window
+	winSeq  int
+	running bool
+
+	// viewTearing 在 Run 的 Destroy 前置位（语义同 Window.tearing）：
+	// 主窗口已入队的 dispatch 回调会被销毁路径泵出执行，闭包凭此原子量自我作废。
+	viewTearing atomic.Bool
+}
+
+// appForEvents 指向当前运行的 App，供平台层回调（单实例/热键等）向 Emit 事件。
+// 契约：一个进程只跑一个 App——托盘/消息窗口/热键等平台层状态均为进程级单例，
+// 并发创建多个 App 会让事件串门。
+var appForEvents atomic.Pointer[App]
+
+func currentApp() *App { return appForEvents.Load() }
+
+// setView 设置主窗口 webview 引用。
+func (a *App) setView(w webview.WebView) {
+	a.viewMu.Lock()
+	a.view = w
+	a.viewMu.Unlock()
+}
+
+// withView 在 viewMu 读锁内对主窗口 webview 执行 f；未创建/已摘除时静默跳过。
+// 与 Run 的拆除序列（写锁内摘引用 + Destroy）互斥：调用方拿到引用并 Dispatch 的
+// 窗口期内实例不可能被销毁，杜绝 check-then-destroy 竞态下的 use-after-free。
+func (a *App) withView(f func(view webview.WebView)) {
+	a.viewMu.RLock()
+	defer a.viewMu.RUnlock()
+	if a.view != nil {
+		f(a.view)
+	}
+}
+
+// teardownView 是 Run 的回收 defer 与测试的同构入口：写锁内立拆除旗标、摘引用、
+// Destroy。Destroy 会泵出队列里的 dispatch 回调（闭包读 viewTearing 自我作废，
+// 不得再取 viewMu——回调就跑在本临界区内）。
+func (a *App) teardownView(view webview.WebView) {
+	a.viewMu.Lock()
+	defer a.viewMu.Unlock()
+	a.viewTearing.Store(true)
+	a.view = nil
+	view.Destroy()
 }
 
 // New 创建并初始化一个 Freedom 应用。调用 Run() 之前不会显示窗口。
@@ -77,8 +156,11 @@ func New(cfg Config) *App {
 	if cfg.Title == "" {
 		cfg.Title = "Freedom App"
 	}
+	// M1：默认无边框（frameless），与 freedom-cli 模板默认一致。
+	// 此前默认 native 而 CLI 默认 frameless，resources 缺失/配置不完整时
+	// 会出现"系统原生标题栏 + 页面自绘标题栏"双标题栏错位。
 	if cfg.TitleBar == "" {
-		cfg.TitleBar = TitleBarNative
+		cfg.TitleBar = TitleBarFrameless
 	}
 	if cfg.Width <= 0 {
 		cfg.Width = 1024
@@ -86,11 +168,10 @@ func New(cfg Config) *App {
 	if cfg.Height <= 0 {
 		cfg.Height = 768
 	}
-	explicit := cfg.Backend != nil
-	if !explicit {
+	if cfg.Backend == nil {
 		cfg.Backend = NewEmbedBackend()
 	}
-	return &App{cfg: cfg, backend: cfg.Backend, backendExplicit: explicit}
+	return &App{cfg: cfg, backend: cfg.Backend, windows: map[string]*Window{}}
 }
 
 // OnReady 注册一个回调，在窗口与桥接层就绪、页面加载前执行。
@@ -106,6 +187,9 @@ func (a *App) OnReady(fn func(a *App)) {
 //   - 参数与返回值通过 JSON 编解码，前端用 window.freedom.call(name, ...args) 调用，
 //     返回 Promise（resolve 为返回值，reject 为 error 的字符串表示）。
 //   - 返回值约定：可返回 (T, error) 或仅 (T) 或仅 error 或空。
+//   - 执行线程（M1 起）：绑定函数在 worker goroutine 中执行，UI 线程不被
+//     长任务阻塞；多次调用可并发、完成顺序不保证。handler 内调用 Emit 等
+//     线程安全 API 即可回推结果。
 func (a *App) Bind(name string, fn interface{}) error {
 	eb, ok := a.backend.(*EmbedBackend)
 	if !ok {
@@ -114,9 +198,8 @@ func (a *App) Bind(name string, fn interface{}) error {
 	if err := eb.Bind(name, fn); err != nil {
 		return err
 	}
-	// B56：用户显式绑定方法 = 显式指定内嵌后端。置位后外部 resources/config.json
-	// 的 backend 配置不再覆盖（loadRuntimeConfig 仅当 !backendExplicit 时生效），
-	// 避免"用户 Bind 的方法被 config.json 的进程后端静默替换而全部失效"。
+	// 用户显式绑定方法 = 显式指定内嵌后端：resources/config.json 的 backend
+	// 配置不再覆盖，避免内嵌方法被进程后端静默替换而全部失效。
 	a.backendExplicit = true
 	return nil
 }
@@ -128,35 +211,42 @@ func (a *App) Unbind(name string) {
 	}
 }
 
-// getView / setView 以互斥锁保护 view 字段：Run 在主 goroutine 写，
-// Emit/Quit/WindowHandle 可能被任意 goroutine（如后端事件推送）读，
-// 无保护时 race detector 报数据竞争。
-func (a *App) getView() webview.WebView {
-	a.viewMu.Lock()
-	defer a.viewMu.Unlock()
-	return a.view
-}
-
-func (a *App) setView(v webview.WebView) {
-	a.viewMu.Lock()
-	a.view = v
-	a.viewMu.Unlock()
-}
-
 // Run 启动窗口并进入主事件循环，阻塞直到窗口被关闭。
 func (a *App) Run() {
-	// 通用壳：先加载 exe 同目录 resources/config.json 覆盖窗口与后端配置
-	//（CLI build 时写入；缺失则使用编译期/默认配置）。
-	// 配置存在但非法时打印告警（不中断启动），避免用户手改配置出错时静默无感。
+	// 通用壳：先加载 exe 同目录 resources/ 覆盖窗口与后端配置（CLI build 写入；
+	// 缺失则使用编译期/默认配置）。配置存在但非法时打印告警不中断启动。
 	if err := a.loadRuntimeConfig(); err != nil {
+		// H2：high 模式资源解密/完整性校验失败必须拒绝运行——不显示窗口、
+		// 不回退占位页，防止资源被篡改/替换后静默降级运行。
+		var se *secureFatalError
+		if errors.As(err, &se) {
+			fmt.Printf("freedom: 安全模式资源校验失败，拒绝运行：%v\n", err)
+			return
+		}
 		fmt.Printf("freedom: warning: %v\n", err)
 	}
-
-	// high 安全模式：反调试检测（调试器下静默退出，防止逆向解密逻辑）。
+	// high 模式：反调试检测（调试器下静默退出，防止逆向解密逻辑）。
 	if a.secure {
 		antiDebugCheck()
 	}
-
+	// 平台层回调（单实例转发/热键）经 currentApp 找到本实例推送事件。
+	appForEvents.Store(a)
+	defer appForEvents.Store(nil)
+	// M2：标记运行中（NewWindow 的前置条件）并登记主窗口；退出前回收次级窗口。
+	a.winMu.Lock()
+	a.running = true
+	a.windows[mainWindowID] = &Window{id: mainWindowID, app: a, doneCh: make(chan struct{})}
+	a.winMu.Unlock()
+	defer func() {
+		a.CloseWindows()
+		a.winMu.Lock()
+		if mw := a.windows[mainWindowID]; mw != nil {
+			close(mw.doneCh) // 主窗口随 Run 退出回收：Window("main").WaitClosed() 可等待
+		}
+		delete(a.windows, mainWindowID)
+		a.running = false
+		a.winMu.Unlock()
+	}()
 	html, err := a.resolveHTML()
 	if err != nil {
 		fmt.Printf("freedom: failed to resolve HTML: %v\n", err)
@@ -165,21 +255,18 @@ func (a *App) Run() {
 
 	w := webview.New(a.cfg.Debug)
 	if w == nil {
-		if !webview2Available() {
-			fmt.Println("freedom: failed to create webview: 未检测到 WebView2 Runtime，请安装 Microsoft Edge WebView2 Runtime（https://go.microsoft.com/fwlink/?linkid=2124703）后重试")
-		} else {
-			fmt.Println("freedom: failed to create webview")
-		}
+		fmt.Println("freedom: failed to create webview")
 		return
 	}
 	a.setView(w)
 	defer func() {
-		_ = a.backend.Close()
-		// 先清空视图引用再销毁：Destroy 后 C 层 webview 对象已被 delete，
-		// 若此时仍有并发 goroutine（如后端事件推送触发的 Emit/Quit/WindowHandle）
-		// 持旧引用调用会访问悬垂指针导致随机崩溃。
-		a.setView(nil)
-		w.Destroy()
+		if err := a.backend.Close(); err != nil {
+			fmt.Fprintf(os.Stderr, "freedom: backend close: %v\n", err)
+		}
+		a.uninstallWindowEvents()
+		// 摘引用与 Destroy 必须同处一个写锁临界区：读锁侧（withView）判空后
+		// Dispatch 的窗口期内实例不会被销毁（否则 Emit/Quit/pushResolve UAF）。
+		a.teardownView(w)
 	}()
 
 	// 进程后端：启动后端进程并把其推送的事件转发到前端。
@@ -195,21 +282,24 @@ func (a *App) Run() {
 
 	w.SetTitle(a.cfg.Title)
 	w.SetSize(a.cfg.Width, a.cfg.Height, webview.HintNone)
-	// 最小尺寸：任一项 >0 即生效；未设置的一项传 0 表示该维度不限制
-	//（GTK gtk_widget_set_size_request / Cocoa minSize 对 0 均视为"未指定"）。
+	// 最小尺寸：任一项 >0 即生效；未设置的一项传 0 表示该维度不限制。
 	if a.cfg.MinWidth > 0 || a.cfg.MinHeight > 0 {
 		w.SetSize(a.cfg.MinWidth, a.cfg.MinHeight, webview.HintMin)
 	}
 	a.applyCenter()
 	a.applyTitleBar()
-	a.setWindowIcon()
+	// 窗口事件与关闭拦截（Windows 经 WndProc 子类化；其他平台 no-op）。
+	a.installWindowEvents()
+	// 恢复上次退出的窗口几何（仅 Config.RememberWindowState 时生效）。
+	a.restoreWindowState()
 
 	// 注入前端 SDK：window.freedom 全局对象。
 	w.Init(jsSDK)
 
-	// 绑定 IPC 桥接入口：前端 window.__freedom_bridge(method, paramsJson)。
-	// webview_go 的 Bind 会让前端调用返回 Promise，Go 侧结果自动 JSON 序列化回传。
-	if err := w.Bind("__freedom_bridge", a.bridge); err != nil {
+	// 绑定 IPC 桥接入口：前端 window.__freedom_bridge(id, method, paramsJson)。
+	// M1 异步化：调用立即返回，handler 在 worker goroutine 执行，结果经
+	// __freedom__resolve 回写前端 Promise（见 dispatch.go）。
+	if err := w.Bind("__freedom_bridge", a.bridgeAsync); err != nil {
 		fmt.Printf("freedom: failed to bind bridge: %v\n", err)
 		return
 	}
@@ -218,17 +308,50 @@ func (a *App) Run() {
 		fmt.Printf("freedom: failed to bind ping: %v\n", err)
 		return
 	}
-	// 框架内置方法：窗口控制（无边框模式下前端自绘按钮使用）。
-	// 支持动作：minimize / maximize / unmaximize / toggleMaximize / close / isMaximized / isFrameless。
+	// 框架内置方法：窗口控制（无边框模式下前端自绘按钮使用 + 运行时窗口能力）。
+	// 支持动作：minimize / maximize / unmaximize / toggleMaximize / close / isMaximized /
+	// isFrameless / setPosition / setSize / getPosition / getSize / innerSize / center /
+	// setTitle / show / hide / focus / isVisible / isFocused / isMinimized /
+	// setAlwaysOnTop / setSkipTaskbar / setResizable / setMaximizable / setMinimizable /
+	// setFullscreen / isFullscreen / interceptClose / getInfo。
+	// 第二参数为 JSON object 字符串（SDK 始终传入，可解析为空对象）。
 	if err := w.Bind("__freedom_window", a.windowControl); err != nil {
 		fmt.Printf("freedom: failed to bind window control: %v\n", err)
 		return
 	}
-
-	if a.onReady != nil {
-		a.onReady(a)
+	// 框架内置方法：原生系统能力（wails v3 对标层）。
+	// 支持方法：taskbar.*（进度/状态/角标）、window.backdrop/corner/borderColor、
+	// dialog.message/open/save。平台实现分文件：syscap_windows.go / syscap_other.go。
+	// 绑定入口带 M3 能力闸（见 capability.go）。
+	if err := w.Bind("__freedom_sys", a.sysCapGated); err != nil {
+		fmt.Printf("freedom: failed to bind sys capability: %v\n", err)
+		return
+	}
+	// 框架内置方法：系统托盘与原生菜单栏。
+	// 支持方法：tray.create/destroy/tooltip/menu、menu.set。
+	// 平台实现分文件：tray_windows.go / tray_other.go。绑定入口带 M3 能力闸。
+	if err := w.Bind("__freedom_tray", a.trayGated); err != nil {
+		fmt.Printf("freedom: failed to bind tray: %v\n", err)
+		return
+	}
+	// 框架内置方法：页面就绪回调（H3）。前端 SDK 在 DOMContentLoaded 后调用，
+	// 保证 onReady 触发时页面已加载、监听器已注册；此前 onReady 在 SetHtml 前
+	// 触发，期间 Emit 的初始化事件因 window.freedom 尚未建立而丢失。
+	// 页面可能因导航/重载多次触发 DOMContentLoaded，用 once 兜底只执行一次。
+	var readyOnce sync.Once
+	if err := w.Bind("__freedom__ready", func() {
+		readyOnce.Do(func() {
+			if a.onReady != nil {
+				a.onReady(a)
+			}
+		})
+	}); err != nil {
+		fmt.Printf("freedom: failed to bind ready: %v\n", err)
+		return
 	}
 
+	// 注：onReady 不再在 SetHtml 前触发（H3），改由前端 SDK 在页面
+	// DOMContentLoaded 后经 __freedom__ready 回调，保证初始化事件不丢失。
 	w.SetHtml(html)
 	w.Run()
 }
@@ -245,6 +368,12 @@ func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage,
 		}
 	}()
 
+	// 框架内置健康检查：__freedom__ping 同时以 JS 直调全局函数与桥接路由两种方式
+	// 暴露（占位页/文档示例走桥接路由），此处兜底保证两条链路行为一致。
+	if method == "__freedom__ping" {
+		return json.RawMessage(`"pong"`), nil
+	}
+
 	var params []json.RawMessage
 	if len(paramsJSON) > 0 && paramsJSON != "null" {
 		if err := json.Unmarshal([]byte(paramsJSON), &params); err != nil {
@@ -252,13 +381,6 @@ func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage,
 		}
 	}
 
-	// 框架内置方法特判：__freedom__ping 由 webview Bind 注册为全局函数
-	// window.__freedom__ping()，同时兼容经 freedom.call()/__freedom_bridge 路由的旧写法，
-	// 避免模板"测试桥接"自检报"method not bound"。
-	if method == "__freedom__ping" {
-		return json.RawMessage(`"pong"`), nil
-	}
-
 	raw, err := a.backend.Handle(method, params)
 	if err != nil {
 		return nil, err
@@ -273,50 +395,78 @@ func (a *App) bridge(method string, paramsJSON string) (result json.RawMessage,
 // Emit 把事件推送到前端。前端通过 window.freedom.on(event, cb) 订阅。
 // 线程安全：可从任意 goroutine 调用（进程后端推送的事件亦经由本函数）。
 func (a *App) Emit(event string, data interface{}) {
-	v := a.getView()
-	if v == nil {
-		return
-	}
 	eb, _ := json.Marshal(event)
 	db, err := json.Marshal(data)
 	if err != nil {
 		db = []byte("null")
 	}
 	js := "window.freedom && window.freedom.emit(" + string(eb) + "," + string(db) + ");"
-	v.Dispatch(func() {
-		v.Eval(js)
+	a.withView(func(view webview.WebView) {
+		view.Dispatch(func() {
+			if !a.viewTearing.Load() {
+				view.Eval(js)
+			}
+		})
 	})
+	a.emitSecondary(js) // M2：事件广播到全部次级窗口
 }
 
 // Quit 关闭窗口并退出应用。可从任意 goroutine 调用。
 func (a *App) Quit() {
-	if v := a.getView(); v != nil {
-		v.Dispatch(func() {
-			v.Terminate()
+	a.withView(func(view webview.WebView) {
+		view.Dispatch(func() {
+			if !a.viewTearing.Load() {
+				view.Terminate()
+			}
 		})
-	}
+	})
 }
 
 // WindowHandle 返回底层原生窗口句柄（Windows 上为 HWND）。
 func (a *App) WindowHandle() uintptr {
-	if v := a.getView(); v != nil {
-		return uintptr(unsafe.Pointer(v.Window()))
-	}
-	return 0
+	var h uintptr
+	a.withView(func(view webview.WebView) {
+		h = uintptr(view.Window())
+	})
+	return h
 }
 
 // windowControl 处理前端 window.freedom.window.* 的窗口控制请求。
 // 具体实现按平台分文件：window_windows.go（Windows）/ window_other.go（macOS、Linux）。
-func (a *App) windowControl(action string) (interface{}, error) {
-	return windowControl(a, action)
+func (a *App) windowControl(action string, paramsJSON string) (result interface{}, err error) {
+	// H1：windowControl 直接经 w.Bind 暴露给前端，不经 bridge 的 recover 兜底；
+	// 平台实现（如 appIcon → dibToPNG 解析越界）一旦 panic 会直接崩掉整个壳进程。
+	// 这里统一加 recover，把 panic 转成错误回传前端（页面 catch 后提示，进程不崩）。
+	defer func() {
+		if r := recover(); r != nil {
+			result = nil
+			err = fmt.Errorf("freedom: window action %q panicked: %v", action, r)
+		}
+	}()
+	// M3 能力闸先于一切动作处理（拒绝路径不触平台层，无副作用）。
+	if err := a.capCheckWindow(action); err != nil {
+		return nil, err
+	}
+	if res, ok, merr := a.windowManage(action, paramsJSON); ok {
+		return res, merr
+	}
+	return windowControl(a.WindowHandle(), action, a.cfg.TitleBar, paramsJSON)
 }
 
 // resolveHTML 依据配置返回页面内容。
-// 优先级：exe 同目录 resources/index.html（预编译通用壳，CLI build 写入）> cfg.HTML > 内置占位页。
+// 优先级：exe 同目录 resources/（high 模式 app.bin 或 index.html，预编译通用壳）
+// > cfg.HTML（go:embed 源码构建）> 内置占位页。
 func (a *App) resolveHTML() (string, error) {
-	if html, err := loadRuntimeHTML(); err == nil && html != "" {
+	html, err := loadRuntimeHTML()
+	if err == nil && html != "" {
 		return html, nil
 	}
+	// H2 双保险：high 模式校验失败时禁止回退 cfg.HTML/占位页（拒绝运行）。
+	// 正常路径下 Run 已捕获 secureFatalError 提前 return，此处防御调用顺序调整。
+	var se *secureFatalError
+	if errors.As(err, &se) {
+		return "", err
+	}
 	if a.cfg.HTML != nil {
 		return a.cfg.HTML()
 	}