@arraypress/extension-kit 1.10.0 → 1.11.0

package/src/testing/e2e.js

@@ -96,7 +96,11 @@ export async function extensionProfile(chromium, dir, { prefix = 'extension-', a
         ...options,
         args: [`--disable-extensions-except=${dir}`, `--load-extension=${dir}`, ...args],
       });
-      const worker = context.serviceWorkers()[0] ?? await context.waitForEvent('serviceworker');
+      const worker = context.serviceWorkers()[0] ?? await context.waitForEvent('serviceworker', { timeout: 15_000 }).catch(async () => {
+        // Chrome refused the extension (a manifest or `_locales` error) or it has no worker: nothing to wait for.
+        await context.close();
+        throw new Error(`The extension at ${dir} didn't start a service worker: Chrome may have refused to load it (check its manifest and _locales at chrome://extensions)`);
+      });
       const extensionId = new URL(worker.url()).host;
       return {
         context,
@@ -137,6 +141,56 @@ export async function launchExtension(chromium, dir, options = {}) {
   };
 }
 
+/**
+ * Stop the extension's service worker, as Chrome does after 30 seconds idle: its globals,
+ * timers and anything else kept in memory are gone; storage, alarms and registered listeners
+ * stay. Chrome never does this by itself in an e2e run (Playwright's debugger keeps the worker
+ * alive), so a check that state survives a restart has to ask for it. Done through the
+ * DevTools protocol from a page of the extension (`ServiceWorker.stopWorker`), and, unless
+ * `start` is false, the worker is started again with no event (`ServiceWorker.startWorker`).
+ *
+ * `launched.worker` stays the handle to use: Playwright keeps it across the restart. Anything a
+ * test put in the old worker (`recordIconCalls`, a patched `chrome.*` function) is gone with it.
+ *
+ * @param {Pick<LaunchedExtension, 'context' | 'worker' | 'extensionId' | 'url'>} launched - From {@link launchExtension}.
+ * @param {{start?: boolean, page?: string}} [options] - `start: false` leaves the worker stopped, for
+ *   the next event (a message, an alarm, a tab) to start it as on a person's computer; `page`: a file
+ *   of the extension to open for the protocol session (default `manifest.json`).
+ * @returns {Promise<void>} Once the worker has stopped (and, with `start`, is running again).
+ * @throws {Error} When the worker isn't running, or doesn't stop or start in 10 s.
+ *
+ * @example
+ * await worker.evaluate(() => { globalThis.cache = { tab: 7 }; });
+ * await stopWorker(launched);
+ * await worker.evaluate(() => globalThis.cache); // undefined: what wasn't stored is gone
+ */
+export async function stopWorker({ context, worker, extensionId, url }, { start = true, page: file = 'manifest.json' } = {}) {
+  const page = await context.newPage();
+  try {
+    await page.goto(url(file));
+    const cdp = await context.newCDPSession(page);
+    /** @type {Map<string, {versionId: string, scriptURL: string, runningStatus: string}>} */
+    const versions = new Map();
+    cdp.on('ServiceWorker.workerVersionUpdated', (event) => {
+      for (const version of event.versions) versions.set(version.versionId, version);
+    });
+    await cdp.send('ServiceWorker.enable');
+    const own = () => [...versions.values()].filter((version) => version.scriptURL === worker.url());
+    const running = await until(() => own().find((version) => version.runningStatus === 'running'), 'the service worker to be running', 10_000);
+    await cdp.send('ServiceWorker.stopWorker', { versionId: running.versionId });
+    await until(() => own().every((version) => version.runningStatus === 'stopped'), 'the service worker to stop', 10_000);
+    if (start) {
+      await cdp.send('ServiceWorker.startWorker', { scopeURL: `chrome-extension://${extensionId}/` });
+      await until(() => own().some((version) => version.runningStatus === 'running'), 'the service worker to start again', 10_000);
+      // Running, and answering: its script has run again.
+      await worker.evaluate(() => true);
+    }
+    await cdp.detach();
+  } finally {
+    await page.close();
+  }
+}
+
 /**
  * Emulate colour schemes in the offscreen document: one CDP session attached
  * to it, reused for every change.
@@ -164,10 +218,12 @@ export async function offscreenEmulator(cdp, suffix = '/offscreen/offscreen.html
 
 /**
  * Wrap the worker's real `chrome.action.setIcon` so each call is recorded once
- * Chrome has taken it (a path Chrome can't load fails, and isn't recorded).
+ * Chrome has taken it (a path Chrome can't load fails, and isn't recorded):
+ * its `path`, or `'imageData'` for an icon given as pixels. The record lives
+ * in the worker: it's gone when the worker restarts ({@link stopWorker}).
  *
  * @param {Worker} worker - The extension's service worker.
- * @returns {Promise<() => Promise<unknown[]>>} Reads the recorded `path`s, oldest first.
+ * @returns {Promise<() => Promise<unknown[]>>} Reads the recorded icons, oldest first.
  */
 export async function recordIconCalls(worker) {
   await worker.evaluate(() => {
@@ -176,7 +232,7 @@ export async function recordIconCalls(worker) {
     const real = chrome.action.setIcon.bind(chrome.action);
     chrome.action.setIcon = /** @type {typeof chrome.action.setIcon} */ (async (/** @type {chrome.action.TabIconDetails} */ details) => {
       await real(details);
-      calls.push(details.path);
+      calls.push(details.path ?? (details.imageData ? 'imageData' : undefined));
     });
   });
   return () => worker.evaluate(() => /** @type {{iconCalls: unknown[]}} */ (/** @type {unknown} */ (globalThis)).iconCalls);
@@ -195,7 +251,8 @@ export const CHECK_MS = 60_000;
  *   whether it passed.
  * @property {(name: string) => void} fail Count a failure found outside any check (a page's
  *   uncaught error, say): printed now, listed and counted at the end.
- * @property {() => void} finish Print the tally, and exit with 1 if anything failed.
+ * @property {() => void} finish Print the tally, and exit with 1 if anything failed or no check ran at all
+ *   (a script that returned early, or whose filter matched nothing, hasn't passed).
  */
 
 /**
@@ -238,6 +295,11 @@ export function checkRunner({ timeout: runnerTimeout = CHECK_MS } = {}) {
     },
     finish() {
       console.log(`\n${passed} passed, ${failures.length} failed`);
+      if (!passed && !failures.length) {
+        console.log('  No checks ran.');
+        process.exit(1);
+        return;
+      }
       if (!failures.length) return;
       for (const failure of failures) console.log(`  - ${failure}`);
       process.exit(1);

package/src/testing/fake-model.d.ts

@@ -4,7 +4,9 @@
  * worker's or page's `globalThis`: Playwright's Chromium has no model). It
  * acts out what a real Chrome does: a model still to download (with
  * progress), one this computer can't run, a slow first session (the cold
- * start), a slow answer, an answer cut short by its signal, and a failure.
+ * start), a slow answer, an answer cut short by its signal, a failure, a
+ * session that's been destroyed (it answers nothing more), and a download
+ * asked for without a click (Chrome refuses it).
  * Moved here from Better Downloads' tests, so every extension that uses the
  * model tests against the same one.
  *
@@ -38,6 +40,12 @@ export type FakeModelState = {
      * Whether a download fails part way.
      */
     failDownload: boolean;
+    /**
+     * Whether a click is behind a `create()` that has to download the
+     * model (Chrome refuses one without: `NotAllowedError`). `null`, the default, reads the page's own
+     * `navigator.userActivation` (and takes it as given where there's none: Node, a worker).
+     */
+    userActivation: boolean | null;
 };
 export type FakeModelLog = {
     /**

package/src/testing/fake-model.js

@@ -4,7 +4,9 @@
  * worker's or page's `globalThis`: Playwright's Chromium has no model). It
  * acts out what a real Chrome does: a model still to download (with
  * progress), one this computer can't run, a slow first session (the cold
- * start), a slow answer, an answer cut short by its signal, and a failure.
+ * start), a slow answer, an answer cut short by its signal, a failure, a
+ * session that's been destroyed (it answers nothing more), and a download
+ * asked for without a click (Chrome refuses it).
  * Moved here from Better Downloads' tests, so every extension that uses the
  * model tests against the same one.
  *
@@ -25,6 +27,9 @@
  * @property {(prompt: string, options: PromptOptions) => string} answer The answer to a prompt.
  * @property {boolean} failPrompt Whether answers fail (the model gave up).
  * @property {boolean} failDownload Whether a download fails part way.
+ * @property {boolean | null} userActivation Whether a click is behind a `create()` that has to download the
+ *   model (Chrome refuses one without: `NotAllowedError`). `null`, the default, reads the page's own
+ *   `navigator.userActivation` (and takes it as given where there's none: Node, a worker).
  */
 
 /**
@@ -77,7 +82,7 @@ function wait(ms, signal) {
 export function fakeLanguageModel(initial = {}) {
   /** @type {FakeModelState} */
   const state = {
-    availability: 'available', createMs: 0, answerMs: 0, answer: () => 'Fake answer', failPrompt: false, failDownload: false, ...initial,
+    availability: 'available', createMs: 0, answerMs: 0, answer: () => 'Fake answer', failPrompt: false, failDownload: false, userActivation: null, ...initial,
   };
   /** @type {FakeModelLog} */
   const log = { availability: [], created: [], prompts: [], promptOptions: [], cloned: 0, aborted: 0, destroyed: 0 };
@@ -87,27 +92,40 @@ export function fakeLanguageModel(initial = {}) {
    *
    * @returns {LanguageModelSession} It.
    */
-  const session = () => ({
-    async prompt(prompt, options = {}) {
-      log.prompts.push(prompt);
-      log.promptOptions.push(options);
-      try {
-        await wait(state.answerMs, options.signal);
-      } catch (error) {
-        log.aborted++;
-        throw error;
-      }
-      if (state.failPrompt) throw new DOMException('The model failed', 'UnknownError');
-      return state.answer(prompt, options);
-    },
-    async clone() {
-      log.cloned++;
-      return session();
-    },
-    destroy() {
-      log.destroyed++;
-    },
-  });
+  const session = () => {
+    let destroyed = false;
+    /** Chrome's refusal to use a session that's been destroyed. */
+    const refuseDestroyed = () => {
+      if (destroyed) throw new DOMException('The session has been destroyed.', 'InvalidStateError');
+    };
+    return /** @type {LanguageModelSession} */ ({
+      async prompt(prompt, options = {}) {
+        refuseDestroyed();
+        log.prompts.push(prompt);
+        log.promptOptions.push(options);
+        try {
+          await wait(state.answerMs, options.signal);
+        } catch (error) {
+          log.aborted++;
+          throw error;
+        }
+        // Destroyed while it was answering: Chrome stops the answer.
+        if (destroyed) throw new DOMException('The session has been destroyed.', 'AbortError');
+        if (state.failPrompt) throw new DOMException('The model failed', 'UnknownError');
+        return state.answer(prompt, options);
+      },
+      async clone() {
+        refuseDestroyed();
+        log.cloned++;
+        return session();
+      },
+      destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        log.destroyed++;
+      },
+    });
+  };
 
   return {
     state,
@@ -121,6 +139,9 @@ export function fakeLanguageModel(initial = {}) {
       log.created.push(options);
       if (state.availability === 'unavailable') throw new DOMException('Not supported', 'NotSupportedError');
       if (state.availability !== 'available') {
+        // Chrome starts a download only from a click (transient user activation).
+        const active = state.userActivation ?? /** @type {{navigator?: {userActivation?: {isActive: boolean}}}} */ (globalThis).navigator?.userActivation?.isActive ?? true;
+        if (!active) throw new DOMException('Requires a user gesture when availability is "downloading" or "downloadable".', 'NotAllowedError');
         // A download, reported as Chrome reports it, then the model is here.
         const monitor = new EventTarget();
         options.monitor?.(monitor);

package/src/testing/fake-storage.d.ts

@@ -1,29 +1,60 @@
 /**
- * An in-memory `chrome.storage` for tests, behaving as Chrome does: values
- * are stored as JSON, `onChanged` fires only for values that changed, and
- * sync refuses an item over its 8,192-byte quota and more than 120 writes
- * (set or remove) a minute. Tests then check outcomes (what's stored), not
+ * An in-memory `chrome.storage` for tests, behaving as Chrome does (each point
+ * checked against Chromium): values are stored as Chrome converts them (what
+ * JSON can't hold is dropped, a `Date` is `{}`), `get` takes a key, keys, an
+ * object of defaults or nothing, `onChanged` fires only for values that
+ * changed (whatever order an object's keys come in), and every area has
+ * Chrome's quotas. Sync refuses an item over 8,192 bytes as Chrome counts them
+ * (`syncItemBytes`: UTF-8, `<` six bytes), more than 102,400 bytes or 512
+ * items in all, and more than 120 calls a minute or 1,800 an hour of `set`,
+ * `remove` or `clear` (each counted by itself, refused calls included); local
+ * and session hold 10 MB. Tests then check outcomes (what's stored), not
  * calls.
  *
  * @module testing/fake-storage
  */
 import type { StorageChange } from '../settings/storage.js';
 /** @import { StorageChange } from '../settings/storage.js' */
-/** Chrome Sync's write limit: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
+/** Chrome Sync's write limit a minute: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
 export declare const SYNC_WRITES_PER_MINUTE = 120;
+/** Chrome Sync's write limit an hour: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_HOUR`. */
+export declare const SYNC_WRITES_PER_HOUR = 1800;
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export declare const SYNC_QUOTA_BYTES = 102400;
+/** The most items sync holds (`chrome.storage.sync.MAX_ITEMS`). */
+export declare const SYNC_MAX_ITEMS = 512;
+/** What local and session each hold (`chrome.storage.local.QUOTA_BYTES`), without `unlimitedStorage`. */
+export declare const LOCAL_QUOTA_BYTES = 10485760;
 export type ChangeListener = (changes: Record<string, StorageChange>, area: string) => unknown;
+export type FakeEvent<L extends (...args: any[]) => unknown> = {
+    addListener: (listener: L) => void;
+    removeListener: (listener: L) => void;
+    hasListener: (listener: L) => boolean;
+};
 export type FakeArea = {
     /**
      * What it holds, to inspect (and seed) in tests.
      */
     data: Record<string, any>;
     /**
-     * How many writes it has taken.
+     * How many writes (`set`, `remove`, `clear`) it has taken.
      */
     writes: number;
-    get: (keys?: string | string[] | null) => Promise<Record<string, any>>;
+    /**
+     *   A key's or keys' items, an object's keys with its values for the missing ones, or everything.
+     */
+    get: (keys?: string | string[] | Record<string, unknown> | null) => Promise<Record<string, any>>;
     set: (items: Record<string, unknown>) => Promise<void>;
     remove: (keys: string | string[]) => Promise<void>;
+    clear: () => Promise<void>;
+    /**
+     * The bytes the keys' items (or all) take.
+     */
+    getBytesInUse: (keys?: string | string[] | null) => Promise<number>;
+    /**
+     * This area's changes.
+     */
+    onChanged: FakeEvent<(changes: Record<string, StorageChange>) => unknown>;
 };
 export type FakeChromeStorage = {
     /**
@@ -41,16 +72,12 @@ export type FakeChromeStorage = {
     /**
      * `chrome.storage.onChanged`.
      */
-    onChanged: {
-        addListener(listener: ChangeListener): void;
-    };
+    onChanged: FakeEvent<ChangeListener>;
     /**
      * Waits for every listener, including the changes those listeners make.
      */
     settled: () => Promise<void>;
 };
-/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
-export declare const SYNC_QUOTA_BYTES = 102400;
 /**
  * Make a fake `chrome.storage`.
  *
@@ -58,8 +85,9 @@ export declare const SYNC_QUOTA_BYTES = 102400;
  * @param {Record<string, unknown>} [initial.local] - What local holds.
  * @param {Record<string, unknown>} [initial.sync] - What sync holds.
  * @param {Record<string, unknown>} [initial.session] - What session holds.
- * @param {() => number} [initial.now] - The clock sync's write limit reads. Default `Date.now`.
+ * @param {() => number} [initial.now] - The clock sync's write limits read. Default `Date.now`.
  * @returns {FakeChromeStorage} The fake.
+ *
  * @example
  * const storage = fakeChromeStorage({ sync: { days: 3 } });
  * await store.save(storage, { days: 5 });

package/src/testing/fake-storage.js

@@ -1,33 +1,65 @@
 /**
- * An in-memory `chrome.storage` for tests, behaving as Chrome does: values
- * are stored as JSON, `onChanged` fires only for values that changed, and
- * sync refuses an item over its 8,192-byte quota and more than 120 writes
- * (set or remove) a minute. Tests then check outcomes (what's stored), not
+ * An in-memory `chrome.storage` for tests, behaving as Chrome does (each point
+ * checked against Chromium): values are stored as Chrome converts them (what
+ * JSON can't hold is dropped, a `Date` is `{}`), `get` takes a key, keys, an
+ * object of defaults or nothing, `onChanged` fires only for values that
+ * changed (whatever order an object's keys come in), and every area has
+ * Chrome's quotas. Sync refuses an item over 8,192 bytes as Chrome counts them
+ * (`syncItemBytes`: UTF-8, `<` six bytes), more than 102,400 bytes or 512
+ * items in all, and more than 120 calls a minute or 1,800 an hour of `set`,
+ * `remove` or `clear` (each counted by itself, refused calls included); local
+ * and session hold 10 MB. Tests then check outcomes (what's stored), not
  * calls.
  *
  * @module testing/fake-storage
  */
 
-import { MAX_SYNC_ITEM_BYTES } from '../settings/storage.js';
+import { MAX_SYNC_ITEM_BYTES, sameValue, syncItemBytes } from '../settings/storage.js';
 
 /** @import { StorageChange } from '../settings/storage.js' */
 
-/** Chrome Sync's write limit: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
+/** Chrome Sync's write limit a minute: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_MINUTE`. */
 export const SYNC_WRITES_PER_MINUTE = 120;
 
+/** Chrome Sync's write limit an hour: `chrome.storage.sync.MAX_WRITE_OPERATIONS_PER_HOUR`. */
+export const SYNC_WRITES_PER_HOUR = 1800;
+
+/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
+export const SYNC_QUOTA_BYTES = 102_400;
+
+/** The most items sync holds (`chrome.storage.sync.MAX_ITEMS`). */
+export const SYNC_MAX_ITEMS = 512;
+
+/** What local and session each hold (`chrome.storage.local.QUOTA_BYTES`), without `unlimitedStorage`. */
+export const LOCAL_QUOTA_BYTES = 10_485_760;
+
 /**
  * @typedef {(changes: Record<string, StorageChange>, area: string) => unknown} ChangeListener
  */
 
+/**
+ * An `onChanged` event.
+ *
+ * @template {(...args: any[]) => unknown} L
+ * @typedef {object} FakeEvent
+ * @property {(listener: L) => void} addListener
+ * @property {(listener: L) => void} removeListener
+ * @property {(listener: L) => boolean} hasListener
+ */
+
 /**
  * One fake storage area.
  *
  * @typedef {object} FakeArea
  * @property {Record<string, any>} data What it holds, to inspect (and seed) in tests.
- * @property {number} writes How many writes it has taken.
- * @property {(keys?: string | string[] | null) => Promise<Record<string, any>>} get
+ * @property {number} writes How many writes (`set`, `remove`, `clear`) it has taken.
+ * @property {(keys?: string | string[] | Record<string, unknown> | null) => Promise<Record<string, any>>} get
+ *   A key's or keys' items, an object's keys with its values for the missing ones, or everything.
  * @property {(items: Record<string, unknown>) => Promise<void>} set
  * @property {(keys: string | string[]) => Promise<void>} remove
+ * @property {() => Promise<void>} clear
+ * @property {(keys?: string | string[] | null) => Promise<number>} getBytesInUse The bytes the keys' items (or all) take.
+ * @property {FakeEvent<(changes: Record<string, StorageChange>) => unknown>} onChanged This area's changes.
  */
 
 /**
@@ -37,28 +69,79 @@ export const SYNC_WRITES_PER_MINUTE = 120;
  * @property {FakeArea} local `chrome.storage.local`.
  * @property {FakeArea} sync `chrome.storage.sync`, with Chrome's quotas.
  * @property {FakeArea} session `chrome.storage.session`.
- * @property {{addListener(listener: ChangeListener): void}} onChanged `chrome.storage.onChanged`.
+ * @property {FakeEvent<ChangeListener>} onChanged `chrome.storage.onChanged`.
  * @property {() => Promise<void>} settled Waits for every listener, including the changes those listeners make.
  */
 
+/** Stands for a value Chrome doesn't store (`undefined`, a function, `NaN`). */
+const DROPPED = Symbol('dropped');
+
 /**
- * Copy a value the way storage does, through JSON.
+ * A value as Chrome stores it: what JSON holds, copied; `undefined`, functions, symbols and
+ * numbers that aren't finite dropped from objects (`null` in arrays); any other object (a
+ * `Date`, a `RegExp`, a `Map`) as `{}`.
  *
- * @param {unknown} value - Anything JSON-able, or undefined.
+ * @param {unknown} value - What an extension gave `set`.
+ * @returns {unknown} The stored copy, or {@link DROPPED}.
+ */
+function asStored(value) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : DROPPED;
+  if (typeof value !== 'object') return DROPPED;
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      const stored = asStored(item);
+      return stored === DROPPED ? null : stored;
+    });
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return {};
+  return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, asStored(inner)]).filter(([, inner]) => inner !== DROPPED));
+}
+
+/**
+ * A copy of what's stored, as `get` and `onChanged` hand it out.
+ *
+ * @param {unknown} value - A stored value, or undefined.
  * @returns {any} The copy.
  */
