electrobun 0.0.2 → 0.0.4

package/documentation/docs/apis/bun/Updater.md

@@ -0,0 +1,74 @@
+> Electrobun's built-in update mechanism for your app
+
+```typescript title="/src/bun/index.ts"
+import { Updator } from "electrobun/bun";
+```
+
+```json title="/electrobun.config"
+{
+ ...
+
+ "release": {
+    "bucketUrl": "https://s3-url"
+ }
+}
+```
+
+## Updating Electrobun Apps
+
+Electrobun ships with a built-in update mechanism that lets you ship updates to your app as small as 14KB so you can ship often. All you need to do is specify a url where your artifacts are stored in your `electrobun.config` file. A static file host like S3 + cloudfront is more than enough, most likely your app will stay well within the free tier.
+
+The electrobun `cli` will automatically generate an `artifacts` folder for each non-dev build (typically `canary` and `stable`), just upload those folders to S3 and set the bucketUrl, then use the api to check for and install updates when your app launches and on an interval or in response to a system tray menu to check for updates whenever a user initiates it.
+
+## Methods
+
+### getLocalInfo
+
+Get the local version info for display in your app or other logic. This will read the `version.json` file bundled with your app.
+
+```
+const localInfo = await Electrobun.Updator.getLocal;
+
+localInfo: {
+  version: string;
+  hash: string;
+  bucketUrl: string;
+  channel: string;
+  name: string;
+  identifier: string;
+};
+```
+
+### checkForUpdate
+
+Checks for an update by reading the update.json file at the url specified in the s3 subfolder for the current channel.
+
+```
+const updateInfo = await Electrobun.Updater.checkForUpdate();
+
+updateInfo: {
+  version: string;
+  hash: string;
+  updateAvailable: boolean;
+  updateReady: boolean;
+  error: string;
+};
+```
+
+### downloadUpdate
+
+This will initiate a process where it attempts to download patch files and apply them until the patched app matches the current version. If something goes wrong like there isn't a trail of patch files from the user's version to current it will download the latest full version of the app directly.
+
+```
+await Electrobun.Updater.downloadUpdate();
+```
+
+### applyUpdate
+
+Once the latest version is either patched or downloaded and ready to install you can call `applyUpdate` to quit the current app, replace it with the latest version, and relaunch.
+
+```
+if (Electrobun.Updater.updateInfo()?.updateReady) {
+  await Electrobun.Updater.applyUpdate();
+}
+```

package/documentation/docs/apis/bun/Utils.md

@@ -0,0 +1,51 @@
+> Various utilities for Electrobun apps.
+
+```
+import {Utils} from "electrobun/bun";
+
+```
+
+## moveToTrash
+
+Move a file or folder on your system to the Trash (recycle bin).
+
+:::warning
+On MacOS when you move something to trash from the finder you can open the trash can and see a "restore" button that will put the files/folders back where they were deleted from
+
+When using moveToTrash in Electrobun it moves it to the trash can but does not enable the "restore" button. To restore you will need to manually drag the files and folders back to their originating folder
+:::
+
+```
+Utils.moveToTrash(absolutePath)
+```
+
+## showItemInFolder
+
+Open the finder to the specified path
+
+```
+Utils.showItemInFolder(absolutePath)
+```
+
+## openFileDialog
+
+Open a file dialogue to let the user specify a file or folder and return the path to your app. Typically you would have an event handler in the browser context like clicking an "open" button, this would trigger an rpc call to bun, which would call `openFileDialog()` and then optionally pass the response back to the browser context via rpc after the user has made their selection
+
+```
+// To simplify this example we'll just show a dialogue after a 2 second timeout
+
+setTimeout(async () => {
+
+    const chosenPaths = await Utils.openFileDialog({
+        startingFolder: join(homedir(), "Desktop"),
+        allowedFileTypes: "*",
+        // allowedFileTypes: "png,jpg",
+        canChooseFiles: true,
+        canChooseDirectory: false,
+        allowsMultipleSelection: true,
+    });
+
+    console.log("chosen paths", chosenPaths);
+ }, 2000);
+
+```

