sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/copy-button.js

@@ -0,0 +1,63 @@
+// The small square "copy this to the clipboard" button that sits
+// beside a path.
+//
+// Shared because it appears in more than one place — the viewer's
+// Location row and each entry in its Local overrides row, and the
+// delete dialog's file path — and they must not drift into different
+// icons, different flash durations, or different failure behavior.
+// Its CSS (`.copy-btn`) is in styles.css for the same reason.
+//
+// The text is supplied as a callback rather than a string: a button
+// can outlive the render that made it (the Location row's is one
+// long-lived element moved between renders, so an in-flight "Copied"
+// flash survives a repaint), and it must copy what the row says NOW,
+// not what it said when the button was built.
+// The copy / check glyphs. Both live in the shared sprite
+// (src/glyph-sprite.svg) and are referenced here rather than inlined,
+// so every icon in the extension is defined in one place. Safe to
+// embed via innerHTML: no interpolation, and the strings ship as part
+// of the extension bundle.
+//
+// Both are always in the button; `.copied` on the button swaps which
+// one is displayed, so the flash needs no re-render.
+const COPY_ICON_SVG = '<svg class="copy-icon" viewBox="0 0 24 24" aria-hidden="true"><use href="#sm-copy"/></svg>';
+const CHECK_ICON_SVG = '<svg class="check-icon" viewBox="0 0 24 24" aria-hidden="true"><use href="#sm-check"/></svg>';
+// How long the checkmark stays up after a successful copy.
+const COPIED_FLASH_MS = 1200;
+export function makeCopyButton(options) {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'copy-btn';
+    btn.title = options.label;
+    btn.setAttribute('aria-label', options.label);
+    btn.innerHTML = COPY_ICON_SVG + CHECK_ICON_SVG;
+    // Per-button timer, so two buttons flashing at once don't cancel each
+    // other, and a rapid double-click on one leaves no stuck checkmark:
+    // each click clears its own prior reset and schedules a new one.
+    let resetTimer = null;
+    btn.addEventListener('click', () => {
+        void (async () => {
+            const text = options.text();
+            if (!text)
+                return;
+            try {
+                await navigator.clipboard.writeText(text);
+            }
+            catch {
+                // The write can be rejected (permission denied, or no user
+                // gesture credited). The text is selectable on the page, so
+                // there is nothing to fall back to and nothing worth saying.
+                return;
+            }
+            // `.copied` swaps the visible icon to a checkmark via CSS.
+            btn.classList.add('copied');
+            if (resetTimer !== null)
+                clearTimeout(resetTimer);
+            resetTimer = setTimeout(() => {
+                btn.classList.remove('copied');
+                resetTimer = null;
+            }, COPIED_FLASH_MS);
+        })();
+    });
+    return btn;
+}

package/dist/extension/copy-dialog.js

