service_worker.test.js

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import deriveSystemTotals from './src/lib/utils/deriveSystemTotals.js';
import isTrackableUrl from './src/lib/utils/isTrackableUrl.js';
import samePageKey from './src/lib/utils/samePageKey.js';
import pruneDeletedUrls from './src/lib/utils/pruneDeletedUrls.js';
import appendGroupingLog from './src/lib/utils/groupingLog.js';
import healDriftedLabelSlot from './src/lib/utils/healDriftedLabelSlot.js';
import navigatedAwayFromRecordedSlot from './src/lib/utils/navigatedAwayFromRecordedSlot.js';
import {
  buildGroupRemovalEntry,
  GROUP_REMOVAL_LOG_KEY,
  GROUP_REMOVAL_LOG_CAP,
  RemovalSource,
} from './src/lib/utils/groupRemovalLog.js';
import {
  buildGroupAdditionEntry,
  GROUP_ADDITION_LOG_KEY,
  GROUP_ADDITION_LOG_CAP,
  AdditionSource,
} from './src/lib/utils/groupAdditionLog.js';
import {
  buildGroupMoveEntry,
  GROUP_MOVE_LOG_KEY,
  GROUP_MOVE_LOG_CAP,
  MoveSource,
} from './src/lib/utils/groupMoveLog.js';
import { needsGroupCall, needsUngroupCall, bucketTabsByWindow } from './src/lib/utils/tabPlacement.js';
import { areaForKey } from './src/lib/utils/storageAreas.js';
import { readByArea, writeByArea } from './src/lib/utils/storageAccess.js';
import { migrateLabelsToSync } from './src/lib/utils/migrateLabelsToSync.js';
import findLabelForUrlKey from './src/lib/utils/findLabelForUrlKey.js';
import deletedLabelTitles from './src/lib/utils/deletedLabelTitles.js';

// service_worker.js is a vanilla (non-module) background script: it declares
// top-level functions and immediately registers chrome.*
// listeners / queries at load time. To exercise the functions without editing
// the source, we read the file and evaluate it in a sloppy-mode Function
// wrapper with a stubbed `chrome` injected, then return the top-level
// declarations plus getters onto the module-level mutable state. The chrome
// stub's callback-taking methods are no-ops by default so the load-time side
// effects register listeners but never run their async bodies; individual
// tests reconfigure the stubs they need.
const SW_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), 'service_worker.js');

function makeChrome() {
  const evt = () => ({ addListener: vi.fn(), removeListener: vi.fn() });
  return {
    tabGroups: {
      onCreated: evt(),
      onUpdated: evt(),
      query: vi.fn(),
      get: vi.fn(),
      update: vi.fn(),
    },
    tabs: {
      WindowType: { NORMAL: 'normal' },
      onUpdated: evt(),
      onActivated: evt(),
      onCreated: evt(),
      onReplaced: evt(),
      onMoved: evt(),
      onRemoved: evt(),
      query: vi.fn(),
      get: vi.fn(),
      group: vi.fn(),
      ungroup: vi.fn(),
      remove: vi.fn(),
      create: vi.fn(),
      update: vi.fn(),
    },
    processes: { onUpdatedWithMemory: evt() },
    alarms: {
      create: vi.fn(),
      onAlarm: evt(),
    },
    storage: {
      local: { get: vi.fn(), set: vi.fn(), remove: vi.fn() },
      onChanged: evt(),
    },
    runtime: { getURL: vi.fn((p) => `chrome-extension://abc/${p}`) },
  };
}

// service_worker.js is shipped as an ES-module service worker (crxjs sets
// `"type": "module"` at build), so it `import`s the pure deriveSystemTotals util.
// The sloppy-mode Function wrapper here can't hold a top-level `import`, so we
// strip the import line and inject the REAL util as a parameter — the worker
// tests then exercise the same util that deriveSystemTotals.test.js covers.
function loadWorker(chrome) {
  // The worker's `update` / `getStorage` delegate to the storageAccess module,
  // which is a REAL import here and therefore reads the ambient global `chrome`
  // — not the mock passed as a Function parameter below. In the shipped service
  // worker those are the same object; the parameter injection is an artifact of
  // the sloppy-mode Function wrapper. Publishing the mock globally HERE (rather
  // than in beforeEach) keeps them in step for the several tests that build
  // their own chrome and call loadWorker directly.
  //
  // Note the mocks deliberately expose NO `chrome.storage.sync`, which exercises
  // storageAccess's degrade-to-local path — the behavior a host without a sync
  // area gets, identical to this worker's pre-sync behavior.
  globalThis.chrome = chrome;

  const raw = fs.readFileSync(SW_PATH, 'utf8');
  const code = raw.replace(/^\s*import\s.*$/gm, '');
  const factory = new Function(
    'chrome',
    'console',
    'deriveSystemTotals',
    'isTrackableUrl',
    'samePageKey',
    'pruneDeletedUrls',
    'appendGroupingLog',
    'healDriftedLabelSlot',
    'navigatedAwayFromRecordedSlot',
    'buildGroupRemovalEntry',
    'GROUP_REMOVAL_LOG_KEY',
    'GROUP_REMOVAL_LOG_CAP',
    'RemovalSource',
    'buildGroupAdditionEntry',
    'GROUP_ADDITION_LOG_KEY',
    'GROUP_ADDITION_LOG_CAP',
    'AdditionSource',
    'buildGroupMoveEntry',
    'GROUP_MOVE_LOG_KEY',
    'GROUP_MOVE_LOG_CAP',
    'MoveSource',
    'needsGroupCall',
    'needsUngroupCall',
    'bucketTabsByWindow',
    'findLabelForUrlKey',
    'deletedLabelTitles',
    'areaForKey',
    'readByArea',
    'writeByArea',
    'migrateLabelsToSync',
    `${code}
    ;return {
      fns: { trackGroup, listenToProcesses, updateActiveTabs, update,
             newUrl, recordAccess, closeUrl, processProcesses, updateTotals, associateProcess,
             tabUpdates, urlUpdates, getUrlKey, validTab, getTabGroup, mapColors,
             getStorage, parseTabId, handleActiveTabsGroupChanges, groupTabs,
             initLoadSource, processesApiAvailable, systemApiAvailable,
             startSystemLoadPolling, stopSystemLoadPolling, pollSystemLoad,
             autoCloseSweep, isAutoCloseEligible, pruneAutoClosed,
             autoCloseThresholdMinutes, urlKeyIsMember, ejectAutoGroupedTab,
             recordInGroupTab, debugGroup, pruneVisits, stampLabelMembership,
             dissolveDeletedLabelGroups },
      state: {
        get groups() { return groups; },
        get samples() { return samples; },
        get processesIndex() { return processesIndex; },
        get pendingUngroups() { return pendingUngroups; },
        get autoGroupedTabs() { return autoGroupedTabs; },
        get userDeletedLabels() { return userDeletedLabels; },
      }
    };`
  );
  return factory(chrome, { log: vi.fn(), error: vi.fn() }, deriveSystemTotals, isTrackableUrl, samePageKey, pruneDeletedUrls, appendGroupingLog, healDriftedLabelSlot, navigatedAwayFromRecordedSlot, buildGroupRemovalEntry, GROUP_REMOVAL_LOG_KEY, GROUP_REMOVAL_LOG_CAP, RemovalSource, buildGroupAdditionEntry, GROUP_ADDITION_LOG_KEY, GROUP_ADDITION_LOG_CAP, AdditionSource, buildGroupMoveEntry, GROUP_MOVE_LOG_KEY, GROUP_MOVE_LOG_CAP, MoveSource, needsGroupCall, needsUngroupCall, bucketTabsByWindow, findLabelForUrlKey, deletedLabelTitles, areaForKey, readByArea, writeByArea, migrateLabelsToSync);
}