package/documentation/docs/apis/bun/index.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+title: "Bun API"
+---
+
+These are apis you can use in the main bun process. Electrobun is just an npm dependency in your bun project. If you're just starting to look around take a look at the [Getting Started Guide](/docs/guides/Getting%20Started/) first to learn how to set up your first project.
+
+In Electrobun you simply write Typescript for the main process, when your app is all bundled up it will ship with a version of the bun runtime and it'll execute your main bun process with it, so any bun-compatible typescript is valid.
+
+You should explicitely import the `electrobun/bun` api for the main process:
+
+```typescript
+import Electrobun from "electrobun/bun";
+
+const win = new Electrobun.BrowserWindow(/*...*/);
+
+// or
+
+import {
+  BrowserWindow,
+  ApplicationMenu,
+  // other specified imports
+} from "electrobun/bun";
+
+const win = new BrowserWindow(/*...*/);
+```

package/documentation/docs/apis/cli/Electrobun.config.md

@@ -0,0 +1,97 @@
+## Electrobun Configuration (`electrobun.config`)
+
+This document provides detailed descriptions of the `electrobun.config` file, outlining how to configure your Electrobun application's build, deployment, and operational settings. This file tells the Electrobun CLI how to build and configure your app.
+
+```javascript
+{
+    // This section sets the core application metadata.
+    "app": {
+        // Your application name, spaces and some special characters are allowed.
+        // Your App distributables will use this and it's the name displayed in the
+        // Mac application menu when your app is focused.
+        "name": "Electrobun (Playground)",
+        // A unique identifier for the application, typically using reverse domain name
+        // notation. This should match the identifier for this app in your Apple Developer
+        // account
+        "identifier": "dev.electrobun.playground",
+        // The version of your app
+        "version": "0.0.1"
+    },
+    // Defines the settings and paths for the application's build process.
+    "build": {
+        // Configure the `bun build <entrypoint>` command that gets run
+        // to build the main bun process
+        "bun": {
+            // entrypoint should point to your typescript entrypoint for
+            // the main bun process
+            "entrypoint": "src/bun/index.ts",
+            // List any dependencies that should be treated as external
+            "external": []
+        },
+        // Configure the `bun build <entrypoint>` command that gets
+        // run to transpile typescript for the browser.
+        "views": {
+            // you can use any folder-safe name "mainview"
+            // will transpile the entrypoint into /Resources/app/views/mainview/index.js
+            // in the MacOS bundle
+            "mainview": {
+                "entrypoint": "src/mainview/index.ts",
+                "external": []
+            },
+            "myextension": {
+                "entrypoint": "src/myextension/preload.ts",
+                "external": []
+            }
+        },
+        // Copy files or folders from your src repo into the bundle. On MacOS
+        // the to paths are relative to the Resources/app/ folder. While the main
+        // bun process can access resources anywhere in the bundle BrowserViews
+        "copy": {
+            // can use the views:// scheme urls to load bundled resources.
+            // the views://mainview/index.html url maps to the views/mainview/index.html
+            "src/mainview/index.html": "views/mainview/index.html",
+            // It's useful to group your source code and bundled files by the name
+            // of the view they're for but that's not necessary, you can organize
+            // them however you like.
+            "src/mainview/index.css": "views/mainview/index.css"
+        },
+        // Mac specific configuration
+        "mac": {
+            // Fill a folder with different sized pngs that will be used as your App's icon.
+            // (https://developer.apple.com/documentation/xcode/configuring-your-app-icon)
+            // You can use a single 1024x1024 image or multiple images at different sizes. Name the folder icon.iconset and specify the path here.
+            "icons": "icon.iconset",
+            // Toggle code signing and notarization for non-dev builds on and off
+            "codesign": true,
+            "notarize": true,
+            // Specify a list of entitlements.
+
+            "entitlements": {
+                // The "com.apple.security.cs.allow-jit": true is enabled by default
+                // as it's required for hardened runtime macos applications, which is
+                // required for notarization.
+                // https://developer.apple.com/documentation/bundleresources/entitlements
+
+                // You will likely also have to enable some entitlements in your
+                // Apple Developer account for the corresponding app.
+            }
+        }
+    }
+    // Script hooks to run custom code during the build process. These are Typescript
+    // files executed with the bun runtime.
+    "scripts": {
+        // postBuild is executed after the mac app bundle is created, but before codeSigning.
+        // A good time to run tailwind, copy extra assets into the bundle, or other
+        // custom build steps.
+        "postBuild": "./buildScript.ts"
+    },
+    "release": {
+        // The only thing you need for updates to work is a static file host like S3.
+        // Specify the main bucket url. Electrobun will append the channel name internally
+        // to find the files it needs for updating. When building non-dev channels
+        // like canary and stable Electrobun will generate an artifacts folder
+        // with subfolders for each channel that you can upload direcly to the bucketUrl
+        "bucketUrl": "https://storage.googleapis.com/somebucket/bucket-subfolder/"
+    }
+}
+```

