sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/debug/icons.js

@@ -0,0 +1,203 @@
+import { renderGlyph, setGlyphButton, setGlyphButtonBusy, } from '../glyph.js';
+import { formatLogTimestamp } from '../log-format.js';
+import { installHomeLinkHandler } from '../page-links.js';
+import { formatBytes } from '../../script-display.js';
+import { isIconCacheKey, listCachedIcons, } from '../site-icon.js';
+import { deleteAllCachedIcons, deleteCachedIcon, refreshCachedIcon } from '../worker-client.js';
+const summaryEl = document.getElementById('icons-summary');
+const emptyEl = document.getElementById('icons-empty');
+const tableEl = document.getElementById('icons-table');
+const tbodyEl = document.getElementById('icons-tbody');
+const deleteAllBtn = document.getElementById('delete-all');
+const REFRESH_LABELS = {
+    idle: 'Refresh cached icon',
+    busy: 'Refreshing…',
+};
+const refreshingKeys = new Set();
+let renderGeneration = 0;
+// The log's local-time spelling, without its milliseconds: cache
+// timestamps are days apart, so the tail is noise here.
+function formatTimestamp(ms) {
+    if (Number.isNaN(new Date(ms).getTime()))
+        return '—';
+    return formatLogTimestamp(ms).replace(/\.\d{3}$/, '');
+}
+// Storage failures on this page have no surface of their own; an
+// unhandled rejection would land in chrome://extensions/?errors, where
+// it reads as SourceMonkey being broken.
+function report(what) {
+    return (err) => console.info(`[SourceMonkey] debug icons: ${what} failed`, err);
+}
+function formatIso(ms) {
+    const d = new Date(ms);
+    return Number.isNaN(d.getTime()) ? '' : d.toISOString();
+}
+function kindLabel(kind) {
+    return kind === 'url' ? '@icon' : kind;
+}
+function renderRow(row) {
+    const tr = document.createElement('tr');
+    tr.dataset.storageKey = row.storageKey;
+    // 1. Icon
+    const iconTd = document.createElement('td');
+    iconTd.className = 'col-icon';
+    if (row.entry.dataUrl) {
+        const img = document.createElement('img');
+        img.src = row.entry.dataUrl;
+        img.alt = '';
+        iconTd.appendChild(img);
+    }
+    else {
+        iconTd.appendChild(renderGlyph(document, '#sm-globe', 'site-icon-globe'));
+    }
+    tr.appendChild(iconTd);
+    // 2. Site / Target
+    const targetTd = document.createElement('td');
+    targetTd.className = 'col-target';
+    const link = document.createElement('a');
+    link.href = row.target;
+    link.target = '_blank';
+    link.rel = 'noopener noreferrer';
+    link.textContent = row.target;
+    link.title = row.storageKey;
+    targetTd.appendChild(link);
+    tr.appendChild(targetTd);
+    // 3. Scope
+    const kindTd = document.createElement('td');
+    const chip = document.createElement('span');
+    chip.className = `kind-chip kind-${row.kind}`;
+    chip.textContent = kindLabel(row.kind);
+    chip.title = row.storageKey;
+    kindTd.appendChild(chip);
+    tr.appendChild(kindTd);
+    // 4. Details
+    const detailsTd = document.createElement('td');
+    const parts = [];
+    if (row.entry.dataUrl) {
+        const mime = row.mimeType ?? 'image';
+        const size = row.byteLength !== null ? formatBytes(row.byteLength) : '';
+        parts.push(size ? `${mime} (${size})` : mime);
+    }
+    else {
+        parts.push('none (miss)');
+    }
+    if (row.entry.v !== undefined) {
+        parts.push(`v${row.entry.v}`);
+    }
+    detailsTd.textContent = parts.join(' · ');
+    const badge = document.createElement('span');
+    if (!row.isFresh) {
+        badge.className = 'status-badge status-stale';
+        badge.textContent = 'expired';
+    }
+    else if (row.requiredVersion !== null && row.entry.v !== row.requiredVersion) {
+        badge.className = 'status-badge status-stale';
+        badge.textContent = 'stale schema';
+        const have = row.entry.v === undefined ? 'none' : `v${row.entry.v}`;
+        badge.title = [
+            `Schema version: ${have}`,
+            `Current version: v${row.requiredVersion}`,
+            'Ignored and refetched on the next render.',
+        ].join('\n');
+    }
+    else if (!row.isUsable) {
+        badge.className = 'status-badge status-stale';
+        badge.textContent = 'unpaintable';
+        badge.title = [
+            'The cached value is not an icon we would paint.',
+            'Ignored and refetched on the next render.',
+        ].join('\n');
+    }
+    else if (row.entry.dataUrl === null) {
+        badge.className = 'status-badge status-miss';
+        badge.textContent = 'miss';
+    }
+    else {
+        badge.className = 'status-badge status-ok';
+        badge.textContent = 'ok';
+    }
+    detailsTd.appendChild(badge);
+    tr.appendChild(detailsTd);
+    // 5. Fetched timestamp
+    const fetchedTd = document.createElement('td');
+    fetchedTd.className = 'col-time';
+    fetchedTd.textContent = formatTimestamp(row.entry.fetchedAt);
+    fetchedTd.title = formatIso(row.entry.fetchedAt);
+    tr.appendChild(fetchedTd);
+    // 6. Expiry timestamp
+    const expiresTd = document.createElement('td');
+    expiresTd.className = 'col-time';
+    expiresTd.textContent = formatTimestamp(row.expiresAt);
+    expiresTd.title = formatIso(row.expiresAt);
+    tr.appendChild(expiresTd);
+    // 7. Actions (Refresh + Delete)
+    const actionsTd = document.createElement('td');
+    actionsTd.className = 'col-actions';
+    const wrap = document.createElement('div');
+    wrap.className = 'row-actions';
+    const refreshBtn = document.createElement('button');
+    refreshBtn.type = 'button';
+    refreshBtn.className = 'refresh-icon';
+    setGlyphButton(refreshBtn, '#sm-refresh', REFRESH_LABELS.idle);
+    if (refreshingKeys.has(row.storageKey)) {
+        setGlyphButtonBusy(refreshBtn, true, REFRESH_LABELS);
+    }
+    // The storage write at the end of a refresh re-renders the table via
+    // `onChanged`, so this button is replaced rather than un-busied; the
+    // explicit render covers the refresh that stored nothing new.
+    refreshBtn.addEventListener('click', () => {
+        refreshingKeys.add(row.storageKey);
+        setGlyphButtonBusy(refreshBtn, true, REFRESH_LABELS);
+        void refreshCachedIcon(row.storageKey)
+            .catch(report('refresh'))
+            .finally(() => {
+            refreshingKeys.delete(row.storageKey);
+            void render();
+        });
+    });
+    const deleteBtn = document.createElement('button');
+    deleteBtn.type = 'button';
+    deleteBtn.className = 'delete-icon';
+    setGlyphButton(deleteBtn, '#sm-trash', 'Delete cached icon');
+    deleteBtn.addEventListener('click', () => {
+        deleteBtn.disabled = true;
+        void deleteCachedIcon(row.storageKey)
+            .catch(report('delete'))
+            .finally(() => {
+            void render();
+        });
+    });
+    wrap.append(refreshBtn, deleteBtn);
+    actionsTd.appendChild(wrap);
+    tr.appendChild(actionsTd);
+    return tr;
+}
+async function render() {
+    const gen = ++renderGeneration;
+    const rows = await listCachedIcons();
+    if (gen !== renderGeneration)
+        return;
+    const count = rows.length;
+    summaryEl.textContent = count === 1 ? '1 cached icon' : `${count} cached icons`;
+    deleteAllBtn.disabled = count === 0;
+    emptyEl.hidden = count > 0;
+    tableEl.hidden = count === 0;
+    tbodyEl.replaceChildren(...rows.map(renderRow));
+}
+installHomeLinkHandler();
+deleteAllBtn.addEventListener('click', () => {
+    deleteAllBtn.disabled = true;
+    void deleteAllCachedIcons()
+        .catch(report('delete all'))
+        .finally(() => {
+        void render();
+    });
+});
+chrome.storage.onChanged.addListener((changes, areaName) => {
+    if (areaName !== 'local')
+        return;
+    if (Object.keys(changes).some(isIconCacheKey)) {
+        void render();
+    }
+});
+void render();