-const viaJson = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
+const copied = (value) => (value === undefined ? undefined : structuredClone(value));
 
-/** All of sync's items together may take this many bytes (`chrome.storage.sync.QUOTA_BYTES`). */
-export const SYNC_QUOTA_BYTES = 102_400;
+/**
+ * An event's listeners.
+ *
+ * @template {(...args: any[]) => unknown} L
+ * @returns {FakeEvent<L> & {listeners: L[]}} The event, and who listens.
+ */
+function fakeEvent() {
+  /** @type {L[]} */
+  const listeners = [];
+  return {
+    listeners,
+    addListener: (listener) => { if (!listeners.includes(listener)) listeners.push(listener); },
+    removeListener: (listener) => { if (listeners.includes(listener)) listeners.splice(listeners.indexOf(listener), 1); },
+    hasListener: (listener) => listeners.includes(listener),
+  };
+}
 
 /**
- * The bytes an area's items take, as Chrome counts sync's: each key plus its value's JSON, in UTF-8.
+ * A limit on calls in a window of time, as Chrome's quota service keeps one: the window opens
+ * with the first call and takes so many; the first call after it has passed opens the next.
  *
- * @param {Record<string, unknown>} items - The items.
- * @returns {number} Bytes.
+ * @param {number} most - Calls a window.
+ * @param {number} ms - The window.
+ * @param {() => number} now - The clock.
+ * @returns {() => boolean} Counts a call; false when it's over the limit.
  */
