Safari Browser Scripts# PRO

Safari Browser Scripts let Scripting run userscripts in Safari through the Safari Web Extension. The runtime supports Greasemonkey-style GM.* APIs and selected Scripting APIs.

#Where Scripts Run

There are two sources:

• browser.tsx in a Scripting script project. It is built to browser.js.
• Installed .user.js / .js files from Safari's extension popup.

Scripts installed from Safari's extension popup are stored under:

scripting-safari-extension/userscripts/

Downloads and GM storage live in the same root:

scripting-safari-extension/downloads/
scripting-safari-extension/storages/

This root follows the Safari Browser Data storage location configured in Settings, including WebDAV when enabled.

#Script Format

Create or install a .user.js / .js file with a userscript metadata block:

// ==UserScript==
// @name GitHub Demo
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

GM.log("loaded", location.href)

Common metadata keys:

// @name
// @namespace
// @version
// @description
// @author
// @match
// @include
// @exclude
// @exclude-match
// @connect
// @grant
// @require
// @resource
// @run-at document-start | document-body | document-end | document-idle
// @inject-into auto | content | page
// @weight 1..999
// @noframes
// @homepageURL
// @supportURL
// @updateURL
// @downloadURL
// @license

@weight controls execution order when multiple scripts match the page. Larger weights run first. If no @run-at is provided, scripts run at document-end.

@inject-into defaults to auto. With auto, a script that declares any @grant (GM.* or Scripting.*) runs in the content world (privileged APIs available, isolated from the page's JavaScript), while a script with @grant none or no grant runs in the page world (shares the page's real window, can read page globals). Use @inject-into content or @inject-into page to force a world explicitly. GM.*, Scripting.*, and extension messaging are only available in the content world; grants are ignored in the page world. On pages whose Content-Security-Policy blocks injected scripts, auto page-world scripts automatically fall back to the content world.

#Permissions

Privileged APIs must be declared with @grant.

// @grant GM.getValue
// @grant GM.setValue
// @grant GM.xmlHttpRequest
// @grant GM.cookie
// @grant Scripting.FileManager

@grant none disables GM APIs, but GM_info and GM.info remain available for compatibility.

Cross-origin network, download, resource, and cookie access must be allowed with @connect.

// @connect api.github.com
// @connect https://api.github.com/*
// @connect *

When a required grant or connect rule is missing, the runtime throws an error with a stable code such as permissionDenied or connectDenied.

#GM_info

GM_info and GM.info expose parsed metadata and runtime details:

GM_info.script.name
GM_info.script.version
GM_info.script.matches
GM_info.script.connects
GM_info.script.runAt
GM_info.script.injectInto
GM_info.script.weight
GM_info.scriptHandler
GM_info.version

#Supported GM APIs

#Storage

await GM.getValue(key, defaultValue)
await GM.setValue(key, value)
await GM.deleteValue(key)
await GM.listValues()

const id = GM.addValueChangeListener(key, (key, oldValue, newValue, remote) => {})
GM.removeValueChangeListener(id)

GM storage is stored as JSON under scripting-safari-extension/storages/.

#DOM and Menu

GM.log(...items)
GM.addStyle(css)
GM.addElement("div", { textContent: "Hello" })
GM.addElement(document.body, "button", { textContent: "Run" })

const id = GM.registerMenuCommand("Run", () => {})
GM.unregisterMenuCommand(id)
GM.removeMenuCommand(id)

Menu commands are shown in Safari's extension popup for the current page.

#Tabs, Clipboard, Notification

const tab = await GM.openInTab("https://github.com/trending", { active: false })
tab.close()
await GM.closeTab()

await GM.setClipboard("Hello")
await GM.notification({ title: "Scripting", text: "Done" })

GM.closeTab() closes the current tab when supported by Safari. GM.openInTab() returns a tab control with close().

#Resources

const text = await GM.getResourceText("name")
const url = await GM.getResourceURL("name")

Declare resources in the metadata block:

// @resource name https://example.com/file.txt

#Download

await GM.download({
  url: "https://example.com/file.txt",
  name: "file.txt",
  onload(response) {
    GM.log(response.path)
  }
})

Downloaded files are stored under scripting-safari-extension/downloads/.

#XHR

