DEV Community: Danila Pryadko

How I restored Chrome tab groups without scrambling tab order

Danila Pryadko — Sun, 09 Aug 2026 17:53:50 +0000

A two-pass restore algorithm that preserves global tab order, duplicate URLs, pinned tabs, group metadata, and the active tab — and reports partial failures.

Disclosure: I build Tabwell, a local-first Chrome session manager.

My first restore implementation passed the only assertion I had: every saved URL reopened. Then I used it on a mixed grouped-and-ungrouped session that the test did not cover.

I'd saved a window with a pinned Gmail tab, a research group, a build group, and a few loose tabs in between. Hit restore. Every URL opened. And the window was still wrong — the loose tabs were bunched at the end instead of sitting between the groups, the duplicate URLs could no longer be distinguished during regrouping, and the intended active tab was lost. Nothing crashed. No error anywhere. The session was just... not my session anymore. That's the moment this post is about: a browser session can look successfully restored and still be damaged.

Here's a layout that breaks naive implementations:

[pinned tab]
→ [Research: A, B]
→ [ungrouped C]
→ [Build: D, D]
→ [ungrouped E]

The two D tabs intentionally contain the same URL.

The tempting way to restore this is one group at a time, then the ungrouped tabs at the end. All URLs reopen, so a simple "did everything open" test passes. But the tab strip no longer matches the original global order — C is no longer between the groups, and, if URL is used as the mapping key, the two Ds collapse into one mapping entry.

While building restore for Tabwell, I eventually stopped thinking of it as "reopen a list of URLs" and started treating it as reconstruction of a small object graph.

What does "restored" actually mean?

Before rewriting the algorithm I had to pin down the contract, because "it works" was clearly not a spec.

For one saved Chrome window, a successful restore should preserve:

the global order of tabs;
separate instances of duplicate URLs;
pinned state;
the intended active tab;
group membership;
each group's title, color, and collapsed state;
the original window state, where Chrome allows it.

It should also report partial success honestly. If nine of ten tabs open, a generic "success" is a lie. But throwing the whole result away isn't obviously better either — a window with nine perfectly good tabs already exists on the user's screen.

And some things a URL-based snapshot simply cannot bring back: text typed into forms, scroll position, unsaved editor state, application state hiding behind an unchanged URL, anything that happened after the snapshot. I treat that boundary as a product constraint, not just a code detail, because users will otherwise assume more.

Runtime IDs are references, not identities

Chrome gives every tab and tab group a numeric ID. Those IDs identify objects in the current browser runtime — a freshly restored window gets entirely new ones.

A simplified snapshot model:

type SavedGroup = {
  savedRef: number;
  title: string;
  color: chrome.tabGroups.ColorEnum;
  collapsed: boolean;
};

type SavedTab = {
  id: number;
  url: string;
  index?: number;
  pinned: boolean;
  active?: boolean;
  savedGroupRef?: number;
};

type SavedWindow = {
  windowState: chrome.windows.windowStateEnum;
  groups: SavedGroup[];
  tabs: SavedTab[];
};

savedGroupRef is a pedagogical name — in Tabwell's actual stored schema, the captured numeric group ID serves as the relation between a saved tab and its saved group. The name doesn't matter; the semantics do. That number means something inside the snapshot only. It is never treated as the ID of the future Chrome group.

During restoration, chrome.tabs.group() hands back a brand-new group ID, and that new ID is what goes into chrome.tabGroups.update().

The duplicate Gmail URLs still have separate saved tab IDs.

Why the restore needs two passes

The algorithm that finally held up:

Materialize every saved tab in global order. Tabwell reuses the new window's default blank tab for the first successfully restored item, then creates the remaining tabs.
Record the mapping from saved tab IDs to new Chrome tab IDs.
Build the groups from those new tab IDs.
Apply group metadata.
Restore the intended active tab last.

Pass one: create tabs

Sort the selected tabs by their captured index, falling back to snapshot order. A newly created Chrome window already contains one blank tab, so the production path reuses it for the first successfully restored tab. The helper in this simplified loop hides that bookkeeping and returns either the new runtime tab ID or undefined:

