sourcemonkey 0.0.0-stage → 0.5.0

package/dist/extension/storage-breakdown.js

@@ -0,0 +1,253 @@
+// Where `chrome.storage.local` goes, script by script and file by file,
+// for the storage debug page (src/extension/debug/storage.ts). Pure:
+// takes the rows a `get(null)` read returns.
+//
+// Sizes are measured as storage-usage.ts measures them (key + JSON
+// value, in UTF-8 bytes), so they agree with the Options page's table.
+//
+// What a script's storage is made of:
+//   - `script`: its body, a `blob:` row (docs/storage.md#content-blobs).
+//   - `metadata`: the `script:<id>` row itself, without any body.
+//   - `require` / `resource`: each file, a `blob:` row.
+//   - For a script sm-dev pushed (a scratch script): sm-dev's copy of
+//     its text, and each file it pushed from disk.
+// A body still inline in a format 1 row (not yet migrated) is counted
+// as its own file, and taken out of the row's metadata.
+import { blobKey, BLOB_PREFIX } from './script-blobs.js';
+import { collectionKey, SCRIPT_PREFIX } from './structural-keys.js';
+import { VALUE_PREFIX as GM_VALUE_PREFIX } from './gm-values.js';
+import { isScratchUrl, SCRATCH_FILES_KEY_PREFIX, SCRATCH_SOURCE_KEY_PREFIX, SCRATCH_TEXT_KEY_PREFIX, scratchFilesKey, scratchSourceKey, scratchTextKey, } from './location-kinds.js';
+import { effectiveDisplayName } from './collection-display.js';
+import { compareScriptNames, displayLocation, scriptDisplayName } from '../script-display.js';
+import { jsonBytes, rowBytes } from './storage-usage.js';
+const SCRATCH_PREFIXES = [SCRATCH_TEXT_KEY_PREFIX, SCRATCH_FILES_KEY_PREFIX, SCRATCH_SOURCE_KEY_PREFIX];
+const str = (v) => (typeof v === 'string' ? v : '');
+export function buildStorageBreakdown(rows) {
+    // File key → its size and uses. A blob's key is its row key; a body
+    // stored anywhere else is unique, keyed by where it is.
+    const files = new Map();
+    const addUse = (key, item, use) => {
+        const entry = files.get(key);
+        if (entry)
+            entry.uses.push(use);
+        else
+            files.set(key, { key, bytes: item.bytes, uses: [use], ...(item.missing ? { missing: true } : {}) });
+    };
+    // A blob's size is its row's. A ref to a missing blob is sized from
+    // the ref (its content's length, not what storing it would take), so
+    // the script still shows roughly what it's meant to hold.
+    const blobSize = (ref) => {
+        const key = blobKey(str(ref.hash));
+        if (key in rows)
+            return { bytes: rowBytes(key, rows[key]) };
+        return { bytes: typeof ref.size === 'number' ? ref.size : 0, missing: true };
+    };
+    // sm-dev rows some script accounts for; the rest are leftovers.
+    const claimedScratch = new Set();
+    const collectionNames = new Map();
+    const collectionName = (id) => {
+        let name = collectionNames.get(id);
+        if (name === undefined) {
+            const c = rows[collectionKey(id)];
+            name = c ? effectiveDisplayName(c) : '';
+            collectionNames.set(id, name);
+        }
+        return name;
+    };
+    // Per script: its ref and the file keys of its items, in order.
+    const scriptRefs = new Map();
+    const pending = [];
+    for (const [rowKey, value] of Object.entries(rows)) {
+        if (!rowKey.startsWith(SCRIPT_PREFIX) || !value || typeof value !== 'object')
+            continue;
+        const row = value;
+        const collectionId = str(row.collectionId);
+        const relativePath = str(row.relativePath);
+        const ref = {
+            scriptId: rowKey.slice(SCRIPT_PREFIX.length),
+            collectionId: collectionId && collectionKey(collectionId) in rows ? collectionId : '',
+            collectionName: collectionName(collectionId),
+            scriptName: scriptDisplayName({ header: row.header ?? null, relativePath }),
+        };
+        scriptRefs.set(ref.scriptId, ref);
+        const items = [];
+        const use = (item, key) => {
+            items.push({ item, key });
+            addUse(key, item, { ...ref, kind: item.kind, name: item.name, location: item.location });
+        };
+        // Bodies inline in the row come out of its metadata.
+        let inline = 0;
+        const scriptLocation = displayLocation(str(row.fileUrl) || relativePath);
+        if (typeof row.bodyBlobRef?.hash === 'string') {
+            use({ kind: 'script', location: scriptLocation, ...blobSize(row.bodyBlobRef) }, BLOB_PREFIX + row.bodyBlobRef.hash);
+        }
+        else if (typeof row.bodyText === 'string') {
+            const bytes = jsonBytes(row.bodyText);
+            inline += bytes;
+            use({ kind: 'script', location: scriptLocation, bytes }, `${rowKey}#body`);
+        }
+        const requires = Array.isArray(row.requires) ? row.requires : [];
+        requires.forEach((r, i) => {
+            const location = displayLocation(str(r.url));
+            if (typeof r.blobRef?.hash === 'string') {
+                use({ kind: 'require', location, ...blobSize(r.blobRef) }, BLOB_PREFIX + r.blobRef.hash);
+            }
+            else if (typeof r.source === 'string') {
+                const bytes = jsonBytes(r);
+                inline += bytes;
+                use({ kind: 'require', location, bytes }, `${rowKey}#require${i}`);
+            }
+        });
+        const resources = Array.isArray(row.resources) ? row.resources : [];
+        resources.forEach((r, i) => {
+            const name = str(r.name);
+            const location = displayLocation(str(r.url));
+            if (typeof r.blobRef?.hash === 'string') {
+                use({ kind: 'resource', name, location, ...blobSize(r.blobRef) }, BLOB_PREFIX + r.blobRef.hash);
+            }
+            else if (typeof r.bytesBase64 === 'string') {
+                const bytes = jsonBytes(r);
+                inline += bytes;
+                use({ kind: 'resource', name, location, bytes }, `${rowKey}#resource${i}`);
+            }
+        });
+        items.push({ item: { kind: 'metadata', bytes: Math.max(0, rowBytes(rowKey, value) - inline) } });
+        // sm-dev's own rows for a scratch script: its text (with the
+        // record of where on disk it came from), and the files it pushed.
+        if (isScratchUrl(relativePath)) {
+            const textKey = scratchTextKey(relativePath);
+            const sourceKey = scratchSourceKey(relativePath);
+            const filesKey = scratchFilesKey(relativePath);
+            for (const key of [textKey, sourceKey, filesKey])
+                claimedScratch.add(key);
+            if (textKey in rows || sourceKey in rows) {
+                const bytes = (textKey in rows ? rowBytes(textKey, rows[textKey]) : 0)
+                    + (sourceKey in rows ? rowBytes(sourceKey, rows[sourceKey]) : 0);
+                use({ kind: 'smdev-text', bytes }, textKey);
+            }
+            const pushed = rows[filesKey];
+            if (pushed && typeof pushed === 'object') {
+                for (const [fileRef, file] of Object.entries(pushed)) {
+                    // The entry's share of the row: its key and its value.
+                    const bytes = jsonBytes(fileRef) + 1 + jsonBytes(file);
+                    use({ kind: 'smdev-file', location: displayLocation(str(file?.url) || fileRef), bytes }, `${filesKey}#${fileRef}`);
+                }
+            }
+        }
+        pending.push({ ref, items });
+    }
+    const scripts = pending.map(({ ref, items }) => {
+        const full = items.map(({ item, key }) => ({
+            ...item,
+            shared: key === undefined ? 1 : files.get(key).uses.length,
+        }));
+        return {
+            ...ref,
+            bytes: full.reduce((sum, it) => sum + it.bytes, 0),
+            shared: Math.max(1, ...full.map((it) => it.shared)),
+            items: full,
+        };
+    });
+    const unused = [];
+    const values = new Map();
+    for (const [key, value] of Object.entries(rows)) {
+        if (key.startsWith(BLOB_PREFIX)) {
+            if (!files.has(key))
+                unused.push({ key, bytes: rowBytes(key, value), uses: [] });
+        }
+        else if (SCRATCH_PREFIXES.some((p) => key.startsWith(p))) {
+            if (!claimedScratch.has(key))
+                unused.push({ key, bytes: rowBytes(key, value), uses: [] });
+        }
+        else if (key.startsWith(GM_VALUE_PREFIX)) {
+            // `gmval:<scriptId>:<name>`
+            const scriptId = key.slice(GM_VALUE_PREFIX.length).split(':', 1)[0];
+            let entry = values.get(scriptId);
+            if (!entry) {
+                entry = { scriptId, script: scriptRefs.get(scriptId), bytes: 0, count: 0 };
+                values.set(scriptId, entry);
+            }
+            entry.bytes += rowBytes(key, value);
+            entry.count++;
+        }
+    }
+    return { scripts, files: [...files.values()], unused, values: [...values.values()] };
+}
+export function fileIdentity(file) {
+    const [first, ...rest] = file.uses;
+    if (!first || rest.some((u) => u.kind !== first.kind)) {
+        return { kind: null, sameName: false, sameLocation: false };
+    }
+    return {
+        kind: first.kind,
+        sameName: rest.every((u) => u.name === first.name),
+        sameLocation: rest.every((u) => u.location === first.location),
+        name: first.name,
+        location: first.location,
+    };
+}
+// Numbers start largest first; names start A to Z.
+export function defaultSortDir(key) {
+    return key === 'collection' || key === 'script' ? 'asc' : 'desc';
+}
+function compareNames(a, b) {
+    return compareScriptNames(a.collectionName, b.collectionName) || compareScriptNames(a.scriptName, b.scriptName);
+}
+function compareBy(key, dir) {
+    const sign = dir === 'asc' ? 1 : -1;
+    return (a, b) => {
+        let c = 0;
+        if (key === 'collection')
+            c = compareScriptNames(a.collectionName, b.collectionName);
+        else if (key === 'script')
+            c = compareScriptNames(a.scriptName, b.scriptName);
+        else if (key === 'size')
+            c = a.bytes - b.bytes;
+        else if (key === 'shared')
+            c = a.shared - b.shared;
+        else
+            c = a.count - b.count;
+        return sign * c || compareNames(a, b);
+    };
+}
+const KIND_ORDER = ['script', 'require', 'resource', 'smdev-text', 'smdev-file', 'metadata'];
+// Scripts by the column; each script's items largest first.
+export function sortScripts(scripts, key, dir) {
+    const cmp = compareBy(key, dir);
+    return scripts
+        .map((s) => ({
+        ...s,
+        items: [...s.items].sort((a, b) => b.bytes - a.bytes
+            || KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind)
+            || (a.location ?? '').localeCompare(b.location ?? '')),
+    }))
+        .sort((a, b) => cmp({ ...a, count: 0 }, { ...b, count: 0 }));
+}
+// Files sort only by size or shared copies: a file has no one
+// collection or script to sort by. Ties go to the other of the two,
+// largest first, then to the first use's collection and script. Each
+// file's uses are listed by collection, then script.
+export function sortFiles(files, key, dir) {
+    const sign = dir === 'asc' ? 1 : -1;
+    const size = (a, b) => a.bytes - b.bytes;
+    const shared = (a, b) => a.uses.length - b.uses.length;
+    const [primary, secondary] = key === 'size' ? [size, shared] : [shared, size];
+    const firstUse = (f) => f.uses[0] ?? { collectionName: '', scriptName: '' };
+    return files
+        .map((f) => ({ ...f, uses: [...f.uses].sort(compareNames) }))
+        .sort((a, b) => sign * primary(a, b)
+        || -secondary(a, b)
+        || compareNames(firstUse(a), firstUse(b))
+        || a.key.localeCompare(b.key));
+}
+export function sortValues(values, key, dir) {
+    const asSortable = (v) => ({
+        collectionName: v.script?.collectionName ?? '',
+        scriptName: v.script?.scriptName ?? v.scriptId,
+        bytes: v.bytes,
+        shared: 0,
+        count: v.count,
+    });
+    const cmp = compareBy(key, dir);
+    return [...values].sort((a, b) => cmp(asSortable(a), asSortable(b)));
+}