package/documentation/docs/apis/cli/cli args.md

@@ -0,0 +1,76 @@
+## CLI Tool Integration
+
+When you execute `bun install electrobun`, it installs the Electrobun CLI tool into the `node_modules/bin` folder. This setup enables your npm scripts to simply invoke `electrobun <args>` directly, utilizing the CLI seamlessly.
+
+The CLI leverages the `electrobun.config` file to manage commands and handle processes associated with building and running the application efficiently.
+
+### Installation
+
+To install the CLI tool, use the following command:
+
+```bash
+bun install electrobun
+```
+
+This command integrates the Electrobun CLI into your project's `node_modules` directory, making it accessible for npm scripts or direct command-line usage within the project environment.
+
+## Commands
+
+### init
+
+**Description**: Initializes a new Electrobun project structure.  
+**Status**: Not yet implemented.
+
+### build
+
+**Description**: Compiles the project according to configurations specified in the `electrobun.config`.
+
+### dev
+
+**Description**: Facilitates the project running in a development environment with live reloading, providing real-time feedback during development phases.
+
+### launcher
+
+**Description**: Manages application launching, adapting to different settings for development and production environments to ensure appropriate resource utilization.
+
+## Environments
+
+### env
+
+**Description**: Specifies the build environment, which can be set to `dev`, `canary`, or `stable`. Non-dev environments like `canary` and `stable` lead to the generation of an `artifacts` folder, containing all necessary distribution files. These files can be hosted on static file services for application distribution.
+
+## Example Build Scripts
+
+Incorporating Electrobun into your `package.json` scripts can streamline both development and build processes:
+
+```json
+"scripts": {
+"build:dev": "electrobun build",
+"start:dev": "electrobun dev",
+"dev": "bun install && npm run build:dev && npm run start:dev",
+"build:canary": "electrobun build env=canary",
+"build:stable": "electrobun build env=stable"
+}
+```
+
+## Development vs. Production Builds
+
+### Development Build (`dev`)
+
+In the development environment, the build configuration is designed to output logs and errors directly to the terminal window, ensuring immediate feedback and error reporting for enhanced developer intervention.
+
+### Canary and Stable Builds
+
+For environments marked as `canary` and `stable`, the CLI employs an optimized launcher binary better suited for production deployments. This launcher is optimized for performance and stability, ensuring efficient application execution.
+
+#### Canary
+
+Typically utilized for pre-release versions or testing new features in conditions that closely mimic production.
+
+#### Stable
+
+Used for releasing final, production-ready builds that are distributed to end-users.
+
+### Optimized Launcher Binary
+
+The optimized launcher binary is not merely for launching the application; it is also engineered to handle updates, system integration, and other critical runtime operations more reliably than the development-based launcher. This optimization ensures peak performance in environments where direct developer oversight is minimized.