const orderedTabs = [...savedWindow.tabs].sort(compareCapturedOrder);

const newTabIdBySavedTabId = new Map<number, number>();
const failedUrls: string[] = [];

for (const savedTab of orderedTabs) {
  const newTabId = await createRestoredTab(savedTab, windowId);

  if (newTabId === undefined) {
    failedUrls.push(savedTab.url);
    continue;
  }

  newTabIdBySavedTabId.set(savedTab.id, newTabId);
}

The map is keyed by the saved tab ID, not the URL. Key by URL and two saved entries collapse into one mapping entry, so a later step can no longer assign group membership and active state to the correct tab. Two tabs with the same URL are still two distinct browser objects.

Creating everything in global order also dodges a subtler grouping problem: Chrome groups are contiguous. If you restore group A, then group B, then the ungrouped tabs, you have already destroyed any layout where grouped and ungrouped tabs were interleaved. Fixing that afterwards requires a separate tab-moving pass, so it is simpler not to destroy the order in the first place.

Pass two: create groups

Once the tabs exist, each saved group is rebuilt from the tab IDs that were actually created:

let failedGroups = 0;

for (const savedGroup of savedWindow.groups) {
  const newTabIds = orderedTabs
    .filter((tab) => tab.savedGroupRef === savedGroup.savedRef)
    .map((tab) => newTabIdBySavedTabId.get(tab.id))
    .filter((id): id is number => id !== undefined);

  if (newTabIds.length === 0) {
    continue;
  }

  try {
    const newGroupId = await chrome.tabs.group({
      tabIds: newTabIds as [number, ...number[]],
      createProperties: { windowId },
    });

    await chrome.tabGroups.update(newGroupId, {
      title: savedGroup.title,
      color: savedGroup.color,
      collapsed: savedGroup.collapsed,
    });
  } catch {
    failedGroups += 1;
  }
}

After grouping settles, the saved active tab gets reactivated through the saved-ID-to-new-ID map. Grouping can change which tab Chrome leaves active, so the intended tab is activated only after all group operations finish.

Partial restore is a real result

Once a new window exists, restoration stops being an all-or-nothing transaction, whether you like it or not.

A tab can fail when Chrome rejects the create or update call, or when a create call returns no tab ID. A later page-load failure is outside this restore result. A group operation can fail after its tabs already opened. Instead of hiding all that behind one generic exception, the restore path returns structure:

type RestoreResult = {
  windowId: number;
  requested: number;
  restored: number;
  failed: number;
  failedUrls: string[];
  failedGroups?: number;
};

Now the UI can say "9 of 10 tabs restored" and point at the URL that failed.

It also makes a dangerous retry pattern visible. If the caller assumes the whole operation failed and just runs it again, the second attempt duplicates every tab that had already opened. The caller can instead decide whether to keep, remove, or explicitly retry the partial window.

URL handling needs its own boundary, and it isn't one-size-fits-all. For imported third-party session files, a strict http:/https: allowlist is reasonable. For snapshots captured from the user's own browser, Tabwell does not pre-filter chrome: or file: URLs, although Chrome may refuse or rewrite them at restore time. It still rejects dangerous schemes such as javascript:, data:, and vbscript: before any create or update call.

Manifest V3 changes the persistence assumptions

An MV3 service worker is not a permanent process. Anything held only in memory can be gone between two events. Tabwell therefore treats persistence as the save boundary: a save counts as successful only after the snapshot reaches local IndexedDB.

The normal restore flow is not a resumable transaction journal. After partial success, it reports what happened instead of retrying automatically.

Test invariants, not just the happy path

"Three URLs reopened" is not an interesting test. The interesting ones encode the invariants:

grouped and ungrouped tabs interleaved in one window;
two tabs with exactly the same URL;
a pinned ungrouped tab;
the intended active tab restored after grouping;
a separate group whose collapsed state must survive;
groups with different titles and colors;
restoring only one selected group;
one URL rejected while the rest succeed;
a group operation failing after its tabs were created;
an empty selection, or one with no matching tabs, rejected before any window is created.

