🪷 Lotus (lotus-gui)

⚠️ IMPORTANT

UPDATED TO USE THE LATEST SERVO EMBEDDINGS 0.1.0!

We were using 0.0.6 so this is a large jump and allows us better control and ci along with bring in a whole sport of improvements from stability to performance. Please go take a look and give them some love! Servo 0.1.0 release

NEW SUPPORT FOR ENCRYPTED APPS with AEAD-ENCRYPTED (AES-256-GCM) VFS

The latest version adds support for packaging your app in a VFS with a natively derived key. This allows developers to ship closed-source applications while still leveraging web-based frontends. The decryption key is sharded across the native binary and never touches the V8 heap or the Node.js environment.

Disclaimer about Encryption and Closed-Source Software

Lotus supports encryption to protect your intellectual property. However, the encryption layer relies on secrets injected during the build process. Anyone with access to the decrypted application in memory (e.g., using debugging tools like WinDbg, Frida, or manual memory inspection) may eventually extract these secrets. Users should be aware that client-side encryption is primarily a deterrent against casual reverse engineering and unauthorized distribution, not a guarantee of absolute security against determined adversaries. As always, security in distributed binaries is a game of making extraction difficult enough that most people won't bother. It is fundamentally impossible to keep assets perfectly secure in the presence of a dedicated reverse engineer.

Lotus is a high-performance, lightweight desktop GUI framework that pairs the power of Node.js with the speed of the Servo rendering engine.

It's designed for developers who want to build cross-platform desktop applications with web technologies (HTML/CSS/JS) and want someting a bit easier to use. By using Servo instead of Chromium and keeping Node.js in the driver's seat for OS integration, Lotus delivers a "blistering fast" experience with a tiny footprint.

---

🏎️ "LOTUS IS MADE WITH THE IDEOLOGY OF A LOTUS ELISE." "If a part doesn't make it start faster, use less memory, or render pixels, it's gone. No extra suspension. No spare tires. No browser pretending to be an operating system."

