--- name: scriptcat-userscript description: "Write, fix and debug userscripts for ScriptCat (Tampermonkey-compatible): page scripts that run on matching sites (@match), background scripts that keep running without a page (@background) and scheduled scripts (@crontab); metadata, @grant and the GM_* / GM.* / CAT_* APIs, user config, retries. When the sctl CLI is connected, install the script into the user's ScriptCat and verify it in their real browser. Use whenever the user wants a userscript, 油猴脚本, 后台脚本, 定时脚本, a .user.js file or a ScriptCat script written, changed or debugged. Not for developing the ScriptCat extension itself, and not for managing installed scripts without changing their code (that is the sctl skill)." --- # Writing ScriptCat userscripts ScriptCat runs Tampermonkey-style userscripts and adds two kinds of its own: background scripts and scheduled scripts, which run in the extension's background sandbox instead of a web page. Most Tampermonkey knowledge carries over; the differences below are the ones that break scripts. **Authority.** The API surface is `scriptcat.d.ts` — in this repository `src/types/scriptcat.d.ts`, otherwise . Working examples live in . The developer docs at can lag behind the types; when they disagree, trust the types. ## 1. Pick the script type | The script must… | Type | Key metadata | |---|---|---| | Change, read or automate a web page | Page script | `@match` / `@include`, `@run-at` | | Keep running while the browser is open, with no page (listeners, polling, a menu in the popup) | Background script | `@background` | | Run on a schedule (check-in, sync, report, periodic fetch) | Scheduled script | `@crontab ` | Background and scheduled scripts have **no web page**: no `document` of any site, no `unsafeWindow` page, no `GM_getTab`/`GM_saveTab`. To touch a page from the background, open it with `GM_openInTab` and let a page script do the DOM work, or fetch data with `GM_xmlhttpRequest` instead of scraping a rendered page. ## 2. Start from the right skeleton These match the templates ScriptCat's own "new script" uses. ```js // ==UserScript== // @name Example page script // @namespace https://example.com/your-namespace // @version 0.1.0 // @description What it does, in one line // @author You // @match https://example.com/* // @grant none // @noframes // ==/UserScript== (function () { "use strict"; // ... })(); ``` ```js // ==UserScript== // @name Example background script // @namespace https://example.com/your-namespace // @version 0.1.0 // @description What it does, in one line // @author You // @background // @grant GM_xmlhttpRequest // @grant GM_notification // ==/UserScript== return new Promise((resolve, reject) => { // ... resolve() when the work is really finished, reject(err) on failure }); ``` A scheduled script is the background skeleton with `@crontab * * once * *` (or another expression) in place of `@background`. Background and scheduled bodies are wrapped in a function by ScriptCat, so a top-level `return` is legal there. ## 3. Rules that break scripts when ignored **Identity and updates** - `@name` + `@namespace` identify a script. Keep both stable once the user has installed it; changing either makes a different script. Bump `@version` on every change you hand back. - A page script cannot become a background or scheduled script (or the reverse) under the same `@name` + `@namespace`: ScriptCat rejects that install with a script type mismatch. Give a temporary script of the other type its own `@name`. **Permissions** - Every API needs a `@grant` line (`@grant GM_xmlhttpRequest`, …). An ungranted API is simply undefined at runtime. Granting `GM_foo` also exposes `GM.foo` and vice versa — only when the names match exactly: `GM.xmlHttpRequest` needs its own `@grant GM.xmlHttpRequest` (`@grant GM_xmlhttpRequest` does not expose it). - `GM_info` needs no grant. `unsafeWindow` needs no grant either, but only exists in the sandbox (any grant other than `none`, or no `@grant` line at all); `@grant unsafeWindow` is harmless. - `@grant none` runs the script without the sandbox: `window` is the page's own window, and the only API is `GM_info` / `GM.info` — no other GM API and **no `unsafeWindow`** (referencing it throws a `ReferenceError`). Use it only for scripts that need nothing but the page. - With any other grant — and also with no `@grant` line at all, unlike Tampermonkey — the script is sandboxed: its `window` is not the page's. Reach page globals (a site's own JS objects, variables it defines) through `unsafeWindow`. - Declare every host you request with `@connect ` (it also covers the host's subdomains; `@connect self` covers subdomains of the page's host; requests to exactly the page's host need nothing). For a host that is not covered, `GM_xmlhttpRequest` is **refused** ("This domain is not a part of the @connect list") as soon as the script has any `@connect` line, unless the user allowed that host before; only a script with no `@connect` at all asks the user instead. `GM_download` in native mode always asks, and `GM_cookie` throws for a host outside `@connect`. **Page timing and SPAs** - `@run-at`: `document-start` (as early as possible), `document-end` (DOM parsed), `document-idle` (the default; everything loaded), `document-body` (wait until `` exists), `context-menu` (run when the user picks the script from the page's right-click menu). Only the first value counts, and an unknown value silently falls back to the default. - Add `@early-start` together with `document-start` when the script must beat the page's own scripts, and wait for `CAT_scriptLoaded()` before relying on the full API. - Single-page apps change the URL without reloading, so a page script runs once and then misses later views. Listen with `@grant window.onurlchange` and `window.addEventListener("urlchange", e => …)`, and use a `MutationObserver` for content that renders late. Never assume an element exists at injection time — wait for it. - `@noframes` keeps the script out of iframes; without it, a `*://*/*` match also runs inside every iframe. - `@inject-into content` runs in the content-script world: unaffected by the page's CSP, but `unsafeWindow` is then not the page's `window`. The default is `page`. - `GM_addStyle` and `GM_addElement` bypass the page's CSP; prefer them over creating `