@yufengtadian/freedom-cli 1.0.0

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

@@ -0,0 +1,257 @@
+// Package freedom 是一个从零自研的 WebView 桌面壳子框架（对标 Wails / Tauri）。
+//
+// Freedom 2.0 架构：
+//   - shell：跨平台渲染壳。复用各系统自带 WebView 内核（Windows WebView2 / macOS
+//     WKWebView / Linux WebKitGTK），通过跨平台库 webview_go 绑定，自身不携带浏览器
+//     内核。壳负责窗口生命周期、前端资源 embed、后端进程管理、IPC 路由。一份壳代码
+//     编译三平台。
+//   - backend：后端抽象。任意时刻绑定一个后端，前端 window.freedom.call 全部路由过去。
+//     内置两种实现：
+//       * 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 嵌入二进制，运行时
+//     直接 SetHtml 从内存加载，无需本地 HTTP 端口。
+package freedom
+
+import (
+	"encoding/json"
+	"fmt"
+	"unsafe"
+
+	webview "github.com/webview/webview_go"
+)
+
+// TitleBarMode 描述窗口标题栏策略。
+type TitleBarMode string
+
+const (
+	// TitleBarNative 保留系统原生标题栏（默认）。
+	TitleBarNative TitleBarMode = "native"
+	// TitleBarHidden 隐藏标题栏视觉，但保留系统原生最小化 / 最大化 / 关闭按钮。
+	// 当前仅 Windows 生效（基于 DWM 扩展实现）；macOS / Linux 上回退为原生标题栏。
+	TitleBarHidden TitleBarMode = "hidden"
+	// TitleBarFrameless 完全无边框，客户区铺满整个窗口。
+	// 最小化 / 最大化 / 关闭按钮需由前端自绘（通过 window.freedom.window.* 控制），
+	// 三平台行为一致。
+	TitleBarFrameless TitleBarMode = "frameless"
+)
+
+// Config 描述一个 Freedom 应用的窗口与运行配置。
+type Config struct {
+	// Title 是窗口标题。
+	Title string
+	// TitleBar 指定标题栏策略（默认 TitleBarNative）。可通过 freedom CLI 一键切换。
+	TitleBar TitleBarMode
+	// Width / Height 是窗口初始尺寸（像素）。
+	Width  int
+	Height int
+	// Center 为 true 时窗口在屏幕居中（Windows 生效；macOS/Linux 由窗口管理器决定）。
+	Center bool
+	// MinWidth / MinHeight 为窗口最小尺寸（<=0 表示不限制）。
+	MinWidth  int
+	MinHeight int
+	// Debug 为 true 时开启 WebView 开发者工具（目标平台支持时）。
+	Debug bool
+	// Backend 指定后端适配器。为空时默认使用内嵌 Go 后端（配合 Bind 使用）。
+	Backend Backend
+	// HTML 返回要加载到窗口的前端页面内容（内存加载，无本地端口）。
+	// 为 nil 时使用框架内置的默认占位页。
+	HTML func() (string, error)
+}
+
+// App 是 Freedom 应用实例。
+type App struct {
+	cfg     Config
+	view    webview.WebView
+	backend Backend
+	onReady func(a *App)
+}
+
+// New 创建并初始化一个 Freedom 应用。调用 Run() 之前不会显示窗口。
+func New(cfg Config) *App {
+	if cfg.Title == "" {
+		cfg.Title = "Freedom App"
+	}
+	if cfg.TitleBar == "" {
+		cfg.TitleBar = TitleBarNative
+	}
+	if cfg.Width <= 0 {
+		cfg.Width = 1024
+	}
+	if cfg.Height <= 0 {
+		cfg.Height = 768
+	}
+	if cfg.Backend == nil {
+		cfg.Backend = NewEmbedBackend()
+	}
+	return &App{cfg: cfg, backend: cfg.Backend}
+}
+
+// OnReady 注册一个回调，在窗口与桥接层就绪、页面加载前执行。
+// 回调内可以安全调用 Emit 向已注入的页面发送初始化事件。
+func (a *App) OnReady(fn func(a *App)) {
+	a.onReady = fn
+}
+
+// Bind 把后端 Go 方法暴露给前端。仅当后端为内嵌 Go 后端（默认）时有效；
+// 进程后端的方法由后端进程自身注册，此处调用会返回错误。
+//
+//   - fn 必须是函数。
+//   - 参数与返回值通过 JSON 编解码，前端用 window.freedom.call(name, ...args) 调用，
+//     返回 Promise（resolve 为返回值，reject 为 error 的字符串表示）。
+//   - 返回值约定：可返回 (T, error) 或仅 (T) 或仅 error 或空。
+func (a *App) Bind(name string, fn interface{}) error {
+	eb, ok := a.backend.(*EmbedBackend)
+	if !ok {
+		return fmt.Errorf("freedom: Bind 仅适用于内嵌 Go 后端；当前后端为 %T，方法请在进程后端中注册", a.backend)
+	}
+	return eb.Bind(name, fn)
+}
+
+// Unbind 移除先前 Bind 的方法（内嵌后端）。
+func (a *App) Unbind(name string) {
+	if eb, ok := a.backend.(*EmbedBackend); ok {
+		eb.Unbind(name)
+	}
+}
+
+// Run 启动窗口并进入主事件循环，阻塞直到窗口被关闭。
+func (a *App) Run() {
+	html, err := a.resolveHTML()
+	if err != nil {
+		fmt.Printf("freedom: failed to resolve HTML: %v\n", err)
+		return
+	}
+
+	w := webview.New(a.cfg.Debug)
+	if w == nil {
+		fmt.Println("freedom: failed to create webview")
+		return
+	}
+	a.view = w
+	defer func() {
+		_ = a.backend.Close()
+		w.Destroy()
+	}()
+
+	// 进程后端：启动后端进程并把其推送的事件转发到前端。
+	if pb, ok := a.backend.(*ProcBackend); ok {
+		pb.OnEvent(func(event string, data interface{}) {
+			a.Emit(event, data)
+		})
+		if err := pb.start(); err != nil {
+			fmt.Printf("freedom: backend start failed: %v\n", err)
+			return
+		}
+	}
+
+	w.SetTitle(a.cfg.Title)
+	w.SetSize(a.cfg.Width, a.cfg.Height, webview.HintNone)
+	if a.cfg.MinWidth > 0 && a.cfg.MinHeight > 0 {
+		w.SetSize(a.cfg.MinWidth, a.cfg.MinHeight, webview.HintMin)
+	}
+	a.applyCenter()
+	a.applyTitleBar()
+
+	// 注入前端 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 {
+		fmt.Printf("freedom: failed to bind bridge: %v\n", err)
+		return
+	}
+	// 框架内置方法：健康检查。
+	if err := w.Bind("__freedom__ping", func() string { return "pong" }); err != nil {
+		fmt.Printf("freedom: failed to bind ping: %v\n", err)
+		return
+	}
+	// 框架内置方法：窗口控制（无边框模式下前端自绘按钮使用）。
+	// 支持动作：minimize / maximize / unmaximize / toggleMaximize / close / isMaximized / isFrameless。
+	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)
+	}
+
+	w.SetHtml(html)
+	w.Run()
+}
+
+// bridge 是前端调用后端的统一入口（JSON-RPC 风格）。
+// 前端 SDK 通过 window.__freedom_bridge(method, paramsJson) 调用，
+// 桥接层把请求转发给当前绑定的后端（内嵌 Go 方法或任意语言进程）。
+func (a *App) bridge(method string, paramsJSON string) (json.RawMessage, error) {
+	var params []json.RawMessage
+	if len(paramsJSON) > 0 && paramsJSON != "null" {
+		if err := json.Unmarshal([]byte(paramsJSON), &params); err != nil {
+			return nil, fmt.Errorf("freedom: method %q: invalid params: %w", method, err)
+		}
+	}
+
+	result, err := a.backend.Handle(method, params)
+	if err != nil {
+		return nil, err
+	}
+	data, err := json.Marshal(result)
+	if err != nil {
+		return nil, fmt.Errorf("freedom: method %q: cannot marshal result: %w", method, err)
+	}
+	return json.RawMessage(data), nil
+}
+
+// Emit 把事件推送到前端。前端通过 window.freedom.on(event, cb) 订阅。
+// 线程安全：可从任意 goroutine 调用（进程后端推送的事件亦经由本函数）。
+func (a *App) Emit(event string, data interface{}) {
+	if a.view == 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) + ");"
+	a.view.Dispatch(func() {
+		a.view.Eval(js)
+	})
+}
+
+// Quit 关闭窗口并退出应用。可从任意 goroutine 调用。
+func (a *App) Quit() {
+	if a.view != nil {
+		a.view.Dispatch(func() {
+			a.view.Terminate()
+		})
+	}
+}
+
+// WindowHandle 返回底层原生窗口句柄（Windows 上为 HWND）。
+func (a *App) WindowHandle() uintptr {
+	if a.view == nil {
+		return 0
+	}
+	return uintptr(unsafe.Pointer(a.view.Window()))
+}
+
+// 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)
+}
+
+// resolveHTML 依据配置返回页面内容。
+func (a *App) resolveHTML() (string, error) {
+	if a.cfg.HTML != nil {
+		return a.cfg.HTML()
+	}
+	return defaultHTML, nil
+}

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