🥊 THE ARCHITECTURE (Or: Why It's Fast) • Lotus Strategy: Node owns the OS. Servo paints the pixels. No magic. No fake sandboxes. No hidden instances listening to how you use each piece of it for telemetry. The Goal here is to just be a renderer and let the devs do everything else directly in node with a blistering fast ipc (tested up to 9k messages per second reliably)

🔧 THE ANALOGY THAT EXPLAINS EVERYTHING: • Node.js is the track. • Servo is the car. • IPC is the steering wheel. "On a track, you don't worry about potholes. You worry about lap times."

💡 THE POINT: "Node.js already does OS integration. We just needed a renderer. That's it. That's the whole project."

---

🚀 Quick Start (Usage from NPM)

The Easy Way: working Windows and Linux builds are on npm. You don't need to build from source.

Option 1: Quick Start (Recommended)

The fastest way to get started is with the CLI:

npx lotus init my-app
cd my-app
npm install
npx lotus dev

Option 2: Manual Setup

If you prefer to set things up yourself:

mkdir my-lotus-app && cd my-lotus-app
npm init -y
npm install @lotus-gui/core @lotus-gui/dev

Then see the example code below or check node_modules/@lotus-gui/core/test_app for a full reference.

---

🚀 Features (The Good Stuff)

• Speed that actually matters:

  • Cold start to interactive window can get below 400ms on linux
  • Windows is a litter slower right now as it has to compile ANGLE shaders, i am working on a pr to the servo project to add support for caching this on disk so it doesnt have to compile them every time. should eliminate the slower on windows after first launch
  • A single window stack (Rust + Node + Servo), even add windows maintains the reliance on the stack, you dont just spin up a second renderer or instance, its just a second dom that's it.
  • Adding a second window costs ~80MB. We share the renderer.

• Hybrid Runtime:

  • Core: Rust-based Servo engine. It renders HTML/CSS/JS. That's it.
  • Controller: Node.js main thread. It does literally everything else.

• Hybrid Mode (File Serving):

  • Custom Protocol: lotus-resource:// serves files from disk.
  • Why? I wanted to eliminate the need for a webserver just to serve local files. It's faster and more secure this way though it also allows us to have direct control over the file serving process and protocol for adding encrypted virtual file systems in the future. (coming soon!)
  • Security: Directory jailing. You can't ../../ your way to /etc/passwd. Nice try. This will also be further enhanced with the encrypted file systems in the future as you will be chunk loading on the fly in the loader itself or from ram if we load the whole thing in so reaching outside of that is noticiably harder on accident.

• Asset Protection (Encrypted VFS):

  • Zero-Trust Architecture: Want to ship a closed-source app? Lotus uses an AEAD-encrypted (AES-256-GCM) Virtual File System where the decryption key never touches JavaScript or the V8 heap.
  • Native Key Sharding: The CLI shards the master key across compiled Rust constants and native binary sections (ELF/PE). The Rust core autonomously derives the key in protected memory.
  • Byte-Limited LRU Cache: We mitigate decryption overhead with a strict 128MB byte-limited LRU cache. Once an asset is loaded, it's served from memory at blistering speeds without risking an Out-Of-Memory (OOM) panic on heavy media files.

• Advanced IPC (The Steering Wheel):

  • WebSocket IPC Server: We use tokio + axum on 127.0.0.1:0 with persistent WebSocket connections. It works. It's pretty fast and low latency. Yeah i know its a bit overkill but it works and it was fun to implement, though the main reasons are it also gives us blustering fast ipc, at least on my system in my personal testing i was able to get 10k messages per second reliably at an average latency of 0.111 ms in a string message test.

IPC stress test: 9,000+ messages/second at 0.111ms average latency (Linux)

• Auto-Adapting: JSON? Binary? Blobs? We don't care. We handle it via WebSockets natively using msgpack to massively decrease the serialization/deserialization overhead and increase performance.

  • MsgPack Batching (Pipelines): We pack small messages together and unleash them in bursts to avoid starving the Winit rendering thread.
  • Zero-Copy focused Routing: It's not fully zero copy as we have to move between stacks but i have tried my best to minimize this as much as possibly and moving it as little as possible. the only time it becomes copy is when it moves stacks but inside themselves they are not. i am looking into ideas of how to see if we can hand them off with a shared memory space between node and servo but.... for now this is a imo beautiful solution that is fast and reliable.
  • invoke() / handle() (Promise IPC): The renderer calls window.lotus.invoke('ch', data) and gets back a Promise. Node registers ipcMain.handle('ch', async fn). No manual reply channels, no leaked listeners, no correlation IDs in your app code. I wanted this as simple as possible so it is easier to just pickup and use, though with the invoke and handle we still have .send and .on for the more advanced users who want more control over the ipc.
  • File Drag-and-Drop: OS-level file drag is intercepted from winit and forwarded to both the renderer (window.lotus.on('file-drop', ...)) and Node.js (win.on('file-drop', ...)). Zero Servo involvement, pure winit event forwarding so we dont have to have it touch pieces it doesnt have to.

• Window State Persistence:

  • It remembers where you put the window (if you give it an ID). i know its a basic concept but i wanted to make it clear it does this on its own, you dont have to do anything special other than give it an ID.
  • Handles maximized state, size, position.

• Script Injection:

  • Execute arbitrary JS in the renderer from the main process. God mode unlocked? Basically i know there are a lot of cases where you will want to inject scripts into the renderer from the main process on startup or dynamically or inject things into the window. This is the proper way to do it, if you run into any weird cases let me know.

• Native Look & Feel:

  • True OS transparency I have gone through and built out the proper winit 0.30 so we are using the latest and greatest in windowing tech for linux, mac, and windows and is properly using window-vibrancy 0.5 for native os transparncy on windows so you dont have the horrible overhead of trying to use transparnecy that is software and it looks a lot nicer.
  • No White Flash: We paint transparently. Your users won't be blinded by a white box while your JS loads.

• Frameless Windows:

  • Kill the title bar. Remove the frame. Build whatever you imagine.
  • Custom Drag Regions: Mark any element with -webkit-app-region: drag or data-lotus-drag. Lotus bridges it to the OS, no JS required.
  • Custom Resize Borders: 8px invisible resize handles on every edge and corner. They just work, i might add a parameter so you can adjust it if people find this is not how they like or want it differently. though if you are using the frame and decorations then this is handled by the os so i cant do much there.
  • Cursor-Aware: Resize cursors show up at the borders. Servo drives all other cursors (grab, pointer, text, etc.) no interference. it properly communicates with the os it is running on to properly trigger and show the right cursor for the right action.

• Multi-Window Support:

  • Spawn multiple independent windows from a single Node process.
  • Shared renderer = ~80MB per extra window.

---

📦 Monorepo Structure

Lotus is organized as a monorepo with two packages:

lotus/
├── packages/
│   ├── lotus-core/          # @lotus-gui/core -- Runtime engine (Servo + Node bindings)
│   │   ├── src/             # Rust source (N-API bindings, window management)
│   │   ├── lotus.js         # High-level JS API (ServoWindow, IpcMain, App)
│   │   ├── index.js         # Native binding loader
│   │   ├── resources/       # IPC bridge scripts, debugger
│   │   └── test_app/        # Example application
│   │
│   └── lotus-dev/           # @lotus-gui/dev -- CLI toolkit for development & packaging
│       ├── bin/lotus.js      # CLI entry point (lotus dev, build, clean)
│       └── lib/templates/    # Installer templates (RPM spec, etc.)
│
├── package.json             # Monorepo root (npm workspaces)
└── README.md                # You are here

Package	npm Name	What It Does
lotus-core	@lotus-gui/core	The runtime -- Servo engine, window management, IPC. This is what your app require()s.
lotus-dev	@lotus-gui/dev	CLI toolkit -- dev server with hot-reload, build system, DEB/RPM installer packaging.

---

🛠 Platform Support Matrix

Platform	Arch	Native Binary (.node)	Installer Target	Status
Linux (Debian/Ubuntu)	x64	✅ Verified	.deb (Stable)	Ready
Linux (Fedora/RHEL)	x64	✅ Verified	.rpm (Stable)	Ready
Linux (openSUSE)	x64	🛠 Testing	Planned	Alpha
Windows	x64	✅ Verified	.msi (testing)	Beta *1
FreeBSD	x64	🛠 Testing	Planned	Alpha
macOS	arm64	🆘 Help Wanted	TBD	On Hold

1 Windows Status:*

• What Works:

  • ✅ Native Binary: Pre-built .node available on npm
  • ✅ Build System: lotus build creates .msi installers
  • ✅ Runtime: Angle + Servo + Node.js run correctly
  • ✅ VC++ Redist: Auto-embedded and installed silently
  • ✅ Icon Handling: PNG/JPG → ICO conversion for installers
  • ✅ PE Header Patching: No black console window on launch

• Known Issues:

  • ⚠️ Installer Signing: Not yet implemented (requires EV cert)
  • ⚠️ NSIS Fallback: lotus build --target nsis still uses old logic

Note: * Installer Target: The packaged distribution format (what users download/install) * Native Binary: The .node file that powers the runtime (what developers require())

---

� STATUS: ALPHA almost BETA (BUT IT WORKS WELL!)

We have working Windows and Linux builds available on npm (@lotus-gui/core@0.3.3). Mac support is missing (because their ecosystem needs someone who nows it, please feel free to help!). BSD and SUSE support is planned (because I know the pain points over there, see Roadmap). Right now there are builds for BSD and SUSE so you can use it though it does not have an installer builder for them yet. I plan to add that in future releases.

## Version 0.3.3 (Current)

• Status: Beta? I'm not sure what to call it, but it works way better than any alpha ive seen! but hasnt been around long enough to call it stable yet. This is a big release and brings with it support for linux and windows installers for apps built with lotus. This allows you to build apps with lotus and just npx lotus build and it will build the app installer for you for your platform. It is still a bit early so any feedback is appreciated! I plan to be a continued project for a while and I'm excited to see what we can do with it.

Supported-Installers

• **Windows: