super-clipboard / userscripts

English ｜ 简体中文

A community-maintained collection of user scripts.

Repo Layout

package.json                      # name = @ziuchen/super-clipboard-userscripts
scripts/<id>/<id>.user.js         # script body, must contain a ==UserScript== block
scripts/<id>/README.md            # optional usage notes / screenshots
scripts/_template/                # copy this directory to start a new script (dirs starting with `_` are skipped)
scripts/build-manifest.mjs        # manifest builder; runs automatically as `prepublishOnly`
.github/workflows/publish.yml     # pushing a `v*` tag → publishes to npm via OIDC

Contributing a Script

1. Copy scripts/_template/ to scripts/<your-id>/. The directory name is the script id (kebab-case).
2. Rename _template.user.js → <your-id>.user.js. Fill in the ==UserScript== block.
3. The manifest is generated entirely from the ==UserScript== header — no meta.json needed.
4. Open a pull request. After merging, a maintainer will publish a new release.

UserScript Header Reference

Standard directives (@name, @version, @description, @author, @homepage, @namespace, @updateURL, @require, @grant, @run-at) work as in Tampermonkey. Two extras are recognised by the manifest builder:

// @match-clip   text          // repeatable: text | image | file
// @match-clip   image
// @tag          ocr           // repeatable: free-form tags shown in the market UI
// @tag          background
// @preinstall   true          // optional, defaults to false

Script API Cheat Sheet

// Register a context-menu command
globalNativeApi.registerMenuCommand("My Command", async (ctx) => {
  if (!ctx.clip) return;
  const body = await globalNativeApi.getClipBody(ctx.clip);
  const text = body?.text ?? body?.preview ?? "";

  // Common operations:
  utools.copyText(text); // write back to clipboard
  globalNativeApi.notification({ title, body }); // show a notification
  document.body.innerHTML = "..."; // build a UI
  await globalNativeApi.showPanel({ width, height, placement: "center" });
});

@match-clip text (or image, file) controls when the command is offered. External libraries can be loaded via // @require <url>.

Local Development

npm install
npm test                    # node:test, exercises lib/ helpers
npm run build               # generates manifest.json

Release (maintainers only)

npm version patch          # or minor / major
git push --follow-tags

publish.yml rebuilds the manifest and publishes to npm via an OIDC trusted publisher.

License

MIT