package/dist/extension/storage-scan.js

@@ -0,0 +1,86 @@
+// Whole-store reads, in one place: `chrome.storage.local.get(null)`
+// (`scanAllStorage`), and the narrower read of only the rows a caller
+// wants (`scanStorageRows`), which most callers use now.
+//
+// A `get(null)` returns EVERY row the extension owns — every script
+// body, every `@require`/`@resource` payload, every `gmval:` row — even
+// when the caller wants one prefix. On a small profile that is
+// invisible; on a real one it is megabytes, and the cost lands in two
+// places, only one of which is obvious:
+//
+//   - the read itself, on Chrome's storage thread; and
+//   - deserializing the result into JS objects, which runs on the
+//     CALLING context's single thread and blocks it. While that runs,
+//     every unrelated pending promise callback in that context waits —
+//     so a scan can inflate a phase that has nothing to do with it.
+//
+// The second effect is why these are worth naming individually. A
+// reload fast-path phase measured at ~130ms for a point read of a
+// small row is not explained by that row; it is explained by whatever
+// else was on the thread. Without a per-scan line there is no way to
+// tell those apart from the outside.
+//
+// Gated on the same debug-logging toggle as the phase timers, and the
+// wrapper is a plain pass-through when it's off.
+import { debugLoggingPending, debugLoggingSettled, isDebugLoggingEnabled } from '../debug-log.js';
+// Same rounding as the phase timers on purpose: these lines are read
+// against phase numbers on the same console, and two formats that
+// drift would make that comparison quietly wrong.
+import { formatMs } from '../phase-timing.js';
+import { formatBytes } from '../script-display.js';
+// Runs `chrome.storage.local.get(null)`, reporting what it cost and who
+// asked. `reason` should name the CALLER's purpose ("gm snapshot",
+// "match index"), not the mechanism — the mechanism is the same every
+// time, and the caller is the thing a reader needs to identify.
+export async function scanAllStorage(reason) {
+    return timeStorageRead(reason, () => chrome.storage.local.get(null));
+}
+// The rows whose keys `keep` accepts, and nothing else: no script
+// bodies (each in its own `blob:` row) and no GM values. Lists the keys,
+// then reads the wanted ones, which costs far less than a `get(null)`
+// once the rest is megabytes.
+export async function scanStorageRows(reason, keep) {
+    return timeStorageRead(reason, async () => {
+        const keys = (await chrome.storage.local.getKeys()).filter(keep);
+        return keys.length > 0 ? await chrome.storage.local.get(keys) : {};
+    });
+}
+// Same line for a read that is deliberately NARROW, so a caller that
+// used to scan and now doesn't reports in the units it is being
+// compared against. `reason` should carry the shape (`gm snapshot
+// (narrow)`) — the point of the line is the contrast.
+// A `null` result means the read didn't happen (the caller fell back to
+// something else) and nothing is logged — a line reporting `0 row(s)`
+// for a read that never ran would be worse than silence.
+//
+// A read made at a worker's start, before the debug setting has been
+// read, is timed anyway, and its line printed once the setting turns
+// out to be on: the row cache's load is one of those. That line can
+// then come after lines for work that started later.
+export async function timeStorageRead(reason, read) {
+    const pending = debugLoggingPending();
+    if (!isDebugLoggingEnabled() && !pending)
+        return await read();
+    const start = performance.now();
+    const rows = await read();
+    const ms = performance.now() - start;
+    if (rows === null)
+        return rows;
+    if (pending) {
+        void debugLoggingSettled().then((on) => { if (on)
+            logStorageRead(reason, ms, rows); });
+        return rows;
+    }
+    logStorageRead(reason, ms, rows);
+    return rows;
+}
+function logStorageRead(reason, ms, rows) {
+    const keys = Object.keys(rows);
+    const head = `[SourceMonkey] timing: storage scan (${reason}): ${formatMs(ms)}, ${keys.length} keys`;
+    // The size comes from Chrome, which keeps it for each stored value,
+    // rather than from serializing the rows here: on a store of several
+    // MB that took tens of ms on this thread, inside whatever phase the
+    // caller was timing. Not awaited, so the caller never waits on it;
+    // the line prints when the answer arrives.
+    chrome.storage.local.getBytesInUse(keys).then((bytes) => console.log(`${head}, ${formatBytes(bytes)}`), () => console.log(head));
+}