@@ -0,0 +1,8 @@
+//go:build !windows
+
+package freedom
+
+import "os/exec"
+
+// hideWindow 非 Windows 平台无控制台窗口概念，空实现占位。
+func hideWindow(_ *exec.Cmd) {}

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

@@ -0,0 +1,15 @@
+//go:build windows
+
+package freedom
+
+import (
+	"os/exec"
+	"syscall"
+)
+
+// hideWindow 让后端子进程（即使自身是控制台程序）不弹出 cmd 黑窗。
+// GUI 子系统父进程拉起 console 子进程时，Windows 默认会为其新建控制台窗口，
+// 设置 HideWindow 可使其在后台静默运行。
+func hideWindow(cmd *exec.Cmd) {
+	cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
+}

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

@@ -0,0 +1,25 @@
+//go:build !windows
+
+package freedom
+
+import "fmt"
+
+// applyTitleBar 在 macOS / Linux 上为空实现：
+// 原生标题栏由窗口管理器接管，hidden / frameless 模式暂回退为原生标题栏，
+// 前端仍可通过 window.freedom.window.isFrameless() 感知当前是否无边框。
+func (a *App) applyTitleBar() {}
+
+// windowControl 处理前端 window.freedom.window.* 请求（macOS / Linux 占位实现）。
+func windowControl(hwnd uintptr, action string, mode TitleBarMode) (interface{}, error) {
+	switch action {
+	case "isFrameless":
+		return mode == TitleBarFrameless || mode == TitleBarHidden, nil
+	case "isMaximized":
+		return false, nil
+	case "minimize", "maximize", "unmaximize", "restore", "toggleMaximize", "close":
+		// 非 Windows 平台暂不提供底层窗口控制，前端自绘按钮可对事件静默处理
+		return nil, nil
+	default:
+		return nil, fmt.Errorf("unknown window action %q", action)
+	}
+}

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

