Make websites work a little more like you want.

Start here

How @grant works

For new scripts, declare every privileged API you use. Social Browser runs scripts with explicit grants in an isolated User Script world and bridges only the requested capabilities. A script with @grant none runs without GM capabilities.

// ==UserScript==// @name Remember display mode// @namespace https://example.com/my-scripts// @match https://example.com/*// @grant GM_getValue// @grant GM_setValue// ==/UserScript== const mode = GM_getValue('displayMode', 'compact');console.log('Saved mode:', mode); GM_setValue('displayMode', 'comfortable');

Classic GM_* or modern GM.*?

Social Browser supports the familiar classic names and their modern GM.* forms for the main GM capability set. The modern form is Promise-friendly, so use await. Pick one style per script and stay consistent.

const theme = GM_getValue('theme', 'dark');GM_setValue('theme', 'light');

const theme = await GM.getValue('theme', 'dark');await GM.setValue('theme', 'light');

GM_info / GM.info

Use script information when you need to inspect the current script, version, grants, matches or Social Browser runtime information. Do not hard-code behavior around version strings unless you really need compatibility logic.

// @grant GM_info console.log('Script:', GM_info.script.name);console.log('Version:', GM_info.version);console.log('Handler:', GM_info.scriptHandler);console.log('Grants:', GM_info.scriptGrants);console.log('Matches:', GM_info.scriptMatches);

Storage

Remember small script data

GM storage is scoped to the User Script instead of being ordinary page storage. It is ideal for harmless preferences, counters and script state. Do not use it as a casual vault for passwords, 2FA secrets, cookies or session material.

// @grant GM_getValue// @grant GM_setValue// @grant GM_deleteValue const settings = GM_getValue('settings', { compact: true, rowsPerPage: 25}); settings.rowsPerPage = 50;GM_setValue('settings', settings); // Reset later if the user asks for defaults.// GM_deleteValue('settings');

Watch a value change

GM_addValueChangeListener is useful when the same script is open in more than one frame or tab. The callback receives (name, oldValue, newValue, remote). In Social Browser, value-change events can synchronize across frames/tabs in the same Profile/session.

// @grant GM_addValueChangeListener// @grant GM_removeValueChangeListener const listenerId = GM_addValueChangeListener( 'displayMode', (name, oldValue, newValue, remote) => { console.log({ name, oldValue, newValue, remote }); }); // Remove it when you no longer need it.// GM_removeValueChangeListener(listenerId);

Page helpers

Add styles or small elements

GM_addStyle(css) / GM.addStyle(css)

Use this when a page customization is mostly visual. It is cleaner than setting many individual element.style properties.

// @grant GM_addStyle GM_addStyle(` .important-total { font-weight: 700; outline: 2px solid currentColor; padding: 4px 8px; }`);

GM_addElement(...) / GM.addElement(...)

Create a small DOM element and append it safely. You can pass a parent element first, or omit it to use the page body.

// @grant GM_addElement const panel = document.querySelector('#account-panel');if (panel) { GM_addElement(panel, 'button', { type: 'button', textContent: 'Copy account ID', className: 'my-copy-button', onclick() { const id = panel.querySelector('.account-id')?.textContent?.trim(); if (id) navigator.clipboard.writeText(id); } });}

Réseau

Make privileged requests with GM_xmlhttpRequest

Normal page fetch() is controlled by the page's normal browser/CORS rules. Social Browser's GM request API uses a dedicated browser-process request channel. Before a request is sent, its destination is checked against the script's @connect rules.

// ==UserScript==// @match https://app.example.com/*// @connect api.example.com// @grant GM_xmlhttpRequest// ==/UserScript== const response = await GM_xmlhttpRequest({ method: 'GET', url: 'https://api.example.com/status', responseType: 'json', timeout: 10000, headers: { Accept: 'application/json' }}); console.log(response.status, response.response);

Callbacks and abort

The request API supports common request callbacks and returns a handle that can be aborted. Use a timeout even when you also support aborting.

// @connect api.example.com// @grant GM_xmlhttpRequest const request = GM_xmlhttpRequest({ url: 'https://api.example.com/slow-report', timeout: 15000, onload(response) { console.log('Loaded:', response.status); }, onerror(error) { console.error('Request failed:', error); }, ontimeout() { console.warn('Request timed out'); }, onabort() { console.log('Request aborted'); }}); // Cancel only if your script no longer needs the result.// request.abort();

