@craft-native/craft 0.0.5

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 (5) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +421 -0
  3. package/bin/cli.ts +899 -0
  4. package/dist/index.js +8712 -0
  5. package/package.json +69 -0
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ # MIT License
2
+
3
+ Copyright (c) 2025 Stacks.js
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,421 @@
1
+ # ts-craft
2
+
3
+ Build lightning-fast desktop apps with web languages, powered by Zig.
4
+
5
+ ## Features
6
+
7
+ - **Lightning Fast**: 50ms startup vs Electron's 230ms (4.5x faster)
8
+ - **Tiny Memory Footprint**: ~14 KB idle vs Electron's 68 MB (4857x less)
9
+ - **Small Binaries**: 3 MB vs Electron's 135 MB (45x smaller)
10
+ - **TypeScript First**: Full type safety with zero dependencies
11
+ - **Zero Config**: Just write HTML/CSS/JS and run
12
+ - **Cross-Platform**: macOS, Linux, Windows
13
+ - **GPU Accelerated**: Direct Metal/Vulkan access for blazing performance
14
+ - **Hot Reload**: Built-in development mode with auto-refresh
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ bun add ts-craft
20
+ ```
21
+
22
+ ## Quick Start
23
+
24
+ ### Minimal Example (1 line!)
25
+
26
+ ```ts
27
+ import { show } from '@stacksjs/ts-craft'
28
+
29
+ await show('<h1>Hello Craft!</h1>', { title: 'My App', width: 600, height: 400 })
30
+ ```
31
+
32
+ ### Hello World
33
+
34
+ ```ts
35
+ import { createApp } from '@stacksjs/ts-craft'
36
+
37
+ const html = `
38
+ <!DOCTYPE html>
39
+ <html>
40
+ <head>
41
+ <meta charset="UTF-8">
42
+ <style>
43
+ body {
44
+ margin: 0;
45
+ display: flex;
46
+ justify-content: center;
47
+ align-items: center;
48
+ height: 100vh;
49
+ background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
50
+ color: white;
51
+ font-family: system-ui, sans-serif;
52
+ }
53
+ </style>
54
+ </head>
55
+ <body>
56
+ <h1>⚡ Lightning Fast Desktop Apps</h1>
57
+ </body>
58
+ </html>
59
+ `
60
+
61
+ const app = createApp({
62
+ html,
63
+ window: {
64
+ title: 'My Craft App',
65
+ width: 800,
66
+ height: 600,
67
+ },
68
+ })
69
+
70
+ await app.show()
71
+ ```
72
+
73
+ ### Load a URL
74
+
75
+ ```ts
76
+ import { loadURL } from '@stacksjs/ts-craft'
77
+
78
+ // Load any website or local dev server
79
+ await loadURL('http://localhost:3000', {
80
+ title: 'My Web App',
81
+ width: 1200,
82
+ height: 800,
83
+ devTools: true,
84
+ hotReload: true,
85
+ })
86
+ ```
87
+
88
+ ## API Reference
89
+
90
+ ### `createApp(config)`
91
+
92
+ Create a new Craft app instance.
93
+
94
+ ```ts
95
+ import { createApp } from '@stacksjs/ts-craft'
96
+
97
+ const app = createApp({
98
+ html: '<h1>Hello</h1>', // HTML content
99
+ url: 'https://example.com', // Or load a URL
100
+ window: {
101
+ title: 'My App',
102
+ width: 800,
103
+ height: 600,
104
+ // ... more options
105
+ },
106
+ })
107
+
108
+ await app.show()
109
+ ```
110
+
111
+ ### `show(html, options)`
112
+
113
+ Quick helper to show a window with HTML.
114
+
115
+ ```ts
116
+ import { show } from '@stacksjs/ts-craft'
117
+
118
+ await show('<h1>Hello World</h1>', {
119
+ title: 'My App',
120
+ width: 600,
121
+ height: 400,
122
+ })
123
+ ```
124
+
125
+ ### `loadURL(url, options)`
126
+
127
+ Quick helper to load a URL.
128
+
129
+ ```ts
130
+ import { loadURL } from '@stacksjs/ts-craft'
131
+
132
+ await loadURL('http://localhost:3000', {
133
+ title: 'Dev Server',
134
+ width: 1200,
135
+ height: 800,
136
+ devTools: true,
137
+ })
138
+ ```
139
+
140
+ ## Window Options
141
+
142
+ ```ts
143
+ interface WindowOptions {
144
+ title?: string // Window title
145
+ width?: number // Width in pixels (default: 800)
146
+ height?: number // Height in pixels (default: 600)
147
+ x?: number // X position
148
+ y?: number // Y position
149
+ resizable?: boolean // Can resize (default: true)
150
+ frameless?: boolean // Frameless window (default: false)
151
+ transparent?: boolean // Transparent background (default: false)
152
+ alwaysOnTop?: boolean // Always on top (default: false)
153
+ fullscreen?: boolean // Start fullscreen (default: false)
154
+ darkMode?: boolean // Enable dark mode
155
+ hotReload?: boolean // Enable hot reload (default: dev mode)
156
+ devTools?: boolean // Enable dev tools (default: dev mode)
157
+ systemTray?: boolean // Enable system tray (default: false)
158
+ hideDockIcon?: boolean // Hide dock icon (macOS menubar-only mode)
159
+ menubarOnly?: boolean // No window, tray icon only
160
+ titlebarHidden?: boolean // Hide titlebar (content extends into titlebar)
161
+ vibrancy?: string // macOS vibrancy effect
162
+ }
163
+ ```
164
+
165
+ ## Menubar Apps
166
+
167
+ Craft supports menubar/system tray apps with or without a popup window.
168
+
169
+ ### Menubar with Popup Window
170
+
171
+ ```ts
172
+ import { createApp } from '@stacksjs/ts-craft'
173
+
174
+ const app = createApp({
175
+ html: `<h1>Pomodoro Timer</h1>`,
176
+ window: {
177
+ title: 'Timer',
178
+ width: 320,
179
+ height: 380,
180
+ systemTray: true, // Enable system tray icon
181
+ hideDockIcon: true, // Hide dock icon (menubar-only)
182
+ frameless: true,
183
+ transparent: true,
184
+ },
185
+ })
186
+
187
+ await app.show()
188
+ ```
189
+
190
+ ### Menubar-Only (No Window)
191
+
192
+ ```ts
193
+ const app = createApp({
194
+ window: {
195
+ title: 'System Monitor',
196
+ menubarOnly: true, // No window, tray icon only
197
+ systemTray: true,
198
+ hideDockIcon: true,
199
+ },
200
+ })
201
+
202
+ await app.show()
203
+ ```
204
+
205
+ ### Tray API (from JavaScript in your HTML)
206
+
207
+ ```js
208
+ // Update menubar title (e.g., "🍅 25:00")
209
+ window.craft.tray.setTitle('🍅 25:00')
210
+
211
+ // Set context menu
212
+ window.craft.tray.setMenu([
213
+ { label: 'Start', action: 'start' },
214
+ { label: 'Pause', action: 'pause' },
215
+ { type: 'separator' },
216
+ { label: 'Quit', action: 'quit' }
217
+ ])
218
+
219
+ // Listen for menu actions
220
+ window.addEventListener('craft:tray:menu', (e) => {
221
+ switch (e.detail.action) {
222
+ case 'start': startTimer(); break
223
+ case 'pause': pauseTimer(); break
224
+ case 'quit': window.craft.app.quit(); break
225
+ }
226
+ })
227
+ ```
228
+
229
+ ## Window API (JavaScript)
230
+
231
+ Control the window from your HTML/JavaScript:
232
+
233
+ ```js
234
+ // Visibility
235
+ window.craft.window.show()
236
+ window.craft.window.hide()
237
+ window.craft.window.toggle()
238
+ window.craft.window.focus()
239
+
240
+ // State
241
+ window.craft.window.minimize()
242
+ window.craft.window.maximize()
243
+ window.craft.window.close()
244
+ window.craft.window.toggleFullscreen()
245
+ window.craft.window.center()
246
+
247
+ // Properties
248
+ window.craft.window.setTitle('New Title')
249
+ window.craft.window.setPosition(100, 100)
250
+
251
+ // Events
252
+ window.craft.window.on('focus', () => console.log('Focused'))
253
+ window.craft.window.on('blur', () => console.log('Blurred'))
254
+ ```
255
+
256
+ ## App API (JavaScript)
257
+
258
+ Application lifecycle and system integration:
259
+
260
+ ```js
261
+ // Lifecycle
262
+ window.craft.app.quit()
263
+ window.craft.app.hide()
264
+ window.craft.app.show()
265
+
266
+ // Dock (macOS)
267
+ window.craft.app.hideDockIcon()
268
+ window.craft.app.showDockIcon()
269
+ window.craft.app.setBadge('3')
270
+ window.craft.app.bounce()
271
+
272
+ // Notifications
273
+ window.craft.app.notify({
274
+ title: 'Timer Complete',
275
+ body: 'Your focus session is done!'
276
+ })
277
+
278
+ // System info
279
+ window.craft.app.isDarkMode() // Returns true/false
280
+ window.craft.app.getLocale() // Returns 'en-US', etc.
281
+ ```
282
+
283
+ ## Sidebar Styles
284
+
285
+ Craft includes pre-built CSS styles for three popular sidebar designs:
286
+
287
+ ### Tahoe Style (macOS Finder)
288
+
289
+ ```ts
290
+ import { tahoeStyles, renderTahoeSidebar, tahoeDemoData } from '@stacksjs/ts-craft'
291
+
292
+ // Use Tailwind classes
293
+ const sidebar = `<div class="${tahoeStyles.sidebar}">...</div>`
294
+
295
+ // Or render full HTML
296
+ const html = renderTahoeSidebar(tahoeDemoData)
297
+ ```
298
+
299
+ ### Arc Style (Arc Browser)
300
+
301
+ ```ts
302
+ import { arcStyles, renderArcSidebar, arcDemoData } from '@stacksjs/ts-craft'
303
+
304
+ // Gradient pills, collapsible sections
305
+ const html = renderArcSidebar(arcDemoData, false) // collapsed = false
306
+ ```
307
+
308
+ ### OrbStack Style (Minimal Dark)
309
+
310
+ ```ts
311
+ import { orbstackStyles, renderOrbStackSidebar, orbstackDemoData } from '@stacksjs/ts-craft'
312
+
313
+ // Dark #1a1a1a theme with status indicators
314
+ const html = renderOrbStackSidebar(orbstackDemoData)
315
+ ```
316
+
317
+ ## Examples
318
+
319
+ See the [examples directory](../examples-ts) for more:
320
+
321
+ ### Basic Apps
322
+ - **minimal.ts** - Simplest possible app
323
+ - **hello-world.ts** - Modern styled app
324
+ - **todo-app.ts** - Interactive todo list
325
+
326
+ ### Menubar Apps
327
+ - **menubar-timer.ts** - Pomodoro timer with popup window
328
+ - **menubar-only.ts** - System monitor (no window, tray icon only)
329
+
330
+ ### Sidebar Apps
331
+ - **file-browser.ts** - Finder-like app with Tahoe sidebar
332
+ - **arc-browser.ts** - Browser with Arc-style vertical tabs
333
+ - **orbstack-containers.ts** - Container manager with OrbStack style
334
+ - **sidebar-showcase.ts** - All three sidebar styles side-by-side
335
+
336
+ Run examples:
337
+
338
+ ```bash
339
+ # Basic apps
340
+ bun run packages/examples-ts/hello-world.ts
341
+ bun run packages/examples-ts/todo-app.ts
342
+
343
+ # Menubar apps
344
+ bun run packages/examples-ts/menubar-timer.ts
345
+ bun run packages/examples-ts/menubar-only.ts
346
+
347
+ # Sidebar apps
348
+ bun run packages/examples-ts/file-browser.ts
349
+ bun run packages/examples-ts/arc-browser.ts
350
+ bun run packages/examples-ts/sidebar-showcase.ts
351
+ ```
352
+
353
+ ## Performance Comparison
354
+
355
+ | Metric | Craft | Electron | Advantage |
356
+ |--------|------|----------|-----------|
357
+ | **Startup Time** | 50ms | 230ms | **4.5x faster** |
358
+ | **Idle Memory** | 14 KB | 68 MB | **4857x less** |
359
+ | **Binary Size** | 3 MB | 135 MB | **45x smaller** |
360
+ | **IPC Throughput** | 2.89 µs | 2.16 ms | **748x faster** |
361
+
362
+ See [benchmarks](../../benchmarks) for detailed performance comparisons.
363
+
364
+ ## Why Craft?
365
+
366
+ ### vs Electron
367
+
368
+ - **4.5x faster startup** - Your app opens instantly
369
+ - **4857x less memory** - More performant on any machine
370
+ - **45x smaller binaries** - Faster downloads, less disk space
371
+ - **No Chromium** - Native webview means better integration
372
+ - **GPU accelerated** - Direct Metal/Vulkan for smooth rendering
373
+
374
+ ### vs Tauri
375
+
376
+ - **2.77x faster startup** - Even quicker than Tauri
377
+ - **186x less idle memory** - Extremely lightweight
378
+ - **No Rust required** - Just TypeScript/JavaScript
379
+ - **Zero dependencies** - Pure Node.js APIs only
380
+ - **Better DX** - Hot reload and dev tools built-in
381
+
382
+ ## Requirements
383
+
384
+ - Bun >= 1.0.0 (for development)
385
+ - Craft binary (automatically built on install)
386
+
387
+ ## Building from Source
388
+
389
+ ```bash
390
+ # Clone the monorepo
391
+ git clone https://github.com/stacksjs/craft
392
+ cd craft
393
+
394
+ # Install dependencies
395
+ bun install
396
+
397
+ # Build the Zig core
398
+ bun run build:core
399
+
400
+ # Build the TypeScript SDK
401
+ bun run build:sdk
402
+
403
+ # Run examples
404
+ cd packages/examples-ts
405
+ bun run hello-world
406
+ ```
407
+
408
+ ## Contributing
409
+
410
+ We love contributions! Please see our [contributing guide](../../CONTRIBUTING.md).
411
+
412
+ ## License
413
+
414
+ MIT © [Chris Breuer](https://github.com/chrisbbreuer)
415
+
416
+ ## Links
417
+
418
+ - [Documentation](https://github.com/stacksjs/craft#readme)
419
+ - [Examples](../examples-ts)
420
+ - [Benchmarks](../../benchmarks)
421
+ - [Issues](https://github.com/stacksjs/craft/issues)