- Userscript
- {#if scriptChecking}
- {showInstallPrompt}
- {:else}
- {scriptInstalled ? "Installed" : "Detected"}:
- {showInstallPrompt}
- {/if}
-
-{/if}
-{#if errorNotification}
- Be sure you trust the author before saving remote code to your device.
-
- {@html iconLoader}
- {#if abort}
-
- Fetching resources, cancel request
-
- {/if}
+
+
+ {@html iconLoader}
+ {#if abort}
+
+ Fetching resources,
+
+ {/if}
diff --git a/src/shared/Components/LogoIcon.svelte b/src/shared/Components/LogoIcon.svelte
new file mode 100644
index 00000000..7b5f74df
--- /dev/null
+++ b/src/shared/Components/LogoIcon.svelte
@@ -0,0 +1,14 @@
+
+
+
+
+
diff --git a/src/shared/Components/LogoText.svelte b/src/shared/Components/LogoText.svelte
new file mode 100644
index 00000000..e5ad9068
--- /dev/null
+++ b/src/shared/Components/LogoText.svelte
@@ -0,0 +1,24 @@
+
+
+
+
+
diff --git a/src/shared/Components/Tag.svelte b/src/shared/Components/Tag.svelte
index 13e80cf2..80e00954 100644
--- a/src/shared/Components/Tag.svelte
+++ b/src/shared/Components/Tag.svelte
@@ -1,55 +1,55 @@
diff --git a/src/shared/Components/Toggle.svelte b/src/shared/Components/Toggle.svelte
index cc26375d..9b1d338f 100644
--- a/src/shared/Components/Toggle.svelte
+++ b/src/shared/Components/Toggle.svelte
@@ -1,70 +1,68 @@
-
-
+
+
diff --git a/src/shared/colors.js b/src/shared/colors.js
new file mode 100644
index 00000000..73d9001f
--- /dev/null
+++ b/src/shared/colors.js
@@ -0,0 +1,10 @@
+/**
+ * Theme colors for console log css
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/console#styling_console_output}
+ */
+export const colors = {
+ inherit: "color: inherit;",
+ blue: "color: light-dark( #317eff, #006fff);",
+ green: "color: light-dark( #2bb239, #60f36c);",
+ yellow: "color: light-dark( #b8722c, #fff600);",
+};
diff --git a/src/shared/dev.js b/src/shared/dev.js
deleted file mode 100644
index 9b1037d2..00000000
--- a/src/shared/dev.js
+++ /dev/null
@@ -1,502 +0,0 @@
-import {parse, uniqueId, wait} from "./utils";
-
-/**
- *
- * @param {("css"|"js")} type
- * @param {boolean?} updates
- * @param {boolean?} longName
- * @returns
- */
-function generateFile(type, updates = false, longName = false, request = false) {
- let canUpdate = updates;
- const uid = uniqueId();
- let name = request ? `${uid}-request-${type}` : `${uid}-example-${type}`;
- if (longName) name = `${uid}${uid}${uid}-example-${type}`;
- const randomDate = +(new Date() - Math.floor(Math.random() * 10000000000));
- let content = "// ==UserScript=="
- + `\n// @name ${name}`
- + `\n// @description Custom description for userscript with name "${name}"`
- + "\n// @match *://*.*"
- + "\n// @exclude-match https://github.com/quoid/userscripts"
- + "\n// @version 1.0"
- + "\n// @noframes"
- + "\n// ==/UserScript=="
- + `\n\nconsole.log("I am ${name}");`;
- if (type === "css") {
- content = content.replace("// ==UserScript==", "/* ==UserStyle==");
- content = content.replace("// ==/UserScript==", "==/UserStyle== */");
- content = content.replaceAll("// @", "@");
- content = content.replace(
- `console.log("I am ${name}");`,
- "#id,\n.class\n.pseudo-element::after {\n color: red\n}"
- );
- canUpdate = false;
- }
- if (request) {
- content = content.replace("// @noframes", "// @noframes\n// @run-at request");
- }
- if (canUpdate) {
- content = content.replace(
- "1.0",
- "1.0\n// @updateURL https://www.k21p.com/example.user.js"
- );
- content = content.replace(
- `console.log("I am ${name}");`,
- `console.log("I am ${name} and you can update me!");`
- );
- }
- return {
- content,
- filename: `${name}.${type}`,
- lastModified: randomDate,
- name,
- request,
- type
- };
-}
-
-const files = [
- generateFile("js", true, true),
- generateFile("css"),
- generateFile("js", false, false, true),
- ...Array.from({length: 7}, () => generateFile("js"))
-];
-
-const _browser = {
- delay: 200,
- platform: "macos", // ios || macos
- runtime: {
- getURL() {
- return "https://www.example.com/";
- },
- async sendMessage(message, responseCallback) {
- const name = message.name;
- console.info(`Got message: ${name}`);
- let response = {};
- if (name === "REFRESH_SESSION_RULES") {
- response = {success: true};
- }
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- },
- async sendNativeMessage(message, responseCallback) {
- const name = message.name;
- console.info(`Got message: ${name}`);
- let response = {};
- if (name === "PAGE_INIT_DATA") {
- response = {
- saveLocation: "/Users/someone/Library/Directory",
- version: "5.0.0",
- build: "55"
- };
- } else if (name === "PAGE_LEGACY_IMPORT") {
- response = {
- active: "true",
- autoCloseBrackets: "true",
- autoHint: "true",
- blacklist: [],
- descriptions: "true",
- languageCode: "en",
- lint: "true",
- log: "false",
- showCount: "true",
- showInvisibles: "true",
- sortOrder: "lastModifiedDesc",
- tabSize: "4"
- };
- } else if (name === "PAGE_ALL_FILES") {
- response = [];
- files.forEach(file => {
- const content = file.content;
- const parsed = parse(content);
- const metadata = parsed.metadata;
- const canUpdate = !!(metadata.version && metadata.updateURL);
- const scriptData = {
- canUpdate,
- content,
- description: metadata.description ? metadata.description[0] : "",
- disabled: false,
- filename: file.filename,
- lastModified: file.lastModified,
- metadata,
- name: metadata.name[0],
- request: file.request,
- // type: file.filename.substring(file.filename.lastIndexOf(".") + 1)
- type: file.type
- };
- response.push(scriptData);
- });
- } else if (name === "TOGGLE_ITEM") {
- response = {success: true};
- // response = {error: true};
- } else if (name === "PAGE_UPDATE_SETTINGS") {
- response = {success: true};
- } else if (name === "PAGE_UPDATE_BLACKLIST") {
- response = {success: true};
- } else if (name === "PAGE_NEW_REMOTE") {
- const result = await getRemoteFileContents(message.url);
- response = result;
- } else if (name === "PAGE_SAVE") {
- const newContent = message.content;
- const oldFilename = message.item.filename;
- const parsed = parse(newContent);
- const lastModified = Date.now();
- let canUpdate = false;
- // script failed to parse
- if (!parsed) {
- return {error: "save failed, file has invalid metadata"};
- }
- const metaName = parsed.metadata.name[0];
- const newFilename = `${metaName}.${message.item.type}`;
- // filename length too long
- if (newFilename.length > 255) {
- return {error: "save failed, filename too long!"};
- }
-
- // check if file can be remotely updated
- if (parsed.metadata.version && parsed.metadata.updateURL) {
- canUpdate = true;
- }
-
- const success = {
- canUpdate,
- content: newContent,
- filename: newFilename,
- lastModified,
- name
- };
-
- // add description if in file metadata
- if (parsed.metadata.description) {
- // const foo = parsed.metadata;
- success.description = parsed.metadata.description[0];
- }
- // check if declarative network request
- if (
- parsed.metadata["run-at"]
- && parsed.metadata["run-at"][0] === "request"
- ) {
- success.request = true;
- }
- // overwriting
- if (newFilename.toLowerCase() === oldFilename.toLowerCase()) {
- saveFile(newContent, lastModified, newFilename, oldFilename);
- return success;
- }
-
- // not overwriting, check if filename for that type is taken
- if (files.find(a => a.filename.toLowerCase() === newFilename.toLowerCase())) {
- return {error: "save failed, name already taken!"};
- }
-
- // not overwriting but all validation passed
- saveFile(newContent, lastModified, newFilename, oldFilename);
- return success;
- } else if (name === "PAGE_UPDATE") {
- const url = parse(message.content).metadata.updateURL;
- await wait(500);
- const result = await getRemoteFileContents(url);
- response = result;
- // response.error = "Something went wrong!";
- // response.info = "No updates found";
- } else if (name === "TOGGLE_EXTENSION") {
- // response = {error: "Failed toggle extension"};
- response = {success: true};
- } else if (name === "POPUP_UPDATE_ALL" || name === "POPUP_UPDATE_SINGLE") {
- // response = {error: "Failed refresh scripts"};
- response = {
- items: [
- {
- name: "Google Images Restored",
- filename: "Google Images Restored.js",
- disabled: false,
- type: "js"
- },
- {
- name: "Wikipedia Mobile Redirect",
- filename: "Wikipedia Mobile Redirect.js",
- disabled: true,
- type: "js"
- },
- {
- name: "A Special Userscript",
- filename: "A Special Userscript.js",
- disabled: false,
- type: "js"
- },
- {
- name: "CSS Adblock",
- filename: "CSS Adblock.css",
- disabled: false,
- type: "css"
- },
- {
- name: "New Userscript With a Really Really Long Name",
- filename: "New Userscript With a Really Really Long Name.css",
- disabled: true,
- type: "css"
- },
- {
- name: "Subframe Script Managerial Staffing Company",
- filename: "Subframe Script.js",
- disabled: false,
- subframe: true,
- type: "css"
- }
- ],
- updates: []
- };
- } else if (name === "POPUP_CHECK_UPDATES") {
- response = {
- updates: [
- {
- filename: "Google Images Restored.js",
- name: "Google Images Restored",
- url: "https://www.k21p.com"
- },
- {
- filename: "New Userscript With a Really Really Long Name.js",
- name: "New Userscript With a Really Really Long Name",
- url: "https://www.filmgarb.com"
- }
- ]
- };
- } else if (name === "POPUP_INIT") {
- response.initData = {
- active: "true",
- items: [
- {
- name: "Google Images Restored",
- filename: "Google Images Restored.js",
- disabled: false,
- type: "js"
- },
- {
- name: "Subframe Script Managerial Staffing Company",
- filename: "Subframe Script.js",
- disabled: false,
- subframe: true,
- type: "css"
- }
- ],
- updates: [
- {
- filename: "Google Images Restored.js",
- name: "Google Images Restored",
- url: "https://www.k21p.com"
- },
- {
- filename: "New Userscript With a Really Really Long Name.js",
- name: "New Userscript With a Really Really Long Name",
- url: "https://www.filmgarb.com"
- }
- ]
- };
- } else if (name === "POPUP_MATCHES") {
- response = {
- matches: [
- ...files,
- {
- name: "Subframe Script Managerial Staffing Company",
- filename: "Subframe Script.js",
- disabled: false,
- subframe: true,
- type: "js"
- }
- ]
- };
- } else if (name === "POPUP_UPDATES") {
- response = {
- updates: [
- {
- filename: "Google Images Restored.js",
- name: "Google Images Restored",
- url: "https://www.k21p.com"
- },
- {
- filename: "New Userscript With a Really Really Long Name.js",
- name: "New Userscript With a Really Really Long Name",
- url: "https://www.filmgarb.com"
- }
- ]
- };
- response.updates = [];
- } else if (name === "REQ_PLATFORM") {
- response = {platform: _browser.platform};
- } else if (name === "POPUP_OPEN_EXTENSION_PAGE") {
- response = {error: "Failed to get page url"};
- window.open("https://github.com/quoid/userscripts");
- } else if (name === "OPEN_SAVE_LOCATION") {
- if (_browser.platform === "macos") {
- response = {success: true};
- } else {
- response = {
- items: [
- {
- name: "Google Images Restored",
- filename: "Google Images Restored.js",
- disabled: false,
- type: "js",
- metadata: []
- },
- {
- name: "Subframe Script Managerial Staffing Company",
- filename: "Subframe Script.js",
- disabled: false,
- type: "css",
- metadata: []
- },
- {
- name: "Another Script from Managerial Staffing Company",
- filename: "Cool Script.js",
- disabled: false,
- type: "js",
- metadata: []
- }
- ]
- };
- }
- } else if (name === "POPUP_INSTALL_CHECK") {
- response = random([
- {success: "Click to install", installed: false},
- {success: "Click to re-install", installed: true}
- ]);
- response.metadata = {
- description: "This userscript re-implements the \"View Image\" and \"Search by image\" buttons into google images.",
- grant: ["GM.getValue", "GM.setValue", "GM.xmlHttpRequest"],
- match: ["https://www.example.com/*", "https://www.example.com/somethingReallylong/goesRightHere"],
- name: "Test Install Userscript",
- require: ["https://code.jquery.com/jquery-3.5.1.min.js", "https://code.jquery.com/jquery-1.7.1.min.js"],
- source: "https://greasyforx.org/scripts/00000-something-something-long-name/code/Something%20something%20long20name.user.js"
- };
- // response.error = "something went wrong (dev)";
- }
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- },
- connectNative: () => ({
- onMessage: {
- addListener: () => console.info("connectNative - addListener")
- }
- })
- },
- tabs: {
- getCurrent(/* responseCallback */) {
- const response = random([
- {url: "https://www.filmgarb.com/foo.user.js", id: 101},
- {url: `${window.location.origin}/src/shared/dev/DEMO.Alert-URL.user.js`, id: 102},
- {url: `${window.location.origin}/src/shared/dev/DEMO.Alert-URL.user.js`, id: 103}, // increase probability
- {url: window.location.href, id: 10}
- ]);
- console.info("browser.tabs.getCurrent", response);
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- },
- query(message, responseCallback) {
- const response = [{url: "https://www.filmgarb.com/foo.user.js", id: 101}];
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- },
- sendMessage(tabId, message, responseCallback) {
- let response = {};
- if (message.name === "DEMO_MSG") {
- response = {};
- // response.error = "something went wrong (dev)";
- }
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- }
- },
- webNavigation: {
- getAllFrames(message, responseCallback) {
- const response = [];
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- }
- },
- storage: {
- local: {
- get(items, responseCallback) {
- const response = {};
- if (!responseCallback) {
- return new Promise(resolve => {
- setTimeout(() => resolve(response), _browser.delay);
- });
- }
- setTimeout(() => responseCallback(response), _browser.delay);
- },
- set() {
- return new Promise(resolve => {
- setTimeout(() => resolve(), _browser.delay);
- });
- },
- remove: () => new Promise(resolve => {
- setTimeout(() => resolve(), _browser.delay);
- }),
- onChanged: {
- addListener: () => undefined
- }
- }
- }
-};
-
-async function getRemoteFileContents(url) {
- const result = {};
- await fetch(url).then(response => {
- if (!response.ok) throw Error(response.statusText);
- return response.text();
- }).then(text => {
- result.content = text;
- }).catch(error => {
- console.error(error);
- result.error = "Remote url bad response!";
- });
- return result;
-}
-
-function saveFile(content, lastMod, newFilename, oldName) {
- const ind = files.findIndex(f => f.filename === oldName);
- const s = {
- content,
- filename: newFilename,
- lastModified: lastMod
- };
- if (ind !== -1) {
- // overwrite at index
- files[ind] = s;
- } else {
- // add to beginning of array
- files.unshift(s);
- }
-}
-
-function random(array) {
- return array[Math.floor(Math.random() * array.length)];
-}
-
-export const browser = _browser;
-
-export default {
- browser: _browser
-};
diff --git a/src/shared/img/icon-bug.svg b/src/shared/img/icon-bug.svg
new file mode 100644
index 00000000..400d41b4
--- /dev/null
+++ b/src/shared/img/icon-bug.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/src/shared/img/icon-loader.svg b/src/shared/img/icon-loader.svg
index b75290bb..64cc3f45 100644
--- a/src/shared/img/icon-loader.svg
+++ b/src/shared/img/icon-loader.svg
@@ -1,4 +1,4 @@
-
-10. **Open Page Link** - *macOS only*, opens the extension browser page
+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
@@ -121,149 +142,189 @@ After installing Userscripts on macOS, you **do not** need to select a userscrip
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
- `@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 - 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
+- `@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`
- - `GM` apis are only available when using `content`
- - 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!**
## API
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.
+> [!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`
- - on success returns a promise resolved with the css string argument provided
+ - `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`
- - on success returns a promise resolved with an object indicating success
+ - `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`
- - on success returns a promise resolved with the value that was set or default value provided
+ - `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`
- - on success returns a promise resolved with an object indicating success
+ - `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()`
- - on success returns a promise resolved with an array of the key names of **presently set** values
+ - 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()`
- - on success returns a promise resolved with `Any` data that is persistent as long as this tab is open
+ - 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`
- - on success returns a promise resolved with an object indicating success
+ - `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`
- - on success returns a promise resolved with the [tab data](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/Tab) for the tab just opened
+ - `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`
- - `tabId` is **optional** and if omitted the tab that called `US.closeTab` will be closed
- - on success returns a promise resolved with an object indicating success
+ - `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` - **required**
- - `type: String` - **optional** and defaults to `text/plain`
- - [read more here](https://developer.mozilla.org/en-US/docs/Web/API/ClipboardEvent/clipboardData)
- - on success returns a promise resolved with a `Bool` indicating success
+ - `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*
+ - 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` - defaults to `GET`
- - `user` - `String`
- - `password` - `String`
- - `headers` - `Object`
- - `overrideMimeType`
- - `timeout` - `Int`
- - `binary` - `Bool`
- - `data` - `String`
- - `responseType` - `String`
- - read more about [XMLHttpRequests here](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
- - event handlers:
- - `onabort` - `function`
- - `onerror` - `function`
- - `onload` - `function`
- - `onloadend` - `function`
- - `onloadstart` - `function`
- - `onprogress` - `function`
- - `onreadystatechange` - `function`
- - `ontimeout` - `function`
- - the response object passed to the event handlers has the following properties:
- - `readyState`
- - `response`
- - `responseHeaders`
- - `responseType`
- - `responseURL`
- - `status`
- - `statusText`
- - `timeout`
- - `withCredentials`
- - `responseText` (when `responseType` is `text`)
- - returns an object with a single property, `abort`, which is a `function`
- - usage: `const foo = GM.xmlHttpRequest({...});` ... `foo.abort()` to abort the request
+ - `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)`
- - an alias for `GM.xmlHttpRequest`, works exactly the same
+ - 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
@@ -277,7 +338,7 @@ This is the directory where the app/extension will read from and write to. This
## Getting Help
-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!*
+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
@@ -299,35 +360,32 @@ If you encounter a problem while using this app/extension or are in need of some
**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.
-Further, any issue marked "help wanted" is actively seeking assistance. Please respond to those issues with feedback, guidance or offers of coding assistance.
+Code level contributions please refer to [contributing.md](docs/contributing.md)
-Notes:
-- use [semantic commit messages](https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716)
-- under most circumstances, you should fork the most current version of the `develop` branch for your contributions
+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 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.
-**[iOS Beta Sign Up Form](https://forms.gle/QB46uYQHVyCxULue9)**
-
-**[macOS Beta Sign Up Form](https://forms.gle/cUDtKg1ip4Vc9Xhc7)**
+**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 (c) 2022 Justin Wasack
+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
index 4f9de8ad..3cb92e9d 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,14 +1,33 @@
# 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
-### `master`: default branch
+### `main`: default branch
+
- corresponding to development channel
- all development work around this branch
- protected branches not accept commits
@@ -16,6 +35,7 @@ For development and build environments please refer to [development guide](dev.m
- 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
@@ -23,6 +43,7 @@ For development and build environments please refer to [development guide](dev.m
- 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
@@ -30,6 +51,7 @@ For development and build environments please refer to [development guide](dev.m
- always merge back into master branch
# Commits
+
### Please use semantic commit messages
Format: `