iKeySnail

iKeySnail provides fully-configurable hardware keyboard functionalities for web browsing on iOS (iPadOS).

The aim of this project is to provide { Vimium, Vimperator, Surfingkeys, KeySnail } for iOS. Currently, iKeySnail supports

Hardware keyboard supported web browsing
- Emacs-like keybindings/functionalities
  - e.g., Ctrl-Space to set mark, Meta-w to copy the selected region, Ctrl-y to yank (paste) the clipboard text
- Vim-like keybindings/functionalities
  - e.g., j/k/h/l/g/G to quickly scroll web pages
Link-hints (Hit-a-hint)
- For clicking links without touching your iOS device screen
Vertical tabs
- We do support vertical tabs in iOS!
- Setting config.TAB_VERTICAL = true makes tab orientations vertical
Omnibar support
- Work-in-progress, but we do support omnibar. By default, pressing o opens your bookmarks.

Installation

You need JSBox (https://docs.xteko.com/#/en/) to run iKeySnail. After installing the JSBox, access either of

https://tinyurl.com/ikeysnail
jsbox://import/?url=https%3A%2F%2Fgithub.com%2Fmooz%2Fikeysnail%2Freleases%2Flatest%2Fdownload%2Fikeysnail.box

from iOS Safari. Then JSBox will install iKeySnail.

Manual Build

You can also manually build the package and install it in JSBox:

make package

then copy .output/ikeysnail.box to your JSBox app.

Usage

See strings/settings.js for available shortcuts.

Customization

Edit strings/settings.js.

Remote Settings

Tired of manually syncing your config across all of your devices?

Remote settings is your help. Prepare strings/settings.js that contains a variable config.REMOTE_CONFIG_URL and ikeysnail refers to the specified configuration on the remote server. For example

config.REMOTE_CONFIG_URL = "https://gist.githubusercontent.com/mooz/676f15e3814751df2e1b67e0b14f5f97/raw/ikeysnail_config.js";

works.

Defining / Customizing Keymap

We have four types of mode for key bindings.

all-mode, whose keymaps are always active.
- https://github.com/mooz/jsbox-ksc/blob/master/strings/settings.js#L19
view-mode, whose keymaps are active only if the cursor isn't on editable elements (akin to vim's normal mode).
- https://github.com/mooz/jsbox-ksc/blob/master/strings/settings.js#L81
rich-mode, whose keymaps are active only if the cursor is on rich text editors (such as CodeMirror, Ace, Scrapbox, and contenteditable).
- https://github.com/mooz/jsbox-ksc/blob/master/strings/settings.js#L32
edit-mode, whose keymaps are active only if the cursor is on input or textarea.
- https://github.com/mooz/jsbox-ksc/blob/master/strings/settings.js#L74

In each keymap, you can define a key's functionality in two ways:

Remapping to different key (e.g., "ctrl-s": "meta-f"), and
Invoke a JavaScript function (e.g., "ctrl-y": () => keysnail.paste()).
- See keysnail object for checking available functionalities https://github.com/mooz/jsbox-ksc/blob/master/strings/content-script.js#L761

Defining a site

You can also define a site configuration in your settings.js. Configuration consists of

keymap -> keymap
style -> user css
alias -> alias
url -> url.

Examples are follows.

config.sites.push({
    alias: "Google",
    url: "https://www.google.com"
  });

  const GDOCS_KEYMAP = {
    rich: {
      "meta-f": keysnail.marked("alt-ArrowRight"),
      "meta-b": keysnail.marked("alt-ArrowLeft"),
      "meta-d": keysnail.marked("alt-Delete"),
      "ctrl-_": "ctrl-z",
      "ctrl-z": "meta-z",
      "ctrl-s": "ctrl-f"
    }
  };

  config.sites.push({
    alias: "Google Docs",
    url: "https://docs.google.com/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "Google Docs (Slide)",
    url: "https://docs.google.com/presentation/",
    keymap: GDOCS_KEYMAP
  });

  config.sites.push({
    alias: "OverLeaf",
    url: "https://www.overleaf.com/project/",
    style: `
.toolbar { font-size: small !important; }
.entity { font-size: small !important; }
`
  });

  config.sites.push({
    alias: "Scrapbox",
    url: "https://scrapbox.io/",
    keymap: {
      rich: {
        "meta-f": keysnail.marked("alt-ArrowRight"),
        "meta-b": keysnail.marked("alt-ArrowLeft"),
        "ctrl-i": "ctrl-i",
        "ctrl-t": "ctrl-t"
      }
    },
    style: `
#editor {
  caret-color: transparent !important;
}
`
  });

Gifs

Omnibar

Link hints

Acknowledgements

Parts of iKeySnail are inspired by previous wonderful works (thanks to).

Scrapbox scripts by @four_or_three
- https://scrapbox.io/customize/iPad%E3%81%A8%E5%A4%96%E9%83%A8%E3%82%AD%E3%83%BC%E3%83%9C%E3%83%BC%E3%83%89%E3%81%A7%E7%B7%A8%E9%9B%86%E3%81%A7%E3%81%8D%E3%82%8BScrapbox%E3%81%AE%E3%83%96%E3%83%A9%E3%82%A6%E3%82%B6
Bookmarklet Hit-a-hint @okayu_tar_gz
- https://qiita.com/okayu_tar_gz/items/924481d4acf50be37618

Releasing (for developers)

Building a package

make package

Releasing a package

make release

mooz/ikeysnail