package/documentation/docs/guides/Architecture/Events.md

@@ -0,0 +1,19 @@
+`Electrobun.events` is a custom event emitter in the [Bun api](/docs/apis/bun/Events).
+
+Some events happen entirely within bun process, some happen in a BrowserView and make their way through zig into bun, and others originate in the native code layer (objc on MacOS) through zig into bun and then back to objc. Let's look at how the 'will-navigate' event works.
+
+1. Objc event is fired on a BrowserView and handled by zig
+1. zig sends json rpc request to decide navigation over the main bun named pipe with a url and a webviewid
+1. zig pauses the main thread simulating a promise-like behaviour while listening on a separate named pipe listener thread
+1. bun parses the json rpc and sees it's a 'will navigate' request
+1. bun creates a new Electrobun.events.webview.willNavigate event with the data (url and webviewid).
+1. bun then emits the event globally `('will-navigate')` that could be listened to with `Electrobun.events.on('will-navigate', handlerFn)`
+1. bun then passes the same event to a specific event `('will-navigate-<webviewId>'` eg: `will-navigate-1` for the webview with id 1).
+1. you could also listen to this globally via `Electrobun.events.on('will-navigate-1', handlerFn)` if you wanted to. Since ids are incremented deterministically this allows for some interesting patterns like handling navigation for the first window created.
+1. you can also listen on the webview with `myWebview.on('will-navigate', handlerFn)`. Webview extends a "event emitter class' that essentially provides `on`, `off`, `appendEventListener`, etc. but instead of being an event listener it modifies the event name to include its id, and subscribes the handler to the main event emitter. So it basically does `Electrobun.events.on('will-navigate-1')` for you without you having to think about the webview's id and providing other lifecycle handling for you.
+1. the event object has a `response` getter/setter and a `clearResponse` method that allows any handler to respond with a value as well as a `responseWasSet` flag. so in any handler you can both check if another handler set a response, and if you want override or modify the response.
+1. the response is then serialized as an rpc response and sent back to zig which is listening on another thread, zig unfreezes the main thread returning the value to objc.
+
+:::note
+Global events are always called before specific events.
+:::

package/documentation/docs/guides/Architecture/IPC and Isolation.md

@@ -0,0 +1,20 @@
+## IPC
+
+Bun spawns the zig bindings as a separate process. GUI applications require the main thread of a process to run a blocking event loop, so this is separate to the bun process.
+
+There are two categories of named pipes for IPC.
+
+1. bun \<-> zig. This is used for communicating with zig. ie: creating windows and webviews, and binding native handlers that need a response from bun like will-navigate.
+2. bun \<-> webview. Each webview gets its own pair of named pipes for communicating with bun.
+
+### bun \<-> zig
+
+There is a primary named pipe used to send rpc-anywhere encoded json messages between bun and zig on this pipe. There is a minimal zig implementation of rpc-anywhere that also implements a promise-like api in zig (freezes the main thread while waiting and unfreezes it returning a value).
+
+In order to simulate something promise-like in zig we send the request to bun and pause the main zig thread. We have a pipe listener on another thread waiting for a reply, when it gets a response it unfreezes the main thread and returns the value back to the function that was waiting.
+
+In general (whether receiving rpc requests, responses, and messages from bun) there is a performant loop in zig listening on another thread. We use native functions to group named pipe into a kqueue and let the process subscribe to events that continue the loop so it isn't busy waiting. For any gui-related rpc whe have to pass messages to the main thread to be executed.
+
+### bun \<-> webview
+
+When creating a webview a new named pipe pair is created. zig creates a bridge between the named pipe and the webview that passes anything between the named pipe and the webview so it's never deserialized in zig. We also have code in the webview for handling the other end of the RPC anywhere bun\<->webview communication. By using a named pipe for each webview we eliminate the need for the zig bridge having to double wrap or partially de/serialize json messages to route them to the right webview which makes bun \<-> webview communciation significantly faster.