package/dist/extension/debug/storage.js

@@ -0,0 +1,365 @@
+// The storage debug page (/debug/storage.html): where
+// `chrome.storage.local` goes, by script, by stored file, or in GM
+// values. Read-only. See docs/storage.md#storage-debug-page.
+import { collectionAnchorId } from '../collection-display.js';
+import { installHomeLinkHandler, namedPageUrl, wireNamedTabLink } from '../page-links.js';
+import { timeStorageRead } from '../storage-scan.js';
+import { describeError } from '../script-store.js';
+import { appendWithSlashBreaks, viewerUrl } from '../../script-display.js';
+import { buildStorageBreakdown, defaultSortDir, fileIdentity, sortFiles, sortScripts, sortValues, } from '../storage-breakdown.js';
+const summaryEl = document.getElementById('storage-summary');
+const emptyEl = document.getElementById('storage-empty');
+const tableEl = document.getElementById('storage-table');
+const viewButtons = [...document.querySelectorAll('.views button')];
+installHomeLinkHandler();
+// Each view keeps its own sort while the page is open.
+const sorts = {
+    script: { key: 'size', dir: 'desc' },
+    file: { key: 'size', dir: 'desc' },
+    values: { key: 'size', dir: 'desc' },
+};
+let breakdown = null;
+let loadError = '';
+// The view is the URL's fragment, so a reload keeps it.
+function currentView() {
+    const hash = location.hash.slice(1);
+    return hash === 'file' || hash === 'values' ? hash : 'script';
+}
+for (const button of viewButtons) {
+    button.addEventListener('click', () => {
+        const view = button.dataset.view;
+        history.replaceState(null, '', view === 'script' ? location.pathname : `#${view}`);
+        render();
+    });
+}
+addEventListener('hashchange', render);
+// ---------- Formatting ----------
+const numberFormat = new Intl.NumberFormat();
+function plural(n, one, many = `${one}s`) {
+    return `${numberFormat.format(n)} ${n === 1 ? one : many}`;
+}
+// Whole KB, as on the Options page; a size too small to show as 1 KB
+// still reads as something rather than 0.
+function formatKb(bytes) {
+    const kb = Math.round(bytes / 1024);
+    if (kb === 0 && bytes > 0)
+        return '< 1 KB';
+    return `${numberFormat.format(kb)} KB`;
+}
+const KIND_LABELS = {
+    script: 'script',
+    metadata: 'metadata',
+    require: '@require',
+    resource: '@resource',
+    'smdev-text': 'sm-dev script text',
+    'smdev-file': 'sm-dev pushed file',
+};
+// ---------- Cells ----------
+function span(className, text) {
+    const el = document.createElement('span');
+    el.className = className;
+    el.textContent = text;
+    return el;
+}
+function td(className, ...children) {
+    const cell = document.createElement('td');
+    if (className)
+        cell.className = className;
+    // Spaces between the parts, so a kind, a name and a location wrap
+    // as words.
+    children.forEach((child, i) => {
+        if (i > 0)
+            cell.append(' ');
+        cell.append(child);
+    });
+    return cell;
+}
+// A name cell running down beside the group's item lines, so a long
+// name wraps alongside them rather than pushing them down.
+function spanGroup(cell, items) {
+    cell.rowSpan = 1 + items;
+    return cell;
+}
+function sizeCell(bytes) {
+    const cell = td('num', formatKb(bytes));
+    cell.title = `${numberFormat.format(bytes)} bytes`;
+    return cell;
+}
+// Blank for a file only one script uses.
+function sharedCell(shared) {
+    return td('num', shared > 1 ? numberFormat.format(shared) : '');
+}
+function collectionCell(ref) {
+    if (!ref.collectionId)
+        return td(undefined, span('muted', 'No collection'));
+    const a = document.createElement('a');
+    // Break after slashes, as the collections page does: a name is often a path.
+    appendWithSlashBreaks(a, ref.collectionName);
+    const hash = collectionAnchorId(ref.collectionId);
+    wireNamedTabLink(a, 'collections', hash);
+    // Its page-relative href would resolve inside debug/, beside this page.
+    a.href = chrome.runtime.getURL(namedPageUrl('collections', hash));
+    return td(undefined, a);
+}
+function scriptCell(ref) {
+    const a = document.createElement('a');
+    appendWithSlashBreaks(a, ref.scriptName);
+    a.href = `../${viewerUrl(ref.scriptId)}`;
+    a.target = '_blank';
+    a.rel = 'noopener';
+    return td(undefined, a);
+}
+// The parts naming an item: its kind, `@resource` name and location,
+// whichever it has and the caller wants.
+function itemParts(item) {
+    const parts = [];
+    if (item.kind)
+        parts.push(span('kind', KIND_LABELS[item.kind]));
+    if (item.name)
+        parts.push(span('loc', item.name));
+    if (item.location) {
+        const loc = span('loc', '');
+        appendWithSlashBreaks(loc, item.location);
+        parts.push(loc);
+    }
+    if (item.missing)
+        parts.push(span('muted', MISSING));
+    return parts;
+}
+// A file scripts point at that isn't in storage (see `missing` in
+// storage-breakdown.ts).
+const MISSING = '(missing from storage)';
+function row(className, cells) {
+    const tr = document.createElement('tr');
+    tr.className = className;
+    tr.append(...cells);
+    return tr;
+}
+function group(rows) {
+    const tbody = document.createElement('tbody');
+    tbody.className = 'group';
+    tbody.append(...rows);
+    return tbody;
+}
+function head(view, columns) {
+    const colgroup = document.createElement('colgroup');
+    for (const c of columns) {
+        const col = document.createElement('col');
+        if (c.width)
+            col.className = c.width;
+        colgroup.append(col);
+    }
+    const thead = document.createElement('thead');
+    const tr = document.createElement('tr');
+    const sort = sorts[view];
+    for (const c of columns) {
+        const th = document.createElement('th');
+        th.textContent = c.label;
+        const classes = [c.num ? 'num' : '', c.sort ? 'sortable' : ''].filter(Boolean);
+        if (classes.length)
+            th.className = classes.join(' ');
+        if (c.sort) {
+            const key = c.sort;
+            th.dataset.sort = key;
+            if (sort.key === key) {
+                th.append(span('sort-arrow', sort.dir === 'desc' ? '▼' : '▲'));
+                th.setAttribute('aria-sort', sort.dir === 'desc' ? 'descending' : 'ascending');
+            }
+            th.addEventListener('click', () => {
+                sorts[view] = sort.key === key
+                    ? { key, dir: sort.dir === 'desc' ? 'asc' : 'desc' }
+                    : { key, dir: defaultSortDir(key) };
+                render();
+            });
+        }
+        tr.append(th);
+    }
+    thead.append(tr);
+    return [colgroup, thead];
+}
+function scriptTable(b) {
+    const { key, dir } = sorts.script;
+    return [
+        ...head('script', [
+            { label: 'Collection', sort: 'collection', width: 'col-collection' },
+            { label: 'Script', sort: 'script', width: 'col-name' },
+            { label: 'File' },
+            { label: 'Size', sort: 'size', width: 'col-size', num: true },
+            { label: 'Shared copies', sort: 'shared', width: 'col-shared', num: true },
+        ]),
+        ...sortScripts(b.scripts, key, dir).map((s) => group([
+            row('group-head', [
+                spanGroup(collectionCell(s), s.items.length), spanGroup(scriptCell(s), s.items.length),
+                td('total-label', 'Total'), sizeCell(s.bytes), td(),
+            ]),
+            ...s.items.map((item) => row('group-item', [
+                td('item', ...itemParts(item)), sizeCell(item.bytes), sharedCell(item.shared),
+            ])),
+        ])),
+    ];
+}
+function fileGroup(file) {
+    const id = fileIdentity(file);
+    // The heading names what every use agrees on; each use's line names
+    // the rest.
+    const heading = id.kind === null
+        ? [span('muted', 'Multiple locations')]
+        : [
+            ...itemParts({
+                kind: id.kind,
+                name: id.sameName ? id.name : undefined,
+                location: id.sameLocation ? id.location : undefined,
+            }),
+            ...(id.sameLocation ? [] : [span('muted', 'multiple locations')]),
+        ];
+    if (file.missing)
+        heading.push(span('muted', MISSING));
+    const own = (use) => id.kind === null ? itemParts(use) : itemParts({
+        name: id.sameName ? undefined : use.name,
+        location: id.sameLocation ? undefined : use.location,
+    });
+    const useCells = (use) => [collectionCell(use), scriptCell(use)].map((cell) => {
+        cell.classList.add('use');
+        return cell;
+    });
+    // When the heading says it all, the first use goes on the heading's
+    // line rather than leaving a gap above the uses, and the heading runs
+    // down beside the rest, so a long one wraps without pushing them down.
+    const [first, ...rest] = file.uses;
+    const lead = first && file.uses.every((use) => own(use).length === 0) ? first : undefined;
+    if (lead) {
+        return group([
+            row('group-head', [
+                spanGroup(td(undefined, ...heading), rest.length), ...useCells(lead),
+                sizeCell(file.bytes), sharedCell(file.uses.length),
+            ]),
+            ...rest.map((use) => row('group-item', [...useCells(use), td(), td()])),
+        ]);
+    }
+    return group([
+        row('group-head', [td(undefined, ...heading), td(), td(), sizeCell(file.bytes), sharedCell(file.uses.length)]),
+        ...file.uses.map((use) => row('group-item', [
+            td('item', ...own(use)), ...useCells(use), td(), td(),
+        ])),
+    ]);
+}
+function fileTable(b) {
+    const { key, dir } = sorts.file;
+    const parts = [
+        ...head('file', [
+            { label: 'File' },
+            { label: 'Collection', width: 'col-collection' },
+            { label: 'Script', width: 'col-name' },
+            { label: 'Size', sort: 'size', width: 'col-size', num: true },
+            { label: 'Shared copies', sort: 'shared', width: 'col-shared', num: true },
+        ]),
+        // Only those two headings sort here.
+        ...sortFiles(b.files, key === 'shared' ? 'shared' : 'size', dir).map(fileGroup),
+    ];
+    // Always last: it belongs to no collection or script to sort by.
+    if (b.unused.length > 0) {
+        const unused = [...b.unused].sort((x, y) => y.bytes - x.bytes);
+        parts.push(group([
+            row('group-head', [
+                td(undefined, span('muted', 'Not used by any script')), td(), td(),
+                sizeCell(unused.reduce((sum, f) => sum + f.bytes, 0)), td(),
+            ]),
+            ...unused.map((f) => row('group-item', [
+                td('item', span('loc', f.key)), td(), td(), sizeCell(f.bytes), td(),
+            ])),
+        ]));
+    }
+    return parts;
+}
+function valuesTable(b) {
+    const { key, dir } = sorts.values;
+    return [
+        ...head('values', [
+            { label: 'Collection', sort: 'collection', width: 'col-values-name' },
+            { label: 'Script', sort: 'script' },
+            { label: 'Size', sort: 'size', width: 'col-size', num: true },
+            { label: 'Values', sort: 'count', width: 'col-count', num: true },
+        ]),
+        ...sortValues(b.values, key, dir).map((v) => group([
+            row('group-head', v.script
+                ? [collectionCell(v.script), scriptCell(v.script), sizeCell(v.bytes), td('num', numberFormat.format(v.count))]
+                : [
+                    td(undefined, span('muted', 'Removed script')), td(undefined, span('loc', v.scriptId)),
+                    sizeCell(v.bytes), td('num', numberFormat.format(v.count)),
+                ]),
+        ])),
+    ];
+}
+// ---------- Render ----------
+function summary(view, b) {
+    if (view === 'script') {
+        // Scripts whose collection row is missing ('') aren't one more.
+        const collections = new Set(b.scripts.map((s) => s.collectionId).filter(Boolean)).size;
+        return `${plural(b.scripts.length, 'script')} in ${plural(collections, 'collection')}. `
+            + 'Shared files are counted once in each script that references them.';
+    }
+    if (view === 'file') {
+        // A missing file isn't stored.
+        const all = [...b.files.filter((f) => !f.missing), ...b.unused];
+        const bytes = all.reduce((sum, f) => sum + f.bytes, 0);
+        return `${plural(all.length, 'stored file')}, ${formatKb(bytes)}. Each shared file counts once.`;
+    }
+    const count = b.values.reduce((sum, v) => sum + v.count, 0);
+    const bytes = b.values.reduce((sum, v) => sum + v.bytes, 0);
+    return `${plural(count, 'value')} in ${plural(b.values.length, 'script')}, ${formatKb(bytes)}.`;
+}
+const EMPTY = {
+    script: 'No scripts in storage.',
+    file: 'No stored files.',
+    values: 'No scripts have stored values.',
+};
+function render() {
+    const view = currentView();
+    for (const button of viewButtons)
+        button.setAttribute('aria-pressed', String(button.dataset.view === view));
+    if (!breakdown) {
+        summaryEl.textContent = loadError;
+        emptyEl.hidden = true;
+        tableEl.hidden = true;
+        return;
+    }
+    const b = breakdown;
+    const isEmpty = view === 'script' ? b.scripts.length === 0
+        : view === 'file' ? b.files.length + b.unused.length === 0
+            : b.values.length === 0;
+    summaryEl.textContent = isEmpty ? '' : summary(view, b);
+    emptyEl.textContent = EMPTY[view];
+    emptyEl.hidden = !isEmpty;
+    tableEl.hidden = isEmpty;
+    tableEl.replaceChildren(...(isEmpty ? [] : view === 'script' ? scriptTable(b) : view === 'file' ? fileTable(b) : valuesTable(b)));
+}
+// Each load reads every row, so a burst of writes (a refresh, a script
+// spamming GM_setValue) is coalesced into one reload a second at most.
+// Loads can overlap; only the newest one may draw.
+let latest = 0;
+let pending = false;
+async function load() {
+    pending = false;
+    const mine = ++latest;
+    try {
+        const rows = await timeStorageRead('storage debug page', () => chrome.storage.local.get(null));
+        if (mine !== latest)
+            return;
+        breakdown = buildStorageBreakdown(rows);
+    }
+    catch (err) {
+        if (mine !== latest)
+            return;
+        breakdown = null;
+        loadError = `Could not read storage: ${describeError(err)}`;
+    }
+    render();
+}
+chrome.storage.onChanged.addListener((_changes, areaName) => {
+    if (areaName !== 'local' || pending)
+        return;
+    pending = true;
+    setTimeout(() => void load(), 1000);
+});
+render();
+void load();

