positron.js 1.0.2 → 1.0.4

package/bin/positron.js

@@ -35,6 +35,6 @@ switch (command) {
     break;
 
   default:
-    console.log("Usage: npx positron [build | dev | run]");
+    console.log("Usage: npx positron [build | dev | run | package]");
     process.exit(0);
 }

package/builder.js

@@ -1,7 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const cp = require("child_process");
-const { success, error, info } = require("./logs");
+const { success, error, info, warn } = require("./logs");
 
 const arch = process.argv.includes("--x64") ? "x64" : process.argv.includes("--arm64") ? "arm64" : process.arch;
 
@@ -144,10 +144,19 @@ function performNativeBuild() {
       });
 
       try {
-        const iconPathEscaped = path.join(__dirname, "positronicon.png").replace(/"/g, '\\"');
+        let swiftScript = "";
+        if(fs.existsSync(path.join(appRoot, "icon.icns"))) {
+           const iconPathEscaped = path.join(appRoot, "icon.icns").replace(/"/g, '\\"');
         const binPathEscaped = path.join(outBinaryDir, binaryName).replace(/"/g, '\\"');
-        const swiftScript = `import Cocoa; NSWorkspace.shared.setIcon(NSImage(contentsOfFile: "${iconPathEscaped}"), forFile: "${binPathEscaped}", options: [])`;
+        swiftScript = `import Cocoa; NSWorkspace.shared.setIcon(NSImage(contentsOfFile: "${iconPathEscaped}"), forFile: "${binPathEscaped}", options: []); `;
         cp.execFileSync("swift", ["-e", swiftScript], { stdio: "ignore" });
+          return true;
+        } else if(fs.existsSync(path.join(__dirname, ['positronicon', 'png'].join('.')))) {
+        const iconPathEscaped = path.join(__dirname, ['positronicon', 'png'].join('.')).replace(/"/g, '\\"');
+        const binPathEscaped = path.join(outBinaryDir, binaryName).replace(/"/g, '\\"');
+        swiftScript = `import Cocoa; NSWorkspace.shared.setIcon(NSImage(contentsOfFile: "${iconPathEscaped}"), forFile: "${binPathEscaped}", options: []);`;
+        }
+         cp.execFileSync("swift", ["-e", swiftScript], { stdio: "ignore" });
       } catch (err) {
         error("Failed to set custom icon on native binary:", err);
       }

package/core/mac/main.swift

@@ -141,13 +141,9 @@ func getBuiltInHandlers() -> [String: (Int, [String]) -> Void] {
             return 
         }
         
-        let selector = Selector(("_showDeveloperTools:"))
-        if webView.responds(to: selector) {
-            webView.perform(selector, with: nil)
-        } else {
-            printError("openDevTools failed: _showDeveloperTools: selector not found on WKWebView (windowId \(windowId))")
+            let inspector = webView.value(forKey: "inspector") as? NSObject
+            inspector?.perform(NSSelectorFromString("show"))
         }
-        },
     ]
     
     return baseHandlers + getExtensionRegistry()
@@ -169,6 +165,26 @@ struct IPCResponse: Codable {
     let data: [String: String]
 }
 
+ func GetIPCClient() -> IPCClient {
+    return AppDelegate.shared?.ipcClient ?? IPCClient()
+}
+
+func GetWebView(windowId: Int) -> WKWebView? {
+    guard let window = windows[windowId],
+          let webView = window.contentView as? WKWebView else {
+        printError("GetWebView failed: no webview found for window \(windowId)")
+        return nil
+    }
+    return webView
+}
+
+func GetWindow(windowId: Int) -> NSWindow? {
+    guard let window = windows[windowId] else {
+        printError("GetWindow failed: no window found with ID \(windowId)")
+        return nil
+    }
+    return window
+}
 
 // MARK: - Command Handler
 
@@ -272,6 +288,26 @@ func handleCommand(windowId: Int, command: String, args: [String]) {
 
     window.performClose(nil) 
 
+case "isFullscreen":
+    guard let window = windows[windowId] else { return }
+    let isFullscreen = window.styleMask.contains(.fullScreen)
+    AppDelegate.shared?.ipcClient.send(
+        IPCResponse(windowId: windowId, event: "isFullscreen-reply-\(windowId)", data: ["isFullscreen": isFullscreen ? "true" : "false"])
+    )
+
+case "setSwipeNav":
+        guard let window = windows[windowId],
+              let webView = window.contentView as? WKWebView else {
+            return
+        }
+        
+        let enable = args.first?.lowercased() != "false"
+        webView.allowsBackForwardNavigationGestures = enable
+
+        GetIPCClient().send(
+            IPCResponse(windowId: windowId, event: "setSwipeNav-reply-\(windowId)", data: ["enabled": enable ? "true" : "false"])
+        )
+
 case "forceCloseWindow":
     guard let window = windows[windowId] else { return }
 
@@ -488,6 +524,97 @@ UNUserNotificationCenter.current().requestAuthorization(
                 printError("executeAppleScript failed: \(errorMessage)")
             }
 
+case "isVisible":
+    guard let window = windows[windowId] else { return }
+    let isVisible = window.isVisible
+    AppDelegate.shared?.ipcClient.send(
+        IPCResponse(windowId: windowId, event: "isVisible-reply-\(windowId)", data: ["isVisible": isVisible ? "true" : "false"])
+    )
+
+case "addToContentBlocker":
+    guard let window = windows[windowId],
+          let webView = window.contentView as? WKWebView,
+          let input = args.first
+    else {
+        printError("addToContentBlocker — missing rules")
+        return
+    }
+
+    let jsonStr: String
+
+    if FileManager.default.fileExists(atPath: input) {
+        do {
+            jsonStr = try String(contentsOfFile: input, encoding: .utf8)
+        } catch {
+            printError("Failed to read rule file: \(error.localizedDescription)")
+            return
+        }
+    } else {
+        jsonStr = input
+    }
+
+    guard let data = jsonStr.data(using: .utf8),
+          (try? JSONSerialization.jsonObject(with: data)) != nil
+    else {
+        printError("addToContentBlocker — invalid JSON rules")
+        return
+    }
+
+    let reload = args.count > 1
+        ? args[1].lowercased() == "true"
+        : true
+
+    let clearAll = args.count > 2
+        ? args[2].lowercased() == "true"
+        : false
+
+    let identifier = "dynamicRules-\(windowId)-\(UUID().uuidString)"
+
+    WKContentRuleListStore.default().compileContentRuleList(
+        forIdentifier: identifier,
+        encodedContentRuleList: jsonStr
+    ) { [weak webView] ruleList, error in
+
+        guard let webView else { return }
+
+        if let error {
+            printError("Failed to compile content blocker rules: \(error.localizedDescription)")
+            return
+        }
+
+        guard let ruleList else {
+            printError("Failed to compile content blocker rules: no rule list returned")
+            return
+        }
+
+        let controller = webView.configuration.userContentController
+
+        if clearAll {
+            controller.removeAllContentRuleLists()
+        }
+
+        controller.add(ruleList)
+
+        if reload {
+            webView.reload()
+        }
+    }
+
+    GetIPCClient().send(
+        IPCResponse(windowId: windowId, event: "addToContentBlocker-reply-\(windowId)", data: ["status": "success"])
+    )
+
+        case "isSwipeNavEnabled":
+            guard let window = windows[windowId],
+                  let webView = window.contentView as? WKWebView else {
+                printError("isSwipeNavEnabled — webview not found for window \(windowId)")
+                return
+            }
+            let enabled = webView.allowsBackForwardNavigationGestures
+            AppDelegate.shared?.ipcClient.send(
+                IPCResponse(windowId: windowId, event: "isSwipeNavEnabled-reply-\(windowId)", data: ["enabled": enabled ? "true" : "false"])
+            )
+
        case "forward":
            guard let window = windows[windowId] else { return }
             (window.contentView as? WKWebView)?.goForward()
@@ -606,6 +733,24 @@ UNUserNotificationCenter.current().requestAuthorization(
             }
         }
 
+    case "confirm":
+        guard let window = windows[windowId] else { return }
+        guard let message = args.first else {
+            printError("confirm — missing message argument")
+            return
+        }
+        let alert = NSAlert()
+        alert.messageText = message
+        alert.addButton(withTitle: "OK")
+        alert.addButton(withTitle: "Cancel")
+
+        alert.beginSheetModal(for: window) { response in
+            let confirmed = (response == .alertFirstButtonReturn)
+            AppDelegate.shared?.ipcClient.send(
+                IPCResponse(windowId: windowId, event: "confirm-reply-\(windowId)", data: ["confirmed": confirmed ? "true" : "false"])
+            )
+        }
+
     case "isFocused":
         guard let window = windows[windowId] else { return }
         let isFocused = window.isKeyWindow
@@ -1016,6 +1161,15 @@ class AppDelegate: NSObject, NSApplicationDelegate {
     editMenu.addItem(withTitle: "Paste", action: #selector(NSText.paste(_:)), keyEquivalent: "v")
     editMenu.addItem(withTitle: "Select All", action: #selector(NSText.selectAll(_:)), keyEquivalent: "a")
 
+    // Window menu
+    let windowMenuItem = NSMenuItem()
+    mainMenu.addItem(windowMenuItem)
+    let windowMenu = NSMenu(title: "Window")
+    windowMenuItem.submenu = windowMenu
+    windowMenu.addItem(withTitle: "Minimize", action: #selector(NSWindow.miniaturize(_:)), keyEquivalent: "m")
+    windowMenu.addItem(withTitle: "Zoom", action: #selector(NSWindow.zoom(_:)), keyEquivalent: "")
+    NSApp.windowsMenu = windowMenu
+
     NSApp.mainMenu = mainMenu
 }
 }
@@ -1094,6 +1248,12 @@ func buildMenu(from descriptor: [[String: Any]], windowId: Int) -> NSMenu {
         let sub = NSMenu(title: topItem.title)
         topItem.submenu = sub
 
+        if let role = topLevel["role"] as? String, role.lowercased() == "window" {
+            NSApp.windowsMenu = sub
+        } else if topItem.title.lowercased() == "window" {
+            NSApp.windowsMenu = sub
+        }
+
         if let items = topLevel["items"] as? [[String: Any]] {
             populateMenu(sub, with: items, windowId: windowId, isContextMenu: false)
         }

package/core/win/main.cs

@@ -24,7 +24,6 @@ namespace PositronWindows
     
     // MARK: - IPC Message Types
     
-
     public class IPCMessage
     {
         public int windowId { get; set; }
@@ -382,6 +381,58 @@ private void StartNodeProcess(string workingDirectory)
     
     // 3. Attach it to the layout
     layout.ContextMenu = contextMenu;
+    break;
+
+    case "setSwipeNav":
+    if (!WindowsMap.TryGetValue(windowId, out var winSwipeNav)) break;
+    var wvSwipeNav = GetWebView(windowId);
+    if (wvSwipeNav != null)    {
+        bool enable = args.Count == 0 || args[0].ToLower() != "false";
+        wvSwipeNav.CoreWebView2.Settings.IsSwipeNavigationEnabled = enable;
+    }
+    
+    GetIPCClient().Send(new IPCResponse
+    {
+        windowId = windowId,
+        @event = "setSwipeNav-reply-" + windowId,
+        data = new() { { "enabled", (wvSwipeNav?.CoreWebView2.Settings.IsSwipeNavigationEnabled ?? false).ToString().ToLower() } }
+    });
+
+    break;
+
+    case "isSwipeNavEnabled":
+    if (!WindowsMap.TryGetValue(windowId, out var winCheckSwipe)) break;
+    var wvCheckSwipe = GetWebView(windowId);
+    if (wvCheckSwipe != null)    {
+        bool isEnabled = wvCheckSwipe.CoreWebView2.Settings.IsSwipeNavigationEnabled;
+        GetIPCClient().Send(new IPCResponse
+        {
+            windowId = windowId,
+            @event = "isSwipeNavEnabled-reply-" + windowId,
+            data = new() { { "enabled", isEnabled.ToString().ToLower() } }
+        }
+        );
+    }
+    break;
+
+    case "isVisible":
+    if (!WindowsMap.TryGetValue(windowId, out var winVisible)) break;
+    bool isVisible = winVisible.IsVisible;
+    GetIPCClient().Send(new IPCResponse
+    {        windowId = windowId,
+        @event = "isVisible-reply-" + windowId,
+        data = new() { { "isVisible", isVisible.ToString().ToLower() } }
+    });
+    break;
+
+    case "isFullscreen":
+    if (!WindowsMap.TryGetValue(windowId, out var winFullscreen)) break;
+    bool isFullscreen = winFullscreen.WindowState == WindowState.Maximized;
+    GetIPCClient().Send(new IPCResponse
+    {        windowId = windowId,
+        @event = "isFullscreen-reply-" + windowId,
+        data = new() { { "isFullscreen", isFullscreen.ToString().ToLower() } }
+    });
     break;
 
                 case "closeWindow":
@@ -621,6 +672,24 @@ case "setBounds":
                     }
                     break;
 
+                case "confirm":
+                    if (args.Count < 1)
+                    {
+                        error("confirm — expected message argument");
+                        break;
+                    }
+                    {
+                        var message = args[0];
+                        var result = MessageBox.Show(message, "Confirm", MessageBoxButton.YesNo) == MessageBoxResult.Yes;
+                        _ipcClient.Send(new IPCResponse
+                        {
+                            windowId = windowId,
+                            @event = "confirm-reply-" + windowId,
+                            data = new() { { "confirmed", result.ToString().ToLower() } }
+                        });
+                    }
+                    break;
+
                 case "emitToRenderer":
                     if (args.Count < 2)
                     {
@@ -841,6 +910,15 @@ case "setBounds":
             return null;
         }
 
+        public static Window? GetWindow(int windowId)
+        {
+            if (WindowsMap.TryGetValue(windowId, out var window))
+                return window;
+            return null;
+        }
+
+        public static IPCClient GetIPCClient() => _ipcClient;
+
         // MARK: - Menu Management
 
         private static void BuildAndAttachMenu(int windowId, string jsonStr)

package/index.js

@@ -267,7 +267,8 @@ class Window extends Events.EventEmitter {
    * @param {string} command 
    * @param {string[]} args 
    */
-  sendCommand(command, args = []) {
+  sendCommand(command, ...args) {
+    if(args[0] instanceof Array) args = args[0].concat(args.slice(1));
     const normalizedArgs = Array.isArray(args) ? args.map(String) : [String(args)];
     
     const payload = JSON.stringify({ 
@@ -338,7 +339,7 @@ class Window extends Events.EventEmitter {
    * @param {string} channel The IPC channel to send the message on.
    * @param {string[]} args The arguments to send with the message.
    */
-sendIpc(channel, args = []) {
+emitToRenderer(channel, args = []) {
   if (activeSocket && activeSocket.readyState === WebSocket.OPEN) {
     const payload = JSON.stringify({
       windowId: this.id,
@@ -352,6 +353,15 @@ sendIpc(channel, args = []) {
   }
 }
 
+
+/**
+ * @deprecated Use emitToRenderer instead.
+ */
+sendIpc = (channel, args = []) => {
+  warn("sendIpc is deprecated. Use emitToRenderer instead.");
+  this.emitToRenderer(channel, args);
+}
+
  #created = false;
 
  /**
@@ -405,6 +415,10 @@ create(width, height, darwinOptions = {
     this.sendCommand("forceCloseWindow");
   }
 
+  isClosed() {
+    return !activeWindows.has(this);
+  }
+
 
   /**
    * Sets the application menu for this window.
@@ -488,10 +502,6 @@ resize(width, height) {
  * Opens the developer tools for the window. Emits a "devtools-opened" event when done. Does not work on macOS. For macOS, right-click the window and select "Inspect Element" to open dev tools for that window.
  */
 openDevTools() {
-  if(process.platform === "darwin") {
-    warn("The openDevTools command is not supported on macOS due to OS limitations. Please right-click the window and select 'Inspect Element' to access developer tools.");
-    return;
-  }
   this.sendCommand("openDevTools");
   this.emit("devtools-opened");
 }
@@ -560,6 +570,26 @@ focus() {
   this.emit("focused");
 }
 
+/**
+ * Checks if the window is currently visible. Returns a Promise that resolves to true if the window is visible, or false if it is hidden. Emits an "is-visible-checked" event with the result as data when done.
+ * @returns {Promise<boolean>} True if the window is visible, false otherwise.
+ */
+async isVisible() {
+  const res = await this.request("isVisible", `isVisible-reply-${this.id}`);
+  return res?.isVisible === "true";
+}
+
+/**
+ * Checks if the window is currently in fullscreen mode.
+ * @returns {Promise<boolean>} True if the window is fullscreen, false otherwise.
+ */
+async isFullscreen() {
+  const res = await this.request("isFullscreen", `isFullscreen-reply-${this.id}`);
+  return res?.isFullscreen === "true";
+}
+
+
+
 /**
  * Reloads the window. Emits a "reloaded" event when done.
  */
@@ -627,7 +657,7 @@ if (timeoutArg) {
 
   args = args.filter(arg => arg !== timeoutArg);
 
-  timeoutDuration = parseInt(timeoutArg.split("=")[1], 10);
+  timeoutDuration = parseInt(timeoutArg.split("=")[1]);
 }
       
     timeout = setTimeout(() => {
@@ -747,6 +777,10 @@ setContextMenu(menuTemplate) {
   this.emit("context-menu-updated", menuTemplate);
 }
 
+/**
+ * Checks if the window is currently focused.
+ * @returns {Promise<boolean>} True if the window is focused, false otherwise.
+ */
 async isFocused() {
   const res = await this.request("isFocused", `isFocused-reply-${this.id}`);
   return res?.isFocused === "true";
@@ -765,7 +799,7 @@ async getBounds() {
  * @returns {Promise<string>} The current URL loaded in the window.
  */
 async getURL() {
-  return await this.request("getURL", `getURL-reply-${this.id}`);
+  return (await this.request("getURL", `getURL-reply-${this.id}`))?.url || "";
 }
 
 /**
@@ -773,7 +807,7 @@ async getURL() {
  * @returns {Promise<string>} The current title of the window.
  */
 async getTitle() {
-  return await this.request("getTitle", `getTitle-reply-${this.id}`);
+  return (await this.request("getTitle", `getTitle-reply-${this.id}`)).title || "";
 }
 
 /**
@@ -801,7 +835,7 @@ setTitlebarTransparent(isTransparent) {
  */
 async evaluateJavaScript(script) {
 const res = await this.request("evaluateJS", `evaluateJS-reply-${this.id}`, script);
-return res;
+return res.result;
 }
 
 /**
@@ -809,8 +843,7 @@ return res;
  * @returns {Promise<string>} The user agent string of the window.
  */
 async getUserAgent() {
-  const res = await this.evaluateJavaScript("navigator.userAgent");
-  return res;
+  return await this.evaluateJavaScript("navigator.userAgent");
 }
 
 /**
@@ -822,10 +855,14 @@ async getUserAgent() {
 async setStyleOf(selector, style) {
   const styleString = Object.entries(style).map(([key, value]) => `${key}: ${value};`).join(" ");
   const script = `
+  (function() { 
     const elements = document.querySelectorAll(${JSON.stringify(selector)});
     elements.forEach(el => {
-      el.style.cssText += ${JSON.stringify(styleString)};
+      Object.entries(${JSON.stringify(style)}).forEach(([key, value]) => {
+        el.style[key] = value;
+      });
     });
+  })();
   `;
   await this.evaluateJavaScript(script);
   this.emit("style-updated", { selector, style });
@@ -840,10 +877,12 @@ async setStyleOf(selector, style) {
  */
 async setAttributeOf(selector, attribute, value) {
   const script = `
+  (function() {
     const elements = document.querySelectorAll(${JSON.stringify(selector)});
     elements.forEach(el => {
       el.setAttribute(${JSON.stringify(attribute)}, ${JSON.stringify(value)});
     });
+  })();
   `;
   await this.evaluateJavaScript(script);
   this.emit("attribute-updated", { selector, attribute, value });
@@ -857,10 +896,12 @@ async setAttributeOf(selector, attribute, value) {
  */
 async removeAttributeOf(selector, attribute) {
   const script = `
-    const elements = document.querySelectorAll(${JSON.stringify(selector)});
-    elements.forEach(el => {
-      el.removeAttribute(${JSON.stringify(attribute)});
-    });
+    (function() {
+      const elements = document.querySelectorAll(${JSON.stringify(selector)});
+      elements.forEach(el => {
+        el.removeAttribute(${JSON.stringify(attribute)});
+      });
+    })();
   `;
   await this.evaluateJavaScript(script);
   this.emit("attribute-removed", { selector, attribute });
@@ -875,12 +916,14 @@ async removeAttributeOf(selector, attribute) {
 async removeStyleOf(selector, styleProperties) {
   const propertiesString = styleProperties.map(prop => `${prop}:`).join("|");
   const script = `
-    const elements = document.querySelectorAll(${JSON.stringify(selector)});
-    elements.forEach(el => {
-      el.style.cssText = el.style.cssText.split(";").filter(rule => {
-        return !${JSON.stringify(propertiesString)}.includes(rule.trim().split(":")[0] + ":");
-      }).join(";");
-    });
+    (function() {
+      const elements = document.querySelectorAll(${JSON.stringify(selector)});
+      elements.forEach(el => {
+        el.style.cssText = el.style.cssText.split(";").filter(rule => {
+          return !${JSON.stringify(propertiesString)}.includes(rule.trim().split(":")[0] + ":");
+        }).join(";");
+      });
+    })();
   `;
   await this.evaluateJavaScript(script);
   this.emit("style-removed", { selector, styleProperties });
@@ -896,6 +939,7 @@ async removeStyleOf(selector, styleProperties) {
  */
 async onClick(selector, channel, { replace = true } = {}) {
   const script = `
+  (function() {
       const selector = ${JSON.stringify(selector)};
       const channel = ${JSON.stringify(channel)};
       const replace = ${replace};
@@ -913,6 +957,7 @@ async onClick(selector, channel, { replace = true } = {}) {
         });  
         }
             })
+  })();
   `;
 
   await this.evaluateJavaScript(script);
@@ -933,6 +978,78 @@ async removeOnClick(selector) {
   await this.evaluateJavaScript(script);
 }
 
+/**
+ * Displays a confirmation dialog with the given message. Returns a Promise that resolves to true if the user confirmed, or false if the user cancelled. Emits a "confirm" event with the message as data when done.
+ * @param {string} message The message to display in the confirmation dialog.
+ * @returns {Promise<boolean>} True if the user confirmed, false if the user cancelled.
+ */
+async confirm(message) {
+  const res = await this.request("confirm", `confirm-reply-${this.id}`, message);
+  this.emit("confirm", message);
+  return res?.confirmed === "true";
+}
+
+/**
+ * Enables or disables swipe navigation for the window. When enabled, users can navigate back and forward through their history by swiping left or right on a trackpad or touchscreen. Emits a "swipe-navigation-updated" event with the new value when done.
+ * @param {boolean} enabled Whether swipe navigation should be enabled.
+ * @returns {Promise<void>} A Promise that resolves when the swipe navigation setting has been updated.
+ */
+async setSwipeNavigation(enabled) {
+const res = await this.request("setSwipeNav", `setSwipeNav-reply-${this.id}`, String(enabled));
+this.emit("swipe-navigation-updated", enabled);
+}
+
+/**
+ * Checks if swipe navigation is enabled for the window. Returns a Promise that resolves to true if swipe navigation is enabled, or false if it is disabled. Emits an "is-swipe-navigation-enabled-checked" event with the result as data when done.
+ * @returns {Promise<boolean>} True if swipe navigation is enabled, false otherwise.
+ */
+async isSwipeNavigationEnabled() {
+  const res = await this.request("isSwipeNavEnabled", `isSwipeNavEnabled-reply-${this.id}`);
+  return res?.enabled === "true";
+}
+
+/**
+ * Adds content blocker rules to the window. The rules can be provided as a JSON object, loaded from a URL that returns JSON, or loaded from a local file. 
+ * Once the rules are added, the window will block content according to the specified rules. Emits a "content-blocker-updated" event with the new rules as data when done.
+ * @param {Object} config The configuration for adding content blocker rules.
+ * @param {Object[]} [config.json] An array of content blocker rules as JSON objects. Each rule should follow the format specified by the native layer's content blocking implementation.
+ * @param {string} [config.url] A URL that returns a JSON array of content blocker rules. If provided, the rules will be loaded from this URL instead of using the `json` property.
+ * @param {string} [config.file] A local file path containing the content blocker rules in JSON format. If provided, the rules will be loaded from this file instead of using the `json` or `url` properties.
+ * @param {boolean} [config.reload] Whether to reload the window after adding the content blocker rules. Reloading may be necessary for the new rules to take effect immediately, but it can also be set to false if you want to add rules without interrupting the user's current session.
+ * @param {boolean} [config.clearExisting] Whether to clear existing content blocker rules before adding the new ones. If false, the new rules will be added alongside any existing rules. If true, all existing rules will be removed before adding the new ones.
+ * @platform macOS only
+ * @see https://webkit.org/blog/3476/content-blockers-first-look/
+ */
+async addToContentBlocker(config={ json:[], url:"", file:"", reload:true, clearExisting: false }) {
+
+  if(process.platform !== "darwin") return;
+
+  let json = config.json || [];
+
+  if(config.file) {
+    json = config.file
+  } else {
+  if(config.url) {
+    let req = (await fetch(config.url));
+    let _json = await req.json();
+
+    if(json.length) {
+      json = json.concat(_json);
+    } else {
+      json = _json;
+    }
+  }
+
+  json = JSON.stringify(json);
+}
+
+
+  const res = await this.request("addToContentBlocker", `addToContentBlocker-reply-${this.id}`, json, config.reload, config.clearExisting);
+  this.emit("content-blocker-updated", json);
+}
+
+
+
 }
 
 const app = {
@@ -963,7 +1080,7 @@ const app = {
   },
 
   /**
-   * Adds an event listener for application-level events. Supported events include "before-quit" and "quit".
+   * Adds an event listener for application-level events.
    * @param {string} event The name of the event to listen for.
    * @param {Function} listener The callback function to invoke when the event is emitted.
    */
@@ -989,11 +1106,19 @@ const app = {
     this.events.once(event, listener);
   },
 
+  /**
+   * Gets the currently focused window. Returns a Promise that resolves to the focused Window instance, or null if no windows are currently focused. Emits a "focused-window-retrieved" event with the focused window as data when done.
+   * @returns {Promise<Window|null>} The currently focused window, or null if no windows are focused.
+   */
   async getFocusedWindow() {
    const results = await Promise.all([...activeWindows].map(win => win.isFocused().then(isFocused => ({ win, isFocused }))));
    return results.find(({ isFocused }) => isFocused)?.win || null;
   },
 
+  /**
+   * Sets the application name, which is used for things like the user data directory and may be used by the native layer for other purposes.
+   * @param {*} name The new name for the application. This will be converted to a string before being used.
+   */
   setName(name) {
     process.env.POSITRON_APP_NAME = name;
     this.events.emit("name-updated", name);
@@ -1005,7 +1130,12 @@ const app = {
   },
 
 userData: {
-  getPath() {
+  /**
+   * Gets the path to the user data directory for the application. The path is determined based on the operating system and the application name. If the directory does not exist, it will be created. Emits a "user-data-path-retrieved" event with the path as data when done.
+   * @param {string} [append] An optional string to append to the user data path. This can be used to create subdirectories within the user data directory for organizing different types of data. If provided, the appended path will also be created if it does not exist.
+   * @returns {string} The path to the user data directory.
+   */
+  getPath(append) {
     let userPath = null;
 
     if (process.platform === "win32") {
@@ -1030,9 +1160,12 @@ userData: {
       fs.mkdirSync(userPath, { recursive: true });
   }
 
-    return userPath;
+    return append ? path.join(userPath, append) : userPath;
   },
 
+  /**
+   * Creates the user data directory if it does not already exist. Emits a "user-data-created" event when the directory is created successfully.
+   */
   create() {
     const userPath = this.getPath();
 
@@ -1042,6 +1175,10 @@ userData: {
     }
   },
 
+  /**
+   * Deletes the user data directory and all of its contents. Use with caution, as this will permanently remove all user data for the application. Emits a "user-data-deleted" event when the directory is deleted successfully.
+   */
+
   delete() {
     const userPath = this.getPath();
 

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/systemsoftware/positron.js"
   },
   "homepage": "https://positronjs.gitbook.io",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "main": "index.js",
   "scripts": {
     "test": "node --test"