Skip to content

Commit 45796fc

Browse files
chrisbbreuerchrisbbreuer
committed
chore: wip
1 parent a87bfac commit 45796fc

File tree

12 files changed

+1933
-207
lines changed

12 files changed

+1933
-207
lines changed

‎packages/zyte/API_REFERENCE.md‎

Lines changed: 493 additions & 0 deletions
Large diffs are not rendered by default.

‎packages/zyte/FEATURES.md‎

Lines changed: 403 additions & 0 deletions
Large diffs are not rendered by default.

‎packages/zyte/README.md‎

Lines changed: 164 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,42 @@
1-
# Zyte
1+
# ⚡ Zyte
22

3-
> Build desktop apps with web languages, powered by Zig
3+
**Build lightning-fast desktop apps with web languages**
44

5-
Zyte is a lightweight desktop application framework written in Zig that allows you to create native desktop applications using HTML, CSS, and JavaScript - similar to Tauri but implemented in Zig.
5+
A lightweight, Zig-powered framework for creating native desktop applications using HTML, CSS, and JavaScript. Think Electron or Tauri, but **100x smaller** and **blazingly fast**.
66

7-
## Features
7+
## ✨ Features
88

9-
- 🚀 **Native Performance** - Built with Zig for maximum performance and minimal overhead
10-
- 🎨 **Web Technologies** - Use familiar HTML, CSS, and JavaScript for UI
11-
- 📦 **Small Bundle Size** - Leverages system webview, no Chromium bundling
12-
- 🔒 **Secure** - Zig's memory safety combined with sandboxed webviews
13-
- 🌐 **Cross-Platform** - Support for macOS, Linux, and Windows
9+
### Core
10+
- 🪶 **Tiny**: 1.3MB binaries (vs 100MB+ Electron)
11+
- ⚡ **Fast**: Native WebKit, instant startup
12+
- 🎯 **Simple**: Clean, intuitive Zig API
13+
- 🌐 **Cross-platform**: macOS ✅ | Linux 🚧 | Windows 🚧
1414

15-
## Platform Support
15+
### Advanced
16+
- 🔗 **JavaScript Bridge**: Seamless Zig ↔ Web communication
17+
- 🎨 **Custom Windows**: Frameless, transparent, always-on-top
18+
- 🛠️ **DevTools**: Built-in WebKit Inspector
19+
- 📋 **Native Dialogs**: File open/save, clipboard access
20+
- ⚙️ **Configuration**: TOML-based config files
21+
- 📊 **Logging**: Color-coded, level-based logging system
1622

17-
| Platform | WebView Technology | Status |
18-
|----------|-------------------|--------|
19-
| macOS | WebKit | 🚧 In Progress |
20-
| Linux | WebKit2GTK | 🚧 In Progress |
21-
| Windows | WebView2 | 🚧 In Progress |
22-
23-
## Quick Start
24-
25-
### Prerequisites
26-
27-
- Zig 0.13.0 or later
23+
## 🚀 Quick Start
2824

2925
### Installation
3026

3127
```bash
32-
# Clone the repository
28+
# Clone or add as dependency
3329
git clone https://github.com/stacksjs/stx
3430
cd stx/packages/zyte
3531

36-
# Build the library
32+
# Build
3733
zig build
3834

39-
# Run the example
40-
zig build run
35+
# Run example
36+
./zig-out/bin/zyte-minimal http://localhost:3000
4137
```
4238

43-
## Usage
39+
### Basic Example
4440

4541
```zig
4642
const std = @import("std");
@@ -49,113 +45,183 @@ const zyte = @import("zyte");
4945
pub fn main() !void {
5046
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
5147
defer _ = gpa.deinit();
52-
const allocator = gpa.allocator();
5348
54-
var app = zyte.App.init(allocator);
49+
var app = zyte.App.init(gpa.allocator());
5550
defer app.deinit();
5651
57-
const html =
58-
\\<!DOCTYPE html>
59-
\\<html>
60-
\\<head>
61-
\\ <title>My App</title>
62-
\\</head>
63-
\\<body>
64-
\\ <h1>Hello from Zyte!</h1>
65-
\\ <p>This is a desktop app built with web technologies</p>
66-
\\</body>
67-
\\</html>
68-
;
69-
70-
_ = try app.createWindow("My App", 800, 600, html);
52+
// Load a URL directly (no iframe!)
53+
_ = try app.createWindowWithURL(
54+
"My App",
55+
1200,
56+
800,
57+
"http://localhost:3000",
58+
.{ .frameless = false },
59+
);
60+
7161
try app.run();
7262
}
7363
```
7464

