@yufengtadian/freedom-cli 1.13.1 → 1.13.3

package/templates/go/third_party/webview_go/libs/webview/vendor.go

@@ -0,0 +1,2 @@
+// Dummy file to allow vendoring.
+package vendor

package/templates/go/third_party/webview_go/libs/webview/version.txt

@@ -0,0 +1 @@
+fb6b17d826041411e6346cd9a785a5ceba7987c4

package/templates/go/third_party/webview_go/webkit2_40.go

@@ -0,0 +1,21 @@
+// 本地补丁（Freedom）：WebKitGTK 的 pkg-config 依赖名按构建标签选择，
+// 上游把它写死成 webkit2gtk-4.0，而 Ubuntu 24.04 / Debian 13 已移除 4.0，
+// 只保留同一套 C API 的 webkit2gtk-4.1 —— 写死会让 `go build` 在新发行版上直接失败。
+//
+// 选择规则（两个文件互斥，任何时刻只有一行 pkg-config 生效）：
+//
+//	默认（无标签）    → webkit2gtk-4.0（老发行版与既有 CI 产物基线不变）
+//	-tags webkit2_41 → webkit2gtk-4.1
+//
+// 构建脚本按 pkg-config 实际可用性自动决定是否加 -tags webkit2_41，见
+// freedom-cli/lib/webkit.js 与 tools/webkit-env.sh。
+// webkitgtk-6.0 是另一套 API（NetworkSession/权限处理器重写），不能按此桥接，需上游适配。
+
+//go:build !webkit2_41
+
+package webview
+
+/*
+#cgo linux openbsd freebsd netbsd pkg-config: gtk+-3.0 webkit2gtk-4.0
+*/
+import "C"

package/templates/go/third_party/webview_go/webkit2_41.go

@@ -0,0 +1,8 @@
+//go:build webkit2_41
+
+package webview
+
+/*
+#cgo linux openbsd freebsd netbsd pkg-config: gtk+-3.0 webkit2gtk-4.1
+*/
+import "C"

package/templates/go/third_party/webview_go/webview.cc

@@ -0,0 +1 @@
+#include "webview.h"

package/templates/go/third_party/webview_go/webview.go

