npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

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.

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.

CI Rust Platform License

Installation • Quick Start • CLI Reference • Configuration • JavaScript API • Roadmap • Documentation


📦 Installation

Prerequisites (Windows 10/11)

  • Node.js >= 14.8.0 (used to evaluate wavical.config.js)
  • Microsoft Edge WebView2 Runtime (pre-installed on Windows 11)

Option 1: Install via npm (Recommended)

npm install -g wavical

Once installed, both wavical and the short alias wca are available globally:

wavical --version
wca --help

Option 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 --backend

2. Run in Development Mode

Starts the hot-reload dev server and opens the native WebView2 shell:

wavical dev

3. 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.js is evaluated by Node.js during wavical dev and wavical build. Always inspect wavical.config.js before 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.