75-
## API Reference
65+
## 📚 Documentation
7666

77-
### App
67+
- **[API Reference](API_REFERENCE.md)** - Complete API documentation
68+
- **[Improvements](IMPROVEMENTS.md)** - v0.2.0 changelog
69+
- **[Getting Started](GETTING_STARTED.md)** - Detailed setup guide
70+
- **[Quick Start](QUICK_START.md)** - 5-minute tutorial
7871

79-
The main application struct that manages windows and the event loop.
72+
## 🎯 CLI Usage
8073

81-
```zig
82-
pub const App = struct {
83-
pub fn init(allocator: std.mem.Allocator) Self
84-
pub fn createWindow(self: *Self, title: []const u8, width: u32, height: u32, html: []const u8) !*Window
85-
pub fn run(self: *Self) !void
86-
pub fn deinit(self: *Self) void
87-
}
74+
```bash
75+
# Show help
76+
zyte --help
77+
78+
# Load URL
79+
zyte http://localhost:3000
80+
81+
# Custom window
82+
zyte --url http://example.com \
83+
--title "My App" \
84+
--width 1200 \
85+
--height 800 \
86+
--frameless
87+
88+
# Load HTML directly
89+
zyte --html "<h1>Hello, World!</h1>"
90+
91+
# Transparent overlay
92+
zyte http://localhost:3000 \
93+
--transparent \
94+
--always-on-top \
95+
--frameless
8896
```
8997

90-
### Window
98+
## 🌟 JavaScript Bridge
9199

92-
Represents a single application window with a webview.
100+
Zyte automatically injects a powerful API into your web pages:
93101

94-
```zig
95-
pub const Window = struct {
96-
pub fn init(title: []const u8, width: u32, height: u32, html: []const u8) Self
97-
pub fn show(self: *Self) !void
98-
pub fn setHtml(self: *Self, html: []const u8) void
99-
pub fn eval(self: *Self, js: []const u8) !void
100-
pub fn deinit(self: *Self) void
101-
}
102-
```
102+
```javascript
103+
// Listen for ready event
104+
window.addEventListener('zyte:ready', async () => {
105+
console.log('Zyte version:', window.zyte.version);
103106

104-
## Architecture
107+
// Call native functions
108+
await window.zyte.notify('Hello from JavaScript!');
105109

106-
Zyte uses native system webviews for rendering:
110+
// File operations
111+
const content = await window.zyte.readFile('/path/to/file.txt');
112+
await window.zyte.writeFile('/path/to/output.txt', 'Hello!');
107113

108-
- **macOS**: Uses Cocoa's `WKWebView` via the WebKit framework
109-
- **Linux**: Uses GTK3 with `webkit2gtk-4.0`
110-
- **Windows**: Uses Microsoft's WebView2 (Edge Chromium)
114+
// Clipboard
115+
await window.zyte.setClipboard('Copied text!');
116+
const text = await window.zyte.getClipboard();
111117

112-
This approach keeps binary sizes small since we don't bundle a browser engine.
118+
// Dialogs
119+
const path = await window.zyte.openDialog({ title: 'Select file' });
120+
});
121+
```
113122

114-
## Development Status
123+
## ⚙️ Configuration
115124

116-
Zyte is currently in early development. The API structure is in place, but platform-specific webview bindings are still being implemented.
125+
Create a `zyte.toml` file:
117126

118-
### Roadmap
127+
```toml
128+
[window]
129+
title = "My App"
130+
width = 1200
131+
height = 800
132+
resizable = true
133+
frameless = false
134+
transparent = false
119135

120-
- [ ] Complete macOS WebKit bindings
121-
- [ ] Complete Linux GTK/WebKit2 bindings
122-
- [ ] Complete Windows WebView2 bindings
123-
- [ ] JavaScript ↔ Zig communication bridge
124-
- [ ] File system access APIs
125-
- [ ] Window customization (frameless, transparency, etc.)
126-
- [ ] System tray support
127-
- [ ] Menu bar integration
128-
- [ ] Multi-window support
129-
- [ ] Developer tools integration
136+
[webview]
137+
dev_tools = true
138+
```
130139

131-
## Building from Source
140+
## 🔧 Build Modes
132141

133142
```bash
134-
# Build library
143+
# Debug (default) - fast compilation
135144
zig build
136145