And the assertions have to inspect the real restored window — tab order, group membership, metadata, pinned state, active tab. Counting opened URLs is precisely the test that passed while my first implementation was scrambling everything.

The three rules I'm keeping

The implementation now follows three constraints:

Runtime IDs can serve as references inside a snapshot, but they are not identities for future runtime objects.
Rebuild global ordering before rebuilding the relationships that can move those objects around.
Once an operation has irreversible partial success, return a structured result — don't flatten it into an exception and a suggestion to blindly retry.

I implemented this restore path in Tabwell.

A question for you: once a manual restore window exists and one tab fails, what would you actually prefer — keep the partial window, roll it back, or build a resumable restore journal? For ordinary manual restore I keep the partial window and report it; automatic crash recovery uses a separate rollback path.

Disclosure: I used AI to help structure an early outline and check the final draft against the implementation. I rewrote the article from my own implementation experience and verified the technical claims against the code.

One Checkbox, Three Kinds of State in a Chrome MV3 Extension

Danila Pryadko — Sat, 08 Aug 2026 23:38:17 +0000

I thought I had a settings bug. What I actually had was three different kinds of state pretending to be one boolean.

While building a Chrome Manifest V3 email-tracker blocker, I expected a simple flow: you flip Gmail on in the settings, and the extension starts working in Gmail. That was the theory, anyway.

The problem showed up when I was testing on a second Chrome profile. I'd enabled Gmail on my main profile, and Chrome Sync helpfully carried that preference over to the other one. But the optional permission for mail.google.com didn't come along — host grants live in the local profile and never sync. Profile number two now believed Gmail was enabled while lacking the host grant needed to inject the inbox content script or inspect its DOM. Depending on how you write your code, that's either a silent no-op or an extension quietly behaving as if access exists when it does not. Neither is great.

Once I stopped and wrote it down, the picture got clearer. There are three separate things here: the inbox the user wants enabled, the host access Chrome has actually granted in this profile, and the dynamic DNR rules that are currently installed. Collapsing them into one flag is convenient. It's also wrong.

The manifest is a menu, not an order

The extension declares each webmail origin under optional_host_permissions. Every inbox gets activated on its own, and Chrome only asks the user for access when they turn that particular integration on.

Here's the thing I had to internalize: declaring an optional origin means nothing by itself. Until the live grant exists, the extension has no business registering a content script for that inbox, poking at its DOM, or — by its own scoping policy — activating client-scoped blocking rules for it.

Why bother with per-inbox prompts at all? Mostly trust. A tracker blocker that asks for all your webmail up front looks exactly like the thing it's supposed to protect you from. Asking for Gmail when you enable Gmail — and nothing more — is an easy story to tell users, and it doesn't hurt during store review either. Chrome's docs recommend optional permissions for exactly this kind of informed control. The docs don't mention the hard part, though: making the runtime actually preserve that choice through permission revocations, browser sync, and service worker restarts. That's on you.

Packaged rules as templates

The extension ships two packaged DNR rulesets, and both stay disabled. The background service worker loads the high-confidence pixel rules from rules/pixels.json as a read-only template and clones only those into extension-owned, client-scoped dynamic rules. Recognized tracking links are handled by the content script rather than navigation DNR.

The scope I want is, conceptually:

clients enabled in settings  AND  hosts granted in this profile

Before generating anything, the extension asks chrome.permissions.contains() about the origin. A synced setting is intent. It is not evidence of a current host grant, so the extension does not activate that client.

The generated blocking rules list only the enabled-and-granted webmail origins in initiatorDomains. If Gmail is the only authorized inbox, a request elsewhere on the web doesn't get blocked just because it happens to match a tracker pattern. The same transformation also emits higher-priority allow rules for tracker domains the user has explicitly whitelisted.

Rebuild everything, don't patch

My first instinct was incremental: checkbox on, add rules; checkbox off, remove them. It works right up until reality intervenes. A permission gets revoked from Chrome's own extension settings page. Settings arrive via sync. The service worker dies between two state changes. Several permission and settings events land on top of each other. An update leaves stale dynamic rules behind from the previous version. I hit most of these within a week of testing.

