wavical
v1.0.2
Published
A lightweight, security-first, AI-native desktop app framework built in Rust using OS WebView2, capability-gated IPC, optional sandboxed Node.js backends, and signed auto-updates.
Maintainers
Readme
🌊 Wavical
A lightweight, security-first, AI-native desktop app framework built in Rust.
Build native desktop apps with HTML, CSS, and JavaScript using the OS WebView2 runtime, capability-gated IPC, local/cloud AI, optional sandboxed Node.js backends, and signed auto-updates.
Installation • Quick Start • CLI Reference • Configuration • JavaScript API • Roadmap • Documentation
📦 Installation
Prerequisites (Windows 10/11)
- Node.js
>= 14.8.0(used to evaluatewavical.config.js) - Microsoft Edge WebView2 Runtime (pre-installed on Windows 11)
Option 1: Install via npm (Recommended)
npm install -g wavicalOnce installed, both wavical and the short alias wca are available globally:
wavical --version
wca --helpOption 2: Build from Source (Rust / Cargo)
Requires Rust (stable) and Visual Studio C++ Build Tools:
git clone https://github.com/dhananjay-ryu-jin-sama/Wavical.git
cd Wavical
# Install the CLI binary (`wavical` and `wca`) into ~/.cargo/bin
cargo install --path crates/wavical-cli🚀 Quick Start
1. Create a New App
# Standard app template
wavical init my-app
cd my-app
# Or scaffold with AI assistance
wavical init my-ai-app --ai "Create a markdown note-taking app"
# Or scaffold with an optional Node.js backend (`backend/main.js`)
wavical init my-backend-app --backend2. Run in Development Mode
Starts the hot-reload dev server and opens the native WebView2 shell:
wavical dev3. Build for Production
Bundles your frontend (and optional backend) into dist/ with a SHA-256 asset manifest (wavical-manifest.json):
wavical build
# Bundle the verified Node.js backend runtime into the output directory
wavical build --bundle-runtime🛠️ CLI Reference
Both wavical and wca accept the same commands:
Core Project Commands
| Command | Description |
|---|---|
| wavical init <DIR> [--force] [--backend] [--ai "<prompt>"] | Scaffold a new Wavical project in <DIR>. |
| wavical dev [DIR] | Start hot-reload development server and launch the desktop shell. |
| wavical build [DIR] [--outdir dist] [--bundle-runtime] | Build production assets and generate wavical-manifest.json. |
| wavical register-filetypes [DIR] | Register file extensions from wavical.config.js in Windows (HKCU). |
| wavical unregister-filetypes [DIR] | Remove registered Windows file associations for the project. |
AI & Cloud Secret Commands
| Command | Description |
|---|---|
| wavical ai doctor [DIR] | Check CPU SIMD support (AVX2/FMA), RAM, disk space, and AI readiness. |
| wavical ai bench [DIR] [--rag-only] [--runs 5] | Run local chat and RAG vector store performance benchmarks. |
| wavical model list | List approved catalog GGUF models and local installation status. |
| wavical model pull <ID> [--accept-license <ID>] | Download and SHA-256 verify a model from Hugging Face. |
| wavical model verify <ID> | Verify SHA-256 hash and GGUF header of an installed model. |
| wavical model remove <ID> | Delete an installed model from local storage. |
| wavical secret set <HOST> | Save a cloud provider API key in the Windows Credential Store (e.g. api.openai.com). |
| wavical secret clear <HOST> | Remove a stored API key from the Windows Credential Store. |
Node.js Backend Runtime Commands
| Command | Description |
|---|---|
| wavical runtime list | List approved pinned Node.js runtimes and local cache status. |
| wavical runtime install <VERSION> | Download, verify SHA-256, and cache a Node.js runtime (e.g. 22.11.0). |
| wavical runtime verify <VERSION> | Verify cryptographic integrity of a cached runtime. |
| wavical runtime remove <VERSION> | Remove a cached runtime version. |
| wavical runtime status [DIR] | Inspect runtime cache status and project backend configuration. |
Update Signing & Release Commands
| Command | Description |
|---|---|
| wavical signer keygen --out <PATH> | Generate an Ed25519 signing keypair (must be stored outside git repos). |
| wavical release manifest --payload <FILE> --version <VER> --channel <CH> --expires <DAYS> --rollout <0-100> --notes <FILE> | Generate an update manifest.json for a release payload. |
| wavical release sign --key <KEY_PATH> <MANIFEST> | Sign manifest.json with your private key to produce manifest.json.sig. |
| wavical release verify --pubkey <BASE64_PUBKEY> <MANIFEST> | Verify manifest.json and its .sig against an Ed25519 public key. |
⚙️ Configuration (wavical.config.js)
Every project is configured through a single wavical.config.js file in the project root. All capabilities are default-deny (omitted or false means blocked).
/** @type {import('wavical-config').AppConfig} */
export default {
appId: 'my-app',
version: '0.1.0',
window: {
title: 'My App',
width: 1200,
height: 800,
persistState: true,
},
singleInstance: true,
// Explicitly grant only the IPC capabilities your app needs
capabilities: {
'core.ping': true,
'clipboard.read': true,
'clipboard.write': true,
'notify.send': true,
'dialog.openFile': true,
'dialog.saveFile': true,
'fs.readGranted': true,
'fs.writeGranted': true,
'menu.showContextMenu': true,
'tray.set': true,
'shortcut.register': true,
// Requires `ai.enabled: true`
'ai.chat': true,
'ai.index': true,
'ai.search': true,
// Requires `backend.enabled: true`
'backend.invoke': true,
// Requires `updater.enabled: true`
'updater.check': true,
'updater.apply': true,
},
// Optional: Local / Cloud AI configuration
ai: {
enabled: true,
mode: 'local', // 'local' | 'cloud' | 'local-first'
local: {
chatModel: 'qwen2.5-1.5b-instruct',
embedModel: 'bge-small-en-v1.5',
contextSize: 4096,
maxTokens: 1024,
idleMinutes: 10,
threads: 'auto',
},
},
// Optional: Sandboxed Node.js backend
backend: {
enabled: true,
runtime: 'node',
version: '22.11.0',
entry: 'backend/main.js',
methods: ['greet', 'compute'],
timeoutSeconds: 30,
permissions: {
fsRead: [],
fsWrite: [],
childProcess: false,
workers: false,
},
},
// Optional: Signed auto-updates
updater: {
enabled: false,
manifestUrl: 'https://updates.example.com/manifest.json',
publicKeys: ['<BASE64_ED25519_PUBLIC_KEY>'],
channel: 'stable', // 'stable' | 'beta' | 'canary'
checkIntervalHours: 24,
autoDownload: true,
},
dialog: {
filters: {
text: { name: 'Text Documents', extensions: ['txt', 'md', 'json'] },
},
},
shortcuts: ['Ctrl+Shift+K'],
fileAssociations: ['wca'],
dev: {
port: 7890,
},
};[!WARNING]
wavical.config.jsis evaluated by Node.js duringwavical devandwavical build. Always inspectwavical.config.jsbefore running CLI commands on untrusted third-party repositories.
🧩 JavaScript API
Wavical injects a frozen window.wavical object into your frontend.
1. Core & Native OS APIs
// Health check
const ping = await window.wavical.invoke('core.ping');
// Clipboard
await window.wavical.invoke('clipboard.write', { text: 'Hello from Wavical!' });
const clip = await window.wavical.invoke('clipboard.read');
// Native desktop notification
await window.wavical.invoke('notify.send', {
title: 'Export Complete',
body: 'Your file has been saved.',
});
// Scoped File Access (Webview never sees raw file paths, only opaque grantIds)
const openRes = await window.wavical.invoke('dialog.openFile', {
title: 'Select a note',
filterId: 'text',
});
if (!openRes.cancelled) {
const { content } = await window.wavical.invoke('fs.readGranted', {
grantId: openRes.grantId,
});
console.log(content);
}
// Listen for native menu & global shortcut events
window.addEventListener('wavical:menu', (e) => console.log('Menu clicked:', e.detail.id));
window.addEventListener('wavical:shortcut', (e) => console.log('Shortcut pressed:', e.detail));2. Local & Cloud AI (ai.chat, ai.index, ai.search)
// Stream AI chat tokens
await window.wavical.invoke(
'ai.chat',
{
messages: [{ role: 'user', content: 'Summarize Rust ownership in 2 sentences.' }],
maxTokens: 256,
temperature: 0.7,
stream: true,
},
(chunk) => {
// Always use textContent (never innerHTML) for model output
document.getElementById('output').textContent += chunk;
}
);
// Cancel an active generation in the current window
await window.wavical.cancel(1);
// Index documents into the embedded local SQLite vector store
await window.wavical.invoke('ai.index', {
action: 'add',
collection: 'notes',
documents: [{ id: 'doc-1', text: 'Wavical uses WebView2 and default-deny capabilities.' }],
});
// Semantic similarity search
const results = await window.wavical.invoke('ai.search', {
collection: 'notes',
query: 'How are permissions handled?',
topK: 3,
});3. Invoking the Node.js Backend (backend.invoke)
// Calls a method allowlisted in `backend.methods` in wavical.config.js
const res = await window.wavical.invoke('backend.invoke', {
method: 'compute',
params: { values: [10, 20, 30] },
});All Supported Capabilities
| Capability | Parameters | Description |
|---|---|---|
| core.ping | none | Health check ({ message: "pong", version }). |
| core.echo | any | Echoes input parameters back. |
| clipboard.read | none | Reads text from system clipboard (max 1 MB). |
| clipboard.write | { text: string } | Writes text to system clipboard (max 1 MB). |
| notify.send | { title: string, body?: string } | Sends native OS notification (rate-limited: 5 / 10s). |
| dialog.openFile | { title?: string, filterId?: string } | Opens file dialog; returns ReadOnly grantId. |
| dialog.saveFile | { title?: string, defaultName?: string, filterId?: string } | Opens save dialog; returns WriteOnly grantId. |
| fs.readGranted | { grantId: string } | Reads UTF-8 file using a ReadOnly grantId (max 10 MB). |
| fs.writeGranted | { grantId: string, content: string } | Atomically writes UTF-8 text using a WriteOnly grantId (max 10 MB). |
| menu.showContextMenu | { items: MenuItem[] } | Displays native popup context menu at cursor (max 200 items). |
| tray.set | { tooltip?: string, items?: MenuItem[] } | Configures system tray icon tooltip and menu items. |
| shortcut.register | { shortcut: string } \| { shortcuts: string[] } | Registers global keyboard shortcuts (max 32). |
| badge.set | { count: number \| null } | Sets taskbar badge count (0..=99). |
| ai.chat | { messages, maxTokens?, temperature?, stream? } | Runs local GGUF or cloud chat completion (also enables ai.cancel). |
| ai.index | { action: 'add' \| 'replace' \| 'delete', collection, documents? } | Indexes or deletes documents in the local RAG store. |
| ai.search | { collection: string, query: string, topK?: number } | Searches local RAG collection by cosine similarity (topK 1–20). |
| backend.invoke | { method: string, params?: any } | Invokes an allowlisted method in the Node.js backend process. |
| updater.check | none | Checks configured manifestUrl for a signed update. |
| updater.apply | none | Stages and applies a verified update with health-check rollback. |
🗺️ Roadmap
| Phase | Focus | Status |
|:-:|---|:-:|
| 0 | Foundation shell (tao/wry), wavical:// protocol, secure IPC, CSP | ✅ Completed |
| 1 | wavical / wca CLI (init, dev, build), wavical.config.js, hot-reload | ✅ Completed |
| 2 | Native Tier 1 APIs: scoped file grants, clipboard, notifications, tray, menus, shortcuts | ✅ Completed |
| 3 | AI-native: local GGUF engine, cloud fallback + consent, local RAG (ai.index/ai.search) | ✅ Completed |
| 4 | Opt-in sandboxed Node.js backend runtime (wavical runtime), Ed25519 signed updates | ✅ Completed |
| 5 | Windows installers (.exe/.msi), code signing, portable builds, public benchmarks | 📋 Planned |
| 6 | Enterprise: structured audit logging, SBOM generation, wavical audit, private registries | 📋 Planned |
Full breakdown: ROADMAP.md
📄 License
Dual-licensed under either of MIT License or Apache License, Version 2.0, at your option.
