sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/gm-notification.js

@@ -0,0 +1,141 @@
+// SW-side `GM_notification` dispatcher.
+//
+// chrome.notifications wrapping. The page sends a details object
+// describing the notification; we call chrome.notifications.create
+// and remember the (chromeNotificationId ↔ originator + requestId)
+// mapping so onClicked / onClosed can be routed back.
+//
+// chrome.notifications has its own assigned-id mechanism (we can
+// pass an explicit notificationId or "" to have Chrome assign one).
+// We always let Chrome assign — keeps our requestId space cleanly
+// page-side and avoids collisions between userscripts.
+import { dropEntriesForOriginator } from './gm-originator-map.js';
+import { hasAllowedScheme, WEB_SCHEMES } from './gm-url-scheme.js';
+const byChromeId = new Map();
+// One string for the two guards that check the same thing: this one and
+// `handleNotificationShow` in `background.ts`, which rejects before it
+// ever calls in here. Names the browser permission the reader would go
+// looking for rather than the API object we happened to test.
+export const NOTIFICATIONS_UNAVAILABLE = 'this browser will not show notifications to SourceMonkey; check the extension\'s notification permission';
+// Page-supplied notification image. Chrome fetches `iconUrl` from the
+// privileged extension context, so we only honor http(s) / data: URLs.
+// A `file://` or `chrome-extension://` image would let a script probe
+// local files / packaged resources through the extension; reject those
+// and fall back to the default icon.
+function isAllowedIconUrl(image) {
+    return hasAllowedScheme(image, [...WEB_SCHEMES, 'data:']);
+}
+// Pick the icon URL chrome.notifications wants. The user-supplied
+// image is preferred when it's an allowed scheme; otherwise we fall
+// back to the extension's own icon so chrome.notifications doesn't
+// reject the create call (iconUrl is required by the API).
+function pickIconUrl(image) {
+    if (image && isAllowedIconUrl(image))
+        return image;
+    try {
+        return chrome.runtime.getURL('icons/icon-128.png');
+    }
+    catch {
+        return '';
+    }
+}
+export async function showGmNotification(payload, originatorTabId) {
+    // Defense in depth — handleNotificationShow already guards this,
+    // but a future direct caller (test surface, retry path) shouldn't
+    // crash if the API is missing.
+    if (!chrome.notifications) {
+        return { ok: false, error: NOTIFICATIONS_UNAVAILABLE };
+    }
+    const d = payload.details;
+    const options = {
+        type: 'basic',
+        iconUrl: pickIconUrl(d.image),
+        title: d.title || 'SourceMonkey',
+        message: d.text,
+        silent: d.silent,
+    };
+    try {
+        // The installed @types/chrome declares the callback form only,
+        // but chrome.notifications.create is Promise-returning in MV3.
+        // Wrap to avoid the type mismatch and stay forward-compatible.
+        const chromeId = await new Promise((res, rej) => {
+            try {
+                chrome.notifications.create('', options, (id) => {
+                    if (chrome.runtime.lastError) {
+                        rej(new Error(chrome.runtime.lastError.message ?? 'notifications.create failed'));
+                        return;
+                    }
+                    res(id);
+                });
+            }
+            catch (e) {
+                rej(e);
+            }
+        });
+        const entry = {
+            originatorTabId,
+            requestId: payload.requestId,
+            scriptId: payload.scriptId,
+            timeoutTimer: null,
+        };
+        if (d.timeout > 0) {
+            entry.timeoutTimer = setTimeout(() => {
+                // chrome.notifications.clear fires its callback synchronously
+                // for our purposes; the onClosed listener will then dispatch
+                // the page-side ondone via the normal path.
+                try {
+                    chrome.notifications.clear(chromeId);
+                }
+                catch { /* gone */ }
+            }, d.timeout);
+        }
+        byChromeId.set(chromeId, entry);
+        return { ok: true, notificationId: chromeId };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// Called by the SW's chrome.notifications.onClicked listener.
+export function takeForClicked(chromeId) {
+    const entry = byChromeId.get(chromeId);
+    if (!entry)
+        return null;
+    // Don't delete the entry on click — TM's `onclick` is NOT terminal.
+    // The user may click then the notification auto-closes (or stays
+    // open until they dismiss); we still want to deliver ondone later.
+    return {
+        originatorTabId: entry.originatorTabId,
+        requestId: entry.requestId,
+        scriptId: entry.scriptId,
+    };
+}
+// Called by the SW's chrome.notifications.onClosed listener.
+// Terminal — we free the entry.
+export function takeForClosed(chromeId) {
+    const entry = byChromeId.get(chromeId);
+    if (!entry)
+        return null;
+    if (entry.timeoutTimer != null)
+        clearTimeout(entry.timeoutTimer);
+    byChromeId.delete(chromeId);
+    return {
+        originatorTabId: entry.originatorTabId,
+        requestId: entry.requestId,
+        scriptId: entry.scriptId,
+    };
+}
+// Drop every entry whose originator tab just closed. Best-effort
+// matches GM_openInTab's dropOriginator. The chrome notifications
+// themselves stay on screen — chrome.notifications survive tab close
+// (they're per-extension, not per-tab) — but with the originator
+// gone we have nobody to route the eventual events to.
+export function dropOriginator(originatorTabId) {
+    return dropEntriesForOriginator(byChromeId, originatorTabId, (entry) => {
+        if (entry.timeoutTimer != null)
+            clearTimeout(entry.timeoutTimer);
+    });
+}

package/dist/extension/gm-originator-map.js

@@ -0,0 +1,23 @@
+// Shared shed-on-tab-close helper for the per-request maps in
+// `gm-tab.ts` (GM_openInTab), `gm-notification.ts` (GM_notification),
+// and `gm-download.ts` (GM_download).
+//
+// Each keeps an in-memory `Map<key, { originatorTabId, … }>` and, when
+// a tab that originated requests is itself closed, drops every entry
+// that points at it (the opened tabs / on-screen notifications /
+// running downloads stay; we just have nowhere left to route their
+// eventual events). The iterate → match `originatorTabId` → per-entry
+// cleanup → delete → collect-key loop is identical; only the per-entry
+// cleanup differs (a secondary index vs. timers). Factored here so the
+// dispatchers can't drift.
+export function dropEntriesForOriginator(map, originatorTabId, cleanup) {
+    const dropped = [];
+    for (const [key, entry] of map) {
+        if (entry.originatorTabId !== originatorTabId)
+            continue;
+        cleanup(entry);
+        map.delete(key);
+        dropped.push(key);
+    }
+    return dropped;
+}

package/dist/extension/gm-tab-data.js

@@ -0,0 +1,121 @@
+// SW-side store for `GM_getTab` / `GM_saveTab` / `GM_getTabs`: one
+// plain object per (tab, script), kept while the tab is open.
+//
+// Behavior, as observed in TM:
+//   - `GM_getTab` gives this script's object for the sender's tab, `{}`
+//     when it has saved nothing there. The call itself counts as
+//     presence: the tab then shows in `GM_getTabs` with `{}`.
+//   - `GM_saveTab(obj)` replaces the object with a shallow copy. A null
+//     or undefined `obj` saves nothing.
+//   - `GM_getTabs` gives this script's object for every tab that has
+//     one, keyed by tab id.
+//   - Frames share their tab's object; the key is the tab, not the
+//     document.
+//   - Closing the tab drops its objects (`dropTabData`, from
+//     background.ts's `tabs.onRemoved`).
+//
+// Where it lives: in memory, mirrored to `chrome.storage.session` as one
+// `gmtab:<tabId>` row per tab ({ [scriptId]: object }). The mirror is
+// what keeps the data across the service worker being stopped while
+// idle, which would otherwise lose it within a minute of quiet. Session
+// storage also clears with the browser, the lifetime the API promises.
+// The rows are first read on the first call after a worker start.
+//
+// Wire protocol (page → SW): `{ type: SM_TAB_DATA_MSG, scriptId,
+// action: 'get' | 'save' | 'list', data? }` → `{ ok: true, value }` or
+// `{ ok: false, error }`. Values cross as JSON, so they hold what JSON
+// can.
+export const SM_TAB_DATA_MSG = 'sm:gm-tab-data';
+const KEY_PREFIX = 'gmtab:';
+let tabs = null;
+let loading = null;
+function rowKey(tabId) {
+    return `${KEY_PREFIX}${tabId}`;
+}
+function load() {
+    if (tabs)
+        return Promise.resolve(tabs);
+    if (!loading) {
+        loading = (async () => {
+            const all = await chrome.storage.session.get(null);
+            const m = new Map();
+            for (const [key, value] of Object.entries(all)) {
+                if (!key.startsWith(KEY_PREFIX))
+                    continue;
+                const tabId = Number(key.slice(KEY_PREFIX.length));
+                if (!Number.isInteger(tabId) || !value || typeof value !== 'object')
+                    continue;
+                m.set(tabId, value);
+            }
+            tabs = m;
+            return m;
+        })().finally(() => { loading = null; });
+    }
+    return loading;
+}
+// Write one tab's row (or remove it once empty). On failure this
+// script's entry is put back as it was, so memory and the row don't
+// disagree; other scripts' entries, which may have changed since, stay.
+async function persist(m, tabId, scriptId, prev) {
+    const next = m.get(tabId);
+    try {
+        if (next && Object.keys(next).length > 0) {
+            await chrome.storage.session.set({ [rowKey(tabId)]: next });
+        }
+        else {
+            await chrome.storage.session.remove(rowKey(tabId));
+        }
+    }
+    catch (err) {
+        const { [scriptId]: _failed, ...rest } = m.get(tabId) ?? {};
+        const restored = prev ? { ...rest, [scriptId]: prev } : rest;
+        if (Object.keys(restored).length > 0)
+            m.set(tabId, restored);
+        else
+            m.delete(tabId);
+        throw err;
+    }
+}
+export async function getTabData(tabId, scriptId) {
+    const m = await load();
+    const prev = m.get(tabId);
+    const existing = prev?.[scriptId];
+    if (existing)
+        return existing;
+    m.set(tabId, { ...prev, [scriptId]: {} });
+    await persist(m, tabId, scriptId, undefined);
+    return {};
+}
+export async function saveTabData(tabId, scriptId, data) {
+    if (data == null)
+        return;
+    if (typeof data !== 'object')
+        throw new Error('The tab object must be an object');
+    const m = await load();
+    const byScript = m.get(tabId);
+    const prev = byScript?.[scriptId];
+    m.set(tabId, { ...byScript, [scriptId]: { ...data } });
+    await persist(m, tabId, scriptId, prev);
+}
+export async function listTabData(scriptId) {
+    const m = await load();
+    const out = {};
+    for (const [tabId, byScript] of m) {
+        const obj = byScript[scriptId];
+        if (obj)
+            out[tabId] = obj;
+    }
+    return out;
+}
+// The tab closed. Waits out a first load already under way, which may
+// have read the row before it goes.
+export async function dropTabData(tabId) {
+    const m = tabs ?? (loading ? await loading : null);
+    m?.delete(tabId);
+    await chrome.storage.session.remove(rowKey(tabId));
+}
+// For the test surface's `resetAllState`, which clears session storage:
+// the memory copy came from it.
+export function forgetTabDataForTests() {
+    tabs = null;
+}

package/dist/extension/gm-tab.js

@@ -0,0 +1,160 @@
+// SW-side `GM_openInTab` dispatcher.
+//
+// Owns the (requestId ↔ chrome tab id ↔ originator tab id) mapping
+// so we can route close events back to the page that opened the tab.
+// Per-call state is small; we keep two maps for O(1) lookup either
+// way:
+//
+//   requestState: requestId -> { tabId?, originatorTabId, scriptId }
+//   tabIdToRequest: chromeTabId -> requestId
+//
+// The maps live in memory only. On SW restart the mapping is lost —
+// userscripts that hold a control handle from before the restart
+// stop receiving close notifications. That's the same boat as XHR
+// requests in flight; acceptable for v1.
+import { dropEntriesForOriginator } from './gm-originator-map.js';
+import { hasAllowedScheme, WEB_SCHEMES } from './gm-url-scheme.js';
+const requestState = new Map();
+const tabIdToRequest = new Map();
+// Only http(s) targets are allowed. The URL comes straight from
+// page-supplied message payload, so without this gate a script could
+// ask the privileged SW to open `file://`, `chrome://`, or
+// `chrome-extension://` tabs (local-file disclosure, settings pages,
+// other extensions' pages). TM/VM's GM_openInTab is web-oriented;
+// restricting to http/https matches the realistic use and closes the
+// scheme-smuggling hole.
+export function isAllowedTabUrl(url) {
+    return hasAllowedScheme(url, WEB_SCHEMES);
+}
+// The refusal a script sees for a URL `isAllowedTabUrl` rejects.
+export function tabUrlRefusedMessage(url) {
+    return `GM_openInTab: refusing non-http(s) URL ${url}`;
+}
+// Open a new tab on behalf of a script. Returns the assigned chrome
+// tab id (or an error) and stores the originator mapping so close
+// events can be routed back.
+export async function openGmTab(payload, originatorTabId, 
+// Run on the new tab before it loads the URL: it opens blank, this
+// runs, then the URL loads. For a tab sm-dev controls, whose claim
+// has to be on the new tab before its scripts ask (sm-dev-link.ts).
+beforeLoad) {
+    if (!isAllowedTabUrl(payload.url)) {
+        return { ok: false, error: tabUrlRefusedMessage(payload.url) };
+    }
+    // Stash the entry first so a close event arriving between
+    // chrome.tabs.create resolving and the page receiving the reply
+    // can still find the request. The originator can't have called
+    // close() yet because it doesn't have the tabId yet, but the user
+    // could theoretically close the new tab manually that fast.
+    requestState.set(payload.requestId, {
+        originatorTabId,
+        scriptId: payload.scriptId,
+        tabId: null,
+        closeRequested: false,
+    });
+    try {
+        const created = await chrome.tabs.create({
+            url: beforeLoad ? 'about:blank' : payload.url,
+            active: payload.active,
+            // Bias positioning: when `insert` is true, hint Chrome to place
+            // the new tab next to the originator.
+            ...(payload.insert ? { openerTabId: originatorTabId } : {}),
+        });
+        if (created.id == null) {
+            requestState.delete(payload.requestId);
+            return { ok: false, error: 'internal error: the tab opened but Chrome reported no id for it' };
+        }
+        const entry = requestState.get(payload.requestId);
+        if (!entry) {
+            // Request was already aborted; close the tab we just opened so
+            // we don't leak it.
+            try {
+                await chrome.tabs.remove(created.id);
+            }
+            catch { /* gone */ }
+            return {
+                ok: false,
+                error: 'internal error: the tab request was dropped before the tab opened',
+            };
+        }
+        entry.tabId = created.id;
+        tabIdToRequest.set(created.id, payload.requestId);
+        if (beforeLoad) {
+            try {
+                await beforeLoad(created.id);
+                // Closed meanwhile, by the script or the person: nothing to load.
+                if (!entry.closeRequested)
+                    await chrome.tabs.update(created.id, { url: payload.url });
+            }
+            catch (err) {
+                // The tab opened, so the script is told so. A tab gone before
+                // its URL loaded is reported closed by the onRemoved listener.
+                console.info('[SourceMonkey] GM_openInTab: could not load the URL into the new tab:', err);
+            }
+        }
+        if (entry.closeRequested) {
+            // The page called close() before create resolved. Close
+            // immediately — the onRemoved listener will then clear the
+            // mapping and route the close event back to the originator.
+            try {
+                await chrome.tabs.remove(created.id);
+            }
+            catch { /* gone */ }
+        }
+        return { ok: true, tabId: created.id };
+    }
+    catch (err) {
+        requestState.delete(payload.requestId);
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+// Close a tab by requestId. Idempotent — close on a tab that's
+// already gone is a no-op.
+export async function closeGmTab(requestId) {
+    const entry = requestState.get(requestId);
+    if (!entry)
+        return;
+    if (entry.tabId == null) {
+        // chrome.tabs.create hasn't resolved yet. Flag the entry; the
+        // openGmTab path checks closeRequested after create resolves and
+        // closes the just-opened tab. Avoids a "open-then-leak" when
+        // close() fires faster than create.
+        entry.closeRequested = true;
+        return;
+    }
+    const tabId = entry.tabId;
+    try {
+        await chrome.tabs.remove(tabId);
+    }
+    catch { /* tab already gone; the onRemoved listener handles cleanup */ }
+}
+// Called by the SW's chrome.tabs.onRemoved listener. Returns the
+// originator that needs notifying (or null if this wasn't a
+// GM_openInTab-created tab). The caller is responsible for the
+// actual sendMessage so this module stays independent of the broader
+// message-routing surface.
+export function takeRequestForClosedTab(tabId) {
+    const requestId = tabIdToRequest.get(tabId);
+    if (!requestId)
+        return null;
+    tabIdToRequest.delete(tabId);
+    const entry = requestState.get(requestId);
+    if (!entry)
+        return null;
+    requestState.delete(requestId);
+    return { originatorTabId: entry.originatorTabId, requestId, scriptId: entry.scriptId };
+}
+// Drop every entry pointing at this originator tab — used when a tab
+// containing a userscript that opened other tabs is itself closed.
+// The opened tabs stay open (matches TM/VM), but we can't route close
+// notifications anywhere useful, so we shed the mapping. Returns the
+// dropped requestIds for logging.
+export function dropOriginator(originatorTabId) {
+    return dropEntriesForOriginator(requestState, originatorTabId, (entry) => {
+        if (entry.tabId != null)
+            tabIdToRequest.delete(entry.tabId);
+    });
+}

package/dist/extension/gm-url-change.js

@@ -0,0 +1,111 @@
+// SW-side driver for `@grant window.onurlchange`.
+//
+// Why the service worker is involved at all: a USER_SCRIPT-world
+// script does NOT share `window.history` with the page. Patching
+// `history.pushState` from the isolated world produces a patched
+// function only isolated-world code ever calls — the page's own SPA
+// router keeps calling the real one, unobserved. The isolated world
+// does receive `popstate` / `hashchange`, but those cover only part of
+// the surface and overlap the events below, so this module is the
+// single source rather than one of two.
+//
+// `chrome.webNavigation` reports the whole surface:
+//
+//   - `onHistoryStateUpdated`      — pushState / replaceState and
+//                                    same-document traversals
+//   - `onReferenceFragmentUpdated` — fragment-only changes
+//
+// These two are *also* what Tampermonkey feeds its own `urlchange`
+// from (verified in TM 5.5.0's `background.js`), which is why our
+// firing rules match theirs for free: nothing on initial load,
+// nothing on a cross-document navigation, one event per reported
+// history update — including a same-URL `replaceState`, which TM does
+// not suppress. The `webNavigation` permission is already in the
+// manifest and `background.ts` already subscribes to
+// `onHistoryStateUpdated` for tab status, so this costs no new
+// privilege.
+//
+// The alternative — registering a MAIN-world helper that patches the
+// page's `history` and postMessages across — was rejected: it
+// pollutes every page's globals with a wrapper the page can see,
+// unpatch, or use to forge events, for a signal Chrome already hands
+// us for free.
+//
+// Wire protocol:
+//   SW → page: `{ type: 'sm:url-change', url }` via
+//   `chrome.tabs.sendMessage(tabId, msg, { documentId })`, falling
+//   back to `{ frameId }` (see `urlChangeTarget`). The URL is
+//   replayed verbatim to the userscript, so a burst of history
+//   updates produces one event each rather than a coalesced one.
+//
+// No gating: we notify on every reported update rather than tracking
+// which tabs have a granting script. A stateful gate would have to
+// survive SW restarts (chrome.userScripts registrations do; SW memory
+// doesn't), and getting that wrong fails silently. The message is
+// cheap — the SW is already awake handling this exact event for tab
+// status — and a frame with no SourceMonkey runtime just rejects the
+// send, which we swallow.
+export const SM_URL_CHANGE_MSG = 'sm:url-change';
+// Pure: should this history update be forwarded to a frame?
+//
+// Chrome reports events for pre-render / devtools targets with a
+// negative `tabId`, which `chrome.tabs.sendMessage` can't address. A
+// URL-less event has nothing worth reporting. Everything else is
+// forwarded, including `file://` (SourceMonkey injects there too).
+//
+// Sub-frames pass the filter, but the targeting below is what
+// actually matters for them: a sub-frame's navigation must never
+// be delivered to the top frame's listeners as if the document had
+// moved. A sub-frame with no script in it simply has no receiver.
+export function shouldNotifyUrlChange(details) {
+    if (typeof details.tabId !== 'number' || details.tabId < 0)
+        return false;
+    if (typeof details.frameId !== 'number' || details.frameId < 0)
+        return false;
+    return typeof details.url === 'string' && details.url !== '';
+}
+// Which receiver the message is addressed to.
+//
+// Prefer `documentId` over `frameId`: a frame ID names a *slot*, not a
+// document. The send is asynchronous relative to the navigation event,
+// so if that frame commits a cross-document navigation in between, a
+// frame-addressed message lands in a document that was never at this
+// URL and its listeners report a URL the page isn't on. A document ID
+// names the exact document, and the send simply finds no receiver once
+// that document is gone — which is the outcome we want.
+//
+// Only one of the two is passed: Chrome treats them as alternatives,
+// not as a pair to intersect.
+export function urlChangeTarget(details) {
+    return typeof details.documentId === 'string' && details.documentId !== ''
+        ? { documentId: details.documentId }
+        : { frameId: details.frameId };
+}
+// Fire-and-forget notification to the document that changed. Rejections
+// are expected and swallowed: pages with no active SourceMonkey script
+// have no GM runtime registered, so there is no receiving end.
+export function notifyUrlChange(details) {
+    if (!shouldNotifyUrlChange(details))
+        return;
+    void chrome.tabs
+        .sendMessage(details.tabId, { type: SM_URL_CHANGE_MSG, url: details.url }, urlChangeTarget(details))
+        .catch(() => undefined);
+}
+// Subscribe to both same-document navigation events. Called once from
+// `installNavigationListeners` in background.ts.
+//
+// This registers its own listeners rather than piggy-backing on the
+// tab-status `onHistoryStateUpdated` listener already in background.ts:
+// that one filters to the main frame, and a userscript inside an
+// iframe wants its own frame's navigations too.
+export function installUrlChangeWatch() {
+    const wn = chrome.webNavigation;
+    if (!wn?.onHistoryStateUpdated || !wn?.onReferenceFragmentUpdated) {
+        // Matches what TM logs in the same situation. `console.info`, not
+        // `.warn` — see the logging policy in CLAUDE.md.
+        console.info('[SourceMonkey] chrome.webNavigation same-document events unavailable; window.onurlchange will not fire');
+        return;
+    }
+    wn.onHistoryStateUpdated.addListener((d) => notifyUrlChange(d));
+    wn.onReferenceFragmentUpdated.addListener((d) => notifyUrlChange(d));
+}

package/dist/extension/gm-url-scheme.js

@@ -0,0 +1,27 @@
+// Shared URL-scheme gate for the SW-side `GM_*` dispatchers.
+//
+// Every dispatcher that hands a page-supplied URL to a privileged
+// Chrome API (`chrome.tabs.create`, `chrome.notifications.create`,
+// `chrome.downloads.download`) has to answer the same question first:
+// is this a scheme we're willing to act on? Without the gate a
+// userscript could ask the extension to open, fetch, or save
+// `file:///…`, `chrome://…`, or `chrome-extension://<id>/…` — reaching
+// past what the page itself could do.
+//
+// The allowed set differs per API (tabs and downloads take http(s);
+// notification icons also take `data:`), so the caller passes it in.
+// Only the parse-and-compare is shared — that's the part that was
+// previously copied three times and could drift.
+// True iff `url` parses and its scheme is one of `allowed`.
+// `allowed` entries include the trailing colon (`'http:'`), matching
+// `URL.protocol`. Anything unparseable is refused.
+export function hasAllowedScheme(url, allowed) {
+    try {
+        return allowed.includes(new URL(url).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+// The common case: plain web URLs.
+export const WEB_SCHEMES = Object.freeze(['http:', 'https:']);