-10. **Open button** - opens the extension browser page
-11. **Enable Injection toggle** - turns on/off page script inject (on/off switch)
+10. **Open Page Link** - _macOS only_, opens the extension browser page
+11. **Enable Injection toggle** - turns on/off page script injection (on/off switch)
+12. **Refresh View** - refreshes the popup view
+13. **Available Updates View** - the extension periodically checks all userscripts in your save location for updates and when an update is found, it is shown in this view
+14. **Folder Button** - on **macOS** this button opens your save location directory in Finder, on **iOS** this button displays the "all scripts view" where you can see every script that found in your save location directory, the "all scripts view" allows you to toggle individual userscript scripts on/off regardless of the current page being displayed in the browser
+15. **Install Prompt** - when a userscript is displayed in the browser, this alert displays, giving the user the option to install the userscript into their save location directory, tapping the prompt will take them through the installation steps
+16. **Matched Userscripts List** - this list shows the currently matched userscripts relative to the current page being displayed in the browser, all userscripts that match to the domain will be showed, whether they are active or not. Users can click/tap the userscript to the toggle them on/off. If a userscript is active for the domain through a subframe a **sub** tag will be show next the to the file type indicator
## Metadata
Userscripts Safari currently supports the following userscript metadata:
-- `@name` - This will be the name that displays in the sidebar and be used as the filename - you can *not* use the same name for multiple files of the same type
+- `@name` - This will be the name that displays in the sidebar and be used as the filename - you can _not_ use the same name for multiple files of the same type
- `@description`- Use this to describe what your userscript does - this will be displayed in the sidebar - there is a setting to hide descriptions
-- `@match` - Domain match patterns - you can use several instances of this field if you'd like multiple domain matches - view [this article for more information on constructing patterns](https://developer.chrome.com/extensions/match_patterns)
- - **Note:** this extension only supports `http/s`
-- `@exclude-match` - Domain patterns where you do *not* want the script to run
+- `@icon` - This doesn't have a function with this userscript manager, but the **first value** provided in the metadata will be accessible in the `GM_/GM.info` object
+- `@match` - Domain match patterns - you can use several instances of this field if you'd like multiple domain matches - please refer to: [Match pattern structure](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns#match_pattern_structure)
+ - **Note:** this extension only supports `http/s`
+- `@exclude-match` - Domain patterns where you do _not_ want the script to run
- `@include` - Used to match against urls for injection, globs and regular expressions are allowed, [read more here](https://wiki.greasespot.net/Include_and_exclude_rules)
- `@exclude` - Functions in a similar way as `@include` but rather than injecting, a match against this key's value will prevent injection
- `@inject-into` - allows the user to choose which context to inject the script into
- - allows the user to choose which context to inject the script into
- - values: auto (default), content, page
- - works like [violentmonkey](https://violentmonkey.github.io/api/metadata-block/#inject-into)
+ - allows the user to choose which context to inject the script into
+ - values: `auto` (default), `content`, `page`
+ - `GM` apis are only available when using `content`
+ - works like [violentmonkey](https://violentmonkey.github.io/api/metadata-block/#inject-into)
- `@run-at`
- - allows the user to choose the injection timing
- - document-start, document-end (default), document-idle
- - works like [violentmonkey](https://violentmonkey.github.io/api/metadata-block/#run-at)
- - **JS Only**
+ - allows the user to choose the injection timing
+ - document-start, document-end (default), document-idle
+ - works like [violentmonkey](https://violentmonkey.github.io/api/metadata-block/#run-at)
+ - **JS Only**
- `@weight`
- - allows the user to further adjust script injection timing
- - can be used to ensure one script injects before another
- - ONLY accepts integers (floats, strings and everything else will be ignored)
- - min value = 1, max value = 999, higher numbers (“heavier”) execute earlier
+ - allows the user to further adjust script injection timing
+ - can be used to ensure one script injects before another
+ - ONLY accepts integers (floats, strings and everything else will be ignored)
+ - min value = 1, max value = 999, higher numbers (“heavier”) execute earlier
- `@require`
- - allows users to include remote resources in their scripts
- - the value must be a valid url, currently no local file support
- - must require a resource of the same file type (JS for JS, CSS for CSS)
- - when a resource is required, it is downloaded and saved locally
- - the resources is downloaded once at save and never checked for updates or parsed in anyway
- - if you want to update the require resources, and the url does not change, you must remove the resources, save, then re-input it
- - **require remote resources at your own risk, the extension never validates remote resource code in any way and be aware that using remote resources from untrusted sources can jeopardize your personal security**
+ - allows users to include remote resources in their scripts
+ - the value must be a valid url, currently no local file support
+ - must require a resource of the same file type (JS for JS, CSS for CSS)
+ - when a resource is required, it is downloaded and saved locally
+ - the resources is downloaded once at save and never checked for updates or parsed in anyway
+ - if you want to update the require resources, and the url does not change, you must remove the resources, save, then re-input it
+ - **require remote resources at your own risk, the extension never validates remote resource code in any way and be aware that using remote resources from untrusted sources can jeopardize your personal security**
- `@version`
- - used to determine the current version of a userscript
- - when paired with `@updateURL`, this will allow the user to update a userscript from a remote source, if the version on their machine is `<` version at the update URL
- - `@version` does nothing by itself, it needs to be paired with` @updateURL` for remote updating to function properly
+ - used to determine the current version of a userscript
+ - when paired with `@updateURL`, this will allow the user to update a userscript from a remote source, if the version on their machine is `<` version at the update URL
+ - `@version` does nothing by itself, it needs to be paired with` @updateURL` for remote updating to function properly
- `@updateURL`
- - the remote url to check version against
- - if the version of the file located at the update URL is `>` the version on the local machine, the file will be updated
- - `@updateURL` does nothing by itself, it needs to be paired with `@version` for remote updating to function properly
+ - the remote url to check version against, the url `/PATH` should end with `.meta.js` and contains the Metadata block
+ - if the version of the file located at the update URL is `>` the version on the local machine, the file will be updated
+ - `@updateURL` does nothing by itself, it needs to be paired with `@version` for remote updating to function properly
+ - Read this [link](https://stackoverflow.com/questions/38023717/) for more details
+ - _Note: The extension does not correctly implement the entire update process, tracking in issue [#248](https://github.com/quoid/userscripts/issues/248)_
- `@downloadURL`
- - optional download location for a remotely updateable file (*i.e. a file that has both `@version` and `@updateURL`)
- - when paired with `@version` and `@updateURL`, if the local version is `<` the version of the file that `@updateURL` points to, the extension will attempt to update the file's code with the contents of the file located at the `@downloadURL`
- - `@downloadURL` does nothing by itself, it needs `@version` and `@updateURL` to present in order to function properly
+ - the url `/PATH` should end with `.user.js`, that is, it cannot be in `?QUERY` or `#HASH` parts
+ - optional download location for a remotely updateable file (\*i.e. a file that has both `@version` and `@updateURL`)
+ - when paired with `@version` and `@updateURL`, if the local version is `<` the version of the file that `@updateURL` points to, the extension will attempt to update the file's code with the contents of the file located at the `@downloadURL`
+ - `@downloadURL` does nothing by itself, it needs `@version` and `@updateURL` to present in order to function properly
- `@noframes`
- - this key takes no value
- - prevents code from being injected into nested frames
-
+ - this key takes no value
+ - prevents code from being injected into nested frames
+- `@grant`
+ - Imperative controls which special [`APIs`](#api) (if any) your script uses, one on each `@grant` line, only those API methods will be provided.
+ - If no `@grant` values are provided, `none` will be assumed.
+ - If you specify `none` and something else, `none` takes precedence.
+
**All userscripts need at least 1 `@match` or `@include` to run!**
-## Save Location
+## API
-In order to change the save location, you must either launch `Userscripts.app` as you would any other application, or open the settings modal within the browser extension and click the "settings" icon within the "Save location" row.
+Userscripts currently supports the following api methods. All methods are asynchronous unless otherwise noted. Users must `@grant` these methods in order to use them in a userscript. When using API methods, it's only possible to inject into the content script scope due to security concerns.
-Once the host app is open, you will see a button called "Change save location". Click this and select the directory where you'd like to save to/load from.
+> [!NOTE]
+>
+> The following API description applies to the latest development branch, you may need to check the documentation for the corresponding version. Please switch to the version you want to check via `Branches` or `Tags` at the top. For example:
+>
+> For the current version of the App Store:
+> https://github.com/quoid/userscripts/tree/release/4.x.x#api
+>
+> For the v4.5.x and earlier versions:
+> https://github.com/quoid/userscripts/tree/v4.5.4#api
+
+For API type definitions, please refer to: [`types.d.ts`](https://github.com/userscriptsup/testscripts/blob/f2fcde4b556fa436fe806a44a89afb9eb5dccd0b/userscripts/types.d.ts)
+
+- `GM.addStyle(css)`
+ - `css: String`
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved if succeeds, rejected with error message if fails
+- `GM.setValue(key, value)`
+ - `key: String`
+ - `value: Any` - any can be JSON-serialized
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved if succeeds, rejected with error message if fails
+- `GM.getValue(key, defaultValue)`
+ - `key: String`
+ - `defaultValue: Any` - optional
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved with the `value` that was set or `defaultValue` provided or `undefined` if succeeds, rejected with error message if fails
+- `GM.deleteValue(key)`
+ - `key: String`
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved if succeeds, rejected with error message if fails
+- `GM.listValues()`
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved with an array of the key names of **presently set** values if succeeds, rejected with error message if fails
+- `GM.getTab()`
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved with `Any` data that is persistent as long as this tab is open if succeeds, rejected with error message if fails
+- `GM.saveTab(tabObj)`
+ - `tabObj: Any` - any can be JSON-serialized
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved if succeeds, rejected with error message if fails
+- `GM.openInTab(url, openInBackground)`
+ - `url: String`
+ - `openInBackground: Bool` - optional, `false` by default
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved with [tab data](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab) for the tab just opened if succeeds, rejected with error message if fails
+- `GM.closeTab(tabId)`
+ - `tabId: Int` - optional, the `caller tab` by default
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved if succeeds, rejected with error message if fails
+- `GM.setClipboard(data, type)`
+ - `data: String`
+ - `type: String` - optional, `text/plain` by default
+ - [read more here](https://developer.mozilla.org/en-US/docs/Web/API/ClipboardEvent/clipboardData)
+ - returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), resolved with a `Bool` value indicating succeeds or fails, rejected with error message if fails
+- `GM.info` && `GM_info`
+ - is available without needing to add it to `@grant`
+ - an object containing information about the running userscript
+ - `scriptHandler: String` - returns `Userscripts`
+ - `version: String` - the version of Userscripts app
+ - `scriptMetaStr: String` - the metablock for the currently running script
+ - `script: Object` - contains data about the currently running script
+ - `description: String`
+ - `exclude-match: [String]`
+ - `excludes: [String]`
+ - `grant: [String]`
+ - `includes: [String]`
+ - `inject-into: String`
+ - `matches: [String]`
+ - `name: String`
+ - `namespace: String`
+ - `noframes: Bool`
+ - `require: [String]`
+ - `resources: [String]` - _currently not implemented_
+ - `run-at: String`
+ - `version: String` - _the userscript version value_
+- `GM.xmlHttpRequest(details)`
+ - `details: Object`
+ - the `details` object accepts the following properties
+ - `url: String` - required
+ - `method: String` - optional, `GET` by default
+ - `user: String` - optional
+ - `password: String` - optional
+ - `headers: Object` - optional
+ - `overrideMimeType: String` - optional
+ - `timeout: Int` - optional
+ - `binary: Bool` - optional (Deprecated, use binary data objects such as `Blob`, `ArrayBuffer`, `TypedArray`, etc. instead.)
+ - `data: String | Blob | ArrayBuffer | TypedArray | DataView | FormData | URLSearchParams` - optional
+ - `responseType: String` - optional
+ - refer to [`XMLHttpRequests`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
+ - upload event handlers:
+ - `upload: Object` - optional
+ - `onabort: Function` - optional
+ - `onerror: Function` - optional
+ - `onload: Function` - optional
+ - `onloadend: Function` - optional
+ - `onloadstart: Function` - optional
+ - `onprogress: Function` - optional
+ - `ontimeout: Function` - optional
+ - the progress object passed to the event handlers has the following properties:
+ - `lengthComputable`
+ - `loaded`
+ - `total`
+ - event handlers:
+ - `onabort: Function` - optional
+ - `onerror: Function` - optional
+ - `onload: Function` - optional
+ - `onloadend: Function` - optional
+ - `onloadstart: Function` - optional
+ - `onprogress: Function` - optional
+ - `onreadystatechange: Function` - optional
+ - `ontimeout: Function` - optional
+ - the response object passed to the event handlers has the following properties:
+ - `readyState`
+ - `response`
+ - `responseHeaders`
+ - `responseType`
+ - `responseURL`
+ - `status`
+ - `statusText`
+ - `timeout`
+ - `responseText` (when `responseType` is `text`)
+ - returns a custom [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) contains an additional property `abort`, resolved with the response object.
+ - usage:
+ - `const xhr = GM.xmlHttpRequest({...});`
+ - `xhr.abort();` to abort the request
+ - `const response = await xhr;`
+ - or just:
+ - `const response = await GM.xmlHttpRequest({...});`
+- `GM_xmlhttpRequest(details)`
+ - Basically the same as `GM.xmlHttpRequest(details)`, except:
+ - returns an object with a single property, `abort`, which is a `Function`
+ - usage: `const foo = GM.xmlHttpRequest({...});` ... `foo.abort();` to abort the request
+
+## Scripts Directory
+
+This is the directory where the app/extension will read from and write to. This directory is changed by opening the **containing app** and clicking the respective "change location" button.
+
+**Script Directory Notes**
+
+- Close all instances of the extension UI (browser app and/or popup) before changing the scripts directory
+- After files are added, removed or edited, you will need to open the popup at least 1 time to see those changes reflected in your browsing experience
+- **On macOS**, after a directory outside of the default is selected, if you rename or move that selected directory, the extension will continue to read/write to that directory - the only way to remove the “link” is by trashing the folder or selecting a new save location
-**Save Location Notes**
+## Getting Help
-- Close all instances of the extension UI (browser app) before you change the save location. The extension will attempt to do this automatically, but it could fail (if it does, please bug report)
-- Currently, when changing the save location, the app does not copy over userscripts from the previous save/load directory
-- After a new save location is selected, if you rename or move that selected folder, the extension will continue to load/save to that location - the only way to remove the “link” is by trashing the folder or selecting a new save location
+If you encounter a problem while using this app/extension or are in need of some assistance, please open an issue here in the repository. When doing so, please provide as much detail as possible. This includes listing system specs and what website and script you are trying to execute. _Please follow the issue template!_
## FAQs
@@ -157,33 +352,40 @@ Once the host app is open, you will see a button called "Change save location".
**Do I need to use the extension's editor to create new userscripts or to edit existing?**
-> You can use your own editor to update and manage your files. As long as you are saving the files to the save location, and they are properly formatted, they should be injected. However, you **must open the extension page** beforehand. That means, if you create a new userscript and save it to the save location, before injection will occur properly, the extension page must be open by clicking the extension button in Safari.
+> You can use your own editor to update and manage your files. As long as you are saving the files to the save location, and they are properly formatted, they should be injected. However, you **must open the extension popup** beforehand. That means, if you create a new or edit an existing userscript with an external editor and save it to the save location, before injection will occur properly, the extension popup must be opened and the popup must load completely.
**What are the keyboard shortcuts?**
-> While editing a file, clicking `Command + S` will save the file. While working the editor, clicking `Command + F` will bring up the search bar.
+> Whilst using the included editor, clicking `⌘ + s` will save the file. While working the editor, clicking `⌘ + f` will bring up the search bar and `esc` will hide it.
**When I use `@require`, where are the required files stored?**
-> All required files are saved *as Javascript files* in the extension container folder in macOS 11.x. That folder is located in the default save location, at: `~/Library/Containers/Userscripts/Data/Documents/require/`.
+> All required files are saved _as Javascript files_ in the extension container folder in macOS 11.x. That folder is located in the default save location, at: `~/Library/Containers/Userscripts/Data/Documents/require/`.
>
> If you move files from the require folder or manually edit the `manifest.json` file, you will likely break app/extension functionality.
## Contributing
-Code level contributions are welcome. I prefer to collaborate directly with contributors rather than receiving spontaneous pull requests. If you feel you can improve the project in some way, please reach out to me by email or by opening an issue with your improvement/feature request.
+
+Code level contributions please refer to [contributing.md](docs/contributing.md)
Further, any issue marked "help wanted" is actively seeking assistance. Please respond to those issues with feedback, guidance or offers of coding assistance.
-Please ensure your contributions align with the project's license before committing anything.
+Participating and interacting with any existing [`Issues`](https://github.com/quoid/userscripts/issues) or [`Discussions`](https://github.com/quoid/userscripts/discussions) would be a great help to the project and open source communities. Thank you for your contributions.
## Support
-The quickest and easiest way to support the project is by [leaving a positive review on the App Store](https://apps.apple.com/us/app/userscripts/id1463298887) if you enjoy the extension and want to see it improve in the future. Seeing these reviews let me know I am doing something right, or wrong, and motivates me to continue working on the project.
-Secondly, you can [sign up to be a beta tester](https://forms.gle/QB46uYQHVyCxULue9). Since this extension values your privacy, and **does not collect any data from users**, it is difficult to gauge how the extension is being used. By signing up to be a beta tester it not only allows you to test upcoming features, but also gives me the opportunity to elicit direct feedback from real users.
+The quickest and easiest way to support the project is by [leaving a positive review on the App Store](https://apps.apple.com/us/app/userscripts/id1463298887) if you enjoy the extension and want to see future improvements. Seeing these reviews let me know I am doing something right, or wrong, and motivates me to continue working on the project.
+
+The second best way to help out is to sign up to beta test new versions of the app. Since this extension values your privacy, and **does not collect any data from users**, it is difficult to gauge how the extension is being used. By signing up to be a beta tester it not only allows you to test upcoming features, but also gives me the opportunity to elicit direct feedback from real users.
+
+**Please join and test the corresponding beta version in [releases](https://github.com/quoid/userscripts/releases) via the TestFlight public link.**
## Privacy Policy
+
Userscripts does not collect any data from its users nor monitor activities or actions you perform within the application and extension. This means everything that you do with the application and extension is private to you and is never shared with the developers or third parties. Since there is no data collection, there is no data retention of any kind.
## License
+Copyright © 2018-2025 Justin Wasack
+
Licensed under the [GNU General Public License v3.0](/LICENSE) license for all open source applications. A commercial license is required for all other applications.
diff --git a/Userscripts.code-workspace b/Userscripts.code-workspace
new file mode 100644
index 00000000..11c4d094
--- /dev/null
+++ b/Userscripts.code-workspace
@@ -0,0 +1,14 @@
+// https://code.visualstudio.com/docs/editor/workspaces
+{
+ "folders": [
+ {
+ "name": "Userscripts-JS",
+ "path": ".",
+ },
+ {
+ "name": "Userscripts-Xcode",
+ "path": "xcode",
+ },
+ ],
+ "settings": {},
+}
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000..3cb92e9d
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,120 @@
+# Welcome to Userscripts contributing guide
+
+### Please note: the project is currently temporarily suspended from receiving direct code contributions.
+
+Please do not submit any new pull requests, they will be close immediately.
+
+If you have any ideas and suggestions, please submit them to us through [`Issues`](https://github.com/quoid/userscripts/issues) or [`Discussions`](https://github.com/quoid/userscripts/discussions).
+
+We apologize for the inconvenience and thank you for your understanding.
+
+### The following is the original guide for reference only.
+
+Thank you for investing your time in contributing to this open source project!
+
+We hope this guide will helps you understand how to contribute to this project.
+
+For development and build environments please refer to [development guide](dev.md).
+
+> [!NOTE]
+> Portions of this guide are outdated. Some processes are still being tweaked and optimized, we will update them in due course.
+
+> [!IMPORTANT]
+> Please ensure your contributions align with the project's license before committing anything.
+>
+> Any pull requests must first go through code formatting and linters, otherwise you will fail the CI check. (Refer to the `scripts` in [`package.json`](../package.json))
+
+# Branches
+
+### `main`: default branch
+
+- corresponding to development channel
+- all development work around this branch
+- protected branches not accept commits
+- all work will be done in sub-branches
+- all sub-branches will be merged via PRs
+
+### `beta`: latest test version
+
+- generated from the master branch
+- corresponding to TestFlight channel
+- only accept version number commits
+- hotfixes and PRs are not accepted
+- never merge back into master branch
+
+### `release`: latest public version
+
+- generated from the beta branch
+- generate GitHub Releases and Tags
+- corresponding to App Store channel
+- accept hotfixes and version commits
+- always merge back into master branch
+
+# Commits
+
+### Please use semantic commit messages
+
+Format: `Version {$settings.version}
You can review the documentation, report bugs and get more information about this extension by visiting the code repository.
If you enjoy using this extension, please consider leaving a review on the App Store or supporting the project.
-
+ + native-app + , + + action-popup + , + + extension-page + +
+ +This is the development preview environment
+Welcome, first use please:
+ +to complete the initialization
+{installError}
+Be sure you trust the author before saving remote code to your device.
+ +{:else} ++ Userscripts {import.meta.env.BROWSER ?? ""} + {#if import.meta.env.GIT_TAG && import.meta.env.GIT_COMMIT} + + () + {:else} + v{$settings["version"]} + ({$settings["build"]}) + {/if} +
++ {gl("settings_about_text1")} + + | + + | + +
++ {gl("settings_about_text2")} + + | + +
+