This document is under construction.

Gear add-on engine is a new high-performance mobile Userscript engine that is compatible with Tampermonkey and Greasemonkey Userscript.

The basic Userscript demo

// ==UserScript==
// @name         {{name}}
// @version      0.1
// @description  New Userscript
// @author       You
// @match        *
// @run-at       document-end
// @grant        none
// ==/UserScript==

(function() {
    'use strict';
    // Your code here...
    
})();

Userscript headers

@name

The name of the Userscript.
@namespace

The namespace of the Userscript.
@version

The version of Userscript. This number should be increased to indicate the script had changed, so Gear will decide can update or not according to this value.
@author

The author name of the Userscript. It will appear on the script's detail view.
@description

The description of the Userscript. It will appear from the add-on list.
@homepage

The script homepage URL for the user to visit.
@icon

The icon of the Userscript. It will appear from the add-on list.
@icon64

The high-quality icon of the Userscript. Gear will prefer using this value to display the icon if set.
@updateURL

The URL for updating the script. Gear will prefer using this value for checking the new version.
@downloadURL

The URL for downloading the script. Gear will use this value for checking the new version if @updateURL is not set. If this value is also null, Gear will choose the first-time install URL as the update URL for updating.
@supportURL

The support URL for the user to contact.
@run-at

Defines when the script is injected.
- document-start
  
  The script will be injected as fast as possible.
- document-body
  
  The script will be injected if the body element exists.
- document-end
  
  The script will be injected when or after the DOMContentLoaded event was dispatched.
- document-idle
  
  The script will be injected after the DOMContentLoaded event was dispatched. This is the default value if no @run-at tag is given.
- context-menu
  
  The script will be injected if it is clicked at the browser context menu.
@include

The URL match patterns that the script will run. Gear will prefer using this value for matching.

Matches any URL that uses the http scheme
```
// @include http://*/*
```
Will match: http://foo.bar/ http://example.org/foo/bar.html

Matches any URL that uses the http scheme, on any host, as long as the path starts with /foo.
```
// @include http://*/foo*
```
Will match: http://example.com/foo/bar.html http://abc.com/foo

Matches any URL that starts with http or https for foo.bar.
```
// @include *://foo.bar/
```
Will match: http://foo.bar/ https://foo.bar
@match

Like the same as @include. Gear will use this value if @include is not set.
@exclude

The URL match patterns that the script should not run. The pattern rule is the same as @include.

@require

The JavaScript file will be loaded and be executed before the script starts running.

// @require https://code.jquery.com/jquery-2.1.4.min.js
// @require https://foo.bar/your_packing.js

@connect

The allowed domain for GM_xmlHttpRequest.
@grant

The allowlist for GM_* and GM.* functions and APIs. Please read the following grant list for more details.
```
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_setClipboard
// @grant unsafeWindow
```

Grant List

unsafeWindow

The shadow window object for full access to the page's JavaScript functions and variables.

Storage

Gear provides a high-performance storage engine. You save your script data here. It's standalone with the website and will be clear up when the script is uninstalled. You can use those functions to save and delete data from the storage.

Set value to the storage.


GM_setValue(name, value) : void
GM.setValue(name, value) : Promise

Get value from the storage. You can a provide default value if nothing found from the storage.


GM_getValue(name, defaultValue) : any
GM.getValue(name, defaultValue) : Promise

Delete a value from the storage.


GM_deleteValue(name) : void
GM.deleteValue(name) : Promise

List all values from the storage.


GM_listValues() : array
GM.listValues() : Promise

Add an value listener to detect value change, and return the listenerId that you can remove it by calling `GM_removeValueChangeListener(listenerId)`.

GM_addValueChangeListener(name, function(name, oldValue, newValue, isRemote)) : string

Remove the value listener by listenerId.

GM_removeValueChangeListener(listenerId)

Insert a new CSS style to head element.


GM_addStyle(style) : void
GM.addStyle(style) : void

Output log message to the console.


GM_log(message) : void
GM.log(message) : void

Get the raw content predefined from @resource.

GM_getResourceText(name) : String

Get the base64 encoded URI predefined from @resource.


GM_getResourceURL(name) : any
GM.getResourceUrl(name) : Promise

Register a menu command that can access from the running add-on menu.


GM_registerMenuCommand(name, fn, accessKey) : int
GM.registerMenuCommand(name, fn, accessKey) : int

Unregister the menu command by its id.


GM_unregisterMenuCommand(id) : void
GM.unregisterMenuCommand(id) : void

Open a new tab with options.


GM_openInTab(url, options) : TabObject
GM_openInTab(url, loadInBackground) : TabObject

TabObject = {'closed': Bool, 'onclose': Function, 'close': Function}

Create a new xmlHttpRequest.


GM_xmlHttpRequest(options) : void
GM.xmlHttpRequest(options) : void

Create a new download task.

GM_download(options), GM_download(url, name) : void

Set value to the clipboard.


GM_setClipboard(data, info = 'text|html') : void
GM.setClipboard(data, info = 'text|html') : void

Get the tab object.


// This function is unsupported.
GM_getTab

Save the tab object.


// This function is unsupported.
GM_saveTab

Send notification.


// This function is unsupported.
GM_notification

Get script's information.


console.log(GM_info)

[
    "script": [
        "uuid": string,
        "name": string,
        "author": string,
        "description": string,
        "namespace": string,
        "homepage": string,
        "version": string,
        "icon": string,
        "icon64": string,
        "excludes": array,
        "includes": array,
        "matches": array,
        "requires": array,
        "resources": object,
        "run-at": string,
        "updateURL": string,
        "downloadURL": string,
        "supportURL": string,
    ],
    "downloadMode": string = native,
    "scriptMetaStr": string,
    "scriptSource": string,
    "scriptUpdateURL": string,
    "scriptHandler": string = Tampermonkey,
    "isIncognito": bool,
    "version": string
]

Compatibility Issues for iOS

On iOS, all web browser render engines are using the WKWebView framework based on WebKit for displaying web content. That means all web browsers on iOS including Safari, will have the same JavaScript engine for running JavaScript code. Although WKWebView and desktop browsers like Chrome, Edge is WebKit based that Userscript can run on Gear just like a desktop without having significant modification, there are still some different compatibility issues that need to check out.

WKWebView RegExp engine didn't support group lookahead and group lookbehind, like positive lookahead (?:), negative lookahead (?!), positive lookbehind (?<=) and negative lookbehind (?<!). You may need to change the RegExp pattern with those.
Check the list of different APIs between Chrome and Safari https://caniuse.com/?compare=chrome+101,safari+15.4&compareCats=HTML5,JS,JS%20API.

Gear

Add-on Documentation

This document is under construction.

The basic Userscript demo

Userscript headers

@name

@namespace

@version

@author

@description

@homepage

@icon

@icon64

@updateURL

@downloadURL

@supportURL

@run-at

document-start

document-body

document-end

document-idle

context-menu

@include

Matches any URL that uses the http scheme

Matches any URL that uses the http scheme, on any host, as long as the path starts with /foo.

Matches any URL that starts with http or https for foo.bar.

@match

@exclude