-const totalBytes = (items) => Object.entries(items).reduce((sum, [key, value]) => sum + new TextEncoder().encode(key + JSON.stringify(value)).length, 0);
+function callLimit(most, ms, now) {
+  let opened = -Infinity;
+  let left = 0;
+  return () => {
+    if (now() >= opened + ms) [opened, left] = [now(), most];
+    left -= 1;
+    return left >= 0;
+  };
+}
 
 /**
  * Make a fake `chrome.storage`.
@@ -67,71 +150,89 @@ const totalBytes = (items) => Object.entries(items).reduce((sum, [key, value]) =
  * @param {Record<string, unknown>} [initial.local] - What local holds.
  * @param {Record<string, unknown>} [initial.sync] - What sync holds.
  * @param {Record<string, unknown>} [initial.session] - What session holds.
- * @param {() => number} [initial.now] - The clock sync's write limit reads. Default `Date.now`.
+ * @param {() => number} [initial.now] - The clock sync's write limits read. Default `Date.now`.
  * @returns {FakeChromeStorage} The fake.
+ *
  * @example
  * const storage = fakeChromeStorage({ sync: { days: 3 } });
  * await store.save(storage, { days: 5 });
  * assert.equal(storage.sync.data.days, 5);
  */
 export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = Date.now } = {}) {
-  /** @type {ChangeListener[]} */
-  const listeners = [];
+  /** @type {ReturnType<typeof fakeEvent<ChangeListener>>} */
+  const onChanged = fakeEvent();
   /** @type {unknown[]} */
   const running = [];
 
   /**
    * @param {string} name
    * @param {Record<string, unknown>} initialData
-   * @param {{quotaPerItem?: number, quotaBytes?: number, writesPerMinute?: number}} [limits]
+   * @param {{quotaPerItem?: number, quotaBytes: number, maxItems?: number, limited?: boolean}} limits
    * @returns {FakeArea}
    */
-  function area(name, initialData, { quotaPerItem, quotaBytes, writesPerMinute } = {}) {
+  function area(name, initialData, { quotaPerItem, quotaBytes, maxItems, limited = false }) {
     /** @type {Record<string, any>} */
-    const data = viaJson(initialData);
-    /** @type {number[]} */
-    const recent = [];
+    const data = /** @type {Record<string, any>} */ (asStored(initialData));
+    /** @type {ReturnType<typeof fakeEvent<(changes: Record<string, StorageChange>) => unknown>>} */
+    const areaChanged = fakeEvent();
+    /** Each function's own limits, as Chrome counts them. @type {Map<string, (() => boolean)[]>} */
+    const limits = new Map();
     /** @param {Record<string, StorageChange>} changes */
     const fire = (changes) => {
       if (!Object.keys(changes).length) return;
-      for (const listener of listeners) running.push(listener(viaJson(changes), name));
+      for (const listener of [...onChanged.listeners]) running.push(listener(copied(changes), name));
+      for (const listener of [...areaChanged.listeners]) running.push(listener(copied(changes)));
     };
-    /** A write, counted against the per-minute limit; refused over it, as Chrome does. */
-    const take = () => {
-      if (writesPerMinute) {
-        while (recent.length && recent[0] <= now() - 60_000) recent.shift();
-        if (recent.length >= writesPerMinute) throw new Error('This request exceeds the MAX_WRITE_OPERATIONS_PER_MINUTE quota.');
-        recent.push(now());
-      }
-      fake.writes++;
+    /**
+     * A call counted against the function's limits (a minute's, an hour's); refused over one, as Chrome does.
+     *
+     * @param {string} method - `set`, `remove` or `clear`.
+     */
+    const count = (method) => {
+      if (!limited) return;
+      if (!limits.has(method)) limits.set(method, [callLimit(SYNC_WRITES_PER_MINUTE, 60_000, now), callLimit(SYNC_WRITES_PER_HOUR, 3_600_000, now)]);
+      const [minute, hour] = /** @type {(() => boolean)[]} */ (limits.get(method)).map((take) => take());
+      if (!minute) throw new Error('This request exceeds the MAX_WRITE_OPERATIONS_PER_MINUTE quota.');
+      if (!hour) throw new Error('This request exceeds the MAX_WRITE_OPERATIONS_PER_HOUR quota.');
     };
+    /** @param {Record<string, unknown>} items @returns {number} */
+    const bytes = (items) => Object.entries(items).reduce((sum, [key, value]) => sum + syncItemBytes(key, value), 0);
     /** @type {FakeArea} */
     const fake = {
       data,
       writes: 0,
+      onChanged: areaChanged,
       async get(keys) {
+        const defaults = keys !== null && typeof keys === 'object' && !Array.isArray(keys) ? /** @type {Record<string, unknown>} */ (asStored(keys)) : {};
+        const wanted = keys == null ? Object.keys(data) : typeof keys === 'string' ? [keys] : Array.isArray(keys) ? keys : Object.keys(keys);
+        return Object.fromEntries(wanted.filter((key) => key in data || key in defaults).map((key) => [key, copied(key in data ? data[key] : defaults[key])]));
+      },
+      async getBytesInUse(keys) {
         const wanted = keys == null ? Object.keys(data) : [keys].flat();
-        return Object.fromEntries(wanted.filter((key) => key in data).map((key) => [key, viaJson(data[key])]));
+        return bytes(Object.fromEntries(wanted.filter((key) => key in data).map((key) => [key, data[key]])));
       },
       async set(items) {
-        for (const [key, value] of Object.entries(items)) {
-          if (quotaPerItem && key.length + JSON.stringify(value).length > quotaPerItem) {
-            throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
-          }
+        count('set');
+        const stored = /** @type {Record<string, unknown>} */ (asStored(items));
+        for (const [key, value] of Object.entries(stored)) {
+          if (quotaPerItem && syncItemBytes(key, value) > quotaPerItem) throw new Error('Resource::kQuotaBytesPerItem quota exceeded');
         }
-        if (quotaBytes && totalBytes({ ...data, ...items }) > quotaBytes) throw new Error('Resource::kQuotaBytes quota exceeded');
-        take();
+        const next = { ...data, ...stored };
+        if (bytes(next) > quotaBytes) throw new Error('Resource::kQuotaBytes quota exceeded');
+        if (maxItems && Object.keys(next).length > maxItems) throw new Error('Resource::kMaxItems quota exceeded');
+        fake.writes++;
         /** @type {Record<string, StorageChange>} */
         const changes = {};
-        for (const [key, value] of Object.entries(items)) {
-          if (JSON.stringify(data[key]) === JSON.stringify(value)) continue;
-          changes[key] = { oldValue: data[key], newValue: viaJson(value) };
-          data[key] = viaJson(value);
+        for (const [key, value] of Object.entries(stored)) {
+          if (key in data && sameValue(data[key], value)) continue;
+          changes[key] = { ...(key in data ? { oldValue: data[key] } : {}), newValue: value };
+          data[key] = value;
         }
         fire(changes);
       },
       async remove(keys) {
-        take();
+        count('remove');
+        fake.writes++;
         /** @type {Record<string, StorageChange>} */
         const changes = {};
         for (const key of [keys].flat()) {
@@ -141,15 +242,26 @@ export function fakeChromeStorage({ local = {}, sync = {}, session = {}, now = D
         }
         fire(changes);
       },
+      async clear() {
+        count('clear');
+        fake.writes++;
+        /** @type {Record<string, StorageChange>} */
+        const changes = {};
+        for (const key of Object.keys(data)) {
+          changes[key] = { oldValue: data[key] };
+          delete data[key];
+        }
+        fire(changes);
+      },
     };
     return fake;
   }
 
   return {
-    local: area('local', local),
-    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, quotaBytes: SYNC_QUOTA_BYTES, writesPerMinute: SYNC_WRITES_PER_MINUTE }),
-    session: area('session', session),
-    onChanged: { addListener: (listener) => listeners.push(listener) },
+    local: area('local', local, { quotaBytes: LOCAL_QUOTA_BYTES }),
+    sync: area('sync', sync, { quotaPerItem: MAX_SYNC_ITEM_BYTES, quotaBytes: SYNC_QUOTA_BYTES, maxItems: SYNC_MAX_ITEMS, limited: true }),
+    session: area('session', session, { quotaBytes: LOCAL_QUOTA_BYTES }),
+    onChanged,
     async settled() {
       while (running.length) await Promise.all(running.splice(0));
     },