@binblink/wasmnest-plugin-sdk-mobile 0.0.0-stage → 0.0.2

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 (122) hide show
  1. package/README.md +439 -2
  2. package/README_en.md +415 -0
  3. package/bin/build.js +271 -0
  4. package/bin/cli.js +96 -0
  5. package/bin/lib.js +349 -0
  6. package/bin/manifest-gen.js +327 -0
  7. package/bin/package.js +151 -0
  8. package/bin/scaffold.js +299 -0
  9. package/dev-shell/README.md +151 -0
  10. package/dev-shell/index.html +27 -0
  11. package/dev-shell/package.json +27 -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/apps/mock-terminal/MockTerminalSlotCard.vue +43 -0
  16. package/dev-shell/src/apps/mock-terminal/MockTerminalView.vue +168 -0
  17. package/dev-shell/src/apps/mock-terminal/index.ts +50 -0
  18. package/dev-shell/src/components/DevToolbar.vue +100 -0
  19. package/dev-shell/src/components/DialogHost.vue +119 -0
  20. package/dev-shell/src/components/LogPanel.vue +80 -0
  21. package/dev-shell/src/i18n.ts +22 -0
  22. package/dev-shell/src/loader.ts +239 -0
  23. package/dev-shell/src/locale.ts +29 -0
  24. package/dev-shell/src/locales/en-shell.ts +332 -0
  25. package/dev-shell/src/locales/index.ts +70 -0
  26. package/dev-shell/src/locales/shell.ts +331 -0
  27. package/dev-shell/src/main.ts +58 -0
  28. package/dev-shell/src/mock/dialog-service.ts +58 -0
  29. package/dev-shell/src/mock/file-transfer.ts +390 -0
  30. package/dev-shell/src/mock/mobile-api.ts +369 -0
  31. package/dev-shell/src/mock/preset-tasks.ts +186 -0
  32. package/dev-shell/src/mock/session.ts +121 -0
  33. package/dev-shell/src/mock-context.ts +374 -0
  34. package/dev-shell/src/registry.ts +151 -0
  35. package/dev-shell/src/shared-runtime.ts +44 -0
  36. package/dev-shell/src/shell/ShellView.vue +52 -0
  37. package/dev-shell/src/shell/adapters/devAppSource.ts +144 -0
  38. package/dev-shell/src/shell/components/PluginContextHost.vue +40 -0
  39. package/dev-shell/src/shell/components/ShellAppCell.vue +75 -0
  40. package/dev-shell/src/shell/components/ShellAppIcon.vue +111 -0
  41. package/dev-shell/src/shell/components/ShellAppSurface.vue +46 -0
  42. package/dev-shell/src/shell/components/ShellBrandTile.vue +27 -0
  43. package/dev-shell/src/shell/components/ShellCapsuleMenu.vue +123 -0
  44. package/dev-shell/src/shell/components/ShellChip.vue +49 -0
  45. package/dev-shell/src/shell/components/ShellGroupCard.vue +17 -0
  46. package/dev-shell/src/shell/components/ShellHost.vue +75 -0
  47. package/dev-shell/src/shell/components/ShellNotificationShade.vue +501 -0
  48. package/dev-shell/src/shell/components/ShellPermissionPrompt.vue +127 -0
  49. package/dev-shell/src/shell/components/ShellPlaceholderSurface.vue +33 -0
  50. package/dev-shell/src/shell/components/ShellSection.vue +27 -0
  51. package/dev-shell/src/shell/components/ShellSheet.vue +74 -0
  52. package/dev-shell/src/shell/components/ShellStatusbar.vue +84 -0
  53. package/dev-shell/src/shell/components/screens/PluginRoutePage.vue +98 -0
  54. package/dev-shell/src/shell/components/screens/ShellAppDetailScreen.vue +359 -0
  55. package/dev-shell/src/shell/components/screens/ShellAppRunScreen.vue +90 -0
  56. package/dev-shell/src/shell/components/screens/ShellAppsScreen.vue +195 -0
  57. package/dev-shell/src/shell/components/screens/ShellHomeScreen.vue +357 -0
  58. package/dev-shell/src/shell/components/screens/ShellPermissionsScreen.vue +376 -0
  59. package/dev-shell/src/shell/components/screens/ShellSettingsScreen.vue +240 -0
  60. package/dev-shell/src/shell/components/screens/ShellSwitcherScreen.vue +559 -0
  61. package/dev-shell/src/shell/components/ui/ConfirmDialog.vue +137 -0
  62. package/dev-shell/src/shell/components/ui/Toggle.vue +53 -0
  63. package/dev-shell/src/shell/composables/useShellApps.ts +417 -0
  64. package/dev-shell/src/shell/composables/useShellNavigation.ts +197 -0
  65. package/dev-shell/src/shell/composables/useShellNotifications.ts +115 -0
  66. package/dev-shell/src/shell/composables/useShellOpen.ts +44 -0
  67. package/dev-shell/src/shell/composables/useShellOverlays.ts +101 -0
  68. package/dev-shell/src/shell/composables/useShellPreferences.ts +143 -0
  69. package/dev-shell/src/shell/composables/useShellRecent.ts +84 -0
  70. package/dev-shell/src/shell/composables/useSlotCarousel.ts +238 -0
  71. package/dev-shell/src/shell/composables/useToast.ts +33 -0
  72. package/dev-shell/src/shell/index.ts +88 -0
  73. package/dev-shell/src/shell/logger.ts +45 -0
  74. package/dev-shell/src/shell/permissions.ts +145 -0
  75. package/dev-shell/src/shell/registry.ts +220 -0
  76. package/dev-shell/src/shell/slotCards.ts +47 -0
  77. package/dev-shell/src/shell/styles/shell.css +1155 -0
  78. package/dev-shell/src/shell/surfaceIntent.ts +107 -0
  79. package/dev-shell/src/shell/types.ts +152 -0
  80. package/dev-shell/src/shell/utils.ts +54 -0
  81. package/dev-shell/src/styles/main.css +153 -0
  82. package/dev-shell/src/styles/mobile.css +981 -0
  83. package/dev-shell/src/styles/wallpaper.css +130 -0
  84. package/dev-shell/src/theme.ts +71 -0
  85. package/dev-shell/src/vite-env.d.ts +20 -0
  86. package/dev-shell/tailwind.config.js +101 -0
  87. package/dev-shell/tsconfig.json +16 -0
  88. package/dev-shell/vite.config.ts +130 -0
  89. package/dist/index.d.ts +124 -0
  90. package/dist/index.js +229 -0
  91. package/dist/types.d.ts +738 -0
  92. package/dist/types.js +0 -0
  93. package/dist/vite-plugin.d.ts +16 -0
  94. package/dist/vite-plugin.js +95 -0
  95. package/package.json +88 -3
  96. package/src/constants.ts +6 -0
  97. package/src/global-dialog.ts +168 -0
  98. package/src/index.ts +96 -0
  99. package/src/runtime.ts +44 -0
  100. package/src/types.ts +822 -0
  101. package/src/ui/AppUpdateSection.d.ts +44 -0
  102. package/src/ui/AppUpdateSection.vue +253 -0
  103. package/src/ui/PluginGlobalDialog.vue +388 -0
  104. package/src/ui/QuickCard.d.ts +33 -0
  105. package/src/ui/QuickCard.vue +167 -0
  106. package/src/ui/Select.d.ts +37 -0
  107. package/src/ui/Select.vue +307 -0
  108. package/src/ui/plugin-global-dialog.d.ts +11 -0
  109. package/src/ui/useSwipeTabs.d.ts +20 -0
  110. package/src/ui/useSwipeTabs.ts +53 -0
  111. package/src/update.ts +123 -0
  112. package/src/vite-plugin.ts +132 -0
  113. package/template/.gitignore +4 -0
  114. package/template/README.md +46 -0
  115. package/template/package.json +23 -0
  116. package/template/plugin.json +13 -0
  117. package/template/rust/Cargo.toml +19 -0
  118. package/template/rust/src/lib.rs +33 -0
  119. package/template/src/env.d.ts +24 -0
  120. package/template/src/index.ts +37 -0
  121. package/template/tsconfig.json +17 -0
  122. package/template/vite.config.ts +21 -0