package/dist/extension/storage-usage.js

@@ -0,0 +1,194 @@
+// Breakdown of what SourceMonkey keeps in `chrome.storage.local`, for the
+// Options page's usage table. Pure: takes the rows a `get(null)` read
+// returns and sorts them into the kinds a user would recognize.
+//
+// Sizes are measured the way Chrome charges them: the key plus the
+// JSON-serialized value, in UTF-8 bytes. They are close to
+// `getBytesInUse`, not identical to it, so the page takes its total
+// from Chrome and lets "Other" absorb the difference (see
+// `withRemainder`). `toWholeKb` then rounds so the shown sizes add up.
+//
+// `chrome.storage.session` isn't covered: it holds only this session's
+// logs and tab state, has its own quota, and is nowhere near filling.
+import { COLLECTION_PREFIX, COLLECTIONS_INDEX_KEY, SCRIPT_PREFIX } from './structural-keys.js';
+import { BLOB_PREFIX } from './script-blobs.js';
+import { VALUE_PREFIX as GM_VALUE_PREFIX } from './gm-values.js';
+import { isIconCacheKey } from './site-icon.js';
+import { SCRATCH_FILES_KEY_PREFIX, SCRATCH_SOURCE_KEY_PREFIX, SCRATCH_TEXT_KEY_PREFIX, } from './location-kinds.js';
+const encoder = new TextEncoder();
+export function jsonBytes(value) {
+    return encoder.encode(JSON.stringify(value) ?? '').length;
+}
+// What Chrome charges for one row. Shared with the storage debug page
+// (storage-breakdown.ts), so its sizes agree with this table.
+export function rowBytes(key, value) {
+    return encoder.encode(key).length + jsonBytes(value);
+}
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+// sm-dev's scratch scripts: the text, its pushed files, and its origin.
+const SCRATCH_PREFIXES = [
+    SCRATCH_TEXT_KEY_PREFIX, SCRATCH_FILES_KEY_PREFIX, SCRATCH_SOURCE_KEY_PREFIX,
+];
+function startsWithAny(key, prefixes) {
+    return prefixes.some((p) => key.startsWith(p));
+}
+// `chrome.storage.local`. Bodies live in shared `blob:` rows
+// (docs/storage.md#content-blobs); each is counted once, under the kind
+// of the first row found pointing at it: a script body, a `@require`,
+// or a `@resource`. A blob nothing points at (left by a remove, or a
+// refresh that replaced a body, until cleanup deletes it)
+// gets its own row. A format 1 row, not yet migrated, carries its
+// `@require` / `@resource` bodies inline, so those are split out of the
+// row instead.
+export function summarizeLocalStorage(rows) {
+    let scripts = 0, scriptBytes = 0;
+    let requires = 0, requireBytes = 0;
+    let resources = 0, resourceBytes = 0;
+    let icons = 0, iconBytes = 0;
+    let values = 0, valueBytes = 0;
+    const valueScripts = new Set();
+    let scratch = 0, scratchBytes = 0;
+    let collections = 0, collectionBytes = 0;
+    let otherBytes = 0;
+    // Blob key → the kind whose size it counts under (the first found).
+    const claimed = new Map();
+    // Per kind: files stored as blobs, and their distinct blobs. A blob
+    // shared across kinds is distinct in each, though sized under one.
+    const withRef = { script: 0, require: 0, resource: 0 };
+    const distinct = { script: new Set(), require: new Set(), resource: new Set() };
+    const claim = (ref, kind) => {
+        const hash = ref?.hash;
+        if (typeof hash !== 'string')
+            return;
+        const key = BLOB_PREFIX + hash;
+        withRef[kind]++;
+        distinct[kind].add(key);
+        if (!claimed.has(key))
+            claimed.set(key, kind);
+    };
+    for (const [key, value] of Object.entries(rows)) {
+        if (!key.startsWith(SCRIPT_PREFIX))
+            continue;
+        const row = (value ?? {});
+        const req = Array.isArray(row.requires) ? row.requires : [];
+        const res = Array.isArray(row.resources) ? row.resources : [];
+        const inlineReq = req.filter((r) => typeof r.source === 'string');
+        const inlineRes = res.filter((r) => typeof r.bytesBase64 === 'string');
+        const reqBytes = inlineReq.length ? jsonBytes(inlineReq) : 0;
+        const resBytes = inlineRes.length ? jsonBytes(inlineRes) : 0;
+        scripts++;
+        scriptBytes += rowBytes(key, value) - reqBytes - resBytes;
+        requires += req.length;
+        requireBytes += reqBytes;
+        resources += res.length;
+        resourceBytes += resBytes;
+        claim(row.bodyBlobRef, 'script');
+        for (const r of req)
+            claim(r.blobRef, 'require');
+        for (const r of res)
+            claim(r.blobRef, 'resource');
+    }
+    let unused = 0, unusedBytes = 0;
+    for (const [key, value] of Object.entries(rows)) {
+        if (key.startsWith(SCRIPT_PREFIX))
+            continue;
+        const bytes = rowBytes(key, value);
+        if (key.startsWith(BLOB_PREFIX)) {
+            const kind = claimed.get(key);
+            if (kind === 'script')
+                scriptBytes += bytes;
+            else if (kind === 'require')
+                requireBytes += bytes;
+            else if (kind === 'resource')
+                resourceBytes += bytes;
+            else {
+                unused++;
+                unusedBytes += bytes;
+            }
+        }
+        else if (isIconCacheKey(key)) {
+            icons++;
+            iconBytes += bytes;
+        }
+        else if (key.startsWith(GM_VALUE_PREFIX)) {
+            // `gmval:<scriptId>:<name>`
+            values++;
+            valueBytes += bytes;
+            valueScripts.add(key.slice(GM_VALUE_PREFIX.length).split(':', 1)[0]);
+        }
+        else if (startsWithAny(key, SCRATCH_PREFIXES)) {
+            if (key.startsWith(SCRATCH_TEXT_KEY_PREFIX))
+                scratch++;
+            scratchBytes += bytes;
+        }
+        else if (key.startsWith(COLLECTION_PREFIX)) {
+            collections++;
+            collectionBytes += bytes;
+        }
+        else if (key === COLLECTIONS_INDEX_KEY) {
+            collectionBytes += bytes;
+        }
+        else {
+            otherBytes += bytes;
+        }
+    }
+    // "(N unique)" when files stored as blobs share some. A file not
+    // stored as a blob (never loaded, or not yet migrated) counts as
+    // unique, so it can't make the count look like sharing.
+    const total = { script: scripts, require: requires, resource: resources };
+    const withUnique = (text, kind) => {
+        const unique = total[kind] - (withRef[kind] - distinct[kind].size);
+        return unique < total[kind] ? `${text} (${unique} unique)` : text;
+    };
+    return [
+        { label: 'Scripts', count: withUnique(plural(scripts, 'script'), 'script'), bytes: scriptBytes },
+        { label: '@require files', count: withUnique(plural(requires, 'file'), 'require'), bytes: requireBytes },
+        { label: '@resource files', count: withUnique(plural(resources, 'file'), 'resource'), bytes: resourceBytes },
+        {
+            label: 'Script values (GM_setValue)',
+            count: `${plural(values, 'value')} in ${plural(valueScripts.size, 'script')}`,
+            bytes: valueBytes,
+        },
+        { label: 'Site and script icons', count: plural(icons, 'icon'), bytes: iconBytes },
+        { label: 'Scripts run by sm-dev', count: plural(scratch, 'script'), bytes: scratchBytes },
+        { label: 'Collections', count: plural(collections, 'collection'), bytes: collectionBytes },
+        { label: 'Stored files no script uses', count: plural(unused, 'file'), bytes: unusedBytes },
+        { label: 'Other', count: '', bytes: otherBytes },
+    ];
+}
+// Makes the rows add up to Chrome's own total: the last row ("Other")
+// takes whatever our measurement and `getBytesInUse` disagree on, so
+// the table never shows parts that sum to more or less than the whole.
+export function withRemainder(rows, total) {
+    const measured = rows.slice(0, -1).reduce((sum, r) => sum + r.bytes, 0);
+    const last = rows[rows.length - 1];
+    return [...rows.slice(0, -1), { ...last, bytes: Math.max(0, total - measured) }];
+}
+// Whole-KB sizes that sum exactly to the rounded total, by giving the
+// leftover KB to the rows that lost most to rounding (largest
+// remainder). Rounding each row on its own makes a column whose parts
+// visibly don't add up to the total under it.
+export function toWholeKb(rows, total) {
+    const exact = rows.map((r) => r.bytes / 1024);
+    const kb = exact.map(Math.floor);
+    let left = Math.round(total / 1024) - kb.reduce((a, b) => a + b, 0);
+    const order = exact
+        .map((x, i) => ({ i, frac: x - Math.floor(x) }))
+        .sort((a, b) => b.frac - a.frac);
+    for (let n = 0; left > 0 && n < order.length; n++, left--)
+        kb[order[n].i]++;
+    // Short of the total only by rounding above. Over it means the rows
+    // were measured larger than Chrome's total (`withRemainder` clamps
+    // "Other" at 0): take the excess back from the largest rows, which
+    // it changes least. The excess is a few KB at most, so one KB at a
+    // time is cheap.
+    for (; left < 0; left++) {
+        const i = kb.indexOf(Math.max(...kb));
+        if (i < 0 || kb[i] === 0)
+            break;
+        kb[i]--;
+    }
+    return kb;
+}

