sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/page-links.js

@@ -0,0 +1,199 @@
+// How one extension page opens another.
+//
+// Two of our pages are *named tabs*: Collections and Options each have
+// at most one tab by default, and every link to them reuses it rather
+// than stacking up copies. A viewer tab is not named — it is per-script,
+// and having several open at once is the point.
+//
+// The rules this module exists to keep in one place:
+//   - A link to a named page opens in a NEW tab, never in the tab the
+//     user is reading. Leaving the viewer to look at a collection and
+//     losing the viewer is the behaviour this replaces.
+//   - "New tab" means the named one where there already is one: focus
+//     it and tell it where to scroll, instead of opening a second.
+//   - A modified click (Ctrl/Cmd/Shift/middle) is the user overriding
+//     us, and is left to the browser — which is why every one of these
+//     links is a real anchor with a real `href`, not a button.
+//
+// Usable from an extension page and from the service worker: both can
+// call `chrome.tabs` and `chrome.runtime.getContexts`, and the worker
+// passes the window it wants explicitly (see `openCollectionsPage` in
+// src/extension/background.ts).
+const PAGE_FILES = {
+    collections: 'collections.html',
+    options: 'options.html',
+};
+// Sent to a named tab that was reused rather than opened. A tab that is
+// already loaded does not act on a fragment we write into its URL, so
+// the scroll has to be asked for directly.
+export const NAMED_TAB_FOCUS_MESSAGE = 'sm:named-tab-focus';
+// The page-relative URL of a named page, for an anchor's `href`. Every
+// extension page lives at the extension root, so the browser resolves
+// it against the current page and the `chrome-extension://<id>/` prefix
+// stays out of the markup.
+export function namedPageUrl(page, hash) {
+    return hash ? `${PAGE_FILES[page]}#${hash}` : PAGE_FILES[page];
+}
+// Focus the named tab for `page` — reusing the open one where there is
+// one — and land it on `hash`.
+export async function openNamedTab(page, opts = {}) {
+    const hash = opts.hash ?? '';
+    const url = chrome.runtime.getURL(namedPageUrl(page, hash));
+    const windowId = opts.windowId !== undefined ? opts.windowId : await currentWindowId();
+    const existing = await findNamedTab(page, windowId, opts.sameWindowOnly === true);
+    if (!existing) {
+        await chrome.tabs.create(windowId == null ? { url } : { url, windowId });
+        return;
+    }
+    await chrome.tabs.update(existing.tabId, { active: true });
+    // Only when it is somewhere else: the current window is already
+    // focused, and asking again is a no-op at best.
+    if (existing.windowId != null && existing.windowId !== windowId) {
+        try {
+            await chrome.windows.update(existing.windowId, { focused: true });
+        }
+        catch {
+            // A window that closed between the lookup and here. The tab
+            // activation above is the part that mattered.
+        }
+    }
+    if (hash || !opts.preserveScroll)
+        await notifyNamedTabFocus(page, hash);
+}
+// The open tab showing `page`, preferring one in `windowId`.
+//
+// getContexts, not tabs.query({url}): filtering a query by URL needs
+// permission for that URL, and `<all_urls>` does not cover the
+// `chrome-extension:` scheme — the query comes back empty for our own
+// pages and we'd open a duplicate tab every time. getContexts needs no
+// permission and reports tabId/windowId directly. It only sees loaded
+// contexts, so a named tab still navigating is missed; the cost of that
+// is one extra tab.
+async function findNamedTab(page, windowId, sameWindowOnly) {
+    const base = chrome.runtime.getURL(PAGE_FILES[page]);
+    let contexts;
+    try {
+        contexts = await chrome.runtime.getContexts({ contextTypes: [chrome.runtime.ContextType.TAB] });
+    }
+    catch {
+        // Nothing to reuse that we can prove; opening a tab is the safe
+        // failure.
+        return null;
+    }
+    const matches = contexts.filter((ctx) => (ctx.tabId != null && ctx.tabId >= 0
+        && typeof ctx.documentUrl === 'string' && isPageUrl(ctx.documentUrl, base)));
+    const here = windowId == null ? undefined : matches.find((ctx) => ctx.windowId === windowId);
+    const pick = here ?? (sameWindowOnly ? undefined : matches[0]);
+    return pick ? { tabId: pick.tabId, windowId: pick.windowId } : null;
+}
+// Whether a document URL is this page, with or without a query string
+// and a fragment — `?first_run=1` and `#collection-…` variants are the
+// same tab. The delimiter check is what keeps a prefix match from
+// claiming a future `collections-archive.html`.
+function isPageUrl(documentUrl, base) {
+    if (!documentUrl.startsWith(base))
+        return false;
+    const rest = documentUrl.slice(base.length);
+    return rest === '' || rest.startsWith('?') || rest.startsWith('#');
+}
+// This page's window, so a link prefers the named tab the user can
+// already see. Null in the worker, and on any page Chrome won't name a
+// tab for.
+async function currentWindowId() {
+    try {
+        const tab = await chrome.tabs.getCurrent();
+        return tab?.windowId ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Tell the reused tab where to go. Broadcast rather than addressed at
+// the tab: a page cannot name itself as a message target, and the only
+// listeners are the named pages themselves — where a second Collections
+// tab exists, both scrolling to the same collection is the harmless
+// answer.
+async function notifyNamedTabFocus(page, hash) {
+    const message = { type: NAMED_TAB_FOCUS_MESSAGE, page, hash };
+    try {
+        await chrome.runtime.sendMessage(message);
+    }
+    catch {
+        // No listener answered — the tab is mid-load and will read the
+        // fragment out of its own URL instead. Not worth reporting.
+    }
+}
+// Register a named page's handler for "you were reused; go here". The
+// argument is the fragment without its `#`, empty for the top.
+export function onNamedTabFocus(page, handler) {
+    chrome.runtime.onMessage.addListener((message) => {
+        const msg = message;
+        if (!msg || msg.type !== NAMED_TAB_FOCUS_MESSAGE || msg.page !== page)
+            return undefined;
+        handler(typeof msg.hash === 'string' ? msg.hash : '');
+        // No reply, and no `true`: holding the channel open for an answer
+        // we never send makes the sender wait for the timeout.
+        return undefined;
+    });
+}
+// Turn an anchor into a link to a named page: a real href (so the
+// browser's own open-in-new-tab gestures work and the URL is
+// copyable), and a plain left click routed through `openNamedTab`.
+export function wireNamedTabLink(a, page, hash) {
+    a.href = namedPageUrl(page, hash);
+    // The href alone would open a new tab; the handler below is what
+    // makes it the NAMED one. `target` is what a modified click and a
+    // pre-script click both fall back to.
+    a.target = '_blank';
+    a.rel = 'noopener';
+    a.addEventListener('click', (ev) => {
+        if (!isPlainClick(ev))
+            return;
+        ev.preventDefault();
+        void openNamedTab(page, { hash });
+    });
+}
+// The header bar's product name and icon, on every page that is not the
+// collections page, are a link home. One delegated listener rather than
+// per-element wiring: the viewer repaints its heading (and the link
+// inside it) on every in-place navigation.
+export function installHomeLinkHandler() {
+    document.addEventListener('click', (ev) => {
+        if (!isPlainClick(ev))
+            return;
+        const target = ev.target;
+        if (!(target instanceof Element))
+            return;
+        if (!target.closest('a.page-home'))
+            return;
+        ev.preventDefault();
+        void openNamedTab('collections');
+    });
+}
+// A click we are allowed to reinterpret: primary button, no modifier.
+// Anything else is the user asking the browser for a new tab, a new
+// window, or a download, and the anchor's own href serves that.
+function isPlainClick(ev) {
+    return !ev.defaultPrevented && ev.button === 0
+        && !ev.ctrlKey && !ev.metaKey && !ev.shiftKey && !ev.altKey;
+}
+// Open an extension page in a plain new tab — no reuse, because the
+// destination is per-script (a viewer or an install preview) and two of
+// them is a normal thing to want.
+//
+// Returns the promise rather than dropping it: an unhandled rejection
+// in an extension page is reported into chrome://extensions/?errors,
+// where it reads as SourceMonkey being broken.
+export function openExtensionTab(url) {
+    return chrome.tabs.create({ url }).then(() => undefined);
+}
+// Open an extension page in a new background tab, as a middle click or
+// Ctrl/Cmd-click on a link does.
+export function openBackgroundTab(url) {
+    return chrome.tabs.create({ url, active: false }).then(() => undefined);
+}
+// Open an extension page in a new window, as a Shift-click on a link
+// does.
+export function openExtensionWindow(url) {
+    return chrome.windows.create({ url }).then(() => undefined);
+}

package/dist/extension/parse-check-client.js

@@ -0,0 +1,70 @@
+// Page-side compile-only parse check, for the install preview: it
+// compiles a script it hasn't added yet, before the user decides, so
+// there's no stored row for the store's checker to run on.
+//
+// Every stored row is checked in the service worker, which runs every
+// refresh, add and install (docs/worker-writes.md), through the
+// offscreen document.
+//
+// A page has a DOM, so it embeds its own `parse-sandbox.html` and
+// compiles locally — `parse-sandbox-host.ts` does the driving, exactly
+// as it does for the offscreen document on the service worker's
+// behalf. The service worker is not involved: no wake, and no copy of
+// the script across contexts, before the user has even chosen to
+// install.
+//
+// Only the transport differs from the service worker's checker. Both
+// compose the checked text with `buildParseCheckSource`, so both judge
+// the same program.
+//
+// Fails open like every other leg of this feature (see
+// [docs/parse-check.md]): a sandbox that won't load, a timeout, a
+// verdict in an unrecognised shape, or a throw anywhere in between all
+// resolve to `null` = "couldn't check", never to "didn't parse".
+import { buildParseCheckSource } from '../composed-source.js';
+import { dlog } from '../debug-log.js';
+import { attachParseLocation } from '../parse-location.js';
+import { isParseCheckDisabled } from '../parse-check-protocol.js';
+import { createParseSandboxHost } from './parse-sandbox-host.js';
+export const checkScriptParses = async (script) => {
+    if (await isParseCheckDisabled())
+        return null;
+    try {
+        const source = buildParseCheckSource(script);
+        const verdicts = await ensureHost().compile([source.text]);
+        // Resolved here rather than by the caller: `source` is what maps a
+        // reported line back to a file, and this is the last point where
+        // we still hold it.
+        return verdicts ? attachParseLocation(verdicts[0], source) : null;
+    }
+    catch (err) {
+        dlog(`[SourceMonkey] parse check unavailable in this page: ${String(err)}`);
+        return null;
+    }
+};
+// One frame per page, created on the first check rather than at
+// startup: a page that never adds or refreshes anything (the common
+// case for the viewer) never pays for it. Once created it stays for
+// the life of the page — checks come in bursts (a Refresh All is one
+// per script), and re-creating the frame per check would pay the load
+// and readiness handshake every time.
+let host = null;
+function ensureHost() {
+    if (host)
+        return host;
+    const frame = document.createElement('iframe');
+    // `src`, not `srcdoc`: the URL has to resolve to the page listed in
+    // the manifest's `sandbox.pages`, or the frame inherits this page's
+    // CSP and loses the `'unsafe-eval'` that is the entire point.
+    frame.src = 'parse-sandbox.html';
+    // Belt-and-braces, mirroring offscreen.html: the page is already
+    // sandboxed by the manifest key, and this keeps the frame from
+    // silently becoming a privileged extension page — with `chrome.*`
+    // reachable from whatever it compiles — if that key is ever dropped.
+    frame.setAttribute('sandbox', 'allow-scripts');
+    frame.hidden = true;
+    frame.style.display = 'none';
+    document.body.append(frame);
+    host = createParseSandboxHost(frame);
+    return host;
+}

package/dist/extension/parse-check.js

@@ -0,0 +1,161 @@
+// Service-worker side of the compile-only parse check.
+//
+// ---------- What this answers ----------
+//
+// "Would V8 accept the code we are about to register?" — asked at
+// install / refresh time rather than discovered at injection time.
+//
+// Before this existed, a `@require` with a syntax error (a truncated
+// CDN response, an HTML error page that squeaked past the content-type
+// gate) made the whole concatenated entry fail to parse. The seal
+// entry caught it and logged "Script source failed to parse (a
+// @require or the script body has a syntax error); nothing was run" —
+// but only on a page the script matched. Checking up front turns that
+// into an `invalid` status on the collections page, next to the script,
+// the moment it is added or refreshed.
+//
+// The verdict is about the whole composed program, so on its own it
+// says nothing about WHERE. The sandbox answers that separately, by
+// compiling the same text a second way to get a line and column out of
+// V8, and `parse-location.ts` maps that line back to the `@require`
+// (or the body) it was written in.
+//
+// This is the SERVICE WORKER's route to the sandbox. Extension pages
+// have a DOM and embed their own sandbox frame instead — see
+// `parse-check-client.ts`. Both share `parse-sandbox-host.ts`.
+//
+// ---------- Why the SW route takes three contexts ----------
+//
+// `new Function(src)` compiles without executing, which is exactly the
+// check — and it is V8's own verdict on the same text we inject, not a
+// bundled parser's opinion about a similar text. But it is `eval` as
+// far as CSP is concerned, and MV3's extension CSP forbids that in the
+// service worker, in extension pages, and in offscreen documents.
+//
+// A **sandboxed page** may declare `'unsafe-eval'`, and is the only
+// context that may. It also has an opaque origin and no `chrome.*`, so
+// it cannot be messaged by the service worker directly. Hence:
+//
+//   service worker  →  offscreen document  →  sandboxed iframe
+//     (chrome.*,          (chrome.* + DOM,        ('unsafe-eval',
+//      no DOM,             no eval)                no chrome.*)
+//      no eval)
+//
+// Considered and rejected: bundling a real parser (acorn, vendored the
+// way Prism is). It needs no offscreen machinery and runs synchronously
+// in the worker — but it parses a *Program* where our injected code is
+// a *function body*, so it disagrees with V8 on top-level `return`,
+// `await` and `new.target`. Those appear in real userscripts, and a
+// parser that rejects code V8 accepts would flip working scripts to
+// invalid. Being wrong in that direction is much worse than the setup
+// cost here.
+//
+// ---------- Failing open ----------
+//
+// Every failure of this machinery itself — no `chrome.offscreen`, the
+// document won't open, the sandbox never answers — resolves to "I
+// don't know", never to "didn't parse". A script that works must not
+// be marked invalid because our plumbing broke. The seal entry is
+// still in place as the backstop, so a parse failure we miss here is
+// reported at run time exactly as it was before.
+import { dlog } from '../debug-log.js';
+import { PARSE_CHECK_MSG } from '../parse-check-protocol.js';
+const OFFSCREEN_URL = 'offscreen.html';
+// How long to wait for the sandbox before giving up on a batch. The
+// compile itself is fast (V8 parsing a few hundred KB), so this is a
+// guard against the offscreen document being torn down mid-flight
+// rather than a realistic budget. Kept short because opportunistic
+// refresh runs on the navigation path: a wedged check should cost a
+// moment, not ten seconds per pass.
+const PARSE_TIMEOUT_MS = 3_000;
+// After this many consecutive failures, stop trying for the rest of
+// the service-worker's life. Without it, a permanently broken sandbox
+// costs every refresh a full timeout per script forever — a
+// degraded-capability path that gets slower the more scripts you have
+// is worse than one that turns itself off.
+const FAILURE_LIMIT = 3;
+let consecutiveFailures = 0;
+// `chrome.offscreen.createDocument` rejects if one already exists, and
+// there is no "create if absent" call. Serializing through one promise
+// keeps two concurrent refreshes from racing into that rejection.
+let creating = null;
+// True when this browser can run the check at all. Chrome gained
+// `chrome.offscreen` in 109; we don't support anything near that old,
+// but the guard also covers test environments and any future context
+// where the API is absent.
+export function parseCheckAvailable() {
+    return typeof chrome !== 'undefined' && !!chrome.offscreen;
+}
+// Reset the circuit breaker. Exposed for tests, which need a clean
+// slate between cases that deliberately break the machinery.
+export function resetParseCheckFailures() {
+    consecutiveFailures = 0;
+}
+async function ensureOffscreenDocument() {
+    if (creating)
+        return creating;
+    creating = (async () => {
+        // hasDocument() landed alongside the API; getContexts() is the
+        // newer spelling. Prefer whichever exists rather than assuming.
+        const existing = await hasOffscreenDocument();
+        if (existing)
+            return;
+        await chrome.offscreen.createDocument({
+            url: OFFSCREEN_URL,
+            reasons: [chrome.offscreen.Reason.IFRAME_SCRIPTING],
+            justification: 'Compile userscript source in a sandboxed iframe to detect syntax errors without running it.',
+        });
+    })().finally(() => {
+        creating = null;
+    });
+    return creating;
+}
+async function hasOffscreenDocument() {
+    const runtime = chrome.runtime;
+    if (runtime.getContexts) {
+        const contexts = await runtime.getContexts({ contextTypes: ['OFFSCREEN_DOCUMENT'] });
+        return contexts.length > 0;
+    }
+    const offscreen = chrome.offscreen;
+    return offscreen.hasDocument ? offscreen.hasDocument() : false;
+}
+// Compile each source independently. Returns one verdict per input, or
+// null when the check could not be performed at all — callers must
+// treat null as "unknown", never as failure. See "Failing open" above.
+export async function checkParses(sources) {
+    if (sources.length === 0)
+        return [];
+    if (!parseCheckAvailable())
+        return null;
+    if (consecutiveFailures >= FAILURE_LIMIT)
+        return null;
+    try {
+        await ensureOffscreenDocument();
+        // Correlating a reply with its request is the sandbox host's job
+        // (`parse-sandbox-host.ts`) — this leg is a single awaited
+        // sendMessage, so there is nothing here to mix up.
+        const reply = await withTimeout(chrome.runtime.sendMessage({ type: PARSE_CHECK_MSG, sources }), PARSE_TIMEOUT_MS);
+        const verdicts = reply?.verdicts;
+        if (!Array.isArray(verdicts) || verdicts.length !== sources.length) {
+            dlog('[SourceMonkey] parse check returned no usable verdicts');
+            consecutiveFailures++;
+            return null;
+        }
+        consecutiveFailures = 0;
+        return verdicts;
+    }
+    catch (err) {
+        // console.info, not .warn/.error: this is a degraded-capability
+        // path, not an extension bug, and Chrome forwards warn/error into
+        // chrome://extensions/?errors.
+        console.info('[SourceMonkey] parse check unavailable', err);
+        consecutiveFailures++;
+        return null;
+    }
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('parse check timed out')), ms);
+        promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+    });
+}

