sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/options.js

@@ -0,0 +1,504 @@
+// Options page controller. Owns the actual configurable settings
+// (link capture, debug-logging gate, local-file-override search roots,
+// GitHub auth token), plus a read-only storage-usage table. The
+// per-collection management UI lives on `collections.html` /
+// `collections.ts`; a header link points users back and forth.
+import { DEBUG_LOGGING_KEY, installDebugLoggingListener, loadDebugLoggingFlag, } from '../debug-log.js';
+import { GITHUB_AUTH_TOKEN_KEY } from '../github-auth.js';
+import { INSTALL_CAPTURE_KEY } from './install-capture.js';
+import { LOCAL_ROOTS_KEY, parseLocalRootLines, readRootsSetting, rootsFromText, textFromRoots, } from '../local-file-overrides.js';
+import { fetchFileUrlText } from './directories.js';
+import { describeError, getCollections } from './script-store.js';
+import { updateCollection, writeSetting } from './worker-client.js';
+import { timeStorageRead } from './storage-scan.js';
+import { formatQuota, formatStorageUsage } from '../script-display.js';
+import { summarizeLocalStorage, toWholeKb, withRemainder, } from './storage-usage.js';
+import { collectionSupportsLocalFiles } from '../local-file-overrides.js';
+import { isFileSchemeAccessAllowed, renderFileAccessBanner } from './file-access.js';
+import { DOWNLOADS_COPIES_KEY, parseDownloadsCopiesSetting, readDownloadsCopiesSetting, } from './local-copy.js';
+import { installHomeLinkHandler, onNamedTabFocus, openNamedTab } from './page-links.js';
+const openCollectionsBtn = document.getElementById('open-collections');
+// The collections page is a named tab: focus the open one if there is
+// one, and otherwise open a new tab rather than replacing this one.
+openCollectionsBtn.addEventListener('click', () => {
+    void openNamedTab('collections');
+});
+// The header bar's icon and product name are the same link.
+installHomeLinkHandler();
+// A link elsewhere focusing this tab rather than opening a second one.
+// This page has no anchors of its own to land on, so the whole of it is
+// the target: back to the top. See src/extension/page-links.ts.
+onNamedTabFocus('options', () => {
+    scrollTo({ top: 0, behavior: 'smooth' });
+});
+// Both boolean settings differ only in their storage key and what an
+// absent value means, so they share one binder. `defaultValue` is what
+// an unset key reads back as — capture is opt-out, debug logging is
+// opt-in.
+initBooleanSetting('capture-userjs', INSTALL_CAPTURE_KEY, true);
+// This page both sets the flag AND reads storage through shared code
+// that logs under it (the storage-read timings in `storage-scan`), so
+// it observes the flag like any other context: each one reads it for
+// itself. Refreshes it asks for run in the worker, which has its own.
+installDebugLoggingListener();
+void loadDebugLoggingFlag();
+initBooleanSetting('debug-logging', DEBUG_LOGGING_KEY, false);
+initGithubTokenControls();
+initLocalRootControls();
+initDownloadsDirControls();
+initStorageUsage();
+// Read-only table of what is stored in `chrome.storage.local`, by
+// kind, against Chrome's quota. Each paint scans every row, so a burst
+// of writes (a refresh, a script spamming GM_setValue) is coalesced into
+// one repaint a second at most.
+function initStorageUsage() {
+    const table = document.getElementById('storage-usage');
+    const limit = document.getElementById('storage-limit');
+    if (!table || !limit)
+        return;
+    const quota = chrome.storage.local.QUOTA_BYTES;
+    if (typeof quota === 'number' && quota > 0) {
+        limit.textContent = `Chrome limits each extension to ${formatQuota(quota)} of storage.`;
+        limit.hidden = false;
+    }
+    let pending = false;
+    // Paints can overlap (a slow full read, then a change); only the
+    // newest one may draw, so an older read finishing last can't put
+    // stale numbers back.
+    let latest = 0;
+    const paint = async () => {
+        pending = false;
+        const mine = ++latest;
+        const usage = await readUsage();
+        if (mine === latest)
+            table.replaceChildren(...usageRows(usage));
+    };
+    void paint();
+    chrome.storage.onChanged.addListener((_changes, areaName) => {
+        if (areaName !== 'local' || pending)
+            return;
+        pending = true;
+        setTimeout(() => void paint(), 1000);
+    });
+}
+async function readUsage() {
+    const quota = chrome.storage.local.QUOTA_BYTES;
+    if (typeof quota !== 'number' || quota <= 0) {
+        return { error: 'Chrome did not report its storage limit' };
+    }
+    try {
+        const [rows, used] = await Promise.all([
+            timeStorageRead('storage usage', () => chrome.storage.local.get(null)),
+            chrome.storage.local.getBytesInUse(null),
+        ]);
+        return { rows: withRemainder(summarizeLocalStorage(rows), used), used, quota };
+    }
+    catch (err) {
+        return { error: `Could not read storage usage: ${describeError(err)}` };
+    }
+}
+const kbFormat = new Intl.NumberFormat();
+function usageRows(usage) {
+    const row = (cells, className) => {
+        const tr = document.createElement('tr');
+        if (className)
+            tr.className = className;
+        for (const [text, cls, span] of cells) {
+            const td = document.createElement('td');
+            td.textContent = text;
+            if (cls)
+                td.className = cls;
+            if (span)
+                td.colSpan = span;
+            tr.appendChild(td);
+        }
+        return tr;
+    };
+    if ('error' in usage)
+        return [row([[usage.error]])];
+    // Whole KB throughout, so the column visibly adds up to the total.
+    const kb = toWholeKb(usage.rows, usage.used);
+    return [
+        // A row that rounds to nothing is left out rather than shown as 0.
+        ...usage.rows.flatMap((r, i) => kb[i] === 0 ? [] : [
+            row([[r.label], [r.count, 'num'], [`${kbFormat.format(kb[i])} KB`, 'num']]),
+        ]),
+        row([
+            ['Total'],
+            // Spans Count too: in the Size column alone, this longer text
+            // would set that column's width and open a wide gap before every
+            // size.
+            [formatStorageUsage(usage.used, usage.quota), 'num', 2],
+        ], 'total'),
+    ];
+}
+// The Downloads folder the local-copy feature learned (see
+// docs/local-copy.md). Editable for the one case the extension can't
+// detect on its own: Chrome's download location changed after the
+// first copy. Saving keeps the recorded collection id — the next copy
+// re-checks whether that collection still sits at the new path.
+function initDownloadsDirControls() {
+    const box = document.getElementById('downloads-dir');
+    const saveBtn = document.getElementById('downloads-dir-save');
+    const status = document.getElementById('downloads-dir-status');
+    if (!box || !saveBtn || !status)
+        return;
+    let saved = null;
+    const paint = (setting) => {
+        saved = setting;
+        if (!box.matches(':focus'))
+            box.value = setting?.downloadsDir ?? '';
+        saveBtn.disabled = box.value.trim() === (saved?.downloadsDir ?? '');
+    };
+    void readDownloadsCopiesSetting().then(paint);
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[DOWNLOADS_COPIES_KEY];
+        if (change)
+            paint(parseDownloadsCopiesSetting(change.newValue));
+    });
+    box.addEventListener('input', () => {
+        saveBtn.disabled = box.value.trim() === (saved?.downloadsDir ?? '');
+        status.textContent = '';
+    });
+    saveBtn.addEventListener('click', () => {
+        const dir = box.value.trim().replace(/\/+$/, '');
+        if (!dir.startsWith('/')) {
+            status.textContent = 'The Downloads folder must be an absolute path';
+            status.className = 'token-status err';
+            return;
+        }
+        void writeSetting(DOWNLOADS_COPIES_KEY, { downloadsDir: dir, collectionId: saved?.collectionId ?? null })
+            .then(() => {
+            status.textContent = 'Saved';
+            status.className = 'token-status ok';
+        }, (err) => {
+            status.textContent = `Could not save the Downloads folder: ${describeError(err)}`;
+            status.className = 'token-status err';
+        });
+    });
+}
+function initBooleanSetting(elementId, key, defaultValue) {
+    const cb = document.getElementById(elementId);
+    if (!cb)
+        return;
+    const read = (raw) => (typeof raw === 'boolean' ? raw : defaultValue);
+    // Hydrate from storage so the box reflects the persisted state, then
+    // mirror future writes (from anywhere — DevTools, another options
+    // tab) so the two never drift out of sync.
+    void chrome.storage.local.get(key).then((got) => {
+        cb.checked = read(got[key]);
+    });
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[key];
+        if (!change)
+            return;
+        cb.checked = read(change.newValue);
+    });
+    cb.addEventListener('change', () => {
+        const wanted = cb.checked;
+        writeSetting(key, wanted).catch((err) => {
+            console.info(`[SourceMonkey] could not save ${key}:`, describeError(err));
+            // Back to what is stored, unless another change has moved it since.
+            if (cb.checked === wanted)
+                cb.checked = !wanted;
+        });
+    });
+}
+// Local search roots: a multi-line box, one absolute path per line.
+//
+// The setting stores the PARSED array, so this box is where text
+// becomes roots — which is why Save is disabled while any line is
+// malformed. Nothing downstream re-parses, so nothing downstream has to
+// decide what a bad line means.
+//
+// Two kinds of complaint, and only one of them blocks Save:
+//   - Format. Decided locally and instantly. Blocks.
+//   - Existence. Requires a `file://` read, so it's debounced — and
+//     it's a warning: a directory can appear later (a repo you haven't
+//     cloned yet), and saving a root that isn't there yet costs
+//     nothing, since resolution simply finds no candidate under it.
+function initLocalRootControls() {
+    const box = document.getElementById('local-roots-text');
+    const saveBtn = document.getElementById('local-roots-save');
+    const status = document.getElementById('local-roots-status');
+    const problems = document.getElementById('local-roots-problems');
+    const fileAccess = document.getElementById('local-roots-file-access');
+    if (!box || !saveBtn || !status || !problems || !fileAccess)
+        return;
+    let savedText = '';
+    let checkTimer;
+    // Existence results, keyed by canonical root URL. Cached for the
+    // page's lifetime so re-validating on each keystroke doesn't re-probe
+    // every unchanged line.
+    const exists = new Map();
+    void chrome.storage.local.get(LOCAL_ROOTS_KEY).then((got) => {
+        savedText = textFromRoots(readRootsSetting(got[LOCAL_ROOTS_KEY]));
+        // Don't overwrite a user who started typing before the read landed
+        // — the same reasoning as the cross-tab guard below, for the much
+        // narrower window between page load and hydration.
+        if (!box.value)
+            box.value = savedText;
+        void validate();
+    });
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[LOCAL_ROOTS_KEY];
+        if (!change)
+            return;
+        const next = textFromRoots(readRootsSetting(change.newValue));
+        if (next === savedText)
+            return;
+        savedText = next;
+        // Don't clobber an edit being typed in THIS box with a write from
+        // another options tab. Focus is the signal: a box the user is in
+        // keeps its text and shows "Unsaved changes" against the new saved
+        // value, so nothing is lost silently either way.
+        if (box.value !== next && !box.matches(':focus'))
+            box.value = next;
+        void validate();
+    });
+    box.addEventListener('input', () => {
+        renderProblems();
+        if (checkTimer !== undefined)
+            clearTimeout(checkTimer);
+        checkTimer = setTimeout(() => void validate(), 400);
+    });
+    saveBtn.addEventListener('click', () => void onSave());
+    async function onSave() {
+        const roots = rootsFromText(box.value);
+        // Save is disabled while this is null, so reaching it means a
+        // keystroke landed between the last render and the click.
+        if (!roots)
+            return;
+        // Write back the canonical form: the stored array IS the setting,
+        // and showing anything else would leave the box disagreeing with
+        // what's actually searched.
+        savedText = textFromRoots(roots);
+        box.value = savedText;
+        saveBtn.disabled = true;
+        try {
+            await writeSetting(LOCAL_ROOTS_KEY, roots);
+            // The roots only change what the NEXT refresh resolves to, so the
+            // refresh is part of the save — same reasoning as the collection
+            // dialog's local-overrides option, which refreshes its collection
+            // on save. Without it a newly-added root would
+            // appear to do nothing until something else happened to touch a
+            // collection.
+            setStatus('Saved, refreshing scripts', '');
+            await refreshLocalCollections();
+        }
+        finally {
+            saveBtn.disabled = false;
+        }
+        await validate();
+    }
+    // Refresh only the collections a root could possibly affect. http(s)
+    // collections and the web / GitHub containers resolve everything over
+    // the network, so refreshing them would be cost with no possible
+    // change.
+    async function refreshLocalCollections() {
+        try {
+            const collections = await getCollections();
+            for (const collection of collections) {
+                if (!collectionSupportsLocalFiles(collection.path))
+                    continue;
+                await updateCollection(collection.id, 'manual');
+            }
+        }
+        catch {
+            // A refresh that fails is not a failed save: the setting is
+            // written, and every collection re-resolves on its own next
+            // refresh. Per-collection failures already surface on the
+            // collections page.
+        }
+    }
+    // Probe every well-formed root that hasn't been probed yet, then
+    // repaint. Cheap after the first pass — `exists` short-circuits.
+    async function validate() {
+        renderProblems();
+        const entries = parseLocalRootLines(box.value);
+        // A malformed line already blocks Save, so there is nothing to be
+        // learned from probing the others yet — and the format complaint is
+        // the one the user has to act on first.
+        if (entries.some((e) => e.error))
+            return;
+        const unknown = entries
+            .flatMap((e) => (e.url ? [e.url] : []))
+            .filter((url) => !exists.has(url));
+        // Before the early return, or a banner raised by an earlier pass
+        // outlives the condition that raised it — deleting the offending
+        // line would leave it on screen with nothing left to probe.
+        if (unknown.length === 0) {
+            if (await isFileSchemeAccessAllowed())
+                fileAccess.replaceChildren();
+            return;
+        }
+        // With "Allow access to file URLs" off, every read fails the same
+        // way a missing directory does — so say which it is, using the
+        // shared banner rather than a second copy of its wording. Reload is
+        // the right retry here: `exists` is cached for the page's life.
+        if (!(await isFileSchemeAccessAllowed())) {
+            if (!fileAccess.firstChild)
+                fileAccess.appendChild(renderFileAccessBanner());
+            return;
+        }
+        fileAccess.replaceChildren();
+        await Promise.all(unknown.map(async (url) => {
+            exists.set(url, await isReadableDir(url));
+        }));
+        renderProblems();
+    }
+    function renderProblems() {
+        const entries = parseLocalRootLines(box.value);
+        problems.replaceChildren();
+        for (const entry of entries) {
+            const message = problemFor(entry);
+            if (!message)
+                continue;
+            const li = document.createElement('li');
+            li.textContent = message;
+            problems.appendChild(li);
+        }
+        renderStatus(entries);
+    }
+    function problemFor(entry) {
+        if (entry.error)
+            return `Line ${entry.lineNumber}: ${entry.error}`;
+        if (entry.url && exists.get(entry.url) === false) {
+            return `Line ${entry.lineNumber}: No directory found at ${entry.text}`;
+        }
+        return null;
+    }
+    function renderStatus(entries) {
+        const bad = entries.filter((e) => e.error).length;
+        // A format error is the one thing that blocks a save. The listed
+        // problem already names the line and the fix, and the button is
+        // visibly disabled, so the status line stays out of it rather than
+        // restating both.
+        saveBtn.disabled = bad > 0;
+        if (bad > 0) {
+            setStatus('', '');
+            return;
+        }
+        if (textFromRoots(rootsFromText(box.value) ?? []) !== savedText) {
+            setStatus('Unsaved changes', '');
+            return;
+        }
+        if (entries.length === 0) {
+            setStatus('No directories configured, so only each script\'s own folder and its collection\'s are searched', '');
+            return;
+        }
+        setStatus(`Searching ${entries.length} ${entries.length === 1 ? 'directory' : 'directories'} after each script's own folder and its collection's`, 'ok');
+    }
+    function setStatus(text, cls) {
+        status.textContent = text;
+        status.classList.remove('ok', 'err');
+        if (cls)
+            status.classList.add(cls);
+    }
+}
+// True when the URL names a readable directory. Chrome serves a
+// directory listing for a `file://` URL ending in `/`, and fails for a
+// plain file or a missing path — so the trailing slash the canonical
+// root form already carries is what makes this a directory test.
+async function isReadableDir(rootUrl) {
+    try {
+        await fetchFileUrlText(rootUrl);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function initGithubTokenControls() {
+    const input = document.getElementById('github-token');
+    const revealBtn = document.getElementById('github-token-reveal');
+    const saveBtn = document.getElementById('github-token-save');
+    const clearBtn = document.getElementById('github-token-clear');
+    const status = document.getElementById('github-token-status');
+    if (!input || !revealBtn || !saveBtn || !clearBtn || !status)
+        return;
+    // Hydrate from storage. We deliberately do NOT pre-fill the input
+    // when a token already exists — instead show a "token is set" status
+    // and leave the field empty, so a shoulder-surfer (or screenshot)
+    // doesn't reveal the value. Saving an empty input is a no-op; Clear
+    // is the only way to remove a stored token.
+    let storedToken = '';
+    void chrome.storage.local.get(GITHUB_AUTH_TOKEN_KEY).then((got) => {
+        const raw = got[GITHUB_AUTH_TOKEN_KEY];
+        storedToken = typeof raw === 'string' ? raw : '';
+        renderStatus();
+    });
+    chrome.storage.onChanged.addListener((changes, areaName) => {
+        if (areaName !== 'local')
+            return;
+        const change = changes[GITHUB_AUTH_TOKEN_KEY];
+        if (!change)
+            return;
+        storedToken = typeof change.newValue === 'string' ? change.newValue : '';
+        renderStatus();
+    });
+    revealBtn.addEventListener('click', () => {
+        const visible = input.type === 'text';
+        input.type = visible ? 'password' : 'text';
+        revealBtn.textContent = visible ? 'Show' : 'Hide';
+    });
+    saveBtn.addEventListener('click', () => {
+        const next = input.value.trim();
+        if (!next) {
+            setStatus('Enter a token, or use Clear to remove the saved one.', 'err');
+            return;
+        }
+        void writeSetting(GITHUB_AUTH_TOKEN_KEY, next).then(() => {
+            input.value = '';
+            input.type = 'password';
+            revealBtn.textContent = 'Show';
+            // Reuse the same "A token is saved (ends in …XXXX)" message
+            // renderStatus produces on a hydrated page. Don't show a transient
+            // "Token saved." line that vanishes — the persistent message
+            // makes it obvious there IS a token, and which one.
+            // (The storage.onChanged listener will also fire renderStatus,
+            // but the explicit call here keeps the UI immediate.)
+            storedToken = next;
+            renderStatus();
+        }, (err) => setStatus(`Could not save the token: ${describeError(err)}`, 'err'));
+    });
+    clearBtn.addEventListener('click', () => {
+        void writeSetting(GITHUB_AUTH_TOKEN_KEY, null).then(() => {
+            input.value = '';
+            // Mirror Save's input reset so Show→Clear doesn't leave the
+            // (now empty) field stuck in text mode with a "Hide" button.
+            input.type = 'password';
+            revealBtn.textContent = 'Show';
+            storedToken = '';
+            renderStatus();
+        }, (err) => setStatus(`Could not remove the token: ${describeError(err)}`, 'err'));
+    });
+    // Allow Enter inside the input to save, so users don't have to mouse
+    // over to the Save button.
+    input.addEventListener('keydown', (ev) => {
+        if (ev.key === 'Enter') {
+            ev.preventDefault();
+            saveBtn.click();
+        }
+    });
+    function renderStatus() {
+        if (storedToken) {
+            setStatus(`A token is saved (ends in …${storedToken.slice(-4)}). Saved tokens are never re-displayed; paste a new one to replace it.`, 'ok');
+        }
+        else {
+            setStatus('No token saved. SourceMonkey will use unauthenticated GitHub API calls (60/hr).', '');
+        }
+    }
+    function setStatus(text, cls) {
+        status.textContent = text;
+        status.classList.remove('ok', 'err');
+        if (cls)
+            status.classList.add(cls);
+    }
+}

package/dist/extension/page-heading.js

@@ -0,0 +1,170 @@
+// The viewer's heading: the shared vocabulary for it, the DOM that
+// paints its leading terms, and the early paint that puts a name in the
+// header bar before the rest of the page arrives.
+//
+// Why this is its own module, loaded from `userscript.html` ahead of
+// `userscript.js`:
+//   - `userscript.js` is a large module graph that used to sit behind
+//     blocking Prism scripts. The browser's first paint landed well
+//     before any of it evaluated, so the header bar drew with an icon
+//     and nothing else and filled in a beat later — the one thing on
+//     the page that is supposed to say what the page IS.
+//   - This module has NO static imports, which is the point: a module
+//     does not evaluate until everything it imports has been fetched,
+//     so even one small import would put its first line behind another
+//     round trip and back after the first paint. Everything the early
+//     paint needs beyond the prefix is pulled in with a dynamic
+//     `import()`, after the prefix is already on screen.
+//   - `userscript.ts` imports it as well. A module runs once, so the
+//     early paint happens exactly once and the constants below have a
+//     single home rather than a copy per entry point.
+//
+// `import type` is fine here — it is erased, so it costs no fetch.
+// What every heading's leading terms are joined by — the same `|` the
+// tab titles use (architecture.md, "Page names").
+export const HEADING_SEPARATOR = ' | ';
+// The product run, which every heading opens with and which the header
+// bar paints in the brand colour.
+const BRAND_PREFIX = `SourceMonkey${HEADING_SEPARATOR}`;
+export const INSTALLED_HEADING = BRAND_PREFIX;
+// The verb is a page name beside the product's, not a word governing
+// the script's — so it takes its own separator rather than running
+// straight into the favicon and the name.
+export const PREVIEW_HEADING = `${BRAND_PREFIX}Install${HEADING_SEPARATOR}`;
+// The installed title takes no prefix — a tab strip has little room,
+// and the script's own name is what the reader is scanning for. The
+// preview spends that room: "which of my tabs is asking to install
+// something" is the question a preview tab has to answer.
+export const INSTALLED_TITLE = '';
+export const PREVIEW_TITLE = 'Install script: ';
+// Stands in for the label when there is no script to name.
+export const MISSING_LABEL = 'Not available';
+// Same spelling as script-store's own (which is module-private), and as
+// the copies in background.ts / injector.ts / script-log-id.ts. Reading
+// one row is all this module does; importing the store to get the key
+// would pull its whole graph in and undo the point of being early.
+const SCRIPT_PREFIX = 'script:';
+// The heading's leading run of product text. Shared with `showMissing`,
+// which draws a heading with no script in it — the class, the constant
+// and the ordering must not be written twice and drift.
+//
+// The product name and every separator wear `.brand` and take the
+// header bar's colour (src/styles.css); the page names between them
+// read in the heading's own. So the preview's heading is a brown
+// "SourceMonkey | … | " skeleton with a dark "Install" set into it,
+// which is the same shape the other pages' headings have — theirs just
+// have no middle term.
+export function headingPrefixEl(prefix) {
+    const frag = document.createDocumentFragment();
+    // A prefix always ends in a separator, so the last part is empty and
+    // contributes nothing but its own `|`.
+    const [product, ...rest] = prefix.split(HEADING_SEPARATOR);
+    frag.appendChild(brandHomeLink(product));
+    for (const part of rest) {
+        frag.appendChild(prefixSpan(HEADING_SEPARATOR, true));
+        if (part)
+            frag.appendChild(prefixSpan(part, false));
+    }
+    return frag;
+}
+// The product name, as a link home to the collections page — the same
+// element `userscript.html` ships in its markup, so repainting the
+// heading doesn't change what the bar's first term is.
+//
+// A plain anchor with a real href, and no listener of its own: the
+// click is caught by the page's delegated handler
+// (`installHomeLinkHandler`, src/extension/page-links.ts), which is what makes it
+// open the NAMED collections tab. Importing that here would put this
+// module's first line behind another fetch and undo the early paint, so
+// the href + `target` are also the behaviour before it runs.
+function brandHomeLink(text) {
+    const el = document.createElement('a');
+    el.className = 'heading-prefix brand page-home';
+    el.href = 'collections.html';
+    el.target = '_blank';
+    el.rel = 'noopener';
+    el.title = 'Open the collections page';
+    el.textContent = text;
+    return el;
+}
+function prefixSpan(text, brand) {
+    const el = document.createElement('span');
+    el.className = brand ? 'heading-prefix brand' : 'heading-prefix';
+    el.textContent = text;
+    return el;
+}
+// `<label> | SourceMonkey`, with the preview's own prefix in front so a
+// tab strip full of viewer tabs says which is an install question and
+// which is a script already installed.
+export function setPageTitle(prefix, label) {
+    document.title = `${prefix}${label} | SourceMonkey`;
+}
+// The favicon's fixed-width slot, empty. `renderHeading` fills it with
+// the real thing later; drawing it now is what keeps the name from
+// shifting sideways when that lands.
+function emptyIconSlot() {
+    const el = document.createElement('span');
+    el.className = 'site-icon';
+    return el;
+}
+// Whether the full page has drawn this heading yet. The early paint is
+// a placeholder for exactly as long as that hasn't happened, and it must
+// never land on top of the real thing — `userscript.ts` calls
+// `notePainted` from every path that writes the heading, and its storage
+// reads can finish either side of ours.
+//
+// A flag rather than an inspection of the heading's own contents: the
+// markup's brand run and a finished heading are both just spans and
+// text, so any test on the DOM comes down to matching bytes that the
+// markup is free to change without failing anything.
+let painted = false;
+export function notePainted() {
+    painted = true;
+}
+// ---------- The early paint ----------
+// Everything above is also used by `userscript.ts`; the rest of this
+// module is the side effect that makes loading it early worth doing.
+//
+// The prefix goes on synchronously, before any `await` or `import()`,
+// because it is the half we can know without reading anything: which of
+// the two pages this is. Only the script's name needs a storage read.
+const headingEl = document.getElementById('filename');
+const searchParams = new URLSearchParams(location.search);
+const earlyScriptId = searchParams.get('script');
+if (headingEl) {
+    // The install page's own name for itself. The installed page's prefix
+    // is already in the markup, but it is repainted here anyway so both
+    // modes leave the heading in the same shape — prefix, then the
+    // favicon's fixed-width slot, so the name doesn't shift sideways when
+    // the real favicon lands.
+    const prefix = earlyScriptId ? INSTALLED_HEADING : PREVIEW_HEADING;
+    if (earlyScriptId || searchParams.get('preview')) {
+        headingEl.replaceChildren(headingPrefixEl(prefix), emptyIconSlot());
+    }
+}
+void paintEarlyName();
+// The script's name, which needs the one `script:<id>` row plus the
+// helpers that turn it into a label. A preview has no name to paint:
+// its script's `@name` is inside a file that hasn't been fetched, and
+// naming it from the URL would only move the flash — the location it
+// would show is usually not what the finished heading says.
+async function paintEarlyName() {
+    if (!headingEl || !earlyScriptId)
+        return;
+    const key = `${SCRIPT_PREFIX}${earlyScriptId}`;
+    const [got, display] = await Promise.all([
+        chrome.storage.local.get(key),
+        import('../script-display.js'),
+    ]);
+    const script = got[key];
+    if (!script)
+        return;
+    // Bail if the full page beat us to it while we were reading.
+    if (painted)
+        return;
+    const label = display.scriptLabel(script.header, script.relativePath);
+    // The same slash-aware wrap `renderHeading` uses, so the finished
+    // heading breaks its lines exactly where this one did.
+    display.appendWithSlashBreaks(headingEl, label);
+    setPageTitle(INSTALLED_TITLE, label);
+}