package/dist/extension/structural-keys.js

@@ -0,0 +1,29 @@
+// The storage key layout of the structural rows (the collection index,
+// collection rows, script rows), and the active-times key the worker's
+// row cache keeps beside them. Split from script-store.ts, which owns
+// those rows, so a page that only watches for changes to them (the
+// toolbar popup) doesn't load the store and everything it imports.
+export const COLLECTIONS_INDEX_KEY = 'collections';
+export const COLLECTION_PREFIX = 'collection:';
+export const SCRIPT_PREFIX = 'script:';
+export const collectionKey = (id) => `${COLLECTION_PREFIX}${id}`;
+export const scriptKey = (id) => `${SCRIPT_PREFIX}${id}`;
+// Every script's active times (`writeEnablement` in script-store.ts). Not
+// a structural row, so `isStructuralKey` leaves it out; here so the
+// worker's row cache can keep it without importing the store.
+export const ENABLEMENT_TIMES_KEY = 'enablementTimes';
+// Does a `chrome.storage.local` change touch the structural rows — the
+// collection index, a collection, or a script? Pages watching for
+// "something I display moved" ask the module that owns the key layout
+// instead of re-deriving the prefixes, where a rename here would leave
+// them silently watching keys that no longer exist.
+export function touchesStructuralRows(keys) {
+    for (const key of keys) {
+        if (isStructuralKey(key))
+            return true;
+    }
+    return false;
+}
+export function isStructuralKey(key) {
+    return key === COLLECTIONS_INDEX_KEY || key.startsWith(collectionKey('')) || key.startsWith(scriptKey(''));
+}