@@ -0,0 +1,133 @@
+//go:build windows
+
+package freedom
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// Windows 平台原生窗口操作（user32 / dwmapi）。
+// 供标题栏策略（applyTitleBar）与前端 window.freedom.window.* 控制使用。
+
+var (
+	user32win = syscall.NewLazyDLL("user32.dll")
+
+	procGetWindowLongPtr = user32win.NewProc("GetWindowLongPtrW")
+	procSetWindowLongPtr = user32win.NewProc("SetWindowLongPtrW")
+	procShowWindow       = user32win.NewProc("ShowWindow")
+	procCloseWindow      = user32win.NewProc("CloseWindow")
+	procIsZoomed         = user32win.NewProc("IsZoomed")
+	procSetWindowPos     = user32win.NewProc("SetWindowPos")
+	procSetWindowText    = user32win.NewProc("SetWindowTextW")
+
+	dwmapi                     = syscall.NewLazyDLL("dwmapi.dll")
+	procDwmExtendFrameIntoArea = dwmapi.NewProc("DwmExtendFrameIntoClientArea")
+)
+
+const (
+	wsCaption   = 0x00C00000 // WS_CAPTION = WS_BORDER | WS_DLGFRAME
+	wsSysMenu   = 0x00080000
+	wsThickFrame = 0x00040000
+
+	swHide      = 0
+	swShow      = 5
+	swMinimize  = 6
+	swRestore   = 9
+	swMaximize  = 3
+
+	swpFrameChanged = 0x0020
+	swpNoMove       = 0x0002
+	swpNoSize       = 0x0001
+	swpNoZOrder     = 0x0004
+	swpNoActivate   = 0x0010
+)
+
+// gwlStyle = GWL_STYLE（-16）。用变量声明，避免 uintptr 常量转换溢出。
+var gwlStyle = -16
+
+// margins 对应 DWM 的 MARGINS 结构（DwmExtendFrameIntoClientArea）。
+type margins struct {
+	cxLeftWidth, cxRightWidth, cyTopHeight, cyBottomHeight int32
+}
+
+func getWindowStyle(hwnd uintptr) uintptr {
+	r, _, _ := procGetWindowLongPtr.Call(hwnd, uintptr(int(gwlStyle)))
+	return r
+}
+
+func setWindowStyle(hwnd, style uintptr) {
+	procSetWindowLongPtr.Call(hwnd, uintptr(int(gwlStyle)), style)
+}
+
+func refreshFrame(hwnd uintptr) {
+	procSetWindowPos.Call(hwnd, 0, 0, 0, 0, 0,
+		swpFrameChanged|swpNoMove|swpNoSize|swpNoZOrder|swpNoActivate)
+}
+
+// windowControl 处理前端 window.freedom.window.* 请求（Windows 实现）。
+func windowControl(hwnd uintptr, action string, mode TitleBarMode) (interface{}, error) {
+	if hwnd == 0 {
+		return nil, fmt.Errorf("window not ready")
+	}
+	switch action {
+	case "minimize":
+		procShowWindow.Call(hwnd, swMinimize)
+		return nil, nil
+	case "maximize":
+		procShowWindow.Call(hwnd, swMaximize)
+		return nil, nil
+	case "unmaximize", "restore":
+		procShowWindow.Call(hwnd, swRestore)
+		return nil, nil
+	case "toggleMaximize":
+		if isZoomed(hwnd) {
+			procShowWindow.Call(hwnd, swRestore)
+		} else {
+			procShowWindow.Call(hwnd, swMaximize)
+		}
+		return nil, nil
+	case "close":
+		procCloseWindow.Call(hwnd)
+		return nil, nil
+	case "isMaximized":
+		return isZoomed(hwnd), nil
+	case "isFrameless":
+		return mode == TitleBarFrameless || mode == TitleBarHidden, nil
+	default:
+		return nil, fmt.Errorf("unknown window action %q", action)
+	}
+}
+
+func isZoomed(hwnd uintptr) bool {
+	r, _, _ := procIsZoomed.Call(hwnd)
+	return r != 0
+}
+
+// applyTitleBar 依据配置调整窗口标题栏（Windows 实现）。
+func (a *App) applyTitleBar() {
+	hwnd := a.WindowHandle()
+	if hwnd == 0 {
+		return
+	}
+	switch a.cfg.TitleBar {
+	case TitleBarFrameless:
+		// 完全无边框：去掉标题栏 / 系统菜单，客户区铺满整个窗口。
+		// 最小化 / 最大化 / 关闭按钮由前端自绘（window.freedom.window.*）。
+		style := getWindowStyle(hwnd)
+		style &^= wsCaption | wsSysMenu
+		setWindowStyle(hwnd, style)
+		refreshFrame(hwnd)
+	case TitleBarHidden:
+		// 隐藏标题栏视觉但保留系统原生按钮：DWM 玻璃扩展。
+		// 标题栏区域透明化并并入客户区，右上角的最小化 / 最大化 / 关闭按钮
+		// 由 DWM 继续原生绘制，标题文字置空。
+		m := margins{cxLeftWidth: 0, cxRightWidth: 0, cyTopHeight: 0, cyBottomHeight: 1}
+		procDwmExtendFrameIntoArea.Call(hwnd, uintptr(unsafe.Pointer(&m)))
+		// 标题文字一并清除，标题栏区域只保留系统按钮
+		procSetWindowText.Call(hwnd, uintptr(unsafe.Pointer(syscall.StringToUTF16Ptr(""))))
+		refreshFrame(hwnd)
+	default: // TitleBarNative：不处理
+	}
+}

