ScriptVault

---

Project Planning And Research

Project planning is kept in local-only markdown files in the working checkout.

• ROADMAP.md - single source of truth for incomplete planned work.
• RESEARCH.md - consolidated research conclusions and evidence.
• CHANGELOG.md - shipped release ledger.

Features

Professional Security Workbench

ScriptVault uses a focused desktop workbench with a persistent navigation rail, command search, live vault health metrics, site and saved-view filters, progressive row actions, and a contextual trust/access/activity inspector. The popup, side panel, install review, DevTools diagnostics, and full-screen editor share the same accessible four-theme surface system. Dark, light, Catppuccin, and OLED dashboard layouts are protected by browser-rendered visual regression baselines.

GM API — 35+ Functions

Full Greasemonkey/Tampermonkey API compatibility with promise-based GM.* async variants.

Storage	Network	UI	Utilities
GM_getValue	GM_xmlhttpRequest	GM_addStyle	GM_info
GM_setValue	GM_download	GM_notification	GM_log
GM_deleteValue	GM_webRequest	GM_registerMenuCommand	GM_setClipboard
GM_listValues		GM_unregisterMenuCommand	GM_openInTab
GM_getValues		GM_getMenuCommands	GM_getResourceText
GM_setValues	GM_webSocket	GM_addElement	GM_getResourceURL
GM_deleteValues	GM_head	GM_loadScript	GM_cookie
GM_addValueChangeListener	GM.fetch	GM_audio	GM_focusTab
GM_removeValueChangeListener

Plus GM_getTab, GM_saveTab, GM_getTabs for cross-tab state, window.close, window.focus, window.onurlchange grants, @top-level-await, @delay, and @nodownload support.

TypeScript userscripts can reference lib/scriptvault.d.ts for generated ambient declarations that match ScriptVault's GM API surface.

GM.fetch returns a Fetch-compatible Response; modern browser contexts expose res.body as a ReadableStream so scripts can read cross-origin responses chunk-by-chunk while ScriptVault still applies the script's @connect hosts and internal-host guards. Older contexts fall back to the existing GM_xmlhttpRequest response path.

Scripts can opt into a per-script isolated cookie jar with @isolationCookie. ScriptVault maps that script to a deterministic CHIPS partition for GM_cookie, GM_xmlhttpRequest, and GM_download cookie routing; explicit partitionKey or cookiePartition options still override the automatic jar.

SPA URL Changes

Scripts that need to re-run on soft navigation can grant window.onurlchange. ScriptVault dispatches it for Navigation API route changes, history updates, popstate, and hashchange without requiring an extra extension permission. Keep handlers idempotent and re-check the DOM when the target app renders asynchronously:

// ==UserScript==
// @grant window.onurlchange
// ==/UserScript==
function apply() {
  // Rebind or refresh page-specific UI here.
}
window.addEventListener('urlchange', ({ url, oldUrl }) => {
  apply();
});
apply();

Trusted Types and MAIN-world DOM Writes

Most ScriptVault scripts run in the browser USER_SCRIPT world. That world is separate from the page Trusted Types policy, so GM_addElement, GM_addStyle, and normal DOM creation keep working on sites that enforce require-trusted-types-for 'script'.

If a script intentionally switches to MAIN/page context or uses unsafeWindow, the page policy applies. Avoid assigning raw strings to innerHTML, outerHTML, script URLs, or inline event handlers there. Prefer textContent, append, createElement, and GM_addElement with attributes. If the target site requires a TrustedHTML object, use a policy approved by that site; do not create a broad passthrough policy just to bypass CSP.

Script Management