package/dist/extension/sw-teardown.js

@@ -0,0 +1,36 @@
+// Keep service-worker (SW) teardown noise out of chrome://extensions.
+//
+// When Chrome destroys the extension's SW — on every reload of the
+// unpacked extension, and on idle termination — any `chrome.*` call
+// still in flight rejects with `Error: No SW`. The SW's startup path
+// fires many fire-and-forget storage reads (`void ensureLoaded()`
+// and friends in background.ts), so a reload that lands while they're
+// pending produces one unhandled rejection each, and Chrome lists
+// every one under the extension's Errors panel as if SourceMonkey had
+// crashed. Nothing is wrong: a dead SW has no work left to do.
+//
+// One handler here recognizes that rejection and marks it handled,
+// rather than a try/catch at every call site. Every other rejection
+// still surfaces as before.
+// Exact match on purpose: the string is Chrome's own (the extension
+// API binding's "worker is gone" rejection), it carries nothing else,
+// and a looser match could swallow a real failure that happened to
+// mention it. Accepts any object with a `message` rather than only
+// `Error` instances — the reason is created by the API bindings, not
+// necessarily by this realm's `Error`.
+export function isSwTeardownError(err) {
+    const message = typeof err === 'string'
+        ? err
+        : err?.message;
+    return message === 'No SW';
+}
+export function installSwTeardownHandler() {
+    self.addEventListener('unhandledrejection', (event) => {
+        if (!isSwTeardownError(event.reason))
+            return;
+        event.preventDefault();
+        // Stays in the SW's own DevTools console only (console.info is not
+        // forwarded to the Errors panel; .warn/.error are).
+        console.info('[SourceMonkey] ignoring a chrome.* call that was cut off by service-worker shutdown');
+    });
+}