KarimAziev / chrome-emacs

A revitalized browser-to-editor extension, fully updated for Chrome's latest policies with Manifest V3, service workers, and enriched with Monaco Editor support. A tribute and spiritual successor to the beloved Atomic Chrome, designed for seamless bi-directional text editing between Chrome and Emacs.

About

This is a Chrome Extension focused on bi-directional editing in online text editors and text areas from within Emacs.

After the original Atomic Chrome extension was removed from the Chrome Web Store due to policy violations, I undertook the task of creating an entirely refreshed and compliant version. Now named "Chrome Emacs," it represents more than just a fork; it is a comprehensive rewrite that adheres to the newest standards and Chrome Extension Manifest V3, ensuring both compliance and enhanced security.

Differences between the original and the forked package, as well as other similar packages, like GhostText:

• Support for the Monaco Editor: Expands the range of compatible online editors far beyond the original. Note, GhostText also supports the Monaco Editor but without position and scroll synchronization.
• Editable Areas Navigation with Hints: Introduces a navigation feature where editable areas are overlaid with hints (letters). Pressing the corresponding letter key on the keyboard allows users to swiftly switch focus to those areas, enhancing usability and editing efficiency.
• Migration to Chrome Extension Manifest V3: Guarantees that the extension stays compatible with the latest browser versions and meets current security standards.
• Cursor and Scroll Synchronization: The motivation for this comes from the live-coding experience during online interviews. Unlike other solutions, it focuses not only on editing text areas but also on providing a seamless live-code experience in online editors.
• Auto-Major Mode Detection: Automatically configures the most suitable editing mode for any given online editor.
• Complete Rewrite in TypeScript: This enhances the extension's stability, maintainability, and performance.

Chrome Emacs is compatible with almost all online editors, including:

• ☑ codepen.io
• ☑ stackblitz.com
• ☑ jsfiddle.net
• ☑ leetcode.com
• ☑ hackerrank.com
• ☑ repl.it
• ☑ glitch.com
• ☑ plnkr.co
• ☑ coderpad.io

Experimental support is also available. See key considerations for users here:

• ☑ vscode.dev
• ☑ codesandbox.io

Table of Contents

• About
• Installation
  • Chrome Extension
  • Emacs Integration
• Usage
• Customization
  • How to Bind Shortcuts
  • Extension Options
• Development

Installation

Chrome Extension

Install the Chrome extension.

Emacs Integration

Install the corresponding Emacs package from this fork (recommended for cursor and scroll synchronization, file handling, automatic major mode detection, and handling large content, etc.), or the original atomic-chrome package for basic functionality only.

Detailed Differences Between the Original Package and Its Fork

• Handling large payloads: Unlike the original package, which may not handle incomplete frames, this fork is equipped to manage large payloads efficiently.
• Cursor and scroll synchronization: Inspired by the need for a more fluid live-coding experience during online interviews, the chrome-emacs extension and this fork focus on editing text areas and providing seamless cursor and scroll synchronization in online editors.
• Flexible file handling: This fork introduces the atomic-chrome-create-file-strategy variable, enabling refined control over the use of temporary files for editing—a feature not present in the original package. Recognizing that language servers often require file access for functionalities like code linting and autocompletion, this feature allows users to enable, disable, or customize file usage according to their needs. This flexibility ensures users have full control over their editing environment.
• Dynamic major modes: Recognizing the diversity of programming languages within many online editors, this fork surpasses the original package's limitation of one major mode per website. It dynamically sets major modes based on file extensions extracted from the editor instance, resulting in a more responsive and tailored editing experience.
• Enhanced frame configuration: Beyond the original package's limited customization of frame width and height, this fork extends customization to every frame configuration parameter. It also automatically calculates left and top positions for the frame when the Atomic Chrome client provides a rect with pixel dimensions and positions, offering a more adaptable and sophisticated user interface.

Show installation instructions

With use-package and straight.el

