sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/tab-status.js

@@ -0,0 +1,403 @@
+// Per-tab script-status model + badge computation.
+//
+// For each tab we track two views of the world:
+//   - `matches` (expected) — what the in-memory match index says should
+//     be running on this URL. Computed on navigation by background.ts.
+//   - `actual` — what injected wrappers have actually reported via
+//     sm:start / sm:error. Driven by chrome.runtime.onUserScriptMessage.
+//
+// Each script in the union of those two sets gets a status here. The
+// toolbar badge's color and tooltip are summed up from the popup's
+// view of them (src/extension/toolbar-summary.ts). Keeping the
+// computation here (pure) makes it easy to unit test without the
+// chrome.* surface.
+import { compareScriptNames } from '../script-display.js';
+// Tampermonkey-ish orange (the "things differ" state).
+export const BADGE_ORANGE = '#f57c00';
+// Green = expected and actual agree, no errors.
+export const BADGE_GREEN = '#2e7d32';
+// Red = at least one script reported an error.
+export const BADGE_RED = '#d32f2f';
+// Purple = a reload would change what runs: a running script changed
+// on disk, or a script was enabled, disabled or removed since the page
+// loaded, or the page loaded before the extension started. Loses to
+// RED (errors still matter most) but wins over ORANGE. Picked bright
+// (≈ Material purple-A400) so the badge reads as a vivid "something
+// changed" signal, not a muted/inactive color.
+export const BADGE_PURPLE = '#d500f9';
+// Grey = the user reloaded this page with no userscripts, so nothing
+// ran on purpose. Loses to every other color: an UNEXPECTED report on a
+// skipped document is still a disagreement worth orange.
+export const BADGE_GREY = '#757575';
+// Which color wins is decided in src/extension/toolbar-summary.ts.
+// The note a tab an sm-dev run controls carries, in the badge tooltip
+// and as the popup's banner.
+export const SM_DEV_CONTROL_LABEL = 'Page under sm-dev control';
+// Material cyan-600: the corner marker drawn on the icon in a tab an
+// sm-dev run controls. Used for nothing else, so it can't be read as a
+// status.
+export const SM_DEV_MARKER_CYAN = '#00acc1';
+// Pure: derive each script's status from a tab's combined expected +
+// actual.
+//
+// Rules:
+//   - Per script, status is one of:
+//       OK         — expected AND actually started (no error reported)
+//       ERROR      — actual reported `error` (regardless of expected),
+//                    including a script that got no run decision
+//       REJECTED   — expected, never started, and Chrome is refusing to
+//                    register it (so it never will) — see
+//                    src/extension/script-rejection.ts
+//       NOT_LOADED — expected, never started, on a document the user
+//                    loaded with "Reload page with no userscripts", or
+//                    one loaded while user scripts were disabled, while
+//                    they still are
+//       UNTRACKED  — expected, never reported, on a document that
+//                    loaded before this copy of the extension started,
+//                    or while user scripts were disabled
+//       MISSING    — expected but no `actual` entry yet
+//       UNEXPECTED — actual `started` but not in our expected set
+//       RELOAD     — a script that's started here, but its on-disk
+//                    content has changed since (would be OK otherwise)
+//   - The count is the size of the union of expected ∪ actual IDs,
+//     with the scripts running in frames.
+//   - A script running in frames takes the worst of its runs' statuses
+//     (`STATUS_RANK`); one running only in frames is `framesOnly`.
+//
+// REJECTED is a refinement of MISSING, not a new axis: both mean
+// "expected here, never reported". MISSING is provisional — the wrapper
+// may still be on its way, or the user may have loaded the page before
+// installing the script — so it earns amber. A rejected registration is
+// settled: Chrome refused it, so nothing is coming, and red says so.
+// It reads the same word as the collections page and the viewer.
+//
+// `rejected` is passed in rather than stored on TabMatchState because
+// it's global (one refusal applies to every tab) while the state is
+// per-document. Persisting a copy per tab would need a fan-out to keep
+// them all honest.
+export function computeBadge(state, rejected = new Set(), 
+// User scripts are disabled right now. Only asked about a document
+// marked `loadedWithoutUserscripts`.
+userScriptsDisabled = false) {
+    const expectedById = new Map();
+    for (const m of state.matches)
+        expectedById.set(m.id, m);
+    const stale = new Set(state.staleScriptIds ?? []);
+    const frameRuns = state.frameRuns ?? {};
+    const allIds = new Set([
+        ...expectedById.keys(),
+        ...Object.keys(state.actual),
+        ...Object.keys(frameRuns),
+    ]);
+    const rows = [];
+    for (const id of allIds) {
+        const expected = expectedById.get(id);
+        const actual = state.actual[id];
+        // Prefer the actual-side name (most recently reported by the
+        // wrapper); fall back to the match-index name; finally the id.
+        const runs = Object.values(frameRuns[id] ?? {});
+        const name = actual?.name ?? expected?.name ?? runs[0]?.name ?? id;
+        if (!expected && !actual) {
+            rows.push({ id, name, ...frameStatus(runs), framesOnly: true });
+            continue;
+        }
+        let status;
+        let message;
+        // A manual script runs its current copy each time it's asked, so
+        // it's never stale, and it's expected once it has run.
+        const manual = state.manualRuns?.[id] !== undefined;
+        if (actual && stale.has(id) && !manual) {
+            // Whether the wrapper reported started or errored, that report
+            // came from the OLD content. RELOAD/purple is more actionable
+            // than ERROR/red here — the on-disk fix may already address the
+            // failure, and we'd rather nudge the user to reload than to
+            // keep showing an outdated error.
+            status = 'RELOAD';
+        }
+        else if (actual?.state === 'error') {
+            status = 'ERROR';
+            message = actual.message;
+        }
+        else if (expected && !actual && skippedOnDocument(state, id)) {
+            // Settled too, but by the user: the SW told every wrapper on this
+            // document to skip, so "never reported" is the intended outcome.
+            // Checked ahead of REJECTED — a refused registration didn't get
+            // to matter on a document where nothing was going to run.
+            status = 'NOT_LOADED';
+        }
+        else if (expected && !actual && rejected.has(id)) {
+            // Settled, not provisional: Chrome refused the registration, so
+            // no wrapper is coming. Red, like an error.
+            status = 'REJECTED';
+        }
+        else if (expected && !actual && state.loadedWithoutUserscripts && userScriptsDisabled) {
+            // Kept out, like a skipped load, until user scripts are enabled:
+            // a reload won't run it yet.
+            status = 'NOT_LOADED';
+        }
+        else if (expected && !actual && (state.loadedBefore || state.loadedWithoutUserscripts)) {
+            // Not provisional like MISSING: no report is coming, since none
+            // would have reached this copy of the extension, or nothing was
+            // injected.
+            status = 'UNTRACKED';
+        }
+        else if (expected && !actual) {
+            status = 'MISSING';
+        }
+        else if (!expected && actual && !manual) {
+            status = 'UNEXPECTED';
+        }
+        else {
+            status = 'OK';
+        }
+        if (runs.length > 0) {
+            const inFrames = frameStatus(runs);
+            if (STATUS_RANK[inFrames.status] > STATUS_RANK[status])
+                ({ status, message } = inFrames);
+        }
+        rows.push({ id, name, status, message });
+    }
+    rows.sort((a, b) => compareScriptNames(a.name, b.name));
+    const count = [...allIds].filter((id) => countsOnBadge(state, id)).length;
+    return { count, rows };
+}
+// Worst first: a row with runs in several documents shows the worst.
+// Errors outrank everything; a run of outdated code (RELOAD) outranks
+// what a reload would also settle (MISSING, UNEXPECTED).
+const STATUS_RANK = {
+    ERROR: 7, REJECTED: 7, RELOAD: 5, MISSING: 4, UNEXPECTED: 3, UNTRACKED: 2, NOT_LOADED: 1, OK: 0,
+};
+// A script's status from its runs in frames: outdated code first, as
+// for the top frame's run, then an error, else running.
+function frameStatus(runs) {
+    if (runs.some((r) => r.stale))
+        return { status: 'RELOAD' };
+    const error = runs.find((r) => r.state === 'error');
+    return error ? { status: 'ERROR', message: error.message } : { status: 'OK' };
+}
+/** Whether `id` has reported running in this document or any of its frames. */
+export function runsHere(state, id) {
+    return state.actual[id] != null || state.frameRuns?.[id] != null;
+}
+/**
+ * Whether the badge counts `id`. In a tab an sm-dev run controls, the
+ * count is of the scripts its claim let run: the rest were kept out,
+ * not left out by a problem.
+ */
+export function countsOnBadge(state, id) {
+    if (state.smDevAllow === undefined || state.scriptsSkipped)
+        return true;
+    return !skippedOnDocument(state, id) || runsHere(state, id);
+}
+/**
+ * Whether the worker told `id` to skip this document: a reload with no
+ * userscripts, with only another script, or without this one; or a tab
+ * an sm-dev run controls that doesn't allow it.
+ */
+export function skippedOnDocument(state, id) {
+    if (state.scriptsSkipped)
+        return true;
+    if (state.skipOnly !== undefined && state.skipOnly !== id)
+        return true;
+    if (state.skipWithout === id)
+        return true;
+    return state.smDevAllow !== undefined && !(state.smDevAllow?.includes(id) ?? false);
+}
+/** Whether the page is still settling (`settleBy`) at `now`. */
+export function isSettling(state, now) {
+    return state.settleBy !== undefined && now < state.settleBy;
+}
+// ---------- Per-tab document history ----------
+//
+// chrome.userScripts injects once per document. bfcache restores
+// reuse the original `documentId`, so to recognise "this is the same
+// page you had loaded a moment ago" we have to remember each tab's
+// recent documents — not just the current one. Otherwise navigating
+// A → B → back to A throws away A's expected/actual state, then
+// onCommitted for A lands with no prior state and we incorrectly
+// reset, painting every still-running script as MISSING.
+//
+// Cap kept small (covers normal back/forward chains) so the session-
+// storage value per tab stays cheap and a runaway tab can't bloat
+// indefinitely. LRU order: oldest first; the current doc is always
+// the rightmost entry.
+export const MAX_DOCS_PER_TAB = 5;
+export function getDocState(record, documentId) {
+    if (!record || !documentId)
+        return null;
+    return record.byDoc[documentId] ?? null;
+}
+export function getCurrentState(record) {
+    if (!record)
+        return null;
+    return record.byDoc[record.currentDocId] ?? null;
+}
+function trimLru(record) {
+    if (record.docOrder.length <= MAX_DOCS_PER_TAB)
+        return record;
+    const docOrder = record.docOrder.slice();
+    const byDoc = { ...record.byDoc };
+    while (docOrder.length > MAX_DOCS_PER_TAB) {
+        const evicted = docOrder.shift();
+        // Don't evict the current doc even if it's somehow at the head —
+        // promote it back to the most-recent slot.
+        if (evicted === record.currentDocId) {
+            docOrder.push(evicted);
+            continue;
+        }
+        delete byDoc[evicted];
+    }
+    return { currentDocId: record.currentDocId, docOrder, byDoc };
+}
+// Pure: write `state` for `documentId` and mark this doc as the one
+// the badge should display. Used by navigation events
+// (onCommitted / onHistoryStateUpdated) and by message-handler
+// bootstrap when there's no prior record at all.
+export function setCurrentDoc(record, documentId, state) {
+    const docOrder = (record?.docOrder ?? []).filter((d) => d !== documentId);
+    docOrder.push(documentId);
+    const byDoc = { ...(record?.byDoc ?? {}), [documentId]: state };
+    return trimLru({ currentDocId: documentId, docOrder, byDoc });
+}
+// Pure: write `state` for `documentId` WITHOUT promoting it to current.
+// Used by the sm:* message handler: a wrapper firing from a doc that
+// isn't currently displayed (e.g. teardown of the doc we just
+// navigated away from) should still update that doc's recorded state,
+// but the badge stays on whatever the navigation handler set.
+export function writeDocState(record, documentId, state) {
+    if (!record) {
+        return { currentDocId: documentId, docOrder: [documentId], byDoc: { [documentId]: state } };
+    }
+    const docOrder = record.docOrder.filter((d) => d !== documentId);
+    docOrder.push(documentId);
+    const byDoc = { ...record.byDoc, [documentId]: state };
+    return trimLru({ currentDocId: record.currentDocId, docOrder, byDoc });
+}
+// Pure: union two expected-match lists by script id. Used when a SPA
+// navigation within the same document brings in matches for a new URL —
+// we accumulate rather than replace, so a script that matched only the
+// initial URL still surfaces as MISSING if its `sm:start` never came.
+// Sorted by name for stable downstream display.
+export function mergeMatches(existing, incoming) {
+    const byId = new Map();
+    for (const m of existing)
+        byId.set(m.id, m);
+    // Incoming wins on name updates (the cache is fresher).
+    for (const m of incoming)
+        byId.set(m.id, m);
+    return [...byId.values()].sort((a, b) => compareScriptNames(a.name, b.name));
+}
+// Pure: flag `scriptId` as stale. No-op when the wrapper hasn't
+// reported anything for this script — the SW listener uses the
+// identity-return to skip storage writes for non-running tabs.
+//
+// Its runs in frames are marked each (`FrameRun.stale`), so a frame
+// that loads again afterwards, with the new code, isn't.
+export function markScriptStale(state, scriptId) {
+    let next = state;
+    const runs = state.frameRuns?.[scriptId];
+    if (runs && Object.values(runs).some((r) => !r.stale)) {
+        const marked = Object.fromEntries(Object.entries(runs).map(([doc, r]) => [doc, { ...r, stale: true }]));
+        next = { ...next, frameRuns: { ...next.frameRuns, [scriptId]: marked } };
+    }
+    const existing = next.staleScriptIds ?? [];
+    if (!state.actual[scriptId] || existing.includes(scriptId))
+        return next;
+    return { ...next, staleScriptIds: [...existing, scriptId] };
+}
+// Pure: clear the stale flag for `scriptId`. Used after a sm:swapped
+// report — the wrapper just ran the latest content, so any prior
+// staleness marker for this id no longer reflects reality.
+export function clearScriptStale(state, scriptId) {
+    const existing = state.staleScriptIds;
+    if (!existing || !existing.includes(scriptId))
+        return state;
+    const next = existing.filter((id) => id !== scriptId);
+    if (next.length === 0) {
+        const { staleScriptIds: _drop, ...rest } = state;
+        return rest;
+    }
+    return { ...state, staleScriptIds: next };
+}
+// Pure: note that `scriptId` logged a warning from this document.
+// Identity-returns when it already had one, so the caller can skip a
+// storage write.
+export function noteScriptWarning(state, scriptId) {
+    const existing = state.warnedIds ?? [];
+    if (existing.includes(scriptId))
+        return state;
+    return { ...state, warnedIds: [...existing, scriptId] };
+}
+// Pure: merge an incoming wrapper report into the tab's `actual` map.
+// Returns a new state object (callers re-write storage with it).
+//
+// Guard: an existing `error` entry is sticky for the same id — a later
+// sm:start (e.g. on retry / re-evaluation) shouldn't silently flip it
+// back to OK and hide the failure.
+//
+// Except for a manual script's `sm:start` (`manual`): each one is a new
+// run the person asked for, so it replaces the last run's outcome.
+export function applyScriptReport(state, id, report, manual = false) {
+    if (!manual && report.state === 'started' && state.actual[id]?.state === 'error') {
+        return state;
+    }
+    return {
+        ...state,
+        actual: { ...state.actual, [id]: report },
+    };
+}
+// Pure: count a request to run manual script `id` on this document.
+// Recorded before the run is injected, so its reports find it there.
+export function noteManualRun(state, id) {
+    const runs = state.manualRuns ?? {};
+    return { ...state, manualRuns: { ...runs, [id]: (runs[id] ?? 0) + 1 } };
+}
+// Pure: note that a wrapper in `world` reported from this document, and
+// whether it saw an opaque origin. Identity-returns when nothing is new,
+// so the caller can skip a storage write.
+export function notePageReport(state, world, opaqueOrigin) {
+    const worlds = state.reportedWorlds ?? [];
+    const newWorld = !worlds.includes(world);
+    const newOpaque = opaqueOrigin && !state.opaqueOrigin;
+    if (!newWorld && !newOpaque)
+        return state;
+    return {
+        ...state,
+        ...(newWorld ? { reportedWorlds: [...worlds, world] } : {}),
+        ...(newOpaque ? { opaqueOrigin: true } : {}),
+    };
+}
+// Pure: merge a report from a script in one of the page's iframes, the
+// same way `applyScriptReport` does for the top frame: an error stays
+// for that frame's document.
+export function applyFrameReport(state, id, frameDocId, run) {
+    const runs = state.frameRuns?.[id] ?? {};
+    if (run.state === 'started' && runs[frameDocId]?.state === 'error')
+        return state;
+    return {
+        ...state,
+        frameRuns: { ...state.frameRuns, [id]: { ...runs, [frameDocId]: run } },
+    };
+}
+// Pure: drop the frame runs whose document isn't in `liveDocIds` (the
+// tab's frames now): the frame navigated or was removed. Identity-
+// returns when nothing went, so the caller can skip a storage write.
+export function pruneFrameRuns(state, liveDocIds) {
+    if (!state.frameRuns)
+        return state;
+    let changed = false;
+    const kept = {};
+    for (const [id, runs] of Object.entries(state.frameRuns)) {
+        const live = Object.entries(runs).filter(([docId]) => liveDocIds.has(docId));
+        if (live.length !== Object.keys(runs).length)
+            changed = true;
+        if (live.length > 0)
+            kept[id] = Object.fromEntries(live);
+    }
+    if (!changed)
+        return state;
+    if (Object.keys(kept).length > 0)
+        return { ...state, frameRuns: kept };
+    const { frameRuns: _drop, ...rest } = state;
+    return rest;
+}