package/templates/project/freedom.config.js

@@ -0,0 +1,42 @@
+// Freedom 应用配置。
+// 构建时由 freedom CLI 读取，生成对应的壳层配置。
+export default {
+  // 应用名（窗口标题 / 可执行文件名）。
+  name: 'freedom-app',
+
+  // 窗口初始尺寸（像素）。
+  width: 1024,
+  height: 720,
+
+  // 窗口最小尺寸（设为 0 表示不限制）。
+  minWidth: 400,
+  minHeight: 300,
+
+  // 启动时是否在屏幕居中。
+  center: true,
+
+  // 是否开启 WebView 开发者工具。
+  debug: false,
+
+  // 标题栏策略，在终端随时可改，三选一：
+  //   'native'    - 保留系统原生标题栏（默认）
+  //   'hidden'    - 隐藏标题栏视觉，仅保留 Windows 原生最小化 / 最大化 / 关闭按钮
+  //   'frameless' - 完全无边框，按钮由前端自绘（模板已内置自绘标题栏示例）
+  // 终端命令：freedom titlebar <native|hidden|frameless>
+  titlebar: 'native',
+
+  // 产物输出目录（相对项目根目录或绝对路径）：
+  //   'dist' - 输出到 dist/ 子目录（默认）
+  //   '.'    - 直接输出到项目根目录（dist 的上级），exe 与单文件 index.html 就地生成
+  //   'build/app' 等任意路径亦可
+  // 注意：输出到项目根目录时不会覆盖项目源文件（index.html 仅保留 src 源文件）。
+  outDir: 'dist',
+
+  // 后端策略：
+  //   undefined            - 仅使用框架内置能力（ping / 窗口控制），不启动独立后端进程
+  //   { command, args }    - 启动任意语言后端进程（Go/Node/Python/Rust 均可），
+  //                          经 stdin/stdout NDJSON 与壳通信，方法直接暴露给前端
+  // 示例（Node 后端）：
+  //   backend: { command: 'node', args: ['backend/main.mjs'] }
+  // backend: undefined,
+};