(use-package atomic-chrome
  :demand t
  :straight (atomic-chrome
             :repo "KarimAziev/atomic-chrome"
             :type git
             :host github)
  :commands (atomic-chrome-start-server)
  :config
  (setq-default atomic-chrome-extension-type-list '(atomic-chrome))
  (atomic-chrome-start-server))

Manual Installation

Download the source code and place it in your desired directory (e.g., ~/.emacs.d/atomic-chrome/):

git clone https://github.com/KarimAziev/atomic-chrome.git ~/.emacs.d/atomic-chrome/

Add the downloaded directory to the load path and require it:

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

Run server

(atomic-chrome-start-server)

Show Emacs advanced configuration example

(use-package atomic-chrome
  :straight (atomic-chrome
             :type git
             :flavor nil
             :host github
             :repo "KarimAziev/atomic-chrome")
  :defines atomic-chrome-create-file-strategy
  :config
  (setq-default atomic-chrome-buffer-open-style 'frame)
  (setq-default atomic-chrome-auto-remove-file t)
  (setq-default atomic-chrome-url-major-mode-alist
                '(("ramdajs.com" . js-ts-mode)
                  ("github.com" . gfm-mode)
                  ("gitlab.com" . gfm-mode)
                  ("leetcode.com" . typescript-ts-mode)
                  ("codesandbox.io" . js-ts-mode)
                  ("typescriptlang.org" . typescript-ts-mode)
                  ("jsfiddle.net" . js-ts-mode)
                  ("w3schools.com" . js-ts-mode)))
  (add-to-list 'atomic-chrome-create-file-strategy
               '("~/repos/ts-scratch/src/" :extension
                 ("js" "ts" "tsx" "jsx" "cjs" "mjs"))))

Usage

chrome-emacs_with_subs.mp4

Ensure that Emacs is running with the atomic-chrome fork (or original atomic-chrome) loaded and the server is running (M-x atomic-chrome-start-server).

1. Run M-x atomic-chrome-start-server in Emacs. This is needed only once.

2. Focus on or select from detected editable text areas, text editors, or contenteditable elements in Chrome.

3. Activate Chrome Emacs. This can typically be done by clicking on the extension's icon or using a keyboard shortcut.

The text will now open in an Emacs buffer, ready for you to edit.

Customization

How to Bind Shortcuts

1. Navigate to chrome://extensions.
2. Scroll down and click on Keyboard shortcuts at the bottom of the page.
3. Assign shortcuts for the available commands:

• Activate the extension - This is the default action to edit the focused area. If there are no focused areas, it tries to detect them from the visible part of the page.
• Select and edit an element - Shows the key to press near editable elements to focus and start editing. To cancel, press either ESC or Ctrl-g (these keybindings may be changed, as well as the characters used in hints; see Extension Options).

Extension Options

In the options, you can configure which letters to use for hints and exit keybindings.

There are several ways to open the extension's options:

From the Toolbar with a Pinned Icon

If you have pinned the Chrome Emacs icon on the toolbar, right-click on the icon and then click on "Options".

From the Toolbar without a Pinned Icon

Another quick way is to click the "Extensions" button on the toolbar. This is the icon that looks like a small puzzle piece next to the profile avatar. In the dropdown, find Chrome Emacs, and click the settings icon, which looks like a "vertical ellipsis". Then click on "Options".

From the Chrome Extensions URL

Alternatively, navigate to chrome://extensions, find Chrome Emacs, click on "Details", and then click on "Extension options".

In the options popup, after making changes, remember to click on the "Save" button.

Development

Local Setup

1. Clone the repository to your local machine:

   git clone https://github.com/KarimAziev/chrome-emacs.git
   

2. Ensure the correct version of Node.js is installed, as specified in the .nvmrc file. Switch to the correct version with nvm use, if using NVM.
3. Install required dependencies:

   npm install
   

4. Build the extension:

• For rebuilding the extension on file save, run:

  npm run dev
  

• For a one-time build:

  npm run build
  

5. Load the built app directory into Chrome:
   • Navigate to chrome://extensions/
   • Toggle "Developer mode" at the top right.
   • Click "Load unpacked" and select the app directory.

Your contributions to both the Chrome extension and the Emacs package are welcome!