package/documentation/docs/guides/Architecture/Overview.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 1
+---
+
+## Application Bundles
+
+### MacOS
+
+#### Your Installed App
+
+On MacOS an application bundle is really just a folder with a .app file extension. The key subfolders inside are
+
+```
+// electrobun places several binaries here
+/Contents/MacOS
+
+// An optimized zig implementation of bspatch used to generate and apply diffs during updates
+/Contents/MacOS/bspatch
+
+// The bun runtime
+/Contents/MacOS/bun
+
+// An optimized zig binary that typically just calls `bun index.js` with the included runtime
+// to run your compiled bun entrypoint file.
+/Contents/MacOS/launcher
+
+// A folder containing native code layer for the platform, on MacOS this these are
+// objc binaries for interfacing with MacOS apis like NSWindow and WKWebkit
+/Contents/MacOS/native/
+
+// electrobun compiles your application's custom code here
+/Contents/MacOS/Resources
+
+// Your application icons
+/Contents/MacOS/Resources/AppIcon.icns
+
+// Local version info that `Electrobun.Updater` reads
+/Contents/MacOS/Resources/version.json
+
+// Folder containing the bundled javascript code for the main bun process.
+// Use electrobun.config to tell Electrobun where your ts entrypoing is and
+// define external dependencies
+/Contents/MacOS/Resources/app/bun/
+
+// This is where your views defined in electrobun.config are transpiled to
+// Browserviews can also use the views:// url schema anywhere urls are loaded
+// to load bundled static content from here.
+/Contents/MacOS/Resources/app/views
+```
+
+#### IPC
+
+In order to communicate between bun, zig, and browser contexts Electrobun has several mechanisms for establishing IPC between the processes involved. For the most part Electrobun uses efficient named pipes and serializes json rpc over the pipes.
+
+#### Self-Extracting Bundle
+
+Because zip file compression is not the best and we want apps you build with Electrobun to be as tiny as possible Electron automatically bundles your application into a self-extracting bundle. Electrobun takes your entire app bundle, tars it, compresses it with zlib which is fast best-in-class modern compression and creates a second app bundle for distribution.
+
+:::info
+The current Electrobun Playground app is **50.4MB** in size (most of this is the bun runtime), but when compressed and distributed as the self-extracting bundle it's only **13.1MB which is almost 5 times smaller**.
+
+_Meaning almost 5 times as many users can download your app for the same cost in Storage and Network fees._
+:::
+
+The self-extracting bundle looks like this:
+
+```
+// This is different from the regular launcher binary. It's a zig binary that uses zlip to decompress your actual app bundle
+/Contents/MacOS/launcher
+
+// App icons are actually stored again so the self-extractor looks just like your extracted bundled app.
+/Contents/Resources/AppIcons.icns
+
+// Your actual app bundled, tarred, and compressed with the name set to the hash
+/Contents/Resources/23fajlkj2.tar.zst
+```
+
+A user can install the self-extracting bundle the same as any other application in the `/Applications/` folder or run it from any folder on your machine. When your end-user double clicks to open it, it will transparently self-extract and replace itself with your full application and then launch the full application. To your user it just looks like the first time opening your app takes 1 or 2 seconds longer.
+
+The self-extraction process only happens on first install and is entirely local and self-contained using only a designated application support folder for your app for the extraction and verification.
+
+#### DMG
+
+Finally electrobun will automatically generate a DMG with the self-extracting bundle inside.
+
+## Code Signing and Notarization
+
+Electrobun will automatically code sign and notarize your application for you.
+
+### MacOS
+
+There is a prerequesite to register for an Apple Developer account and create an app id as well as download your code signing certificate. We'll have a guide that walks you through this process. There is no need to have any private keys in your code repo but you do need to set `codesigning` and `notarization` flags to `true` in your `electrobun.config` file and make some credentials available in your env.
+
+On MacOS Electrobun will code sign and notarize both your app bundle **and** the self-extracting bundle so your end-users can be confident that what their installing is legitimately from you and has been scanned by Apple.
+
+While code signing is generally very fast, notarization requires uploading a zip file to Apple's servers and waiting for them to scan and verify your app's code which typically takes about 1-2 minutes. The notarization is then stapled to your app bundle.
+
+Because notarization can take time, in cases where a bug only exists on non-dev builds you can simply turn off code signing and/or notarization in your `electrobun.config` while debugging to speed up the build process.
+
+Any notarization issues will be shown to you in the terminal so you can address them. This typically involves setting certain entitlements for your application so that your app declares what it uses to Apple and your end-users.
+
+## Updating
+
+Electrobun has a [built-in update mechanism](/docs/apis/bun/Updater) that optimizes updates for file-size and efficiency.
+
+:::info
+Ship updates to your users as small as 14KB. This lets your ship often without paying huge storage and network fees.
+
+No server required, all you need is a static file host like S3 which you can put behind a CDN like Cloudfront. Most apps will fall well within AWS's free tier even if you ship updates often to many users.
+:::
+
+### How does it work
+
+Using the [Electrobun Updater api](/docs/apis/bun/Updater) you can check for updates and automatically download, and install them. The flow looks something like:
+
+1. Check the local version.json hash against the hosted update.json hash of the latest version.
+2. If it's different download the tiny patch file that matches the hash you have (generated with BSDIFF) and apply it to the current bundle.
+3. Generate a hash of the patched bundle. If it matches the latest hash then replace the running application with the latest version of the app and relaunch (you can control when with the api and let the user trigger this manually when they're ready)
+4. If the hash does not match the latest look for another patch file and keep patching until it does.
+5. If for some reason the algorithm can't patch its way to the latest version it will download a zlib compressed bundle from your static host and complete the update that way.
+
+:::info
+Whenever you build a non-dev build of your app the electrobun cli will automatically generate a patch from the current hosted version to the newly built version.
+
+It's completely up to you how many patches you make available on your static host.
+:::
+
+## CLI and development builds
+
+The Electrobun cli is automatically installed locally to your project when you `bun install electrobun`. You can then add npm scripts and an `electrobun.config` file to build your app.
+
+### Development Builds
+
+When building a `dev` build of your app instead of the optimized `launcher` binary the cli uses a special dev launcher binary which routes any bun, zig, and native output to your terminal.
+
+Dev builds are not meant to be distributed and so the cli does not generate artifacts for dev builds.
+
+### Distribution
+
+Whne building `canary` and `stable` builds of your app Electrobun will generate an `artifacts` folder that contains everything you need to upload to a static host for distribution and updates.

package/documentation/docs/guides/Architecture/Updates.md

@@ -0,0 +1,7 @@
+## Introduction
+
+We've implemented a batteries included update mechanism. All you need is to bring your own static file host like S3.
+
+- [Update API](/docs/apis/bun/Updater) to check for, download, and update your apps.
+- [CLI](/docs/apis/cli/cli%20args) to build your app bundle, codesign, and generate artifacts.
+- A custom BSDIFF implementation in zig that lets you distribute updates as small as 14KB

package/documentation/docs/guides/Architecture/Webview Tag.md

@@ -0,0 +1,5 @@
+isolated
+not deprecated like electron's webview tag
+`<electrobun-webview>`
+
+how it works as a layer above the window

package/documentation/docs/guides/Compatability.md

@@ -0,0 +1,8 @@
+## Dependencies and Versions
+
+| Dependency                 | Version     | Notes                                                     |
+| -------------------------- | ----------- | --------------------------------------------------------- |
+| Bun                        | 1.8         | We will be upgrading to the latest version of bun soon    |
+| Zig                        | 0.8         | We will be upgrading to zig 0.13.0 soon                   |
+| Building Electrobun apps   | MacOS (arm) | No near-term plans to support building on other platforms |
+| Distribute Electrobun apps | MacOS (arm) | Linux and Windows support coming soon                     |