sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/export-backup.js

@@ -0,0 +1,407 @@
+// The backup export: collections and their scripts, written as the zip
+// format in docs/export-format.md#sourcemonkey. Tampermonkey's zip
+// layout, so Tampermonkey and Violentmonkey can import it, plus a
+// `script_manifest.json` only SourceMonkey reads.
+//
+// Two halves:
+//   - `planExportEntries` is pure: rows, values and icon bytes in, zip
+//     entries out. Unit-tested on its own.
+//   - `runExport` gathers those inputs on the collections page, builds
+//     the zip and hands it to Chrome's Save As.
+import { MANIFEST_FILENAME } from '../collection-scan.js';
+import { base64ToBytes } from '../bytes.js';
+import { collectionKind, containerKind, isFileUrl, isHttpUrl, locationFsPath } from '../file-locations.js';
+import { resolveScriptResource } from '../file-loader.js';
+import { iconRefFromHeader } from '../script-icon.js';
+import { fullSource, scriptBasename } from '../script-display.js';
+import { getValue } from '../userscript-header.js';
+import { effectiveDisplayName } from './collection-display.js';
+import { isSmDevCollection } from './location-kinds.js';
+import { isRelativeRef, mirrorPath, relativeRefPath } from './local-copy.js';
+import { dataUrlContent, ensureIconForUrl } from './site-icon.js';
+import { collectionUsesLocalFiles, getCollectionWithScripts, getCollections, isCollectionEnabled, isScriptEnabled, } from './script-store.js';
+import { readScriptValues } from './worker-client.js';
+import { buildZip } from './zip-writer.js';
+export const EXPORT_FORMAT = 'sourcemonkey-export';
+export const EXPORT_FORMAT_VERSION = 1;
+// ---------- Pure helpers ----------
+// A GM value in the type-prefixed string form Tampermonkey and
+// Violentmonkey both store (docs/export-format.md#gm-value-encoding).
+// `undefined` has no entry: Violentmonkey would read `u` as a delete.
+export function encodeExportValue(value) {
+    switch (typeof value) {
+        case 'string': return `s${value}`;
+        case 'number': return `n${value}`;
+        case 'boolean': return `b${value}`;
+        case 'undefined': return undefined;
+        default: return `o${JSON.stringify(value)}`;
+    }
+}
+// Characters Tampermonkey or Violentmonkey would replace in a file
+// name, plus control characters.
+const UNSAFE_NAME_CHARS = /[\\/:*?"<>|$\u0000-\u001f]/g;
+// Longest name kept, in characters, before ` (2)` and the suffix: room
+// to spare under the 255-byte limit most file systems put on a name.
+const MAX_NAME_CHARS = 100;
+// `text` made safe as one file or folder name: characters TM or VM
+// would replace turned into `-`, trimmed, leading dots dropped, and cut
+// to `MAX_NAME_CHARS`. `fallback` when nothing is left.
+export function safeFileName(text, fallback) {
+    const cleaned = text.replace(UNSAFE_NAME_CHARS, '-').trim().replace(/^\.+/, '');
+    return [...cleaned].slice(0, MAX_NAME_CHARS).join('').trim() || fallback;
+}
+// A file name as a manifest entry. An entry is read as a URL, where `#`
+// would start a fragment and `%` an escape, so those two are encoded.
+// Everything else stays readable: the URL parser encodes spaces and
+// non-ASCII itself, and `?` never reaches a name (`exportScriptName`).
+export function manifestEntryPath(fileName) {
+    return fileName.replace(/%/g, '%25').replace(/#/g, '%23');
+}
+// Where a script loads from, for the manifest: a URL, or an absolute
+// file path for a local one. `null` for a location that is neither.
+function scriptLocation(script) {
+    if (isHttpUrl(script.fileUrl))
+        return script.fileUrl;
+    if (isFileUrl(script.fileUrl))
+        return locationFsPath(script.fileUrl);
+    return null;
+}
+function manifestCollection(collection) {
+    const kind = collectionKind(collection.path);
+    const out = {
+        uuid: collection.id,
+        name: effectiveDisplayName(collection),
+        kind,
+        location: kind === 'scripts' ? null : collection.path,
+        enabled: isCollectionEnabled(collection),
+        local_files: collectionUsesLocalFiles(collection),
+    };
+    const builtin = containerKind(collection.path);
+    if (builtin)
+        out.builtin = builtin;
+    return out;
+}
+// Where a dependency or icon file goes, relative to its script's folder:
+//   - A relative ref (`lib/util.js`) at that path, where it resolves
+//     from the unzipped script. One that climbs out of the script's
+//     folder (`../x.js`) has no such place.
+//   - Anything else at `<host>/<path>` of its URL (a `file://` URL at
+//     its path), where the local-file overrides look.
+export function exportFilePath(ref, url) {
+    return (isRelativeRef(ref) && relativeRefPath(ref)) || mirrorPath(url);
+}
+// The resolved URL of a script's own icon, when it is one we can bundle.
+export function scriptIconUrl(script) {
+    const ref = iconRefFromHeader(script.header);
+    if (!ref)
+        return null;
+    const resolved = resolveScriptResource(ref, script.fileUrl);
+    // A `data:` icon is in the header itself.
+    return resolved && resolved.kind !== 'data' ? resolved.url : null;
+}
+function sameBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+// A collection's folder name: its last path segment for one named by a
+// path.
+function collectionFolderName(collection) {
+    const name = effectiveDisplayName(collection);
+    const last = name.split('/').filter(Boolean).pop() ?? name;
+    return safeFileName(last, 'collection');
+}
+// `base`, or `base (2)`, `base (3)`, …: the first not in `used`, which
+// holds lower-cased names. The one chosen is added.
+function uniqueName(base, used) {
+    let name = base;
+    for (let n = 2; used.has(name.toLowerCase()); n++)
+        name = `${base} (${n})`;
+    used.add(name.toLowerCase());
+    return name;
+}
+function scriptFiles(script, icons) {
+    const encoder = new TextEncoder();
+    const files = new Map();
+    const add = (ref, url, data) => {
+        if (!isHttpUrl(url) && !isFileUrl(url))
+            return;
+        const path = exportFilePath(ref, url);
+        if (path && !files.has(path))
+            files.set(path, { data, relative: isRelativeRef(ref) });
+    };
+    for (const r of script.requires ?? [])
+        add(r.ref, r.url, encoder.encode(r.source));
+    for (const r of script.resources ?? [])
+        add(r.ref, r.url, new Uint8Array(base64ToBytes(r.bytesBase64)));
+    const iconRef = iconRefFromHeader(script.header);
+    const iconUrl = scriptIconUrl(script);
+    const icon = iconUrl ? icons[iconUrl] : undefined;
+    if (iconRef && iconUrl && icon)
+        add(iconRef, iconUrl, icon);
+    return files;
+}
+// Every entry of the export. Each script gets a folder of its own,
+// holding its `.user.js`, `.options.json` and `.storage.json`, and the
+// dependency files only it uses; with more than one collection, the
+// script folders sit in a folder per collection:
+//
+//   script_manifest.json
+//   cdn.example.com/lib.js               shared by scripts, same bytes
+//   My scripts/Foo/Foo.user.js
+//   My scripts/Foo/lib/util.js           a relative ref: always here
+//   My scripts/Foo/cdn.example.com/x.js  used by Foo only
+//
+// Laid out for the local-file overrides, so the unzipped folder, added
+// as a manifest collection, runs every script on the bundled files.
+// They search the script's own folder first, then the manifest's
+// folder (docs/local-file-overrides.md#where-roots-come-from):
+//   - A file at the top serves every script whose own folder doesn't
+//     hold another version.
+//   - A relative ref resolves straight to a path under the script's
+//     folder, where the overrides don't look further, so its file is
+//     always there.
+export function planExportEntries(input) {
+    const encoder = new TextEncoder();
+    const json = (value, pretty = false) => encoder.encode(JSON.stringify(value, null, pretty ? 2 : undefined));
+    // Names first: each collection's folder, and each script's.
+    const topNames = new Set([MANIFEST_FILENAME]);
+    const planned = [];
+    for (const { collection, scripts } of input.collections) {
+        const collectionFolder = input.collections.length > 1
+            ? `${uniqueName(collectionFolderName(collection), topNames)}/`
+            : '';
+        const scriptNames = collectionFolder ? new Set() : topNames;
+        for (const script of scripts) {
+            // Every script goes in, with whatever text it has: one that is
+            // empty, or never loaded, gets an empty `.user.js`.
+            const atName = (script.header && getValue(script.header, 'name')?.trim())
+                || scriptBasename(script.relativePath).replace(/\.user\.js$/i, '');
+            const name = uniqueName(safeFileName(atName, 'script'), scriptNames);
+            planned.push({
+                script,
+                collection,
+                atName,
+                folder: `${collectionFolder}${name}/`,
+                name,
+                files: input.options.files ? scriptFiles(script, input.icons) : new Map(),
+            });
+        }
+    }
+    // Which files go at the top: a path that scripts name with the same
+    // bytes, the version the most scripts use. Not a relative ref's file,
+    // and not one whose first folder would land in a collection's or
+    // script's folder.
+    const shared = new Map();
+    const byPath = new Map();
+    for (const p of planned) {
+        for (const [path, f] of p.files) {
+            if (f.relative || topNames.has(path.split('/')[0].toLowerCase()))
+                continue;
+            byPath.set(path, [...(byPath.get(path) ?? []), f.data]);
+        }
+    }
+    for (const [path, versions] of byPath) {
+        // Each copy is compared with the distinct versions seen so far,
+        // usually one, rather than with every other copy: fifty scripts
+        // sharing a large library would otherwise compare it 2,500 times.
+        const groups = [];
+        for (const v of versions) {
+            const group = groups.find((g) => sameBytes(g.data, v));
+            if (group)
+                group.count++;
+            else
+                groups.push({ data: v, count: 1 });
+        }
+        const best = groups.reduce((a, b) => (b.count > a.count ? b : a));
+        if (best.count > 1)
+            shared.set(path, best.data);
+    }
+    const entries = [];
+    const manifestScripts = [];
+    let position = 0;
+    for (const { script, collection, atName, folder, name, files } of planned) {
+        position++;
+        const location = scriptLocation(script);
+        const modified = script.loadedAt;
+        const stem = `${folder}${name}`;
+        entries.push({ path: `${stem}.user.js`, data: encoder.encode(fullSource(script)), modified });
+        const meta = { name: atName, uuid: script.id, modified };
+        if (location && isHttpUrl(location))
+            meta.file_url = location;
+        entries.push({
+            path: `${stem}.options.json`,
+            data: json({
+                meta,
+                // TM and VM have no collections, so a script runs there when it
+                // is active here.
+                settings: { enabled: isCollectionEnabled(collection) && isScriptEnabled(script), position },
+                // Required: VM skips a script without `options`. No `override`,
+                // which TM would take as the script's real match rules.
+                options: { check_for_updates: meta.file_url !== undefined },
+            }),
+            modified,
+        });
+        if (input.options.values) {
+            const data = {};
+            for (const [key, value] of Object.entries(input.values[script.id] ?? {})) {
+                const encoded = encodeExportValue(value);
+                if (encoded !== undefined)
+                    data[key] = encoded;
+            }
+            if (Object.keys(data).length > 0) {
+                entries.push({ path: `${stem}.storage.json`, data: json({ ts: input.now, data }), modified });
+            }
+        }
+        // Its own files, unless the top holds the same bytes. A file can't
+        // take one of the script's own entry names.
+        const own = new Set([`${name}.user.js`, `${name}.options.json`, `${name}.storage.json`].map((n) => n.toLowerCase()));
+        for (const [path, f] of files) {
+            const top = shared.get(path);
+            if (top && !f.relative && sameBytes(top, f.data))
+                continue;
+            if (own.has(path.toLowerCase()))
+                continue;
+            entries.push({ path: `${folder}${path}`, data: f.data });
+        }
+        manifestScripts.push({
+            path: manifestEntryPath(`${stem}.user.js`),
+            uuid: script.id,
+            collection: collection.id,
+            location,
+            enabled: isScriptEnabled(script),
+        });
+    }
+    for (const [path, data] of shared)
+        entries.push({ path, data });
+    const manifest = {
+        created_by: 'SourceMonkey',
+        format: EXPORT_FORMAT,
+        version: EXPORT_FORMAT_VERSION,
+        exported_at: input.now,
+        collections: input.collections.map(({ collection }) => manifestCollection(collection)),
+        scripts: manifestScripts,
+    };
+    return {
+        entries: [{ path: MANIFEST_FILENAME, data: json(manifest, true) }, ...entries],
+        scriptCount: position,
+    };
+}
+// `sourcemonkey-backup-<iso>.zip`, the timestamp as Tampermonkey writes
+// its own: `toISOString()` with `.` and `:` turned into `-`.
+export function exportFileName(now) {
+    return `sourcemonkey-backup-${new Date(now).toISOString().replace(/[.:]/g, '-')}.zip`;
+}
+// Read everything the plan needs. sm-dev's test collections are left
+// out: their scripts belong to a run, and only that run changes them.
+export async function gatherExportInput(scope, options, now) {
+    const all = await getCollections();
+    const chosen = ('all' in scope ? all : all.filter((c) => c.id === scope.collectionId))
+        .filter((c) => !isSmDevCollection(c.path));
+    const collections = [];
+    for (const c of chosen) {
+        const got = await getCollectionWithScripts(c.id);
+        if (got)
+            collections.push(got);
+    }
+    const scripts = collections.flatMap((c) => c.scripts);
+    const values = options.values ? await readScriptValues(scripts.map((s) => s.id)) : {};
+    const icons = {};
+    if (options.files) {
+        const urls = [...new Set(scripts.map(scriptIconUrl).filter((u) => u !== null))];
+        await Promise.all(urls.map(async (url) => {
+            const dataUrl = await ensureIconForUrl(url).catch(() => null);
+            const content = dataUrl ? dataUrlContent(dataUrl) : null;
+            if (content)
+                icons[url] = new Uint8Array(base64ToBytes(content.base64));
+        }));
+    }
+    return { collections, values, icons, options, now };
+}
+// Message for a Save As the person cancelled. Not an error to show.
+export const EXPORT_CANCELLED = 'The export was cancelled';
+// Build the zip and save it through Chrome's Save As. Resolves once
+// the file is written.
+export async function runExport(scope, options) {
+    const now = Date.now();
+    const plan = planExportEntries(await gatherExportInput(scope, options, now));
+    const bytes = buildZip(plan.entries, now);
+    const path = await saveFile(new Blob([bytes], { type: 'application/zip' }), exportFileName(now));
+    return { path, scriptCount: plan.scriptCount };
+}
+// Chrome's reasons a download stopped, in words, for the ones a save
+// to disk realistically hits. Others show Chrome's code.
+const SAVE_FAILURES = {
+    FILE_NO_SPACE: 'The disk is full',
+    FILE_ACCESS_DENIED: 'Chrome was not allowed to write to that folder',
+    FILE_NAME_TOO_LONG: 'The file name is too long',
+    FILE_TOO_LARGE: 'The file is too large for that disk',
+    FILE_TRANSIENT_ERROR: 'The disk was busy. Try again.',
+    FILE_BLOCKED: 'Chrome or the system blocked the file',
+};
+export function saveFailureMessage(reason) {
+    return (reason && SAVE_FAILURES[reason]) || `Chrome stopped the save (${reason || 'no reason given'})`;
+}
+// The saved path once download `id` completes, from Chrome's change
+// events. Checked once at the start too, for a download that finished
+// before the listener was added.
+function downloadFinished(id) {
+    return new Promise((resolve, reject) => {
+        const settle = (item) => {
+            if (!item) {
+                reject(new Error(EXPORT_CANCELLED));
+                return true;
+            }
+            if (item.state === 'complete') {
+                resolve(item.filename);
+                return true;
+            }
+            if (item.state === 'interrupted') {
+                reject(new Error(item.error === 'USER_CANCELED' ? EXPORT_CANCELLED : saveFailureMessage(item.error)));
+                return true;
+            }
+            return false;
+        };
+        const check = () => {
+            void chrome.downloads.search({ id }).then(([item]) => {
+                if (settle(item))
+                    chrome.downloads.onChanged.removeListener(onChanged);
+            }, (err) => {
+                chrome.downloads.onChanged.removeListener(onChanged);
+                reject(err);
+            });
+        };
+        const onChanged = (delta) => {
+            if (delta.id === id && (delta.state || delta.error))
+                check();
+        };
+        chrome.downloads.onChanged.addListener(onChanged);
+        check();
+    });
+}
+async function saveFile(blob, fileName) {
+    const url = URL.createObjectURL(blob);
+    const saveAs = globalThis.smExportSkipSaveAs !== true;
+    try {
+        let id;
+        try {
+            id = await chrome.downloads.download({ url, filename: fileName, saveAs, conflictAction: 'uniquify' });
+        }
+        catch (err) {
+            // A Save As closed without choosing a file can reject here, with
+            // Chrome's "Download canceled".
+            const text = err instanceof Error ? err.message : String(err);
+            if (/cancel/i.test(text))
+                throw new Error(EXPORT_CANCELLED);
+            throw new Error(`Chrome refused to save the file (${text})`);
+        }
+        // No deadline: the Save As waits on the person.
+        return await downloadFinished(id);
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}

package/dist/extension/export-dialog.js

@@ -0,0 +1,142 @@
+// The export dialog, opened from the collections page's ⋯ menus: what to
+// include, then Chrome's Save As. It stays open to say how many scripts
+// went in and where the file went. See docs/export.md.
+import { describeError } from './script-store.js';
+import { makeCopyButton } from './copy-button.js';
+import { EXPORT_CANCELLED, runExport } from './export-backup.js';
+let elements = null;
+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;
+}
+function checkbox(id, label, hint) {
+    const wrap = el('div', 'dlg-option');
+    const labelEl = el('label', 'dlg-check');
+    const input = el('input');
+    input.type = 'checkbox';
+    input.id = id;
+    labelEl.append(input, el('span', undefined, label));
+    wrap.append(labelEl, el('div', 'dlg-hint', hint));
+    return { wrap, input };
+}
+function buildDialog() {
+    const dialog = el('dialog', 'sm-dialog export-dialog');
+    const title = el('h2', 'dlg-title');
+    dialog.appendChild(title);
+    const body = el('div', 'dlg-body');
+    body.appendChild(el('p', 'dlg-intro', 'This saves a .zip file that SourceMonkey, Tampermonkey, Violentmonkey, and other compatible managers can import.'));
+    const include = el('div', 'dlg-includes');
+    const values = checkbox('export-values', 'Stored values', 'Each script’s GM_setValue data.');
+    const files = checkbox('export-files', 'Dependency files', 'The @require, @resource and @icon files each script uses.');
+    include.append(values.wrap, files.wrap);
+    body.append(el('span', 'dlg-label', 'Include'), include);
+    const result = el('div', 'dlg-result');
+    result.id = 'export-result';
+    result.hidden = true;
+    body.appendChild(result);
+    dialog.appendChild(body);
+    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', 'Export…');
+    ok.type = 'button';
+    ok.id = 'export-confirm-btn';
+    actions.append(cancel, ok);
+    dialog.appendChild(actions);
+    document.body.appendChild(dialog);
+    return { dialog, title, values: values.input, files: files.input, result, error, cancel, ok };
+}
+// Open the dialog. Resolves when it closes.
+export function openExportDialog(request) {
+    if (!elements)
+        elements = buildDialog();
+    const ui = elements;
+    if (dialogInFlight)
+        return Promise.resolve();
+    dialogInFlight = true;
+    return new Promise((resolve) => {
+        let busy = false;
+        let done = false;
+        const abort = new AbortController();
+        const finish = () => {
+            abort.abort();
+            dialogInFlight = false;
+            if (ui.dialog.open)
+                ui.dialog.close();
+            resolve();
+        };
+        ui.title.textContent = 'all' in request.scope
+            ? 'Export all collections'
+            : `Export collection: ${request.collectionName ?? ''}`;
+        ui.values.checked = true;
+        ui.files.checked = false;
+        ui.values.disabled = false;
+        ui.files.disabled = false;
+        ui.result.hidden = true;
+        ui.result.replaceChildren();
+        ui.error.textContent = '';
+        ui.cancel.hidden = false;
+        ui.cancel.disabled = false;
+        ui.ok.disabled = false;
+        ui.ok.textContent = 'Export…';
+        const setBusy = (on) => {
+            busy = on;
+            ui.values.disabled = on;
+            ui.files.disabled = on;
+            ui.cancel.disabled = on;
+            ui.ok.disabled = on;
+            ui.ok.textContent = on ? 'Exporting…' : 'Export…';
+        };
+        const onOk = async () => {
+            if (done) {
+                finish();
+                return;
+            }
+            ui.error.textContent = '';
+            setBusy(true);
+            try {
+                const out = await runExport(request.scope, { values: ui.values.checked, files: ui.files.checked });
+                done = true;
+                // The saved path in code font, with a button that copies it.
+                const saved = el('p', 'dlg-saved');
+                const pathEl = el('code', 'dlg-saved-path', out.path);
+                pathEl.id = 'export-saved-path';
+                saved.append(`Exported ${out.scriptCount} ${out.scriptCount === 1 ? 'script' : 'scripts'} to `, pathEl, makeCopyButton({ label: 'Copy path to clipboard', text: () => out.path }));
+                ui.result.replaceChildren(saved);
+                ui.result.hidden = false;
+                setBusy(false);
+                ui.values.disabled = true;
+                ui.files.disabled = true;
+                ui.cancel.hidden = true;
+                ui.ok.textContent = 'Close';
+            }
+            catch (err) {
+                setBusy(false);
+                const message = describeError(err);
+                if (message !== EXPORT_CANCELLED)
+                    ui.error.textContent = `Export failed: ${message}`;
+            }
+        };
+        ui.ok.addEventListener('click', () => void onOk(), { signal: abort.signal });
+        ui.cancel.addEventListener('click', finish, { signal: abort.signal });
+        // Esc while the zip is being saved would leave the save running
+        // behind a closed dialog.
+        ui.dialog.addEventListener('cancel', (ev) => {
+            ev.preventDefault();
+            if (!busy)
+                finish();
+        }, { signal: abort.signal });
+        ui.dialog.showModal();
+        ui.ok.focus();
+    });
+}

package/dist/extension/file-access.js

@@ -0,0 +1,74 @@
+// The "Allow access to file URLs" probe and the banner that explains a
+// failed `file://` read, shared by every extension page that can hit
+// one (collections page, script viewer / install preview).
+//
+// The toggle lives on `chrome://extensions` and is invisible from a
+// fetch's point of view: with it off, reading a local file fails with
+// the same opaque error a missing file produces (see
+// [docs/file-access.md]). So a page that couldn't read a local file
+// asks here whether the toggle is the reason, and shows a banner that
+// names it and links to the page that fixes it.
+//
+// Page-only — `chrome.extension` is not exposed to the service worker.
+// Whether the per-extension file-access toggle is on. Callback-style
+// API, so it gets a promise wrapper.
+//
+// Never rejects. Callers use this to decide whether to *explain* a
+// failure, and an explanation is not worth taking a page down for — a
+// probe that throws (API renamed, unexpected context) reports "allowed"
+// so the banner stays away and everything else renders as usual.
+export function isFileSchemeAccessAllowed() {
+    return new Promise((resolve) => {
+        try {
+            chrome.extension.isAllowedFileSchemeAccess((allowed) => resolve(allowed));
+        }
+        catch {
+            resolve(true);
+        }
+    });
+}
+// The banner itself. `retry` completes "…turn it on, <retry>:" — what
+// the user has to do to make the read actually happen again, which
+// differs by caller: a page that reads on load wants a reload, while
+// the viewer renders a stored row and doesn't re-read until Refresh.
+export function renderFileAccessBanner(retry = 'then reload this page') {
+    const div = document.createElement('div');
+    div.className = 'banner';
+    const heading = document.createElement('strong');
+    heading.textContent = 'File access is disabled.';
+    div.appendChild(heading);
+    const explain = document.createElement('p');
+    explain.textContent =
+        'SourceMonkey can\'t read local files until you enable ' +
+            '"Allow access to file URLs". Open the extension\'s details page, ' +
+            `turn it on, ${retry}:`;
+    div.appendChild(explain);
+    div.appendChild(extensionDetailsLink());
+    return div;
+}
+// chrome:// URLs are blocked from <a href> navigation, so we use a
+// click handler that calls chrome.tabs.create — that path is allowed
+// from extension pages. Rendered as an <a> so it looks/behaves like
+// any other link.
+//
+// Exported because the collections page's "Allow User Scripts" banner
+// points at the same details page. With `text`, it reads as a plain link
+// inside a sentence instead of showing the address.
+export function extensionDetailsLink(text) {
+    const url = `chrome://extensions/?id=${chrome.runtime.id}`;
+    const a = document.createElement('a');
+    a.href = url;
+    a.textContent = text ?? url;
+    a.className = text ? 'chrome-text-link' : 'chrome-link';
+    a.addEventListener('click', (event) => {
+        event.preventDefault();
+        // Caught, not dropped: an unhandled rejection in an extension page
+        // is filed under chrome://extensions/?errors, which is the panel
+        // this banner is trying to send the user to — arriving there to
+        // find SourceMonkey's own error would be its own kind of confusing.
+        // A `chrome://` target has no realistic failure, so there is
+        // nothing to say beyond leaving the link inert.
+        chrome.tabs.create({ url }).catch(() => { });
+    });
+    return a;
+}