Changelog

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• package.json
• src/background.ts
• src/content-script.ts
• src/window.ts
• src/internal/persistent-port.ts
• src/internal/endpoint-runtime.ts
• src/internal/endpoint.ts
• src/devtools.ts
• src/options.ts

This document provides a detailed technical breakdown of the significant changes introduced in webext-bridge, focusing on major versions. It aims to explain the architectural shifts, API modifications, and bug fixes by referencing the source code. The primary focus is on version 6.0.0, which introduced substantial codebase improvements and breaking changes for end-users.

Sources: CHANGELOG.md

v6.0.0

Version 6.0.0 was a major revision focused on improving codebase readability, splitting responsibilities into smaller modules, and adapting to Manifest V3 constraints. While the core API behavior remains similar, the way developers interact with the library has changed significantly.

Sources: CHANGELOG.md:3-7

Breaking Change: Explicit Runtime Context Imports

Previously, webext-bridge would attempt to automatically detect the runtime context (e.g., background, content-script). In v6.0.0, this is no longer the case. Developers must explicitly import the bridge from the entry point corresponding to the script's context. This change makes the library's behavior more predictable and the code easier to understand.

The new import structure is defined in package.json through the exports and typesVersions fields, which map specific import paths to their corresponding compiled files.

Sources: CHANGELOG.md:10-12, package.json:28-53

The following diagram illustrates the new import model for different extension contexts.

This diagram shows how different import paths from the webext-bridge package resolve to specific entry points for each runtime context.

Sources: package.json:28-53

Breaking Change: Context-Specific APIs

With the move to explicit context imports, certain APIs are now only available in the contexts where they are relevant.

Function	Available Context(s)	Source File
allowWindowMessaging(namespace)	content-script	src/content-script.ts:30-33
setNamespace(namespace)	window	src/window.ts:15-18

• allowWindowMessaging: This function is used in a content script to establish a postMessage communication channel with scripts running in the main window context. It is exclusively available in the content-script entry point.
• setNamespace: This function is used by a script in the window context to connect to the bridge established by the content script. It is exclusively available in the window entry point.

The getCurrentContext export has been removed entirely as part of this refactoring.

Sources: CHANGELOG.md:13-14, src/content-script.ts:30-33, src/window.ts:15-18

Breaking Change: Manifest V3 Background Script Message Queuing

Due to the ephemeral nature of service workers in Manifest V3, the reliability of message queuing for messages sent from the background script has been reduced. If the background service worker sends a message and is terminated by the browser before the message can be delivered (e.g., the target tab/context is not yet ready), the message will be lost. The queue is disposed of when the service worker terminates.

However, queuing for messages sent from other contexts to the background still works. The createPersistentPort utility, used by non-background contexts, maintains an undeliveredQueue and attempts to re-sync and re-send messages when the connection to the background script is re-established.

Sources: CHANGELOG.md:18-21, src/internal/persistent-port.ts:21, 41-54

Fix: Message Delivery Reliability After Tab Navigation

A race condition was fixed where messages sent to a content-script or window immediately after a tab navigation (forward or back) could be dropped. The issue occurred because the old content script's port onDisconnect event could fire after the new content script's onConnect event, causing the new port mapping to be incorrectly removed from the background script's connection map (connMap).

The fix involves associating a unique fingerprint with each connection. When onDisconnect is called, the background script now checks if the fingerprint of the disconnecting port matches the currently registered fingerprint for that endpoint. If they don't match (meaning a new port has already connected), the connection map is not cleared, preserving the new connection.

Sources: CHANGELOG.md:23-26, src/background.ts:208-212

The following sequence diagram illustrates how the fingerprint check prevents the race condition.

This diagram shows the background script correctly ignoring the disconnect event from the old content script because the connection fingerprint has been updated.

Sources: src/background.ts:208-212

Fix: Sender Notification on Recipient Termination

If a message recipient terminates (e.g., a tab is closed) before it can reply to a sender, the sendMessage promise will now reject with an error instead of hanging indefinitely.

This is handled in the background script. When a port disconnects, a cleanup process is triggered. It identifies any pending messages (rogueMsgs) that were expecting a reply from the terminated context (identified by its fingerprint). For each of these messages, it notifies the original sender that the session has ended.

• If the sender is another extension context (e.g., popup), a terminated status message is sent back to it via PortMessage.
• If the sender was the background script itself, the corresponding transaction is rejected locally via endpointRuntime.endTransaction.

Sources: CHANGELOG.md:27-29, src/background.ts:196-207, src/internal/persistent-port.ts:90-97

This flow ensures that senders are promptly made aware of delivery failures due to recipient termination.

This diagram shows how the background script detects a port disconnection and notifies the original sender that the recipient has terminated.

Sources: src/background.ts:196-207, src/internal/persistent-port.ts:90-97