@@ -0,0 +1,332 @@
+package webview
+
+/*
+#cgo CFLAGS: -I${SRCDIR}/libs/webview/include
+#cgo CXXFLAGS: -I${SRCDIR}/libs/webview/include -DWEBVIEW_STATIC
+
+#cgo linux openbsd freebsd netbsd CXXFLAGS: -DWEBVIEW_GTK -std=c++11
+#cgo linux openbsd freebsd netbsd LDFLAGS: -ldl
+// 本地补丁：webkit2gtk 的 pkg-config 名字不再写死为 4.0，改由 webkit2_40.go /
+// webkit2_41.go 按构建标签提供（Ubuntu 24.04+ 已移除 webkit2gtk-4.0）。
+
+#cgo darwin CXXFLAGS: -DWEBVIEW_COCOA -std=c++11
+#cgo darwin LDFLAGS: -framework WebKit -ldl
+
+#cgo windows CXXFLAGS: -DWEBVIEW_EDGE -std=c++14 -I${SRCDIR}/libs/mswebview2/include
+#cgo windows LDFLAGS: -static -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion
+
+#include "webview.h"
+
+#include <stdlib.h>
+#include <stdint.h>
+
+void CgoWebViewDispatch(webview_t w, uintptr_t arg);
+void CgoWebViewBind(webview_t w, const char *name, uintptr_t index);
+void CgoWebViewUnbind(webview_t w, const char *name);
+*/
+import "C"
+import (
+	_ "github.com/webview/webview_go/libs/mswebview2"
+	_ "github.com/webview/webview_go/libs/mswebview2/include"
+	_ "github.com/webview/webview_go/libs/webview"
+	_ "github.com/webview/webview_go/libs/webview/include"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"runtime"
+	"sync"
+	"unsafe"
+)
+
+func init() {
+	// Ensure that main.main is called from the main thread
+	runtime.LockOSThread()
+}
+
+// Hints are used to configure window sizing and resizing
+type Hint int
+
+const (
+	// Width and height are default size
+	HintNone = C.WEBVIEW_HINT_NONE
+
+	// Window size can not be changed by a user
+	HintFixed = C.WEBVIEW_HINT_FIXED
+
+	// Width and height are minimum bounds
+	HintMin = C.WEBVIEW_HINT_MIN
+
+	// Width and height are maximum bounds
+	HintMax = C.WEBVIEW_HINT_MAX
+)
+
+type WebView interface {
+
+	// Run runs the main loop until it's terminated. After this function exits -
+	// you must destroy the webview.
+	Run()
+
+	// Terminate stops the main loop. It is safe to call this function from
+	// a background thread.
+	Terminate()
+
+	// Dispatch posts a function to be executed on the main thread. You normally
+	// do not need to call this function, unless you want to tweak the native
+	// window.
+	Dispatch(f func())
+
+	// Destroy destroys a webview and closes the native window.
+	Destroy()
+
+	// Window returns a native window handle pointer. When using GTK backend the
+	// pointer is GtkWindow pointer, when using Cocoa backend the pointer is
+	// NSWindow pointer, when using Win32 backend the pointer is HWND pointer.
+	Window() unsafe.Pointer
+
+	// SetTitle updates the title of the native window. Must be called from the UI
+	// thread.
+	SetTitle(title string)
+
+	// SetSize updates native window size. See Hint constants.
+	SetSize(w int, h int, hint Hint)
+
+	// Navigate navigates webview to the given URL. URL may be a properly encoded data.
+	// URI. Examples:
+	// w.Navigate("https://github.com/webview/webview")
+	// w.Navigate("data:text/html,%3Ch1%3EHello%3C%2Fh1%3E")
+	// w.Navigate("data:text/html;base64,PGgxPkhlbGxvPC9oMT4=")
+	Navigate(url string)
+
+	// SetHtml sets the webview HTML directly.
+	// Example: w.SetHtml(w, "<h1>Hello</h1>");
+	SetHtml(html string)
+
+	// Init injects JavaScript code at the initialization of the new page. Every
+	// time the webview will open a the new page - this initialization code will
+	// be executed. It is guaranteed that code is executed before window.onload.
+	Init(js string)
+
+	// Eval evaluates arbitrary JavaScript code. Evaluation happens asynchronously,
+	// also the result of the expression is ignored. Use RPC bindings if you want
+	// to receive notifications about the results of the evaluation.
+	Eval(js string)
+
+	// Bind binds a callback function so that it will appear under the given name
+	// as a global JavaScript function. Internally it uses webview_init().
+	// Callback receives a request string and a user-provided argument pointer.
+	// Request string is a JSON array of all the arguments passed to the
+	// JavaScript function.
+	//
+	// f must be a function
+	// f must return either value and error or just error
+	Bind(name string, f interface{}) error
+
+	// Removes a callback that was previously set by Bind.
+	Unbind(name string) error
+}
+
+type webview struct {
+	w C.webview_t
+}
+
+var (
+	m        sync.Mutex
+	index    uintptr
+	dispatch = map[uintptr]func(){}
+	bindings = map[uintptr]func(id, req string) (interface{}, error){}
+)
+
+func boolToInt(b bool) C.int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// New calls NewWindow to create a new window and a new webview instance. If debug
+// is non-zero - developer tools will be enabled (if the platform supports them).
+func New(debug bool) WebView { return NewWindow(debug, nil) }
+
+// NewWindow creates a new webview instance. If debug is non-zero - developer
+// tools will be enabled (if the platform supports them). Window parameter can be
+// a pointer to the native window handle. If it's non-null - then child WebView is
+// embedded into the given parent window. Otherwise a new window is created.
+// Depending on the platform, a GtkWindow, NSWindow or HWND pointer can be passed
+// here.
+func NewWindow(debug bool, window unsafe.Pointer) WebView {
+	w := &webview{}
+	w.w = C.webview_create(boolToInt(debug), window)
+	return w
+}
+
+func (w *webview) Destroy() {
+	C.webview_destroy(w.w)
+}
+
+func (w *webview) Run() {
+	C.webview_run(w.w)
+}
+
+func (w *webview) Terminate() {
+	C.webview_terminate(w.w)
+}
+
+func (w *webview) Window() unsafe.Pointer {
+	return C.webview_get_window(w.w)
+}
+
+func (w *webview) Navigate(url string) {
+	s := C.CString(url)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_navigate(w.w, s)
+}
+
+func (w *webview) SetHtml(html string) {
+	s := C.CString(html)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_set_html(w.w, s)
+}
+
+func (w *webview) SetTitle(title string) {
+	s := C.CString(title)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_set_title(w.w, s)
+}
+
+func (w *webview) SetSize(width int, height int, hint Hint) {
+	C.webview_set_size(w.w, C.int(width), C.int(height), C.webview_hint_t(hint))
+}
+
+func (w *webview) Init(js string) {
+	s := C.CString(js)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_init(w.w, s)
+}
+
+func (w *webview) Eval(js string) {
+	s := C.CString(js)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_eval(w.w, s)
+}
+
+func (w *webview) Dispatch(f func()) {
+	m.Lock()
+	for ; dispatch[index] != nil; index++ {
+	}
+	dispatch[index] = f
+	m.Unlock()
+	C.CgoWebViewDispatch(w.w, C.uintptr_t(index))
+}
+
+//export _webviewDispatchGoCallback
+func _webviewDispatchGoCallback(index unsafe.Pointer) {
+	m.Lock()
+	f := dispatch[uintptr(index)]
+	delete(dispatch, uintptr(index))
+	m.Unlock()
+	f()
+}
+
+//export _webviewBindingGoCallback
+func _webviewBindingGoCallback(w C.webview_t, id *C.char, req *C.char, index uintptr) {
+	m.Lock()
+	f := bindings[uintptr(index)]
+	m.Unlock()
+	jsString := func(v interface{}) string { b, _ := json.Marshal(v); return string(b) }
+	status, result := 0, ""
+	if res, err := f(C.GoString(id), C.GoString(req)); err != nil {
+		status = -1
+		result = jsString(err.Error())
+	} else if b, err := json.Marshal(res); err != nil {
+		status = -1
+		result = jsString(err.Error())
+	} else {
+		status = 0
+		result = string(b)
+	}
+	s := C.CString(result)
+	defer C.free(unsafe.Pointer(s))
+	C.webview_return(w, id, C.int(status), s)
+}
+
+func (w *webview) Bind(name string, f interface{}) error {
+	v := reflect.ValueOf(f)
+	// f must be a function
+	if v.Kind() != reflect.Func {
+		return errors.New("only functions can be bound")
+	}
+	// f must return either value and error or just error
+	if n := v.Type().NumOut(); n > 2 {
+		return errors.New("function may only return a value or a value+error")
+	}
+
+	binding := func(id, req string) (interface{}, error) {
+		raw := []json.RawMessage{}
+		if err := json.Unmarshal([]byte(req), &raw); err != nil {
+			return nil, err
+		}
+
+		isVariadic := v.Type().IsVariadic()
+		numIn := v.Type().NumIn()
+		if (isVariadic && len(raw) < numIn-1) || (!isVariadic && len(raw) != numIn) {
+			return nil, errors.New("function arguments mismatch")
+		}
+		args := []reflect.Value{}
+		for i := range raw {
+			var arg reflect.Value
+			if isVariadic && i >= numIn-1 {
+				arg = reflect.New(v.Type().In(numIn - 1).Elem())
+			} else {
+				arg = reflect.New(v.Type().In(i))
+			}
+			if err := json.Unmarshal(raw[i], arg.Interface()); err != nil {
+				return nil, err
+			}
+			args = append(args, arg.Elem())
+		}
+		errorType := reflect.TypeOf((*error)(nil)).Elem()
+		res := v.Call(args)
+		switch len(res) {
+		case 0:
+			// No results from the function, just return nil
+			return nil, nil
+		case 1:
+			// One result may be a value, or an error
+			if res[0].Type().Implements(errorType) {
+				if res[0].Interface() != nil {
+					return nil, res[0].Interface().(error)
+				}
+				return nil, nil
+			}
+			return res[0].Interface(), nil
+		case 2:
+			// Two results: first one is value, second is error
+			if !res[1].Type().Implements(errorType) {
+				return nil, errors.New("second return value must be an error")
+			}
+			if res[1].Interface() == nil {
+				return res[0].Interface(), nil
+			}
+			return res[0].Interface(), res[1].Interface().(error)
+		default:
+			return nil, errors.New("unexpected number of return values")
+		}
+	}
+
+	m.Lock()
+	for ; bindings[index] != nil; index++ {
+	}
+	bindings[index] = binding
+	m.Unlock()
+	cname := C.CString(name)
+	defer C.free(unsafe.Pointer(cname))
+	C.CgoWebViewBind(w.w, cname, C.uintptr_t(index))
+	return nil
+}
+
+func (w *webview) Unbind(name string) error {
+	cname := C.CString(name)
+	defer C.free(unsafe.Pointer(cname))
+	C.CgoWebViewUnbind(w.w, cname)
+	return nil
+}