@@ -0,0 +1,502 @@
+// The "make a local copy of this script" dialog, opened from the Local
+// copy button on the viewer's Collection row.
+//
+// It owns the whole action, the way the move dialog owns Move: the
+// file name and header fields, the refusals, the write through
+// `makeLocalCopy`, and any failure in its own error slot — so the
+// caller only ever hears about a copy that landed.
+//
+// See docs/local-copy.md.
+import { checkExistingFiles, COPY_OVER_ITSELF, defaultCopyName, dependencyFiles, downloadsCopiesDir, DOWNLOADS_COPIES_NAME, DOWNLOADS_COPIES_SUBDIR, findDownloadsCollection, isCopyOfItself, makeLocalCopy, planFiles, readDownloadsCopiesSetting, validateCopyName, } from './local-copy.js';
+import { effectiveDisplayName } from './collection-display.js';
+import { isFileSchemeAccessAllowed, renderFileAccessBanner } from './file-access.js';
+import { formatBytes } from '../script-display.js';
+import { collectionUsesLocalFiles, describeError, getCollections, } from './script-store.js';
+import { getValue } from '../userscript-header.js';
+import { localEditVersion } from '../version-compare.js';
+import { dlog } from '../debug-log.js';
+let elements = null;
+// One at a time, claimed synchronously — same reason as the other
+// dialogs' guards: two overlapping opens would leave the first caller's
+// promise unsettled and `showModal` throwing on the second.
+let dialogInFlight = false;
+function el(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className)
+        node.className = className;
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+// A one-line box that grows with its content, to the cap the CSS sets
+// (four lines) and then scrolls. A `<textarea>` rather than an
+// `<input>` because the value can be a sentence, but it still holds ONE
+// line of a metadata block — see `sanitizeOneLine`.
+function growingInput(id) {
+    const box = document.createElement('textarea');
+    box.id = id;
+    box.rows = 1;
+    box.spellcheck = false;
+    return box;
+}
+// Fit the box to its content. Height is cleared first so shrinking
+// works: `scrollHeight` never reports less than the current height.
+function autoGrow(box) {
+    box.style.height = 'auto';
+    box.style.height = `${box.scrollHeight}px`;
+}
+// A metadata value is one line by definition, so a pasted newline
+// becomes a space rather than a broken header. Same length, so the
+// caret doesn't move.
+function sanitizeOneLine(box) {
+    if (box.value.includes('\n') || box.value.includes('\r')) {
+        box.value = box.value.replace(/[\r\n]/g, ' ');
+    }
+}
+function textInput(id) {
+    const input = el('input');
+    input.type = 'text';
+    input.id = id;
+    input.spellcheck = false;
+    input.autocomplete = 'off';
+    return input;
+}
+function buildDialog() {
+    const dialog = el('dialog', 'sm-dialog copy-dialog');
+    dialog.appendChild(el('h2', 'dlg-title', 'Make a local copy of this script'));
+    // The file-access banner, when the toggle is off: a copy that can be
+    // written but never read back would register as a broken script.
+    const banner = el('div', 'dlg-banner');
+    dialog.appendChild(banner);
+    const body = el('div', 'dlg-body');
+    // One tooltip per row, on the label AND the control: the label is
+    // what a reader points at to ask "what is this?", and the control is
+    // where the pointer already is when they wonder.
+    const row = (label, control, tooltip, note) => {
+        const cell = el('span', 'dlg-label', label);
+        // A second line under the label, for what the field accepts that
+        // its name doesn't say.
+        if (note)
+            cell.appendChild(el('span', 'dlg-label-note', note));
+        cell.title = tooltip;
+        control.title = tooltip;
+        body.appendChild(cell);
+        body.appendChild(control);
+    };
+    const target = el('span', 'dlg-static');
+    target.id = 'copy-target';
+    row('Target collection', target, 'Copy to this collection. It uses a directory under Chrome\u2019s Downloads directory.');
+    const fileName = textInput('copy-file-name');
+    row('Filename', fileName, 'Copy script here, relative to the collection\u2019s directory. '
+        + 'The relative path can include a subdirectory.', '(with subdir)');
+    const depsWrap = el('div', 'dlg-deps');
+    const depsLabel = el('label', 'dlg-check');
+    const deps = el('input');
+    deps.type = 'checkbox';
+    deps.id = 'copy-deps';
+    const depsText = el('span');
+    depsLabel.append(deps, depsText);
+    depsWrap.appendChild(depsLabel);
+    const depsHint = el('div', 'dlg-hint');
+    depsWrap.appendChild(depsHint);
+    const depsList = el('ul', 'dlg-deps-list');
+    depsWrap.appendChild(depsList);
+    // The row's own tooltip is about the paths it lists; the checkbox
+    // decides whether anything is written there, which is a different
+    // question, so it carries its own.
+    row('Dependencies', depsWrap, 'Local paths for @require and @resource files this script loads. '
+        + 'Files at these local paths will be used if they exist.');
+    depsLabel.title = 'Also save local copies of @require and @resource files if checked.';
+    // The header fields are a group of their own: everything above says
+    // where the copy goes, everything below is what will differ from the
+    // script it is copied from.
+    const heading = el('div', 'dlg-section', 'Updated headers in downloaded script');
+    body.appendChild(heading);
+    const name = el('span', 'dlg-static');
+    name.id = 'copy-name';
+    row('Name', name, 'The @name for the copied script. Unchanged, to keep a link to the source script.');
+    // `<original> → [new]`, so the edit is read against what it replaces
+    // rather than having to be remembered.
+    const versionWrap = el('div', 'dlg-arrow');
+    const versionWas = el('span', 'dlg-was');
+    versionWas.id = 'copy-version-was';
+    // Its own, overriding the row's: this half is the version being
+    // copied FROM, where the box beside it is the one being written.
+    versionWas.title = 'The @version of the source script';
+    const version = textInput('copy-version');
+    versionWrap.append(versionWas, el('span', 'dlg-arrow-mark', '\u2192'), version);
+    row('Version', versionWrap, 'The @version for the source and copied script. '
+        + 'The copied script gets a "-local" suffix by default.');
+    const description = growingInput('copy-description');
+    row('Description', description, 'The @description for the copied script');
+    dialog.appendChild(body);
+    // In the shared error row, so the text lines up with the form's
+    // padding rather than the dialog's edge.
+    const errorRow = el('div', 'dlg-error-row');
+    const error = el('p', 'dlg-error');
+    error.setAttribute('role', 'alert');
+    errorRow.appendChild(error);
+    dialog.appendChild(errorRow);
+    const actions = el('div', 'dlg-actions');
+    const cancel = el('button', undefined, 'Cancel');
+    cancel.type = 'button';
+    const ok = el('button', 'primary', 'Copy');
+    ok.type = 'button';
+    ok.id = 'copy-confirm-btn';
+    // Enter in the description would insert a line the header can't hold,
+    // and it is what a one-line field is expected to submit on. Wired
+    // here rather than at the field, so it can name the button directly.
+    description.addEventListener('keydown', (ev) => {
+        if (ev.key !== 'Enter')
+            return;
+        ev.preventDefault();
+        ok.click();
+    });
+    actions.append(cancel, ok);
+    dialog.appendChild(actions);
+    document.body.appendChild(dialog);
+    return {
+        dialog, banner, target, fileName, deps, depsLabel, depsText, depsList, depsHint,
+        name, versionWas, version, description, error, cancel, ok,
+    };
+}
+// Open the dialog and resolve with the new copy, or null when it was
+// dismissed or nothing was written.
+export function openCopyDialog(request) {
+    if (!elements)
+        elements = buildDialog();
+    const ui = elements;
+    if (dialogInFlight)
+        return Promise.resolve(null);
+    dialogInFlight = true;
+    return new Promise((resolve) => {
+        try {
+            runDialog(ui, request, (result) => {
+                dialogInFlight = false;
+                resolve(result);
+            });
+        }
+        catch (err) {
+            dialogInFlight = false;
+            resolve(null);
+            dlog(`[SourceMonkey] copy dialog failed to open: ${describeError(err)}`);
+        }
+    });
+}
+async function readOpenContext() {
+    const [setting, collections, fileAccess] = await Promise.all([
+        readDownloadsCopiesSetting(),
+        getCollections(),
+        isFileSchemeAccessAllowed(),
+    ]);
+    return {
+        copiesDir: setting ? downloadsCopiesDir(setting.downloadsDir) : null,
+        collection: findDownloadsCollection(setting, collections),
+        fileAccess,
+    };
+}
+function runDialog(ui, request, resolve) {
+    const { script } = request;
+    let settled = false;
+    // A submit is in flight. Esc is refused for its duration: closing
+    // would resolve the caller `null` while the files are still landing,
+    // so the caller would skip the exclusive-enable sweep and the
+    // navigation the new copy needs.
+    let submitting = false;
+    // The open-time reads have landed. Until then nothing can be checked
+    // against the disk, so the confirm stays off.
+    let context = null;
+    // The last COMPLETED disk check, with the file name it was made for.
+    // Everything about replacing — the warning line, the marks in the
+    // dependency list, the confirm's wording — is drawn from this and
+    // never from a half-known state: an edit leaves the last answer on
+    // screen and disables the confirm until the new one lands, so the
+    // marks and the button don't blink off and back on with every
+    // keystroke. `null` until the first check.
+    let checked = null;
+    // A check is pending or in flight, so what is on screen is the
+    // PREVIOUS answer. Only the confirm reacts.
+    let checking = false;
+    let checkTimer;
+    let checkSeq = 0;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        if (checkTimer !== undefined)
+            clearTimeout(checkTimer);
+        if (ui.dialog.open)
+            ui.dialog.close();
+        resolve(result);
+    };
+    // ----- Fill the form from the script -----
+    const header = script.header;
+    const originalVersion = header ? getValue(header, 'version') ?? '' : '';
+    ui.name.textContent = (header && getValue(header, 'name')) || '(no @name)';
+    // `<none>` rather than an empty gap: the arrow needs a left-hand
+    // side, and "the script declares no version" is what it says.
+    ui.versionWas.textContent = originalVersion || '<none>';
+    ui.version.value = originalVersion ? localEditVersion(originalVersion) : '';
+    ui.version.placeholder = originalVersion ? '' : 'none';
+    ui.description.value = header ? getValue(header, 'description') ?? '' : '';
+    ui.description.placeholder = ui.description.value ? '' : 'none';
+    ui.fileName.value = defaultCopyName(script);
+    const deps = dependencyFiles(script);
+    // Off to begin with; `paintDependencies` runs again when the
+    // open-time reads land and must not undo a tick made in between.
+    ui.deps.checked = false;
+    paintDependencies(ui, deps, null);
+    ui.target.replaceChildren();
+    ui.target.appendChild(el('span', 'dlg-target-name', DOWNLOADS_COPIES_NAME));
+    const targetHint = el('span', 'dlg-hint', ` (a ${DOWNLOADS_COPIES_SUBDIR} directory under Chrome's Downloads directory)`);
+    ui.target.appendChild(targetHint);
+    ui.banner.replaceChildren();
+    // ----- Validation -----
+    const currentPlan = () => ({
+        fileName: ui.fileName.value.trim(),
+        version: ui.version.value,
+        description: ui.description.value,
+        includeDependencies: ui.deps.checked && !ui.deps.disabled,
+    });
+    // What the last completed check says the copy would overwrite. The
+    // checkbox is read live rather than checked for: the check covers
+    // every file the plan COULD write, so ticking it changes what will
+    // be replaced without needing another listing.
+    const replaceState = () => {
+        if (!checked)
+            return { scriptExists: false, depsExisting: 0 };
+        const copyingDeps = ui.deps.checked && !ui.deps.disabled;
+        return {
+            scriptExists: checked.existing.includes(checked.fileName),
+            depsExisting: copyingDeps
+                ? checked.existing.filter((p) => p !== checked.fileName).length
+                : 0,
+        };
+    };
+    // Paint the error slot and the confirm button from the current state.
+    // `report` is what the last attempt said, which outranks the live
+    // validation until the user changes something.
+    let report = null;
+    const sync = () => {
+        const nameError = validateCopyName(ui.fileName.value)
+            ?? (context?.copiesDir && isCopyOfItself(script, context.copiesDir, ui.fileName.value)
+                ? COPY_OVER_ITSELF
+                : null);
+        const message = report ?? nameError;
+        const blocked = !context || !context.fileAccess || nameError !== null || report !== null;
+        const { scriptExists, depsExisting } = replaceState();
+        const willReplace = scriptExists || depsExisting > 0;
+        // Where the dependencies WOULD go, when they aren't going: still
+        // worth reading, but not a description of what Copy is about to
+        // do, so it and the list it heads are dimmed.
+        const copyingDeps = ui.deps.checked && !ui.deps.disabled;
+        ui.depsHint.classList.toggle('dimmed', !copyingDeps);
+        ui.depsList.classList.toggle('dimmed', !copyingDeps);
+        ui.error.textContent = message ?? replaceWarning(scriptExists, depsExisting);
+        ui.error.classList.toggle('warn', !message && willReplace);
+        // Paths and marks both from the last completed check, so a name
+        // being typed can't pair a new path with the old answer about it.
+        paintDependencyRows(ui, checked?.existing ?? [], checked?.fileName ?? '');
+        ui.fileName.classList.toggle('invalid', nameError !== null);
+        // A pending check is the one thing that disables the confirm
+        // without changing anything else on screen: the answer it would
+        // act on is about to be replaced, and it may well come back the
+        // same.
+        ui.ok.disabled = blocked || submitting || checking;
+        ui.ok.textContent = willReplace ? 'Replace' : 'Copy';
+    };
+    // The disk check: which of the files this plan would write are
+    // already there. Debounced behind typing, and sequenced so a slow
+    // listing can't overwrite the answer for a newer name.
+    const scheduleCheck = () => {
+        report = null;
+        checking = true;
+        // Bumped HERE, not only in `runCheck`: a check already awaiting a
+        // listing must not be allowed to land its answer for the name the
+        // user has just moved off. Without this it would, then clear
+        // `checking` and re-enable the confirm — so a click in the 250ms
+        // before this edit's own check ran would write the new name with
+        // the old name's answer about what is already there.
+        checkSeq++;
+        if (checkTimer !== undefined)
+            clearTimeout(checkTimer);
+        checkTimer = setTimeout(() => void runCheck(), 250);
+        sync();
+    };
+    const runCheck = async () => {
+        checkTimer = undefined;
+        const seq = ++checkSeq;
+        const fileName = ui.fileName.value.trim();
+        if (!context?.copiesDir
+            || validateCopyName(ui.fileName.value) !== null
+            || isCopyOfItself(script, context.copiesDir, ui.fileName.value)) {
+            // Nothing to check against — and the name is what the confirm is
+            // already refusing, so the previous answer stays on screen rather
+            // than being cleared to a state nobody can act on.
+            checking = false;
+            sync();
+            return;
+        }
+        // Every file the plan COULD write, dependencies included, so the
+        // list's marks don't depend on the checkbox.
+        const files = planFiles(script, { ...currentPlan(), includeDependencies: true });
+        try {
+            const found = await checkExistingFiles(context.copiesDir, files);
+            if (seq !== checkSeq || settled)
+                return;
+            checked = { fileName, existing: found.existing };
+        }
+        catch (err) {
+            if (seq !== checkSeq || settled)
+                return;
+            dlog(`[SourceMonkey] copy dialog could not check existing files: ${describeError(err)}`);
+        }
+        checking = false;
+        sync();
+    };
+    ui.fileName.oninput = scheduleCheck;
+    // No re-check: the check covers every file the plan COULD write, so
+    // the box only changes which of them count. `report` is cleared like
+    // any other edit — otherwise a failed copy's message would sit there
+    // blocking the confirm until some other field was touched.
+    ui.deps.onchange = () => { report = null; sync(); };
+    ui.version.oninput = () => { report = null; sync(); };
+    ui.description.oninput = () => {
+        sanitizeOneLine(ui.description);
+        autoGrow(ui.description);
+        report = null;
+        sync();
+    };
+    // Replaced on every open, so stale closures can't fire.
+    ui.cancel.onclick = () => finish(null);
+    ui.dialog.onclose = () => finish(null);
+    ui.dialog.oncancel = (event) => {
+        if (submitting)
+            event.preventDefault();
+    };
+    ui.ok.onclick = () => void submit();
+    const submit = async () => {
+        if (!context)
+            return;
+        submitting = true;
+        sync();
+        ui.cancel.disabled = true;
+        const spinner = el('span', 'busy-spinner');
+        ui.ok.after(spinner);
+        try {
+            const result = await makeLocalCopy({
+                script,
+                plan: currentPlan(),
+                overwrite: (() => {
+                    const { scriptExists, depsExisting } = replaceState();
+                    return scriptExists || depsExisting > 0;
+                })(),
+            });
+            finish(result);
+        }
+        catch (err) {
+            report = describeError(err);
+        }
+        finally {
+            submitting = false;
+            spinner.remove();
+            ui.cancel.disabled = false;
+            sync();
+        }
+    };
+    report = null;
+    checking = true;
+    sync();
+    ui.dialog.showModal();
+    // After `showModal`: a closed dialog is `display: none`, where a box
+    // has no scroll height to measure.
+    autoGrow(ui.description);
+    ui.fileName.focus();
+    ui.fileName.setSelectionRange(0, Math.max(0, ui.fileName.value.length - '.user.js'.length));
+    // ----- The open-time reads, after the dialog is on screen -----
+    void readOpenContext().then((ctx) => {
+        if (settled)
+            return;
+        context = ctx;
+        if (ctx.copiesDir) {
+            targetHint.textContent = ` (${ctx.copiesDir})`;
+            if (ctx.collection) {
+                ui.target.firstChild.textContent = effectiveDisplayName(ctx.collection);
+            }
+        }
+        paintDependencies(ui, deps, ctx.collection);
+        if (!ctx.fileAccess) {
+            ui.banner.replaceChildren(renderFileAccessBanner('then open this dialog again'));
+        }
+        void runCheck();
+    }, (err) => {
+        if (settled)
+            return;
+        report = `Could not read the collections: ${describeError(err)}`;
+        sync();
+    });
+}
+// What Replace would overwrite, as the line in the error slot. Which
+// files: a dependency that is already there is marked in the list under
+// the checkbox, which already names every file, so the line names
+// none — and it counts dependencies only when they are being copied.
+function replaceWarning(scriptExists, depsExisting) {
+    if (scriptExists && depsExisting > 0) {
+        return 'Target script file and dependency files already exist and will be replaced';
+    }
+    if (scriptExists)
+        return 'Target script file already exists and will be replaced';
+    if (depsExisting === 1)
+        return 'Target dependency file already exists and will be replaced';
+    if (depsExisting > 1)
+        return 'Target dependency files already exist and will be replaced';
+    return '';
+}
+function paintDependencyRows(ui, existing, fileName) {
+    // Dependencies go under the SCRIPT's folder, so a file name with a
+    // subdirectory in it moves them too — the list shows where each one
+    // would actually land, collection-relative, like the field above it.
+    const dir = fileName.includes('/') ? fileName.slice(0, fileName.lastIndexOf('/') + 1) : '';
+    const set = new Set(existing);
+    for (const li of ui.depsList.querySelectorAll('li')) {
+        const dep = dir + (li.dataset.dep ?? '');
+        li.replaceChildren(dep);
+        if (set.has(dep))
+            li.appendChild(el('span', 'dlg-exists', ' (already exists)'));
+    }
+}
+// The dependencies row: the checkbox's wording, whether it can be
+// ticked at all, and the list under it.
+function paintDependencies(ui, deps, collection) {
+    const total = deps.reduce((n, d) => n + d.size, 0);
+    const noun = deps.length === 1 ? 'dependency file' : 'dependency files';
+    const localFilesOff = collection !== null && !collectionUsesLocalFiles(collection);
+    if (deps.length === 0) {
+        ui.depsText.textContent = 'No dependency files to copy';
+        ui.depsHint.textContent = '';
+    }
+    else {
+        ui.depsText.textContent = `Also copy ${deps.length} ${noun} (${formatBytes(total)})`;
+        ui.depsHint.textContent = localFilesOff
+            ? 'Local files are turned off for this collection, so copies would not be used'
+            : 'Local filenames in download collection';
+    }
+    const off = deps.length === 0 || localFilesOff;
+    ui.deps.disabled = off;
+    // Only ever forced off, never on: this runs a second time when the
+    // open-time reads land, and a tick made before then is the user's.
+    if (off)
+        ui.deps.checked = false;
+    ui.depsLabel.classList.toggle('off', off);
+    ui.depsList.replaceChildren(...deps.map((d) => {
+        // Path relative to the SCRIPT's folder. `paintDependencyRows`
+        // renders it against the current file name and adds the
+        // "(already exists)" mark.
+        const li = el('li', undefined, d.relativePath);
+        // No tooltip of its own, so the row's applies: the declared URL
+        // this file came from says nothing about the local path the row
+        // is showing.
+        li.dataset.dep = d.relativePath;
+        return li;
+    }));
+}

