sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/script-updater.js

@@ -0,0 +1,991 @@
+// Single entry point for every userscript refresh path.
+//
+// Two trigger modes share the same underlying work (refreshScript /
+// refreshCollection / refreshAllCollections in script-store.ts):
+//
+//   - 'manual'        — the user clicked a Refresh button. Always runs.
+//                       Awaited by the caller so the UI can show a
+//                       spinner and react to the result.
+//   - 'opportunistic' — the SW noticed a page that uses some scripts
+//                       and wants to check whether their source files
+//                       changed on disk. Fire-and-forget. Rate-limited
+//                       to no sooner than UPDATE_MIN_INTERVAL_MS after
+//                       the previous completion, and never concurrent
+//                       for the same resource.
+//
+// In both modes a check that's currently in flight for a resource is
+// shared — a manual click that lands while an opportunistic check is
+// already running awaits that existing promise instead of starting a
+// second pass. This holds PER gate key: the script gate
+// (`updateScript`), the collection gate (`updateCollection`), and the
+// all-collections gate (`updateAllCollections`) are independent maps,
+// so an opportunistic `updateScript(X)` can still run alongside a
+// manual `updateCollection(S⊇X)` or `updateAllCollections` that also
+// rebuilds X. They fetch the same bytes, and their storage writes are
+// serialized and re-read user-owned state by `script-store.ts`'s
+// `mutate()` lock (see docs/storage.md "Write serialization"), so the
+// overlap is idempotent rather than corrupting — but it is NOT deduped
+// to a single fetch.
+//
+// We deliberately don't try to mark tabs stale from here. The actual
+// stale propagation happens via chrome.storage.onChanged in
+// background.ts so that ANY write that changes a script's content
+// (this module, external tools poking storage, future paths we haven't
+// imagined) triggers the same propagation.
+import { getAllScriptMetas, getScriptMeta, getCollections, getCollectionWithScriptMeta, loadStateLogEntry, localFileLogMessages, startupLogEntry, refreshAllCollections, refreshScript, refreshCollection, createRefreshBatch, setVersionProbes, } from './script-store.js';
+import { outdatedProbe, probeLabel, probeTargets, probesAreFresh, } from '../version-probe.js';
+import { isContainerCollection } from './directories.js';
+import { probeVersions } from './version-probe-fetch.js';
+import { mapWithConcurrency, PROBE_SCRIPTS_CONCURRENCY } from './concurrency.js';
+import { describeRefreshError, readRefreshErrors } from './refresh-error.js';
+import { getValue } from '../userscript-header.js';
+import { formatBytes, scriptOutdatedProbe } from '../script-display.js';
+import { dlog } from '../debug-log.js';
+import { startPhaseTimer, resetPhaseTotals, reportPhaseTotals } from '../phase-timing.js';
+import { githubTokenLogSuffix } from '../github-auth.js';
+import { getScriptLogLabel } from './script-log-id.js';
+import { appendScriptLog, logScriptEvent } from './script-log.js';
+import { describeDiagnostic } from '../diagnostic-location.js';
+import { retryRejectedRegistrations } from './injector.js';
+// Minimum gap between opportunistic checks for the same resource. The
+// 10s figure is a balance: short enough that a user editing a script
+// and switching tabs sees the update within a click or two, long
+// enough that the background work doesn't measurably affect navigation.
+export const UPDATE_MIN_INTERVAL_MS = 10_000;
+// Allow tests to swap the clock. Production uses Date.now.
+let nowMsImpl = () => Date.now();
+export function _setNowForTests(fn) {
+    nowMsImpl = fn;
+}
+// Pure-ish core: run `task` if and only if there isn't one already in
+// flight for this resource, and (for opportunistic mode) the cooldown
+// has elapsed. Returns the active promise either way. The state Map is
+// mutated in place; callers pass in a stable per-resource-type map so
+// independent resources can run concurrently.
+//
+// Exported so tests can exercise the concurrency/rate-limit logic
+// without touching chrome.storage.
+export function gate(state, key, mode, task, skipResult, 
+// How the rate-limit skip below names this resource. Only the caller
+// knows whether the key is a script, a collection, or the
+// all-collections sentinel, and only a script has a readable label —
+// so the naming is passed in rather than guessed from the key.
+label = String(key), 
+// A caller that needs its own run's result (a Refresh click: forced
+// probe, awaited parse check) rather than a running check's. It waits
+// for that check, then runs, and later callers join it instead.
+own = false) {
+    let slot = state.get(key);
+    if (!slot) {
+        slot = {};
+        state.set(key, slot);
+    }
+    // Coalesce onto any in-flight work for this resource regardless of
+    // mode, unless the caller needs its own run (`own`). A manual check
+    // during a background one shouldn't start a second fetch; it should
+    // wait for the running one.
+    const running = slot.inFlight?.promise;
+    if (running && !own)
+        return running;
+    if (mode === 'opportunistic') {
+        const last = slot.lastCompletedAt ?? 0;
+        const since = nowMsImpl() - last;
+        if (since < UPDATE_MIN_INTERVAL_MS) {
+            // Logged because a rate-limited check does nothing else: no
+            // fetch, no storage write, no other log line. Without this it
+            // looks identical to a check that never started.
+            dlog(`[SourceMonkey] update check skipped for ${label}: ` +
+                `checked ${Math.round(since / 1000)}s ago, interval is ${UPDATE_MIN_INTERVAL_MS / 1000}s`);
+            return Promise.resolve(skipResult);
+        }
+    }
+    // The slot entry first: its cleanup compares the slot against it.
+    const entry = {};
+    entry.promise = (async () => {
+        if (running)
+            await running.catch(() => undefined);
+        try {
+            return await task();
+        }
+        finally {
+            const s = state.get(key);
+            if (s) {
+                // Only its own entry: an `own` run may have taken the slot since.
+                if (s.inFlight === entry)
+                    s.inFlight = undefined;
+                s.lastCompletedAt = nowMsImpl();
+            }
+        }
+    })();
+    slot.inFlight = entry;
+    return entry.promise;
+}
+// Separate maps per result type so type inference stays clean.
+const scriptState = new Map();
+const collectionState = new Map();
+const allCollectionsState = new Map();
+// "all collections" is one global slot, but reuse the same shape so the
+// concurrency/rate-limit logic stays uniform.
+const ALL_COLLECTIONS_KEY = '*';
+// Public API ---------------------------------------------------------
+// `probe` is separate from `mode` on purpose. `manual` means "not
+// rate-limited as a refresh", and the reload fast-path uses it for
+// every matched script on every explicit tab reload — so treating
+// `manual` as "the user asked, check upstream now" would fire a
+// third-party request per script per reload. Only a genuine Refresh
+// click passes `'force'`.
+//
+// `parseCheck` follows one rule, and it is deliberately not the same
+// axis as `mode`: **a navigation-triggered check never waits for a
+// parse verdict; a user-initiated one does.** Both of this module's
+// navigation callers therefore pass 'defer' — the reload fast path,
+// which has a wrapper in the page blocked on the answer, and the
+// opportunistic sweep, which has nobody waiting at all.
+//
+// The rule has to be uniform because `gate()` coalesces regardless of
+// mode, and both of those callers are queued off the same
+// `onCommitted`. If one of them waited for the verdict, whichever
+// reached the gate first would decide for both — so the fast path
+// would silently pay the check on exactly the first reload after an
+// idle gap, which is the ordinary edit-save-reload loop.
+//
+// The same coalescing would let a user-initiated check inherit a
+// verdict-less row, and miss its forced probe. So a check that forces
+// the probe (a Refresh click, from a page or from sm-dev) doesn't join a
+// running one: it waits for it, then runs its own (`own` in `gate`).
+// `batch` shares the reads a group of checks started together would
+// otherwise each do (see `RefreshBatch`). Every navigation-triggered
+// fan-out passes one — the reload fast path and the opportunistic
+// sweep share the batch their common `onCommitted` created. The
+// user-initiated single-script callers (the Refresh buttons) don't:
+// they check one script, so there is nothing to share.
+//
+// **A coalesced call inherits the running check's batch, and that is
+// safe.** `gate()` hands a second caller the FIRST call's promise, so it
+// has always received that call's whole result — rows, verdicts and all.
+// Which cache produced those rows changes nothing: the coalescing caller
+// never had a refresh of its own to be given stale data from.
+export function updateScript(scriptId, mode, probe = 'if-stale', parseCheck = 'await', batch) {
+    return gate(scriptState, scriptId, mode, () => runScriptCheck(scriptId, mode, probe, parseCheck, batch), null, getScriptLogLabel(scriptId), probe === 'force');
+}
+// Only ever reached from a Refresh button, so probes force by default.
+export function updateCollection(collectionId, mode, probe = 'force') {
+    return gate(collectionState, collectionId, mode, () => runCollectionCheck(collectionId, mode, probe), null, `collection ${collectionId}`);
+}
+// Only ever reached from Refresh All, so probes force by default.
+export function updateAllCollections(mode, probe = 'force') {
+    // We have to do the cast dance because gate is generic over a single
+    // result type and the skip result for "no work done" is just an empty
+    // map, not null.
+    return gate(allCollectionsState, ALL_COLLECTIONS_KEY, mode, () => runAllCollectionsCheck(mode, probe), new Map(), 'all collections');
+}
+// ---------- Task wrappers that log lifecycle to the SW console -------
+//
+// Each user-visible check goes through these so the SW console tells
+// the story: "checking X", then either "no change", "loaded new
+// content", or "failed: <err>". Without this it's hard to tell
+// whether the opportunistic refresh is even running.
+//
+// We do a getScript / getCollectionWithScripts read BEFORE the refresh
+// so we have the prior loadedAt to compare against the post-refresh
+// row. One extra storage read per check — cheap.
+// `@require` + `@resource` policy by trigger mode. Manual clicks
+// rebuild deps from scratch so users can pick up remote updates
+// without touching the main script. Opportunistic background checks
+// preserve the cached entries verbatim and only fetch newly-declared
+// refs — keeping page-load cost bounded.
+function fileRecheckMode(mode) {
+    return mode === 'manual' ? 'all' : 'preserve';
+}
+async function runScriptCheck(scriptId, mode, probe, parseCheck = 'await', batch) {
+    const prior = await getScriptMeta(scriptId);
+    const label = getScriptLogLabel(scriptId);
+    // Manual checks fire on a deliberate user click and are infrequent;
+    // their start + "no change" outcome stays at console.log so the user
+    // gets unconditional confirmation that the click did something.
+    // Opportunistic checks fire on every navigation and are gated by the
+    // debug flag.
+    const checkLog = mode === 'manual' ? console.log : dlog;
+    const tokenSuffix = prior?.fileUrl ? githubTokenLogSuffix(prior.fileUrl) : '';
+    checkLog(`[SourceMonkey] update check (${mode}): ${label}${tokenSuffix}`);
+    // No Log-tab row before the work: `emitScriptOutcomeLog` writes the
+    // whole story afterwards, as one line when there is nothing to report
+    // and a `Checking for updates` preamble when there is. The SW console
+    // above still brackets the work for anyone watching it live.
+    let next;
+    try {
+        next = await refreshScript(scriptId, {
+            recheckFiles: fileRecheckMode(mode),
+            parseCheck,
+            ...(batch ? { batch } : {}),
+        });
+    }
+    catch (err) {
+        const msg = describe(err);
+        console.info(`[SourceMonkey] update check failed: ${label}: ${msg}`);
+        // Stands alone — it names the check and its failure in one line,
+        // so it needs no preamble.
+        //
+        // `state: 'refresh-failed'` even though the row carries no
+        // `refreshError` (the throw came from before the row was written):
+        // the meaning is the same — this check didn't complete and the
+        // cached copy keeps running — and a bare `error` would bump the
+        // `loglevel:` sentinel and leave the script badged ERROR for the
+        // rest of the session over a failure the next check may not repeat.
+        logScriptEvent(scriptId, {
+            level: 'error',
+            state: 'refresh-failed',
+            source: refreshLogSource(mode),
+            message: `Could not check for updates: ${msg}`,
+        });
+        throw err;
+    }
+    logScriptOutcome(label, prior, next, mode);
+    emitScriptOutcomeLog(scriptId, prior, next, mode);
+    // Deliberately NOT awaited. This promise is what the reload
+    // fast-path races against a 500 ms window (see
+    // docs/injection.md#reload-fast-path) — folding a third-party fetch
+    // into it would blow that budget and drop the reload back to running
+    // the old body. The probe's own storage write repaints any open
+    // viewer via storage.onChanged when it lands.
+    if (next)
+        void runVersionProbes([next], probe);
+    // Not awaited, same as the probe above: it must not sit in the
+    // fast-path window. No-ops unless this script is currently rejected,
+    // in which case a refresh that changed nothing would otherwise never
+    // re-offer it to Chrome. See `retryRejectedRegistrations`.
+    //
+    // `probe === 'force'` is the only signal we have for "the user
+    // clicked Refresh" — `mode: 'manual'` means "not rate-limited" and
+    // the reload fast-path uses it for every matched script on every
+    // reload. A click retries immediately; a navigation-driven check
+    // takes the rate limit, so one page load can't produce a burst of
+    // identical rows.
+    void retryRejectedRegistrations([scriptId], { userInitiated: probe === 'force' });
+    return next;
+}
+async function runCollectionCheck(collectionId, mode, probe) {
+    const priorData = await getCollectionWithScriptMeta(collectionId);
+    const prior = priorData
+        ? { collection: priorData.collection, scripts: new Map(priorData.scripts.map((s) => [s.id, s])) }
+        : undefined;
+    const label = priorData?.collection.path ?? collectionId;
+    // Suffix the start line with "(with GitHub token)" when the
+    // collection URL would carry the GitHub auth header on fetch. Lets
+    // the user confirm from the SW console that their Options-page token
+    // is actually in play for this collection (otherwise a silent "still
+    // hitting unauthenticated rate limits" is hard to diagnose).
+    const tokenSuffix = prior?.collection.path ? githubTokenLogSuffix(prior.collection.path) : '';
+    console.log(`[SourceMonkey] collection refresh (${mode}): ${label}${tokenSuffix}`);
+    // Sits OUTSIDE refreshCollection's own timer rather than extending it:
+    // the probes and the rejection retry are this layer's work, and the
+    // question "is the refresh slow or is the annotation pass slow?" is
+    // exactly what the split answers.
+    const timer = startPhaseTimer(`collection check (${mode})`);
+    resetPhaseTotals();
+    let result;
+    try {
+        result = await refreshCollection(collectionId, { recheckFiles: fileRecheckMode(mode) });
+    }
+    catch (err) {
+        const msg = describe(err);
+        console.info(`[SourceMonkey] collection refresh failed: ${label}: ${msg}`);
+        // A throw out of refreshCollection leaves every script under this
+        // collection unrefreshed. Say so in each one's Log rather than
+        // letting the failure live only in the SW console.
+        logCollectionEventToScripts([...(prior?.scripts.values() ?? [])], mode, await collectionFailureMessage(collectionId, msg));
+        throw err;
+    }
+    timer.mark('refresh');
+    if (result) {
+        summarizeCollectionOutcome(label, prior, result, mode);
+        await runVersionProbes(result.scripts, probe);
+        timer.mark('probes');
+        timer.note(() => `${probedCount(result.scripts)} of ${result.scripts.length} scripts have a probe target`);
+        // Retry any script under this collection that Chrome is refusing —
+        // refreshing a collection is one of the places a user goes to say
+        // "try again". See `retryRejectedRegistrations`.
+        await retryRejectedRegistrations(result.scripts.map((s) => s.id), { userInitiated: probe === 'force' });
+        timer.mark('retry-rejected');
+    }
+    timer.done();
+    reportPhaseTotals('collection check');
+    return result;
+}
+// How many of these scripts a probe pass would actually fetch for.
+// Reported alongside the probe phase because a `0ms` probe leg means
+// two very different things — nothing to check, or everything already
+// fresh — and only the count separates them.
+function probedCount(scripts) {
+    return scripts.filter((s) => s.status === 'ok' && probeTargets(s.header, s.fileUrl).length > 0).length;
+}
+// The one sentence a collection-level refresh failure gets in every
+// affected script's Log, whichever entry point caught it. Both callers
+// route through here so the same failure can't read two ways.
+//
+// Which sentence depends on WHERE it failed, and the recorded map is the
+// evidence: `refreshCollection` records only when its write throws, so
+// an entry means the collection was read fine and couldn't be stored.
+// A throw with nothing recorded came from earlier in the pipeline — a
+// storage read, a hash, a rebuild — and must not claim the read
+// succeeded, so it gets the generic wording.
+async function collectionFailureMessage(collectionId, fallbackReason) {
+    const recorded = (await readRefreshErrors())[collectionId];
+    return recorded
+        ? describeRefreshError(recorded)
+        : `Could not refresh this collection: ${fallbackReason}`;
+}
+async function runAllCollectionsCheck(mode, probe) {
+    console.log(`[SourceMonkey] refreshing all collections (${mode})`);
+    // Same split as runCollectionCheck: each collection times its own
+    // refresh, so what this adds is the work Refresh All does AROUND
+    // them — the prior snapshot, and the probe + retry pass that runs
+    // once over every script in every collection rather than per
+    // collection.
+    const timer = startPhaseTimer(`all-collections check (${mode})`);
+    resetPhaseTotals();
+    // Snapshot priors BEFORE the refresh; reading after would just give
+    // back the post-refresh state and the summary would always say 0
+    // updated / 0 added.
+    const priorByCollectionId = await snapshotAllCollectionScripts();
+    timer.mark('snapshot');
+    let result;
+    try {
+        result = await refreshAllCollections({ recheckFiles: fileRecheckMode(mode) });
+    }
+    catch (err) {
+        const msg = describe(err);
+        console.info(`[SourceMonkey] refresh all failed: ${msg}`);
+        // Reached only when the PASS itself broke — a per-collection failure
+        // is recorded and skipped inside `refreshAllCollections`, and handled
+        // below. Nothing was summarized here, so every script hears the same
+        // reason. Same fan-out as runCollectionCheck so the two paths can't
+        // drift.
+        for (const snapshot of priorByCollectionId.values()) {
+            logCollectionEventToScripts([...snapshot.scripts.values()], mode, `Could not refresh this collection: ${msg}`);
+        }
+        throw err;
+    }
+    // Collections that were refreshed but couldn't be saved are absent
+    // from `result` without the pass having failed. They still owe their
+    // scripts a Log entry — a Refresh All that silently skipped this would
+    // say less than refreshing the same collection on its own, which does
+    // log (see runCollectionCheck).
+    //
+    // Keyed off the recorded map so each collection gets ITS reason, and so
+    // a collection absent for the other reason — removed mid-refresh, which
+    // clears its entry — stays quiet.
+    timer.mark('refresh');
+    const refreshErrors = await readRefreshErrors();
+    for (const [id, snapshot] of priorByCollectionId) {
+        if (result.has(id))
+            continue;
+        const reason = refreshErrors[id];
+        if (!reason)
+            continue;
+        logCollectionEventToScripts([...snapshot.scripts.values()], mode, describeRefreshError(reason));
+    }
+    for (const [, refreshed] of result) {
+        summarizeCollectionOutcome(refreshed.collection.path, priorByCollectionId.get(refreshed.collection.id), refreshed, mode);
+    }
+    const allScripts = [...result.values()].flatMap((r) => r.scripts);
+    timer.mark('summarize');
+    await runVersionProbes(allScripts, probe);
+    timer.mark('probes');
+    // Counted, not just timed: each probe result is its own storage write,
+    // and a write is what schedules a registration re-sync. The number of
+    // probed scripts is therefore the number of re-syncs this pass can
+    // provoke, which is not something the elapsed time shows.
+    timer.note(() => `${probedCount(allScripts)} of ${allScripts.length} scripts have a probe target`);
+    // Refresh All is the other "try again" button, so it retries every
+    // refused registration it just re-read. See
+    // `retryRejectedRegistrations`.
+    await retryRejectedRegistrations(allScripts.map((s) => s.id), { userInitiated: probe === 'force' });
+    timer.mark('retry-rejected');
+    timer.done();
+    reportPhaseTotals('all-collections check');
+    return result;
+}
+// ---------- Update probes ----------
+//
+// Runs after the refresh, against the rows it produced. Deliberately
+// downstream of everything above: a probe can't change a status, can't
+// set a refreshError, and a probe host that's down or slow must leave
+// the refresh's own outcome exactly as it was. See src/version-probe.ts
+// for what "probe" means here and [docs/updates.md] for why we don't
+// simply update from the probed URL.
+//
+// Awaited by the collection-level entry points (a Refresh button click,
+// where the user is watching a spinner and expects the row to be
+// current when it stops) but not by the per-script one, which sits on
+// the navigation hot path — see runScriptCheck.
+async function runVersionProbes(scripts, probe) {
+    // Bounded for the same reason the refresh fan-out is (see
+    // src/extension/concurrency.ts): "Refresh All" hands this every script in every
+    // collection, and each one expands into its own pool of probe fetches.
+    // Unbounded here would put the product in flight at once.
+    await mapWithConcurrency(scripts, PROBE_SCRIPTS_CONCURRENCY, (s) => probeOneScript(s, probe).catch(() => {
+        // A probe is an annotation. Nothing downstream depends on it, so a
+        // failure that escaped runProbe's own handling dies here rather
+        // than propagating into the refresh the user actually asked for.
+    }));
+}
+// After a single-script install: check for a newer version at once, so
+// an install of an already-outdated copy says so without waiting for a
+// Refresh. Not awaited by the install, like the per-script refresh's:
+// the result lands on the row, and the pages repaint from it. A whole
+// collection added at once isn't probed here; its first Refresh does.
+export function probeInstalledScript(result) {
+    const id = result?.kind === 'existingContainer' ? result.scriptId
+        : result && isContainerCollection(result.collection.path) ? result.collection.scriptIds[0]
+            : undefined;
+    if (!id)
+        return;
+    void (async () => {
+        const script = await getScriptMeta(id);
+        if (script)
+            await runVersionProbes([script], 'force');
+    })().catch(() => {
+        // An annotation, as in `runVersionProbes`: the install stands.
+    });
+}
+async function probeOneScript(script, policy) {
+    // Only rows that are actually running get probed. An `invalid` row's
+    // header may not have parsed at all. Its stored probes are left alone
+    // rather than cleared: INVALID outranks OUTDATED so nothing stale is
+    // on screen, and a row that recovers gets its annotation back without
+    // a refetch.
+    if (script.status !== 'ok')
+        return;
+    const loadedVersion = script.header ? getValue(script.header, 'version') : undefined;
+    const targets = probeTargets(script.header, script.fileUrl);
+    if (targets.length === 0) {
+        // The script no longer names an upstream we don't already fetch
+        // from (or never did). Clear any annotation left from when it did,
+        // so a removed `@updateURL` doesn't strand an OUTDATED badge.
+        if (script.versionProbes) {
+            const wasOutdated = outdatedProbe(loadedVersion, script.versionProbes);
+            await setVersionProbes(script.id, []);
+            if (wasOutdated)
+                logUpToDateAgain(script.id, loadedVersion);
+        }
+        return;
+    }
+    const now = nowMsImpl();
+    // Everything but an explicit Refresh click respects the interval —
+    // including the reload fast-path, which runs in `manual` mode on
+    // every tab reload.
+    if (policy === 'if-stale' && probesAreFresh(script.versionProbes, targets, now))
+        return;
+    const before = outdatedProbe(loadedVersion, script.versionProbes);
+    const probes = await probeVersions(targets, now, script.versionProbes);
+    await setVersionProbes(script.id, probes);
+    // Report the transition, not the state: an upstream that has been
+    // ahead of us for a month shouldn't add a Log entry every interval.
+    // Both directions carry the `state` they leave the badge in, so the
+    // Log's status column reads OUTDATED / OK exactly where the badge
+    // changed.
+    //
+    // `before` is computed against the row this probe was handed, which
+    // is the freshly refreshed one — so "our copy caught up" is already
+    // not outdated here. That transition is reported by
+    // `emitScriptOutcomeLog`, which has the prior row; this one only sees
+    // the upstream side moving (a version rolled back).
+    const after = outdatedProbe(loadedVersion, probes);
+    if (!after) {
+        if (before)
+            logUpToDateAgain(script.id, loadedVersion);
+        return;
+    }
+    if (after.version === before?.version)
+        return;
+    const entry = outdatedLogEntry(after, loadedVersion);
+    console.info(`[SourceMonkey] ${getScriptLogLabel(script.id)}: ${entry.message}`);
+    // Not split by trigger mode like the refresh labels: this entry
+    // reports a transition ("an upstream copy just moved ahead of us"),
+    // and whether a click or a navigation noticed it tells the user
+    // nothing they'd act on.
+    logScriptEvent(script.id, { ...entry, source: 'version-probe' });
+}
+// The OUTDATED row, minus its source: written by the probe when the
+// upstream moves ahead, and restated at boot for a probe that persisted
+// across a restart. One formatter so both read alike.
+function outdatedLogEntry(probe, loadedVersion) {
+    return {
+        level: 'warning',
+        state: 'outdated',
+        message: `Newer version ${probe.version} at ${probeLabel(probe.kinds)} ` +
+            `(running ${loadedVersion}): ${probe.url}`,
+    };
+}
+// The OUTDATED → OK row. One message for every way the badge can go:
+// our copy caught up (seen by the refresh outcome), the upstream rolled
+// back (seen by the probe), or the header stopped naming an upstream
+// (the probe's clear path).
+function logUpToDateAgain(scriptId, loadedVersion) {
+    logScriptEvent(scriptId, {
+        level: 'info', state: 'ok', source: 'version-probe',
+        message: `Up to date again (running ${loadedVersion ?? '<none>'})`,
+    });
+}
+// Pre-refresh state per collection: the collection row (for its
+// `scanError`, so a still-down collection doesn't re-log) plus its
+// scripts by ID.
+async function snapshotAllCollectionScripts() {
+    const collections = await getCollections();
+    const entries = await Promise.all(collections.map(async (s) => {
+        const data = await getCollectionWithScriptMeta(s.id);
+        const scripts = new Map((data?.scripts ?? []).map((sc) => [sc.id, sc]));
+        return [s.id, { collection: s, scripts }];
+    }));
+    return new Map(entries);
+}
+// ---------- Logging helpers ----------
+function logScriptOutcome(label, prior, next, mode) {
+    if (!next) {
+        console.info(`[SourceMonkey] update check: ${label}: row vanished`);
+        return;
+    }
+    if (next.status === 'invalid') {
+        console.info(`[SourceMonkey] update check: ${label}: invalid: ` +
+            `${describeDiagnostic(next.errorMessage ?? 'unknown', next.errorLocation)}`);
+        return;
+    }
+    // Refresh failed but the cached good copy keeps running. Log once on
+    // the transition (or when the reason changes) so a collection that
+    // stays down doesn't spam the console on every opportunistic check.
+    if (next.refreshError && prior?.refreshError !== next.refreshError) {
+        console.info(`[SourceMonkey] refresh failed: ${label}: ${next.refreshError}`);
+        return;
+    }
+    if (!prior || prior.loadedAt !== next.loadedAt) {
+        // loadedAt bumps iff the load pipeline actually built from fresh
+        // content. Same loadedAt means the size+mtime skip caught it.
+        if (dependenciesOnlyChange(prior, next)) {
+            console.log(`[SourceMonkey] loaded new content for its @require or @resource files: ${label}`);
+            return;
+        }
+        const size = next.size != null ? ` (${formatBytes(next.size)})` : '';
+        console.log(`[SourceMonkey] loaded new content: ${label}${size}`);
+    }
+    else {
+        // "no change" pairs with the entry log: visible on manual, gated
+        // on opportunistic. Otherwise a Refresh click could log "update
+        // check" with nothing following.
+        const outcomeLog = mode === 'manual' ? console.log : dlog;
+        outcomeLog(`[SourceMonkey] no change: ${label}`);
+    }
+}
+// A new `loadedAt` that came from a `@require` / `@resource` alone: the
+// script's own content hash is the same (see `dependenciesChanged` in
+// src/script-build.ts).
+function dependenciesOnlyChange(prior, next) {
+    return prior?.contentHash !== undefined && prior.contentHash === next.contentHash;
+}
+// Write a check's whole story into the per-script Log, mirroring the
+// SW-console outcome line. The uneventful outcome is manual-only, so
+// background polling doesn't fill the log with rows saying a healthy
+// script is still healthy — those still get debug-gated console output
+// via dlog.
+//
+// Every failure the UI surfaces on a script row also lands here, so
+// clicking a red/amber badge always leads to an explanation: the entry
+// carries the `state` the badge shows (INVALID / REFRESH FAILED, and
+// OK for the recovery) — see `loadStateLogEntry` for the
+// phrasing.
+//
+// **One row per uneventful check, two when there's news.** A check
+// that finds nothing writes a single `Checked for updates and found no change`
+// line. A check with something to report writes `Checking for updates`
+// and then the outcome, which carries its own severity and is what the
+// status badge links to.
+//
+// "Still broken" is a freshly computed verdict, not an echo: an
+// `invalid` row can't take the size+mtime skip (`canSkip` requires
+// `status === 'ok'`), so every check refetches and re-runs split +
+// parse + validate.
+//
+// **Opportunistic checks log too.** They report the same facts a manual
+// check would, and the whole point of a background check is to notice a
+// failure the user hasn't gone looking for yet — a badge that turns
+// amber on its own should have a matching Log line. (Trigger mode still
+// gates the *non*-events: the uneventful row is manual-only.)
+//
+// Exported for unit tests — the public entry points would need the
+// whole chrome.storage pipeline stubbed to reach it.
+export function emitScriptOutcomeLog(scriptId, prior, next, mode) {
+    const source = refreshLogSource(mode);
+    // A check that found nothing to say is ONE line naming both the
+    // check and its result — see `NO_CHANGE_MESSAGE`. Only a check with
+    // something to report gets a preamble, because there the result is
+    // its own line (and its own severity) and needs the check named
+    // separately.
+    //
+    // Written after the work, so both halves land together. The SW
+    // console is where a check is bracketed live; the Log tab is a
+    // record of what happened.
+    // A row that went away during the check — deleted by the user, or
+    // dropped by this very check because its file was no longer listed
+    // — has no Log any more: `removeScript` cleared it. Writing here
+    // would leave an orphan `log:` row for a script nothing displays.
+    // The SW console line in `logScriptOutcome` is the record.
+    if (!next)
+        return;
+    if (hasReportableOutcome(prior, next)) {
+        logScriptEvent(scriptId, { level: 'info', source, message: 'Checking for updates' });
+    }
+    // Before the state verdict, and not gated by it: a script can be
+    // `invalid` for an unrelated reason and still have picked up a local
+    // stand-in this pass, and that substitution is exactly what the user
+    // needs to know about while debugging the failure.
+    for (const entry of localFileLogMessages(prior, next)) {
+        logScriptEvent(scriptId, { ...entry, source });
+    }
+    const nextState = loadStateLogEntry(next);
+    const priorState = prior ? loadStateLogEntry(prior) : null;
+    if (nextState) {
+        // Written even when the failure is byte-identical to the one
+        // already in the log: every check re-runs the full fetch + parse +
+        // validate — an `invalid` row can't take the size+mtime skip, which
+        // requires `status === 'ok'` — so this is a fresh verdict on a
+        // fresh read, and the check that produced it has to end somewhere.
+        logScriptEvent(scriptId, { ...nextState, source });
+        return;
+    }
+    if (prior && priorState) {
+        // The row is healthy again. Log the recovery so the Log explains
+        // why the badge went back to OK — without this the last word on the
+        // script would be a failure that is no longer true.
+        logScriptEvent(scriptId, { level: 'info', state: 'ok', source, message: recoveryMessage(prior) });
+        // Recovering IS the outcome of this check. Falling through to the
+        // uneventful line below would read as a contradiction when the
+        // recovery didn't come with new bytes (a dependency host that
+        // starts answering again clears the failure without touching the
+        // script's own content, so `loadedAt` is preserved unless the
+        // dependency's bytes changed meanwhile).
+        if (prior.loadedAt === next.loadedAt)
+            return;
+    }
+    if (!prior || prior.loadedAt !== next.loadedAt) {
+        // The script's own file is the same, so its size is too. The changed
+        // files have their own lines when they are local copies
+        // (`localFileLogMessages`).
+        const dependenciesOnly = dependenciesOnlyChange(prior, next);
+        const size = next.size != null && !dependenciesOnly ? ` (${formatBytes(next.size)})` : '';
+        // A new version is a clean slate for the WARNING / ERROR badge: the
+        // old version's runtime errors say nothing about this one, and a
+        // developer who just fixed one needs the badge to reflect only what
+        // happens next. Shown as OK in the Log's status column for the same
+        // reason. See `LogEntry.resetsLogLevel`.
+        logScriptEvent(scriptId, {
+            level: 'info',
+            state: 'ok',
+            resetsLogLevel: true,
+            source,
+            message: dependenciesOnly ? 'Loaded new content for its @require or @resource files' : `Loaded new content${size}`,
+        });
+        // The new content's `@version` caught up with a probe that had been
+        // ahead of us. The probes ride along unchanged on the refreshed row
+        // (see `preserveConcurrentEdits` in script-store.ts), so the comparison is
+        // between the old and new header against the same stored answer.
+        if (prior && scriptOutdatedProbe(prior) && !scriptOutdatedProbe(next)) {
+            logUpToDateAgain(scriptId, next.header ? getValue(next.header, 'version') : undefined);
+        }
+        // Replay parse-time diagnostics whenever a new version lands. They
+        // appear AFTER the "Loaded new content" line so it's clear which
+        // version the warning belongs to. A dependency-only change too: the
+        // line above starts the badge over, and the header's warnings still
+        // hold (a row that was invalid on a failed `@require` didn't log
+        // them on any refresh while it stayed so).
+        for (const entry of next.startupLogs ?? []) {
+            logScriptEvent(scriptId, startupLogEntry(entry));
+        }
+        return;
+    }
+    if (mode === 'manual') {
+        logScriptEvent(scriptId, { level: 'info', source, message: NO_CHANGE_MESSAGE });
+        // A manual refresh is the user asking what state this script is in,
+        // so a parse-time problem that is STILL TRUE gets restated — the
+        // same reason `replayScriptLogsAtBoot` restates load state and
+        // OUTDATED rather than leaving a badge over a silent Log. Without
+        // it the only line a permanently misconfigured script ever gets is
+        // the one from the refresh that first loaded it: it scrolls away,
+        // Clear log wipes it, and nothing brings it back until the next
+        // Chrome restart. Manual only, like the line above — a background
+        // check nobody asked for stays silent.
+        for (const entry of next.startupLogs ?? []) {
+            logScriptEvent(scriptId, startupLogEntry(entry));
+        }
+    }
+}
+// Fan a COLLECTION-level fact out into the Log of every script under
+// that collection. Used for the failures that stop us from checking any
+// of them (an unreadable listing, a throw out of the refresh) and for
+// the matching recovery.
+//
+// **Always `info`, never warning/error.** These entries exist so a user
+// reading one script's Log can see why it wasn't checked — the badge
+// for a collection-level problem belongs on the collection row, which
+// already renders `scanError` (see `renderCollectionSection` in
+// collections.ts). Logging them higher would badge every script under
+// the collection WARNING via the `loglevel:` sentinel, which is for
+// things the script itself did.
+//
+// Plain append. A collection that stays unreadable re-logs on each pass,
+// which is honest — every one of those passes really did try to read
+// it. Only reachable from a Refresh / Refresh All click (see the
+// `updateCollection` / `updateAllCollections` callers in
+// collections.ts), so the user asked for each repeat.
+function logCollectionEventToScripts(scripts, mode, message) {
+    for (const s of scripts) {
+        logScriptEvent(s.id, { level: 'info', source: refreshLogSource(mode), message });
+    }
+}
+// The Log tab's Source label for a refresh pass. Spelled out per mode
+// rather than composed from the mode name: these strings are read by
+// users, and "opportunistic" describes our scheduling policy rather
+// than anything they did or would recognise.
+function refreshLogSource(mode) {
+    return mode === 'manual' ? 'manual-refresh' : 'background-refresh';
+}
+// The single line a check writes when it has nothing to report: names
+// the check AND its result, so a routine poll costs one row rather than
+// a start/outcome pair. Manual-only (see `emitScriptOutcomeLog`).
+const NO_CHANGE_MESSAGE = 'Checked for updates and found no change';
+// Whether this check has anything to say beyond that one line — i.e.
+// whether there was something to check for this script in the first
+// place.
+//
+// Mirrors the branches of `emitScriptOutcomeLog` below, in the same
+// order, and is only ever read by it. Kept as its own predicate so the
+// "should we announce the check?" decision and the "what do we report?"
+// decision are written once each rather than twice.
+//
+// True when: it's failing now, it was failing before (so this pass
+// genuinely re-fetched and re-validated — an `invalid` row can't take
+// the size+mtime skip), or the content changed. False only for the
+// healthy-and-unchanged case, whose whole outcome is the one
+// self-describing `NO_CHANGE_MESSAGE` row.
+function hasReportableOutcome(prior, next) {
+    if (loadStateLogEntry(next))
+        return true;
+    if (prior && loadStateLogEntry(prior))
+        return true;
+    // A local stand-in that appeared, vanished, or changed on disk is an
+    // outcome even when the script's own bytes didn't move — that's the
+    // common shape while editing a required library.
+    if (localFileLogMessages(prior, next).length > 0)
+        return true;
+    return !prior || prior.loadedAt !== next.loadedAt;
+}
+// How to phrase "the failure we last logged for this row is over".
+// Keyed off the prior row's state so the line names what recovered —
+// a bare "ok again" wouldn't tell the user whether the file came back,
+// the parse started succeeding, or the server did.
+function recoveryMessage(prior) {
+    if (prior.status === 'invalid')
+        return 'Loads cleanly again (was invalid)';
+    return 'Refresh succeeded again (collection is reachable)';
+}
+// Sentinel key in chrome.storage.session that records "we've already
+// replayed the persisted per-script state for THIS Chrome session."
+// session storage is cleared on Chrome shutdown, so a fresh Chrome
+// session always misses the sentinel; SW restarts within a session
+// always hit it.
+//
+// The key name predates the load-state leg and now under-describes what
+// it gates. Kept as-is deliberately: renaming it would make one Chrome
+// session miss its existing sentinel and replay a second time, which
+// buys nothing.
+const BOOT_REPLAY_SENTINEL_KEY = 'sm:startup-logs-replayed-at';
+// Refill the Log tab from persisted state, once per Chrome session, at
+// SW startup. Everything replayed here is so for the same reason: the
+// facts live in `chrome.storage.local` and outlive the Chrome shutdown
+// that wipes the session-scoped log, so without this a fresh session
+// shows a red or amber badge over an empty Log until the user manually
+// refreshes.
+//
+//   - **Load state** — a row that is currently `invalid` / `missing` /
+//     carrying a `refreshError`. Nothing re-checks a script until it is
+//     refreshed or its page is visited, so without this a script broken
+//     since before the restart shows a badge over an empty Log.
+//   - **Outdated** — a row whose persisted `versionProbes` put an
+//     upstream ahead of it. The probe only logs the *transition*, and a
+//     re-probe after the restart finds the same answer, so this is the
+//     only line the OUTDATED badge would ever get.
+//   - **Parse-time diagnostics** — `script.startupLogs`.
+//
+// The sentinel makes it idempotent: SW restarts within the same Chrome
+// session bail out immediately. Every leg reuses the exact message
+// text the refresh paths use, so the Log tab is visually uniform.
+//
+// The sentinel is written AFTER the walk, not before: MV3 can evict the
+// worker mid-loop, and claiming it up front would mark the session
+// replayed while most scripts still had empty logs — the exact state
+// this exists to prevent. A torn-down replay simply runs again on the
+// next SW wake-up, duplicating a row for the scripts the first pass
+// reached. Rare and bounded to one Chrome session.
+export async function replayScriptLogsAtBoot() {
+    const got = await chrome.storage.session.get(BOOT_REPLAY_SENTINEL_KEY);
+    if (got[BOOT_REPLAY_SENTINEL_KEY])
+        return;
+    // One read of the script rows (no bodies) via getAllScriptMetas —
+    // cheaper than per-collection reads when most scripts won't have
+    // anything to replay anyway. Per-script work runs concurrently;
+    // `appendScriptLog`'s own queue keeps each script's appends ordered.
+    const scripts = await getAllScriptMetas();
+    await Promise.all(scripts.map(async (script) => {
+        await ensureLoadStateInLogTab(script);
+        await ensureOutdatedInLogTab(script);
+        await ensureStartupLogsInLogTab(script);
+    }));
+    await chrome.storage.session.set({ [BOOT_REPLAY_SENTINEL_KEY]: Date.now() });
+}
+// Restate a script's current load failure, if it has one.
+//
+// `source: 'extension-startup'` rather than a `*-refresh` label so the
+// Log reads honestly: nothing was re-checked, we're just carrying the
+// last known verdict forward across a browser restart. Not plain
+// 'startup' either — that would read as the *script's* startup, which
+// is what the `parser` source already covers.
+//
+// Plain append. The session sentinel already makes this run once per
+// Chrome session, which is the only thing keeping the volume down that
+// needs to.
+async function ensureLoadStateInLogTab(script) {
+    const entry = loadStateLogEntry(script);
+    if (!entry)
+        return;
+    await appendScriptLog(script.id, { ...entry, source: 'extension-startup' });
+}
+// Restate OUTDATED for a row whose stored probe is still ahead of it.
+// Same source and reasoning as `ensureLoadStateInLogTab`; same wording
+// as the probe's own transition row.
+//
+// `ok` rows only, mirroring `probeOneScript`: an `invalid` / `missing`
+// row keeps its stale probes but isn't running, so "(running <v>)"
+// would be false and the line would land after — and appear to
+// override — the load-state line the row actually deserves.
+async function ensureOutdatedInLogTab(script) {
+    if (script.status !== 'ok')
+        return;
+    const probe = scriptOutdatedProbe(script);
+    if (!probe)
+        return;
+    const loadedVersion = script.header ? getValue(script.header, 'version') : undefined;
+    await appendScriptLog(script.id, { ...outdatedLogEntry(probe, loadedVersion), source: 'extension-startup' });
+}
+// Replay `script.startupLogs` into the Log tab as `parser`-source rows.
+//
+// Plain append, like everything else here. A refresh that races this
+// replay can leave a duplicate pair of rows — bounded to once per
+// script per Chrome session, and a visible duplicate is a cheaper
+// problem than a rule that has to explain when a line is dropped.
+async function ensureStartupLogsInLogTab(script) {
+    for (const sl of script.startupLogs ?? []) {
+        await appendScriptLog(script.id, startupLogEntry(sl));
+    }
+}
+// Roll a collection-level refresh up into one SW-console line, and fan
+// the per-script outcomes out into the Log tab.
+//
+// The scan-failure case is handled separately from the per-script loop.
+// `refreshCollection` deliberately leaves every script row untouched
+// when the listing can't be read (see [docs/storage.md]) — so the
+// per-script loop would report no change for every one of them, which
+// is a lie: nothing was checked. Instead the reason is fanned out to
+// each script (see `logCollectionEventToScripts` for why that's
+// `info`).
+//
+// Exported for unit tests.
+export function summarizeCollectionOutcome(label, prior, next, mode) {
+    const nextScripts = next.scripts;
+    const scanError = next.collection.scanError;
+    if (scanError) {
+        logCollectionEventToScripts(nextScripts, mode, 
+        // Same no-echo phrasing as the collections page's banner, since
+        // `scanError` usually starts with its own `Could not read …`.
+        // A message that already ends its sentence (a GitHub hint) gets no
+        // second period.
+        `This collection did not load: ${/[.!?]$/.test(scanError) ? scanError : `${scanError}.`} Still running the cached copy.`);
+        console.log(`[SourceMonkey] collection refresh: ${label}: scan failed: ${scanError}`);
+        return;
+    }
+    if (prior?.collection.scanError) {
+        logCollectionEventToScripts(nextScripts, mode, 'This collection is readable again');
+    }
+    const priorBy = prior?.scripts ?? new Map();
+    let changed = 0;
+    let added = 0;
+    let unchanged = 0;
+    let errored = 0;
+    let refreshFailed = 0;
+    for (const n of nextScripts) {
+        const prior = priorBy.get(n.id);
+        emitScriptOutcomeLog(n.id, prior, n, mode);
+        if (n.status === 'invalid') {
+            errored++;
+            continue;
+        }
+        // A still-running row whose latest refresh failed counts as its own
+        // bucket, not "unchanged" — the content is unchanged but the outcome
+        // wasn't a clean check.
+        if (n.refreshError) {
+            refreshFailed++;
+            continue;
+        }
+        if (!prior) {
+            added++;
+            continue;
+        }
+        if (prior.loadedAt !== n.loadedAt)
+            changed++;
+        else
+            unchanged++;
+    }
+    const parts = [`${nextScripts.length} script(s)`];
+    if (added)
+        parts.push(`${added} new`);
+    if (changed)
+        parts.push(`${changed} updated`);
+    if (unchanged)
+        parts.push(`${unchanged} unchanged`);
+    if (refreshFailed)
+        parts.push(`${refreshFailed} refresh-failed`);
+    if (errored)
+        parts.push(`${errored} error`);
+    console.log(`[SourceMonkey] collection refresh: ${label}: ${parts.join(', ')}`);
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// Convenience: kick off opportunistic checks for a batch of script IDs
+// without awaiting. Each id gates independently; ids whose check is
+// rate-limited or already in flight are dropped silently. Used by the
+// background SW when a navigation matches one or more scripts.
+//
+// **This is a fan-out over one page's script set, so it always gets a
+// batch** — the caller's when they have one (the same navigation's
+// reload fast path, so the two halves of one commit share a single
+// collection read and their file reads rather than one each), otherwise
+// its own. The rule is uniform on purpose: making it depend on which
+// call reached `gate()` first is exactly the ordering-sensitive shape
+// `parseCheck` had to be fixed out of. See `updateScript`.
+export function requestOpportunisticScriptChecks(scriptIds, batch = createRefreshBatch()) {
+    for (const id of scriptIds) {
+        // Swallow rejections — opportunistic work shouldn't ever surface a
+        // user-visible error; the failure was already logged by the fetch.
+        //
+        // `'defer'`: navigation-triggered, so it doesn't wait for the parse
+        // verdict — and this call and the reload fast path's coalesce onto
+        // whichever of them reaches the gate first. See `updateScript`.
+        updateScript(id, 'opportunistic', 'if-stale', 'defer', batch).catch(() => { });
+    }
+}
+// Test/debug hook so tests can reset the rate-limiter without
+// timing-mock gymnastics.
+export function _resetUpdaterStateForTests() {
+    scriptState.clear();
+    collectionState.clear();
+    allCollectionsState.clear();
+}