package/templates/installer/app.nsi

@@ -0,0 +1,43 @@
+; Freedom NSIS 安装器模板（freedom build --installer 填充 @...@ 占位符后编译）。
+; 占位符：@NAME@ 应用名 / @VERSION@ 版本 / @SRC@ 产物目录（exe + resources）
+;        @OUT@ 输出目录 / @EXE@ 可执行文件名。
+Unicode true
+!include "MUI2.nsh"
+
+!define APPNAME "@NAME@"
+!define VERSION "@VERSION@"
+!define SRC "@SRC@"
+!define OUT "@OUT@"
+!define EXE "@EXE@"
+
+Name "${APPNAME}"
+OutFile "${OUT}\${APPNAME}-setup-${VERSION}.exe"
+InstallDir "$PROGRAMFILES64\${APPNAME}"
+InstallDirRegKey HKLM "Software\${APPNAME}" "InstallDir"
+RequestExecutionLevel admin
+
+!insertmacro MUI_PAGE_DIRECTORY
+!insertmacro MUI_PAGE_INSTFILES
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+!insertmacro MUI_LANGUAGE "SimpChinese"
+
+Section "Install"
+  SetOutPath "$INSTDIR"
+  File /r "${SRC}\*.*"
+  WriteUninstaller "$INSTDIR\uninstall.exe"
+  CreateShortCut "$DESKTOP\${APPNAME}.lnk" "$INSTDIR\${EXE}"
+  CreateShortCut "$SMPROGRAMS\${APPNAME}.lnk" "$INSTDIR\${EXE}"
+  WriteRegStr HKLM "Software\${APPNAME}" "InstallDir" "$INSTDIR"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" "DisplayName" "${APPNAME}"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" "DisplayVersion" "${VERSION}"
+  WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}" "UninstallString" "$INSTDIR\uninstall.exe"
+SectionEnd
+
+Section "Uninstall"
+  RMDir /r "$INSTDIR"
+  Delete "$DESKTOP\${APPNAME}.lnk"
+  Delete "$SMPROGRAMS\${APPNAME}.lnk"
+  DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${APPNAME}"
+  DeleteRegKey HKLM "Software\${APPNAME}"
+SectionEnd