package/README_en.md ADDED
@@ -0,0 +1,415 @@
1
+ # @binblink/wasmnest-plugin-sdk-mobile
2
+
3
+ The WasmNest Mobile WASM app development kit — provides **type definitions**, **runtime proxies**, a **Vite build plugin**, and **shared UI components**. Compared to the desktop SDK, it additionally wraps mobile-only capabilities: SAF storage access, dialogs / system notifications, dynamic routing, lifecycle hooks, and the dev-shell mock data protocol.
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-mobile`).
6
+ >
7
+ > Full development guide: [`wasm-app-dev-mobile.md`](../../docs/wasm-app-dev-mobile.md) (Chinese); development red-line checklist [`wasm-app-development-checklist.md`](../../../docs/knowledge/wasm-app-development-checklist.md).
8
+
9
+ English | [简体中文](README.md)
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pnpm add -D @binblink/wasmnest-plugin-sdk-mobile
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; a WASM backend is included by default, --ts-only for frontend-only)
28
+ wasmnest-plugin create com.example.my-app "My App" --author "you"
29
+
30
+ cd my-app
31
+ pnpm install
32
+ ppnpm run dev # Browser dev environment (Dev Shell: empty host shell + mobile skeleton, HMR)
33
+ ppnpm run build # Build output dist/
34
+ ppnpm run package # Pack the dist/{id}.zip app bundle
35
+ ```
36
+
37
+ More commands (run the CLI directly inside the app project, not as npm scripts):
38
+
39
+ ```bash
40
+ wasmnest-plugin manifest [--check] # auto-fill plugin.json contributes / permissions from source
41
+ wasmnest-plugin validate [--dir] # validate plugin.json
42
+ wasmnest-plugin doctor # environment self-check
43
+ wasmnest-plugin build --watch # rebuild on change
44
+ wasmnest-plugin dev --host # bind the LAN so a phone browser can open http://<pc-ip>:5173
45
+ ```
46
+
47
+ > [!NOTE]
48
+ > `ppnpm run dev` auto-installs dev-shell dependencies on first run and opens http://localhost:5173 in the browser; WASM backends and mobile-only capabilities (SAF, system back key, ...) still need verification on a real device.
49
+
50
+ **Installing on a phone**: transfer `dist/{id}.zip` to the phone → WasmNest Mobile → Plugin Management → Install from file (remote download with SHA256 verification is also supported).
51
+
52
+ ## Creating a Plugin Manually
53
+
54
+ A minimal plugin needs just two files:
55
+
56
+ **`plugin.json`** — plugin manifest (id / permissions / extension point declarations):
57
+
58
+ ```json
59
+ {
60
+ "id": "com.example.my-plugin",
61
+ "name": "My Plugin",
62
+ "version": "0.1.0",
63
+ "platform": "mobile",
64
+ "description": "Example plugin",
65
+ "author": "you",
66
+ "icon": "🧩",
67
+ "main": "index.js",
68
+ "pluginType": "frontend",
69
+ "permissions": ["storage", "ui:input"],
70
+ "contributes": {
71
+ "commands": [{ "id": "my-plugin.hello", "title": "Hello" }],
72
+ "terminal": {
73
+ "toolbarItems": [{ "id": "my-plugin.toolbar", "title": "My Plugin", "icon": "🧩" }]
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ **`src/index.ts`** — plugin entry (must export `activate`):
80
+
81
+ ```ts
82
+ import type { PluginContext } from '@binblink/wasmnest-plugin-sdk-mobile'
83
+
84
+ export async function activate(context: PluginContext): Promise<void> {
85
+ // Register a terminal toolbar button
86
+ context.ui.registerTerminalToolbarItem({
87
+ id: 'my-plugin.toolbar',
88
+ label: 'My Plugin',
89
+ icon: '🧩',
90
+ onClick: () => {
91
+ context.dialogs.showToast('Hello WasmNest!', 'success')
92
+ },
93
+ })
94
+ }
95
+
96
+ export async function deactivate(): Promise<void> {
97
+ // Clean up (all Disposables registered via context are collected by the host automatically)
98
+ }
99
+ ```
100
+
101
+ ## PluginContext API
102
+
103
+ The `PluginContext` received by `activate(context)` is the **single channel** through which a plugin accesses host capabilities, grouped by permission:
104
+
105
+ | API | Description | Required permission |
106
+ |-----|-------------|---------------------|
107
+ | `context.commands` | Register / execute commands (`register` / `execute`) — including the app's own business commands (e.g. `file-transfer.list-remote`) | granted by default |
108
+ | `context.session` | Session list, single-session lookup, status change subscription | `session:read` / `session:write` |
109
+ | `context.ui` | Host-shell surface / home quick cards / capsule menu / platform settings entries / dynamic routes (`registerSurface` / `registerSlot` / `registerCapsuleItem` / `registerSettingsEntry` / `registerRoute`), navigation (`openPage` / `goBack`), system back-key interception (`onBackPressed`), surface entry intents (`onSurfaceIntent`), global dialogs (`showDialog`) | `ui:route` / `ui:back` / `ui:dialog` / `ui:settings` |
110
+ | `context.events` | Host event subscription & publishing (`on` / `emit`) | granted by default |
111
+ | `context.storage` | Key-value storage (`get` / `set` / `delete`) | `storage` (**always granted on mobile** — see note below) |
112
+ | `context.lifecycle` | App lifecycle hooks (`onAppStartup` / `onAppShutdown` / `onAuthSuccess` / `onDisconnect` / `onSessionCreated` / `onSessionStopped`) | granted by default |
113
+ | `context.dialogs` | Dialogs (`showDialog` / `showConfirm` / `showPrompt` / `showToast`) | granted by default |
114
+ | `context.notifications` | System notifications (`notify(title, body?)`) | granted by default |
115
+ | `context.status` | Lifecycle status reporting (`reportReady` / `reportError`) | granted by default |
116
+ | `context.logger` | Leveled logging (`info` / `debug` / `warn` / `error`) | granted by default |
117
+ | `context.i18n` | Register app translations, `t()` helper | granted by default |
118
+ | `context.system` | System-level operations (`openFile` / `revealInDir` / `revealReceivedFileLocation` / `requestAllFilesAccess` / `openDownloadDir`) | `system:open` |
119
+ | `context._disposables` | List of Disposables collected by the host on deactivation (internal) | — |
120
+
121
+ > Note: mobile has **no** `context.terminal` / `context.fileService` / `context.http` (those three are desktop-only).
122
+ > On mobile, terminal output is subscribed through the host-shell run surface (the app owns the protocol), file access goes through the `system` domain APIs (gated by `system:open` and SAF authorization), and cross-device transfer goes through app-owned `context.commands` (the underlying peer-network primitives live in the business core crate).
123
+
124
+ > Permissions are declared **per risk domain** — no default grants except `storage`: the host grants the effective set from the manifest `permissions`, and anything undeclared is denied.
125
+ > The exception is `storage` — mobile treats it as **always granted** (reading/writing the app's own configuration space; turning it off would make the app unusable), so there is no toggle: the host's `src-tauri/src/plugin/approval.rs::effective_permissions` unconditionally `insert("storage")`, and the shell marks it as a locked entry in `src/shell/permissions.ts::SHELL_LOCKED_PERMISSIONS`.
126
+
127
+ All `register*` / `on*` calls return a `Disposable`; the host collects them automatically on plugin deactivation — no manual `dispose()` needed.
128
+
129
+ ## Mobile-Only Capabilities
130
+
131
+ ### Dynamic Routing
132
+
133
+ Plugins can register routes at any depth; the host mounts them under `/mobile/plugins/{pluginId}/{id}`:
134
+
135
+ ```ts
136
+ context.ui.registerRoute({
137
+ id: 'settings', // may contain '/' for deep paths
138
+ title: 'Plugin Settings', // host header title (omitted when header: false)
139
+ component: SettingsPage, // any Vue component
140
+ })
141
+
142
+ context.ui.openPage('settings') // full navigation
143
+ context.ui.goBack() // go back
144
+ ```
145
+
146
+ > [!NOTE]
147
+ > `context.ui.onBackPressed()` can intercept the Android system back key (Android devices only; it fires only while this app's surface is in the foreground — a backgrounded app never consumes the back press); on iOS / dev-shell it silently downgrades to never firing.
148
+
149
+ ### Dialogs & Notifications
150
+
151
+ ```ts
152
+ const ok = await context.dialogs.showConfirm({ title: 'Confirm', message: 'Delete?', variant: 'danger' })
153
+ const name = await context.dialogs.showPrompt({ title: 'Name', inputPlaceholder: 'Enter name' })
154
+ context.dialogs.showToast('Saved', 'success')
155
+
156
+ await context.notifications.notify('Task done', 'Session #3 finished')
157
+ ```
158
+
159
+ ### Lifecycle Hooks
160
+
161
+ ```ts
162
+ context.lifecycle.onAppStartup(() => { /* app start (foreground launches only) */ })
163
+ context.lifecycle.onAuthSuccess(() => { /* refresh peer data after pairing */ })
164
+ context.lifecycle.onDisconnect((reason) => { /* disconnected from desktop */ })
165
+ context.lifecycle.onSessionCreated((sessionId) => { /* new session established */ })
166
+ context.lifecycle.onSessionStopped((sessionId) => { /* session ended */ })
167
+ context.lifecycle.onAppShutdown(() => { /* clean up before shutdown */ })
168
+ ```
169
+
170
+ > `onTerminalInput` / `onTerminalOutput` were retired in ticket 15 phase B — terminal I/O no longer flows through lifecycle hooks; the app owns its subscription channel (host-shell run surface).
171
+
172
+ ### Peer Desktop HTTP Capabilities (MobileHostApi)
173
+
174
+ `getMobileApi()` provides reactive connection state plus a peer REST client (task queue, session auto mode, task history, scheduled jobs — the HTTP paths are owned by each business app):
175
+
176
+ ```ts
177
+ import { getMobileApi } from '@binblink/wasmnest-plugin-sdk-mobile'
178
+
179
+ const api = getMobileApi()
180
+ console.log(api.isConnected.value, api.activeSessionId.value, api.isPaired.value)
181
+
182
+ // Generic REST client (path and payload shapes are app-owned)
183
+ const res = await api.httpRequest<{ tasks: unknown[]; queue_count: number }>(
184
+ `/task-queue/${api.activeSessionId}`, { method: 'GET' },
185
+ )
186
+
187
+ await api.loadActiveSessions() // refresh active sessions
188
+ api.onSessionEvent((evt) => { /* session event push */ })
189
+ const settings = await api.readAllSettings() // read all settings (flat key/value table)
190
+ await api.writeSetting('my-key', 'my-value') // write a single setting key
191
+ ```
192
+
193
+ ### File & System Access
194
+
195
+ Mobile has **no** `context.fileService`. File-related capabilities split into two paths:
196
+
197
+ - **`context.system`** (`system:open` permission): `openFile(path, displayName?)` opens with the system viewer, `revealInDir(path)` / `revealReceivedFileLocation(fileName)` locate a file in the file manager, `openDownloadDir()` opens the shared downloads directory, `requestAllFilesAccess()` guides the user to grant MANAGE_EXTERNAL_STORAGE (unauthorized access to the shared downloads directory rejects with a message starting with `needs_all_files_access` — catch it and show the guidance dialog instead of failing silently).
198
+ - **Cross-device file transfer**: goes through app-owned `context.commands` (e.g. `file-transfer.list-remote`); the underlying peer-network / resumable transfer lives in the business core crate (`应用仓 apps/file-transfer/rust/core`) and is not exposed as a shared SDK API.
199
+
200
+ ### dev-shell Mock Data (devMock)
201
+
202
+ Apps can export a `devMock` field with business demo data for the browser dev environment (queue seeds, SAF tree, ...); the real host ignores it — no conditional compilation needed:
203
+
204
+ ```ts
205
+ export const devMock: PluginDevMock = {
206
+ queueSeed: [{ id: '1', prompt: 'Example task', position: 0, status: 'pending', created_at: '' }],
207
+ }
208
+ ```
209
+
210
+ > `PluginDevMock` is typed as `Record<string, unknown>` — key names are a convention between the app and the dev-shell, with no compile-time validation.
211
+
212
+ ## Shared Modules (avoid bundling vue etc.)
213
+
214
+ During plugin builds, `vue` / `vue-i18n` / `pinia` 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**:
215
+
216
+ ```ts
217
+ import { getVue, getPinia, getRouter, getPresetTasks, getMobileApi, getPluginContext } from '@binblink/wasmnest-plugin-sdk-mobile'
218
+
219
+ const { ref, computed } = getVue() // Host Vue instance (components can import vue directly — externalized at build time)
220
+ const presetTasks = getPresetTasks() // Host preset-tasks composable
221
+ const context = getPluginContext() // PluginContext via inject inside component setup
222
+ ```
223
+
224
+ ### App run and stores (Pinia)
225
+
226
+ The host scopes plugin stores to a single **app run**: everything between `activate` and `deactivate`
227
+ (including swipe-away / × / "disable" in the app detail / uninstall) belongs to that run. **Stopping
228
+ the app disposes every store created in it** — the next launch starts from the setup initial state and
229
+ never sees leftovers from the previous run.
230
+
231
+ Two contracts follow:
232
+
233
+ 1. **Define stores at the top level of your plugin module** (`const useX = defineStore(...)`). The host
234
+ records ownership while the module is loaded; because the module is cached and evaluated only once,
235
+ that is still enough for the next run to get a fresh scope. Stores defined in async chunks fall back
236
+ to the host Pinia with a warning (not guaranteed to be disposed on app stop).
237
+ 2. **Module-level mutable singletons must be cleared in `deactivate`** (or tied to a `context`
238
+ disposable). The host does not re-evaluate your module; state that survives across activations is a
239
+ plugin defect. Data that must outlive a run belongs in storage / plugin-database.
240
+
241
+ ## Vite Build Integration
242
+
243
+ Add `wasmnestPlugin()` to the plugin's `vite.config.ts`; it marks shared modules as external and rewrites them to read from the host global:
244
+
245
+ ```ts
246
+ import { defineConfig } from 'vite'
247
+ import vue from '@vitejs/plugin-vue'
248
+ import { wasmnestPlugin } from '@binblink/wasmnest-plugin-sdk-mobile/vite'
249
+
250
+ export default defineConfig({
251
+ plugins: [vue(), wasmnestPlugin()],
252
+ build: {
253
+ lib: {
254
+ entry: 'src/index.ts',
255
+ formats: ['es'],
256
+ fileName: () => 'index.js',
257
+ },
258
+ outDir: 'dist',
259
+ },
260
+ })
261
+ ```
262
+
263
+ The output filename must be `index.js` (matching `main` in `plugin.json`).
264
+
265
+ ## Rust WASM Backend (`--rust` plugins)
266
+
267
+ The `--rust` scaffold includes the Rust-side SDK crate **`wasmnest-plugin-api-mobile`** (in this package's `rust/` directory, MIT) for backend logic compiled into a WASM component that runs inside the host's wasmtime sandbox.
268
+
269
+ ### Enable
270
+
271
+ ```toml
272
+ [dependencies]
273
+ wasmnest-plugin-api-mobile = { path = "<host>/packages/plugin-sdk-mobile/rust", features = ["wasm"] }
274
+ ```
275
+
276
+ The `wasm` feature provides:
277
+
278
+ - `WasmPlugin` trait + `wasm_entry!` macro — generates all component exports defined by the WIT contract (`rust/wit/wasmnest.wit`, single source of truth)
279
+ - `WasmHost` — host API bindings (import backend), calling host capabilities via bindgen
280
+
281
+ ### Minimal Example
282
+
283
+ ```rust
284
+ use wasmnest_plugin_api_mobile::{CommandArgs, WasmHost, WasmPlugin};
285
+
286
+ struct MyPlugin;
287
+
288
+ impl WasmPlugin for MyPlugin {
289
+ fn activate() -> anyhow::Result<()> {
290
+ // Access host capabilities via WasmHost (events, storage, file service, ...)
291
+ Ok(())
292
+ }
293
+ }
294
+
295
+ wasmnest_plugin_api_mobile::wasm_entry!(MyPlugin);
296
+ ```
297
+
298
+ ### Build
299
+
300
+ ```bash
301
+ cargo build --target wasm32-unknown-unknown --no-default-features --features wasm --release
302
+ ```
303
+
304
+ The output is a WASM component (Component Model) loaded by the host inside the wasmtime sandbox — a crashing plugin never affects the host. Mobile-only capabilities (SAF, system back key, ...) need verification on a real Android device.
305
+
306
+ ## Shared UI Components
307
+
308
+ 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**):
309
+
310
+ ```vue
311
+ <script setup lang="ts">
312
+ import { ref } from 'vue'
313
+ import Select from '@binblink/wasmnest-plugin-sdk-mobile/ui'
314
+
315
+ const value = ref('a')
316
+ const options = [
317
+ { value: 'a', label: 'Option A' },
318
+ { value: 'b', label: 'Option B' },
319
+ ]
320
+ </script>
321
+
322
+ <template>
323
+ <Select v-model="value" :options="options" size="sm" />
324
+ </template>
325
+ ```
326
+
327
+ ### Home quick cards (QuickCard)
328
+
329
+ A host-shell quick card = **shared SDK chrome + app-owned content + host navigation**.
330
+ The app only implements the content and registers it with `context.ui.registerSlot` during
331
+ `activate`; the host shell renders it, auto-rotates the rail (up to 5 cards) and opens the
332
+ owning app on tap. The app must not handle navigation inside the card.
333
+
334
+ A card can **deep-link into a position inside the app** (e.g. an "active sessions" card that
335
+ jumps into the most recent session): the optional `onPress()` on `registerSlot` computes an
336
+ entry intent (`{ key, payload }`, entirely app-owned) at tap time. The host launches and
337
+ opens the app, then delivers that intent verbatim to the surface — subscribe with
338
+ `context.ui.onSurfaceIntent(handler)` in the surface's `onMounted`. Intents that arrive
339
+ before subscription are queued and flushed on subscribe, so a surface created after the tap
340
+ does not lose them; the queue is cleared when the app is stopped / uninstalled.
341
+
342
+ ```vue
343
+ <script setup lang="ts">
344
+ import QuickCard from '@binblink/wasmnest-plugin-sdk-mobile/ui/quick-card'
345
+
346
+ defineProps<{ activeCount: number }>()
347
+ </script>
348
+
349
+ <template>
350
+ <QuickCard
351
+ label="Active sessions"
352
+ :value="activeCount"
353
+ hint="Running"
354
+ tone="success"
355
+ :icon-path="['M4 5h16v14H4z', 'M8 10l3 2.5-3 2.5']"
356
+ />
357
+ </template>
358
+ ```
359
+
360
+ ```ts
361
+ context.ui.registerSlot({
362
+ id: 'sessions',
363
+ component: SessionCard,
364
+ order: 10,
365
+ // Deep link target; omit to only open the app (previous behavior)
366
+ onPress: () => ({ key: 'open-session', payload: { sessionId: latestLiveSessionId() } }),
367
+ })
368
+ ```
369
+
370
+ ```ts
371
+ // App surface root: consume the host-delivered entry intent
372
+ const sub = context.ui.onSurfaceIntent((intent) => {
373
+ if (intent.key !== 'open-session') return
374
+ openSession((intent.payload as { sessionId: string }).sessionId)
375
+ })
376
+ // sub.dispose() on unmount
377
+ ```
378
+
379
+ - The host wraps the whole card in a button (tap = launch and open the contributing app,
380
+ then deliver the value returned by `onPress()`); do not put buttons or links inside the card;
381
+ - The host truncates by registration order (currently 5 cards) and auto-rotates when there
382
+ are several — paused on touch / keyboard focus / background / system reduced motion, with
383
+ a pause/play control in the section header;
384
+ - `label` / `value` / `hint` / `tone` / `iconPath` cover the common metric card; use the
385
+ default slot for custom content.
386
+
387
+ Currently provided (each subpath is an independent export):
388
+
389
+ | Subpath | Contents | Purpose |
390
+ |---------|----------|---------|
391
+ | `./ui` | `Select` component | Dropdown (`update:modelValue` / `open` events, `md` / `sm` sizes) |
392
+ | `./ui/quick-card` | `QuickCard` component | Shared chrome for host-shell home quick cards (host tokens / dark mode / font scale; tap handled by the host) |
393
+ | `./ui/plugin-global-dialog` | `PluginGlobalDialog` component | Mobile host global dialog (mounted once at the app root; rendering driven by the global dialog controller, same shape as desktop) |
394
+ | `./ui/swipe-tabs` | `useSwipeTabs` composable | Horizontal swipe switching for dialog/tab content areas (a dominant-horizontal swipe past the threshold fires `onSwitch`; dominant-vertical swipes record no offset; `shouldSkip` excludes touch origins that must not act as page-swipe gestures, e.g. input controls) |
395
+ | `./global-dialog` | global dialog controller | Publish-subscribe dialog queue (FIFO, at most one open at a time; `update()` builds a fresh entry object before broadcasting), shared by the host and the dev-shell |
396
+
397
+ ## Subpath Exports
398
+
399
+ | Subpath | Contents |
400
+ |---------|----------|
401
+ | `@binblink/wasmnest-plugin-sdk-mobile` | Main API: types + runtime proxies |
402
+ | `@binblink/wasmnest-plugin-sdk-mobile/vite` | `wasmnestPlugin()` Vite build plugin |
403
+ | `@binblink/wasmnest-plugin-sdk-mobile/types` | Pure types (types only, no runtime) |
404
+ | `@binblink/wasmnest-plugin-sdk-mobile/ui` | Shared Vue component: `Select` |
405
+ | `@binblink/wasmnest-plugin-sdk-mobile/ui/quick-card` | `QuickCard` home quick card |
406
+ | `@binblink/wasmnest-plugin-sdk-mobile/ui/plugin-global-dialog` | `PluginGlobalDialog` |
407
+ | `@binblink/wasmnest-plugin-sdk-mobile/ui/swipe-tabs` | `useSwipeTabs` |
408
+ | `@binblink/wasmnest-plugin-sdk-mobile/global-dialog` | global dialog controller |
409
+
410
+ ## Developing this SDK
411
+
412
+ ```bash
413
+ pnpm run build # tsup build → dist (ESM + d.ts)
414
+ pnpm run test:run # vitest run
415
+ ```