electrobun 0.0.2 → 0.0.3

package/documentation/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.5.1",
+    "@docusaurus/preset-classic": "3.5.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.5.1",
+    "@docusaurus/tsconfig": "3.5.1",
+    "@docusaurus/types": "3.5.1",
+    "typescript": "~5.5.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

package/documentation/sidebars.ts

@@ -0,0 +1,32 @@
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  guidesSidebar: [{ type: "autogenerated", dirName: "guides" }],
+  apiSidebar: [{ type: "autogenerated", dirName: "apis" }],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

package/documentation/src/components/HomepageFeatures/index.tsx

@@ -0,0 +1,70 @@
+import clsx from 'clsx';
+import Heading from '@theme/Heading';
+import styles from './styles.module.css';
+
+type FeatureItem = {
+  title: string;
+  Svg: React.ComponentType<React.ComponentProps<'svg'>>;
+  description: JSX.Element;
+};
+
+const FeatureList: FeatureItem[] = [
+  {
+    title: 'Easy to Use',
+    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
+    description: (
+      <>
+        Docusaurus was designed from the ground up to be easily installed and
+        used to get your website up and running quickly.
+      </>
+    ),
+  },
+  {
+    title: 'Focus on What Matters',
+    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
+    description: (
+      <>
+        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
+        ahead and move your docs into the <code>docs</code> directory.
+      </>
+    ),
+  },
+  {
+    title: 'Powered by React',
+    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+    description: (
+      <>
+        Extend or customize your website layout by reusing React. Docusaurus can
+        be extended while reusing the same header and footer.
+      </>
+    ),
+  },
+];
+
+function Feature({title, Svg, description}: FeatureItem) {
+  return (
+    <div className={clsx('col col--4')}>
+      <div className="text--center">
+        <Svg className={styles.featureSvg} role="img" />
+      </div>
+      <div className="text--center padding-horiz--md">
+        <Heading as="h3">{title}</Heading>
+        <p>{description}</p>
+      </div>
+    </div>
+  );
+}
+
+export default function HomepageFeatures(): JSX.Element {
+  return (
+    <section className={styles.features}>
+      <div className="container">
+        <div className="row">
+          {FeatureList.map((props, idx) => (
+            <Feature key={idx} {...props} />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

package/documentation/src/components/HomepageFeatures/styles.module.css

@@ -0,0 +1,11 @@
+.features {
+  display: flex;
+  align-items: center;
+  padding: 2rem 0;
+  width: 100%;
+}
+
+.featureSvg {
+  height: 200px;
+  width: 200px;
+}

package/documentation/src/css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

package/documentation/src/pages/index.module.css

@@ -0,0 +1,23 @@
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 996px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}

package/documentation/src/pages/index.tsx

@@ -0,0 +1,137 @@
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
+import Layout from "@theme/Layout";
+
+export default function Home(): JSX.Element {
+  const { siteConfig } = useDocusaurusContext();
+  return (
+    <Layout
+      title={`Hello from ${siteConfig.title}`}
+      description="Description will go into a meta tag in <head />"
+    >
+      <main
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignSelf: "center",
+          width: "100vw",
+          background: "#111",
+        }}
+      >
+        <div
+          style={{
+            alignSelf: "center",
+            textAlign: "center",
+
+            color: "#fefefe",
+            padding: 20,
+            maxWidth: 800,
+          }}
+        >
+          <h1 style={{ fontSize: "4rem" }}>Electrobun</h1>
+          <div style={{}}>
+            <p>
+              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.
+            </p>
+            <img src="/img/electrobun-logo-256.png"></img>
+            <p>
+              Under the hood it uses bun to execute the main process and to
+              bundle webview typescript, and has native bindings written in zig.
+            </p>
+          </div>
+          <hr style={{ margin: "35px 0" }} />
+          <h2>Install Electrobun v0.1.0</h2>
+          <div
+            style={{
+              display: "flex",
+              border: "4px solid #e263a9",
+              borderRadius: 8,
+              padding: 8,
+              background: "#000",
+              fontSize: 20,
+              fontWeight: "bold",
+              width: 300,
+              alignSelf: "center",
+              margin: "auto",
+            }}
+          >
+            <span style={{ color: "#777", padding: "0 8px" }}>$</span>
+            <span style={{ color: "#aaa" }}>bun install electrobun</span>
+          </div>
+          <hr style={{ margin: "35px 0" }} />
+          <div
+            style={{
+              display: "flex",
+              margin: "auto",
+              textAlign: "left",
+              flexWrap: "wrap",
+              justifyContent: "space-evenly",
+            }}
+          >
+            <div
+              style={{
+                minWidth: 100,
+                maxWidth: 350,
+                padding: 20,
+                border: "2px solid black",
+              }}
+            >
+              <h3>Typescript</h3>
+              <p>
+                Write typescript for the main process and webviews without
+                having to think about it. One language, no hassle.
+              </p>
+            </div>
+
+            <div
+              style={{
+                minWidth: 100,
+                maxWidth: 350,
+                padding: 20,
+                border: "2px solid black",
+              }}
+            >
+              <h3>Fast</h3>
+              <p>
+                Security and Performance with isolation between the main and
+                webview processes and fast, typed, easy to implement RPC between
+                them.
+              </p>
+            </div>
+
+            <div
+              style={{
+                minWidth: 100,
+                maxWidth: 350,
+                padding: 20,
+                border: "2px solid black",
+              }}
+            >
+              <h3>Tiny</h3>
+              <p>
+                Small self-extracting app bundles ~12MB and tiny app updates as
+                small as 4KB. Ship often while saving bandwidth costs.
+              </p>
+            </div>
+
+            <div
+              style={{
+                minWidth: 100,
+                maxWidth: 350,
+                padding: 20,
+                border: "2px solid black",
+              }}
+            >
+              <h3>Batteries</h3>
+              <p>
+                Everything you need in one tightly integrated workflow to start
+                writing code in 5 minutes and distribute in 10.
+              </p>
+            </div>
+          </div>
+        </div>
+      </main>
+    </Layout>
+  );
+}

package/documentation/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  // This file is not used in compilation. It is here just for a nice editor experience.
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": "."
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electrobun",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Build ultra fast, tiny, and cross-platform desktop apps with Typescript.",
   "license": "MIT",
   "author": "Blackboard Technologies Inc.",
@@ -11,7 +11,7 @@
     "./view": "./src/browser/index.ts"
   },
   "bin": {
-    "electrobun": "src/cli/build/electrobun"    
+    "electrobun": "src/cli/build/electrobun"
   },
   "homepage": "https://electrobun.dev",
   "repository": {
@@ -19,7 +19,7 @@
     "url": "https://github.com/blackboardsh/electrobun.git"
   },
   "scripts": {
-    "start": "bun src/bun/index.ts",    
+    "start": "bun src/bun/index.ts",
     "check-zig-version": "vendors/zig/zig version",
     "install-zig": "mkdir -p vendors/zig && curl -L https://ziglang.org/download/0.11.0/zig-macos-aarch64-0.11.0.tar.xz | tar -xJ --strip-components=1 -C vendors/zig zig-macos-aarch64-0.11.0/zig zig-macos-aarch64-0.11.0/lib",
     "build:objc:object": "mkdir -p src/objc/build && clang -c src/objc/objcWrapper.m -o src/objc/build/objcWrapper.o -fobjc-arc -fno-objc-msgsend-selector-stubs",
@@ -34,20 +34,25 @@
     "build:launcher:release": "cd src/launcher && ../../vendors/zig/zig build -Doptimize=ReleaseSmall",
     "build:extractor:release": "cd src/extractor && ../../vendors/zig/zig build -Doptimize=ReleaseSmall",
     "build:browser": "bun build src/browser/index.ts --outdir src/zig/build/",
-    "build:cli": "bun build src/cli/index.ts --compile --outfile src/cli/build/electrobun",    
+    "build:cli": "bun build src/cli/index.ts --compile --outfile src/cli/build/electrobun",
     "build:dev": "bun install && bun build:zig:trdiff && bun build:objc && bun build:browser && bun build:zig && bun build:launcher && bun build:extractor && bun build:cli",
     "build:release": "bun build:objc && bun build:zig:trdiff:release && bun build:browser && bun build:zig:release && bun build:launcher:release && bun build:extractor:release && bun build:cli",
     "release:dist": "bun build:release && cp src/launcher/zig-out/bin/launcher dist/launcher && cp src/extractor/zig-out/bin/extractor dist/extractor && cp src/bsdiff/zig-out/bin/bsdiff dist/bsdiff && cp src/bsdiff/zig-out/bin/bspatch dist/bspatch && cp src/zig/zig-out/bin/webview dist/webview && cp node_modules/.bin/bun dist/bun",
     "build:electrobun": "bun build:objc && bun build:browser && bun build:zig && bun build:bun",
     "dev:example": "bun build:dev && cd example && npm install && bun build:dev && bun start",
     "dev:example:rerun": "cd example && bun start",
-    "dev:example:canary": "bun build:release && cd example && npm install && bun build:canary"
+    "dev:example:canary": "bun build:release && cd example && npm install && bun build:canary",
+    "dev:docs": "cd documentation && bun start",
+    "build:docs:release": "cd documentation && bun run build"
   },
   "devDependencies": {
     "@types/bun": "^1.0.8",
     "bun": "1.0.26"
   },
   "dependencies": {
-    "rpc-anywhere": "1.5.0", "tar": "^6.2.1", "@oneidentity/zstd-js": "^1.0.3" 
+    "@oneidentity/zstd-js": "^1.0.3",
+    "electrobun": "^0.0.2",
+    "rpc-anywhere": "1.5.0",
+    "tar": "^6.2.1"
   }
 }

