sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/gm-download.js

@@ -0,0 +1,419 @@
+// SW-side `GM_download` dispatcher.
+//
+// Wraps `chrome.downloads` so a userscript can save a file to the
+// user's download directory. The page side keeps the caller's
+// `onload` / `onerror` / `onprogress` / `ontimeout` callbacks (they
+// aren't serializable) and we ship terminal + progress events back to
+// the originating tab keyed by the page-generated `requestId`.
+//
+// Wire protocol:
+//
+//   Page → SW: `sm:gm-download-start` { type, scriptId, requestId, ... }
+//   Page → SW: `sm:gm-download-abort` { type, requestId }
+//   SW → page: `sm:gm-download-event` { type, requestId, event }
+//
+// Only `http(s)` URLs reach this module. `blob:` / `data:` downloads
+// are handled entirely page-side by the runtime (an `<a download>`
+// click), because a page-minted `blob:` URL is not resolvable from the
+// extension's own context and a `data:` URL of arbitrary size has no
+// business crossing the message boundary. See docs/GM-APIs.md.
+//
+// Why `chrome.downloads` and not "fetch in the SW, then hand the bytes
+// to an offscreen document": `chrome.downloads.download` already does
+// the fetching, the Content-Disposition handling, the resume/retry, the
+// progress accounting, the Save-As dialog and the Safe-Browsing danger
+// prompt. Buffering a multi-GB video through the SW to rebuild a Blob
+// elsewhere would burn memory for a strictly worse result.
+import { dropEntriesForOriginator } from './gm-originator-map.js';
+import { hasAllowedScheme, WEB_SCHEMES } from './gm-url-scheme.js';
+const byRequestId = new Map();
+const byDownloadId = new Map();
+// How often we ask the download manager about an in-flight download.
+// `chrome.downloads.onChanged` does NOT carry `bytesReceived` (the
+// delta only reports state/filename/error/totalBytes changes), so
+// progress has to be polled — and the same tick doubles as the
+// terminal-state backstop and the service worker's keep-alive. 500 ms
+// is fine for a progress bar and cheap enough to leave running.
+const PROGRESS_POLL_MS = 500;
+// Schemes we hand to the download manager. The URL comes from a
+// page-supplied message, so without this gate a script could ask the
+// privileged SW to pull `file:///etc/passwd` (or a `chrome-extension://`
+// resource) onto disk under a name of its choosing. `blob:` / `data:`
+// never reach here — the page-side runtime handles those itself.
+export function isAllowedDownloadUrl(url) {
+    return hasAllowedScheme(url, WEB_SCHEMES);
+}
+// The `details.message` a script sees for a URL `isAllowedDownloadUrl`
+// rejects.
+export function downloadUrlRefusedMessage(url) {
+    return `refusing to download non-http(s) URL: ${url}`;
+}
+// Validate the caller's `name` and turn it into the `filename` we pass
+// to `chrome.downloads.download`.
+//
+// Chrome already rejects absolute paths and `..` traversal, but it
+// does so by throwing a generic error; validating here lets the script
+// see a clean `not_permitted` instead of a `not_succeeded` with an
+// opaque message, and keeps the rule in one testable place.
+//
+// Relative subdirectories ARE allowed (`pics/cat.png`) — Chrome
+// resolves them under the user's download directory and TM allows the
+// same. Backslashes are normalized to `/` first so a Windows-style
+// name doesn't slip a segment past the `..` check.
+export function validateDownloadName(name) {
+    const raw = (name ?? '').trim();
+    if (raw === '')
+        return { ok: true };
+    const normalized = raw.replace(/\\/g, '/');
+    if (/[\u0000-\u001f\u007f]/.test(normalized)) {
+        return { ok: false, reason: 'name contains control characters' };
+    }
+    if (normalized.startsWith('/')) {
+        return { ok: false, reason: 'name must be a relative path' };
+    }
+    if (/^[A-Za-z]:\//.test(normalized)) {
+        return { ok: false, reason: 'name must be a relative path' };
+    }
+    if (normalized.endsWith('/')) {
+        return { ok: false, reason: 'name must not be a directory' };
+    }
+    const segments = normalized.split('/');
+    if (segments.some((s) => s === '..')) {
+        return { ok: false, reason: 'name must not traverse out of the download directory' };
+    }
+    if (segments.some((s) => s === '')) {
+        return { ok: false, reason: 'name has an empty path segment' };
+    }
+    return { ok: true, filename: normalized };
+}
+// chrome.downloads.download in the Promise form the installed
+// @types/chrome doesn't declare consistently across versions. Wrap the
+// callback form and surface chrome.runtime.lastError as a rejection —
+// same shape as gm-notification.ts's create wrapper.
+function downloadViaChrome(options) {
+    return new Promise((resolve, reject) => {
+        try {
+            chrome.downloads.download(options, (downloadId) => {
+                const lastError = chrome.runtime.lastError;
+                if (lastError || downloadId === undefined) {
+                    reject(new Error(lastError?.message ?? 'downloads.download failed'));
+                    return;
+                }
+                resolve(downloadId);
+            });
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+}
+// Kick off a download. Resolves with the assigned download id, or with
+// an error code the caller ships back to the page.
+export async function startGmDownload(payload, originatorTabId, emit) {
+    if (!chrome.downloads) {
+        // The `downloads` permission is declared in the manifest, so this
+        // only happens if a future build makes it optional and the user
+        // hasn't granted it. TM uses `not_permitted` for exactly that case.
+        return {
+            ok: false,
+            error: 'not_permitted',
+            details: { message: 'chrome.downloads unavailable (missing downloads permission)' },
+        };
+    }
+    if (!isAllowedDownloadUrl(payload.url)) {
+        return {
+            ok: false,
+            error: 'not_permitted',
+            details: { message: downloadUrlRefusedMessage(payload.url) },
+        };
+    }
+    const nameCheck = validateDownloadName(payload.name);
+    if (!nameCheck.ok) {
+        return { ok: false, error: 'not_permitted', details: { message: nameCheck.reason } };
+    }
+    const entry = {
+        originatorTabId,
+        url: payload.url,
+        downloadId: null,
+        cancelRequested: false,
+        emit,
+        wantsProgress: false,
+        timeoutTimer: null,
+        progressTimer: null,
+    };
+    // Register before awaiting so an abort() that arrives while
+    // chrome.downloads.download is still resolving finds the entry.
+    byRequestId.set(payload.requestId, entry);
+    // Arm the timeout BEFORE creating the download, not after. Chrome
+    // doesn't hand back a download id until the server has answered, so
+    // a timer armed after the await could never fire for the case that
+    // needs it most — a host that accepts the connection and then sits
+    // there. `timeoutFired` below is what keeps it from double-settling.
+    if (payload.timeout > 0) {
+        entry.timeoutTimer = setTimeout(() => {
+            const live = byRequestId.get(payload.requestId);
+            if (!live)
+                return;
+            if (live.downloadId == null) {
+                // No id yet: tell the page now and leave the entry for the
+                // start path, which cancels the download the moment it exists
+                // (same handoff as `cancelRequested`).
+                live.cancelRequested = true;
+                live.emit({ kind: 'timeout' });
+                return;
+            }
+            // Drop the entry before cancelling so the `interrupted` delta
+            // that follows finds nothing — the script sees exactly one
+            // terminal event.
+            releaseEntry(payload.requestId);
+            void cancelViaChrome(live.downloadId);
+            live.emit({ kind: 'timeout' });
+        }, payload.timeout);
+    }
+    const headers = headerPairs(payload.headers);
+    let downloadId;
+    try {
+        downloadId = await downloadViaChrome({
+            url: payload.url,
+            ...(nameCheck.filename ? { filename: nameCheck.filename } : {}),
+            saveAs: payload.saveAs,
+            // Chrome's default anyway, but pin it: a script that downloads
+            // 50 images named by the page shouldn't fail on the first
+            // collision.
+            conflictAction: 'uniquify',
+            ...(headers ? { headers } : {}),
+        });
+    }
+    catch (err) {
+        releaseEntry(payload.requestId);
+        return {
+            ok: false,
+            error: 'not_succeeded',
+            details: { message: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    // The request was abandoned while we were starting — the page called
+    // abort() (it settled its own callbacks locally) or our timeout fired
+    // (it emitted `timeout` already). Either way: cancel the download we
+    // just created and report nothing more.
+    if (entry.cancelRequested) {
+        releaseEntry(payload.requestId);
+        await cancelViaChrome(downloadId);
+        return { ok: false, error: 'download_canceled', details: {} };
+    }
+    // The originating tab closed while we were starting: `dropOriginator`
+    // already swept the entry, so re-registering it here would leave a
+    // poll timer nobody can ever clear. The transfer itself keeps going
+    // (a download the user started is theirs to keep) — we simply stop
+    // tracking it. Same window `gm-tab.ts` guards after `tabs.create`.
+    if (byRequestId.get(payload.requestId) !== entry) {
+        return { ok: true, downloadId };
+    }
+    entry.downloadId = downloadId;
+    byDownloadId.set(downloadId, payload.requestId);
+    // Poll for as long as the download is in flight — unconditionally,
+    // not just when the caller wants progress. Two jobs beyond progress:
+    //
+    //   - It is the backstop for the terminal event. A delta can be
+    //     missed (it fires against the download id, which we only learn
+    //     when `download()` resolves — a small or cached file CAN settle
+    //     inside that window) and a script left without a terminal event
+    //     stalls forever.
+    //   - Each `chrome.downloads.search` is an API call, which keeps the
+    //     service worker from idle-terminating (~30 s) out from under a
+    //     minutes-long download. If the SW died, its in-memory maps would
+    //     go with it and the completion delta would arrive with nothing
+    //     to route it to.
+    //
+    // `wantsProgress` only gates whether progress EVENTS are emitted, so
+    // the failure modes don't differ between callers who passed an
+    // `onprogress` and callers who didn't.
+    entry.wantsProgress = payload.wantsProgress;
+    entry.progressTimer = setInterval(() => {
+        void pollDownload(payload.requestId);
+    }, PROGRESS_POLL_MS);
+    // First poll immediately rather than one interval later, so a
+    // download that already settled reports without a 500 ms delay.
+    void pollDownload(payload.requestId);
+    return { ok: true, downloadId };
+}
+// Convert the caller's `{name: value}` header object into the
+// `[{name, value}]` array chrome.downloads.download wants. Returns
+// null when there's nothing to send.
+function headerPairs(headers) {
+    if (!headers || typeof headers !== 'object')
+        return null;
+    const pairs = [];
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof name !== 'string' || name === '')
+            continue;
+        pairs.push({ name, value: String(value) });
+    }
+    return pairs.length > 0 ? pairs : null;
+}
+async function cancelViaChrome(downloadId) {
+    try {
+        await new Promise((resolve) => {
+            chrome.downloads.cancel(downloadId, () => {
+                // Reading lastError keeps Chrome from logging "Unchecked
+                // runtime.lastError" when the download already finished.
+                void chrome.runtime.lastError;
+                resolve();
+            });
+        });
+    }
+    catch { /* already gone */ }
+}
+// One download item by id, or undefined if the download manager
+// doesn't know it (already erased, or a stubbed API in tests). Shared
+// by the progress poll, the completion path, and the catch-up probe so
+// the lastError handling can't drift.
+async function searchOne(downloadId) {
+    try {
+        return await new Promise((resolve) => {
+            chrome.downloads.search({ id: downloadId }, (found) => {
+                void chrome.runtime.lastError;
+                resolve(found?.[0]);
+            });
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+// One poll tick for an in-flight download: settle it if the download
+// manager says it's already done, otherwise report progress. See the
+// call site in `startGmDownload` for why this runs unconditionally.
+async function pollDownload(requestId) {
+    const entry = byRequestId.get(requestId);
+    if (!entry || entry.downloadId == null)
+        return;
+    const downloadId = entry.downloadId;
+    const item = await searchOne(downloadId);
+    // Re-check liveness: the search is async and the download may have
+    // settled through the delta (releasing the entry) while it was in
+    // flight. Whichever path gets here first wins; the loser finds
+    // nothing and emits nothing, so the script sees one terminal event.
+    if (byRequestId.get(requestId) !== entry)
+        return;
+    if (!item)
+        return;
+    if (item.state === 'complete' || item.state === 'interrupted') {
+        releaseEntry(requestId);
+        entry.emit(item.state === 'complete'
+            ? loadEventFor(entry, downloadId, item)
+            : {
+                kind: 'error',
+                error: 'not_succeeded',
+                details: item.error ? { current: item.error } : {},
+            });
+        return;
+    }
+    if (!entry.wantsProgress)
+        return;
+    const total = typeof item.totalBytes === 'number' ? item.totalBytes : 0;
+    entry.emit({
+        kind: 'progress',
+        loaded: typeof item.bytesReceived === 'number' ? item.bytesReceived : 0,
+        total,
+        lengthComputable: total > 0,
+    });
+}
+// Handle one `chrome.downloads.onChanged` delta. Terminal states emit
+// the matching page event and free the entry; everything else (paused,
+// filename determined, danger prompt) is ignored.
+export function handleDownloadChanged(delta) {
+    const requestId = byDownloadId.get(delta.id);
+    if (!requestId)
+        return;
+    const entry = byRequestId.get(requestId);
+    if (!entry)
+        return;
+    const state = delta.state?.current;
+    if (state === 'complete') {
+        releaseEntry(requestId);
+        void emitComplete(entry, delta.id);
+        return;
+    }
+    if (state === 'interrupted') {
+        releaseEntry(requestId);
+        entry.emit({
+            kind: 'error',
+            error: 'not_succeeded',
+            details: {
+                // `delta.error` is Chrome's InterruptReason (NETWORK_FAILED,
+                // USER_CANCELED, FILE_ACCESS_DENIED, …). Passing it through as
+                // `{current, previous}` is what TM does and what real scripts
+                // branch on.
+                ...(delta.error?.current != null ? { current: delta.error.current } : {}),
+                ...(delta.error?.previous != null ? { previous: delta.error.previous } : {}),
+            },
+        });
+    }
+}
+// Fill in the completed download's filename / size before emitting
+// `load`. The onChanged delta doesn't carry them reliably, so we ask
+// the download manager. A failed lookup still emits `load` — the
+// download DID complete and the script shouldn't be told otherwise.
+async function emitComplete(entry, downloadId) {
+    const item = await searchOne(downloadId);
+    entry.emit(loadEventFor(entry, downloadId, item));
+}
+// The `load` event for a completed download. `item` is optional
+// because the lookup can come back empty (download erased, stubbed
+// API); the request URL is the fallback for `finalUrl`.
+function loadEventFor(entry, downloadId, item) {
+    return {
+        kind: 'load',
+        downloadId,
+        filename: item?.filename ?? '',
+        finalUrl: item?.finalUrl ?? item?.url ?? entry.url,
+        totalBytes: typeof item?.totalBytes === 'number' ? item.totalBytes : 0,
+    };
+}
+// Cancel an in-flight download on the script's behalf. The page has
+// already settled its own callbacks (matching `GM_xmlhttpRequest`'s
+// synchronous abort), so we only tear down SW-side state here.
+export async function abortGmDownload(requestId) {
+    const entry = byRequestId.get(requestId);
+    if (!entry)
+        return;
+    if (entry.downloadId == null) {
+        // The download hasn't been created yet; flag it so the start path
+        // cancels as soon as it has an id.
+        entry.cancelRequested = true;
+        return;
+    }
+    const downloadId = entry.downloadId;
+    releaseEntry(requestId);
+    await cancelViaChrome(downloadId);
+}
+// Timers + secondary index teardown for one entry. Shared by the
+// single-request release path and the shed-on-tab-close sweep so the
+// two can't drift.
+function cleanupEntry(entry) {
+    if (entry.timeoutTimer != null)
+        clearTimeout(entry.timeoutTimer);
+    if (entry.progressTimer != null)
+        clearInterval(entry.progressTimer);
+    if (entry.downloadId != null)
+        byDownloadId.delete(entry.downloadId);
+}
+// Drop an entry and clear its timers. Terminal-event handlers call
+// this BEFORE emitting so a callback that immediately starts another
+// download can't collide with the entry it just settled.
+function releaseEntry(requestId) {
+    const entry = byRequestId.get(requestId);
+    if (!entry)
+        return;
+    cleanupEntry(entry);
+    byRequestId.delete(requestId);
+}
+// Drop every request that belongs to a tab that just closed. Unlike
+// GM_openInTab we do NOT cancel the transfers: a download the user
+// started is theirs to keep even if the page that asked for it is
+// gone. We just stop tracking it (nobody is left to route events to).
+// Returns the dropped requestIds for logging.
+export function dropOriginator(originatorTabId) {
+    return dropEntriesForOriginator(byRequestId, originatorTabId, cleanupEntry);
+}

package/dist/extension/gm-menu.js

@@ -0,0 +1,228 @@
+// SW-side `GM_registerMenuCommand` / `GM_unregisterMenuCommand` state.
+//
+// Per-tab, per-document, per-script registry of menu commands a
+// userscript has asked us to expose. The wrapper holds the actual
+// callback locally (callbacks aren't serializable across worlds); we
+// only track enough to render the toolbar popup's command rows and
+// route a click back to the document that registered it.
+//
+// Lifecycle:
+//   - Registered by the wrapper after `sm:start` via `sm:gm-menu-register`.
+//   - Cleared per-tab on a fresh-document navigation of the top frame
+//     (the new wrappers re-register from scratch) and on tab close.
+//   - A frame's commands go with its document (`pruneDocuments`).
+//   - SW restart wipes this state. The wrapper's per-document callbacks
+//     also vanish on document teardown, so the symmetric drop is
+//     correct: the SW would have no way to route a fire event back to a
+//     callback that no longer exists.
+//
+// Every registration is kept. A script's caption shows once per tab, and
+// picking it runs all its registrations (`visibleCommands`,
+// `menuCommandGroup`).
+//
+// Storage is in-memory only — same shape as `gm-tab.ts` / `gm-notification.ts`.
+//
+// A tab holds commands from several documents when scripts run in its
+// iframes: the top frame's and each frame's. The popup merges them per
+// script (docs/frames.md).
+import { visibleCommands } from '../menu-captions.js';
+// tabId → documentId → its commands, top frame first.
+const byTab = new Map();
+// Commands are per-page, so a register under a different top document
+// than the one we're holding replaces the tab's state rather than
+// adding to it — whichever of the register and the navigation clear
+// arrives first, the loser is a no-op.
+//
+// Known window, same accepted class as the `chrome.tabs.onRemoved` one
+// noted at the register call site: a message from a document that has
+// already been torn down can in principle land after its successor has
+// registered, and would replace the live page's commands. Nothing
+// local can tell that apart from the ordinary case (both are "a
+// different page"), and it needs a message to outlive a whole
+// navigation plus the next document's `document-end`.
+function ensureDoc(tabId, docId, topDocId) {
+    let docs = byTab.get(tabId);
+    if (docs && [...docs.values()].some((d) => d.topDocId !== topDocId))
+        docs = undefined;
+    if (!docs) {
+        docs = new Map();
+        byTab.set(tabId, docs);
+    }
+    let doc = docs.get(docId);
+    if (!doc) {
+        doc = { topDocId, scripts: new Map() };
+        // The top frame's commands list first.
+        if (docId === topDocId)
+            byTab.set(tabId, new Map([[docId, doc], ...docs]));
+        else
+            docs.set(docId, doc);
+    }
+    return doc.scripts;
+}
+// Register or update a menu command. TM/VM both treat `GM_registerMenuCommand`
+// with an existing `id` (passed via the options object) as an update, so
+// we mirror that by overwriting any entry with the same commandId.
+//
+// `topDocId` is the tab's top document; omitted, `docId` is the top
+// frame's own.
+//
+// Returns true iff the visible state changed (new entry, or an update
+// that changed `name`). Callers gate menu rebuilds on this so a noisy
+// no-op register doesn't send an open popup a redraw.
+export function registerMenuCommand(tabId, docId, scriptId, commandId, name, topDocId = docId) {
+    const scripts = ensureDoc(tabId, docId, topDocId);
+    const entry = { commandId, name, documentId: docId };
+    const list = scripts.get(scriptId);
+    if (!list) {
+        scripts.set(scriptId, [entry]);
+        return true;
+    }
+    const existing = list.findIndex((c) => c.commandId === commandId);
+    if (existing >= 0) {
+        if (list[existing].name === name)
+            return false;
+        list[existing] = entry;
+        return true;
+    }
+    list.push(entry);
+    return true;
+}
+// Remove a menu command. No-op if it isn't registered (matches TM —
+// `GM_unregisterMenuCommand(<unknown id>)` is silent). Returns true
+// iff a registration was removed, so callers can skip a wasted rebuild
+// on unknown ids. (Removing a hidden older registration of a repeated
+// caption also returns true: a redraw that changes nothing.)
+//
+// Scoped like the register side: an unregister reaches only its own
+// document's entries. The same commandId can legitimately exist in two
+// documents (an explicit `{id: '...'}`).
+export function unregisterMenuCommand(tabId, docId, scriptId, commandId) {
+    const docs = byTab.get(tabId);
+    const scripts = docs?.get(docId)?.scripts;
+    if (!docs || !scripts)
+        return false;
+    const list = scripts.get(scriptId);
+    if (!list)
+        return false;
+    if (!list.some((c) => c.commandId === commandId))
+        return false;
+    const next = list.filter((c) => c.commandId !== commandId);
+    if (next.length === 0) {
+        scripts.delete(scriptId);
+        if (scripts.size === 0)
+            docs.delete(docId);
+        if (docs.size === 0)
+            byTab.delete(tabId);
+    }
+    else {
+        scripts.set(scriptId, next);
+    }
+    return true;
+}
+// Every registration in a tab, keyed by scriptId, in registration
+// order: the top frame's first, then each frame's.
+function allCommandsForTab(tabId) {
+    const merged = new Map();
+    for (const doc of byTab.get(tabId)?.values() ?? []) {
+        for (const [scriptId, list] of doc.scripts) {
+            const into = merged.get(scriptId);
+            if (into)
+                into.push(...list);
+            else
+                merged.set(scriptId, [...list]);
+        }
+    }
+    return merged;
+}
+// The commands a tab shows, keyed by scriptId: one per caption across
+// all the tab's documents (see `visibleCommands`). Returns an empty map
+// when nothing is registered (callers iterate it either way).
+export function getMenuCommandsForTab(tabId) {
+    const shown = new Map();
+    for (const [scriptId, list] of allCommandsForTab(tabId)) {
+        shown.set(scriptId, visibleCommands(list, (c) => c.name));
+    }
+    return shown;
+}
+// The registrations picking `entry` runs: all of the script's commands
+// in the tab with its caption, in any document, in registration order.
+export function menuCommandGroup(tabId, scriptId, entry) {
+    return (allCommandsForTab(tabId).get(scriptId) ?? []).filter((c) => c.name === entry.name);
+}
+// Look up a single command — used by the popup's command handler to
+// resolve a clicked item back to the originating document. Without
+// `documentId`, the first document holding it, top frame first.
+export function findMenuCommand(tabId, scriptId, commandId, documentId) {
+    for (const [docId, doc] of byTab.get(tabId) ?? []) {
+        if (documentId !== undefined && docId !== documentId)
+            continue;
+        const found = doc.scripts.get(scriptId)?.find((c) => c.commandId === commandId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+// Drop every command for a tab. Called on `chrome.tabs.onRemoved`, on
+// navigation to a page we don't inject into, and on fresh-document
+// navigation (when `updateTabMatches` resets `actual` to `{}`). The
+// next document's wrappers will re-register.
+//
+// `keepDocumentId` is for the navigation caller: it runs after several
+// awaits, by which time the new page's wrappers may already have
+// registered. Passing the top document being navigated TO makes the
+// clear drop only state left over from an earlier page, so a wrapper
+// that registered early (in the top frame or a frame of it) keeps its
+// commands. Omit it to drop the tab's state unconditionally.
+//
+// It does NOT make the clear safe in general: leaving a document drops
+// that document's commands, and a bfcache restore back to it does not
+// re-register them (Chrome doesn't re-inject). See the known gap in
+// GM-APIs.md.
+//
+// An empty `keepDocumentId` means the caller doesn't know which
+// document it is navigating to, and an unknown document must not
+// protect state: fall back to the unconditional clear rather than
+// keeping commands we can't tie to anything.
+//
+// Mirror of the late-register window above: a clear naming an
+// intermediate document can still delete a newer document's
+// registrations if two navigations land inside one await window.
+// Neither side can order documents from local state alone.
+export function clearTab(tabId, keepDocumentId) {
+    const docs = byTab.get(tabId);
+    if (keepDocumentId && docs && [...docs.values()].every((d) => d.topDocId === keepDocumentId))
+        return;
+    byTab.delete(tabId);
+}
+// Drop the commands of a tab's frame documents that aren't in
+// `liveDocIds` (the tab's frames now): the frame navigated or was
+// removed. The top frame's are left to `clearTab`. Returns true iff
+// something went.
+export function pruneDocuments(tabId, liveDocIds) {
+    const docs = byTab.get(tabId);
+    if (!docs)
+        return false;
+    let changed = false;
+    for (const [docId, doc] of docs) {
+        if (docId === doc.topDocId || liveDocIds.has(docId))
+            continue;
+        docs.delete(docId);
+        changed = true;
+    }
+    if (docs.size === 0)
+        byTab.delete(tabId);
+    return changed;
+}
+// The top document the tab's commands belong to, or undefined when it
+// holds none.
+export function topDocument(tabId) {
+    return byTab.get(tabId)?.values().next().value?.topDocId;
+}
+// Whether the tab holds commands from any frame's document (as opposed
+// to only the top frame's): `pruneDocuments` has something to check.
+export function hasFrameDocuments(tabId) {
+    for (const [docId, doc] of byTab.get(tabId) ?? [])
+        if (docId !== doc.topDocId)
+            return true;
+    return false;
+}