sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/site-icon.js

@@ -0,0 +1,1261 @@
+import { base64ToBytes, bytesToBase64 } from '../bytes.js';
+import { fetchResourceBytes, isNotModified, resolveScriptResource } from '../file-loader.js';
+import { presentLocalFileCandidates } from '../local-file-overrides.js';
+import { MAX_SITE_ICONS, representativeMatches } from '../match-targets.js';
+import { renderGlyph } from './glyph.js';
+import { getValue } from '../userscript-header.js';
+import { iconRefFromHeader, isIconContentType, MAX_ICON_BYTES } from '../script-icon.js';
+import { assertWorkerContext, isPageContext } from '../run-context.js';
+import { callWorker } from './worker-client.js';
+// Site-icon (favicon) extraction + cache. Used by the collections page
+// and userscript viewer to show a 16x16 icon per targeted site (up to
+// MAX_SITE_ICONS distinct sites) next to each script.
+//
+// Two-tier lookup, so deep-targeted scripts (e.g. one userscript per
+// section of a big site) each get their own icon instead of sharing
+// the first one discovered for the origin:
+//   1. page URL → Chrome `/_favicon/` DB → HTML discovery there
+//      (cached per page URL).
+//   2. origin fallback → Chrome `/_favicon/` DB → origin-root HTML
+//      → /favicon.ico → Google S2 (cached per origin, shared across
+//      every script on that host).
+// The page URL is each site's `linkUrl` from `representativeMatches` —
+// the same URL that site's favicon click-through navigates to.
+//
+// Caches in chrome.storage.local:
+//   `pathIcon:<pageUrl>`  — page-specific lookup result for that
+//      page. Null means "no icon on this page" — we fall back to
+//      the origin cache, not refetch the page.
+//   `siteIcon:<origin>`   — origin-level fallback result (Chrome DB
+//      + root HTML + /favicon.ico + Google S2). Shared across all
+//      scripts on the origin.
+// Success entries live 7d, null entries 24h so a transient outage
+// doesn't permanently blank the row. The page-URL cache layer is
+// skipped entirely when the page URL is just the origin root — the
+// two would otherwise duplicate the same lookup.
+//
+// Reads go through `usableCacheHit`, which counts a row we wouldn't
+// paint (or one written under an older discovery schema version) as a
+// miss — so a row written by an older, laxer build heals on the next
+// render instead of waiting out its TTL.
+// Schema version for discovered icons (`siteIcon:` / `pathIcon:`).
+// Bumped when a discovery bug (like accepting cross-host SSO — single
+// sign-on — redirects)
+// could have poisoned cached rows with another host's icon.
+const DISCOVERED_ICON_CACHE_VERSION = 2;
+const KEY_PREFIX = 'siteIcon:';
+const siteIconKey = (origin) => `${KEY_PREFIX}${origin}`;
+// Path-scoped cache for icons discovered by probing a non-root URL.
+// Key is the full page URL (origin + `linkUrl` path) — each deep
+// section gets its own entry so e.g. nytimes.com/puzzles/spelling-bee/
+// can have a different icon from nytimes.com/athletic/. Hits here are
+// strictly the HTML-discovery result; origin-level fallbacks live in
+// `siteIcon:` so the /favicon.ico + S2 fetches happen at most once
+// per host.
+const PATH_ICON_KEY_PREFIX = 'pathIcon:';
+const pathIconKey = (pageUrl) => `${PATH_ICON_KEY_PREFIX}${pageUrl}`;
+// Separate cache prefix for icons declared via `@icon`/`@iconURL`/etc.
+// Same `SiteIconEntry` shape and TTLs as the origin-discovered path; the
+// prefix split keeps URL strings (which can be long) from colliding
+// with origin strings and lets either path be invalidated independently.
+const URL_ICON_KEY_PREFIX = 'iconUrl:';
+const urlIconKey = (url) => `${URL_ICON_KEY_PREFIX}${url}`;
+const SUCCESS_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const NULL_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_HTML_BYTES = 1024 * 1024;
+// Cap on inline-`data:`-URL icons declared in `<link href="data:...">`.
+// Base64 inflates by ~4/3 and the `data:image/...;base64,` prefix adds
+// a few dozen chars; round up and add slack rather than guess.
+const MAX_INLINE_DATA_URL_LEN = Math.ceil((MAX_ICON_BYTES * 4) / 3) + 64;
+function isDataUrl(url) {
+    return /^data:/i.test(url);
+}
+// Does a `data:` URL actually carry bytes? `data:,` (empty) is the
+// standard "this site has no favicon, stop asking" marker —
+// example.com serves exactly that — and painting it yields a blank
+// broken `<img>` where the globe placeholder belongs. A missing comma
+// counts as empty too: that's not a well-formed `data:` URL at all.
+// The one rule; every place an icon can enter or leave applies it.
+function dataUrlHasPayload(url) {
+    const comma = url.indexOf(',');
+    return comma >= 0 && url.slice(comma + 1).trim() !== '';
+}
+// A `data:` URL is usable as an icon only when it's within the inline
+// cap AND carries a payload. Shared by both entry points for an inline
+// icon: the `<link href="data:...">` discovery path and a script's own
+// `@icon data:...`. Both check the scheme before calling.
+function usableDataUrl(url) {
+    if (url.length > MAX_INLINE_DATA_URL_LEN)
+        return null;
+    return dataUrlHasPayload(url) ? url : null;
+}
+// Would we put this stored string in an `<img src>`? Every icon we
+// store is a payload-bearing `data:` URL, so anything else is a row
+// this build didn't write — and the point of asking is to distrust
+// rows written by other builds. Defaulting closed keeps an unknown
+// shape (say a bare `https:` URL, which an extension page would fetch
+// remotely and most likely have blocked) out of the DOM.
+function paintableIcon(dataUrl) {
+    return isDataUrl(dataUrl) && dataUrlHasPayload(dataUrl);
+}
+// An `href="data:,"` is the page declaring it HAS no icon, not a
+// candidate. Drop it before scoring, so a page offering both that
+// marker and a real icon doesn't hand the win to the marker — `icon`
+// outscores `apple-touch-icon`, so the marker would take it. Unlike
+// `paintableIcon` this defaults open: most hrefs are ordinary paths,
+// and only the marker shape is disqualifying.
+function emptyDataHref(href) {
+    const h = href.trim();
+    return isDataUrl(h) && !dataUrlHasPayload(h);
+}
+// ---------- Storage I/O ----------
+export async function loadSiteIcons(origins) {
+    const unique = Array.from(new Set(origins));
+    if (unique.length === 0)
+        return new Map();
+    const keys = unique.map(siteIconKey);
+    const got = await chrome.storage.local.get(keys);
+    const out = new Map();
+    for (const o of unique) {
+        const entry = got[siteIconKey(o)];
+        if (entry)
+            out.set(o, entry);
+    }
+    return out;
+}
+async function storeSiteIcon(origin, entry) {
+    assertWorkerContext('write storage');
+    await chrome.storage.local.set({
+        [siteIconKey(origin)]: { ...entry, v: DISCOVERED_ICON_CACHE_VERSION },
+    });
+}
+async function loadPathIcon(pageUrl) {
+    const got = await chrome.storage.local.get(pathIconKey(pageUrl));
+    return got[pathIconKey(pageUrl)];
+}
+async function storePathIcon(pageUrl, entry) {
+    assertWorkerContext('write storage');
+    await chrome.storage.local.set({
+        [pathIconKey(pageUrl)]: { ...entry, v: DISCOVERED_ICON_CACHE_VERSION },
+    });
+}
+async function loadUrlIcon(url) {
+    const got = await chrome.storage.local.get(urlIconKey(url));
+    return got[urlIconKey(url)];
+}
+async function storeUrlIcon(url, entry) {
+    assertWorkerContext('write storage');
+    await chrome.storage.local.set({ [urlIconKey(url)]: entry });
+}
+export function isCacheFresh(entry, now = Date.now()) {
+    const ttl = entry.dataUrl !== null ? SUCCESS_TTL_MS : NULL_TTL_MS;
+    return now - entry.fetchedAt < ttl;
+}
+// Read a cache row as a settled answer, or null meaning "go fetch".
+// Stale is a miss, and so is a row holding a dataUrl we would refuse
+// to paint — a build predating the empty-`data:` check stored
+// example.com's `data:,` marker as though it were an icon, and nothing
+// but the 7-day success TTL would ever have cleared it. Treating it as
+// a miss both hides it now and overwrites the row with the correct
+// "no icon" on the refetch. `requireVersion` extends the same rule to
+// rows written before a discovery-logic fix (e.g. rejecting cross-host
+// SSO redirects).
+export function usableCacheHit(entry, requireVersion, now = Date.now()) {
+    if (!entry || !isCacheFresh(entry, now))
+        return null;
+    if (requireVersion !== undefined && entry.v !== requireVersion)
+        return null;
+    if (entry.dataUrl !== null && !paintableIcon(entry.dataUrl))
+        return null;
+    return entry;
+}
+// ---------- Favicon fetch ----------
+// Bumped by `resetIconFetchesForTests`. A fetch started before the bump
+// returns its icon but doesn't store it: a test's reset would otherwise
+// be followed by an icon an earlier test asked for, landing in storage
+// partway through the next test.
+let fetchEpoch = 0;
+// For the e2e reset (`resetAllState` in background.ts): fetches already
+// running won't store what they find, and later lookups start their own.
+export function resetIconFetchesForTests() {
+    fetchEpoch++;
+    inflight.clear();
+}
+// Discover an icon for `pageUrl` specifically (Chrome's `/_favicon/` DB
+// first, then HTML discovery at `pageUrl`). Cached under
+// `pathIcon:<pageUrl>` so each deep-targeted script gets its own entry.
+// A null result means "no usable icon on this page"; callers fall back
+// to the origin-level cache rather than retrying.
+async function fetchAndCachePathIcon(pageUrl) {
+    const epoch = fetchEpoch;
+    const found = from('favicon-store', await fetchChromeFavicon(pageUrl, { exactPage: true })) ??
+        from('page', await tryDiscoverIconViaHtml(pageUrl));
+    if (epoch === fetchEpoch)
+        await storePathIcon(pageUrl, foundEntry(found));
+    return found?.dataUrl ?? null;
+}
+function from(source, dataUrl) {
+    return dataUrl ? { dataUrl, source } : null;
+}
+function foundEntry(found) {
+    return found ? { dataUrl: found.dataUrl, fetchedAt: Date.now(), source: found.source } : { dataUrl: null, fetchedAt: Date.now() };
+}
+// Discover an icon for `origin` via the shared fallback chain
+// (Chrome's `/_favicon/` DB → origin-root HTML → /favicon.ico → Google S2).
+// Cached under `siteIcon:<origin>` and shared across every script on
+// the host — the path-scoped lookup hits this when its own probe came
+// up empty.
+async function fetchAndCacheOriginIcon(origin) {
+    const epoch = fetchEpoch;
+    const found = await fetchOriginFallback(origin);
+    if (epoch === fetchEpoch)
+        await storeSiteIcon(origin, foundEntry(found));
+    return found?.dataUrl ?? null;
+}
+// Fetch a script-declared (`@icon`) URL and cache it under
+// `iconUrl:<url>`. No discovery, no redirect policy: the script author
+// named this URL, so wherever it lands is what they asked for.
+async function fetchAndCacheUrlIcon(url) {
+    const epoch = fetchEpoch;
+    const dataUrl = await fetchIconAt(url);
+    if (epoch === fetchEpoch)
+        await storeUrlIcon(url, { dataUrl, fetchedAt: Date.now() });
+    return dataUrl;
+}
+async function fetchOriginFallback(origin) {
+    const fromChrome = await fetchChromeFavicon(origin + '/');
+    if (fromChrome)
+        return from('favicon-store', fromChrome);
+    const fromRoot = await tryDiscoverIconViaHtml(origin + '/');
+    if (fromRoot)
+        return from('page', fromRoot);
+    const fromIco = await fetchIconAt(`${origin}/favicon.ico`, { rejectCrossHostRedirect: true });
+    if (fromIco)
+        return from('favicon.ico', fromIco);
+    // Google S2 is the only leg that touches a third party. The host
+    // name is already public via the @match; the request still leaks
+    // "we couldn't find this site's icon ourselves" to Google. Reached
+    // only when every direct leg has failed.
+    return from('google', await fetchGoogleS2Icon(origin));
+}
+async function fetchGoogleS2Icon(origin) {
+    let host;
+    try {
+        host = new URL(origin).hostname;
+    }
+    catch {
+        return null;
+    }
+    if (!host)
+        return null;
+    // sz=64 is sharp at 16x16 even on 2x dpi displays.
+    const url = `https://www.google.com/s2/favicons?domain=${encodeURIComponent(host)}&sz=64`;
+    return await fetchIconAt(url);
+}
+async function tryDiscoverIconViaHtml(pageUrl) {
+    const got = await fetchHtml(pageUrl);
+    if (!got)
+        return null;
+    const best = pickBestIconCandidate(parseIconLinks(got.text));
+    if (!best)
+        return null;
+    let absUrl;
+    try {
+        // Resolve against the post-redirect URL so same-host path / scheme
+        // / `www.` redirects resolve relative hrefs against where the page
+        // actually lives (`fetchHtml` already rejected cross-host redirects).
+        absUrl = new URL(best.href, got.finalUrl).toString();
+    }
+    catch {
+        return null;
+    }
+    if (absUrl.startsWith('data:'))
+        return usableDataUrl(absUrl);
+    return await fetchIconAt(absUrl, { rejectCrossHostRedirect: true });
+}
+// Pull out every `<link rel="...icon...">` tag from an HTML string.
+// Scans only the `<head>` segment when one is delimited; otherwise the
+// whole document. Tolerant of attribute ordering, unquoted values,
+// and self-closing slashes.
+export function parseIconLinks(html) {
+    const headEnd = html.search(/<\/head\s*>/i);
+    const region = headEnd >= 0 ? html.slice(0, headEnd) : html;
+    const out = [];
+    const linkRe = /<link\b([^>]*)>/gi;
+    let m;
+    while ((m = linkRe.exec(region)) !== null) {
+        const attrs = parseAttrs(m[1]);
+        const rel = (attrs.rel ?? '').toLowerCase();
+        if (!rel.includes('icon'))
+            continue;
+        if (!attrs.href)
+            continue;
+        out.push({
+            href: attrs.href,
+            rel,
+            sizes: attrs.sizes ?? null,
+            type: attrs.type ?? null,
+        });
+    }
+    return out;
+}
+function parseAttrs(s) {
+    const out = {};
+    const re = /([a-zA-Z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+    let m;
+    while ((m = re.exec(s)) !== null) {
+        const value = m[2] ?? m[3] ?? m[4] ?? '';
+        out[m[1].toLowerCase()] = value;
+    }
+    return out;
+}
+// Pick the candidate most likely to look good at 16x16. Two kinds are
+// dropped before scoring rather than ranked low: mask-icon (a Safari
+// pinned-tab monochrome SVG mask, which renders as a black silhouette
+// in <img>) and an empty `data:` href (see `emptyDataHref`).
+export function pickBestIconCandidate(candidates) {
+    if (candidates.length === 0)
+        return null;
+    const viable = candidates.filter((c) => !c.rel.includes('mask-icon') && !emptyDataHref(c.href));
+    if (viable.length === 0)
+        return null;
+    return viable
+        .map((c) => ({ c, score: scoreIcon(c) }))
+        .sort((a, b) => b.score - a.score)[0].c;
+}
+function scoreIcon(c) {
+    let s = 0;
+    // Apple touch icons are usually 180px and padded with background
+    // colour — usable but a worse fit at 16x16 than a plain "icon".
+    s += c.rel.includes('apple-touch') ? 20 : 60;
+    const t = (c.type ?? '').toLowerCase();
+    if (t === 'image/png')
+        s += 20;
+    else if (t === 'image/svg+xml')
+        s += 15;
+    else if (t === 'image/x-icon' || t === 'image/vnd.microsoft.icon')
+        s += 10;
+    else if (t === 'image/jpeg' || t === 'image/webp')
+        s += 5;
+    const size = maxDeclaredSize(c.sizes);
+    if (size === null)
+        s += 3;
+    else if (size === Infinity)
+        s += 25; // sizes="any" → vector
+    else if (size >= 32 && size <= 64)
+        s += 30; // 16px @ 2x dpi target
+    else if (size >= 16 && size < 32)
+        s += 18;
+    else if (size > 64 && size <= 192)
+        s += 12;
+    else
+        s += 1;
+    return s;
+}
+// Read the largest `<width>x<height>` pair out of a `sizes` attribute,
+// returning Infinity for the literal `any` (used by vector icons) and
+// null when nothing parses.
+export function maxDeclaredSize(sizes) {
+    if (!sizes)
+        return null;
+    const lc = sizes.toLowerCase().trim();
+    if (lc === 'any')
+        return Infinity;
+    let max = null;
+    for (const m of lc.matchAll(/(\d+)x(\d+)/g)) {
+        const n = Math.max(Number(m[1]), Number(m[2]));
+        if (max === null || n > max)
+            max = n;
+    }
+    return max;
+}
+// ---------- Icon + HTML retrieval ----------
+//
+// Both legs delegate to file-loader's `fetchResourceBytes`. The icon
+// path supports http(s) and file:// uniformly (the latter via the
+// page-context XHR fallback). HTML probing is http-only with a more
+// permissive content-type gate. Size caps are enforced inside
+// fetchResourceBytes against both Content-Length (when the server
+// supplies it) and the buffered body.
+function normalizeSiteHost(url) {
+    try {
+        return new URL(url).host.toLowerCase().replace(/^www\./, '');
+    }
+    catch {
+        return null;
+    }
+}
+// True when a fetch that started at `requestedUrl` and ended at
+// `finalUrl` stayed on the same host (allowing a leading `www.`
+// difference; scheme may change, port may not). False when it bounced
+// across hosts — e.g. to an SSO (single sign-on) login page
+// (`login.corp.google.com`, `accounts.google.com`) or a marketing
+// portal (`workspace.google.com`), whose `<link rel="icon">` belongs
+// to that other host rather than the site we asked about.
+//
+// Deliberately host-level, not registrable-domain (eTLD+1): a looser
+// check would re-admit `app.corp.google.com` → `login.corp.google.com`,
+// which is the exact case this exists to reject. The cost is that a
+// legitimate `example.com` → `app.example.com` bounce also misses,
+// and that layer then falls through to the next strategy.
+export function isSameHostRedirect(requestedUrl, finalUrl) {
+    const reqHost = normalizeSiteHost(requestedUrl);
+    const finHost = normalizeSiteHost(finalUrl);
+    return reqHost !== null && reqHost === finHost;
+}
+// ---------- Chrome `_favicon` database lookup ----------
+//
+// Chrome's Manifest V3 `favicon` permission exposes
+// `chrome-extension://<id>/_favicon/`, backed by Chrome's internal
+// favicon database (populated when the user visits pages in real tabs —
+// after SSO authentication and after client-side JS updates
+// `<link rel="icon">`).
+//
+// Quirk: `/_favicon/` never 404s when a URL is unknown to Chrome's DB;
+// it returns 200 with Chrome's default globe PNG. We fetch a known-miss
+// sentinel URL once per context to learn those exact bytes and reject
+// any response that matches them. (The handler ignores
+// `forceEmptyDefaultFavicon`, so there is no cleaner miss signal.)
+//
+// Chrome's `fallbackToHost` parameter defaults to on: an unvisited page
+// URL then answers with the host's icon. The path-scoped tier turns it
+// off so it only ever reports a page-specific hit — otherwise every
+// deep URL on a host would cache the host icon and HTML discovery at
+// that page would never run.
+//
+// Known gap: Chrome maps an icon onto every URL of the redirect chain
+// that led to it, so a tab that bounced to SSO and never signed in
+// leaves the SSO icon on the original URL. The DB tier then returns it
+// and the 7-day TTL is the only way out (see TODO.md).
+const CHROME_FAVICON_SIZE = 32;
+const CHROME_FAVICON_MISS_SENTINEL = 'http://sm-favicon-miss-sentinel.invalid/';
+let chromeFallbackGlobePromise = null;
+export function chromeFaviconUrl(pageUrl, opts, size = CHROME_FAVICON_SIZE) {
+    const u = new URL(chrome.runtime.getURL('/_favicon/'));
+    u.searchParams.set('pageUrl', pageUrl);
+    u.searchParams.set('size', String(size));
+    if (opts?.exactPage)
+        u.searchParams.set('fallbackToHost', '0');
+    return u.toString();
+}
+async function fetchChromeFaviconRaw(pageUrl, opts) {
+    if (typeof chrome === 'undefined' || !chrome.runtime?.getURL)
+        return null;
+    let url;
+    try {
+        url = chromeFaviconUrl(pageUrl, opts);
+    }
+    catch {
+        return null;
+    }
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    const mime = (res.headers.get('content-type') ?? '').split(';')[0].trim() || 'image/png';
+    let body;
+    try {
+        body = await res.arrayBuffer();
+    }
+    catch {
+        return null;
+    }
+    if (body.byteLength === 0 || body.byteLength > MAX_ICON_BYTES)
+        return null;
+    const dataUrl = arrayBufferToDataUrl(body, mime);
+    return paintableIcon(dataUrl) ? dataUrl : null;
+}
+function getChromeFallbackGlobe() {
+    if (!chromeFallbackGlobePromise) {
+        chromeFallbackGlobePromise = fetchChromeFaviconRaw(CHROME_FAVICON_MISS_SENTINEL).then((res) => {
+            if (!res)
+                chromeFallbackGlobePromise = null;
+            return res;
+        });
+    }
+    return chromeFallbackGlobePromise;
+}
+export async function fetchChromeFavicon(pageUrl, opts) {
+    const [candidate, fallbackGlobe] = await Promise.all([
+        fetchChromeFaviconRaw(pageUrl, opts),
+        getChromeFallbackGlobe(),
+    ]);
+    if (!candidate)
+        return null;
+    if (!fallbackGlobe || candidate === fallbackGlobe)
+        return null;
+    return candidate;
+}
+async function fetchHtml(url) {
+    const res = await fetchResourceBytes(url, {
+        maxBytes: MAX_HTML_BYTES,
+        acceptContentType: (ct) => ct.includes('html'),
+    });
+    // `isNotModified` can't fire — neither icon fetch passes `conditional`
+    // — but it is in the return type, and narrowing it here is cheaper
+    // than a cast that would go stale if one ever did.
+    if ('failed' in res || isNotModified(res))
+        return null;
+    if (!isSameHostRedirect(url, res.finalUrl))
+        return null;
+    // Decode as UTF-8. Real-world HTML in non-UTF-8 charsets is rare
+    // enough today that we accept the occasional mojibake — and even
+    // then the icon link tags are ASCII attributes that decode fine.
+    const text = new TextDecoder('utf-8', { fatal: false }).decode(res.body);
+    return { text, finalUrl: res.finalUrl };
+}
+// Scheme-aware icon fetch. Used by both the origin-discovery path
+// (always http(s)) and the `@icon`-header path (any of http(s)/file://).
+// Goes through file-loader's bounded byte fetcher so the page-context
+// chrome-extension → file:// opaque-response trap is sidestepped.
+async function fetchIconAt(url, opts) {
+    const res = await fetchResourceBytes(url, {
+        maxBytes: MAX_ICON_BYTES,
+        acceptContentType: isIconContentType,
+    });
+    // Icons fail quietly — a missing favicon is cosmetic, and there is
+    // no surface that would show a reason.
+    if ('failed' in res || isNotModified(res))
+        return null;
+    if (opts?.rejectCrossHostRedirect && !isSameHostRedirect(url, res.finalUrl)) {
+        return null;
+    }
+    // Strip any `; charset=…` parameter; default to image/x-icon when
+    // the server omitted Content-Type so the data URL still renders.
+    const mime = res.contentType.split(';')[0].trim() || 'image/x-icon';
+    const dataUrl = arrayBufferToDataUrl(res.body, mime);
+    // Keep the stored-icons-are-paintable invariant local. A zero-byte
+    // 200 would encode to a payload-less `data:<mime>;base64,`, which
+    // the read side rejects — so storing it would mean refetching on
+    // every single paint, forever, and silently. `fetchResourceBytes`
+    // already refuses empty bodies, but that lives in another module.
+    return paintableIcon(dataUrl) ? dataUrl : null;
+}
+function arrayBufferToDataUrl(buffer, mime) {
+    const bytes = new Uint8Array(buffer);
+    // Build the binary string in chunks; passing the whole array to
+    // String.fromCharCode blows the call stack for large icons.
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return `data:${mime};base64,${btoa(binary)}`;
+}
+// ---------- Higher-level helpers ----------
+// In-flight de-dup: simultaneous calls for the same cache key share one
+// Promise. Cache rows that go stale and trigger a refetch land here
+// too — the second caller waits on the first. The map is keyed by the
+// full storage key (e.g. `siteIcon:<origin>` vs `iconUrl:<url>`) so the
+// two icon-collection paths don't collide.
+const inflight = new Map();
+// Answers already known on this page, by the same storage keys: a
+// usable cache row read here, or a fetch finished here. Lets a slot
+// whose icons are all known be drawn finished, with no globe first;
+// see `renderSiteIconInto`. Page-lifetime, like the cache rows it
+// mirrors, which last days.
+const settled = new Map();
+function remember(key, pending) {
+    return pending.then((dataUrl) => {
+        settled.set(key, dataUrl);
+        return dataUrl;
+    });
+}
+// The page URL `ensureSiteIcon` probes before falling back to the
+// origin, or null when it goes straight to the origin. The path-scoped
+// layer only earns its keep when the probe is deeper than the origin
+// root — otherwise it would just duplicate the origin-root HTML fetch
+// the fallback chain already does.
+function pathProbeUrl(origin, pageUrl) {
+    if (pageUrl === undefined || pageUrl === origin + '/' || pageUrl === origin)
+        return null;
+    return pageUrl;
+}
+export async function ensureSiteIcon(origin, pageUrl) {
+    const probe = pathProbeUrl(origin, pageUrl);
+    if (probe) {
+        const pathHit = await ensurePathIcon(probe);
+        if (pathHit !== null)
+            return pathHit;
+    }
+    return ensureOriginIcon(origin);
+}
+async function ensurePathIcon(pageUrl) {
+    const key = pathIconKey(pageUrl);
+    const pending = inflight.get(key);
+    if (pending)
+        return pending;
+    const cached = usableCacheHit(await loadPathIcon(pageUrl), DISCOVERED_ICON_CACHE_VERSION);
+    if (cached) {
+        settled.set(key, cached.dataUrl);
+        return cached.dataUrl;
+    }
+    // Re-check after the storage await: another caller may have started
+    // a fetch while we were reading.
+    const racing = inflight.get(key);
+    if (racing)
+        return racing;
+    const p = remember(key, fetchToCache(key)).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, p);
+    return p;
+}
+async function ensureOriginIcon(origin) {
+    const key = siteIconKey(origin);
+    const pending = inflight.get(key);
+    if (pending)
+        return pending;
+    const cached = usableCacheHit((await loadSiteIcons([origin])).get(origin), DISCOVERED_ICON_CACHE_VERSION);
+    if (cached) {
+        settled.set(key, cached.dataUrl);
+        return cached.dataUrl;
+    }
+    const racing = inflight.get(key);
+    if (racing)
+        return racing;
+    const p = remember(key, fetchToCache(key)).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, p);
+    return p;
+}
+// Resolve a script-declared icon URL (`@icon` / `@iconURL` / etc.).
+// Inline `data:` URLs are returned directly when within the size cap;
+// http(s) and file:// URLs go through the same bounded fetch + storage
+// cache the origin-discovery path uses, keyed by the URL itself so
+// multiple scripts sharing a URL share one fetch.
+//
+// `localRoots` opts this into the same local-override rule `@require`
+// and `@resource` use — see docs/local-file-overrides.md. Without it
+// (the default) nothing changes and no local reads happen. A script
+// that declares its icon by absolute URL while developing locally would
+// otherwise be the one file reference that ignored the copy on disk,
+// which reads as a gap rather than a policy.
+export async function ensureIconForUrl(url, localRoots = []) {
+    if (url.startsWith('data:'))
+        return usableDataUrl(url);
+    for (const candidate of await presentLocalFileCandidates(url, localRoots, iconRootListings)) {
+        const local = await localIconCandidate(candidate);
+        if (local)
+            return local;
+    }
+    return ensureIconAt(url);
+}
+// A local stand-in candidate, memoized for the life of the page rather
+// than written to the storage cache.
+//
+// Deliberately NOT the storage cache: a miss there is remembered for 24
+// hours, so an icon file created after the first paint wouldn't appear
+// until the next day — the same "why isn't my edit showing up" trap the
+// require path exists to avoid. A page-lifetime memo instead means the
+// cost is one local read per icon per page load (repaints are free) and
+// a reload always sees the current state of the disk.
+//
+// A candidate that isn't there, or isn't an image, just returns null and
+// the caller falls through to the declared URL.
+const localIconMemo = new Map();
+// Root listings for the candidate gate, memoized for the life of the
+// page for the same reason as `localIconMemo`: the page-lifetime memo
+// already means a file created after first paint waits for a reload,
+// so a listing of the same age hides nothing the memo didn't.
+const iconRootListings = new Map();
+function localIconCandidate(url) {
+    const memo = localIconMemo.get(url);
+    if (memo)
+        return memo;
+    const p = fetchIconAt(url);
+    localIconMemo.set(url, p);
+    return p;
+}
+async function ensureIconAt(url) {
+    const key = urlIconKey(url);
+    const pending = inflight.get(key);
+    if (pending)
+        return pending;
+    const cached = usableCacheHit(await loadUrlIcon(url));
+    if (cached) {
+        settled.set(key, cached.dataUrl);
+        return cached.dataUrl;
+    }
+    const racing = inflight.get(key);
+    if (racing)
+        return racing;
+    const p = remember(key, fetchToCache(key)).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, p);
+    return p;
+}
+// ---------- Known answers ----------
+// The icon `ensureSiteIcon` would give for a site, when it is already
+// known on this page; undefined when it has to be looked up.
+function settledSiteIcon(t) {
+    const probe = pathProbeUrl(t.origin, t.linkUrl);
+    if (probe) {
+        const pathHit = settled.get(pathIconKey(probe));
+        if (pathHit === undefined)
+            return undefined;
+        if (pathHit !== null)
+            return pathHit;
+    }
+    return settled.get(siteIconKey(t.origin));
+}
+// Same for `ensureIconForUrl`. Never known up front with local roots:
+// a stand-in on disk is looked for first, and that is a read.
+function settledUrlIcon(url, localRoots) {
+    if (url.startsWith('data:'))
+        return usableDataUrl(url);
+    if (localRoots.length > 0)
+        return undefined;
+    return settled.get(urlIconKey(url));
+}
+// The script's declared icon, resolved against its own URL, or null.
+// The header value is raw (URL, data:, or relative path). Resolving it
+// against the script's own URL lets `@icon foo.png` reach the sibling
+// file alongside the script. A ref that climbs out of a LOCAL script's
+// folder is rejected and drops back to origin discovery; from a remote
+// script it resolves like any other URL.
+function declaredIconUrl(script) {
+    const iconRef = iconRefFromHeader(script.header ?? null);
+    return iconRef ? resolveScriptResource(iconRef, script.fileUrl)?.url ?? null : null;
+}
+// Read every cached icon these scripts' slots will ask for, in one
+// storage read, so the slots drawn next can show them straight away
+// instead of a globe that changes a moment later. Only reads: a miss
+// is left for the slot to fetch.
+export async function preloadSiteIcons(scripts, limit = MAX_SITE_ICONS) {
+    const discovered = new Set();
+    const declared = new Set();
+    for (const script of scripts) {
+        const url = declaredIconUrl(script);
+        if (url) {
+            if (!url.startsWith('data:'))
+                declared.add(urlIconKey(url));
+            continue;
+        }
+        for (const t of representativeMatches(script.matching, limit)) {
+            const probe = pathProbeUrl(t.origin, t.linkUrl);
+            if (probe)
+                discovered.add(pathIconKey(probe));
+            discovered.add(siteIconKey(t.origin));
+        }
+    }
+    const keys = [...discovered, ...declared].filter((k) => !settled.has(k));
+    if (keys.length === 0)
+        return;
+    const got = await chrome.storage.local.get(keys);
+    for (const key of keys) {
+        const entry = got[key];
+        const hit = usableCacheHit(entry, discovered.has(key) ? DISCOVERED_ICON_CACHE_VERSION : undefined);
+        if (hit)
+            settled.set(key, hit.dataUrl);
+    }
+}
+// How many sites a page heading shows — the viewer's and the compare
+// page's. More than a collections row: the heading is the one place a
+// script's whole target list is worth a glance, and nothing beside it
+// needs to line up.
+export const HEADING_SITE_ICONS = 10;
+// Build the favicon slot for a script row / viewer header. Always
+// renders something synchronously: one clickable `<a>` per distinct
+// site the script's @match set names (opening that site's linkUrl in
+// a new tab, at most `limit` of them — a table row has less room than
+// a heading), or a single inert `<span>` when no pattern yields a
+// usable origin (file:// scripts, `<all_urls>`, etc.). Every wrapper
+// starts with a globe placeholder, swapped for the real favicon once
+// it loads. Until every site's icon has loaded, only the first site's
+// wrapper is in the slot. When every icon is already known on this
+// page (`preloadSiteIcons`), the finished slot is drawn at once.
+//
+// Two sites that turn out to share one favicon image (maps.google.com
+// and www.google.com, say) — or that both came up empty and show the
+// globe — collapse to the first icon once both have loaded: the
+// duplicate is removed and the survivor's tooltip lists every site it
+// now stands for. Compared by the resolved data URL, which is the only
+// way to know — the hosts differ.
+//
+// Icon collection priority: a script-declared `@icon` (or its aliases)
+// wins outright over the origin-discovered favicons and collapses the
+// slot to that one icon — a script that pins its icon has said what
+// it wants to look like. Its click-through link is still the first
+// site's linkUrl — the @icon header is only a visual override.
+//
+// Resolves, once every fetch has settled, with the number of icons the
+// slot ended up holding.
+export async function renderSiteIconInto(slot, script, 
+// Local override roots for a script-declared `@icon`, from the
+// caller's `StoredCollection`. Passed in rather than derived here
+// because the per-collection opt-out lives on the collection row,
+// which this module has no reason to load. Omitted → no overrides, no
+// local reads.
+localRoots = [], limit = MAX_SITE_ICONS) {
+    const targets = representativeMatches(script.matching, limit);
+    const iconUrl = declaredIconUrl(script);
+    if (targets.length === 0) {
+        // No usable target URL for this script's @match set (file://,
+        // `<all_urls>`, malformed pattern, …). Surface that explicitly so
+        // hovering the inert globe isn't silent.
+        const inner = buildInner(slot, null);
+        slot.replaceChildren(inner);
+        if (iconUrl)
+            await paintDeclaredIcon(inner, iconUrl, localRoots);
+        return 1;
+    }
+    if (iconUrl) {
+        // This is the script's own icon, not a site's, so the tooltip leads
+        // with the script's name; every site it names follows — all of
+        // them, not just the `limit` a row would show.
+        const inner = buildInner(slot, targets[0]);
+        const sites = representativeMatches(script.matching, Infinity).map((t) => t.linkUrl);
+        const name = script.header ? getValue(script.header, 'name')?.trim() : undefined;
+        inner.title = name ? `${name}\n${sitesTooltip(sites)}` : sitesTooltip(sites);
+        slot.replaceChildren(inner);
+        await paintDeclaredIcon(inner, iconUrl, localRoots);
+        return 1;
+    }
+    const inners = targets.map((t) => buildInner(slot, t));
+    // Every icon already known on this page (`preloadSiteIcons`): draw
+    // the finished slot now, so it never changes width after it appears.
+    const known = targets.map(settledSiteIcon);
+    if (known.every((icon) => icon !== undefined)) {
+        const painted = known.map((icon, i) => showIcon(inners[i], icon ?? null));
+        return fillMergedSlot(slot, targets, inners, painted);
+    }
+    // Otherwise only the first site's placeholder is shown while the
+    // icons load: the others are globes too until then, and a row of
+    // identical globes that later collapses to one makes the layout
+    // jump. The slot widens once the icons turn out to differ.
+    slot.replaceChildren(inners[0]);
+    const painted = await Promise.all(targets.map((t, i) => paintIcon(inners[i], ensureSiteIcon(t.origin, t.linkUrl))));
+    // Skipped when a newer render has replaced the slot's contents, so a
+    // stale pass can't put its icons back.
+    if (inners[0].parentNode !== slot)
+        return slot.childElementCount;
+    return fillMergedSlot(slot, targets, inners, painted);
+}
+// Paint a declared `@icon` into `inner`: at once when this page already
+// knows it, otherwise once it loads.
+async function paintDeclaredIcon(inner, url, localRoots) {
+    const known = settledUrlIcon(url, localRoots);
+    if (known !== undefined)
+        showIcon(inner, known);
+    else
+        await paintIcon(inner, ensureIconForUrl(url, localRoots));
+}
+// Fill `slot` with one icon per distinct picture among the sites'
+// painted icons, and return how many that is.
+//
+// Collapses sites whose favicon came back byte-identical — and sites
+// that all ended on the globe, which look identical too; a row of
+// three globes says nothing three times.
+function fillMergedSlot(slot, targets, inners, painted) {
+    const merged = mergeSlot(painted);
+    for (const { sites } of merged) {
+        if (sites.length > 1)
+            inners[sites[0]].title = sitesTooltip(sites.map((i) => targets[i].linkUrl));
+    }
+    slot.replaceChildren(...merged.map(({ sites }) => inners[sites[0]]));
+    return merged.length;
+}
+/**
+ * The icons a slot shows for its sites' icons (`painted`, null for the
+ * globe), in the order shown: each as the indexes of the sites it
+ * stands for, its own first. Byte-identical icons are one, and so are
+ * globes.
+ */
+export function mergeSlot(painted) {
+    const byIcon = new Map();
+    painted.forEach((icon, i) => {
+        const sites = byIcon.get(icon ?? '');
+        if (sites)
+            sites.push(i);
+        else
+            byIcon.set(icon ?? '', [i]);
+    });
+    const kept = [...byIcon.values()];
+    // Real favicons before the globe: a globe says only "a site", so it
+    // goes last where it isn't in the way. The first site stays first
+    // even as a globe — it is the script's primary site, and the header
+    // order is what the reader expects to find there.
+    const shownFirst = (sites) => sites[0] === 0 || painted[sites[0]] !== null;
+    return [...kept.filter(shownFirst), ...kept.filter((sites) => !shownFirst(sites))].map((sites) => ({ sites }));
+}
+// Lines a merged icon's tooltip can show before it turns into a count.
+const TOOLTIP_SITES_MAX = 10;
+// Tooltip for an icon standing for several sites: one URL per line,
+// then `(and N more)` once the list runs long — a fifty-site tooltip
+// is a wall, not a hint.
+export function sitesTooltip(urls) {
+    if (urls.length <= TOOLTIP_SITES_MAX)
+        return urls.join('\n');
+    const shown = urls.slice(0, TOOLTIP_SITES_MAX);
+    return `${shown.join('\n')}\n(and ${urls.length - TOOLTIP_SITES_MAX} more)`;
+}
+// The icon for ONE `@match` pattern, as the viewer's Match rows show
+// beside each entry. Linked to `linkUrl` when the pattern gave us one
+// (the site, or the same-directory fallback for a site-less pattern),
+// inert otherwise. The favicon comes from `target`'s site; a linkable
+// pattern that names no site (`*://*/x/page.html`) keeps the globe.
+// `noLinkTitle` replaces the inert globe's default tooltip.
+export function renderPatternIconInto(slot, target, linkUrl, noLinkTitle) {
+    const inner = buildInner(slot, linkUrl, noLinkTitle);
+    slot.replaceChildren(inner);
+    if (target)
+        void paintIcon(inner, ensureSiteIcon(target.origin, target.linkUrl));
+}
+// One icon's wrapper: a link when there is a URL to open, an inert
+// span otherwise. Starts out holding the globe placeholder.
+function buildInner(slot, target, noLinkTitle = 'Unable to extract link to target site') {
+    const linkUrl = typeof target === 'string' ? target : target?.linkUrl ?? null;
+    const inner = slot.ownerDocument.createElement(linkUrl ? 'a' : 'span');
+    inner.className = 'site-icon-inner';
+    inner.appendChild(buildGlobeSvg(slot.ownerDocument));
+    if (linkUrl) {
+        const a = inner;
+        a.href = linkUrl;
+        a.target = '_blank';
+        a.rel = 'noopener noreferrer';
+        a.title = linkUrl;
+    }
+    else {
+        inner.title = noLinkTitle;
+    }
+    return inner;
+}
+// Swap the globe inside `inner` for the icon `pending` resolves to,
+// and hand back that icon's data URL (null when there is none, or the
+// fetch failed — the globe stays). No isConnected guard: a re-render
+// replaces the whole slot, so any paint into an orphaned `inner`
+// decorates a subtree the user never sees.
+async function paintIcon(inner, pending) {
+    let dataUrl;
+    try {
+        dataUrl = await pending;
+    }
+    catch {
+        return null;
+    }
+    return showIcon(inner, dataUrl);
+}
+// Swap the globe inside `inner` for `dataUrl`'s picture, if there is
+// one, and hand `dataUrl` back.
+function showIcon(inner, dataUrl) {
+    if (!dataUrl)
+        return null;
+    const img = inner.ownerDocument.createElement('img');
+    img.src = iconImgSrc(dataUrl);
+    img.alt = '';
+    inner.replaceChildren(img);
+    return dataUrl;
+}
+// Per-document registry: one blob: URL per distinct large icon. With
+// dozens of scripts targeting the same site, every row otherwise
+// inlined its own copy of the favicon's base64 `data:` URL — a handful
+// of distinct icons re-inlined across ~every row, which ballooned the
+// collections page past half a megabyte. Pointing every row at a shared
+// ~55-char blob: handle instead drops all that duplication out of the
+// DOM; the bytes live once in the browser's blob table.
+//
+// Document-lifetime, never revoked: the set is bounded by the number of
+// DISTINCT icons on the page (tiny), and not revoking keeps it
+// bfcache-safe — a restored page's <img>s still resolve. This mirrors
+// the GM_getResourceURL policy (see wrapper-gm-runtime.js). Keyed by the
+// data: URL string, so a re-render reuses the existing blob for an
+// unchanged icon and only mints one for genuinely new icons.
+const iconObjectUrls = new Map();
+// Icons whose `data:` URL is at or below this many chars stay inline —
+// below it a blob: URL (plus its table entry) doesn't beat the data URL
+// it would replace, and de-duping a handful of tiny bytes isn't worth
+// it. Sits well above the favicons used in tests and well below
+// real-world ones (smallest observed ≈ 1.2 KB).
+const ICON_INLINE_MAX_LEN = 512;
+// Map a cached icon `data:` URL to what we actually put in `<img src>`:
+// large icons become a shared blob: URL (deduped by the data URL
+// string); small ones pass through unchanged.
+function iconImgSrc(dataUrl) {
+    if (dataUrl.length <= ICON_INLINE_MAX_LEN)
+        return dataUrl;
+    const existing = iconObjectUrls.get(dataUrl);
+    if (existing)
+        return existing;
+    const blob = dataUrlToBlob(dataUrl);
+    if (!blob)
+        return dataUrl; // unparseable → fall back to inline
+    const url = URL.createObjectURL(blob);
+    iconObjectUrls.set(dataUrl, url);
+    return url;
+}
+// Decode a `data:[<mime>][;base64],<payload>` URL into a Blob
+// synchronously (no fetch round-trip) so the caller can swap `src`
+// without an extra await. Handles base64 and plain (percent-encoded)
+// payloads; returns null on anything it can't parse. The non-base64
+// branch assumes a TEXT payload (it round-trips through a JS string, so
+// raw binary would be UTF-8-mangled) — fine here because real binary
+// icon data URLs are always `;base64`; the only non-base64 icons we
+// see are inline SVG/text.
+export function dataUrlToBlob(dataUrl) {
+    const content = dataUrlContent(dataUrl);
+    return content ? new Blob([base64ToBytes(content.base64)], { type: content.contentType }) : null;
+}
+/** A `data:` URL's type and bytes, as base64; null for one that isn't well-formed. */
+export function dataUrlContent(dataUrl) {
+    const comma = dataUrl.indexOf(',');
+    if (!dataUrl.startsWith('data:') || comma < 0)
+        return null;
+    const meta = dataUrl.slice(5, comma); // e.g. "image/png;base64"
+    const payload = dataUrl.slice(comma + 1);
+    const isBase64 = /;base64$/i.test(meta);
+    const contentType = (isBase64 ? meta.slice(0, -7) : meta).split(';')[0] || 'application/octet-stream';
+    try {
+        // Checked as base64 by decoding it.
+        if (isBase64)
+            return { contentType, base64: bytesToBase64(new Uint8Array(base64ToBytes(payload.trim()))) };
+        return { contentType, base64: bytesToBase64(new TextEncoder().encode(decodeURIComponent(payload))) };
+    }
+    catch {
+        return null;
+    }
+}
+// The globe placeholder shown until a favicon loads (and the permanent
+// icon for scripts with no resolvable origin). Rendered as a tiny
+// `<use>` of the shared `#sm-globe` <symbol> defined once per page, so
+// 100+ rows don't each inline the full circle+meridian path data. The
+// stroke/fill presentation lives in CSS on `.site-icon-globe`.
+function buildGlobeSvg(doc) {
+    return renderGlyph(doc, '#sm-globe', 'site-icon-globe');
+}
+export function isIconCacheKey(key) {
+    return (key.startsWith(KEY_PREFIX) ||
+        key.startsWith(PATH_ICON_KEY_PREFIX) ||
+        key.startsWith(URL_ICON_KEY_PREFIX));
+}
+export function parseCachedIconRow(storageKey, value, now = Date.now()) {
+    let kind;
+    let target;
+    let requireVersion;
+    if (storageKey.startsWith(KEY_PREFIX)) {
+        kind = 'origin';
+        target = storageKey.slice(KEY_PREFIX.length);
+        requireVersion = DISCOVERED_ICON_CACHE_VERSION;
+    }
+    else if (storageKey.startsWith(PATH_ICON_KEY_PREFIX)) {
+        kind = 'path';
+        target = storageKey.slice(PATH_ICON_KEY_PREFIX.length);
+        requireVersion = DISCOVERED_ICON_CACHE_VERSION;
+    }
+    else if (storageKey.startsWith(URL_ICON_KEY_PREFIX)) {
+        kind = 'url';
+        target = storageKey.slice(URL_ICON_KEY_PREFIX.length);
+        requireVersion = undefined;
+    }
+    else {
+        return null;
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    if (typeof raw.fetchedAt !== 'number')
+        return null;
+    const dataUrl = typeof raw.dataUrl === 'string' ? raw.dataUrl : null;
+    const entry = {
+        dataUrl,
+        fetchedAt: raw.fetchedAt,
+        ...(typeof raw.v === 'number' ? { v: raw.v } : {}),
+    };
+    const ttl = entry.dataUrl !== null ? SUCCESS_TTL_MS : NULL_TTL_MS;
+    const expiresAt = entry.fetchedAt + ttl;
+    const isFresh = isCacheFresh(entry, now);
+    const isUsable = usableCacheHit(entry, requireVersion, now) !== null;
+    let mimeType = null;
+    let byteLength = null;
+    if (entry.dataUrl) {
+        const blob = dataUrlToBlob(entry.dataUrl);
+        if (blob) {
+            mimeType = blob.type || null;
+            byteLength = blob.size;
+        }
+    }
+    return {
+        storageKey,
+        kind,
+        target,
+        entry,
+        expiresAt,
+        isFresh,
+        isUsable,
+        requiredVersion: requireVersion ?? null,
+        mimeType,
+        byteLength,
+    };
+}
+export async function listCachedIcons(now = Date.now()) {
+    const keys = (await chrome.storage.local.getKeys()).filter(isIconCacheKey);
+    if (keys.length === 0)
+        return [];
+    const got = await chrome.storage.local.get(keys);
+    const rows = [];
+    for (const [k, v] of Object.entries(got)) {
+        const row = parseCachedIconRow(k, v, now);
+        if (row)
+            rows.push(row);
+    }
+    rows.sort((a, b) => a.target.localeCompare(b.target) || a.storageKey.localeCompare(b.storageKey));
+    return rows;
+}
+export async function deleteCachedIcon(storageKey) {
+    assertWorkerContext('write storage');
+    await chrome.storage.local.remove(storageKey);
+}
+export async function deleteAllCachedIcons() {
+    assertWorkerContext('write storage');
+    const keys = (await chrome.storage.local.getKeys()).filter(isIconCacheKey);
+    if (keys.length > 0) {
+        await chrome.storage.local.remove(keys);
+    }
+}
+// Fetch the icon a cache key names and store it under that key, in the
+// worker, which alone writes storage (docs/worker-writes.md). A page
+// asks it, and keeps its own in-flight and settled maps for painting.
+function fetchToCache(storageKey) {
+    if (isPageContext())
+        return callWorker('ensureCachedIcon', storageKey);
+    // Not `ensureCachedIcon`: the caller has already put this fetch in
+    // `inflight` under the key, which `refreshCachedIcon` would then wait on.
+    return fetchAndCacheByKey(storageKey) ?? Promise.resolve(null);
+}
+function fetchAndCacheByKey(storageKey) {
+    let fetchIt = null;
+    if (storageKey.startsWith(KEY_PREFIX)) {
+        fetchIt = () => fetchAndCacheOriginIcon(storageKey.slice(KEY_PREFIX.length));
+    }
+    else if (storageKey.startsWith(PATH_ICON_KEY_PREFIX)) {
+        fetchIt = () => fetchAndCachePathIcon(storageKey.slice(PATH_ICON_KEY_PREFIX.length));
+    }
+    else if (storageKey.startsWith(URL_ICON_KEY_PREFIX)) {
+        fetchIt = () => fetchAndCacheUrlIcon(storageKey.slice(URL_ICON_KEY_PREFIX.length));
+    }
+    return fetchIt ? withFetchSlot(fetchIt) : null;
+}
+// At most this many icon fetches at once. A page on a cold cache asks
+// for every icon it shows, all at once.
+const MAX_ICON_FETCHES = 6;
+let iconFetches = 0;
+const iconFetchQueue = [];
+async function withFetchSlot(run) {
+    if (iconFetches >= MAX_ICON_FETCHES)
+        await new Promise((go) => iconFetchQueue.push(go));
+    else
+        iconFetches++;
+    try {
+        return await run();
+    }
+    finally {
+        // A waiter takes this slot over; with none, it is freed.
+        const next = iconFetchQueue.shift();
+        if (next)
+            next();
+        else
+            iconFetches--;
+    }
+}
+// Worker side of a page's lookup: the cached row when it is still
+// usable (another page may have just fetched it), else a fetch, shared
+// with one already in flight for the key.
+export async function ensureCachedIcon(storageKey) {
+    const version = storageKey.startsWith(URL_ICON_KEY_PREFIX) ? undefined : DISCOVERED_ICON_CACHE_VERSION;
+    const row = (await chrome.storage.local.get(storageKey))[storageKey];
+    const cached = usableCacheHit(row, version);
+    if (cached)
+        return cached.dataUrl;
+    return await refreshCachedIcon(storageKey);
+}
+// Worker side: refetch one cache row now, sharing a fetch already in
+// flight for it. Pages reach it through `fetchToCache`, and the debug
+// icons page through worker-client.ts.
+export async function refreshCachedIcon(storageKey) {
+    const pending = inflight.get(storageKey);
+    if (pending)
+        return pending;
+    const p = fetchAndCacheByKey(storageKey);
+    if (!p)
+        return null;
+    const wrapped = p.finally(() => {
+        inflight.delete(storageKey);
+    });
+    inflight.set(storageKey, wrapped);
+    return wrapped;
+}
+// A usable cache row for `storageKey`; with `fetch`, looked up first
+// when there is none.
+async function iconRow(storageKey, fetch) {
+    const version = storageKey.startsWith(URL_ICON_KEY_PREFIX) ? undefined : DISCOVERED_ICON_CACHE_VERSION;
+    const read = async () => usableCacheHit((await chrome.storage.local.get(storageKey))[storageKey], version);
+    const hit = await read();
+    if (hit || !fetch)
+        return hit;
+    await refreshCachedIcon(storageKey);
+    return read();
+}
+/**
+ * Worker: the icons a page heading's slot shows for these `@match`
+ * patterns, merged and in order, ignoring a declared `@icon`. Without
+ * `fetch`, only from the cache: null when any isn't there.
+ */
+export async function siteIconsFor(matches, fetch) {
+    const targets = representativeMatches({ matches }, HEADING_SITE_ICONS);
+    const found = await Promise.all(targets.map(async (t) => {
+        const probe = pathProbeUrl(t.origin, t.linkUrl);
+        if (probe) {
+            const page = await iconRow(pathIconKey(probe), fetch);
+            if (!page)
+                return null;
+            if (page.dataUrl !== null)
+                return { entry: page, fromPage: true };
+        }
+        const origin = await iconRow(siteIconKey(t.origin), fetch);
+        return origin ? { entry: origin, fromPage: false } : null;
+    }));
+    if (found.some((f) => f === null))
+        return null;
+    const rows = found;
+    return mergeSlot(rows.map((r) => r.entry.dataUrl)).map(({ sites }) => {
+        const { entry, fromPage } = rows[sites[0]];
+        return {
+            sites: sites.map((i) => targets[i]),
+            dataUrl: entry.dataUrl,
+            ...(entry.dataUrl !== null && entry.source ? { source: entry.source } : {}),
+            fromPage,
+        };
+    });
+}
+/**
+ * Worker: the local stand-in for a declared http(s) icon, searched for
+ * in `localRoots` as a page does (`ensureIconForUrl`), but read fresh
+ * each time rather than kept for the page's life. Null for none.
+ */
+export async function localIconFor(url, localRoots) {
+    for (const candidate of await presentLocalFileCandidates(url, localRoots, new Map())) {
+        const dataUrl = await fetchIconAt(candidate);
+        if (dataUrl)
+            return { dataUrl, local: candidate };
+    }
+    return null;
+}
+/**
+ * Worker: a script's declared icon at `url`, as a `data:` URL; null
+ * when it can't be read. `file:` URLs are read fresh, uncached, as the
+ * file may have just changed. Leaves local stand-ins to `localIconFor`.
+ */
+export async function declaredIconFor(url) {
+    if (isDataUrl(url))
+        return usableDataUrl(url);
+    if (url.startsWith('file:'))
+        return fetchIconAt(url);
+    return (await iconRow(urlIconKey(url), true))?.dataUrl ?? null;
+}