electrobun 0.0.2 → 0.0.3

package/.colab.json

@@ -0,0 +1 @@
+{"v":1,"name":"electrobun","type":"project","url":"","icon":"","config":{}}

package/README.md

@@ -13,6 +13,8 @@
 Electrobun aims to be a complete **solution-in-a-box** for building, updating, and shipping ultra fast, tiny, and cross-platform desktop applications written in Typescript.
 Under the hood it uses <a href="https://bun.sh">bun</a> to execute the main process and to bundle webview typescript, and has native bindings written in <a href="https://ziglang.org/">zig</a>.
 
+Visit <a href="https://www.electrobun.dev/">Electrobun.dev</a> to see api documentation, guides, and more.
+
 **Project Goals**
 
 - Write typescript for the main process and webviews without having to think about it.
@@ -23,7 +25,7 @@ Under the hood it uses <a href="https://bun.sh">bun</a> to execute the main proc
 
 ## Architecture
 
-Read about how Electrobun is designed, and why, in our <a href="https://github.com/blackboardsh/electrobun/tree/main/docs/architecture.md">architecture docs</a>.
+Read about how Electrobun is designed, and why, in our <a href="https://www.electrobun.dev/docs/guides/Architecture/Overview">architecture docs</a>.
 
 ## Roadmap
 
@@ -31,17 +33,17 @@ See the detailed <a href="https://github.com/blackboardsh/electrobun/issues/2">d
 
 **High level roadmap**
 
-|     | Milestones            | Description                                                                                                                               |
-| :-- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
-| ✅  | Core Architecture     | Ship a working proof of concept with most of the core architecture wired up                                                               |
-| ✅  | Packaging and signing | Packaging and code signing for MacOS                                                                                                      |
-| ✅  | Shipping updates      | Integrated auto-updator                                                                                                                   |
-| ✅  | Webview Tag           | Cross browser electrobun implementation of the <webview> tag that electron has, for isolated nested webviews                              |
-| ✅  | Port Eggbun           | Harden implementation and enough electron parity to migrate <a href="https://Eggbun.sh">https://Eggbun.sh</a> from Electron to Electrobun |
-|     | Custom Web Runtime    | Optionally use a cross-platform web runtime (Chromium) instead of the system's native webview                                             |
-|     | Intel Mac Builds      | build on and distribute to intel macs                                                                                                     |
-|     | API Parity            | Accelerate development of Electrobun apis and native integrations to enable apps to migrate from Electron and Tauri                       |
-|     | Windows support       | build for and distribute to Windows                                                                                                       |
+|     | Milestones            | Description                                                                                                                             |
+| :-- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| ✅  | Core Architecture     | Ship a working proof of concept with most of the core architecture wired up                                                             |
+| ✅  | Packaging and signing | Packaging and code signing for MacOS                                                                                                    |
+| ✅  | Shipping updates      | Integrated auto-updator                                                                                                                 |
+| ✅  | Webview Tag           | Cross browser electrobun implementation of the <webview> tag that electron has, for isolated nested webviews                            |
+| ✅  | Port co(lab)          | Harden implementation and enough electron parity to migrate <a href="https://colab.sh">https://colab.sh</a> from Electron to Electrobun |
+|     | Custom Web Runtime    | Optionally use a cross-platform web runtime (Chromium) instead of the system's native webview                                           |
+|     | Intel Mac Builds      | build on and distribute to intel macs                                                                                                   |
+|     | API Parity            | Accelerate development of Electrobun apis and native integrations to enable apps to migrate from Electron and Tauri                     |
+|     | Windows support       | build for and distribute to Windows                                                                                                     |
 
 ## Contributing
 

package/docs-old/architecture.md