package/dist/extension/toolbar-summary.js

@@ -0,0 +1,105 @@
+// Pure: the toolbar icon's badge (count and color) and its hover
+// tooltip, summed up from the popup's view of the tab, so the icon and
+// the popup can't disagree about a script's status. Painted by
+// `renderBadge` in background.ts. Design: docs/matching.md#tooltip.
+import { POPUP_NO_SCRIPTS, POPUP_NOT_INJECTABLE, USER_SCRIPTS_OFF_HEADING, } from './popup-view.js';
+import { BADGE_GREEN, BADGE_GREY, BADGE_ORANGE, BADGE_PURPLE, BADGE_RED, SM_DEV_CONTROL_LABEL, countsOnBadge, runsHere, } from './tab-status.js';
+export const TOOLBAR_CLICK_HINT = 'Click for details. Double-click for collections.';
+const noun = (n) => (n === 1 ? 'script' : 'scripts');
+const scripts = (n) => `${n} ${noun(n)}`;
+const has = (n) => (n === 1 ? 'has' : 'have');
+const is = (n) => (n === 1 ? 'is' : 'are');
+export function summarizeToolbar(view, state) {
+    // An invalid script that isn't enabled is listed for reference only:
+    // it wasn't going to run, so it's not this page's problem.
+    const rows = [...view.enabled, ...view.frames, ...view.manual, ...view.disabled]
+        .flatMap((g) => g.rows)
+        .filter((r) => r.status !== 'INVALID' || r.active);
+    const count = (pred) => rows.filter(pred).length;
+    const withStatus = (...statuses) => count((r) => r.status !== null && statuses.includes(r.status));
+    const running = count((r) => state != null && runsHere(state, r.id));
+    const errors = withStatus('ERROR');
+    const rejected = withStatus('REJECTED');
+    const invalid = withStatus('INVALID');
+    // What a reload would change, each its own line: updated on disk,
+    // enabled since the page loaded (or matching only the URL it moved
+    // to), disabled or removed since but still running, or not known
+    // because the page loaded before the extension started.
+    const updated = withStatus('RELOAD');
+    const added = withStatus('PENDING');
+    const removed = withStatus('STILL_RUNNING');
+    const untracked = withStatus('UNTRACKED');
+    const missing = withStatus('MISSING');
+    const unexpected = withStatus('UNEXPECTED');
+    const warned = count((r) => r.warned);
+    const skipped = withStatus('NOT_LOADED');
+    // Manual scripts not run here yet are the normal state, and can be
+    // many (an all-pages bookmarklet), so they get no line and no badge;
+    // one counts once it has run. They still keep "No scripts match"
+    // away, which would be untrue.
+    const anyStatus = rows.some((r) => r.status !== null);
+    const anyBadged = rows.some((r) => r.status !== null && r.status !== 'NOT_RUN');
+    const lines = [];
+    if (!view.injectable)
+        lines.push(POPUP_NOT_INJECTABLE);
+    // Nothing on the page can run until they're enabled, so that is the
+    // whole story: no "skipped" line, and no reload to suggest.
+    else if (view.userScriptsDisabled)
+        lines.push(USER_SCRIPTS_OFF_HEADING);
+    else if (!anyStatus)
+        lines.push(POPUP_NO_SCRIPTS);
+    else {
+        if (running > 0)
+            lines.push(`${scripts(running)} running.`);
+        if (errors > 0)
+            lines.push(`${scripts(errors)} ${has(errors)} errors.`);
+        if (rejected > 0)
+            lines.push(`Chrome rejected ${scripts(rejected)}.`);
+        if (invalid > 0)
+            lines.push(`${scripts(invalid)} failed to load.`);
+        if (updated > 0)
+            lines.push(`Reload needed to update ${scripts(updated)}.`);
+        if (added > 0)
+            lines.push(`Reload needed to add ${scripts(added)}.`);
+        if (removed > 0)
+            lines.push(`Reload needed to remove ${scripts(removed)}.`);
+        if (untracked > 0) {
+            const why = state?.loadedWithoutUserscripts && !state.loadedBefore
+                ? 'Page loaded while user scripts were disabled'
+                : 'Page loaded before SourceMonkey started';
+            lines.push(`${why}. Reload needed for ${scripts(untracked)}.`);
+        }
+        if (missing > 0)
+            lines.push(`${missing} expected ${noun(missing)} ${is(missing)} not running.`);
+        if (unexpected > 0)
+            lines.push(`${unexpected} unexpected ${noun(unexpected)} ${is(unexpected)} running.`);
+        if (warned > 0)
+            lines.push(`${scripts(warned)} ${has(warned)} warnings.`);
+        if (skipped > 0)
+            lines.push(`${scripts(skipped)} skipped on this load.`);
+    }
+    // Red, purple, orange or grey, the first that applies, else green.
+    // Warnings have none: a header warning would otherwise keep the badge
+    // off green for good.
+    let color = null;
+    if (anyBadged) {
+        if (errors + rejected + invalid > 0 || view.userScriptsDisabled)
+            color = BADGE_RED;
+        else if (updated + added + removed + untracked > 0)
+            color = BADGE_PURPLE;
+        else if (missing + unexpected > 0)
+            color = BADGE_ORANGE;
+        // Grey says nothing ran: not for a tab where some scripts were kept
+        // out (an sm-dev claim) and the rest ran.
+        else if (skipped > 0 && running === 0)
+            color = BADGE_GREY;
+        else
+            color = BADGE_GREEN;
+    }
+    const head = view.smDev ? ['SourceMonkey', SM_DEV_CONTROL_LABEL] : ['SourceMonkey'];
+    // The rows the popup gives a status, so the count and the lines
+    // agree: a script disabled or deleted since load that never started
+    // has none, and one enabled since that hasn't run yet does.
+    const counted = count((r) => r.status !== null && r.status !== 'NOT_RUN' && (state === null || countsOnBadge(state, r.id)));
+    return { count: counted, color, title: [...head, ...lines, TOOLBAR_CLICK_HINT].join('\n') };
+}