package/templates/project/freedom.config.js

@@ -54,4 +54,18 @@ export default {
   // 示例（Node 后端）：
   //   backend: { command: 'node', args: ['backend/main.mjs'] }
   // backend: undefined,
+
+  // 单实例：true 时二次启动把命令行参数转发给已运行实例后自动退出，
+  //         主实例前端收 freedom.on('app.secondInstance', ({args})=>…)（Windows 生效）。
+  // singleInstance: false,
+
+  // 自动更新（发布环：freedom keygen 生成密钥 → 公钥填这里 → 发版 freedom manifest 签 latest.json）：
+  // updater: {
+  //   manifestURL: 'https://your.host/latest.json',
+  //   publicKey: '<freedom keygen 输出的 base64 公钥>',
+  //   requireSignature: false, // 开启后产物还须通过平台代码签名复核（仅 Windows）
+  // },
+
+  // dev 流自定义启动命令（默认 `npm run dev`，freedom dev 用它拉起 vite 并热更壳窗口）：
+  // dev: { command: 'npm run dev' },
 };

package/templates/project/freedom.d.ts

@@ -0,0 +1,77 @@
+// Freedom 桌面壳前端 SDK 类型声明（window.freedom）
+// 运行时由壳注入（assets/freedom.js）；本文件仅类型提示，不参与打包产物。
+// 用法：tsconfig "include": ["src", "freedom.d.ts"]，直接 window.freedom.* 获得补全。
+
+export {};
+
+interface FreedomWindowAPI {
+  minimize(): Promise<void>;
+  maximize(): Promise<void>;
+  unmaximize(): Promise<void>;
+  toggleMaximize(): Promise<boolean>;
+  close(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  isFrameless(): Promise<boolean>;
+  show(): Promise<void>;
+  hide(): Promise<void>;
+  focus(): Promise<void>;
+  setPosition(x: number, y: number): Promise<void>;
+  setSize(w: number, h: number): Promise<void>;
+  getPosition(): Promise<{ x: number; y: number }>;
+  getSize(): Promise<{ width: number; height: number }>;
+  setAlwaysOnTop(on: boolean): Promise<void>;
+  setFullscreen(on: boolean): Promise<void>;
+  startDrag(): Promise<void>;
+  /** 多窗口：spec.url 或 spec.html 指定页面，返回 {id} */
+  create(spec: { title?: string; url?: string; html?: string; width?: number; height?: number }): Promise<{ id: string }>;
+  list(): Promise<Array<{ id: string; title?: string }>>;
+  focusWindow(id: string): Promise<void>;
+  closeWindow(id: string): Promise<void>;
+}
+
+interface FreedomAPI {
+  /** 调用后端方法（任意语言后端，NDJSON/JSON-RPC over stdio），返回 Promise。 */
+  call(method: string, ...args: unknown[]): Promise<any>;
+  invoke(method: string, ...args: unknown[]): Promise<any>;
+  /** 订阅后端推送事件，返回取消订阅函数。 */
+  on(event: string, fn: (data: any) => void): () => void;
+  off(event: string, fn: (data: any) => void): void;
+  once(event: string, fn: (data: any) => void): () => void;
+  emit(event: string, data?: unknown): void;
+
+  window: FreedomWindowAPI;
+  /** 系统能力总入口（taskbar/backdrop/dialog 等，平台差异见 README 能力矩阵）。 */
+  sys: Record<string, (params?: unknown) => Promise<any>>;
+  clipboard: { read(): Promise<string>; write(text: string): Promise<void> };
+  shell: { open(url: string): Promise<void> };
+  notification: { show(opts: { title: string; body?: string }): Promise<void> };
+  shortcut: { register(combo: string, fn: () => void): Promise<() => void> };
+  autostart: { enable(): Promise<void>; disable(): Promise<void>; isEnabled(): Promise<boolean> };
+  protocol: { register(scheme: string): Promise<void>; unregister(scheme: string): Promise<void> };
+  app: { launchArgs(): Promise<string[]> };
+  path: { get(kind: string, name?: string): Promise<string> };
+  store: {
+    get(namespace: string, key: string): Promise<any>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+    delete(namespace: string, key: string): Promise<void>;
+    keys(namespace: string): Promise<string[]>;
+  };
+  os: { info(): Promise<Record<string, any>> };
+  process: { exit(): Promise<void>; restart(): Promise<void> };
+  /** 自动更新：check 验签后缓存条目；install 仅认 check 结果，进度经 update.* 事件回推。 */
+  update: { check(): Promise<void>; install(): Promise<void> };
+  taskbar: Record<string, (params?: unknown) => Promise<any>>;
+  dialog: {
+    message(opts: { title?: string; text: string; type?: string }): Promise<any>;
+    open(opts?: Record<string, any>): Promise<string | string[] | null>;
+    save(opts?: Record<string, any>): Promise<string | null>;
+  };
+  tray: Record<string, (params?: unknown) => Promise<any>>;
+  menu: Record<string, (params?: unknown) => Promise<any>>;
+}
+
+declare global {
+  interface Window {
+    freedom: FreedomAPI;
+  }
+}

package/templates/project-minimal/freedom.config.js

@@ -55,4 +55,18 @@ export default {
   // 示例（Node 后端）：
   //   backend: { command: 'node', args: ['backend/main.mjs'] }
   // backend: undefined,
+
+  // 单实例：true 时二次启动把命令行参数转发给已运行实例后自动退出，
+  //         主实例前端收 freedom.on('app.secondInstance', ({args})=>…)（Windows 生效）。
+  // singleInstance: false,
+
+  // 自动更新（发布环：freedom keygen 生成密钥 → 公钥填这里 → 发版 freedom manifest 签 latest.json）：
+  // updater: {
+  //   manifestURL: 'https://your.host/latest.json',
+  //   publicKey: '<freedom keygen 输出的 base64 公钥>',
+  //   requireSignature: false, // 开启后产物还须通过平台代码签名复核（仅 Windows）
+  // },
+
+  // dev 流自定义启动命令（默认 `npm run dev`，freedom dev 用它拉起 vite 并热更壳窗口）：
+  // dev: { command: 'npm run dev' },
 };

package/templates/project-minimal/freedom.d.ts

@@ -0,0 +1,77 @@
+// Freedom 桌面壳前端 SDK 类型声明（window.freedom）
+// 运行时由壳注入（assets/freedom.js）；本文件仅类型提示，不参与打包产物。
+// 用法：tsconfig "include": ["src", "freedom.d.ts"]，直接 window.freedom.* 获得补全。
+
+export {};
+
+interface FreedomWindowAPI {
+  minimize(): Promise<void>;
+  maximize(): Promise<void>;
+  unmaximize(): Promise<void>;
+  toggleMaximize(): Promise<boolean>;
+  close(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  isFrameless(): Promise<boolean>;
+  show(): Promise<void>;
+  hide(): Promise<void>;
+  focus(): Promise<void>;
+  setPosition(x: number, y: number): Promise<void>;
+  setSize(w: number, h: number): Promise<void>;
+  getPosition(): Promise<{ x: number; y: number }>;
+  getSize(): Promise<{ width: number; height: number }>;
+  setAlwaysOnTop(on: boolean): Promise<void>;
+  setFullscreen(on: boolean): Promise<void>;
+  startDrag(): Promise<void>;
+  /** 多窗口：spec.url 或 spec.html 指定页面，返回 {id} */
+  create(spec: { title?: string; url?: string; html?: string; width?: number; height?: number }): Promise<{ id: string }>;
+  list(): Promise<Array<{ id: string; title?: string }>>;
+  focusWindow(id: string): Promise<void>;
+  closeWindow(id: string): Promise<void>;
+}
+
+interface FreedomAPI {
+  /** 调用后端方法（任意语言后端，NDJSON/JSON-RPC over stdio），返回 Promise。 */
+  call(method: string, ...args: unknown[]): Promise<any>;
+  invoke(method: string, ...args: unknown[]): Promise<any>;
+  /** 订阅后端推送事件，返回取消订阅函数。 */
+  on(event: string, fn: (data: any) => void): () => void;
+  off(event: string, fn: (data: any) => void): void;
+  once(event: string, fn: (data: any) => void): () => void;
+  emit(event: string, data?: unknown): void;
+
+  window: FreedomWindowAPI;
+  /** 系统能力总入口（taskbar/backdrop/dialog 等，平台差异见 README 能力矩阵）。 */
+  sys: Record<string, (params?: unknown) => Promise<any>>;
+  clipboard: { read(): Promise<string>; write(text: string): Promise<void> };
+  shell: { open(url: string): Promise<void> };
+  notification: { show(opts: { title: string; body?: string }): Promise<void> };
+  shortcut: { register(combo: string, fn: () => void): Promise<() => void> };
+  autostart: { enable(): Promise<void>; disable(): Promise<void>; isEnabled(): Promise<boolean> };
+  protocol: { register(scheme: string): Promise<void>; unregister(scheme: string): Promise<void> };
+  app: { launchArgs(): Promise<string[]> };
+  path: { get(kind: string, name?: string): Promise<string> };
+  store: {
+    get(namespace: string, key: string): Promise<any>;
+    set(namespace: string, key: string, value: unknown): Promise<void>;
+    delete(namespace: string, key: string): Promise<void>;
+    keys(namespace: string): Promise<string[]>;
+  };
+  os: { info(): Promise<Record<string, any>> };
+  process: { exit(): Promise<void>; restart(): Promise<void> };
+  /** 自动更新：check 验签后缓存条目；install 仅认 check 结果，进度经 update.* 事件回推。 */
+  update: { check(): Promise<void>; install(): Promise<void> };
+  taskbar: Record<string, (params?: unknown) => Promise<any>>;
+  dialog: {
+    message(opts: { title?: string; text: string; type?: string }): Promise<any>;
+    open(opts?: Record<string, any>): Promise<string | string[] | null>;
+    save(opts?: Record<string, any>): Promise<string | null>;
+  };
+  tray: Record<string, (params?: unknown) => Promise<any>>;
+  menu: Record<string, (params?: unknown) => Promise<any>>;
+}
+
+declare global {
+  interface Window {
+    freedom: FreedomAPI;
+  }
+}