@binblink/wasmnest-plugin-sdk-desktop 0.0.0-stage → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/README.md +287 -2
  2. package/README_en.md +284 -0
  3. package/bin/cli.js +602 -0
  4. package/bin/manifest-gen.js +454 -0
  5. package/bin/manifest-validate.js +432 -0
  6. package/bin/permission-vocabulary.json +5 -0
  7. package/bin/plugin-watch.js +331 -0
  8. package/bin/wasm-hash.js +124 -0
  9. package/dev-shell/README.md +121 -0
  10. package/dev-shell/index.html +12 -0
  11. package/dev-shell/package.json +28 -0
  12. package/dev-shell/pnpm-workspace.yaml +9 -0
  13. package/dev-shell/postcss.config.js +6 -0
  14. package/dev-shell/src/App.vue +90 -0
  15. package/dev-shell/src/components/LogPanel.vue +90 -0
  16. package/dev-shell/src/loader.ts +109 -0
  17. package/dev-shell/src/locale.ts +29 -0
  18. package/dev-shell/src/locales.ts +50 -0
  19. package/dev-shell/src/main.ts +46 -0
  20. package/dev-shell/src/mock/agent-hub-commands.ts +1065 -0
  21. package/dev-shell/src/mock/agent-hub.ts +42 -0
  22. package/dev-shell/src/mock/app-env.ts +102 -0
  23. package/dev-shell/src/mock/commands.ts +54 -0
  24. package/dev-shell/src/mock/domain-context.ts +46 -0
  25. package/dev-shell/src/mock/events.ts +16 -0
  26. package/dev-shell/src/mock/file-transfer.ts +512 -0
  27. package/dev-shell/src/mock/tauri-ipc.ts +109 -0
  28. package/dev-shell/src/registry.ts +90 -0
  29. package/dev-shell/src/shell/components/AppMountSlot.vue +241 -0
  30. package/dev-shell/src/shell/components/ShellIcon.vue +141 -0
  31. package/dev-shell/src/shell/components/ShellStatusBar.vue +87 -0
  32. package/dev-shell/src/shell/components/ShellToolbar.vue +287 -0
  33. package/dev-shell/src/shell/mount/appSession.ts +45 -0
  34. package/dev-shell/src/shell/mount/devAppMount.ts +80 -0
  35. package/dev-shell/src/shell/types.ts +132 -0
  36. package/dev-shell/src/styles/dev.css +27 -0
  37. package/dev-shell/src/styles/shell.css +546 -0
  38. package/dev-shell/src/styles/style.css +1132 -0
  39. package/dev-shell/src/theme.ts +140 -0
  40. package/dev-shell/src/vite-env.d.ts +24 -0
  41. package/dev-shell/tailwind.config.js +98 -0
  42. package/dev-shell/vite.config.ts +174 -0
  43. package/dist/index.d.ts +109 -0
  44. package/dist/index.js +170 -0
  45. package/dist/types.d.ts +585 -0
  46. package/dist/types.js +0 -0
  47. package/dist/vite-plugin.d.ts +25 -0
  48. package/dist/vite-plugin.js +80 -0
  49. package/package.json +89 -3
  50. package/src/config.ts +49 -0
  51. package/src/global-dialog.ts +169 -0
  52. package/src/index.ts +80 -0
  53. package/src/runtime.ts +54 -0
  54. package/src/types.ts +630 -0
  55. package/src/ui/MarkdownEditor.vue +520 -0
  56. package/src/ui/PluginGlobalDialog.vue +401 -0
  57. package/src/ui/Select.d.ts +36 -0
  58. package/src/ui/Select.vue +220 -0
  59. package/src/ui/TerminalInputRail.vue +184 -0
  60. package/src/ui/apply-select-position.ts +65 -0
  61. package/src/ui/markdown-editor-syntax.ts +234 -0
  62. package/src/ui/markdown-editor.d.ts +36 -0
  63. package/src/ui/plugin-global-dialog.d.ts +12 -0
  64. package/src/ui/select-position.ts +79 -0
  65. package/src/ui/terminal-input-rail.d.ts +30 -0
  66. package/src/ui/zoom-compensation.d.ts +9 -0
  67. package/src/ui/zoom-compensation.ts +52 -0
  68. package/src/vite-plugin.ts +124 -0
  69. package/template/README.md +39 -0
  70. package/template/package.json +23 -0
  71. package/template/plugin.json +14 -0
  72. package/template/rust/Cargo.toml +21 -0
  73. package/template/rust/src/lib.rs +39 -0
  74. package/template/src/env.d.ts +24 -0
  75. package/template/src/index.ts +37 -0
  76. package/template/tsconfig.json +17 -0
  77. package/template/vite.config.ts +21 -0
  78. package/tools/componentize/Cargo.lock +270 -0
  79. package/tools/componentize/Cargo.toml +15 -0
  80. package/tools/componentize/src/main.rs +94 -0