package/src/browser/index.ts

@@ -384,8 +384,8 @@ class Electroview<T> {
 
 export { type RPCSchema, createRPC, Electroview };
 
-const ElectrobunView = {
+const Electrobun = {
   Electroview,
 };
 
-export default ElectrobunView;
+export default Electrobun;

package/src/bun/core/BrowserView.ts

@@ -16,6 +16,8 @@ import type { BuiltinBunToWebviewSchema } from "../../browser/builtinrpcSchema";
 const BrowserViewMap = {};
 let nextWebviewId = 1;
 
+const CHUNK_SIZE = 4096; // 4KB
+
 type BrowserViewOptions<T = undefined> = {
   url: string | null;
   html: string | null;
@@ -213,8 +215,19 @@ export class BrowserView<T> {
     this.executeJavascript(wrappedMessage);
   }
 
+  // Note: the OS has a buffer limit on named pipes. If we overflow it
+  // it won't trigger the kevent for zig to read the pipe and we'll be stuck.
+  // so we have to chunk it
   executeJavascript(js: string) {
-    this.inStream.write(js + "\n");
+    let offset = 0;
+    while (offset < js.length) {
+      const chunk = js.slice(offset, offset + CHUNK_SIZE);
+      this.inStream.write(chunk);
+      offset += CHUNK_SIZE;
+    }
+
+    // Ensure the newline is written after all chunks
+    this.inStream.write("\n");
   }
 
   loadURL(url: string) {

package/src/cli/index.ts

@@ -716,7 +716,9 @@ if (commandArg === "init") {
     const cacheBuster = Math.random().toString(36).substring(7);
     const updateJsonResponse = await fetch(
       urlToPrevUpdateJson + `?${cacheBuster}`
-    );
+    ).catch((err) => {
+      console.log("bucketURL not found: ", err);
+    });
 
     const urlToLatestTarball = join(
       config.release.bucketUrl,

package/docs/architecture.md

@@ -1,84 +0,0 @@
-## 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
-
-## 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.
-
-## Events
-
-Electrobun.events is a custom event emitter. If we look at how the 'will-navigate' event works.
-
-1. zig sends json rpc request to decide navigation over the main bun named pipe with a url and a webviewid
-2. zig pauses the main thread simulating a promise-ish while listening on a separate named pipe listener thread
-3. bun parses the json rpc and sees it's a 'will navigate' request
-4. bun creates a new Electrobun.events.webview.willNavigate event with the data (url and webviewid).
-5. bun then emits the event globally ('will-navigate') that could be listened to with Electrobun.events.on('will-navigate')
-6. bun the passes the same event to a specific event ('will-navigate-<webviewId>' ie: will-navigate-1 for the webivew with id 1)
-7. you could listen to this globally via Electrobun.events.on('will-navigate-1') if you wanted to. Since ids are incremented deterministically this allows for some interesting patterns like handling navigation for the first window created
-8. you can also listen on the webview with myWebview.on('will-navigate'). 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.
-9. 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.
-10. the response is then sent serialized as an rpc response and sent back to zig which is listening on another thread and unfreezes the main thread returning the value
-
-Global events are always called before specific events.
-
-## 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.