Modern form: GM.xmlHttpRequest(...) and GM.xmlhttpRequest(...) map to the same request capability.

Resources

Bundle reusable text, CSS or other assets

Declare an asset with @resource, then read it by name. GM_getResourceText returns decoded text. GM_getResourceURL returns a data URL that preserves the response MIME type.

// ==UserScript==// @resource helperCss https://example.com/assets/helper.css// @grant GM_getResourceText// @grant GM_getResourceURL// ==/UserScript== const css = await GM_getResourceText('helperCss');console.log(css); const dataUrl = await GM_getResourceURL('helperCss');console.log(dataUrl);

If the resource name does not exist, the API returns undefined. Keep resource names short and descriptive.

Browser helpers

Tabs, notifications and clipboard

GM_openInTab(url, options)

Open a URL in a Social Browser tab. Use active: false when the new tab should open without taking focus.

// @grant GM_openInTab GM_openInTab('https://example.com/report', { active: false});

Per-tab script state: GM_getTab, GM_saveTab, GM_getTabs

These APIs store small User Script state associated with tabs. They are useful when a script needs to remember which step or view belongs to a particular tab without mixing it with global script preferences.

// @grant GM_getTab// @grant GM_saveTab// @grant GM_getTabs const tabState = await GM_getTab();await GM_saveTab({ ...tabState, lastPanel: 'orders'}); const allScriptTabs = await GM_getTabs();console.log(allScriptTabs);

GM_notification

Show a browser notification for something the user should actually notice. Avoid notification spam for routine script activity.

// @grant GM_notification await GM_notification({ title: 'Report ready', text: 'The page data is ready to review.'});

GM_setClipboard(data, type)

Copy text (or HTML when requested) to the clipboard. Use it after a clear user action when possible, so the user understands why their clipboard changed.

// @grant GM_setClipboard const orderId = document.querySelector('.order-id')?.textContent?.trim();if (orderId) { GM_setClipboard(orderId, 'text');}

Menus & downloads

Add deliberate user actions

GM_registerMenuCommand / GM_unregisterMenuCommand

Register a command in the User Script menu. This is a good pattern for actions that should happen only when the user explicitly asks for them.

// @grant GM_registerMenuCommand// @grant GM_unregisterMenuCommand const commandId = GM_registerMenuCommand( 'Highlight overdue rows', () => { document.querySelectorAll('.row.overdue').forEach((row) => { row.style.fontWeight = '700'; }); }); // Remove the menu item later if the script no longer needs it.// GM_unregisterMenuCommand(commandId);

GM_download

Start a download through Social Browser. Give the file a clear name and use this only when downloading is part of the script's visible purpose.

// @grant GM_download await GM_download({ url: 'https://example.com/reports/today.csv', name: 'today-report.csv'});

Advanced

unsafeWindow: bridge to page globals only when necessary

Explicit-grant User Scripts normally run in an isolated world. unsafeWindow is an opt-in bridge to globals in the page's MAIN world. Use it only when the website exposes a page variable or function that ordinary isolated script access cannot reach.

// @grant unsafeWindow const appVersion = unsafeWindow.appConfig?.version;if (appVersion) { console.log('Page app version:', appVersion);}

Execution-world rule

Complete example

A small script that combines storage, styles, menu commands and clipboard

This example stays intentionally small. It remembers whether highlighting is enabled, adds one style rule, lets the user toggle it from the User Script menu, and copies a visible page value only when asked.

// ==UserScript==// @name Helpful order-page tools// @namespace https://example.com/my-scripts// @version 1.0.0// @match https://example.com/orders/*// @grant GM_getValue// @grant GM_setValue// @grant GM_addStyle// @grant GM_registerMenuCommand// @grant GM_setClipboard// ==/UserScript== (() => { 'use strict';  GM_addStyle(` .sb-order-highlight { outline: 2px solid currentColor; font-weight: 700; } `);  const applyHighlight = () => { const enabled = GM_getValue('highlightEnabled', true); document.querySelectorAll('.order-total').forEach((element) => { element.classList.toggle('sb-order-highlight', enabled); }); };  GM_registerMenuCommand('Toggle order highlighting', () => { const current = GM_getValue('highlightEnabled', true); GM_setValue('highlightEnabled', !current); applyHighlight(); });  GM_registerMenuCommand('Copy current order ID', () => { const orderId = document.querySelector('.order-id')?.textContent?.trim(); if (orderId) { GM_setClipboard(orderId, 'text'); } });  applyHighlight();})();