So the extension doesn't track transitions anymore. On every relevant event it rebuilds the entire desired rule set from current state: disable the packaged static rulesets, read the extension-owned dynamic rules, check the current optional host grants, treat anything ungranted as disabled, build the full desired set of block and allow rules, compare normalized fingerprints, and replace the owned rules only if something actually changed.

Run it twice with the same inputs and you get the same rules and no write. That idempotence is what makes the whole thing debuggable. Reserved rule-ID ranges keep this component from stepping on rules it doesn't own.

Failing closed

When something goes wrong, the extension errs toward doing less.

If the permissions API is unavailable, every client is treated as inactive. If an individual permission check throws, that client is treated as inactive. If the packaged template can't be loaded while old extension-owned rules are still installed, those rules get removed before the error is reported.

Yes, that can temporarily reduce protection. I went back and forth on this while testing — an argument can be made for keeping the last known-good rules around. But keeping behavior alive outside the scope the user explicitly granted felt worse than a gap. A tracker blocker that blocks things beyond that scope is a different kind of broken, and a scarier one.

One reconciliation at a time

Settings and permissions can change nearly simultaneously. A user enables an inbox, answers the Chrome prompt, edits the allow list, then disables the inbox again — all inside a few seconds. If each event kicks off its own independent reconciliation, an older snapshot can finish after a newer one and win.

So reconciliations go through a queue. Each snapshot waits for the previous operation to settle. A failed operation doesn't poison the queue or stop later state from applying.

Small detail. But in an MV3 service worker — event-driven, no permanent process — it's the difference between "eventually correct" and "correct until you click fast."

"Detected" is not "blocked"

One more boundary worth writing down: production extensions don't get a tidy callback for every DNR match. The inbox UI detects tracker resources present in the message DOM, while DNR separately blocks matching image and ping requests. Two different signals, two different mechanisms.

So a detection shown in the UI must not be described as proof that a specific network request was blocked. The product copy and reports keep "detected" and "blocked" as separate words on purpose.

Where the data lives

Detection history and sender statistics sit in local IndexedDB. Attribution uses sender metadata, opaque identifiers from the webmail provider, and the relevant image or link URLs. Subject and body text aren't extracted, stored, or transmitted — with one honest asterisk: on Outlook, Superhuman, and Yahoo, the locally parsed accessibility label that carries the sender can also contain a subject line. I'd rather document that than pretend the wording is simpler than it is.

Preferences may sync through Chrome; host grants stay local, as established. Paid operations and opt-in crash reporting are separate network paths, not part of inbox detection.

Proton Mail deserves its own caveat too. Its image proxy is on by default, so browser-level DNR pixel blocking is constrained there. Sender attribution and tracking-link protection can still work, but I don't claim identical pixel coverage across clients.

The tests that earned their keep

The useful test matrix turned out to be all about state transitions: a fresh install produces no client-scoped rules; enabling Gmail creates rules only once its host grant exists; a synced Gmail preference without the local grant creates nothing; revoking a grant removes that client's initiator domain; disabling one client leaves the others intact; an allow-listed tracker domain gets its higher-priority allow rule; a failed permission check disables the affected client; a template-loading failure clears stale owned rules; repeated reconciliation with unchanged state performs no update; and rapid snapshots apply in order.

That last one surprised me most. Before the queue existed, I could reliably make the older state win just by toggling a checkbox twice quickly — the first reconciliation, carrying stale state, finished second and overwrote the fresh one. Watching a disabled inbox come back to life because I clicked fast was the moment the queue stopped being optional.

The lesson I keep coming back to: product settings, browser authority, and runtime rules are different kinds of state. Once I stopped mashing them into one flag, the permission model became something I could explain, test, and audit without hand-waving.

How do other extension teams handle this? Do you rebuild the full desired dynamic-rule set from scratch, or apply incremental mutations across permission and settings events? I'd like to hear where incremental has actually held up.

Implementation references:

Disclosure: I used AI to help structure an early research outline. I rewrote this article from my own implementation experience and verified the technical claims against the implementation and Chrome's documentation.