electrobun 0.0.2 → 0.0.4

package/src/browser/webviewtag.ts

@@ -4,6 +4,8 @@ type WebviewEventTypes =
   | "did-commit-navigation"
   | "dom-ready";
 
+type Rect = { x: number; y: number; width: number; height: number };
+
 const ConfigureWebviewTags = (
   enableWebviewTags: boolean,
   zigRpc: (params: any) => any,
@@ -24,6 +26,10 @@ const ConfigureWebviewTags = (
     zigRpc: any;
     syncRpc: any;
 
+    // querySelectors for elements that you want to appear
+    // in front of the webview.
+    maskSelectors: Set<string> = new Set();
+
     // observers
     resizeObserver?: ResizeObserver;
     // intersectionObserver?: IntersectionObserver;
@@ -39,12 +45,16 @@ const ConfigureWebviewTags = (
       height: 0,
     };
 
+    lastMasksJSON: string = "";
+    lastMasks: Rect[] = [];
+
     transparent: boolean = false;
     passthroughEnabled: boolean = false;
     hidden: boolean = false;
     delegateMode: boolean = false;
     hiddenMirrorMode: boolean = false;
     wasZeroRect: boolean = false;
+    isMirroring: boolean = false;
 
     partition: string | null = null;
 
@@ -59,6 +69,16 @@ const ConfigureWebviewTags = (
       });
     }
 