package/dist/extension/parse-sandbox-host.js

@@ -0,0 +1,172 @@
+// Drives a sandboxed parse page over `postMessage`, for any context
+// that has a DOM.
+//
+// The compile itself must happen in a sandboxed page — `new Function`
+// is `eval` as far as CSP is concerned, and a sandboxed page is the
+// only place allowed to declare `'unsafe-eval'` (see
+// [docs/parse-check.md]). A sandboxed page has an opaque origin and no
+// `chrome.*`, so it can only be reached by whoever embeds it.
+//
+// Two contexts embed one:
+//
+//   - `offscreen.ts`, on behalf of the service worker. The SW has no
+//     DOM, so it cannot host an iframe at all; the offscreen document
+//     exists to be the DOM it lacks.
+//   - extension pages (`parse-check-client.ts`). A page already has a
+//     DOM, so it embeds its own frame and skips the service worker
+//     entirely — no wake, no cross-context clone of the script, and no
+//     dependency on the SW being alive mid-request.
+//
+// Both get the same behaviour from here: readiness, correlation,
+// timeouts, verdict validation, and the circuit breaker.
+import { PARSE_CHECK_MSG, PARSE_CHECK_RESULT_MSG, PARSE_SANDBOX_READY_MSG, } from '../parse-check-protocol.js';
+// Per-request ceiling. The compile is fast (V8 parsing a few hundred
+// KB), so this guards against the frame being torn down mid-flight
+// rather than budgeting real work. It also stops `pending` from
+// growing a dead resolver per abandoned request — an offscreen
+// document outlives service-worker restarts, so "leaks slowly,
+// forever" is a real shape there.
+//
+// Longer than the service worker's own `PARSE_TIMEOUT_MS`
+// (`parse-check.ts`), deliberately: the SW is on the navigation path
+// and gives up early, this is the last resort that keeps `pending`
+// bounded. On the SW route that means the SW usually abandons a stuck
+// request before this fires, so the breaker below mostly counts
+// failures on the page route.
+const REQUEST_TIMEOUT_MS = 8_000;
+// Readiness cannot be observed from outside. A sandboxed frame is
+// opaque-origin, so `frame.contentDocument` is ALWAYS null and its
+// `readyState` is unreadable — an "is it loaded?" fast path looks
+// reasonable and can never fire. That leaves two signals, and we take
+// whichever arrives first:
+//
+//   - the sandbox's own ready ping, sent as the last thing it does;
+//   - the iframe's `load` event, in case the ping was posted before
+//     the listener existed.
+//
+// The timeout is the third leg, and the important one: without it a
+// missed signal wedges readiness forever and every check silently
+// times out for the rest of the session. Resolving anyway lets the
+// request through — the sandbox is almost certainly up, and if it
+// isn't, the per-request timeout reports "couldn't check" rather than
+// lying.
+const FRAME_READY_TIMEOUT_MS = 2_000;
+// After this many consecutive failures, stop trying. Without it a
+// permanently broken sandbox costs every refresh a full timeout per
+// script forever — a degraded-capability path that gets slower the
+// more scripts you have is worse than one that turns itself off.
+//
+// Per host, not global: one wedged page no longer speaks for the whole
+// extension, which is part of what embedding per-context buys.
+const FAILURE_LIMIT = 3;
+// ...but the trip is not permanent. The offscreen document is never
+// torn down and is reused for the life of the browser session, so a
+// sticky breaker there would mean three unlucky timeouts disable the
+// check until the browser restarts — including after the sandbox
+// recovers. Instead a tripped host lets one probe request through per
+// cooldown: if it succeeds the breaker resets, if it fails the host
+// goes quiet for another cooldown. The cost of staying wedged stays
+// bounded, and recovery costs one timeout every 30s rather than never
+// happening.
+const BREAKER_COOLDOWN_MS = 30_000;
+export function createParseSandboxHost(frame) {
+    // Requests waiting on the sandbox, by correlation id.
+    const pending = new Map();
+    let consecutiveFailures = 0;
+    let breakerTrippedAt = 0;
+    const frameReady = new Promise((resolve) => {
+        // Named and removed rather than inline: readiness is answered once,
+        // but this listener would otherwise keep type-checking every
+        // message reaching the context for as long as it lives.
+        const onReadyMessage = (event) => {
+            if (event.source !== frame.contentWindow)
+                return;
+            if (event.data?.type === PARSE_SANDBOX_READY_MSG)
+                done();
+        };
+        const done = () => {
+            window.removeEventListener('message', onReadyMessage);
+            resolve();
+        };
+        window.addEventListener('message', onReadyMessage);
+        frame.addEventListener('load', done, { once: true });
+        setTimeout(done, FRAME_READY_TIMEOUT_MS);
+    });
+    window.addEventListener('message', (event) => {
+        // Only the sandboxed frame can reach an offscreen document in
+        // practice, but a normal extension page is a richer target — check
+        // the source so nothing else can resolve a request.
+        if (event.source !== frame.contentWindow)
+            return;
+        const data = event.data;
+        if (!data || data.type !== PARSE_CHECK_RESULT_MSG)
+            return;
+        if (typeof data.id !== 'string' || !Array.isArray(data.verdicts))
+            return;
+        const resolve = pending.get(data.id);
+        if (!resolve)
+            return;
+        pending.delete(data.id);
+        // A verdict we don't recognise is not a verdict. `applyParseCheck`
+        // treats anything that isn't `ok`/`unknown` as `invalid`, so an
+        // unexpected status string would DISABLE the script — exactly what
+        // the three-state design exists to prevent.
+        resolve(data.verdicts.every(isParseVerdict) ? data.verdicts : null);
+    });
+    // Stamp the trip on the failure that reaches the limit, so the
+    // cooldown runs from when the host went quiet.
+    const noteFailure = () => {
+        consecutiveFailures++;
+        if (consecutiveFailures === FAILURE_LIMIT)
+            breakerTrippedAt = Date.now();
+    };
+    return {
+        async compile(sources) {
+            if (sources.length === 0)
+                return [];
+            if (consecutiveFailures >= FAILURE_LIMIT) {
+                if (Date.now() - breakerTrippedAt < BREAKER_COOLDOWN_MS)
+                    return null;
+                // Probe: let this one through, and re-arm the cooldown now so a
+                // second caller during the probe doesn't get a second probe.
+                breakerTrippedAt = Date.now();
+            }
+            await frameReady;
+            const win = frame.contentWindow;
+            if (!win) {
+                // The frame went away (document teardown racing a request).
+                noteFailure();
+                return null;
+            }
+            // Random rather than a counter: an offscreen document outlives
+            // service-worker restarts, and a counter restarts at zero with
+            // it. A reused id can resolve a NEW request with an OLD
+            // request's verdicts, which is the one way this machinery could
+            // mark a good script invalid.
+            const id = crypto.randomUUID();
+            const verdicts = await new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    resolve(null);
+                }, REQUEST_TIMEOUT_MS);
+                pending.set(id, (v) => { clearTimeout(timer); resolve(v); });
+                win.postMessage({ type: PARSE_CHECK_MSG, id, sources }, '*');
+            });
+            if (!verdicts || verdicts.length !== sources.length) {
+                noteFailure();
+                return null;
+            }
+            consecutiveFailures = 0;
+            return verdicts;
+        },
+    };
+}
+const PARSE_STATUSES = ['ok', 'syntax-error', 'unknown'];
+// Exported for the unit test: this predicate is the last thing between
+// an unrecognised status string and `applyParseCheck` disabling the
+// script it describes, so it is worth testing directly rather than
+// only through a sandbox that would have to be made to misbehave.
+export function isParseVerdict(value) {
+    const status = value?.status;
+    return PARSE_STATUSES.includes(status);
+}