Options Storage

The Options Storage system in Ghostbird provides a mechanism for users to configure the add-on's behavior and for these settings to be persisted. It leverages standard WebExtension APIs, specifically browser.storage.local, to save and retrieve configuration data. The user interacts with these settings through a dedicated options page.

The core of this functionality relies on the webext-options-sync library, which simplifies the process of synchronizing settings between the options UI and the browser's storage. The background script then loads these stored options to modify its behavior, such as connecting to the correct GhostText server port.

Sources: doc/design.md, package.json:71, manifest_template.json:19

Architecture

The options storage architecture is composed of several key parts: the options UI page, the script that handles logic on that page, the background script that consumes the settings, and the underlying browser storage API.

• Manifest (manifest_template.json): Defines the entry point for the options UI (options.html) and requests the necessary storage permission to use the browser.storage.local API.
• Options UI (options.html): The HTML page that presents the configuration form to the user. It is styled by options.css.
• Options Script (options.js): A script bundled from src/root/options.ts that runs on the options page. It is responsible for loading current settings into the form and saving any changes back to browser.storage.local.
• Background Script (background.js): Reads the saved settings from storage when the add-on starts or when a new GhostText session is initiated.
• webext-options-sync Library: A third-party dependency that abstracts the interaction with browser.storage.local, providing a simpler API for getting and setting options.

Sources: doc/design.md:65-71, manifest_template.json:19, 44-46, package.json:71, tools/tsdown_config.ts:90-93

Component Interaction

The following diagram illustrates how the different components of the options system interact.

This diagram shows the flow of data from the user interface, through the options script and webext-options-sync library, to the persistent browser.storage.local API. The background script also reads from this storage to apply the settings.

Sources: doc/design.md:65-71, package.json:71

Configuration Options

The add-on exposes several settings to the user via the options page.

The labels for these options are defined in the stylesheet and populated with localized strings.

/* Source: ext/options.css:47-53 */
label {
  &[for="serverPort"]::before {
    content: "__MSG_options_server_port__";
  }
  &[for="enableNotifications"]::before {
    content: "__MSG_options_enable_notifications__";
  }
}

Sources: ext/options.css:47-53, doc/design.md:30

Data Flow

The process of saving and loading options follows a clear sequence, as described in the project's design documentation.

Saving and Loading Options

This sequence diagram shows the user saving a new setting and the background script subsequently loading it.

This flow ensures that any configuration changes made by the user are immediately persisted and are available to the background script the next time they are needed.

Sources: doc/design.md:65-71

Manifest Configuration

The functionality of the options page is declared in manifest_template.json. It specifies the HTML file for the UI and requests the necessary permissions.

/* Source: manifest_template.json:18-24, 43-46 */
  "permissions": [
    "alarms",
    "compose",
    "notifications",
    "menus",
    "scripting",
    "storage"
  ],
...
  "options_ui": {
    "page": "options.html"
  },

• permissions: The "storage" permission is essential for allowing the add-on to use the browser.storage.local API.
• options_ui: The page property points to options.html, which Thunderbird will open when the user accesses the add-on's settings.

Sources: manifest_template.json:18-24, 43-46