English | 简体中文

Appine means "App in Emacs", which is an Emacs plugin using a Dynamic Module that allows you to embed native macOS views (WebKit, PDFKit, Quick look PreviewView, etc.) directly inside Emacs windows.

You can open a browser, read PDFs, listen to music, and watch videos in Emacs. Enjoy the full power of native macOS rendering, smooth scrolling, and hardware acceleration without leaving Emacs!

Support for Windows and Linux systems will be considered in the future. The main reason is that I currently don't have a Windows computer, and the Linux distribution I use doesn't have a GUI, which makes it impossible for me to debug the plugin at present. Moreover, unlike macOS, Windows and Linux lack native system-level rendering frameworks for web pages, PDFs, and Office files, requiring third-party libraries to implement, which often introduces instability. Cross-platform libraries like Qt are often too massive and too heavy for a small Emacs plugin. If you really want to use browsers, PDFs, and other apps in Emacs, you can try the EAF project.

• Native Web Browsing: Embed a fully functional Safari-like WebKit view inside an Emacs window, with full support for cookies.
• Native PDF Rendering: View PDFs with macOS's built-in PDFKit for buttery-smooth scrolling and zooming, and easily copy content from it to other Emacs buffers.
• Native Word/Excel Rendering: View Word/Excel files with macOS's built-in Quartz for buttery-smooth scrolling and zooming. Unfortunately, you cannot edit them yet.
• Seamless Integration: The native views automatically resize and move when you split or adjust Emacs windows.
• Tab Management: Support for multiple embedded tabs, switching, and closing directly from Emacs.
• Org-mode Integration: Use Appine to open links and files within Org files.

The embedded App has two states: Active and Inactive.

• Active State: Click the embedded App to enter the active state. When active, it can be used just like a native Mac App. Emacs is locked during this time.
• Inactive State: When you click on other Emacs buffers, the embedded App is locked, grayed out, and cannot be interacted with. You can use Emacs normally at this time. If the native view has focus, you can click the Deactivate button (or use a configured shortcut) to safely return focus to Emacs and split the view into a side-by-side layout.

A video demonstrating the two states.

deactivate:

Run M-x appine-open-web-split. You will be prompted to enter a URL. A native WebKit view will open in the current Emacs window. A demonstration video is as follows:

A video demonstrating Open Web Page.

Run M-x appine-open-file-split. If you select a PDF file, it will be rendered using macOS PDFKit. Other files will be previewed using Quick Look.

A video demonstrating Open PDF.

Setting (setq appine-enable-open-in-org-mode t) enables opening URLs and files with Appine. You can toggle this feature on or off by running M-x appine-toggle-open-in-org-mode.

TODO: Add a video demonstrating Org-mode integration.

The Toolbar implements common App operations such as New Tab, Open File, etc., and also includes editing operations like Cut/Copy/Paste. Since Appine introduces the macOS Quick Look Preview module, most common files can be previewed. You can open files through the Open File button in the Appine window.

Copy/Paste video

The native view is tied to an Emacs buffer (named *Appine-Window*). You can split windows (C-x 3, C-x 2), resize them, or switch buffers. The native view will automatically track the Emacs window's geometry.

• macOS (Tested on macOS 12+)
• Emacs 29.1 or higher compiled with Dynamic Module support (--with-modules). You can use M-: (functionp 'module-load) to check if the module-load function is available. (Note: Most popular distributions like Emacs Plus, Emacs Mac Port, and emacsformacosx have this enabled by default).

The easiest way to install Appine is using use-package with straight.el or quelpa. The package will automatically download the pre-compiled native binary (.dylib) for your Mac (supports both Apple Silicon and Intel) on the first run.

(use-package appine
  :straight (appine :type git :host github :repo "chaoswork/appine")
  :custom
  ;; enables opening URLs and files with Appine, default is nil
  (appine-enable-open-in-org-mode t) 
  :config
  ;; Optional: Set default keybindings
  (global-set-key (kbd "C-x a w") 'appine-open-web-split)
  (global-set-key (kbd "C-x a o") 'appine-open-file-split))  

If you prefer to build the module yourself, you need the Xcode Command Line Tools (xcode-select --install).

1. Clone the repository:

   git clone https://github.com/chaoswork/appine.git ~/.emacs.d/lisp/appine

2. Compile the C/Objective-C module:

   cd ~/.emacs.d/lisp/appine
   make

3. Add to your init.el:

   (add-to-list 'load-path "~/.emacs.d/lisp/appine")
   (require 'appine)

Appine uses Emacs Dynamic Modules to bridge C/Objective-C and Emacs Lisp. To safely handle events triggered by the macOS UI thread (like clicking a button) without crashing Emacs, it uses a robust combination of POSIX signals (SIGUSR1) and C11 atomic_bool flags to safely interrupt Emacs's event loop and execute Lisp callbacks. The project is still under continuous improvement. If you encounter any problems, feel free to open an issue.

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.