package/README.md CHANGED
@@ -1,3 +1,288 @@
1
- # Temporary Holding Version
1
+ # @binblink/wasmnest-plugin-sdk-desktop
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ WasmNest Desktop wasm 应用开发工具包 — 提供应用所需的**类型定义**、**运行时代理**、**Vite 构建插件**与**共享 UI 组件**,应用只需依赖本包即可开发,无需引用宿主源码。
4
+
5
+ > 术语:本仓把「插件」称为 wasm 应用;包名 / CLI 名 / 标识符保留 `plugin` 原词(`plugin.json`、`wasmnest-plugin-api`)。
6
+ >
7
+ > 完整开发指南见仓库文档 [`wasm-app-dev-desktop.md`](../../docs/wasm-app-dev-desktop.md);API 与扩展点参考 [`wasm-app-dev-guide.md`](../../docs/knowledge/wasm-app-dev-guide.md)。
8
+
9
+ [English](README_en.md) | 简体中文
10
+
11
+ ## 安装
12
+
13
+ ```bash
14
+ pnpm add -D @binblink/wasmnest-plugin-sdk-desktop
15
+ ```
16
+
17
+ Peer 依赖(宿主已在运行时提供,插件侧安装用于构建与类型检查):
18
+
19
+ | 依赖 | 版本 |
20
+ |------|------|
21
+ | vite | ^5.0.0 |
22
+ | vue | ^3.4.0 |
23
+
24
+ ## 快速开始(推荐:脚手架)
25
+
26
+ ```bash
27
+ # 创建 wasm 应用工程(id 与 name 为位置参数,非交互;--rust 附带 WASM 后端脚手架)
28
+ wasmnest-plugin-desktop create com.example.my-app "My App" --author "you" --rust
29
+
30
+ cd my-app
31
+ pnpm install
32
+ ppnpm run dev # 浏览器开发环境(Dev Shell:空壳宿主 + HMR)
33
+ ppnpm run build # 构建产物 dist/(vite 前端 + rust-ts 时 cargo wasm32)
34
+ ppnpm run manifest # 按源码自动填充 plugin.json 的 contributes / permissions
35
+ ```
36
+
37
+ 更多命令(直接在应用工程里跑 CLI,非 npm script):
38
+
39
+ ```bash
40
+ wasmnest-plugin-desktop build --resources-dir ../wasmnest-desktop/src-tauri/resources/plugins/desktop
41
+ # 把产物复制到 src-tauri/resources/plugins/desktop/{id}/(内置 wasm 应用随安装包分发的方式)
42
+
43
+ wasmnest-plugin-desktop build --frontend-only / --rust-only # 只构建一半(rust-ts)
44
+ wasmnest-plugin-desktop dev [pluginDir] [--port <port>] [--host] [--open]
45
+ wasmnest-plugin-desktop manifest --check # 只检查不写入(CI)
46
+ wasmnest-plugin-desktop validate [--dir] # 校验 plugin.json(id 格式 / 必填 / pluginType / 权限白名单 / 产物存在性)
47
+ wasmnest-plugin-desktop doctor # 环境自检(Node / Rust / wasm32 target / dev-shell / SDK)
48
+ ```
49
+
50
+ 构建产物复制到宿主 `src-tauri/resources/plugins/desktop/{id}/` 后,在宿主应用管理页启用。
51
+ 用户侧安装走 zip 包(桌面端「插件」页 → 选 zip,落盘 `app_data_dir/plugins/{id}/`)。
52
+
53
+ ## 手动创建插件
54
+
55
+ 一个最小插件只需两个文件:
56
+
57
+ **`plugin.json`** — 插件清单(id / 权限 / 扩展点声明):
58
+
59
+ ```json
60
+ {
61
+ "id": "com.example.my-plugin",
62
+ "name": "My Plugin",
63
+ "version": "0.1.0",
64
+ "platform": "desktop",
65
+ "description": "示例插件",
66
+ "author": "you",
67
+ "main": "index.js",
68
+ "pluginType": "ts-only",
69
+ "permissions": ["storage", "ui:sidebar"],
70
+ "contributes": {
71
+ "commands": [{ "id": "my-plugin.hello", "title": "Hello" }],
72
+ "views": [{ "id": "my-plugin.sidebar", "type": "sidebar", "title": "My Plugin", "component": "MyPanel" }]
73
+ }
74
+ }
75
+ ```
76
+
77
+ 必填字段:`name` / `version` / `platform` / `main` / `pluginType` / `permissions` / `contributes`
78
+ (校验真源 `bin/manifest-validate.js`;宿主反序列化无缺省,缺失即拒装)。
79
+ `pluginType` 取值 `rust` / `rust-ts` / `ts-only`;`rust-ts` 时必须给 `rustLibrary`
80
+ (与 Cargo.toml 包名一致)。
81
+
82
+ > `sandbox` 已从 manifest 退役(审计票 06 裁决 2:前端不做隔离)——Rust 端类型会
83
+ > 直接忽略并丢弃该字段,写进清单无效,请勿再声明。
84
+
85
+ **`src/index.ts`** — 插件入口(必须导出 `activate`):
86
+
87
+ ```ts
88
+ import { defineComponent, h } from 'vue'
89
+ import type { PluginContext } from '@binblink/wasmnest-plugin-sdk-desktop'
90
+
91
+ export async function activate(context: PluginContext): Promise<void> {
92
+ // 注册侧边栏面板(组件内可通过 inject('pluginContext') 再次获取 context)
93
+ context.ui.registerSidebarPanel({
94
+ id: 'my-plugin.sidebar',
95
+ title: 'My Plugin',
96
+ order: 600,
97
+ component: defineComponent({
98
+ render: () => h('div', 'Hello WasmNest!'),
99
+ }),
100
+ })
101
+ }
102
+
103
+ export async function deactivate(): Promise<void> {
104
+ // 清理资源(context 注册的所有 Disposable 宿主会自动回收)
105
+ }
106
+ ```
107
+
108
+ ## PluginContext API
109
+
110
+ `activate(context)` 接收的 `PluginContext` 是插件访问宿主能力的**唯一通道**,各 API 按权限分组:
111
+
112
+ | API | 说明 | 所需权限 |
113
+ |-----|------|----------|
114
+ | `context.commands` | 注册 / 执行命令 | 默认授予 |
115
+ | `context.terminal` | 向会话发送输入、订阅输出 / 输入 | `terminal:input` / `terminal:output` / `terminal:observe` |
116
+ | `context.session` | 会话列表、状态变更订阅 | `session:read` / `session:write` |
117
+ | `context.ui` | 注册侧边栏 / 工具箱 / 状态栏 / 设置分组 / 输入扩展 / 终端工具栏 / 标题栏 / 文件处理器(`registerFileHandler`) | `ui:sidebar` / `ui:toolbox` / `ui:statusbar` / `ui:pageToolbar` / `ui:settings` / `ui:input` / `ui:fileHandler` |
118
+ | `context.events` | 宿主事件订阅与发布(`on` / `emit`) | 订阅默认授予;发布需 `broadcast` |
119
+ | `context.storage` | 键值存储(`get` / `set` / `delete` / `flush`) | `storage`(**桌面端无默认授予,必须显式声明**) |
120
+ | `context.http` | 注册 HTTP 端点(`registerEndpoint`,供 Agent CLI hooks 等调用) | `network:http` |
121
+ | `context.i18n` | 宿主 i18n:注册应用翻译、`t()` 快捷翻译、`getI18n()` 取实例 | 默认授予 |
122
+ | `context._disposables` | 宿主在注销时统一回收的 Disposable 列表(内部使用) | — |
123
+ | `context.id` / `context.extensionPath` | 应用 id / 安装目录路径(只读) | — |
124
+
125
+
126
+ 权限声明示例:`"permissions": ["storage", "ui:sidebar", "terminal:output", "network:http"]`。
127
+
128
+ 所有 `register*` / `on*` 调用返回 `Disposable`;插件注销时宿主自动回收,无需手动 `dispose()`。
129
+
130
+ ## 共享模块(避免重复打包 vue 等)
131
+
132
+ 插件构建时 `vue` / `vue-i18n` / `pinia` / `vue-sonner` 会被外部化,运行时从宿主全局 `window.__WASMNEST_SHARED__` 读取。**请通过 SDK 代理函数访问,不要直接操作全局变量**:
133
+
134
+ > 收录标准:模块内部持有进程级单例状态,自带第二份实例会导致状态错位。`vue-sonner` 是宿主 toast 队列本体——插件 `import { toast } from 'vue-sonner'` 会被改写成读宿主实例,因此 `toast.success(...)` 与宿主提示同队列、同外观(自带第二份则提示不显示)。
135
+
136
+ ```ts
137
+ import { getVue, getI18n, getPinia, getRouter, getPluginContext } from '@binblink/wasmnest-plugin-sdk-desktop'
138
+
139
+ const { ref, computed } = getVue() // 宿主 Vue 实例(组件内直接 import 即可,构建期已外部化)
140
+ const i18n = getI18n() // 宿主 vue-i18n 实例(模块级代码用;组件内用 useI18n())
141
+ const context = getPluginContext() // 组件 setup 内从 inject 获取 PluginContext
142
+ ```
143
+
144
+ ## Vite 构建集成
145
+
146
+ 在插件 `vite.config.ts` 中引入 `wasmnestPlugin()`,负责将共享模块标记为 external 并改写为全局变量读取:
147
+
148
+ ```ts
149
+ import { defineConfig } from 'vite'
150
+ import vue from '@vitejs/plugin-vue'
151
+ import { wasmnestPlugin } from '@binblink/wasmnest-plugin-sdk-desktop/vite'
152
+
153
+ export default defineConfig({
154
+ plugins: [vue(), wasmnestPlugin()],
155
+ build: {
156
+ lib: {
157
+ entry: 'src/index.ts',
158
+ formats: ['es'],
159
+ fileName: () => 'index.js',
160
+ },
161
+ outDir: 'dist',
162
+ },
163
+ })
164
+ ```
165
+
166
+ 产物文件名必须为 `index.js`(与 `plugin.json` 的 `main` 对应)。
167
+
168
+ ## Rust WASM 后端(`--rust` 插件)
169
+
170
+ `--rust` 脚手架附带 Rust 侧 SDK crate **`wasmnest-plugin-api`**(本包 `rust/` 目录,MIT),用于编写编译为 WASM 组件、在宿主 wasmtime 沙箱内运行的后端逻辑。
171
+
172
+ ### 启用
173
+
174
+ ```toml
175
+ [dependencies]
176
+ wasmnest-plugin-api = { path = "<宿主>/packages/plugin-sdk-desktop/rust", features = ["wasm"] }
177
+ ```
178
+
179
+ `wasm` feature 提供:
180
+
181
+ - `WasmPlugin` trait + `wasm_entry!` 宏 — 生成 WIT 契约(`rust/wit/wasmnest.wit`,单一事实来源)定义的全部组件导出
182
+ - `WasmHost` — 宿主 API 绑定(import 后端),经 bindgen 调用宿主能力
183
+ - `#[plugin_api]` 属性宏(由 `rust-macros/` 的 `wasmnest-plugin-api-macros` crate 提供)— 插件互调 IDL:trait 定义 → JSON-RPC 分派 + client 生成 + 防漂移比对
184
+
185
+ ### 最小示例
186
+
187
+ ```rust
188
+ use wasmnest_plugin_api::{CommandArgs, WasmHost, WasmPlugin};
189
+
190
+ struct MyPlugin;
191
+
192
+ impl WasmPlugin for MyPlugin {
193
+ fn activate() -> anyhow::Result<()> {
194
+ // 经 WasmHost 访问宿主能力(事件订阅、存储、HTTP 端点等)
195
+ Ok(())
196
+ }
197
+ }
198
+
199
+ wasmnest_plugin_api::wasm_entry!(MyPlugin);
200
+ ```
201
+
202
+ ### 构建
203
+
204
+ ```bash
205
+ cargo build --target wasm32-unknown-unknown --no-default-features --features wasm --release
206
+ ```
207
+
208
+ 产物为 WASM 组件(Component Model),宿主以 wasmtime 沙箱加载运行;插件崩溃不影响宿主。不带 `wasm` feature 时可作为普通 Rust crate 使用(静态注册 / 库依赖)。
209
+
210
+ ## 配置声明
211
+
212
+ 插件配置在 `plugin.json` 的 `contributes.configuration` 声明,宿主据此渲染配置页;运行时经 `context.storage` 读写(统一键 `PLUGIN_CONFIG_STORAGE_KEY = 'config'`)。SDK 提供声明式助手保持两端一致:
213
+
214
+ ```ts
215
+ import { defineConfiguration, PLUGIN_CONFIG_STORAGE_KEY } from '@binblink/wasmnest-plugin-sdk-desktop'
216
+
217
+ const config = defineConfiguration('My Plugin Settings', {
218
+ apiKey: { type: 'string', title: 'API Key' },
219
+ maxRetries: { type: 'number', title: 'Max Retries', default: 3 },
220
+ debugMode: { type: 'boolean', title: 'Debug Mode', default: false },
221
+ })
222
+
223
+ // 运行时读取用户配置
224
+ const saved = await context.storage.get<typeof config.properties>(PLUGIN_CONFIG_STORAGE_KEY)
225
+ ```
226
+
227
+ ## 事件常量
228
+
229
+ 事件主题遵循 `{domain}:{action}` 命名规范;各领域事件名由对应 wasm 应用工程自持(单一事实来源),
230
+ SDK 不内置具体业务事件名。例如终端会话应用(`wasm-apps/bedcode`)订阅的任务状态事件:
231
+
232
+ ```ts
233
+ // 应用内订阅本领域事件(字符串字面量或抽为本地常量)
234
+ context.events.on('task:status-changed', (payload) => {
235
+ // 任务状态变更(如 Agent CLI idle → in_progress)
236
+ })
237
+ ```
238
+
239
+ ## 共享 UI 组件
240
+
241
+ `./ui` 子路径导出的组件遵循宿主设计 token,插件 UI 与宿主观感一致(**禁止使用原生 `<select>` 等系统控件外观**):
242
+
243
+ ```vue
244
+ <script setup lang="ts">
245
+ import { ref } from 'vue'
246
+ import Select from '@binblink/wasmnest-plugin-sdk-desktop/ui'
247
+
248
+ const value = ref('a')
249
+ const options = [
250
+ { value: 'a', label: '选项 A' },
251
+ { value: 'b', label: '选项 B' },
252
+ ]
253
+ </script>
254
+
255
+ <template>
256
+ <Select v-model="value" :options="options" size="sm" />
257
+ </template>
258
+ ```
259
+
260
+ 当前提供(每个子路径 = 一个独立导出,默认导出组件本身):
261
+
262
+ | 子路径 | 组件 | 用途 |
263
+ |--------|------|------|
264
+ | `./ui` | `Select` | 下拉选择(`update:modelValue` / `open` 事件,`md` / `sm` 尺寸) |
265
+ | `./ui/markdown-editor` | `MarkdownEditor` | Markdown 编辑区(语法工具栏 + 预览切换,`v-model`) |
266
+ | `./ui/terminal-input-rail` | `TerminalInputRail` | 终端输入导航条(终端右侧悬浮,一根横线 = 一次用户输入,位置映射 buffer 相对位置) |
267
+ | `./ui/plugin-global-dialog` | `PluginGlobalDialog` | 宿主全局弹窗(应用根挂载一次;渲染由全局弹窗控制器驱动,插件经 `context.ui.showDialog` 操控,挂载方无 props) |
268
+ | `./ui/zoom-compensation` | (无组件) | fixed 定位覆盖层在根元素 CSS zoom 下的坐标换算(自校准;当前 F=1,作防御性 no-op 保留) |
269
+
270
+ ## 子路径导出总览
271
+
272
+ | 子路径 | 内容 |
273
+ |--------|------|
274
+ | `@binblink/wasmnest-plugin-sdk-desktop` | 主 API:类型 + 运行时代理 + 配置助手 + 事件常量 |
275
+ | `@binblink/wasmnest-plugin-sdk-desktop/vite` | `wasmnestPlugin()` Vite 构建插件 |
276
+ | `@binblink/wasmnest-plugin-sdk-desktop/types` | 纯类型导出(仅类型,无运行时) |
277
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui` | 共享 Vue 组件:`Select` |
278
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/markdown-editor` | `MarkdownEditor` |
279
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/terminal-input-rail` | `TerminalInputRail` |
280
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/plugin-global-dialog` | `PluginGlobalDialog` |
281
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/zoom-compensation` | zoom 坐标换算工具 |
282
+
283
+ ## 本地开发本 SDK
284
+
285
+ ```bash
286
+ pnpm run build # tsup 构建 dist(ESM + d.ts)
287
+ pnpm run test:run # vitest run
288
+ ```
package/README_en.md ADDED
@@ -0,0 +1,284 @@
1
+ # @binblink/wasmnest-plugin-sdk-desktop
2
+
3
+ The WasmNest Desktop WASM app development kit — provides everything an app needs: **type definitions**, **runtime proxies**, a **Vite build plugin**, and **shared UI components**. Apps only need this package; no host source code required.
4
+
5
+ > Terminology: this repository calls "plugins" WASM apps; the package name, CLI name and identifiers keep the original `plugin` words (`plugin.json`, `wasmnest-plugin-api`).
6
+ >
7
+ > Full development guide: [`wasm-app-dev-desktop.md`](../../docs/wasm-app-dev-desktop.md) (Chinese); API & extension-point reference [`wasm-app-dev-guide.md`](../../docs/knowledge/wasm-app-dev-guide.md).
8
+
9
+ English | [简体中文](README.md)
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pnpm add -D @binblink/wasmnest-plugin-sdk-desktop
15
+ ```
16
+
17
+ Peer dependencies (provided by the host at runtime; installed in the plugin for building & type-checking):
18
+
19
+ | Dependency | Version |
20
+ |------------|---------|
21
+ | vite | ^5.0.0 |
22
+ | vue | ^3.4.0 |
23
+
24
+ ## Quick Start (recommended: scaffold)
25
+
26
+ ```bash
27
+ # Create a WASM app project (id and name are positional args, not interactive; --rust adds a WASM backend)
28
+ wasmnest-plugin-desktop create com.example.my-app "My App" --author "you" --rust
29
+
30
+ cd my-app
31
+ pnpm install
32
+ ppnpm run dev # Browser dev environment (Dev Shell: empty host shell + HMR)
33
+ ppnpm run build # Build dist/ (vite frontend + cargo wasm32 for rust-ts)
34
+ ppnpm run manifest # Auto-fill plugin.json contributes / permissions from source
35
+ ```
36
+
37
+ More commands (run the CLI directly inside the app project, not as npm scripts):
38
+
39
+ ```bash
40
+ wasmnest-plugin-desktop build --resources-dir ../wasmnest-desktop/src-tauri/resources/plugins/desktop
41
+ # copies the build output into src-tauri/resources/plugins/desktop/{id}/ (how built-in WASM apps ship)
42
+
43
+ wasmnest-plugin-desktop build --frontend-only / --rust-only # build only half (rust-ts)
44
+ wasmnest-plugin-desktop dev [pluginDir] [--port <port>] [--host] [--open]
45
+ wasmnest-plugin-desktop manifest --check # check only, don't write (CI)
46
+ wasmnest-plugin-desktop validate [--dir] # validate plugin.json (id format / required fields / pluginType / permission allowlist / artifact presence)
47
+ wasmnest-plugin-desktop doctor # environment self-check (Node / Rust / wasm32 target / dev-shell / SDK)
48
+ ```
49
+
50
+ Copy the build output into the host's `src-tauri/resources/plugins/desktop/{id}/` directory, then enable it on the host's app management page.
51
+ User-side install goes through a zip package (desktop "Plugins" page → pick zip, unpacked into `app_data_dir/plugins/{id}/`).
52
+
53
+ ## Creating a Plugin Manually
54
+
55
+ A minimal plugin needs just two files:
56
+
57
+ **`plugin.json`** — plugin manifest (id / permissions / extension point declarations):
58
+
59
+ ```json
60
+ {
61
+ "id": "com.example.my-plugin",
62
+ "name": "My Plugin",
63
+ "version": "0.1.0",
64
+ "platform": "desktop",
65
+ "description": "Example plugin",
66
+ "author": "you",
67
+ "main": "index.js",
68
+ "pluginType": "ts-only",
69
+ "permissions": ["storage", "ui:sidebar"],
70
+ "contributes": {
71
+ "commands": [{ "id": "my-plugin.hello", "title": "Hello" }],
72
+ "views": [{ "id": "my-plugin.sidebar", "type": "sidebar", "title": "My Plugin", "component": "MyPanel" }]
73
+ }
74
+ }
75
+ ```
76
+
77
+ Required fields: `name` / `version` / `platform` / `main` / `pluginType` / `permissions` / `contributes`
78
+ (validation source of truth `bin/manifest-validate.js`; the host deserializes with no defaults, so a missing field rejects the install).
79
+ `pluginType` accepts `rust` / `rust-ts` / `ts-only`; `rust-ts` requires `rustLibrary` (must match the Cargo.toml package name).
80
+
81
+ > `sandbox` has been retired from the manifest (audit ticket 06 ruling 2: the frontend is not sandboxed) — the Rust types ignore and drop the field, so declaring it has no effect. Do not declare it.
82
+
83
+ **`src/index.ts`** — plugin entry (must export `activate`):
84
+
85
+ ```ts
86
+ import { defineComponent, h } from 'vue'
87
+ import type { PluginContext } from '@binblink/wasmnest-plugin-sdk-desktop'
88
+
89
+ export async function activate(context: PluginContext): Promise<void> {
90
+ // Register a sidebar panel (components can re-fetch context via inject('pluginContext'))
91
+ context.ui.registerSidebarPanel({
92
+ id: 'my-plugin.sidebar',
93
+ title: 'My Plugin',
94
+ order: 600,
95
+ component: defineComponent({
96
+ render: () => h('div', 'Hello WasmNest!'),
97
+ }),
98
+ })
99
+ }
100
+
101
+ export async function deactivate(): Promise<void> {
102
+ // Clean up (all Disposables registered via context are collected by the host automatically)
103
+ }
104
+ ```
105
+
106
+ ## PluginContext API
107
+
108
+ The `PluginContext` received by `activate(context)` is the **single channel** through which a plugin accesses host capabilities, grouped by permission:
109
+
110
+ | API | Description | Required permission |
111
+ |-----|-------------|---------------------|
112
+ | `context.commands` | Register / execute commands | granted by default |
113
+ | `context.terminal` | Send input to sessions, subscribe to output | `terminal:input` / `terminal:output` / `terminal:observe` |
114
+ | `context.session` | Session list, status change subscription | `session:read` / `session:write` |
115
+ | `context.ui` | Sidebar / toolbox / statusbar / settings section / input extensions / terminal toolbar / titlebar / file handlers (`registerFileHandler`) | `ui:sidebar` / `ui:toolbox` / `ui:statusbar` / `ui:pageToolbar` / `ui:settings` / `ui:input` / `ui:fileHandler` |
116
+ | `context.events` | Host event subscription & publishing (`on` / `emit`) | subscribe: default; publish: `broadcast` |
117
+ | `context.storage` | Key-value storage (`get` / `set` / `delete` / `flush`) | `storage` (**no default grant on desktop — must be declared explicitly**) |
118
+ | `context.http` | Register HTTP endpoints (`registerEndpoint`, e.g. for Agent CLI hooks) | `network:http` |
119
+ | `context.i18n` | Host i18n: register app translations, `t()` helper, `getI18n()` for the instance | granted by default |
120
+ | `context._disposables` | List of Disposables collected by the host on deactivation (internal) | — |
121
+ | `context.id` / `context.extensionPath` | App id / install directory path (read-only) | — |
122
+
123
+ Permission example: `"permissions": ["storage", "ui:sidebar", "terminal:output", "network:http"]`.
124
+
125
+ All `register*` / `on*` calls return a `Disposable`; the host collects them automatically on plugin deactivation — no manual `dispose()` needed.
126
+
127
+ ## Shared Modules (avoid bundling vue etc.)
128
+
129
+ During plugin builds, `vue` / `vue-i18n` / `pinia` / `vue-sonner` are externalized and read at runtime from the host global `window.__WASMNEST_SHARED__`. **Always access them via the SDK proxy functions — never touch the global directly**:
130
+
131
+ > Inclusion rule: modules holding process-wide singleton state — a second instance desynchronizes state. `vue-sonner` is the host toast queue itself, so a plugin's `import { toast } from 'vue-sonner'` is rewritten to the host instance (identical queue and look; a bundled second copy would render nothing).
132
+
133
+ ```ts
134
+ import { getVue, getI18n, getPinia, getRouter, getPluginContext } from '@binblink/wasmnest-plugin-sdk-desktop'
135
+
136
+ const { ref, computed } = getVue() // Host Vue instance (components can import vue directly — externalized at build time)
137
+ const i18n = getI18n() // Host vue-i18n instance (module-level code; components use useI18n())
138
+ const context = getPluginContext() // PluginContext via inject inside component setup
139
+ ```
140
+
141
+ ## Vite Build Integration
142
+
143
+ Add `wasmnestPlugin()` to the plugin's `vite.config.ts`; it marks shared modules as external and rewrites them to read from the host global:
144
+
145
+ ```ts
146
+ import { defineConfig } from 'vite'
147
+ import vue from '@vitejs/plugin-vue'
148
+ import { wasmnestPlugin } from '@binblink/wasmnest-plugin-sdk-desktop/vite'
149
+
150
+ export default defineConfig({
151
+ plugins: [vue(), wasmnestPlugin()],
152
+ build: {
153
+ lib: {
154
+ entry: 'src/index.ts',
155
+ formats: ['es'],
156
+ fileName: () => 'index.js',
157
+ },
158
+ outDir: 'dist',
159
+ },
160
+ })
161
+ ```
162
+
163
+ The output filename must be `index.js` (matching `main` in `plugin.json`).
164
+
165
+ ## Rust WASM Backend (`--rust` plugins)
166
+
167
+ The `--rust` scaffold includes the Rust-side SDK crate **`wasmnest-plugin-api`** (in this package's `rust/` directory, MIT) for backend logic compiled into a WASM component that runs inside the host's wasmtime sandbox.
168
+
169
+ ### Enable
170
+
171
+ ```toml
172
+ [dependencies]
173
+ wasmnest-plugin-api = { path = "<host>/packages/plugin-sdk-desktop/rust", features = ["wasm"] }
174
+ ```
175
+
176
+ The `wasm` feature provides:
177
+
178
+ - `WasmPlugin` trait + `wasm_entry!` macro — generates all component exports defined by the WIT contract (`rust/wit/wasmnest.wit`, single source of truth)
179
+ - `WasmHost` — host API bindings (import backend), calling host capabilities via bindgen
180
+ - `#[plugin_api]` attribute macro (from `wasmnest-plugin-api-macros`, the `rust-macros/` crate) — inter-plugin call IDL: trait definition → JSON-RPC dispatch + client generation + drift detection
181
+
182
+ ### Minimal Example
183
+
184
+ ```rust
185
+ use wasmnest_plugin_api::{CommandArgs, WasmHost, WasmPlugin};
186
+
187
+ struct MyPlugin;
188
+
189
+ impl WasmPlugin for MyPlugin {
190
+ fn activate() -> anyhow::Result<()> {
191
+ // Access host capabilities via WasmHost (events, storage, HTTP endpoints, ...)
192
+ Ok(())
193
+ }
194
+ }
195
+
196
+ wasmnest_plugin_api::wasm_entry!(MyPlugin);
197
+ ```
198
+
199
+ ### Build
200
+
201
+ ```bash
202
+ cargo build --target wasm32-unknown-unknown --no-default-features --features wasm --release
203
+ ```
204
+
205
+ The output is a WASM component (Component Model) loaded by the host inside the wasmtime sandbox — a crashing plugin never affects the host. Without the `wasm` feature it works as a regular Rust crate (static registration / library dependency).
206
+
207
+ ## Configuration Declaration
208
+
209
+ Declare plugin config in `plugin.json` under `contributes.configuration`; the host renders a config page from it. At runtime, read/write via `context.storage` (unified key `PLUGIN_CONFIG_STORAGE_KEY = 'config'`). The SDK provides a declarative helper to keep both ends consistent:
210
+
211
+ ```ts
212
+ import { defineConfiguration, PLUGIN_CONFIG_STORAGE_KEY } from '@binblink/wasmnest-plugin-sdk-desktop'
213
+
214
+ const config = defineConfiguration('My Plugin Settings', {
215
+ apiKey: { type: 'string', title: 'API Key' },
216
+ maxRetries: { type: 'number', title: 'Max Retries', default: 3 },
217
+ debugMode: { type: 'boolean', title: 'Debug Mode', default: false },
218
+ })
219
+
220
+ // Read user config at runtime
221
+ const saved = await context.storage.get<typeof config.properties>(PLUGIN_CONFIG_STORAGE_KEY)
222
+ ```
223
+
224
+ ## Event Constants
225
+
226
+ Event topics follow the `{domain}:{action}` convention; each domain owns its event names in its own WASM app package (single source of truth). The SDK ships no business-specific event names. For example, the bedcode app (`wasm-apps/bedcode`) subscribes to its task status event:
227
+
228
+ ```ts
229
+ // Inside an app, subscribe to its domain event (string literal or a local constant)
230
+ context.events.on('task:status-changed', (payload) => {
231
+ // Task status change (e.g. Agent CLI idle → in_progress)
232
+ })
233
+ ```
234
+
235
+ ## Shared UI Components
236
+
237
+ Components exported via the `./ui` subpath follow the host design tokens so plugin UI matches the host look & feel (**native `<select>` etc. system controls are banned**):
238
+
239
+ ```vue
240
+ <script setup lang="ts">
241
+ import { ref } from 'vue'
242
+ import Select from '@binblink/wasmnest-plugin-sdk-desktop/ui'
243
+
244
+ const value = ref('a')
245
+ const options = [
246
+ { value: 'a', label: 'Option A' },
247
+ { value: 'b', label: 'Option B' },
248
+ ]
249
+ </script>
250
+
251
+ <template>
252
+ <Select v-model="value" :options="options" size="sm" />
253
+ </template>
254
+ ```
255
+
256
+ Currently provided (each subpath is an independent export that default-exports the component):
257
+
258
+ | Subpath | Component | Purpose |
259
+ |---------|-----------|---------|
260
+ | `./ui` | `Select` | Dropdown (`update:modelValue` / `open` events, `md` / `sm` sizes) |
261
+ | `./ui/markdown-editor` | `MarkdownEditor` | Markdown editing area (syntax toolbar + preview toggle, `v-model`) |
262
+ | `./ui/terminal-input-rail` | `TerminalInputRail` | Terminal input navigation rail (floating on the right of the terminal; one line = one user input, position mapped to the buffer) |
263
+ | `./ui/plugin-global-dialog` | `PluginGlobalDialog` | Host global dialog (mounted once at the app root; rendering driven by the global dialog controller, apps drive it via `context.ui.showDialog`, no props on mount) |
264
+ | `./ui/zoom-compensation` | (no component) | Coordinate conversion for fixed-position overlays under root CSS zoom (self-calibrating; currently F=1, kept as a defensive no-op) |
265
+
266
+ ## Subpath Exports
267
+
268
+ | Subpath | Contents |
269
+ |---------|----------|
270
+ | `@binblink/wasmnest-plugin-sdk-desktop` | Main API: types + runtime proxies + config helper + event constants |
271
+ | `@binblink/wasmnest-plugin-sdk-desktop/vite` | `wasmnestPlugin()` Vite build plugin |
272
+ | `@binblink/wasmnest-plugin-sdk-desktop/types` | Pure types (types only, no runtime) |
273
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui` | Shared Vue component: `Select` |
274
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/markdown-editor` | `MarkdownEditor` |
275
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/terminal-input-rail` | `TerminalInputRail` |
276
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/plugin-global-dialog` | `PluginGlobalDialog` |
277
+ | `@binblink/wasmnest-plugin-sdk-desktop/ui/zoom-compensation` | zoom coordinate conversion helper |
278
+
279
+ ## Developing this SDK
280
+
281
+ ```bash
282
+ pnpm run build # tsup build → dist (ESM + d.ts)
283
+ pnpm run test:run # vitest run
284
+ ```