await GM.xmlHttpRequest({
  method: "GET",
  url: "https://api.github.com/zen",
  responseType: "text",
  overrideMimeType: "text/plain",
  onloadstart(event) {},
  onprogress(event) {},
  onreadystatechange(response) {},
  onload(response) {},
  onloadend(response) {}
})

The runtime supports responseType values text, json, arraybuffer, blob, and document, plus user, password, headers, data, timeout, binary, overrideMimeType, upload callbacks, finalUrl, and responseURL.

#Cookies

await GM.cookie.set({
  url: location.href,
  name: "scripting_test",
  value: "1",
  path: "/",
  secure: true
})

const cookies = await GM.cookie.list({ url: location.href, name: "scripting_test" })
await GM.cookie.delete({ url: location.href, name: "scripting_test" })

Callback style is also supported:

GM.cookie.list({ url: location.href }, cookies => {
  GM.log(cookies)
})

#Scripting.FileManager

Use @grant Scripting.FileManager or @grant Scripting.* to access the API.

#Properties

Scripting.FileManager.documentsDirectory: string
Scripting.FileManager.iCloudDocumentsDirectory: string | null
Scripting.FileManager.appGroupDocumentsDirectory: string | null
Scripting.FileManager.safariBrowserDirectory: string
Scripting.FileManager.safariBrowserStorageDirectory: string
Scripting.FileManager.safariBrowserDownloadsDirectory: string
Scripting.FileManager.safariBrowserUserscriptsDirectory: string
Scripting.FileManager.isiCloudEnabled: boolean

In regular Scripting app scripts, the same Safari data directories are available as FileManager.safariBrowserDirectory, FileManager.safariBrowserStorageDirectory, FileManager.safariBrowserDownloadsDirectory, and FileManager.safariBrowserUserscriptsDirectory.

#Methods

await Scripting.FileManager.readAsString(path)
await Scripting.FileManager.writeAsString(path, contents)
await Scripting.FileManager.createDirectory(path, true)
await Scripting.FileManager.readDirectory(path)
await Scripting.FileManager.exists(path)
await Scripting.FileManager.remove(path)

All file operations are limited to directories exposed by Scripting.FileManager.

#Scripting.tabs

Use @grant Scripting.tabs (or @grant Scripting.*) to enumerate and switch the real open Safari tabs.

This is different from GM.getTabs, which is a per-script storage bus that only returns data your own script saved with GM.saveTab — it does not list real tabs or their URLs. Scripting.tabs returns the actual open tabs.

#Methods

const tabs = await Scripting.tabs.query()        // all open tabs
const current = await Scripting.tabs.getCurrent() // the tab this script runs in, or null
await Scripting.tabs.activate(tabs[0].id)         // switch focus to an already-open tab

Each tab is a ScriptingTabInfo:

interface ScriptingTabInfo {
  id: number | null
  url: string
  title: string
  active: boolean
  index: number
  windowId: number
  pinned: boolean
}

To open a new tab use GM.openInTab(url); to close a tab use GM.closeTab(id) with an id from query(). Scripting.tabs.activate() only switches focus and never opens a new tab. On a single Safari window, activate() selects the tab; across separate windows it selects the tab within its own window.

Privacy: A script granted Scripting.tabs can read the URL and title of every open tab, not just the page it runs in. Only grant it to scripts you trust. Userscripts run only for PRO users, require the Scripting extension to be allowed on the page, and must declare this grant explicitly.

#Installed Scripts

Safari's extension popup can install userscripts from the current page or from a URL. Installed scripts can be enabled, disabled, updated, or deleted in the popup and in Tools > Development > Safari Browser Scripts.

Use the Tools page to inspect:

• Installed userscripts.
• GM storage JSON files.
• Downloads created by GM.download.

#Example

// ==UserScript==
// @name Save Page URL
// @match https://github.com/*
// @grant GM.log
// @grant Scripting.FileManager
// ==/UserScript==

const fm = Scripting.FileManager
const dir = `${fm.appGroupDocumentsDirectory ?? fm.documentsDirectory}/Safari Notes`
const file = `${dir}/last-url.txt`

await fm.createDirectory(dir)
await fm.writeAsString(file, location.href)

GM.log(await fm.readAsString(file))