sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/wait.js

@@ -0,0 +1,458 @@
+// Waiting: the `wait` command, and the settling that it and the waits
+// after `start`, loads and actions share.
+//
+// A tab has settled when nothing sm-dev can see is still
+// happening in it. A browser has no signal for "the scripts are done":
+// JavaScript runs on events, and a page can keep timers, intervals and
+// sockets going for good. So settled is a set of signals all quiet
+// together for a short window, counted from when the wait began:
+//   - the document has loaded;
+//   - each script the document runs whose rules cover the page has
+//     reported (started, skipped or thrown);
+//   - no `GM_xmlhttpRequest` of its scripts is in flight;
+//   - no request of the page's is in flight;
+//   - its DOM hasn't changed;
+//   - and then its main thread has a moment with nothing to do.
+// Requests open over a few seconds are taken for long-lived ones (a
+// socket, a stream, a long poll), which would keep a page from ever
+// settling. Timers are not waited for: they are set up to run later. A
+// short one that matters changes the DOM when it fires, which the
+// window catches, since it starts no earlier than the wait.
+import { MAX_TIMER_SECONDS, TIMEOUT_NEEDS_SECONDS, timeoutSecondsMs } from './command-list.js';
+import { MISTAKE_PREFIX, quoted, WAIT_FAILED } from './output-style.js';
+import { countOf, pickFrame, refFrameProblem } from './page-commands.js';
+import { explainMatch, preparedScriptName } from './prepare.js';
+import { ALL_LOG_SOURCES, foundAt, inSources, linesLost, parseLogSources, parsePosition, searchedUpTo, streamText, textMatcher } from './run-logs.js';
+import { refProblem } from './snapshot.js';
+import { currentTab, dialogWaitingMessage, NO_TABS, pickTab, TAB_ARG, tabName } from './tab-refs.js';
+/** How long every signal must stay quiet. */
+const QUIET_MS = 200;
+/** How long a wait lasts before it says what is still busy. */
+export const SETTLE_TIMEOUT_MS = 5000;
+// A request open this long counts as long-lived.
+const LONG_REQUEST_MS = 3000;
+// The longest one look into the page may take: a page busy in a long
+// script doesn't answer, which counts as busy.
+const LOOK_MS = 1000;
+const POLL_MS = 50;
+// How often `wait selector` looks again, and the longest one look may
+// take: a page busy in a long script, or stopped on a dialog, doesn't
+// answer.
+const SELECTOR_POLL_MS = 100;
+const SELECTOR_LOOK_MS = 1000;
+// How the replies of the waits with something to match start, so each
+// says plainly whether it got it.
+const WAIT_DONE = '[sm-dev] Wait done: ';
+const LOG_MATCHED = '[sm-dev] Wait matched log line: ';
+/** Waits for `tab` to settle, up to `timeoutMs`. */
+export async function settleTab(tab, host, timeoutMs = SETTLE_TIMEOUT_MS) {
+    const started = Date.now();
+    const deadline = started + timeoutMs;
+    // Each look bounded by the time left too, so a short timeout holds.
+    const look = () => Math.max(POLL_MS, Math.min(LOOK_MS, deadline - Date.now()));
+    for (;;) {
+        if (tab.page.isClosed())
+            return { settled: false, closed: true };
+        if (tab.dialogs?.current)
+            return { settled: false, dialog: true };
+        let busy = await busyWith(tab, host, look(), started);
+        if (busy.length === 0) {
+            // Last, once the rest is quiet: the main thread free, and nothing
+            // changed while it got there. A document that went away meanwhile
+            // just makes the next look busy.
+            await within(tab.link.idle(look()).catch(() => undefined), look());
+            busy = await busyWith(tab, host, look(), started);
+            if (busy.length === 0)
+                return { settled: true };
+        }
+        if (Date.now() >= deadline) {
+            return tab.page.isClosed() ? { settled: false, closed: true } : { settled: false, busy };
+        }
+        await sleep(Math.min(POLL_MS, Math.max(0, deadline - Date.now())));
+    }
+}
+/**
+ * What still keeps `tab` from counting as settled, each starting with
+ * words of ours, lowercase, as the message lists them; empty when
+ * nothing does. `started`: when the wait began, which the quiet window
+ * can't start before, so what an action sets off a moment later is
+ * waited for even on a page that was quiet.
+ */
+async function busyWith(tab, host, lookMs, started) {
+    const busy = [];
+    const { link } = tab;
+    const activity = await within(link.activity().catch(() => null), lookMs);
+    if (activity === 'timeout')
+        return ['the page\'s JavaScript is busy'];
+    if (activity === null)
+        return tab.page.isClosed() ? [] : ['the page has no document yet'];
+    if (activity.readyState !== 'complete')
+        busy.push('the page is still loading');
+    // The scripts the document runs report once there; one whose rules
+    // don't cover the page may say nothing (as on about:blank), and has
+    // nothing to wait for anyway. Reports from the document's first
+    // span count, so one the back/forward cache restored, where the
+    // scripts don't run again, isn't waited on.
+    const url = tab.page.url();
+    const scripts = link.scriptsInDocument().filter((s) => s.id && explainMatch(s.matching, url).matches);
+    const waiting = host.unreported(link, scripts.map((s) => s.id), link.documentFirstStart());
+    if (waiting.length > 0) {
+        busy.push(`scripts not started yet: ${scripts.filter((s) => waiting.includes(s.id)).map(preparedScriptName).join(', ')}`);
+    }
+    const now = Date.now();
+    const xhrs = host.reports.requests.filter((r) => !r.outcome && host.pageOf(r) === link
+        && r.at >= link.documentFirstStart() && now - r.at < LONG_REQUEST_MS);
+    if (xhrs.length > 0)
+        busy.push(`${count(xhrs.length, 'GM_xmlhttpRequest')} pending (${urls(xhrs.map((r) => r.url))})`);
+    const network = link.network();
+    const pending = network.pending.filter((r) => r.ms < LONG_REQUEST_MS);
+    if (pending.length > 0)
+        busy.push(`${count(pending.length, 'request')} pending (${urls(pending.map((r) => r.url))})`);
+    else if (network.sinceLast < QUIET_MS)
+        busy.push('a request just finished');
+    if (activity.sinceDom < QUIET_MS)
+        busy.push(`the DOM is still changing${activity.lastChanged ? ` (${activity.lastChanged})` : ''}`);
+    // Nothing else to say, but the window hasn't passed since the wait
+    // began (only a timeout shorter than the window shows it).
+    if (busy.length === 0 && now - started < QUIET_MS)
+        busy.push('the quiet moment it waits for hasn\'t passed yet');
+    return busy;
+}
+/**
+ * After a load, an action or `start`: each tab settling, all at once.
+ * One that doesn't in time is said, without failing anything, since
+ * what came before worked. A dialog or a closed tab says so elsewhere,
+ * and a tab whose load already gave up (`stalled`) isn't waited on
+ * again.
+ */
+export async function settleTabs(host, tabs, out, timeoutMs = SETTLE_TIMEOUT_MS) {
+    // Only real tabs: a caller's `newTab` (a test's) may return none.
+    await Promise.all(tabs.filter((t) => t?.page && !t.stalled).map(async (t) => {
+        const outcome = await settleTab(t, host, timeoutMs);
+        if (!outcome.settled && 'busy' in outcome)
+            out(`[sm-dev] ${notSettledMessage(t, timeoutMs, outcome.busy)}`);
+    }));
+}
+/** How long a load (`open`, `reload`, the tabs `start` opens) may take. */
+export const LOAD_TIMEOUT_MS = 30_000;
+/**
+ * A command's `--timeout-seconds` in ms, for each wait it does in place
+ * of that wait's default: undefined when not given, null (said why)
+ * when not a number of seconds.
+ */
+export function timeoutFlagMs(flags, out) {
+    const timeout = flags['--timeout-seconds'];
+    if (timeout === undefined)
+        return undefined;
+    const ms = timeoutSecondsMs(timeout);
+    if (ms === null)
+        out(`${MISTAKE_PREFIX}${TIMEOUT_NEEDS_SECONDS}`);
+    return ms;
+}
+// How often a load looks for a page that stopped itself.
+const STOPPED_POLL_MS = 100;
+/** A navigation whose page didn't finish loading in time. */
+export class PageNotLoaded extends Error {
+}
+/**
+ * Runs a navigation (`page.goto`, `page.reload`) until the new page
+ * has loaded. A page that stops its own load with `window.stop()`
+ * counts as loaded: its readyState goes to complete, but it never
+ * fires `load`, which a plain `goto` waits for until it times out.
+ * Rejects with the navigation's own error, or when the page doesn't
+ * load in time.
+ */
+export async function loadPage(page, navigate, timeoutMs = LOAD_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    await navigate({ waitUntil: 'commit', timeout: timeoutMs });
+    let ended = false;
+    const load = page.waitForLoadState('load', { timeout: Math.max(1, deadline - Date.now()) }).then(() => true, (err) => {
+        if (err.name === 'TimeoutError')
+            return false;
+        throw err;
+    }).finally(() => { ended = true; });
+    // Reads readyState in a later task than the one that set it, so a
+    // load that did fire has run its listeners by then too.
+    const stopped = (async () => {
+        while (!ended && Date.now() < deadline) {
+            if (await page.evaluate(() => document.readyState).catch(() => null) === 'complete')
+                return true;
+            await sleep(STOPPED_POLL_MS);
+        }
+        return false;
+    })();
+    try {
+        if (!await Promise.race([load, stopped]))
+            throw new PageNotLoaded(`The page did not finish loading within ${seconds(timeoutMs)}`);
+    }
+    finally {
+        ended = true;
+        load.catch(() => undefined);
+    }
+}
+/** The message when `tab` didn't settle in time, as every wait says it. */
+export function notSettledMessage(tab, timeoutMs, busy) {
+    const list = busy.join('; ');
+    return `T${tab.n} did not settle within ${seconds(timeoutMs)}: ${list.charAt(0).toUpperCase()}${list.slice(1)}`;
+}
+// ---------- The wait command ----------
+/**
+ * `wait`: until a tab settles, an element appears or goes, or an output
+ * line shows up; or a plain delay. `parsed`: its words, as its syntax
+ * reads them (command-args.ts). False when it gave up or was invalid,
+ * so a line of several commands stops there.
+ */
+export async function waitFor(ctx, parsed) {
+    const mistake = (text) => {
+        ctx.out(`${MISTAKE_PREFIX}${text}`);
+        return false;
+    };
+    const timeout = parsed.flags['--timeout-seconds'];
+    const given = timeoutFlagMs(parsed.flags, ctx.out);
+    if (given === null)
+        return false;
+    const timeoutMs = given ?? SETTLE_TIMEOUT_MS;
+    if (parsed.form === 'log') {
+        if (parsed.tab !== undefined)
+            return mistake('The `wait log` command takes no tab, since it watches all of the run\'s output');
+        return waitForLog(ctx, parsed, timeoutMs);
+    }
+    // A plain delay. A tab or `all` before it (`wait T2 3s`) is allowed
+    // and has no effect: a delay waits the same whichever tab is named.
+    // So is --timeout-seconds, which a long delay gets out of habit, as
+    // long as it doesn't cut the delay short.
+    // A named tab must still exist, so a mistyped one is said.
+    const delayWord = parsed.words.length === 2 && parsed.words[0] === 'all' && parsed.tab === undefined
+        ? parsed.words[1] : parsed.words.length === 1 ? parsed.words[0] : undefined;
+    const delay = delayWord !== undefined ? parseDelay(delayWord) : null;
+    if (delay !== null) {
+        if (delay > MAX_TIMER_SECONDS * 1000)
+            return mistake(`A delay can be at most ${MAX_TIMER_SECONDS}s`);
+        if (timeout !== undefined && delay > timeoutMs)
+            return mistake(`The delay ${delayWord} is longer than --timeout-seconds ${timeout}. Give a timeout at least as long, or none.`);
+        if (parsed.tab !== undefined && !pickTab(ctx, parsed.tab))
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return true;
+    }
+    const [word, ...more] = parsed.words;
+    if (more.length > 0) {
+        // `wait all selector .x`: `all` isn't a tab, so the form wasn't taken.
+        if (word === 'all' && (more[0] === 'selector' || more[0] === 'selector-gone')) {
+            return mistake(`The wait ${more[0]} command looks in one tab. Name it (T2), or leave it out for the current one.`);
+        }
+        const valid = word === 'all' || parseDelay(word) !== null;
+        return mistake(`The ${quoted('wait')} command takes a tab, ${quoted('all')}, ${quoted('selector')}, ${quoted('selector-gone')}, ${quoted('log')}, or a delay such as ${quoted('500ms')} or ${quoted('2s')}, not ${quoted(valid ? more.join(' ') : word)}`);
+    }
+    // The tab, or all of them.
+    let tabs;
+    if (parsed.tab !== undefined) {
+        const picked = pickTab(ctx, parsed.tab);
+        if (!picked)
+            return false;
+        tabs = [picked];
+    }
+    else if (word === 'all') {
+        tabs = ctx.tabs();
+    }
+    else {
+        const current = currentTab(ctx);
+        tabs = current ? [current] : [];
+    }
+    if (tabs.length === 0) {
+        ctx.out(NO_TABS);
+        return false;
+    }
+    const kind = parsed.form;
+    if (kind === 'selector' || kind === 'selector-gone') {
+        const selector = parsed.text ?? '';
+        if (!selector)
+            return mistake(`The ${quoted(`wait ${kind}`)} command needs a selector, e.g. ${quoted(`wait ${kind} '#results'`)}`);
+        const [first, ...more] = selector.split(/\s+/);
+        if (more.length > 0 && TAB_ARG.test(first))
+            return mistake(`The tab goes before the word ${kind}: ${quoted(`wait ${first} ${kind} <css>`)}`);
+        const frame = await pickFrame(parsed.flags['--frame'], tabs[0], (line) => ctx.out(`[sm-dev] ${line}`));
+        if (frame === null)
+            return false;
+        return waitForSelector(ctx, tabs[0], selector, kind === 'selector', timeoutMs, frame);
+    }
+    if (word === undefined || word === 'all')
+        return waitToSettle(ctx, tabs, timeoutMs);
+    return mistake(`The ${quoted('wait')} command takes a tab, ${quoted('all')}, ${quoted('selector')}, ${quoted('selector-gone')}, ${quoted('log')}, or a delay such as ${quoted('500ms')} or ${quoted('2s')}, not ${quoted(word)}`);
+}
+// `wait [T<n>|all]`: each tab settling, all at once.
+async function waitToSettle(ctx, tabs, timeoutMs) {
+    const started = Date.now();
+    const outcomes = await Promise.all(tabs.map((t) => settleTab(t, ctx.host, timeoutMs)));
+    let ok = true;
+    outcomes.forEach((outcome, i) => {
+        if (outcome.settled)
+            return;
+        ok = false;
+        const t = tabs[i];
+        ctx.out('dialog' in outcome ? `${WAIT_FAILED}${dialogWaitingMessage(t, currentTab(ctx))}`
+            : 'closed' in outcome ? `${WAIT_FAILED}${tabName(t)} closed`
+                : `[sm-dev] ${notSettledMessage(t, timeoutMs, outcome.busy)}`);
+    });
+    if (ok) {
+        const took = seconds(Date.now() - started);
+        ctx.out(`[sm-dev] ${tabs.length === 1 ? `${tabName(tabs[0])} settled` : 'All tabs settled'} in ${took}`);
+    }
+    return ok;
+}
+// `wait selector` / `wait selector-gone`: looks again until it holds.
+// Each look is bounded, so the timeout holds, and a dialog that opens
+// meanwhile ends the wait rather than stopping it for good.
+async function waitForSelector(ctx, tab, selector, present, timeoutMs, frame) {
+    // In an iframe, the frame on its tab: `T1.F3`.
+    const name = `${tabName(tab)}${frame ? `.F${tab.link.host.frameIds.number(frame)}` : ''}`;
+    // A ref from a snapshot of another page matches nothing, which would
+    // pass for gone.
+    const problem = await within((async () => await refProblem(tab.page, selector)
+        ?? await refFrameProblem(tab.page, selector, frame, tab.link.host.frameIds))().catch(() => null), SELECTOR_LOOK_MS);
+    if (typeof problem === 'string' && problem !== 'timeout') {
+        ctx.out(`${WAIT_FAILED}${problem}`);
+        return false;
+    }
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (tab.page.isClosed()) {
+            ctx.out(`${WAIT_FAILED}${tabName(tab)} closed`);
+            return false;
+        }
+        if (frame?.isDetached()) {
+            ctx.out(`${WAIT_FAILED}${name} has gone from the page`);
+            return false;
+        }
+        if (tab.dialogs?.current) {
+            ctx.out(`${WAIT_FAILED}${dialogWaitingMessage(tab, currentTab(ctx))}`);
+            return false;
+        }
+        const count = await within(countOf(tab.page, selector, frame), Math.max(1, Math.min(SELECTOR_LOOK_MS, deadline - Date.now())));
+        if (typeof count === 'string' && count !== 'timeout') {
+            ctx.out(`${WAIT_FAILED}The selector ${selector} can't be used: ${count}`);
+            return false;
+        }
+        if (typeof count === 'number' && (present ? count > 0 : count === 0)) {
+            ctx.out(`${WAIT_DONE}The selector ${selector} ${present ? 'matches' : 'matches nothing'} on ${name}`);
+            return true;
+        }
+        if (Date.now() >= deadline) {
+            const limit = seconds(timeoutMs);
+            ctx.out(`${WAIT_FAILED}The selector ${selector} ${present ? `matched nothing on ${name} within` : `still matched on ${name} after`} ${limit}`);
+            return false;
+        }
+        await sleep(SELECTOR_POLL_MS);
+    }
+}
+// `wait log`: a log line (see run-logs.ts) of the sources asked for (by
+// default all of them), with the text or matching the /regex/, logged
+// since the previous command began (or since `--since`) or from now on.
+// Matched in the form the stream prints it, whole.
+async function waitForLog(ctx, parsed, timeoutMs) {
+    const mistake = (text) => {
+        ctx.out(`${MISTAKE_PREFIX}${text}`);
+        return false;
+    };
+    const { flags } = parsed;
+    const typed = parsed.text ?? '';
+    const flag = flags['--find'];
+    if (typed && typeof flag === 'string')
+        return mistake('The `wait log` command takes its text either after `log` or with `--find`, not both');
+    const text = typeof flag === 'string' ? flag : typed;
+    if (!text)
+        return mistake('The `wait log` command needs the text to look for, e.g. `wait log ready`');
+    const logs = ctx.logs;
+    if (!logs) {
+        ctx.out(`${WAIT_FAILED}This run cannot watch its log`);
+        return false;
+    }
+    const matcher = textMatcher(text, '');
+    if ('error' in matcher)
+        return mistake(matcher.error);
+    const sources = typeof flags['--log-source'] === 'string' ? parseLogSources(flags['--log-source']) : ALL_LOG_SOURCES;
+    if ('error' in sources)
+        return mistake(sources.error);
+    const given = typeof flags['--since'] === 'string' ? parsePosition(flags['--since']) : undefined;
+    if (typeof given === 'object')
+        return mistake(given.error);
+    const since = given ?? ctx.previousStart ?? 0;
+    const fits = (record) => inSources(record, sources) && matcher.matches(streamText(record, true));
+    const found = (record) => {
+        ctx.out(`${LOG_MATCHED}${streamText(record, true)}`);
+        ctx.out(foundAt(record.id));
+        return true;
+    };
+    if (given !== undefined) {
+        const lost = logs.lostAfter(given);
+        if (lost !== undefined)
+            ctx.out(linesLost(lost));
+    }
+    const earlier = logs.since(since).find(fits);
+    if (earlier)
+        return found(earlier);
+    const later = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            stop();
+            resolve(null);
+        }, timeoutMs);
+        const stop = logs.watch((record) => {
+            if (!fits(record))
+                return;
+            clearTimeout(timer);
+            stop();
+            resolve(record);
+        });
+    });
+    // Seen as it streamed, if its source streams; said again, so the
+    // reply says it was found.
+    if (later)
+        return found(later);
+    ctx.out(`${WAIT_FAILED}No log line matched ${matcher.shown} within ${seconds(timeoutMs)}`);
+    ctx.out(searchedUpTo(logs.position()));
+    return false;
+}
+// ---------- Helpers ----------
+/**
+ * A plain delay as typed, `100ms` or `5s` (`1.5s` too), in milliseconds;
+ * null for anything else.
+ */
+export function parseDelay(text) {
+    const m = /^(\d+(?:\.\d+)?)(ms|s)$/.exec(text);
+    if (!m)
+        return null;
+    return Math.round(Number(m[1]) * (m[2] === 's' ? 1000 : 1));
+}
+/** A duration as the messages say it: `5s`, `0.3s`. */
+export function seconds(ms) {
+    return `${Number((ms / 1000).toFixed(1))}s`;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+// A few URLs, each shortened to its path, and a count of the rest.
+function urls(list) {
+    const shown = list.slice(0, 3).map((url) => {
+        try {
+            const u = new URL(url);
+            return u.protocol.startsWith('http') ? `${u.pathname}${u.search}`.slice(0, 80) : url.slice(0, 80);
+        }
+        catch {
+            return url.slice(0, 80);
+        }
+    });
+    return list.length > 3 ? `${shown.join(', ')}, and ${list.length - 3} more` : shown.join(', ');
+}
+/** `work`'s result, or `timeout` once `ms` has passed. */
+export async function within(work, ms) {
+    let timer;
+    try {
+        return await Promise.race([work, new Promise((resolve) => { timer = setTimeout(() => resolve('timeout'), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/http-read.d.ts

@@ -0,0 +1,30 @@
+export declare const HTTP_READ_MESSAGE = "sm:http-read";
+export interface HttpReadRequest {
+    type: typeof HTTP_READ_MESSAGE;
+    url: string;
+    as: 'text' | 'bytes';
+    headers?: Record<string, string>;
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+export type HttpReadReply = {
+    kind: 'response';
+    status: number;
+    contentType: string;
+    etag: string | null;
+    lastModified: string | null;
+    finalUrl: string;
+    text?: string;
+    bodyBase64?: string;
+} | {
+    kind: 'error';
+    reason: 'timeout' | 'no-response' | 'oversize';
+    message?: string;
+};
+export declare function handleHttpReadRequest(req: HttpReadRequest): Promise<HttpReadReply>;
+export declare function mustHopToWorker(): boolean;
+export declare function readHttpViaWorker(req: Omit<HttpReadRequest, 'type'>): Promise<HttpReadReply | null>;
+export declare function replyBytes(reply: {
+    text?: string;
+    bodyBase64?: string;
+}): ArrayBuffer;

package/lib/http-read.js

@@ -0,0 +1,142 @@
+// One http(s) read, made where it is safe to make it.
+//
+// ---------- Why this module exists ----------
+//
+// A `fetch()` issued by a DOCUMENT hands that document the response's
+// `Link: <…>; rel=preload; as=script` headers, and Chrome acts on them
+// — it tries to preload the named script into the page that asked. Our
+// pages are extension pages, whose CSP is `script-src 'self'`, so the
+// preload is refused, and Chrome files the refusal under
+// `chrome://extensions/?errors`: an uncatchable error, about a script
+// the page never asked for, that reads as SourceMonkey being broken.
+//
+// Nothing exotic triggers it. Any site that preloads its own bundles
+// sends the header on every page, and we fetch site HTML (the site-icon
+// probe) and arbitrary script URLs (Add / Refresh / the install
+// preview) from pages all the time. A response that turns out to be a
+// login page — the case `fetchHttpText` already has a branch for — is
+// among the most likely of all to carry one.
+//
+// A service worker has no document for a hint to apply to, so the same
+// read there is inert. Hence this module: pages hand the read to the
+// worker and get the response back over `chrome.runtime`. Both
+// directions are pinned by `tests/e2e/preload-hints.spec.ts`.
+//
+// ---------- Shape ----------
+//
+// The worker performs the fetch and reports what came back; every
+// caller keeps its own rules about what the response MEANS (which
+// statuses are failures, which content types are acceptable, how a 304
+// is reported). That split is deliberate: the two callers
+// (`fetchResourceBytes` for bytes, `fetchHttpText` for script and
+// manifest text) disagree about all of it, and a handler that tried to
+// decide for both would have to grow their union.
+//
+// `as: 'text'` decodes in the worker via `Response.text()` rather than
+// shipping bytes for the page to decode, so a response's charset is
+// honoured exactly as it was before the hop existed.
+import { base64ToBytes, bytesToBase64 } from './bytes.js';
+import { isPageContext } from './run-context.js';
+import { ensureGithubAuthTokenLoaded, githubAuthHeaders } from './github-auth.js';
+export const HTTP_READ_MESSAGE = 'sm:http-read';
+// Service-worker side. `background.ts` owns the listener (and the
+// sender check that keeps this from being an open fetch proxy — the
+// extension holds `<all_urls>`).
+export async function handleHttpReadRequest(req) {
+    // The worker may have woken up to answer this, with its startup token
+    // read still in flight — a private GitHub raw URL would 404 on a race
+    // the page-side fetch never had.
+    await ensureGithubAuthTokenLoaded();
+    const headers = { ...(req.headers ?? {}), ...githubAuthHeaders(req.url) };
+    const controller = new AbortController();
+    const timer = req.timeoutMs != null
+        ? setTimeout(() => controller.abort(), req.timeoutMs)
+        : null;
+    let response;
+    try {
+        response = await fetch(req.url, {
+            cache: 'no-store',
+            redirect: 'follow',
+            referrerPolicy: 'no-referrer',
+            signal: controller.signal,
+            headers,
+        });
+    }
+    catch (err) {
+        // Our own timer is the only thing that aborts this request, so an
+        // aborted signal identifies the timeout exactly rather than leaving
+        // it merged with a network failure.
+        return controller.signal.aborted
+            ? { kind: 'error', reason: 'timeout' }
+            : { kind: 'error', reason: 'no-response', message: errorText(err) };
+    }
+    finally {
+        if (timer != null)
+            clearTimeout(timer);
+    }
+    // Size checks are for a body we are about to read. A 304 has none —
+    // its `Content-Length`, where a server sends one at all, describes the
+    // entity that WOULD have been sent. Rejecting on it would fail a
+    // conditional read as "too large" for a file that didn't change, and
+    // only on this leg: the local path tests 304 before any size check, so
+    // the two would disagree about the same response.
+    const contentLength = response.headers.get('content-length');
+    if (response.status !== 304 &&
+        req.maxBytes != null && contentLength && Number(contentLength) > req.maxBytes) {
+        return { kind: 'error', reason: 'oversize' };
+    }
+    const base = {
+        kind: 'response',
+        status: response.status,
+        // Verbatim, not lowercased: callers quote it back as evidence of
+        // what the server actually sent.
+        contentType: response.headers.get('content-type') ?? '',
+        etag: response.headers.get('ETag'),
+        lastModified: response.headers.get('Last-Modified'),
+        finalUrl: response.url || req.url,
+    };
+    try {
+        if (req.as === 'text')
+            return { ...base, text: await response.text() };
+        const body = await response.arrayBuffer();
+        if (req.maxBytes != null && body.byteLength > req.maxBytes) {
+            return { kind: 'error', reason: 'oversize' };
+        }
+        return { ...base, bodyBase64: bytesToBase64(new Uint8Array(body)) };
+    }
+    catch (err) {
+        // The body never finished arriving (connection dropped mid-read).
+        return { kind: 'error', reason: 'no-response', message: errorText(err) };
+    }
+}
+// True when this context must not fetch http(s) itself — i.e. it is a
+// page rather than the service worker.
+export function mustHopToWorker() {
+    return isPageContext();
+}
+// Page side. Returns null — not an error — when the request got no
+// answer at all, so the caller can fall back to fetching locally. That
+// reopens the preload leak for that one read, which beats failing a
+// read the user asked for.
+export async function readHttpViaWorker(req) {
+    let reply;
+    try {
+        reply = await chrome.runtime.sendMessage({
+            type: HTTP_READ_MESSAGE,
+            ...req,
+        });
+    }
+    catch {
+        return null; // no receiving end
+    }
+    return reply ?? null;
+}
+// The bytes of a `kind: 'response'` reply, whichever form it arrived in.
+export function replyBytes(reply) {
+    if (reply.bodyBase64 != null)
+        return base64ToBytes(reply.bodyBase64);
+    return new TextEncoder().encode(reply.text ?? '').buffer;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/lib/local-file-overrides.d.ts

@@ -0,0 +1,35 @@
+import { type DirectoryListingCache } from './file-locations.js';
+export declare const LOCAL_ROOTS_KEY = "smLocalFileRoots";
+export interface ParsedRoot {
+    lineNumber: number;
+    text: string;
+    url?: string;
+    error?: string;
+}
+export declare function parseLocalRootLines(text: string): ParsedRoot[];
+export declare function rootsFromText(text: string): string[] | null;
+export declare function textFromRoots(roots: readonly string[]): string;
+export declare function loadLocalRootsSetting(): Promise<void>;
+export declare function localRootsReady(): Promise<void>;
+export declare function installLocalRootsListener(): void;
+export declare function readRootsSetting(raw: unknown): string[];
+export declare function setConfiguredLocalRoots(roots: readonly string[]): void;
+export declare function _setLocalRootsForTests(roots: readonly string[]): void;
+export interface LocalFileScope {
+    enabled: boolean;
+    collectionPath?: string;
+    lookup?: LocalLookup;
+}
+export type LocalLookup = 'known' | 'search';
+export declare function localSearchRoots(scriptFileUrl: string, scope: LocalFileScope): string[];
+export declare function collectionSupportsLocalFiles(collectionPath: string): boolean;
+export declare function localFileCandidates(declaredUrl: string, roots: readonly string[]): string[];
+export interface LocalFileCandidate {
+    url: string;
+    root: string;
+    firstSegment: string;
+    isLeaf: boolean;
+}
+export declare function localFileCandidatesDetailed(declaredUrl: string, roots: readonly string[]): LocalFileCandidate[];
+export declare function presentLocalFileCandidates(declaredUrl: string, roots: readonly string[], listings: DirectoryListingCache): Promise<string[]>;
+export declare function localCandidateMayExist(c: LocalFileCandidate, listings: DirectoryListingCache): Promise<boolean>;