• Auto-detect installation — Navigate to any .user.js URL
• One-click toggle — Enable/disable scripts individually or globally
• Auto-updates — Configurable update intervals that default to notify-only queued review
• Update inbox — Review pending updates with diff, permission, source, and rollback context before install
• Per-script update check — Check and queue updates for individual scripts inline
• Run on Tab — Run any script once from the popup or dashboard without changing permanent registration (Chromium 135+)
• Version tracking — Installed vs. available version comparison
• Tags & search — Organize and filter scripts by name, description, or metadata
• Popup quick-edit — Click any script in the toolbar popup to jump straight into the editor
• Find Scripts — Search and install userscripts from Greasy Fork and other sources directly in the dashboard
• Bulk operations — Select multiple scripts to enable, disable, update, reset, or delete with progress tracking
• Per-script export — Export individual scripts as .user.js files
• Script templates — New Script opens a blank editor instantly; built-in starter templates (page modifier, CSS injector, API interceptor, and more) live in the editor's template manager
• Version rollback — Auto-saves last 3 versions on update; one-click rollback from info panel
• Storage quota monitor — Visual quota bar with warning when approaching the real storage quota (unlimitedStorage-aware)
• Bucketed IndexedDB storage — Separates script records, GM values, and backup blobs through Storage Buckets when Chrome exposes navigator.storageBuckets, with single-DB fallback elsewhere
• Tag filtering — Filter scripts by @tag metadata in the dashboard dropdown
• Drag-and-drop install — Drop .user.js or .zip files onto the dashboard to install
• Shift+click multi-select — Select ranges of scripts with Shift+click
• Library browser — Search and add CDN libraries (@require) from cdnjs directly in the editor
• Advanced filters — Filter scripts by grant type, error status, update URL, scope breadth, or tags

Advanced URL Matching

• Full @match, @include, @exclude, @exclude-match support
• User overrides — Add custom match patterns without editing script code
• Per-pattern toggles — Disable individual original patterns per-script
• Glob and regex pattern support

Per-Site Control

ScriptVault has three independent layers for stopping scripts from running on a given site, all reachable from Settings (and the popup's "Run only on this domain" / "Do not run on this domain" quick actions):

Layer	Behavior	Setting
Denied hosts	Block every script on listed hosts. Highest priority — overrides script @match patterns.	deniedHosts (array of hostnames)
Blacklist mode (default)	Run scripts everywhere except on URLs listed in blacklistedPages (one per line, glob-style patterns).	pageFilterMode: 'blacklist' + blacklistedPages
Whitelist mode	Run scripts only on URLs listed in whitelistedPages. Nothing else triggers a script.	pageFilterMode: 'whitelist' + whitelistedPages

Per-script @match/@include/@exclude still apply on top of these global gates. The popup chip flips a single domain in or out of the active list in one click.

Cloud Sync

Sync scripts across devices with 6 providers:

Provider	Method
WebDAV	Self-hosted or any WebDAV server
Local folder	Browser-selected folder with scriptvault-backup.json for self-managed backups
Google Drive	OAuth2 integration
Dropbox	App folder sync
OneDrive	Microsoft account integration
S3-compatible	AWS S3, Cloudflare R2, MinIO, Backblaze B2, and other S3 endpoints

Two additional zero-config flows ship as separate modules: Easy Cloud for one-click Google Drive sync via chrome.identity, and GitHub Gist import/export/sync via a personal access token.

Session-only credentials — Sync provider secrets and encryption passphrases can be kept in chrome.storage.session (cleared on browser restart) instead of stored at rest. No other MV3 userscript manager offers this mode.

Monaco Editor

• Monaco Editor — Same editor that powers VS Code, loaded in a sandboxed iframe
• Tabbed editing — Open multiple scripts simultaneously with browser-style tabs (middle-click to close)
• Unsaved indicators — Visual dot on tabs with pending changes
• 5 editor themes — Auto (system, follows OS dark/light preference), Dark, Light, Catppuccin Mocha, OLED
• Status bar — Line count and cursor position display
• IntelliSense — Autocomplete for GM API functions and @metadata directives, backed by generated ScriptVault GM declarations in the Monaco sandbox
• Code folding, bracket matching, bracket pair colorization, auto-close
• Search & replace (Ctrl+F / Ctrl+H)
• Real-time userscript metadata linting
• Code beautifier — One-click indentation normalization