package/dist/extension/copy-preference.js

@@ -0,0 +1,66 @@
+// Which installed copy of a script is preferred, when only one of them
+// should run or be shown: the order behind "Enable all" picking one
+// copy per script in a collection, and the toolbar popup picking the
+// copy that stands for a script none of whose copies is active.
+//
+// Pure, so popup-view.ts can use it in the service worker and the
+// rules can be unit tested. Design: docs/script-enablement.md.
+import { compareScriptNames } from '../script-display.js';
+import { compareVersions } from '../version-compare.js';
+function isActive(c) {
+    return c.enabled && c.collectionOn;
+}
+// Most recently active first: an active copy before any inactive one
+// (the later `activeSince` first between two active), then by when it
+// went inactive. A copy with no recorded times gives no signal and
+// comes last.
+function compareRecency(a, b) {
+    const ra = isActive(a);
+    const rb = isActive(b);
+    if (ra !== rb)
+        return ra ? -1 : 1;
+    const ta = (ra ? a.activeSince : a.inactiveSince) ?? 0;
+    const tb = (rb ? b.activeSince : b.inactiveSince) ?? 0;
+    return tb - ta;
+}
+// The order between copies in one collection: most recently active, then
+// the highest `@version` (a copy without one last), then location.
+export function compareInCollection(a, b) {
+    const recency = compareRecency(a, b);
+    if (recency !== 0)
+        return recency;
+    if (a.version !== b.version) {
+        if (a.version === null)
+            return 1;
+        if (b.version === null)
+            return -1;
+        const v = compareVersions(b.version, a.version);
+        if (v !== 0)
+            return v;
+    }
+    return a.location < b.location ? -1 : a.location > b.location ? 1 : 0;
+}
+// How close a copy is to active: in an enabled collection (so only its
+// own box is off), ticked in a disabled collection, unticked in one.
+function closeness(c) {
+    if (c.collectionOn)
+        return 0;
+    return c.enabled ? 1 : 2;
+}
+// The order between copies anywhere: closest to active, then most
+// recently active, then collection name, then `compareInCollection`.
+export function comparePreferred(a, b) {
+    return closeness(a) - closeness(b)
+        || compareRecency(a, b)
+        || compareScriptNames(a.collectionName, b.collectionName)
+        || compareInCollection(a, b);
+}
+// The first of `copies` by `compare`, or undefined when there are none.
+export function preferredCopy(copies, facts, compare = comparePreferred) {
+    let best;
+    for (const copy of copies) {
+        if (best === undefined || compare(facts(copy), facts(best)) < 0)
+            best = copy;
+    }
+    return best;
+}