+    addMaskSelector(selector: string) {
+      this.maskSelectors.add(selector);
+      this.syncDimensions();
+    }
+
+    removeMaskSelector(selector: string) {
+      this.maskSelectors.delete(selector);
+      this.syncDimensions();
+    }
+
     initWebview() {
       const rect = this.getBoundingClientRect();
       this.lastRect = rect;
@@ -206,6 +226,10 @@ const ConfigureWebviewTags = (
     // know that they're chaning something in order to eliminate the lag that the
     // catch all loop will catch
     syncDimensions(force: boolean = false) {
+      if (!force && this.hidden) {
+        return;
+      }
+
       const rect = this.getBoundingClientRect();
       const { x, y, width, height } =
         this.adjustDimensionsForHiddenMirrorMode(rect);
@@ -220,19 +244,45 @@ const ConfigureWebviewTags = (
         return;
       }
 
+      const masks: Rect[] = [];
+      this.maskSelectors.forEach((selector) => {
+        const els = document.querySelectorAll(selector);
+
+        for (let i = 0; i < els.length; i++) {
+          const el = els[i];
+
+          if (el) {
+            const maskRect = el.getBoundingClientRect();
+
+            masks.push({
+              // reposition the bounding rect to be relative to the webview rect
+              // so objc can apply the mask correctly and handle the actual overlap
+              x: maskRect.x - x,
+              y: maskRect.y - y,
+              width: maskRect.width,
+              height: maskRect.height,
+            });
+          }
+        }
+      });
+
+      // store jsonStringified last masks value to compare
+      const masksJson = masks.length ? JSON.stringify(masks) : "";
+
       if (
         force ||
         lastRect.x !== x ||
         lastRect.y !== y ||
         lastRect.width !== width ||
-        lastRect.height !== height
+        lastRect.height !== height ||
+        this.lastMasksJSON !== masksJson
       ) {
-        // if we're not already in an accelerated loop then accelerate it
-        if (!this.positionCheckLoopReset) {
-          this.setPositionCheckLoop(true);
-        }
+        // let it know we're still accelerating
+        this.setPositionCheckLoop(true);
 
         this.lastRect = rect;
+        this.lastMasks = masks;
+        this.lastMasksJSON = masksJson;
 
         this.zigRpc.send.webviewTagResize({
           id: this.webviewId,
@@ -242,6 +292,7 @@ const ConfigureWebviewTags = (
             x: x,
             y: y,
           },
+          masks: masksJson,
         });
       }
 
@@ -265,13 +316,12 @@ const ConfigureWebviewTags = (
         this.positionCheckLoopReset = undefined;
       }
 
-      const delay = accelerate ? 100 : 400;
+      const delay = accelerate ? 0 : 300;
 
       if (accelerate) {
-        clearTimeout(this.positionCheckLoopReset);
         this.positionCheckLoopReset = setTimeout(() => {
           this.setPositionCheckLoop(false);
-        }, 600);
+        }, 2000);
       }
       // Note: Since there's not catch all way to listen for x/y changes
       // we have a 400ms interval to check
@@ -288,6 +338,59 @@ const ConfigureWebviewTags = (
       this.positionCheckLoop = setInterval(() => this.syncDimensions(), delay);
     }
 
+    // The global document mousemove will fire even when the mouse is over
+    // an OOPIF that's layered above this host webview. The two edge cases we
+    // solve for are:
+    // 1. dragging an element on the host over or dropping on the webview anchor
+    // 2. clicking on an element that's "layered over" the OOPIF visually but really uses a
+    // mask to make a section transparent. We want the underlying overlay UI to be
+    // interactive not the OOPIF.
+    //
+    // Solution: Have mirroing on by default.
+    // 1. mouse move events don't fire during drag. So the OOPIF remains non-interactive
+    // and effectively passes through to the host's anchor element underneath letting you
+    // react to drag events on the host as needed.
+    // 2. Detect when the mouse is moving over the anchor and turn mirroring off to make
+    // it interactive. Unless the mouse is over a masked area in which case we want to
+    // keep it non-interactive and pass through to the host "overylay UI".
+    handleDocumentMouseMove(e: MouseEvent) {
+      if (this.hidden) {
+        return;
+      }
+
+      const isInBounds =
+        e.clientX >= this.lastRect.x &&
+        e.clientX <= this.lastRect.x + this.lastRect.width &&
+        e.clientY >= this.lastRect.y &&
+        e.clientY <= this.lastRect.y + this.lastRect.height;
+
+      if (isInBounds) {
+        const isInMaskBounds = this.lastMasks.find((mask) => {
+          // we send relative x/y to objc but here we need the clientX/Y
+          // to compare against. consider doing the opposite or storing both.
+          const clientX = this.lastRect.x + mask.x;
+          const clientY = this.lastRect.y + mask.y;
+          const isInMaskBounds =
+            e.clientX >= clientX &&
+            e.clientX <= clientX + mask.width &&
+            e.clientY <= clientY + mask.height &&
+            e.clientY >= clientY;
+
+          return isInMaskBounds;
+        });
+        if (isInMaskBounds) {
+          this.startMirroring();
+        } else {
+          this.stopMirroring();
+        }
+      } else {
+        this.startMirroring();
+      }
+    }
+
+    boundhandleDocumentMouseMove = (e: MouseEvent) =>
+      this.handleDocumentMouseMove(e);
+
     connectedCallback() {
       this.setPositionCheckLoop();
 
@@ -300,8 +403,14 @@ const ConfigureWebviewTags = (
       // we still need to send it to objc to calculate from its bottom left position
       // otherwise it'll move around unexpectedly.
       window.addEventListener("resize", this.boundForceSyncDimensions);
-
       window.addEventListener("scroll", this.boundSyncDimensions);
+      // Note: mousemove won't fire during a drag so we get that behaviour
+      // for free without doing calculations.
+      document.addEventListener(
+        "mousemove",
+        this.boundhandleDocumentMouseMove,
+        true
+      );
 
       // todo: For chromium webviews (windows native or chromium bundled)
       // should be able to use performanceObservers on layout-shift to
@@ -318,6 +427,10 @@ const ConfigureWebviewTags = (
       // this.mutationObserver?.disconnect();
       window.removeEventListener("resize", this.boundForceSyncDimensions);
       window.removeEventListener("scroll", this.boundSyncDimensions);
+      document.removeEventListener(
+        "mousemove",
+        this.boundhandleDocumentMouseMove
+      );
       this.zigRpc.send.webviewTagRemove({ id: this.webviewId });
     }
 
@@ -407,9 +520,8 @@ const ConfigureWebviewTags = (
     DEFAULT_FRAME_RATE = Math.round(1000 / 30); // 30fps
     streamScreenInterval?: Timer;
 
-    // todo: add a flag to disable automirroring since it's cpu intensive and
-    // developers may want to disable it in specific cases
-    startMirroring(frameRate: number = this.DEFAULT_FRAME_RATE) {
+    // NOTE: This is very cpu intensive, Prefer startMirroring where possible
+    startMirroringToDom(frameRate: number = this.DEFAULT_FRAME_RATE) {
       if (this.streamScreenInterval) {
         clearInterval(this.streamScreenInterval);
       }
@@ -419,13 +531,33 @@ const ConfigureWebviewTags = (
       }, frameRate);
     }
 
-    stopMirroring() {
+    stopMirroringToDom() {
       if (this.streamScreenInterval) {
         clearInterval(this.streamScreenInterval);
         this.streamScreenInterval = undefined;
       }
     }
 
+    startMirroring() {
+      if (this.isMirroring === false) {
+        this.isMirroring = true;
+        this.zigRpc.send.webviewTagToggleMirroring({
+          id: this.webviewId,
+          enable: true,
+        });
+      }
+    }
+
+    stopMirroring() {
+      if (this.isMirroring === true) {
+        this.isMirroring = false;
+        this.zigRpc.send.webviewTagToggleMirroring({
+          id: this.webviewId,
+          enable: false,
+        });
+      }
+    }
+
     clearScreenImage() {
       this.style.backgroundImage = "";
     }
@@ -503,11 +635,11 @@ const ConfigureWebviewTags = (
         this.syncScreenshot(() => {
           this.delegateMode = true;
           this.toggleTransparent(true, true);
-          this.startMirroring();
+          this.startMirroringToDom();
         });
       } else {
         this.delegateMode = false;
-        this.stopMirroring();
+        this.stopMirroringToDom();
         this.toggleTransparent(this.transparent);
         this.tryClearScreenImage();
       }
@@ -527,10 +659,10 @@ const ConfigureWebviewTags = (
           this.hiddenMirrorMode = true;
           this.toggleHidden(true, true);
           this.togglePassthrough(true, true);
-          this.startMirroring();
+          this.startMirroringToDom();
         });
       } else {
-        this.stopMirroring();
+        this.stopMirroringToDom();
         this.toggleHidden(this.hidden);
         this.togglePassthrough(this.passthroughEnabled);
         this.tryClearScreenImage();

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;
@@ -30,6 +32,7 @@ type BrowserViewOptions<T = undefined> = {
   rpc: T;
   syncRpc: { [method: string]: (params: any) => any };
   hostWebviewId: number;
+  autoResize: boolean;
 };
 
 interface ElectrobunWebviewRPCSChema {
@@ -66,6 +69,7 @@ const internalSyncRpcHandlers = {
       partition,
       frame,
       hostWebviewId,
+      autoResize: false,
     });
 
     // Note: we have to give it a couple of ticks to fully create the browserview
@@ -102,6 +106,7 @@ export class BrowserView<T> {
   html: string | null = null;
   preload: string | null = null;
   partition: string | null = null;
+  autoResize: boolean = true;
   frame: {
     x: number;
     y: number;
@@ -133,6 +138,7 @@ export class BrowserView<T> {
     // file exists first
     this.pipePrefix = `/private/tmp/electrobun_ipc_pipe_${hash}_${randomId}_${this.id}`;
     this.hostWebviewId = options.hostWebviewId;
+    this.autoResize = options.autoResize === false ? false : true;
 
     this.init();
   }
@@ -156,7 +162,7 @@ export class BrowserView<T> {
         x: this.frame.x,
         y: this.frame.y,
       },
-      //   autoResize: true,
+      autoResize: this.autoResize,
     });
 
     this.createStreams();
@@ -213,8 +219,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/bun/proc/zig.ts

@@ -192,6 +192,7 @@ type ZigHandlers = RPCSchema<{
           width: number;
           height: number;
         };
+        autoResize: boolean;
       };
       response: void;
     };

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.