@@ -0,0 +1,46 @@
+## Project Structure
+
+<pre>
+/src - electrobun's src code
+/src/browser - typescript compiles to the in-webview electrobun javascript api
+/src/bun - typescript compiles to the main process javascript api
+/src/objc - c-abi wrapped objective c, compiled to a static lib
+/src/zig - zig native bindings, compiles to the native renderer process. 
+/src/zig/build - where the compiled src/objc ends up so zig can see it and embed it
+/src/cli - a cli for building and running developer apps, it reads electrobun.config files
+/example - Interactive example using the library. 
+</pre>
+
+## Building
+
+Tldr;
+
+- clang to compile objective c wrappers for macos in src/objc (.m files) into a static library, since objc is a superset of c the wrappers have intentionally been designed with c-compatible wrappers/apis
+- zig is built with zig's build system. must specify zig equivalent types for objc wrappers to map memory
+- electrobun in-webview-api that runs in all frames of the webviews is built using bun with a browser target
+- the in-webview-api and objc are built into src/zig/build/ so zig can see it
+
+## Working on Electrobun
+
+There are some npm scripts to facilitate building everything from the objc, zig, bundling webview api, transpiling the bun api and so an, as well as building the example app and executing it.
+
+The example app is meant to be an interactive example of Electrobun's functionality, it's useful when implementing new functionality in any part of Electrobun to have everything rebuilt so you can interact with it in the example app which then doubles as a demo app for developers wanting to explore what Electrobun can do.
+
+You currently need zig installed globally, and to be on an ARM mac. I dunno if you have to install xcode or xcode tools to get clang on your system. Will iron out a better dev flow in the future.
+
+For now you can simply
+
+1. clone the repo
+2. in the repo root run `bun run dev:example`
+
+If you take a look at the repo's package.json as well as example app's package.json and electrobun.config you'll get a better sense of what's happening for each step.
+
+## How Developer apps are built
+
+> Note: in order for an application to get keyboard focus on macos you can't run it as a subprocess of the terminal which greedily steals keyboard input, so it needs to be built into an app bundle.
+
+This part is wip, but currently we create a minimal macos app bundle and execute it. There is a launcher shell script which calls bun with your typescript. It configures stdout/err to write to a named pipe log file and starts listening to it so you get the output in the terminal.
+
+You can cmd+c to stop that, but for now to quit your running app you have to close the window.
+
+A better dev flow, as well as installing bun to a global location outside the app bundle is being actively developed.

package/documentation/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

package/documentation/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

package/documentation/blog/2024-08-20-electrobun.md