package/templates/project/index.html

@@ -0,0 +1,82 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Freedom App</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { height: 100%; }
+    body {
+      font-family: -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif;
+      background: #111827;
+      color: #e5e7eb;
+      display: flex;
+      flex-direction: column;
+      overflow: hidden;
+      user-select: none;
+    }
+
+    /* 无边框模式下的自绘标题栏（titlebar: 'frameless' 时显示） */
+    .titlebar {
+      display: none;
+      height: 38px;
+      flex: 0 0 38px;
+      align-items: center;
+      justify-content: space-between;
+      padding-left: 14px;
+      background: rgba(17, 24, 39, .92);
+      border-bottom: 1px solid rgba(156, 163, 175, .15);
+      -webkit-app-region: drag;
+    }
+    .titlebar .tb-title { font-size: 13px; color: #9ca3af; }
+    .tb-btns { display: flex; height: 100%; -webkit-app-region: no-drag; }
+    .tb-btn {
+      width: 46px; height: 100%;
+      display: flex; align-items: center; justify-content: center;
+      background: transparent; border: none;
+      color: #9ca3af; font-size: 13px;
+      font-family: "Segoe MDL2 Assets", "Segoe UI Symbol", sans-serif;
+    }
+    .tb-btn:hover { background: rgba(156, 163, 175, .2); color: #fff; }
+    .tb-btn.close:hover { background: #e81123; color: #fff; }
+    body.freedom-frameless .titlebar { display: flex; }
+
+    main {
+      flex: 1;
+      display: flex; flex-direction: column;
+      align-items: center; justify-content: center; gap: 14px;
+    }
+    h1 { font-size: 30px; font-weight: 700; }
+    .desc { color: #9ca3af; font-size: 14px; }
+    button {
+      padding: 10px 22px; border: none; border-radius: 10px;
+      background: #6366f1; color: #fff; font-size: 14px; cursor: pointer;
+    }
+    button:hover { background: #4f46e5; }
+    .result {
+      margin-top: 6px; padding: 8px 14px; border-radius: 8px;
+      background: rgba(99, 102, 241, .12); color: #a5b4fc; font-size: 13px;
+    }
+  </style>
+</head>
+<body>
+  <div class="titlebar">
+    <div class="tb-title">Freedom App</div>
+    <div class="tb-btns">
+      <button class="tb-btn" id="tbMin">&#xE921;</button>
+      <button class="tb-btn" id="tbMax">&#xE922;</button>
+      <button class="tb-btn close" id="tbClose">&#xE8BB;</button>
+    </div>
+  </div>
+
+  <main>
+    <h1>Freedom App</h1>
+    <div class="desc">你的桌面应用已就绪。</div>
+    <button id="pingBtn">测试桥接</button>
+    <div class="result" id="result">点击上方按钮验证前后端桥接。</div>
+  </main>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

package/templates/project/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "freedom-app",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "devDependencies": {
+    "vite": "^5.4.0",
+    "vite-plugin-singlefile": "^2.0.2"
+  }
+}

package/templates/project/src/main.js

@@ -0,0 +1,26 @@
+// Freedom 前端入口。
+// window.freedom 由壳层注入，无需 import。
+//   call(method, ...args) -> Promise    调用后端方法
+//   on(event, cb) / off(event, cb)       订阅 / 取消订阅后端事件
+//   window.minimize() / maximize() / close() 等窗口控制（无边框模式自绘按钮用）
+
+// 无边框模式：显示自绘标题栏并绑定按钮。
+if (window.freedom && window.freedom.window) {
+  window.freedom.window.isFrameless().then((frameless) => {
+    if (frameless) {
+      document.body.classList.add('freedom-frameless');
+      window.freedom.window.bindButtons({ min: '#tbMin', max: '#tbMax', close: '#tbClose' });
+    }
+  }).catch(() => {});
+}
+
+// 桥接自检。
+document.getElementById('pingBtn').addEventListener('click', async () => {
+  const el = document.getElementById('result');
+  try {
+    const r = await window.freedom.call('__freedom__ping');
+    el.textContent = '桥接正常：' + r;
+  } catch (e) {
+    el.textContent = '桥接异常：' + e.message;
+  }
+});

package/templates/project/vite.config.js

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+// 单文件打包：把所有 JS/CSS 内联进一个 index.html，
+// 便于 freedom CLI 嵌入 Go 壳层（内存加载，无本地端口）。
+// outDir 指向临时构建区 .freedom/vite-dist，最终产物由 freedom build 统一输出到
+// freedom.config.js 的 outDir（默认 dist/，可设为项目根目录）。
+export default defineConfig({
+  plugins: [viteSingleFile()],
+  build: {
+    target: 'esnext',
+    outDir: '.freedom/vite-dist',
+    assetsInlineLimit: 100000000,
+    chunkSizeWarningLimit: 100000000,
+    cssCodeSplit: false,
+    reportCompressedSize: false,
+  },
+});