package/dist/extension/deep-link.js

@@ -0,0 +1,77 @@
+// Lets external pages (anywhere on the web) "navigate into" the
+// extension. Plain web pages can't link to chrome-extension:// URLs,
+// so we publish a stub docs/redirect-page.md on GitHub, watch for
+// navigations to it, and rewrite the tab to the requested extension
+// page.
+//
+// Source URL:
+//   https://github.com/jshute96/SourceMonkey/blob/main/docs/redirect-page.md
+//     ?page=<allowed>&<other-params>
+// Target URL:
+//   chrome-extension://<id>/<page>?<other-params>
+//
+// `page` is allowlisted. Anything else short-circuits and leaves the
+// GitHub page alone — the doc itself explains how to install the
+// extension, so a non-redirect outcome is the "no extension" fallback.
+//
+// chrome.runtime.getURL() builds the full chrome-extension:// URL at
+// runtime, so this works whether the extension was loaded unpacked
+// (ID pinned via manifest "key") or installed from the Web Store
+// (different ID).
+import { CAPTURED_PARAM } from './install-capture.js';
+const REDIRECT_URL = 'https://github.com/jshute96/SourceMonkey/blob/main/docs/redirect-page.md';
+const ALLOWED_PAGES = new Set(['collections.html', 'options.html', 'userscript.html']);
+// Pure: maps a source URL to its rewrite target, or null when the URL
+// is not a deep link we should act on. Exported for unit tests.
+export function buildDeepLinkTarget(srcUrl) {
+    let u;
+    try {
+        u = new URL(srcUrl);
+    }
+    catch {
+        return null;
+    }
+    // Reject userinfo (user:pass@host) for defence in depth — origin
+    // strips it, so the equality check would otherwise accept it.
+    if (u.username !== '' || u.password !== '')
+        return null;
+    if (`${u.origin}${u.pathname}` !== REDIRECT_URL)
+        return null;
+    const page = u.searchParams.get('page');
+    if (!page || !ALLOWED_PAGES.has(page))
+        return null;
+    const passthrough = new URLSearchParams(u.searchParams);
+    passthrough.delete('page');
+    // `captured` tells the viewer "the install capture opened this",
+    // which lets it navigate the tab away on its own. That claim is only
+    // the service worker's to make — this is the one way a web page
+    // could put a param onto an extension page, so it does not carry.
+    passthrough.delete(CAPTURED_PARAM);
+    // Note: passthrough.toString() uses application/x-www-form-urlencoded
+    // encoding (spaces → `+`, literal `+` → `%2B`). End-to-end loss-less
+    // for consumers that decode via URLSearchParams; consumers that
+    // hand-parse the query should be aware of this round-trip.
+    const qs = passthrough.toString();
+    return chrome.runtime.getURL(page) + (qs ? `?${qs}` : '');
+}
+export function installDeepLinkRedirect() {
+    const wn = chrome.webNavigation;
+    if (!wn) {
+        console.info('[SourceMonkey] chrome.webNavigation not available; deep-link redirect disabled');
+        return;
+    }
+    wn.onBeforeNavigate.addListener((d) => {
+        if (d.frameId !== 0)
+            return;
+        const target = buildDeepLinkTarget(d.url);
+        if (!target)
+            return;
+        // Tab may have closed between the event firing and our update
+        // landing; ignore the resulting rejection.
+        chrome.tabs.update(d.tabId, { url: target }).catch(() => { });
+    }, 
+    // Cheap pre-filter so we don't run on every navigation. The
+    // listener does the authoritative check; this just narrows the
+    // event volume.
+    { url: [{ urlPrefix: REDIRECT_URL }] });
+}