describe('service_worker.js', () => {
  let chrome;
  let fns;
  let state;

  beforeEach(() => {
    chrome = makeChrome();
    const loaded = loadWorker(chrome);
    fns = loaded.fns;
    state = loaded.state;
  });

  afterEach(() => {
    delete globalThis.chrome;
  });

  // registers chrome listeners at load without throwing
  it('loads and registers chrome event listeners on import', () => {
    expect(chrome.tabs.onUpdated.addListener).toHaveBeenCalled();
    expect(chrome.tabGroups.onCreated.addListener).toHaveBeenCalled();
    expect(chrome.storage.onChanged.addListener).toHaveBeenCalled();
    expect(chrome.processes.onUpdatedWithMemory.addListener).toHaveBeenCalled();
  });

  describe('getUrlKey', () => {
    // builds a url- prefixed key, stripping any hash fragment
    it('prefixes with url- and strips the fragment', () => {
      expect(fns.getUrlKey('https://a.com/p')).toBe('url-https://a.com/p');
      expect(fns.getUrlKey('https://a.com/p#section')).toBe('url-https://a.com/p');
    });
  });

  describe('mapColors', () => {
    // maps a Chrome named color to its hex value (used when seeding a label's color)
    it('maps a named color to hex', () => {
      expect(fns.mapColors('blue')).toBe('#1873E4');
      expect(fns.mapColors('grey')).toBe('#5F6367');
    });

    // maps a hex value back to its Chrome named color (used when grouping from a label)
    it('maps a hex value back to a named color', () => {
      expect(fns.mapColors('#1F8E43')).toBe('green');
      expect(fns.mapColors('#007B82')).toBe('cyan');
    });

    // an unknown color (neither a known name nor hex) resolves to undefined
    it('returns undefined for an unknown color', () => {
      expect(fns.mapColors('chartreuse')).toBeUndefined();
      expect(fns.mapColors('#ABCDEF')).toBeUndefined();
    });
  });

  describe('validTab', () => {
    // accepts ordinary web URLs
    it('accepts http and https tabs', () => {
      expect(fns.validTab({ url: 'https://example.com' })).toBeTruthy();
    });

    // rejects empty and browser-internal schemes
    it('rejects empty and internal-scheme tabs', () => {
      expect(fns.validTab({ url: '' })).toBeFalsy();
      expect(fns.validTab({ url: 'chrome://settings' })).toBe(false);
      expect(fns.validTab({ url: 'devtools://devtools/x' })).toBe(false);
      expect(fns.validTab({ url: 'chrome-extension://abc/index.html' })).toBe(false);
    });

    // incognito tabs are invalid everywhere validTab is consulted, so their
    // visits never reach activeTabs or the url-* process records.
    it('rejects incognito tabs', () => {
      expect(fns.validTab({ url: 'https://secret.com', incognito: true })).toBe(false);
    });
  });

  // Incognito navigations must leave no trace: the onUpdated handler's direct
  // changeInfo.url recording path (which bypasses validTab) is guarded so an
  // incognito navigation never enters allUrls or bumps visitCount, while a
  // normal-tab navigation still records as before.
  describe('onUpdated incognito guard', () => {
    // A storage mock that answers each query shape with sensible empties so the
    // handler (and the newUrl it may call) can run to completion.
    const emptyStorage = (chrome) => {
      chrome.storage.local.get.mockImplementation((query, cb) => {
        const keys =
          typeof query === 'string'
            ? [query]
            : Array.isArray(query)
            ? query
            : Object.keys(query);
        const res = {};
        for (const k of keys) {
          if (k === 'allUrls') res.allUrls = [];
          else if (k === 'activeTabs') res.activeTabs = [];
          else if (k === 'autoClosed') res.autoClosed = {};
          else if (k === 'labels') res.labels = {};
          // url-* keys stay absent (undefined), as on a first visit.
        }
        cb(res);
      });
      chrome.tabs.query.mockImplementation((_q, cb) => cb([]));
    };

    const getHandler = (chrome) =>
      chrome.tabs.onUpdated.addListener.mock.calls[0][0];

    // Did any storage write add this urlKey to allUrls (i.e. record the visit)?
    const recordedAllUrls = (chrome, urlKey) =>
      chrome.storage.local.set.mock.calls.some(
        (c) => Array.isArray(c[0].allUrls) && c[0].allUrls.includes(urlKey)
      );

    // A normal navigation records the url; the incognito one must not.
    it('records a normal-tab navigation but not an incognito one', async () => {
      emptyStorage(chrome);
      const onUpdated = getHandler(chrome);

      // Normal tab navigating to a new URL → recorded into allUrls.
      chrome.storage.local.set.mockClear();
      await onUpdated(
        1,
        { url: 'https://normal.com' },
        { id: 1, url: 'https://normal.com', incognito: false }
      );
      expect(recordedAllUrls(chrome, 'url-https://normal.com')).toBe(true);

      // Incognito tab navigating to a new URL → never recorded.
      chrome.storage.local.set.mockClear();
      await onUpdated(
        2,
        { url: 'https://secret.com' },
        { id: 2, url: 'https://secret.com', incognito: true }
      );
      expect(recordedAllUrls(chrome, 'url-https://secret.com')).toBe(false);
    });
  });

  describe('parseTabId', () => {
    // extracts the integer tab id from a "tab-<n>" key
    it('parses the numeric id from a tabKey', () => {
      expect(fns.parseTabId({ tabKey: 'tab-42' })).toBe(42);
    });
  });

  describe('updateTotals', () => {
    // accumulates each process metric into the running totals
    it('sums process metrics into processTotals', () => {
      const updates = { processTotals: { cpu: 1, network: 1, privateMemory: 0, jsMemoryAllocated: 0, jsMemoryUsed: 0 } };
      const out = fns.updateTotals(
        { cpu: 2, network: 3, privateMemory: 4, jsMemoryAllocated: 5, jsMemoryUsed: 6 },
        updates
      );
      expect(out.processTotals).toEqual({ cpu: 3, network: 4, privateMemory: 4, jsMemoryAllocated: 5, jsMemoryUsed: 6 });
    });

    // treats missing metrics as zero
    it('defaults missing metrics to 0', () => {
      const updates = { processTotals: { cpu: 0, network: 0, privateMemory: 0, jsMemoryAllocated: 0, jsMemoryUsed: 0 } };
      const out = fns.updateTotals({}, updates);
      expect(out.processTotals.cpu).toBe(0);
    });
  });

  describe('urlUpdates', () => {
    // initializes a processes bucket and copies tab metadata
    it('initializes processes and copies title/favicon/groupId', () => {
      const out = fns.urlUpdates(
        { url: 'https://a.com' },
        { status: 'complete', title: 'A', favIconUrl: 'a.png', groupId: 5, url: 'https://a.com' }
      );
      expect(out.title).toBe('A');
      expect(out.favicon).toBe('a.png');
      expect(out.groupId).toBe(5);
      expect(out.processes.samples).toBe(0);
    });

    // accumulates process stats and bumps the sample counter
    it('accumulates process stats when a process is supplied', () => {
      const out = fns.urlUpdates(
        { url: 'https://b.com', title: 'B' },
        { status: 'complete', title: 'B', url: 'https://b.com', groupId: -1 },
        { cpu: 10, network: 2, privateMemory: 1, jsMemoryAllocated: 1, jsMemoryUsed: 1 }
      );
      expect(out.processes.samples).toBe(1);
      expect(out.processes.cpu).toBe(10);
    });

    // falls back to the url as the title when the tab has none
    it('uses the url as title when title is missing', () => {
      const out = fns.urlUpdates({ url: 'https://c.com' }, { status: 'complete', url: 'https://c.com' });
      expect(out.title).toBe('https://c.com');
    });

    // an edited record keeps its user title/favicon instead of taking the live tab's values
    it('preserves an edited title and favicon', () => {
      const out = fns.urlUpdates(
        { url: 'https://a.com', title: 'My Title', favicon: 'mine.png', edited: true },
        { status: 'complete', title: 'Live Title', favIconUrl: 'live.png', groupId: -1, url: 'https://a.com' }
      );
      expect(out.title).toBe('My Title');
      expect(out.favicon).toBe('mine.png');
    });

    // a non-edited record still takes the live tab's title/favicon (guards the flag's scope)
    it('still copies the live title and favicon when not edited', () => {
      const out = fns.urlUpdates(
        { url: 'https://a.com', title: 'Old', favicon: 'old.png' },
        { status: 'complete', title: 'Live Title', favIconUrl: 'live.png', groupId: -1, url: 'https://a.com' }
      );
      expect(out.title).toBe('Live Title');
      expect(out.favicon).toBe('live.png');
    });
  });

  describe('update', () => {
    // writes the supplied object straight to chrome.storage.local
    it('persists updates to chrome.storage.local', () => {
      fns.update({ allUrls: ['url-a'] });
      expect(chrome.storage.local.set).toHaveBeenCalledWith({ allUrls: ['url-a'] });
    });

    // labels now lives in chrome.storage.sync, which caps writes at 120/minute.
    // recordInGroupTab runs per tab from groupTabs on every activeTabs change, so
    // re-persisting an identical labels map would breach the quota within a
    // minute of ordinary browsing.
    it('drops a labels write identical to the last one persisted', () => {
      fns.update({ labels: { Work: { title: 'Work' } } });
      chrome.storage.local.set.mockClear();

      fns.update({ labels: { Work: { title: 'Work' } } });

      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });

    // the guard must only suppress genuinely-identical content — a real group
    // edit still has to reach storage
    it('persists a labels write whose content changed', () => {
      fns.update({ labels: { Work: { title: 'Work' } } });
      chrome.storage.local.set.mockClear();

      fns.update({ labels: { Work: { title: 'Renamed' } } });

      expect(chrome.storage.local.set).toHaveBeenCalledWith({ labels: { Work: { title: 'Renamed' } } });
    });

    // dropping a redundant labels key must not drop its co-written keys — the
    // activeTabs membership stamp rides along in the same call
    it('still writes companion keys when the labels key is dropped', () => {
      const labels = { Work: { title: 'Work' } };
      fns.update({ labels });
      chrome.storage.local.set.mockClear();

      fns.update({ labels, activeTabs: [{ tabKey: 'tab-1' }] });

      expect(chrome.storage.local.set).toHaveBeenCalledWith({ activeTabs: [{ tabKey: 'tab-1' }] });
    });

    // when the redundant labels key was the ONLY key, no write should be issued
    // at all rather than an empty set
    it('issues no write when the dropped labels key was the only key', () => {
      const labels = { Work: { title: 'Work' } };
      fns.update({ labels });
      chrome.storage.local.set.mockClear();

      fns.update({ labels });

      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });
  });

  describe('getStorage', () => {
    // invokes the callback form with the chrome result
    it('invokes the callback with the storage result', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ activeTabs: [1] }));
      const cb = vi.fn();
      fns.getStorage('activeTabs', cb);
      expect(cb).toHaveBeenCalledWith({ activeTabs: [1] });
    });

    // resolves a promise with the result when no callback is given
    it('resolves with the result when no callback is passed', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels: {} }));
      await expect(fns.getStorage('labels')).resolves.toEqual({ labels: {} });
    });
  });

  describe('getTabGroup', () => {
    // short-circuits to null for absent / sentinel ids
    it('resolves null for id -1 or null', async () => {
      await expect(fns.getTabGroup(-1)).resolves.toBeNull();
      await expect(fns.getTabGroup(null)).resolves.toBeNull();
    });

    // resolves the chrome.tabGroups.get result for a real id
    it('resolves the group for a real id', async () => {
      chrome.tabGroups.get.mockImplementation((_id, cb) => cb({ id: 3, title: 'Work' }));
      await expect(fns.getTabGroup(3)).resolves.toEqual({ id: 3, title: 'Work' });
    });
  });

  describe('trackGroup', () => {
    // records the group title keyed by its integer id
    it('stores the group title by id', () => {
      fns.trackGroup({ id: '5', title: 'Reading' });
      expect(state.groups[5]).toBe('Reading');
    });
  });

  describe('listenToProcesses', () => {
    // subscribes processProcesses to the memory-update event
    it('registers the processes listener', () => {
      chrome.processes.onUpdatedWithMemory.addListener.mockClear();
      fns.listenToProcesses();
      expect(chrome.processes.onUpdatedWithMemory.addListener).toHaveBeenCalledWith(fns.processProcesses);
    });

    // swallows the error when the processes API is unavailable
    it('does not throw when the processes API throws', () => {
      chrome.processes.onUpdatedWithMemory.addListener.mockImplementation(() => {
        throw new Error('no processes API');
      });
      expect(() => fns.listenToProcesses()).not.toThrow();
    });
  });

  describe('closeUrl', () => {
    // moves the closed url to the front of allUrls and runs the callback
    it('reorders allUrls, persists, and invokes the callback', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: ['url-a', 'url-b', 'url-c'] }));
      const done = vi.fn();
      fns.closeUrl('url-c', done);
      expect(chrome.storage.local.set).toHaveBeenCalledWith({ allUrls: ['url-c', 'url-a', 'url-b'] });
      expect(done).toHaveBeenCalled();
    });

    // REGRESSION: an UNTRACKED key has indexOf -1, and splice at -1 removes the
    // LAST element — so the unguarded move-to-front silently promoted the OLDEST
    // key to the front, corrupting the recency order the eviction trim relies on.
    // Nothing to reorder for a key we never tracked: leave allUrls alone.
    it('leaves allUrls untouched when the key is not tracked', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: ['url-a', 'url-b', 'url-c'] }));
      const done = vi.fn();
      fns.closeUrl('url-never-seen', done);
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
      expect(done).toHaveBeenCalled();
    });

    // REGRESSION: deleting a page from History splices it out of allUrls, but the
    // tab close that accompanies the delete fires onRemoved -> closeUrl in the
    // service worker process. closeUrl read allUrls before the delete landed, so
    // its move-to-front wrote the key straight back at index 0 -- the row
    // reappeared at the top of History, titleless because the url-* record was
    // already gone. A deletedUrls tombstone makes closeUrl skip the key.
    it('leaves allUrls untouched when the key was just deleted', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls: ['url-a', 'url-b', 'url-c'], deletedUrls: { 'url-c': 1 } })
      );
      const done = vi.fn();
      fns.closeUrl('url-c', done);
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
      expect(done).toHaveBeenCalled();
    });

    // The tombstone is checked by PRESENCE of the specific key, not by "is the
    // map non-empty" — an unrelated deletion must not freeze every other row's
    // recency ordering.
    it('still reorders a tracked key when a different key is tombstoned', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls: ['url-a', 'url-b', 'url-c'], deletedUrls: { 'url-a': 1 } })
      );
      const done = vi.fn();
      fns.closeUrl('url-c', done);
      expect(chrome.storage.local.set).toHaveBeenCalledWith({ allUrls: ['url-c', 'url-a', 'url-b'] });
      expect(done).toHaveBeenCalled();
    });
  });

  describe('newUrl', () => {
    // returns undefined when called without a tab id or url
    it('returns early without tabId/url', async () => {
      await expect(fns.newUrl(undefined, 'https://a.com')).resolves.toBeUndefined();
      await expect(fns.newUrl(1, undefined)).resolves.toBeUndefined();
    });

    // adds a brand-new url key to the front of allUrls
    it('prepends an unseen url key to allUrls', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: ['url-old'], labels: {} }));
      const updates = await fns.newUrl(1, 'https://new.com');
      expect(updates.allUrls[0]).toBe('url-https://new.com');
    });

    // REGRESSION: a REVISIT must move the url key back to the front of allUrls.
    // allUrls is the recency list the tracked-URL cap trims from the TAIL, so a
    // key that never moves on revisit drifts out, gets evicted, and has its whole
    // url-* record — visits and all — deleted. That is what reset a daily-visited
    // site to "1 visit". Previously newUrl only inserted when the key was ABSENT,
    // so for an already-present key it never touched allUrls at all.
    it('moves a revisited url key to the front of allUrls', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          allUrls: ['url-https://new.com', 'url-https://a.com', 'url-https://b.com'],
          labels: {},
        })
      );
      const updates = await fns.newUrl(1, 'https://b.com');
      expect(updates.allUrls[0]).toBe('url-https://b.com');
      expect(updates.allUrls).toHaveLength(3);
    });

    // Deleting from History means "forget this", not "block this" — a deliberate
    // return to the page is the user asking for it back, so a real visit clears
    // the tombstone and the key is re-added to allUrls as normal.
    it('clears the deletedUrls tombstone when the page is revisited', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls: [], labels: {}, deletedUrls: { 'url-https://b.com': Date.now() } })
      );
      const updates = await fns.newUrl(1, 'https://b.com');
      expect(updates.deletedUrls['url-https://b.com']).toBeUndefined();
      expect(updates.allUrls[0]).toBe('url-https://b.com');
    });

    // Tombstones are pruned on the same pass that already prunes allUrls, so the
    // map is bounded by DELETED_URL_TTL_MS instead of growing one entry per
    // page ever deleted. An unrelated FRESH tombstone must survive the prune.
    it('prunes expired tombstones but keeps fresh ones', async () => {
      const now = Date.now();
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          allUrls: [],
          labels: {},
          deletedUrls: {
            'url-https://stale.com': now - 2 * 60 * 60 * 1000,
            'url-https://fresh.com': now - 1000,
          },
        })
      );
      const updates = await fns.newUrl(1, 'https://b.com');
      expect(updates.deletedUrls['url-https://stale.com']).toBeUndefined();
      expect(updates.deletedUrls['url-https://fresh.com']).toBe(now - 1000);
    });

    // The durable half of a visit: it accumulates under the site's HOST in
    // siteVisits, which the eviction branch never touches.
    it('records the visit under the site host in siteVisits', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: [], labels: {} }));
      const before = Date.now();
      const updates = await fns.newUrl(1, 'https://www.espn.com/nfl/story/id/1');
      expect(updates.siteVisits['espn.com']).toHaveLength(1);
      expect(updates.siteVisits['espn.com'][0]).toBeGreaterThanOrEqual(before);
    });

    // Every page of a content site credits the SITE, not its own orphan key: a
    // second article on the same host appends to the same siteVisits bucket.
    it('accumulates visits from different pages of one site under one host', async () => {
      const earlier = Date.now() - 1000 * 60 * 60;
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls: [], labels: {}, siteVisits: { 'espn.com': [earlier] } })
      );
      const updates = await fns.newUrl(1, 'https://espn.com/nba/standings');
      expect(updates.siteVisits['espn.com']).toHaveLength(2);
      expect(updates.siteVisits['espn.com'][0]).toBe(earlier);
    });

    // siteVisits must SURVIVE the eviction that deletes url-* records: the
    // durable store is written even while the tracked-URL cap is trimming keys,
    // so a site's stats outlive its record. This is the whole point of the store.
    it('keeps siteVisits history for a site whose url record is evicted', async () => {
      const history = [Date.now() - 1000 * 60 * 60 * 24 * 3, Date.now() - 1000 * 60 * 60];
      // A full recency list, so this visit pushes the tail past the cap.
      const allUrls = Array.from({ length: 500 }, (_, i) => `url-https://pad-${i}.com`);
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls, labels: {}, siteVisits: { 'wikipedia.org': history } })
      );
      const updates = await fns.newUrl(1, 'https://wikipedia.org/wiki/Main_Page');
      // Keys past the cap were evicted...
      expect(updates.allUrls).toHaveLength(500);
      // ...but the site's history is intact and grew by this visit.
      expect(updates.siteVisits['wikipedia.org']).toHaveLength(history.length + 1);
      expect(updates.siteVisits['wikipedia.org'].slice(0, 2)).toEqual(history);
    });

    // Search engines stay in history (allUrls + visitCount) but stop
    // accumulating the Favorites scoring signal: no siteVisits[host] write and no
    // per-record `visits` append, since rankFavorites discards search hosts anyway.
    // Red if the isSearchEngine gate is removed: siteVisits['google.com'] appears.
    it('records a search engine in history but not in the Favorites scoring stores', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: [], labels: {} }));
      const url = 'https://www.google.com/search?q=weather';
      const updates = await fns.newUrl(1, url);
      const urlKey = fns.getUrlKey(url);
      // Still in history: allUrls + visitCount.
      expect(updates.allUrls).toContain(urlKey);
      expect(updates[urlKey].visitCount).toBe(1);
      // But NOT in the Favorites scoring stores.
      expect(updates.siteVisits).toBeUndefined();
      expect(updates[urlKey].visits).toEqual([]);
    });

    // A search engine with an existing siteVisits bucket does not grow it — the
    // durable store stops accumulating search hosts going forward.
    it('does not append to an existing siteVisits bucket for a search engine', async () => {
      const earlier = Date.now() - 1000 * 60 * 60;
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ allUrls: [], labels: {}, siteVisits: { 'google.com': [earlier] } })
      );
      const updates = await fns.newUrl(1, 'https://www.google.com/search?q=x');
      // siteVisits is left untouched (no write into updates for this host).
      expect(updates.siteVisits).toBeUndefined();
    });

    // Non-website navigations (about:blank, file://, chrome://, data:) are
    // never recorded: newUrl returns before touching storage so they can't
    // enter allUrls or bump visitCount.
    it('does not record non-website URLs', async () => {
      const get = vi.fn((_q, cb) => cb({ allUrls: [], labels: {} }));
      chrome.storage.local.get.mockImplementation(get);
      for (const url of [
        'about:blank',
        'file:///Users/x/doc.html',
        'chrome://extensions',
        'data:text/html,hi',
      ]) {
        await expect(fns.newUrl(1, url)).resolves.toBeUndefined();
      }
      expect(get).not.toHaveBeenCalled();
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });

    // A brand-new url records a first visit timestamp alongside visitCount 1, so
    // Favorites can rank by a time-decayed sum of visits.
    it('records a first visit timestamp and visitCount on a new url', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: [], labels: {} }));
      const before = Date.now();
      const updates = await fns.newUrl(1, 'https://new.com');
      const record = updates['url-https://new.com'];
      expect(record.visitCount).toBe(1);
      expect(record.visits).toHaveLength(1);
      expect(record.visits[0]).toBeGreaterThanOrEqual(before);
    });

    // Every visit stamps `lastVisit` on the url-* record. This is the recency
    // signal the History page dates rows by; `autoClosed` alone only covers
    // tabs the inactivity sweep closed, so a manually-closed or still-open page
    // had no timestamp and fell into "Earlier this week".
    it('stamps lastVisit on the url record for every visit', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: [], labels: {} }));
      const before = Date.now();
      const updates = await fns.newUrl(1, 'https://new.com');
      const record = updates['url-https://new.com'];
      expect(record.lastVisit).toBeGreaterThanOrEqual(before);
      expect(record.lastVisit).toBeLessThanOrEqual(Date.now());
    });

    // The case that motivated putting `lastVisit` OUTSIDE the isSearchEngine
    // gate: a search engine keeps an empty `visits` array (so it stays out of
    // Favorites scoring) but must still be datable on the History page.
    // Red if `lastVisit` is moved inside the gate.
    it('stamps lastVisit on a search engine while leaving visits empty', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ allUrls: [], labels: {} }));
      const before = Date.now();
      const url = 'https://www.google.com/search?q=weather';
      const updates = await fns.newUrl(1, url);
      const record = updates[fns.getUrlKey(url)];
      expect(record.visits).toEqual([]);
      expect(record.lastVisit).toBeGreaterThanOrEqual(before);
    });

    // A repeat visit appends a fresh timestamp and increments visitCount while
    // preserving the prior visits and other url-* fields.
    it('appends a visit timestamp on a repeat visit', async () => {
      const oldTs = Date.now() - 1000 * 60 * 60; // an hour ago
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          allUrls: ['url-https://a.com'],
          labels: {},
          'url-https://a.com': { url: 'https://a.com', title: 'A', visitCount: 2, visits: [oldTs] },
        })
      );
      const updates = await fns.newUrl(1, 'https://a.com');
      const record = updates['url-https://a.com'];
      expect(record.title).toBe('A'); // existing fields preserved
      expect(record.visitCount).toBe(3);
      expect(record.visits).toHaveLength(2);
      expect(record.visits[0]).toBe(oldTs);
    });

    // Visits older than the retention horizon are pruned on write, so per-site
    // history stays bounded.
    it('prunes visits older than the retention horizon on write', async () => {
      const ancient = Date.now() - 1000 * 60 * 60 * 24 * 60; // 60 days ago
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          allUrls: ['url-https://a.com'],
          labels: {},
          'url-https://a.com': { url: 'https://a.com', visitCount: 5, visits: [ancient] },
        })
      );
      const updates = await fns.newUrl(1, 'https://a.com');
      const record = updates['url-https://a.com'];
      // The ancient visit is dropped; only the fresh one survives.
      expect(record.visits).toHaveLength(1);
      expect(record.visits).not.toContain(ancient);
    });
  });

  describe('recordAccess', () => {
    // Mirror of the worker's ACCESS_THROTTLE_MS (not exported through fns).
    const ACCESS_THROTTLE_MS_TEST = 1000 * 60 * 30;
    // Switching back to a tab whose last visit is older than the throttle
    // window records a visit (delegating to newUrl), so a kept-open favorite
    // you return to earns rank credit.
    it('records a visit when the last visit is older than the throttle', async () => {
      const stale = Date.now() - ACCESS_THROTTLE_MS_TEST - 1000; // just past the window
      chrome.tabs.get.mockResolvedValue({ id: 7, url: 'https://a.com' });
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          allUrls: ['url-https://a.com'],
          labels: {},
          'url-https://a.com': { url: 'https://a.com', title: 'A', visitCount: 2, visits: [stale] },
        })
      );
      const updates = await fns.recordAccess(1);
      const record = updates['url-https://a.com'];
      expect(record.visitCount).toBe(3);
      expect(record.visits).toHaveLength(2);
    });

    // Re-activating the same site within the throttle window records nothing, so
    // rapid alt-tabbing and the open→activate sequence can't inflate a rank.
    it('records nothing within the throttle window', async () => {
      const recent = Date.now() - 1000 * 60; // a minute ago, well inside 30 min
      chrome.tabs.get.mockResolvedValue({ id: 7, url: 'https://a.com' });
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ 'url-https://a.com': { url: 'https://a.com', visitCount: 2, visits: [recent] } })
      );
      await expect(fns.recordAccess(1)).resolves.toBeUndefined();
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });

    // A missing tab (rejected get) or a non-trackable URL is ignored — no read,
    // no write.
    it('ignores missing tabs and non-trackable URLs', async () => {
      chrome.tabs.get.mockRejectedValueOnce(new Error('No tab with id'));
      await expect(fns.recordAccess(999)).resolves.toBeUndefined();

      chrome.tabs.get.mockResolvedValueOnce({ id: 8, url: 'chrome://extensions' });
      await expect(fns.recordAccess(8)).resolves.toBeUndefined();
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });
  });

  describe('pruneVisits', () => {
    // A non-array or empty input yields an empty array, never a throw.
    it('returns [] for non-array or empty input', () => {
      const now = Date.now();
      expect(fns.pruneVisits(undefined, now)).toEqual([]);
      expect(fns.pruneVisits([], now)).toEqual([]);
    });

    // Visits older than the retention horizon are dropped.
    it('drops visits older than the retention horizon', () => {
      const now = Date.now();
      const day = 1000 * 60 * 60 * 24;
      const fresh = now - day;
      const stale = now - 60 * day;
      expect(fns.pruneVisits([stale, fresh], now)).toEqual([fresh]);
    });

    // The result is sorted ascending and drops non-finite entries.
    it('sorts ascending and filters non-finite entries', () => {
      const now = Date.now();
      const day = 1000 * 60 * 60 * 24;
      const a = now - 3 * day;
      const b = now - 1 * day;
      expect(fns.pruneVisits([b, a, NaN, 'x'], now)).toEqual([a, b]);
    });

    // More than 50 entries keep only the newest 50.
    it('caps length to the newest 50 visits', () => {
      const now = Date.now();
      const many = [];
      for (let i = 0; i < 60; i++) many.push(now - i * 1000);
      const result = fns.pruneVisits(many, now);
      expect(result).toHaveLength(50);
      expect(result[result.length - 1]).toBe(now);
    });
  });

  describe('updateActiveTabs', () => {
    // queries normal-window tabs and writes the rebuilt activeTabs list
    it('queries tabs and persists the rebuilt active list', () => {
      chrome.tabs.query.mockImplementation((_q, cb) =>
        cb([{ id: 1, url: 'https://a.com', pinned: false, groupId: -1, active: true, tabIndex: 0 }])
      );
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ activeTabs: [], autoClosed: {} }));

      fns.updateActiveTabs();

      expect(chrome.tabs.query).toHaveBeenCalled();
      expect(chrome.storage.local.set).toHaveBeenCalled();
      const written = chrome.storage.local.set.mock.calls.at(-1)[0];
      expect(written.activeTabs[0].urlKey).toBe('url-https://a.com');
    });

    // A Chrome Tab exposes `index`, not `tabIndex`. The old comparator subtracted
    // two undefineds, returned NaN for every pair, and the sort silently did
    // nothing — so activeTabs never actually reflected tab-strip order.
    it('sorts tabs by their tab-strip index', () => {
      chrome.tabs.query.mockImplementation((_q, cb) =>
        cb([
          { id: 3, url: 'https://c.com', pinned: false, groupId: -1, index: 2 },
          { id: 1, url: 'https://a.com', pinned: false, groupId: -1, index: 0 },
          { id: 2, url: 'https://b.com', pinned: false, groupId: -1, index: 1 },
        ])
      );
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ activeTabs: [], autoClosed: {} }));

      fns.updateActiveTabs();

      const written = chrome.storage.local.set.mock.calls.at(-1)[0];
      expect(written.activeTabs.map((t) => t.urlKey)).toEqual([
        'url-https://a.com',
        'url-https://b.com',
        'url-https://c.com',
      ]);
    });

    // Returning to a page the Closer had closed used to ungroup it unconditionally.
    // When the URL is a label member, groupTabs pulls it straight back in on the
    // next pass — a visible out-and-back jump on every revisit. Clearing the
    // autoClosed entry is the point; the eject is not.
    it('does not eject a revisited auto-closed tab whose url is a label member', () => {
      chrome.tabs.query.mockImplementation((_q, cb) =>
        cb([{ id: 1, url: 'https://a.com', pinned: false, groupId: 5, index: 0, active: true }])
      );
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          activeTabs: [],
          autoClosed: { 'url-https://a.com': 123 },
          labels: { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } },
        })
      );

      fns.updateActiveTabs();

      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
      // The autoClosed entry is still cleared — only the move is suppressed.
      const written = chrome.storage.local.set.mock.calls.at(-1)[0];
      expect(written.autoClosed['url-https://a.com']).toBeUndefined();
    });

    // Guards against over-suppression: a revisited auto-closed tab that no label
    // claims is still ejected, exactly as before.
    it('still ejects a revisited auto-closed tab that no label claims', () => {
      chrome.tabs.query.mockImplementation((_q, cb) =>
        cb([{ id: 1, url: 'https://a.com', pinned: false, groupId: 5, index: 0, active: true }])
      );
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({
          activeTabs: [],
          autoClosed: { 'url-https://a.com': 123 },
          labels: { Work: { title: 'Work', urlKeys: ['url-https://zzz.com'] } },
        })
      );

      fns.updateActiveTabs();

      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(1);
    });
  });

  describe('onUpdated navigation eject', () => {
    // Build a worker whose storage answers the load-time labels/activeTabs read and
    // the per-url reads onUpdated performs, then hand back its onUpdated listener.
    const loadForNavigation = ({ labels, recordedUrlKey }) => {
      const nav = makeChrome();
      nav.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      nav.storage.local.get.mockImplementation((query, cb) => {
        // Boot now reads the two keys SEPARATELY: `labels` through the
        // local -> sync migration (this mock exposes no sync area, so the
        // migration falls back to a local ['labels'] read) and `activeTabs`
        // through the ordinary bootstrap. They used to arrive as one combined
        // ['labels','activeTabs'] query.
        if (Array.isArray(query) && query.includes('labels')) {
          cb({ labels });
          return;
        }
        if (Array.isArray(query) && query.includes('activeTabs')) {
          cb({ activeTabs: [] });
          return;
        }
        if (query === 'activeTabs') {
          cb({
            activeTabs: [
              { tabKey: 'tab-7', urlKey: recordedUrlKey, pinned: false, groupId: 5, windowId: 1 },
            ],
          });
          return;
        }
        cb({});
      });
      const loaded = loadWorker(nav);
      return { nav, listener: nav.tabs.onUpdated.addListener.mock.calls[0][0], loaded };
    };

    // Sites that rewrite their own path with no user input (auth bounces, redirect
    // chains, chat and doc apps) tripped the navigation eject on every rewrite. If
    // the new URL is ALSO a member of the tab's label, ejecting it only has
    // groupTabs pull it straight back in — the user watches the tab pop out of the
    // group and snap back, having touched nothing.
    it('does not eject when the tab navigates to another url in the same label', async () => {
      const { nav, listener } = loadForNavigation({
        labels: {
          Work: {
            title: 'Work',
            urlKeys: ['url-https://a.com/apps', 'url-https://a.com/other'],
          },
        },
        recordedUrlKey: 'url-https://a.com/apps',
      });

      await listener(
        7,
        { url: 'https://a.com/other' },
        { id: 7, url: 'https://a.com/other', groupId: 5, windowId: 1, title: 'A' }
      );

      expect(nav.tabs.ungroup).not.toHaveBeenCalled();
    });

    // Guards against over-suppression: a genuine navigation to a URL no label
    // claims must still eject the tab, which is the whole point of the eject path.
    it('still ejects when the tab navigates to a url no label claims', async () => {
      const { nav, listener } = loadForNavigation({
        labels: { Work: { title: 'Work', urlKeys: ['url-https://a.com/apps'] } },
        recordedUrlKey: 'url-https://a.com/apps',
      });

      await listener(
        7,
        { url: 'https://elsewhere.com/page' },
        { id: 7, url: 'https://elsewhere.com/page', groupId: 5, windowId: 1, title: 'E' }
      );

      expect(nav.tabs.ungroup).toHaveBeenCalled();
      expect(nav.tabs.ungroup.mock.calls[0][0]).toBe(7);
    });
  });

  describe('cold start grouping', () => {
    // Chrome tab ids are unique only within a browser session. After a restart the
    // PERSISTED activeTabs snapshot holds ids that now belong to entirely different
    // tabs, and MV3 wakes this worker constantly — so grouping from that snapshot
    // moved unrelated tabs with the user doing nothing at all. The first pass must
    // wait for live tabs, which updateActiveTabs re-reads and writes.
    it('does not group from the persisted snapshot when the worker wakes', async () => {
      const cold = makeChrome();
      cold.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      cold.storage.local.get.mockImplementation((query, cb) => {
        if (Array.isArray(query) && query.includes('labels') && query.includes('activeTabs')) {
          cb({
            labels: { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } },
            // A stale id: tab 99 was a member last session; it is some other tab now.
            activeTabs: [
              { tabKey: 'tab-99', urlKey: 'url-https://a.com', pinned: false, groupId: -1, windowId: 1 },
            ],
          });
        }
      });

      loadWorker(cold);
      await Promise.resolve();

      expect(cold.tabs.group).not.toHaveBeenCalled();
      expect(cold.tabs.ungroup).not.toHaveBeenCalled();
    });
  });

  describe('processProcesses', () => {
    // increments the sample counter and writes accumulated totals
    it('bumps samples and persists process totals', async () => {
      const before = state.samples;
      await fns.processProcesses({}); // no pids → totals only
      expect(state.samples).toBe(before + 1);
      expect(chrome.storage.local.set).toHaveBeenCalled();
    });
  });

  describe('associateProcess', () => {
    // merges per-tab url updates for each task tab id in the process
    it('fetches each task tab and merges its url updates', async () => {
      chrome.tabs.get.mockResolvedValue({ url: 'https://a.com', status: 'complete', title: 'A', groupId: -1 });
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({}));
      const out = await fns.associateProcess(
        { tasks: [{ tabId: 1 }], cpu: 1 },
        { processTotals: {} }
      );
      expect(chrome.tabs.get).toHaveBeenCalledWith(1);
      expect(out['url-https://a.com']).toBeTruthy();
    });
  });

  describe('tabUpdates', () => {
    // resolves an empty object for tabs that fail the validity check
    it('resolves {} for an invalid tab', async () => {
      await expect(fns.tabUpdates({ url: 'chrome://settings' })).resolves.toEqual({});
    });

    // resolves keyed url updates for a valid tab
    it('resolves keyed url updates for a valid tab', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({}));
      const out = await fns.tabUpdates({ url: 'https://a.com', status: 'complete', title: 'A', groupId: -1 });
      expect(out['url-https://a.com']).toBeTruthy();
    });
  });

  describe('handleActiveTabsGroupChanges', () => {
    // returns early when there is no previous value to diff against
    it('no-ops when oldValue is missing', async () => {
      await expect(
        fns.handleActiveTabsGroupChanges({ newValue: [], oldValue: undefined })
      ).resolves.toBeUndefined();
      expect(chrome.storage.local.set).not.toHaveBeenCalled();
    });

    // The add path must seed a label that does not exist yet rather than throwing
    // on `labels[title].urlKeys.push` (the previous `|| { urlKeys: [] }` fallback
    // was never written back).
    it('seeds a missing label on the add path without throwing', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 5 ? { id: 5, title: 'NewGroup', color: 'blue' }
                    : { id: 2, title: 'OldGroup', color: 'red' })
      );
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels: {} }));

      await expect(
        fns.handleActiveTabsGroupChanges({
          oldValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 2, pinned: false }],
          newValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 5, pinned: false }],
        })
      ).resolves.not.toThrow();

      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(written.labels.NewGroup.urlKeys).toContain('url-z');
      // The seeded label carries the group's color, mapped to hex via mapColors.
      expect(written.labels.NewGroup.color).toBe('#1873E4');
    });

    // A genuine re-home (tab moves directly from group A into group B) is
    // unambiguous re-parent intent: it adds the member to B AND removes it from
    // A, so a URL never accumulates membership in every group it passed through.
    it('re-home A→B adds the member to B and removes it from A', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 5 ? { id: 5, title: 'GroupB', color: 'blue' }
                    : { id: 2, title: 'GroupA', color: 'red' })
      );
      const labels = {
        GroupA: { title: 'GroupA', urlKeys: ['url-z'] },
        GroupB: { title: 'GroupB', urlKeys: [] },
      };
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels }));

      await fns.handleActiveTabsGroupChanges({
        oldValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 2, pinned: false }],
        newValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 5, pinned: false }],
      });

      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(written.labels.GroupB.urlKeys).toContain('url-z');
      expect(written.labels.GroupA.urlKeys).not.toContain('url-z');
    });

    // Ungroup-to-nothing (newTab.groupId → -1, so there is no destination group)
    // is NOT a re-home: membership is sticky, so the old group keeps the member.
    it('ungroup-to-nothing keeps the member in the old group', async () => {
      // getTabGroup(-1) resolves null, so the guard skips the whole diff body —
      // no label is ever written.
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 2 ? { id: 2, title: 'GroupA', color: 'red' } : null)
      );
      const labels = { GroupA: { title: 'GroupA', urlKeys: ['url-z'] } };
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels }));

      await fns.handleActiveTabsGroupChanges({
        oldValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 2, pinned: false }],
        newValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: -1, pinned: false }],
      });

      expect(labels.GroupA.urlKeys).toContain('url-z');
      const wroteLabels = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(wroteLabels).toBeUndefined();
    });

    // The sibling append site needs the same navigated-away guard recordInGroupTab
    // has. Note this site is only ever reached on a group-to-group move: the
    // function bails at `if !oldGroup || !newGroup`, so an ungroup-to-nothing
    // followed by a regroup never arrives here. The reachable case is a tab still
    // stamped under the DESTINATION label, sitting in another group, moved back in
    // after navigating. Its live URL must not become a second permanent member.
    it('refuses the append for a stamped tab moved back into the label it is filed under', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 5 ? { id: 5, title: 'GroupB', color: 'blue' }
                    : { id: 2, title: 'GroupA', color: 'red' })
      );
      const labels = {
        GroupA: { title: 'GroupA', urlKeys: [] },
        GroupB: { title: 'GroupB', urlKeys: ['url-https://b.com/one'] },
      };
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels }));

      await fns.handleActiveTabsGroupChanges({
        oldValue: [{ tabKey: 'tab-1', urlKey: 'url-https://b.com/two', groupId: 2, pinned: false }],
        newValue: [{
          tabKey: 'tab-1',
          urlKey: 'url-https://b.com/two',
          groupId: 5,
          pinned: false,
          labelTitle: 'GroupB',
          labelUrlKey: 'url-https://b.com/one',
        }],
      });

      expect(labels.GroupB.urlKeys).toEqual(['url-https://b.com/one']);
      const wroteLabels = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(wroteLabels).toBeUndefined();
    });

    // The guard is per-tab and must not block a genuine re-home: a tab stamped under
    // GroupA moved by hand into GroupB is still recorded into B and removed from A.
    it('still re-homes a stamped tab moved into a different label', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 5 ? { id: 5, title: 'GroupB', color: 'blue' }
                    : { id: 2, title: 'GroupA', color: 'red' })
      );
      const labels = {
        GroupA: { title: 'GroupA', urlKeys: ['url-z'] },
        GroupB: { title: 'GroupB', urlKeys: [] },
      };
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels }));

      await fns.handleActiveTabsGroupChanges({
        oldValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 2, pinned: false }],
        newValue: [{
          tabKey: 'tab-1',
          urlKey: 'url-z',
          groupId: 5,
          pinned: false,
          labelTitle: 'GroupA',
          labelUrlKey: 'url-z',
        }],
      });

      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(written.labels.GroupB.urlKeys).toContain('url-z');
      expect(written.labels.GroupA.urlKeys).not.toContain('url-z');
    });
  });

  describe('groupTabs', () => {
    // ungroups a tab that no longer matches any label
    it('ungroups an unlabeled grouped tab', async () => {
      await fns.groupTabs([{ tabKey: 'tab-9', urlKey: 'url-x', pinned: false, groupId: -1 }], {});
      // groupId -1 (no group) and not pinned → no ungroup; assert it does not throw
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // skips pinned tabs entirely
    it('ignores pinned tabs', async () => {
      await fns.groupTabs([{ tabKey: 'tab-1', urlKey: 'url-y', pinned: true, groupId: 2 }], {});
      expect(chrome.tabs.group).not.toHaveBeenCalled();
    });

    // A tab on its way OUT of a group (ungroup in flight) must never be recorded
    // into the group it is leaving — this is the core navigate-out bug fix.
    it('does not capture a tab whose ungroup is pending', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      state.pendingUngroups.add(7);
      const labels = { Work: { title: 'Work', urlKeys: [] } };
      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: 5 }],
        labels
      );
      expect(labels.Work.urlKeys).not.toContain('url-https://b.com');
    });

    // Guards against over-suppression: a tab that genuinely sits in a group is
    // still recorded into that group's label.
    it('captures a genuinely grouped tab', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      const labels = { Work: { title: 'Work', urlKeys: [] } };
      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: 5 }],
        labels
      );
      expect(labels.Work.urlKeys).toContain('url-https://b.com');
    });

    // A tab already inside its group must never be handed to chrome.tabs.group. On the
    // refuse-append path (recordInGroupTab returns without recording, because the tab
    // merely navigated away from its recorded slot) the tab's state is unchanged, so a
    // group call here repositions it in the tab strip on EVERY pass — the user-visible
    // "my tabs keep jumping around" loop, fed by onMoved -> updateActiveTabs ->
    // storage.onChanged -> groupTabs.
    it('never re-groups a tab that is already in the target group', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com/apps'] } };
      await fns.groupTabs(
        [{
          tabKey: 'tab-7',
          urlKey: 'url-https://a.com/apps/123',
          pinned: false,
          groupId: 5,
          windowId: 1,
          labelTitle: 'Work',
          labelUrlKey: 'url-https://a.com/apps',
        }],
        labels
      );
      expect(chrome.tabs.group).not.toHaveBeenCalled();
    });
  });

  // Every test here pins one of the paths that moved a tab with NO user input.
  // chrome.tabs.group and chrome.tabs.ungroup are repositions, not assertions, so
  // each suppressed call is a tab that stops jumping in the strip.
  describe('groupTabs tab placement', () => {
    // The steady state, and the property that damps the whole feedback loop: when
    // every tab already sits in its label's group, a pass must issue ZERO Chrome
    // calls. Any call here fires onMoved -> updateActiveTabs -> storage.onChanged
    // -> groupTabs and the cycle sustains itself.
    it('issues no chrome calls when every tab is already correctly grouped', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: 5, windowId: 1 }],
        labels
      );

      expect(chrome.tabs.group).not.toHaveBeenCalled();
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // A tab already inside a group must never be handed to groupLabeledTab AT ALL,
    // not merely be caught by the idempotence guard afterwards. If the recording
    // path still queued it, a label whose Chrome group resolves to a DIFFERENT id
    // would relocate the tab out of the group it is sitting in.
    it('never relocates an in-group tab to another group', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      // The label's group in this window resolves to 9, but the tab sits in 5.
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 9, windowId: 1, title: 'Work' }]));
      const labels = { Work: { title: 'Work', urlKeys: [] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: 5, windowId: 1 }],
        labels
      );

      expect(chrome.tabs.group).not.toHaveBeenCalled();
    });

    // Guards against over-suppression: an ungrouped tab whose urlKey is a recorded
    // member is still auto-grouped exactly once. Without this the placement guards
    // would have silently disabled the feature they were added to fix.
    it('still auto-groups an ungrouped tab whose urlKey is a member', async () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: -1, windowId: 1 }],
        labels
      );

      expect(chrome.tabs.group).toHaveBeenCalledTimes(1);
      expect(chrome.tabs.group).toHaveBeenCalledWith({ tabIds: [7], groupId: 5 });
    });

    // Cross-window pull. The title-only tabGroups.query was not window-scoped and
    // the code took groups[0], so grouping into it physically DRAGGED tabs into
    // the other window. Each window must resolve its own group.
    it('scopes the group lookup to each tab window so tabs never cross windows', async () => {
      chrome.tabGroups.query.mockImplementation((query, cb) => {
        cb([{ id: query.windowId === 1 ? 5 : 6, windowId: query.windowId, title: 'Work' }]);
      });
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com', 'url-https://b.com'] } };

      await fns.groupTabs(
        [
          { tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: -1, windowId: 1 },
          { tabKey: 'tab-8', urlKey: 'url-https://b.com', pinned: false, groupId: -1, windowId: 2 },
        ],
        labels
      );

      const queriedWindows = chrome.tabGroups.query.mock.calls.map((c) => c[0].windowId);
      expect(queriedWindows).toContain(1);
      expect(queriedWindows).toContain(2);
      // Each window's tab goes into THAT window's group, never the other's.
      expect(chrome.tabs.group).toHaveBeenCalledWith({ tabIds: [7], groupId: 5 });
      expect(chrome.tabs.group).toHaveBeenCalledWith({ tabIds: [8], groupId: 6 });
    });

    // The removed consolidate branch closed the user's tabs with chrome.tabs.remove
    // and re-created them, losing page state and dropping them at the end of the
    // strip. Grouping must never destroy a tab.
    it('never closes and re-creates tabs while grouping', async () => {
      chrome.tabGroups.query.mockImplementation((query, cb) => {
        cb([{ id: 5, windowId: query.windowId === 2 ? 2 : 1, title: 'Work' }]);
      });
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: -1, windowId: 2 }],
        labels
      );

      expect(chrome.tabs.remove).not.toHaveBeenCalled();
      expect(chrome.tabs.create).not.toHaveBeenCalled();
    });

    // A urlKey filed under TWO labels used to be queued into both buckets, so the
    // tab was moved into group A and then into group B in a single pass — and the
    // winner depended on async query ordering, so it could differ pass to pass.
    // That is the literal back-and-forth. One destination, one call.
    it('groups a tab whose urlKey is in two labels exactly once', async () => {
      chrome.tabGroups.query.mockImplementation((query, cb) => {
        cb([{ id: query.title === 'Work' ? 5 : 6, windowId: 1, title: query.title }]);
      });
      const labels = {
        Work: { title: 'Work', urlKeys: ['url-https://shared.com'] },
        Reading: { title: 'Reading', urlKeys: ['url-https://shared.com'] },
      };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://shared.com', pinned: false, groupId: -1, windowId: 1 }],
        labels
      );

      expect(chrome.tabs.group).toHaveBeenCalledTimes(1);
    });

    // Creating a Chrome group for a label whose tabs all turn out to need no move
    // would leave an empty group behind in the strip.
    it('does not create a group when no tab needs to move into it', async () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([]));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: true, groupId: -1, windowId: 1 }],
        labels
      );

      expect(chrome.tabs.group).not.toHaveBeenCalled();
    });
  });

  describe('groupTabs move trail', () => {
    // The trail exists so the next "TabCommand moved my tabs" report is provable
    // from the user's own profile. An issued move must leave an entry naming the
    // path that made it and where the tab went.
    it('records an entry for an issued group call', async () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({}));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: -1, windowId: 1 }],
        labels
      );

      const moveWrites = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .filter((w) => w.groupMoveLog);
      expect(moveWrites.length).toBeGreaterThan(0);
      const entry = moveWrites.at(-1).groupMoveLog.at(-1);
      expect(entry.action).toBe('group');
      expect(entry.source).toBe('worker:auto-group');
      expect(entry.tabId).toBe(7);
      expect(entry.fromGroupId).toBe(-1);
      expect(entry.toGroupId).toBe(5);
    });

    // A suppressed no-op moved nothing, so it must leave NO entry — that is what
    // makes a quiet steady state readable as an empty trail rather than guessed at.
    it('records nothing when the placement call is suppressed', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 5, windowId: 1, title: 'Work' }]));
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({}));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'] } };

      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://a.com', pinned: false, groupId: 5, windowId: 1 }],
        labels
      );

      const moveWrites = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .filter((w) => w.groupMoveLog);
      expect(moveWrites).toHaveLength(0);
    });
  });

  describe('urlKeyIsMember', () => {
    // a urlKey recorded in the label's urlKeys is a member
    it('is true when the urlKey is present in the label', () => {
      const label = { title: 'Work', urlKeys: ['url-https://a.com', 'url-https://b.com'] };
      expect(fns.urlKeyIsMember(label, 'url-https://b.com')).toBe(true);
    });

    // a urlKey absent from the label's urlKeys is not a member
    it('is false when the urlKey is absent', () => {
      const label = { title: 'Work', urlKeys: ['url-https://a.com'] };
      expect(fns.urlKeyIsMember(label, 'url-https://b.com')).toBe(false);
    });

    // an empty urlKeys list claims no members
    it('is false for a label with no urlKeys', () => {
      expect(fns.urlKeyIsMember({ title: 'Work', urlKeys: [] }, 'url-https://a.com')).toBe(false);
    });

    // a missing/undefined label is treated as non-membership rather than throwing,
    // so callers can pass labels[title] without a prior existence check
    it('is false when the label is undefined or null', () => {
      expect(fns.urlKeyIsMember(undefined, 'url-https://a.com')).toBe(false);
      expect(fns.urlKeyIsMember(null, 'url-https://a.com')).toBe(false);
    });
  });

  describe('stampLabelMembership', () => {
    // The stamp reports whether it CHANGED anything, not just that it ran. groupTabs
    // stamps on every pass, and its persist is a bare storage.set that re-enters
    // onChanged -> groupTabs; a constant `true` there would loop forever. A repeat
    // stamp with identical values must therefore be a no-op that returns false while
    // leaving the recorded slot intact.
    it('returns true on a fresh stamp and false when the stamp already matches', () => {
      const activeTab = { tabKey: 'tab-7', urlKey: 'url-https://b.com' };
      expect(fns.stampLabelMembership(activeTab, 'Work', 'url-https://b.com')).toBe(true);
      expect(fns.stampLabelMembership(activeTab, 'Work', 'url-https://b.com')).toBe(false);
      expect(activeTab.labelTitle).toBe('Work');
      expect(activeTab.labelUrlKey).toBe('url-https://b.com');
    });

    // A genuinely different slot is still a change, so a re-home re-stamps.
    it('returns true when the label or key differs from the existing stamp', () => {
      const activeTab = { labelTitle: 'Work', labelUrlKey: 'url-https://b.com' };
      expect(fns.stampLabelMembership(activeTab, 'Reading', 'url-https://b.com')).toBe(true);
      expect(activeTab.labelTitle).toBe('Reading');
      expect(fns.stampLabelMembership(activeTab, 'Reading', 'url-https://c.com')).toBe(true);
      expect(activeTab.labelUrlKey).toBe('url-https://c.com');
    });
  });

  describe('recordInGroupTab', () => {
    // seeds a brand-new label (carrying the group's mapped color) when none exists
    it('seeds a missing label with the tab urlKey and mapped color', () => {
      const labels = {};
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 }
      );
      expect(labels.Work.urlKeys).toEqual(['url-https://b.com']);
      expect(labels.Work.color).toBe('#1873E4');
    });

    // appends to an existing label's urlKeys rather than overwriting it
    it('pushes the urlKey into an existing label', () => {
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://a.com'], color: '#1873E4' } };
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 }
      );
      expect(labels.Work.urlKeys).toEqual(['url-https://a.com', 'url-https://b.com']);
    });

    // persists the updated labels object via update -> chrome.storage.local.set
    it('persists the updated labels to storage', () => {
      const labels = {};
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 }
      );
      const written = chrome.storage.local.set.mock.calls.map((c) => c[0]).find((o) => o && o.labels);
      expect(written.labels.Work.urlKeys).toContain('url-https://b.com');
    });

    // Reproduction: a Google Doc whose live ?tab= query has drifted since it was
    // recorded must be healed at its ORIGINAL slot on the grouping-sync path, not
    // appended to the bottom of the group. Reverting the drift-heal (plain push)
    // makes this red: the drifted key lands at the end and the doc drops to the
    // bottom of the label.
    it('rewrites a drifted Google Doc slot in place rather than pushing to the end', () => {
      const labels = {
        'Ambiguity Everywhere': {
          title: 'Ambiguity Everywhere',
          urlKeys: [
            'url-https://docs.google.com/document/d/ABC/edit?tab=t.0',
            'url-https://other.com',
          ],
          color: '#1873E4',
        },
      };
      fns.recordInGroupTab(
        labels,
        { title: 'Ambiguity Everywhere', color: 'blue' },
        {
          tabKey: 'tab-7',
          urlKey: 'url-https://docs.google.com/document/d/ABC/edit?tab=t.9',
          groupId: 5,
        }
      );
      // Healed in place at index 0 — the doc keeps its top position, no duplicate.
      expect(labels['Ambiguity Everywhere'].urlKeys).toEqual([
        'url-https://docs.google.com/document/d/ABC/edit?tab=t.9',
        'url-https://other.com',
      ]);
    });

    // Reproduction: one App Store Connect page was filed into the group, then that
    // same tab navigated deeper into the site. A path change is not a same-page
    // drift, so healDriftedLabelSlot finds no slot and the sync path appends the new
    // URL as a SECOND permanent member — which is how the CodeYam group ended up
    // with several "App Store Connect" rows from a single add.
    it('does not add a second member when the recorded tab navigates within the site', () => {
      const labels = {
        CodeYam: {
          title: 'CodeYam',
          urlKeys: ['url-https://appstoreconnect.apple.com/apps'],
          color: '#1873E4',
        },
      };
      fns.recordInGroupTab(
        labels,
        { title: 'CodeYam', color: 'blue' },
        {
          tabKey: 'tab-7',
          urlKey: 'url-https://appstoreconnect.apple.com/apps/123/distribution',
          groupId: 5,
          labelTitle: 'CodeYam',
          labelUrlKey: 'url-https://appstoreconnect.apple.com/apps',
        }
      );
      expect(labels.CodeYam.urlKeys).toEqual(['url-https://appstoreconnect.apple.com/apps']);
    });

    // The guard is per-tab-and-per-label: a tab stamped for a DIFFERENT group is
    // not the tab this label recorded, so its URL is a genuine new member.
    it('still appends when the tab is stamped for a different label', () => {
      const labels = {
        CodeYam: {
          title: 'CodeYam',
          urlKeys: ['url-https://appstoreconnect.apple.com/apps'],
          color: '#1873E4',
        },
      };
      fns.recordInGroupTab(
        labels,
        { title: 'CodeYam', color: 'blue' },
        {
          tabKey: 'tab-7',
          urlKey: 'url-https://example.com/new',
          groupId: 5,
          labelTitle: 'Work',
          labelUrlKey: 'url-https://example.com/old',
        }
      );
      expect(labels.CodeYam.urlKeys).toEqual([
        'url-https://appstoreconnect.apple.com/apps',
        'url-https://example.com/new',
      ]);
    });

    // A stale stamp must not suppress real appends forever: once the user removes
    // the recorded slot by hand, the stamp points at a non-member and the guard
    // stands down.
    it('still appends when the stamped slot is no longer a member', () => {
      const labels = {
        CodeYam: { title: 'CodeYam', urlKeys: ['url-https://other.com'], color: '#1873E4' },
      };
      fns.recordInGroupTab(
        labels,
        { title: 'CodeYam', color: 'blue' },
        {
          tabKey: 'tab-7',
          urlKey: 'url-https://appstoreconnect.apple.com/apps/123/distribution',
          groupId: 5,
          labelTitle: 'CodeYam',
          labelUrlKey: 'url-https://appstoreconnect.apple.com/apps',
        }
      );
      expect(labels.CodeYam.urlKeys).toEqual([
        'url-https://other.com',
        'url-https://appstoreconnect.apple.com/apps/123/distribution',
      ]);
    });

    // Recording a member stamps the tab with the slot it was filed under — that
    // stamp is the entire input to the navigation guard on the next sync.
    it('stamps the tab with the label and urlKey it was filed under', () => {
      const labels = {};
      const activeTab = { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 };
      fns.recordInGroupTab(labels, { title: 'Work', color: 'blue' }, activeTab);
      expect(activeTab.labelTitle).toBe('Work');
      expect(activeTab.labelUrlKey).toBe('url-https://b.com');
    });

    // The stamp only survives if it is persisted with the labels write; the caller
    // hands in the activeTabs array it came from so both land in one storage set.
    it('persists the stamped activeTabs alongside the labels write', () => {
      const labels = {};
      const activeTab = { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 };
      const activeTabs = [activeTab];
      fns.recordInGroupTab(labels, { title: 'Work', color: 'blue' }, activeTab, activeTabs);
      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(written.activeTabs[0].labelUrlKey).toBe('url-https://b.com');
    });

    // A genuinely new URL (no same-page slot) still appends, so the drift-heal
    // does not swallow real new members.
    it('still appends a genuinely new URL that shares no page with any slot', () => {
      const labels = {
        Work: { title: 'Work', urlKeys: ['url-https://a.com'], color: '#1873E4' },
      };
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 }
      );
      expect(labels.Work.urlKeys).toEqual(['url-https://a.com', 'url-https://b.com']);
    });

    // ── Reproduction (from the plan) ────────────────────────────────────────
    // The bug: deleting a group appeared to do nothing, because a tab still
    // sitting in the native Chrome group of the same title reached this
    // function, which helpfully re-seeded the label the user had just removed.
    //
    // The deletion is driven through the REAL storage.onChanged listener rather
    // than by poking the suppression set directly — "the user just deleted it"
    // is precisely a labels write whose oldValue had the title and whose
    // newValue does not, and testing it any other way would not prove the wiring.
    it('does not re-create a label the user just deleted', () => {
      const onChanged = chrome.storage.onChanged.addListener.mock.calls[0][0];

      onChanged(
        { labels: { oldValue: { Work: { title: 'Work', urlKeys: [] } }, newValue: {} } },
        areaForKey('labels')
      );

      const labels = {};
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-7', urlKey: 'url-https://a.com', groupId: 42 }
      );

      expect(labels.Work).toBeUndefined();
    });

    // The counter-case that keeps the guard from becoming "never record". A
    // genuinely pre-existing Chrome group — one the user made in Chrome, never
    // deleted here — is the whole reason recordInGroupTab exists, and startup
    // sync of it must still work.
    it('still records a group title the user never deleted', () => {
      const onChanged = chrome.storage.onChanged.addListener.mock.calls[0][0];

      onChanged(
        { labels: { oldValue: { Work: { title: 'Work', urlKeys: [] } }, newValue: {} } },
        areaForKey('labels')
      );

      const labels = {};
      fns.recordInGroupTab(
        labels,
        { title: 'Reading', color: 'green' },
        { tabKey: 'tab-8', urlKey: 'url-https://b.com', groupId: 43 }
      );

      expect(labels.Reading.urlKeys).toEqual(['url-https://b.com']);
    });

    // Re-creating a group with the same name must work immediately — the
    // suppression is cleared the moment the title is back in `labels`, so a
    // deleted-then-recreated group is not permanently unrecordable.
    it('records again once the deleted title reappears in labels', () => {
      const onChanged = chrome.storage.onChanged.addListener.mock.calls[0][0];
      const area = areaForKey('labels');

      onChanged({ labels: { oldValue: { Work: { title: 'Work' } }, newValue: {} } }, area);
      onChanged({ labels: { oldValue: {}, newValue: { Work: { title: 'Work', urlKeys: [] } } } }, area);

      const labels = {};
      fns.recordInGroupTab(
        labels,
        { title: 'Work', color: 'blue' },
        { tabKey: 'tab-9', urlKey: 'url-https://c.com', groupId: 44 }
      );

      expect(labels.Work.urlKeys).toEqual(['url-https://c.com']);
    });
  });

  describe('dissolveDeletedLabelGroups', () => {
    // Deleting a group dissolves its Chrome tab group so nothing survives to
    // re-record the label. The tabs stay open — ungroup only clears membership.
    it('ungroups every tab in the Chrome group of a deleted label', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 42, title: 'Work' }]));
      chrome.tabs.query.mockImplementation((_q, cb) => cb([{ id: 1 }, { id: 2 }]));

      fns.dissolveDeletedLabelGroups(['Work']);

      expect(chrome.tabs.ungroup).toHaveBeenCalledWith([1, 2], expect.any(Function));
    });

    // A label legitimately has one Chrome group PER WINDOW and the deletion
    // removes all of them, so every returned group is handled — not groups[0],
    // the multi-window bug groupLabeledTab already had to be fixed for.
    it('dissolves the group in every window the label spans', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) =>
        cb([{ id: 42, title: 'Work' }, { id: 43, title: 'Work' }])
      );
      chrome.tabs.query.mockImplementation((q, cb) =>
        cb(q.groupId === 42 ? [{ id: 1 }] : [{ id: 9 }])
      );

      fns.dissolveDeletedLabelGroups(['Work']);

      const ungrouped = chrome.tabs.ungroup.mock.calls.map((c) => c[0]);
      expect(ungrouped).toEqual([[1], [9]]);
    });

    // The in-flight guard must be armed BEFORE the ungroup is issued, or a
    // concurrent groupTabs pass re-records the tabs in the async gap.
    it('marks the tabs pending before issuing the ungroup', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 42, title: 'Work' }]));
      chrome.tabs.query.mockImplementation((_q, cb) => cb([{ id: 1 }]));
      // never invoke the ungroup callback — freeze the call mid-flight
      chrome.tabs.ungroup.mockImplementation(() => {});

      fns.dissolveDeletedLabelGroups(['Work']);

      expect(state.pendingUngroups.has(1)).toBe(true);
    });

    // ...and released once it lands, or the tab is permanently unrecordable.
    it('clears the pending mark in the ungroup callback', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 42, title: 'Work' }]));
      chrome.tabs.query.mockImplementation((_q, cb) => cb([{ id: 1 }]));
      chrome.tabs.ungroup.mockImplementation((_ids, cb) => cb());

      fns.dissolveDeletedLabelGroups(['Work']);

      expect(state.pendingUngroups.has(1)).toBe(false);
    });

    // The COMMON case: deleting a group whose tabs are all closed. No Chrome
    // group exists, and that must be a silent no-op rather than an error.
    it('is a no-op when the deleted label has no Chrome group', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([]));

      expect(() => fns.dissolveDeletedLabelGroups(['Work'])).not.toThrow();
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // An existing group holding no tabs must not produce an empty ungroup call.
    it('issues no ungroup when the group holds no tabs', () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 42, title: 'Work' }]));
      chrome.tabs.query.mockImplementation((_q, cb) => cb([]));

      fns.dissolveDeletedLabelGroups(['Work']);

      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // The ungroup is auditable like every other grouping mutation, under its own
    // source so a user deletion is distinguishable from an autonomous eject.
    it('records the ungroup in the move log under the deletion source', async () => {
      chrome.tabGroups.query.mockImplementation((_q, cb) => cb([{ id: 42, title: 'Work' }]));
      chrome.tabs.query.mockImplementation((_q, cb) => cb([{ id: 1 }]));
      // recordMove reads the existing log before appending; the default stub
      // never invokes its callback, so the write would never be issued.
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({}));

      fns.dissolveDeletedLabelGroups(['Work']);
      await Promise.resolve();

      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o[GROUP_MOVE_LOG_KEY]);
      const entry = written[GROUP_MOVE_LOG_KEY][0];
      expect(entry.source).toBe(MoveSource.WORKER_LABEL_DELETED);
      expect(entry.action).toBe('ungroup');
      expect(entry.toGroupId).toBe(-1);
      expect(entry.fromGroupId).toBe(42);
      expect(entry.label).toBe('Work');
      expect(entry.tabId).toBe(1);
    });
  });

  describe('ejectAutoGroupedTab', () => {
    // While the real URL has not loaded (urlKey is the bare 'url-' placeholder),
    // ejection is deferred so we never act on the transient about:blank state.
    it('returns wait and does nothing while the URL is still unloaded', async () => {
      state.autoGroupedTabs.add(7);
      const result = await fns.ejectAutoGroupedTab(
        { tabKey: 'tab-7', urlKey: 'url-', groupId: 5 },
        'Work'
      );
      expect(result).toBe('wait');
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
      expect(state.autoGroupedTabs.has(7)).toBe(true);
    });

    // Flicker guard: the in-memory snapshot said non-member, but FRESH storage
    // shows the URL is a genuine member (an overlapping event just added it) —
    // keep the tab grouped, clear the flag, and do not ungroup.
    it('keeps the tab and clears the flag when fresh storage shows membership', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ labels: { Work: { title: 'Work', urlKeys: ['url-https://b.com'] } } })
      );
      state.autoGroupedTabs.add(7);
      const result = await fns.ejectAutoGroupedTab(
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', groupId: 5 },
        'Work'
      );
      expect(result).toBe('kept');
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
      expect(state.autoGroupedTabs.has(7)).toBe(false);
    });

    // The URL is a non-member in fresh storage too — eject: ungroup the tab,
    // mark the in-flight ungroup in pendingUngroups, and clear the auto-group flag.
    it('ungroups a confirmed non-member and tracks the in-flight ungroup', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ labels: { Work: { title: 'Work', urlKeys: [] } } })
      );
      state.autoGroupedTabs.add(7);
      const result = await fns.ejectAutoGroupedTab(
        { tabKey: 'tab-7', urlKey: 'url-https://new.com', groupId: 5 },
        'Work'
      );
      expect(result).toBe('ejected');
      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(7, expect.any(Function));
      expect(state.pendingUngroups.has(7)).toBe(true);
      expect(state.autoGroupedTabs.has(7)).toBe(false);
    });
  });

  describe('auto-grouped stickiness fix integration', () => {
    // The core bug fix: a tab Chrome auto-placed into a group whose URL is not a
    // deliberate label member must be EJECTED, never recorded into the label.
    it('ejects an auto-grouped non-member and does not record its URL', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ labels: { Work: { title: 'Work', urlKeys: [] } } })
      );
      state.autoGroupedTabs.add(7);
      const labels = { Work: { title: 'Work', urlKeys: [] } };
      await fns.groupTabs(
        [{ tabKey: 'tab-7', urlKey: 'url-https://new.com', pinned: false, groupId: 5 }],
        labels
      );
      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(7, expect.any(Function));
      expect(labels.Work.urlKeys).not.toContain('url-https://new.com');
    });

    // Membership beats the flag: an auto-grouped tab whose URL IS a deliberate
    // member stays grouped, gets its flag cleared, and is never ungrouped.
    it('keeps an auto-grouped tab whose URL is a deliberate member', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      state.autoGroupedTabs.add(7);
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://b.com'] } };
      const activeTab = { tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: 5 };
      await fns.groupTabs([activeTab], labels);
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
      expect(state.autoGroupedTabs.has(7)).toBe(false);
      // Confirming membership also records the slot — this is the branch the stamp
      // was added to, so the flag-clearing and the stamp must happen together.
      expect(activeTab.labelTitle).toBe('Work');
      expect(activeTab.labelUrlKey).toBe('url-https://b.com');
    });

    // Reproduction (root cause): a tab sitting in a group on a URL that IS already a
    // deliberate member takes groupTabs' urlKeyIsMember `continue` branch, which
    // confirms membership without recording WHICH slot the tab occupies. The append
    // guard reads only that stamp, so on this path it is permanently blind.
    it('stamps the label slot a confirmed member tab occupies', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'CodeYam', color: 'blue' }));
      const labels = {
        CodeYam: { title: 'CodeYam', urlKeys: ['url-https://appstoreconnect.apple.com/apps'] },
      };
      const activeTab = {
        tabKey: 'tab-7',
        urlKey: 'url-https://appstoreconnect.apple.com/apps',
        pinned: false,
        groupId: 5,
      };
      await fns.groupTabs([activeTab], labels);
      expect(activeTab.labelTitle).toBe('CodeYam');
      expect(activeTab.labelUrlKey).toBe('url-https://appstoreconnect.apple.com/apps');
    });

    // Reproduction (user-visible): open a page already in the group, navigate deeper
    // into the same site, sync again. A path change is not a same-page drift, so the
    // heal finds no slot -- and with no stamp from the first pass the guard cannot
    // fire, so the second page is appended as a permanent second member.
    it('does not gain a member when a grouped tab navigates within the site', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'CodeYam', color: 'blue' }));
      const labels = {
        CodeYam: { title: 'CodeYam', urlKeys: ['url-https://appstoreconnect.apple.com/apps'] },
      };
      const activeTab = {
        tabKey: 'tab-7',
        urlKey: 'url-https://appstoreconnect.apple.com/apps',
        pinned: false,
        groupId: 5,
      };
      // Pass 1: the tab is confirmed as a member of the group it is sitting in.
      await fns.groupTabs([activeTab], labels);
      // The user navigates deeper into the same site; the tab is still in the group
      // (the onUpdated eject is async, and its pendingUngroups set is empty after an
      // MV3 teardown).
      activeTab.urlKey = 'url-https://appstoreconnect.apple.com/apps/123/distribution';
      await fns.groupTabs([activeTab], labels);
      expect(labels.CodeYam.urlKeys).toEqual(['url-https://appstoreconnect.apple.com/apps']);
    });

    // The other confirm path: an UNGROUPED tab whose urlKey already matches a label
    // is about to be auto-added to that group. That is the earliest point the binding
    // is known -- it fires when the user clicks a group row, before Chrome's
    // tabs.group has landed -- so it must stamp too, closing the window where the
    // in-group confirm branch has not run yet.
    it('stamps an ungrouped tab whose urlKey matches a label', async () => {
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://b.com'] } };
      const activeTab = { tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: -1 };
      await fns.groupTabs([activeTab], labels);
      expect(activeTab.labelTitle).toBe('Work');
      expect(activeTab.labelUrlKey).toBe('url-https://b.com');
    });

    // The stamps are persisted in ONE batched write per pass, and a pass that stamps
    // nothing new must not write at all: update is a bare storage.local.set whose
    // write re-enters onChanged -> groupTabs, so an unconditional write here would
    // be an infinite write loop. Two tabs stamping in the same pass therefore
    // produce a single activeTabs write, and an identical second pass produces none.
    it('persists stamps in one write per pass and skips the write when nothing changed', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work', color: 'blue' }));
      const labels = { Work: { title: 'Work', urlKeys: ['url-https://b.com'] } };
      const activeTabs = [
        { tabKey: 'tab-7', urlKey: 'url-https://b.com', pinned: false, groupId: 5 },
        { tabKey: 'tab-8', urlKey: 'url-https://b.com', pinned: false, groupId: 5 },
      ];

      await fns.groupTabs(activeTabs, labels);
      const firstPassWrites = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .filter((o) => o && o.activeTabs);
      expect(firstPassWrites).toHaveLength(1);
      expect(activeTabs[0].labelUrlKey).toBe('url-https://b.com');
      expect(activeTabs[1].labelUrlKey).toBe('url-https://b.com');

      chrome.storage.local.set.mockClear();
      await fns.groupTabs(activeTabs, labels);
      const secondPassWrites = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .filter((o) => o && o.activeTabs);
      expect(secondPassWrites).toHaveLength(0);
    });

    // An explicit groupId change is user intent and must clear an earlier
    // auto-group flag so groupTabs won't later yank the deliberately-moved tab out.
    it('clears the auto-group flag on a deliberate group change', async () => {
      chrome.tabGroups.get.mockImplementation((id, cb) =>
        cb(id === 5 ? { id: 5, title: 'NewGroup', color: 'blue' }
                    : { id: 2, title: 'OldGroup', color: 'red' })
      );
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ labels: {} }));
      state.autoGroupedTabs.add(1);
      await fns.handleActiveTabsGroupChanges({
        oldValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 2, pinned: false }],
        newValue: [{ tabKey: 'tab-1', urlKey: 'url-z', groupId: 5, pinned: false }],
      });
      expect(state.autoGroupedTabs.has(1)).toBe(false);
    });

    // onRemoved must clear the flag so the in-memory set never leaks stale tab ids
    // after a flagged tab is closed.
    it('clears the auto-group flag when a flagged tab is removed', async () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ activeTabs: [] }));
      state.autoGroupedTabs.add(9);
      const onRemoved = chrome.tabs.onRemoved.addListener.mock.calls[0][0];
      await onRemoved(9, {});
      expect(state.autoGroupedTabs.has(9)).toBe(false);
    });
  });

  describe('debugGroup', () => {
    // The grouping tracer is gated behind DEBUG_GROUPING (off in production), so a
    // call is a safe no-op that never throws regardless of the payload shape.
    it('is a no-op that does not throw when disabled', () => {
      expect(() => fns.debugGroup('some-event', { tabId: 7, urlKey: 'url-x' })).not.toThrow();
      expect(fns.debugGroup('some-event', {})).toBeUndefined();
    });

    // MV3 recycles the worker constantly, so breadcrumbs must persist to storage
    // when the runtime `debugGrouping` flag is on — this is what makes a
    // cross-restart grouping bug diagnosable after the fact.
    it('persists a breadcrumb to groupingLog when the runtime flag is on', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ debugGrouping: true, groupingLog: [{ event: 'old' }] })
      );
      fns.debugGroup('heal', { tabId: 7, urlKey: 'url-x' });
      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.groupingLog);
      expect(written).toBeTruthy();
      expect(written.groupingLog).toHaveLength(2);
      expect(written.groupingLog[1]).toMatchObject({ event: 'heal', details: { tabId: 7, urlKey: 'url-x' } });
    });

    // With the flag off (the default), the breadcrumb must NOT be written — the
    // diagnostics are opt-in so production storage is never touched with log noise.
    it('does not persist when the runtime flag is off', () => {
      chrome.storage.local.get.mockImplementation((_q, cb) => cb({ debugGrouping: false }));
      fns.debugGroup('heal', { tabId: 7 });
      const written = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.groupingLog);
      expect(written).toBeUndefined();
    });
  });

  describe('onUpdated group leave keeps member sticky', () => {
    // Sets the module-level `labels` by driving the storage.onChanged listener,
    // which mirrors how the worker keeps `labels` in sync at runtime.
    // `labels` lives in chrome.storage.sync now, so its change events carry
    // areaName 'sync'. The worker's listener gates each key against ITS OWN
    // area, so firing this as 'local' would be silently ignored — exactly what
    // would happen in the real extension.
    const setLabels = (chrome, labelsObj) => {
      const onChanged = chrome.storage.onChanged.addListener.mock.calls[0][0];
      onChanged({ labels: { newValue: labelsObj, oldValue: {} } }, areaForKey('labels'));
    };

    // Membership is sticky: a tab leaving all groups (groupId → -1) — Chrome's
    // native ungroup, a nav-eject, or MV3 restart flicker — ungroups the tab
    // visually but must NOT delete the recorded member. Only explicit user
    // actions or a genuine re-home remove a urlKey. Reopening the URL later
    // auto-regroups it via groupTabs. (A fragment on the live URL is included to
    // show even a normalized-key member survives, where the old cleanup removed it.)
    it('keeps the member when a tab leaves a group', async () => {
      chrome.storage.local.get.mockImplementation((query, cb) => {
        const keys = typeof query === 'string' ? [query] : Array.isArray(query) ? query : Object.keys(query);
        const res = {};
        for (const k of keys) {
          if (k === 'activeTabs') {
            res.activeTabs = [{ tabKey: 'tab-3', urlKey: 'url-https://docs.com/page', groupId: 5 }];
          } else if (k === 'allUrls') res.allUrls = [];
          else if (k === 'autoClosed') res.autoClosed = {};
          else if (k === 'labels') res.labels = {};
        }
        cb(res);
      });
      chrome.tabs.query.mockImplementation((_q, cb) => cb && cb([]));

      const labelsObj = { Work: { title: 'Work', urlKeys: ['url-https://docs.com/page'] } };
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });

      const onUpdated = chrome.tabs.onUpdated.addListener.mock.calls[0][0];
      await onUpdated(3, { groupId: -1 }, { id: 3, url: 'https://docs.com/page#section' });

      // labelsObj is the same module-level reference — the member survives.
      expect(labelsObj.Work.urlKeys).toContain('url-https://docs.com/page');
    });

    // The tab is still marked ungrouped in activeTabs (bookkeeping preserved),
    // even though its membership is left intact.
    it('marks the tab ungrouped in activeTabs without touching labels', async () => {
      chrome.storage.local.get.mockImplementation((query, cb) => {
        const keys = typeof query === 'string' ? [query] : Array.isArray(query) ? query : Object.keys(query);
        const res = {};
        for (const k of keys) {
          if (k === 'activeTabs') {
            res.activeTabs = [{ tabKey: 'tab-3', urlKey: 'url-https://docs.com/page', groupId: 5 }];
          } else if (k === 'allUrls') res.allUrls = [];
          else if (k === 'autoClosed') res.autoClosed = {};
          else if (k === 'labels') res.labels = {};
        }
        cb(res);
      });
      chrome.tabs.query.mockImplementation((_q, cb) => cb && cb([]));

      const labelsObj = { Work: { title: 'Work', urlKeys: ['url-https://docs.com/page'] } };
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });

      const onUpdated = chrome.tabs.onUpdated.addListener.mock.calls[0][0];
      await onUpdated(3, { groupId: -1 }, { id: 3, url: 'https://docs.com/page#section' });

      const wroteActiveTabs = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.activeTabs);
      expect(wroteActiveTabs.activeTabs.find((t) => t.tabKey === 'tab-3').groupId).toBe(-1);
      // labels must never be written on this path.
      const wroteLabels = chrome.storage.local.set.mock.calls
        .map((c) => c[0])
        .find((o) => o && o.labels);
      expect(wroteLabels).toBeUndefined();
    });
  });

  describe('onUpdated in-page URL change keeps tab grouped', () => {
    // Storage mock that reports a single grouped tab whose stored urlKey is
    // `oldUrlKey`, so the handler's `oldTabUrl` lookup resolves and the eject
    // path runs. Everything else answers empty so newUrl can complete.
    const storageWithGroupedTab = (chrome, oldUrlKey, labelsObj) => {
      chrome.storage.local.get.mockImplementation((query, cb) => {
        const keys = typeof query === 'string' ? [query] : Array.isArray(query) ? query : Object.keys(query);
        const res = {};
        for (const k of keys) {
          if (k === 'activeTabs') {
            res.activeTabs = [{ tabKey: 'tab-3', urlKey: oldUrlKey, groupId: 5 }];
          } else if (k === 'allUrls') res.allUrls = [oldUrlKey];
          else if (k === 'autoClosed') res.autoClosed = {};
          else if (k === 'labels') res.labels = labelsObj || {};
        }
        cb(res);
      });
      chrome.tabs.query.mockImplementation((_q, cb) => cb && cb([]));
      // The in-page heal branch resolves the group's title, falling back to
      // getTabGroup when the in-memory `groups` map is cold (common right after a
      // service-worker restart). Resolve it here so that fallback completes
      // instead of hanging on an unmocked callback.
      chrome.tabGroups.get.mockImplementation((id, cb) => cb({ id, title: 'Work' }));
    };

    const getHandler = (chrome) => chrome.tabs.onUpdated.addListener.mock.calls[0][0];

    // Publishes `labelsObj` into the worker's module-level `labels` the same way
    // the runtime does — by driving the storage.onChanged listener — so the heal
    // branch reads it and mutations are visible on the same object reference.
    // `labels` lives in chrome.storage.sync now, so its change events carry
    // areaName 'sync'. The worker's listener gates each key against ITS OWN
    // area, so firing this as 'local' would be silently ignored — exactly what
    // would happen in the real extension.
    const setLabels = (chrome, labelsObj) => {
      const onChanged = chrome.storage.onChanged.addListener.mock.calls[0][0];
      onChanged({ labels: { newValue: labelsObj, oldValue: {} } }, areaForKey('labels'));
    };

    // The reported bug: a Google Docs tab in a group rewrites only its `?tab=`
    // query string in-page. Origin + path are unchanged, so this is NOT a
    // navigation and the tab must stay in its group — ungroup is not called.
    it('does not ungroup a grouped tab on a query-string-only change', async () => {
      const base = 'https://docs.google.com/document/d/1GMK/edit';
      storageWithGroupedTab(chrome, `url-${base}?tab=t.whli3qfeqr1i`);
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}?tab=t.other` },
        { id: 3, url: `${base}?tab=t.other`, groupId: 5, incognito: false }
      );

      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // A fragment-only change (SPA anchor navigation) is also in-page: same
    // origin + path, so the tab stays grouped.
    it('does not ungroup a grouped tab on a fragment-only change', async () => {
      const base = 'https://app.example.com/board';
      storageWithGroupedTab(chrome, `url-${base}`);
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}#card-42` },
        { id: 3, url: `${base}#card-42`, groupId: 5, incognito: false }
      );

      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // Guards against over-correction: a real navigation to a different path is
    // still a navigation, so the grouped tab is ejected exactly as before.
    it('still ungroups a grouped tab that navigates to a different path', async () => {
      storageWithGroupedTab(chrome, 'url-https://example.com/a');
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: 'https://example.com/b' },
        { id: 3, url: 'https://example.com/b', groupId: 5, incognito: false }
      );

      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(3, expect.any(Function));
    });

    // A cross-origin navigation is likewise a real navigation and still ejects.
    it('still ungroups a grouped tab that navigates to a different origin', async () => {
      storageWithGroupedTab(chrome, 'url-https://example.com/page');
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: 'https://other.com/page' },
        { id: 3, url: 'https://other.com/page', groupId: 5, incognito: false }
      );

      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(3, expect.any(Function));
    });

    // Sticky membership: a navigation-eject ungroups the tab visually, but the
    // recorded member must survive — it is not an explicit removal or a re-home.
    it('keeps the member when a navigation ejects a grouped tab', async () => {
      const key = 'url-https://example.com/a';
      const labelsObj = { Work: { title: 'Work', urlKeys: [key] } };
      storageWithGroupedTab(chrome, key, labelsObj);
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: 'https://example.com/b' },
        { id: 3, url: 'https://example.com/b', groupId: 5, incognito: false }
      );

      // The tab leaves the group visually...
      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(3, expect.any(Function));
      // ...but its membership stays intact (sticky).
      expect(labelsObj.Work.urlKeys).toContain(key);
    });

    // The reported bug, fixed at the root: a Google Docs tab recorded under one
    // `?tab=` key rewrites its query in-page. The label's stale urlKey must be
    // healed to follow the live URL so downstream exact-key comparisons keep
    // matching — otherwise reconciliation later drops the doc from the group.
    it('heals the drifted label urlKey to the live key on a query-only change', async () => {
      const base = 'https://docs.google.com/document/d/1GMK/edit';
      const staleKey = `url-${base}?tab=t.A`;
      const liveKey = `url-${base}?tab=t.B`;
      const labelsObj = { Work: { title: 'Work', urlKeys: [staleKey] } };
      storageWithGroupedTab(chrome, staleKey, labelsObj);
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}?tab=t.B` },
        { id: 3, url: `${base}?tab=t.B`, groupId: 5, incognito: false }
      );

      expect(labelsObj.Work.urlKeys).toEqual([liveKey]);
      expect(chrome.tabs.ungroup).not.toHaveBeenCalled();
    });

    // The recorded key may be a THIRD `?tab=` variant, not the immediately
    // previous one — locating the drifted slot by page identity (samePageKey)
    // still finds and rewrites it.
    it('heals a stale slot even when it is a third query variant', async () => {
      const base = 'https://docs.google.com/document/d/1GMK/edit';
      const recordedKey = `url-${base}?tab=t.A`;   // what the label holds
      const previousKey = `url-${base}?tab=t.B`;   // the tab's last-seen live key
      const liveKey = `url-${base}?tab=t.C`;        // where it is drifting to now
      const labelsObj = { Work: { title: 'Work', urlKeys: [recordedKey] } };
      storageWithGroupedTab(chrome, previousKey, labelsObj);
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}?tab=t.C` },
        { id: 3, url: `${base}?tab=t.C`, groupId: 5, incognito: false }
      );

      expect(labelsObj.Work.urlKeys).toEqual([liveKey]);
    });

    // If the live key is already recorded elsewhere in the label, healing must
    // remove the stale slot rather than create a duplicate entry.
    it('removes the stale slot without duplicating an already-present live key', async () => {
      const base = 'https://docs.google.com/document/d/1GMK/edit';
      const staleKey = `url-${base}?tab=t.A`;
      const liveKey = `url-${base}?tab=t.B`;
      const labelsObj = { Work: { title: 'Work', urlKeys: [staleKey, liveKey] } };
      storageWithGroupedTab(chrome, staleKey, labelsObj);
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}?tab=t.B` },
        { id: 3, url: `${base}?tab=t.B`, groupId: 5, incognito: false }
      );

      expect(labelsObj.Work.urlKeys).toEqual([liveKey]);
    });

    // A real navigation must NOT heal — the tab is ejected and the label is left
    // untouched, so heal only ever fires on an in-page change.
    it('does not heal the label on a real navigation', async () => {
      const staleKey = 'url-https://example.com/a';
      const labelsObj = { Work: { title: 'Work', urlKeys: [staleKey] } };
      storageWithGroupedTab(chrome, staleKey, labelsObj);
      setLabels(chrome, labelsObj);
      fns.trackGroup({ id: 5, title: 'Work' });
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: 'https://example.com/b' },
        { id: 3, url: 'https://example.com/b', groupId: 5, incognito: false }
      );

      expect(chrome.tabs.ungroup).toHaveBeenCalledWith(3, expect.any(Function));
      expect(labelsObj.Work.urlKeys).toEqual([staleKey]);
    });

    // Cold `groups` map (service worker just restarted): the title is not in the
    // in-memory map, so the heal must resolve it via getTabGroup and still
    // rewrite the drifted key.
    it('heals via the getTabGroup fallback when the groups map is cold', async () => {
      const base = 'https://docs.google.com/document/d/1GMK/edit';
      const staleKey = `url-${base}?tab=t.A`;
      const liveKey = `url-${base}?tab=t.B`;
      const labelsObj = { Work: { title: 'Work', urlKeys: [staleKey] } };
      storageWithGroupedTab(chrome, staleKey, labelsObj);
      setLabels(chrome, labelsObj);
      // Intentionally NO trackGroup — groups[5] is undefined, forcing the
      // getTabGroup fallback (mocked in storageWithGroupedTab to title 'Work').
      const onUpdated = getHandler(chrome);

      await onUpdated(
        3,
        { url: `${base}?tab=t.B` },
        { id: 3, url: `${base}?tab=t.B`, groupId: 5, incognito: false }
      );

      expect(labelsObj.Work.urlKeys).toEqual([liveKey]);
    });
  });

  // Channel-based degradation: the gauge's data source depends on which Chrome
  // API is available. processProcesses (Dev/Canary) tags 'processes'; the
  // system poll (stable Chrome) tags 'system'; neither tags 'none'.
  describe('load source fallback', () => {
    const cpuInfo = {
      processors: [
        { usage: { kernel: 10, user: 10, idle: 80, total: 100 } },
        { usage: { kernel: 20, user: 10, idle: 70, total: 100 } },
      ],
    };
    const memoryInfo = { capacity: 1000, availableCapacity: 400 }; // 60% used

    // Dev/Canary path: processes present → listener registered and the first
    // totals write is tagged loadDataSource:'processes'
    it("tags 'processes' and keeps processing when chrome.processes is present", async () => {
      // default `chrome` from beforeEach has chrome.processes
      expect(chrome.processes.onUpdatedWithMemory.addListener).toHaveBeenCalledWith(fns.processProcesses);
      await fns.processProcesses({});
      const writes = chrome.storage.local.set.mock.calls.map((c) => c[0]);
      expect(writes.some((w) => w.loadDataSource === 'processes')).toBe(true);
    });

    // stable Chrome: no processes API, but chrome.system.* present → one poll
    // writes a normalized processTotals tagged loadDataSource:'system'
    it("falls back to chrome.system and tags 'system' when processes is absent", async () => {
      const c = makeChrome();
      delete c.processes;
      c.system = {
        cpu: { getInfo: vi.fn().mockResolvedValue(cpuInfo) },
        memory: { getInfo: vi.fn().mockResolvedValue(memoryInfo) },
      };
      const loaded = loadWorker(c);
      // let the load-time poll resolve and schedule its repeat, then silence it
      await new Promise((r) => setTimeout(r, 0));
      loaded.fns.stopSystemLoadPolling();
      c.storage.local.set.mockClear();

      await loaded.fns.pollSystemLoad();
      loaded.fns.stopSystemLoadPolling();

      const last = c.storage.local.set.mock.calls.at(-1)[0];
      expect(last.loadDataSource).toBe('system');
      expect(last.processTotals).toBeTruthy();
      // memory pressure flows through on a single sample (never NaN)
      expect(last.processTotals.privateMemory).toBeGreaterThan(0);
      expect(Number.isNaN(last.processTotals.cpu)).toBe(false);
    });

    // neither API available → loadDataSource:'none', written once at init,
    // and nothing throws
    it("tags 'none' and never throws when no load API is available", () => {
      const c = makeChrome();
      delete c.processes;
      // no c.system at all
      expect(() => loadWorker(c)).not.toThrow();
      expect(c.storage.local.set).toHaveBeenCalledWith({ loadDataSource: 'none' });
    });

    // a thrown system call degrades to 'none' rather than crashing the worker
    it('degrades to none when a system call throws', async () => {
      const c = makeChrome();
      delete c.processes;
      c.system = {
        cpu: { getInfo: vi.fn().mockRejectedValue(new Error('denied')) },
        memory: { getInfo: vi.fn().mockResolvedValue(memoryInfo) },
      };
      const loaded = loadWorker(c);
      c.storage.local.set.mockClear();
      await loaded.fns.pollSystemLoad();
      loaded.fns.stopSystemLoadPolling();
      expect(c.storage.local.set).toHaveBeenCalledWith({ loadDataSource: 'none' });
    });
  });

  // The "Closer" engine: a periodic alarm sweeps inactive tabs, removing them and
  // recording each into the autoClosed map so the "Automatically Closed" UI lights up.
  describe('autoCloseSweep', () => {
    const MINUTE = 60 * 1000;

    // Drives one sweep against the supplied storage and returns the removed tab
    // ids plus the autoClosed map that was persisted.
    const runSweep = ({ activeTabs = [], autoClosed = {}, settings = {} }) => {
      chrome.storage.local.get.mockImplementation((_q, cb) =>
        cb({ activeTabs, autoClosed, settings })
      );
      chrome.storage.local.set.mockClear();
      chrome.tabs.remove.mockClear();
      fns.autoCloseSweep();
      const lastSet = chrome.storage.local.set.mock.calls.at(-1);
      return {
        written: lastSet ? lastSet[0].autoClosed : undefined,
        removedIds: chrome.tabs.remove.mock.calls.map((c) => c[0]),
      };
    };

    const tab = (over) => ({
      tabKey: 'tab-1',
      urlKey: 'url-https://x.com',
      pinned: false,
      groupId: -1,
      tabCommandPinned: false,
      active: false,
      ...over,
    });

    // a periodic alarm + onAlarm listener are wired up at load
    it('registers the auto-close alarm at load', () => {
      expect(chrome.alarms.create).toHaveBeenCalledWith('auto-close-sweep', { periodInMinutes: 1 });
      expect(chrome.alarms.onAlarm.addListener).toHaveBeenCalled();
    });

    // an inactive ungrouped tab past the threshold is removed and recorded
    it('closes and records an inactive ungrouped tab', () => {
      const now = Date.now();
      const t = tab({ tabKey: 'tab-5', urlKey: 'url-old', activeAt: now - 200 * MINUTE, openedAt: now - 300 * MINUTE });
      const { written, removedIds } = runSweep({ activeTabs: [t] });
      expect(removedIds).toContain(5);
      expect(written['url-old']).toBeGreaterThan(0);
    });

    // pinned, thumbtack-pinned, and the active tab are exempt
    it('never closes pinned, tabCommandPinned, or the active tab', () => {
      const now = Date.now();
      const old = now - 200 * MINUTE;
      const { written, removedIds } = runSweep({
        activeTabs: [
          tab({ tabKey: 'tab-1', urlKey: 'url-pinned', pinned: true, activeAt: old }),
          tab({ tabKey: 'tab-2', urlKey: 'url-thumb', tabCommandPinned: true, activeAt: old }),
          tab({ tabKey: 'tab-3', urlKey: 'url-active', active: true, activeAt: old }),
        ],
      });
      expect(removedIds).toEqual([]);
      expect(written['url-pinned']).toBeUndefined();
      expect(written['url-thumb']).toBeUndefined();
      expect(written['url-active']).toBeUndefined();
    });

    // a tab active within the threshold window is left open
    it('keeps a tab that was active within the window', () => {
      const now = Date.now();
      const t = tab({ tabKey: 'tab-7', urlKey: 'url-recent', activeAt: now - 10 * MINUTE });
      const { written, removedIds } = runSweep({ activeTabs: [t] });
      expect(removedIds).toEqual([]);
      expect(written['url-recent']).toBeUndefined();
    });

    // grouped/labeled inactive tabs are in scope and get closed
    it('closes a grouped/labeled inactive tab', () => {
      const now = Date.now();
      const t = tab({ tabKey: 'tab-8', urlKey: 'url-grouped', groupId: 42, activeAt: now - 200 * MINUTE });
      const { removedIds } = runSweep({ activeTabs: [t] });
      expect(removedIds).toContain(8);
    });

    // a throwing chrome.tabs.remove for one tab does not abort the others
    it('continues the sweep when one tab removal throws', () => {
      chrome.tabs.remove.mockImplementation((id) => {
        if (id === 1) throw new Error('No tab with id: 1');
      });
      const now = Date.now();
      const old = now - 200 * MINUTE;
      const { written, removedIds } = runSweep({
        activeTabs: [
          tab({ tabKey: 'tab-1', urlKey: 'url-a', activeAt: old }),
          tab({ tabKey: 'tab-2', urlKey: 'url-b', activeAt: old }),
        ],
      });
      expect(removedIds).toContain(2);
      expect(written['url-a']).toBeGreaterThan(0);
      expect(written['url-b']).toBeGreaterThan(0);
    });

    // entries older than the retention window are pruned from the map
    it('prunes autoClosed entries older than MAX_AUTO_CLOSED_TIME', () => {
      const now = Date.now();
      const { written } = runSweep({
        activeTabs: [],
        autoClosed: {
          'url-fresh': now - 1000,
          'url-stale': now - 1000 * 60 * 60 * 24 * 6, // 6 days > 5-day window
        },
      });
      expect(written['url-fresh']).toBeDefined();
      expect(written['url-stale']).toBeUndefined();
    });

    // a shorter user-configured threshold closes a tab the default would keep
    it('respects a custom settings.autoCloseMinutes', () => {
      const now = Date.now();
      const t = tab({ tabKey: 'tab-9', urlKey: 'url-mid', activeAt: now - 90 * MINUTE });
      // default (120) keeps a 90-min-idle tab
      expect(runSweep({ activeTabs: [t] }).removedIds).toEqual([]);
      // a 60-min threshold closes it
      expect(runSweep({ activeTabs: [t], settings: { autoCloseMinutes: 60 } }).removedIds).toContain(9);
    });

    // the "Off" position (0) disables closing entirely
    it('closes nothing when autoCloseMinutes is 0 meaning Off', () => {
      const now = Date.now();
      const t = tab({ tabKey: 'tab-10', urlKey: 'url-off', activeAt: now - 300 * MINUTE });
      const { written, removedIds } = runSweep({ activeTabs: [t], settings: { autoCloseMinutes: 0 } });
      expect(removedIds).toEqual([]);
      expect(written['url-off']).toBeUndefined();
    });

    describe('autoCloseThresholdMinutes', () => {
      // unset → default; 0 → Off; a positive value passes through
      it('falls back to the default and maps Off to 0', () => {
        expect(fns.autoCloseThresholdMinutes({})).toBe(120);
        expect(fns.autoCloseThresholdMinutes({ autoCloseMinutes: 0 })).toBe(0);
        expect(fns.autoCloseThresholdMinutes({ autoCloseMinutes: 45 })).toBe(45);
      });
    });
  });
});