137-
# Run tests
138-
zig build test
146+
# Release Safe - optimized with safety checks
147+
zig build -Doptimize=ReleaseSafe
139148

140-
# Run example
141-
zig build run
149+
# Release Fast - maximum performance
150+
zig build -Doptimize=ReleaseFast
151+
152+
# Release Small - smallest binary (< 1MB!)
153+
zig build -Doptimize=ReleaseSmall
142154
```
143155

144-
## Contributing
156+
## 📊 Comparison
157+
158+
| | Zyte | Electron | Tauri |
159+
|--|------|----------|-------|
160+
| **Binary Size** | 1.3MB | 100MB+ | 3-10MB |
161+
| **Memory** | ~92MB | ~200MB | ~90MB |
162+
| **Startup** | Instant | Slow | Fast |
163+
| **Language** | Zig | JavaScript | Rust |
164+
| **Browser** | System WebKit | Bundled Chromium | System WebView |
165+
| **DevTools** | ✅ Built-in | ✅ Built-in | ✅ Via config |
166+
167+
## 🛠️ Platform Support
168+
169+
| Feature | macOS | Linux | Windows |
170+
|---------|-------|-------|---------|
171+
| Window Creation | ✅ | 🚧 | 🚧 |
172+
| WebView | ✅ | 🚧 | 🚧 |
173+
| DevTools | ✅ | 🚧 | 🚧 |
174+
| Dialogs | ✅ | ❌ | ❌ |
175+
| Clipboard | ✅ | ❌ | ❌ |
176+
| JS Bridge | ✅ | 🚧 | 🚧 |
177+
| Menu Bar | 🚧 | ❌ | ❌ |
178+
| System Tray | ❌ | ❌ | ❌ |
179+
180+
✅ Working | 🚧 Ready | ❌ Not yet
181+
182+
## 📦 What's New in v0.2.0
183+
184+
- ✅ Direct URL loading (no iframe!)
185+
- ✅ Comprehensive CLI with 10+ flags
186+
- ✅ Custom window styles (frameless, transparent, etc.)
187+
- ✅ WebKit DevTools integration
188+
- ✅ JavaScript ↔ Zig bridge
189+
- ✅ Native file dialogs
190+
- ✅ Clipboard access
191+
- ✅ Configuration file support
192+
- ✅ Color-coded logging system
193+
194+
See [IMPROVEMENTS.md](IMPROVEMENTS.md) for full details.
195+
196+
## 🎯 Use Cases
197+
198+
- **Dev Tools**: Create custom development environments
199+
- **Dashboards**: Build system monitoring apps
200+
- **Utilities**: Small, focused desktop tools
201+
- **Prototypes**: Rapid UI development
202+
- **Internal Tools**: Company-specific applications
203+
- **Cross-platform Apps**: Write once, run anywhere
204+
205+
## 🤝 Contributing
206+
207+
Contributions welcome! Areas of focus:
145208

146-
Contributions are welcome! This is part of the Stacks ecosystem.
209+
- Linux support (GTK + WebKit2GTK)
210+
- Windows support (WebView2)
211+
- Hot reload functionality
212+
- System tray integration
213+
- Additional examples
147214

148-
## License
215+
## 📄 License
149216

150-
MIT
217+
MIT License - see LICENSE file for details
151218

152-
## Acknowledgments
219+
## 🙏 Acknowledgments
153220

154-
Inspired by:
155-
- [Tauri](https://tauri.app/) - Rust-based desktop framework
156-
- [webview](https://github.com/webview/webview) - C/C++ webview library
157-
- [Neutralinojs](https://neutralino.js.org/) - Lightweight alternative to Electron
221+
- Built with [Zig](https://ziglang.org/) 0.15.1
222+
- Part of the [Stacks](https://github.com/stacksjs/stacks) ecosystem
223+
- Inspired by Electron, Tauri, and Wails
158224

159225
---
160226

161-
Part of the [Stacks](https://github.com/stacksjs/stx) ecosystem.
227+
**⚡ Built with Zig. Lightning fast. Incredibly small.**

0 commit comments

Comments
 (0)