Spookfox

1. Firefox

2. Chrome (thanks to @kajalelohai)

   But can you run it? Although Chrome is supported and a .crx file is generated in the releases, Chrome won't let you install and use it. Stop using Chrome. PS Check installation below.

There are 2 parts to install spookfox.

1. Install the browser addon

   Download the addon (.xpi file for Firefox) from releases page. Browser will prompt you to install as soon as you download it.

   What is it not available on Browser addons page?

   Because it is not approved on Firefox addons yet.

   ⚠️ You'll have to drag-n-drop the downloaded crx file to Chrome to even install it, because Google. You will probably need to clone this repo, run yarn build, and load unpacked extension to run Spookfox in Chrome.

2. Install Emacs package

   • Using straight.el

     (use-package spookfox
       :straight
       (spookfox :type git
                 :host github
                 :repo "bitspook/spookfox"
                 :files ("lisp/*.el" "lisp/apps/*.el"))
       :config
       (spookfox-init))
     

   • Manually

     • Clone this repository

       git clone https://github.com/bitspook/spookfox <path-to-spookfox>
       

     • Add spookfox and its apps load-path

       (add-to-list 'load-path "<path-to-spookfox>/lisp")
       (add-to-list 'load-path "<path-to-spookfox>/lisp/apps")
       

Spookfox itself is a thin layer which between Emacs and Browser. More functionality on top of it is provided with apps. Different apps need to be configured as documented in apps section below.

1. Load the apps you want to use

   If you followed the installation instructions, all apps bundled with the package itself should be ready to be loaded with a call to require. For example, to load "" app, you'd write this Elisp:

   (require 'spookfox-tabs)
   

2. Tell spookfox which apps you want to enable

   Provide the list of enabled apps to spookfox-enabled-apps variable:

   (setq spookfox-enabled-apps '(spookfox-org-tabs))
   

3. Initialize spookfox

   Changes to spookfox-enabled-apps take effect when spookfox-init function is called. This function also starts the websockets server.

   (spookfox-init)
   

4. Register custom request handlers

   It is possible to send custom events from browser (e.g using a JavaScript bookmarklet), and run elisp code to handle them. For this you need to do 2 things:

   1. Add a handle for request in Emacs

      Here is some example code for registering a request handler:

      (defun my--capture-the-flag (url)
        (message "CAPTURING THE FLAG: %s" url))
      
      (spookfox--register-req-handler "CAPTURE_THE_FLAG" #'my--capture-the-flag)
      

   2. Send a request from browser

      postMessage({
        type: 'SPOOKFOX_RELAY_TO_EMACS',
        action: {
          name: 'CAPTURE_THE_FLAG',
          payload: { url: window.location.href }
        }
      })
      

      action part here decides which request handler will execute. Elisp version of payload will be provided to your request-handler as an argument.

Spookfox has a modular architecture. An "app" is a bundle of functionality isolated and opt-in. Following apps come bundled with this package.

1. Write apps

   If you want to write apps for Spookfox to handle a use-case not covered by existing apps, for now you need to go through the source code to figure things out. I am still working on a web-accessible documentation for Spookfox. Code is allegedly well-commented and existing apps can act as good examples.

2. Modify Spookfox

   To make changes on the Browser side of things, you'll have to modify and rebuild the browser addon itself. Unfortunately browsers don't allow injecting code into the running addon anymore (although it is possible to inject code into a website).

   Or you might want to fix a bug, or make the code cleaner.

   Please take a look at the contributing.org for setting up the development environment to hack Spookfox.