package/dist/extension/user-scripts-access.js

@@ -0,0 +1,43 @@
+// The "Allow User Scripts" probe and the text that explains it being
+// off, shared by the collections page's banner and the popup's bar.
+//
+// The toggle lives on `chrome://extensions`. While it's off nothing
+// injects, though matching still works (the badge counts scripts).
+// Pages ask here, since Chrome tells them nothing when it changes:
+// turning it on or off changes `chrome.userScripts` in open pages at
+// once, with no event.
+import { extensionDetailsLink } from './file-access.js';
+import { USER_SCRIPTS_OFF_HEADING } from './popup-view.js';
+export { USER_SCRIPTS_OFF_HEADING };
+// Whether chrome.userScripts is callable. The namespace's presence only
+// confirms the permission is in the manifest; the toggle still has to be
+// on before a call works.
+//
+// Returns the raw error message so a page can show anything that isn't
+// the routine "toggle is off" case. Asks for no scripts by id, so the
+// call returns none: the popup probes on every redraw.
+export async function probeUserScriptsApi() {
+    // Deliberately NOT recased to a message of ours. This value shares a
+    // slot with Chrome's verbatim `err.message` below and renders as
+    // `Chrome reported: <it>`, so it is written to read as Chrome's own
+    // report rather than as SourceMonkey's sentence — the API-flavoured
+    // wording is the point. See docs/diagnostics.md#wording.
+    if (!chrome.userScripts)
+        return { usable: false, error: 'chrome.userScripts is not available' };
+    try {
+        await chrome.userScripts.getScripts({ ids: [] });
+        return { usable: true };
+    }
+    catch (err) {
+        return { usable: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// The fix, as a line of the page's own: "Open extension settings and
+// enable "Allow User Scripts" for SourceMonkey."
+export function userScriptsFixLine(tag) {
+    const line = document.createElement(tag);
+    const toggle = document.createElement('code');
+    toggle.textContent = 'Allow User Scripts';
+    line.append('Open ', extensionDetailsLink('extension settings'), ' and enable "', toggle, '" for SourceMonkey.');
+    return line;
+}