@@ -0,0 +1,22 @@
+---
+slug: electrobun
+title: Meet Electrobun
+authors: yoav
+tags: [electrobun]
+---
+
+Earlier this year I was just wrapping up a beta of [co(lab)](https://colab.sh) a hybrid web browser + code editor for deep work. Mostly written in Typescript, SolidJS, and Tailwid. I'd been building it in Electron and after figuring out how to get code signing and notarization working, how to distribute it and so on I ended up with a distributable that was 80MB+ compressed.
+
+I'd added an update mechanism as well (from yet another separate project) that was supposed to be the gold standard that uses blockmap technology. This segments your next version into blocks and lets you only download the blocks you need when an update is available. It does this on the uncompressed version of your app which in my case was over 150MB+. However if you happen to make a change that affects a part of your app at the beginning, even if it's only a single character, then all the blocks will shift with different checksums meaning each of your users will likely have to download almost 150MB.
+
+I started multiplying 150MB by the number of users and multiplying that by the number of times I wanted to ship an update. I wanted to ship like the web—continuously—but the sheer amount of data I would have to distribute with every small app change was obsene. I'm bootstrapping [Blackboard](https://blackboard.sh) and I found myself having to hold back on updates and ship less frequently to avoid spending hundreds of dollars in S3/Cloudfront bandwith costs.
+
+I had been kicking around the idea of building an Electron alternative with [Bun](https://bun.sh) since long before Bun hit their 1.0.0 and having to second guess how often I ship while trying to bootstrap a startup lab was just the motivation I needed.
+
+So I picked up zig, C, C++, and Objc and got to work. Once I'd built enough functionality into Electrobun I ported co(lab) from Electron to Electrobun. The compressed distributable for the Electrobun version of co(lab) is only 18MB. That's more than a 4x reduction, but I wasn't satisfied with that. I ported BSDIFF from C to zig, optimizing it for speed with SIMD and some other tricks I came up with and added a built-in update mechanism in Electrobun. Now when users download updates they only need to download a patch file. A small copy change now generates a 14KB patch file. So from up to 150MB with Electron's blockmaps to 14KB patch file that's a 95% reduction in the size of updates.
+
+After 20 years at small startups and unicorns, and spending so much time earlier in my career with Adobe Flex/AIR, being able to ship desktop apps in Typescript with a batteries included framework at the speed of the web is just the thing I've always wanted.
+
+Next steps for Electrobun are to upgrade the Bun and Zig versions, support distributing your apps to Windows and Linux, and enable more functionality like shipping a cross-platform web renderer instead of relying on the system's webview.
+
+Technically Electrobun is the first thing I'm shipping from my startup lab [Blackboard](https://blackboard.sh). I hope you like it as much as I do.

package/documentation/blog/authors.yml

@@ -0,0 +1,8 @@
+yoav:
+  name: Yoav
+  title: Founder @Blackboard Technologies Inc.
+  url: https://yoav.codes
+  image_url: https://avatars.githubusercontent.com/u/75102186
+  socials:
+    x: YoavCodes
+    github: YoavCodes

package/documentation/docs/apis/Application Icons.md

@@ -0,0 +1,9 @@
+## Introduction
+
+Configure your Applications icons. These icons are used for the icon of your app in the app switcher and in the file system like on your Desktop or in the Applications folder.
+
+### MacOS
+
+The default location for the icon folder is in the root of your repo in a folder named `icon.iconset`. At minimum you should add a 1024x1024 png icon, but you can add other sizes as well for more control. [Read here](https://developer.apple.com/documentation/xcode/configuring-your-app-icon) for more details.
+
+You can specify a custom path for the `icon.iconset` folder in your [electrobun.config](/docs/apis/cli/Electrobun.config) file.

package/documentation/docs/apis/Bundled Assets.md

@@ -0,0 +1,95 @@
+## Bundling Static Assets in your app
+
+The `views://` schema in Electrobun provides a robust method for handling static assets, ensuring they are securely and efficiently managed within the application's bundle. This documentation explains how to use this schema to set URLs for new `BrowserWindow` instances, incorporate CSS and JavaScript into HTML, and bundle static assets via the `electrobun.config`.
+
+### Overview of `views://` Schema
+
+The `views://` schema is a custom protocol used in Electrobun to reference assets and files within the application bundle. This schema allows for a clean separation of application logic and resources, ensuring that static assets like HTML, CSS, and JavaScript files are encapsulated within specified views or components.
+
+You can think of the `views://` schema as an alternative to `https://` so it can be used in the context of BrowserViews anywhere a normal url can be used and electrobun will securely map those paths to the static asset folder in your application bundle.
+
+### Using `views://` in BrowserWindow URLs
+
+You can use the `views://` schema to set the URL for a new `BrowserWindow()` in Electrobun. This method simplifies referencing bundled assets and enhances security by encapsulating resources.
+
+#### Example Usage
+
+```javascript
+const { BrowserWindow } = require("electrobun");
+
+const mainWindow = new BrowserWindow({
+  width: 800,
+  height: 600,
+  title: "Main Window",
+});
+
+mainWindow.loadURL("views://mainview/index.html");
+```
+
+In this example, `mainWindow` loads an HTML file located at `views://mainview/index.html`. This URL points to the `index.html` file within the `mainview` directory defined in the `electrobun.config`.
+
+### Incorporating CSS and JavaScript
+
+Using the `views://` schema, CSS and JavaScript files can be loaded directly within an HTML file bundled in the application.
+
+#### HTML Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Sample Page</title>
+    <link rel="stylesheet" href="views://mainview/style.css" />
+    <script src="views://mainview/script.js"></script>
+    <style>
+      div {
+        background: url(views://mainview/somebg.png);
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Welcome to Electrobun</h1>
+  </body>
+</html>
+```
+
+Here, `style.css` and `script.js` are loaded using the `views://` schema, pointing directly to the assets within the `mainview` directory.
+
+You can also see a `views://` url used directly in css just like you'd use any `https://` url.
+
+### Bundling Static Assets via `electrobun.config`
+
+The `electrobun.config` file can be configured to bundle and manage static assets using the `views://` schema. This configuration ensures all necessary assets are included during the build process and correctly referenced within the application.
+
+:::info
+The property name for each view, in this case `mainview` can be anything you'd like. And you can specify as many views as you'd like. This maps directly to the path you would use when referencing a file so you can organize your assets.
+:::
+
+#### Configuration Example
+
+```json
+"build": {
+    "views": {
+        "mainview": {
+            "entrypoint": "src/mainview/index.ts",
+            "external": []
+        }
+    },
+    "copy": {
+        "src/mainview/index.html": "views/mainview/index.html",
+        "src/mainview/style.css": "views/mainview/style.css",
+        "src/mainview/script.js": "views/mainview/script.js"
+    }
+}
+```
+
+:::note
+Notice that in the "copy" section the destination is `views/mainview/` which maps to the url `views://mainview/`.
+:::
+
+In the `electrobun.config`, the `views` section defines entry points for scripts, while the `copy` section specifies static assets like HTML, CSS, and JavaScript files to be copied to their respective directories in the build output.
+
+### Summary
+
+The `views://` schema in Electrobun provides a structured and secure way to manage and reference static assets within your applications. By configuring the `electrobun.config` appropriately and using the schema within your application code, you can ensure a clean, organized, and encapsulated asset management system.

package/documentation/docs/apis/browser/DraggableRegions.md

@@ -0,0 +1,36 @@
+> Configure an html element to function as a draggable region allowing you to move the native application window by clicking and dragging on the element.
+
+When building desktop apps with Electrobun a common pattern is to create a frameless window, sometimes with the traffic light (close, minimize, maximize) buttons overlayed with the html content. You would then use html and css to create a top-bar and set that top-bar to be a draggable region allowing you full control over the style of the window.
+
+You can set any html element to be a draggable region.
+
+### Step 1: Instantiate the Electroview class
+
+```typescript title="/src/mainview/index.ts"
+import { Electroview } from "electrobun/view";
+
+const electrobun = new Electroview();
+```
+
+### Step 2: Add the draggable region css class
+
+Insantiating `Electroview()` will configure any element with the `electrobun-webkit-app-region-drag` css class as a draggable area.
+
+```html title="/src/mainview/index.html"
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Electrobun app</title>
+    <script src="views://mainview/index.js"></script>
+    <link rel="stylesheet" href="views://mainview/index.css" />
+  </head>
+  <body>
+    <div class="electrobun-webkit-app-region-drag">
+      click here and drag to move this window
+    </div>
+    <h1>hi World</h1>
+  </body>
+</html>
+```

package/documentation/docs/apis/browser/Electrobun Webview Tag.md

@@ -0,0 +1,200 @@
+## Introduction
+
+Electrobun's custom webview tag implementation behaves similarly to an enhanced iframe, but with key differences in capabilities and isolation. It serves as a positional anchor within the DOM, communicating with a Zig backend to manage a distinct, isolated BrowserView. This separation ensures full content isolation from the host webview, enhancing both security and performance.
+
+## Basic Usage
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>webview tag test</title>
+    <script src="views://webviewtag/index.js"></script>
+  </head>
+
+  <body>
+    <electrobun-webview src="https://electrobun.dev"></electrobun-webview>
+  </body>
+</html>
+```
+
+## Compatability
+
+The Electrobun webview tag integrates seamlessly with any reactive JavaScript framework, such as React or SolidJS, allowing for dynamic interactions and updates without disrupting the isolation of the webview's contents.
+
+The way the implementation currently works, the html element is just a positional anchor that reports its position and relays events to zig which manages a completely separate BrowserView and overlays it at the same coordinates within the window.
+
+## How is this difffernt to Electron's webview tag
+
+### Chrome plans to deprecate their webviewtag
+
+Electron's webview tag is based on a Chrome feature/api designed for Chrome apps which has been deprecated since 2020. You can read about that on [Electron's Github](https://github.com/electron/electron/issues/34356) and in [Chrome's developer docs](https://developer.chrome.com/docs/apps/reference/webviewTag). The warning declares it "remains supported for Enterprise and Education customers on ChromeOS until at least Jan 2025" which is fast approaching.
+
+It's unknown what Electron will do when and if Chrome actually removes webview tag support from Chrome.
+
+Unlike Electron's reliance on Chrome's now-deprecated webview tag, Electrobun introduces its own robust implementation that does not depend on Chrome's lifecycle. This independence ensures longevity and stability for applications using Electrobun's framework, even as Chrome phases out its support.
+
+### Electrobun's webview tag is a separate layer
+
+Because Electrobun's webview tag implementation uses a div anchor and then positions a separate isolated BrowserView above the parent BrowserView there are some interesting edge cases where you may want to click on the parent document or do things within the parent DOM, so Electrobun provides various special methods for handling those situations. For example ways to mirror a screenshot of the webview tag's contents to the host's anchor and hide it or stream an image of the contents.
+
+## Properties and Attributes
+
+### src
+
+**Type**: `string`  
+**Description**: URL of the web page to load in the webview.
+
+### html
+
+**Type**: `string`  
+**Description**: HTML content to be directly loaded into the webview, useful for dynamic content generation.
+
+### preload
+
+**Type**: `string`  
+**Description**: Path to a script that should be preloaded before any other scripts run in the webview.
+
+### partition
+
+**Type**: `string`  
+**Description**: Sets a partition to provide separate storage for different sessions, useful in multi-user applications.
+
+### transparent
+
+**Type**: `boolean`  
+**Description**: When set to true, makes the webview transparent, allowing underlying elements to be visible.
+
+### passthroughEnabled
+
+**Type**: `boolean`  
+**Description**: Enables or disables mouse and touch events to pass through to underlying elements.
+
+### hidden
+
+**Type**: `boolean`  
+**Description**: Controls the visibility of the webview.
+
+### delegateMode
+
+**Type**: `boolean`  
+**Description**: Activates a mode where input is delegated to the webview even when it is visually mirrored to another element.
+
+### hiddenMirrorMode
+
+**Type**: `boolean`  
+**Description**: Enables a mode where the webview is hidden and mirrored, allowing smooth interactions during transitions or animations.
+
+### wasZeroRect
+
+**Type**: `boolean`  
+**Description**: Indicates if the webview had zero dimensions at any point, used internally to optimize rendering and updates.
+
+### webviewId
+
+**Type**: `number`
+**Description**: A unique identifier for the webview instance, automatically managed by the system.
+
+### id
+
+**Type**: `string`  
+**Description**: The DOM ID for the webview element, automatically set to ensure uniqueness.
+
+## Methods
+
+### callAsyncJavaScript
+
+**Parameters**: `{ script: string }`  
+**Returns**: `Promise`
+**Description**: Executes JavaScript code asynchronously within the webview and returns a promise with the result.
+
+### canGoBack
+
+**Returns**: `Promise<boolean>`
+**Description**: Determines if the webview can navigate backward.
+
+### canGoForward
+
+**Returns**: `Promise<boolean>`
+**Description**: Determines if the webview can navigate forward.
+
+### on
+
+**Parameters**: `event: WebviewEventTypes, listener: () => {}`  
+**Description**: Attach event listeners for webview-specific events such as navigation and loading.
+
+### off
+
+**Parameters**: `event: WebviewEventTypes, listener: () => {}`  
+**Description**: Detach event listeners for webview-specific events.
+
+### syncDimensions
+
+**Parameters**: `force: boolean = false`  
+**Description**: Synchronizes the dimensions and position of the webview with its anchor element in the DOM, optionally forcing an update.
+
+### goBack
+
+**Description**: Navigates the webview back to the previous page.
+
+### goForward
+
+**Description**: Navigates the webview forward to the next page.
+
+### reload
+
+**Description**: Reloads the current content in the webview.
+
+### loadURL
+
+**Parameters**: `url: string`  
+**Description**: Loads a given URL into the webview, similar to setting the `src` attribute.
+
+### syncScreenshot
+
+**Parameters**: `callback?: () => void`  
+**Description**: Captures and synchronizes a screenshot of the webview's contents, useful for visual mirroring.
+
+### startMirroring
+
+**Parameters**: `frameRate: number = DEFAULT_FRAME_RATE`  
+**Description**: Starts mirroring the webview's contents at a specified frame rate, optimizing for performance versus visual fidelity.
+
+### stopMirroring
+
+**Description**: Stops mirroring the webview's contents.
+
+### clearScreenImage
+
+**Description**: Clears any images set as the webview anchor's background, typically used in conjunction with transparency and mirroring modes.
+
+### tryClearScreenImage
+
+**Description**: Attempts to clear the background image of the webview anchor if conditions are met.
+
+### toggleTransparent
+
+**Parameters**: `transparent?: boolean, bypassState?: boolean`  
+**Description**: Toggles the transparency state of the webview.
+
+### togglePassthrough
+
+**Parameters**: `enablePassthrough?: boolean, bypassState?: boolean`  
+**Description**: Toggles the ability for mouse and touch events to pass through the webview.
+
+### toggleHidden
+
+**Parameters**: `hidden?: boolean, bypassState?: boolean`  
+**Description**: Toggles the visibility of the webview.
+
+### toggleDelegateMode
+
+**Parameters**: `delegateMode?: boolean`  
+**Description**: Toggles the delegate mode for input events within the webview.
+
+### toggleHiddenMirrorMode
+
+**Parameters**: `force: boolean`  
+**Description**: Toggles the hidden mirror mode, optimizing interaction during transitions or animations.