tor-browser

CustomizableUI.sys.mjs (295143B)

---

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";
import { AppConstants } from "resource://gre/modules/AppConstants.sys.mjs";
import { SearchWidgetTracker } from "moz-src:///browser/components/customizableui/SearchWidgetTracker.sys.mjs";

const lazy = {};

ChromeUtils.defineESModuleGetters(lazy, {
 AddonManager: "resource://gre/modules/AddonManager.sys.mjs",
 AddonManagerPrivate: "resource://gre/modules/AddonManager.sys.mjs",
 BrowserUsageTelemetry: "resource:///modules/BrowserUsageTelemetry.sys.mjs",
 CustomizableWidgets:
   "moz-src:///browser/components/customizableui/CustomizableWidgets.sys.mjs",
 HomePage: "resource:///modules/HomePage.sys.mjs",
 PanelMultiView:
   "moz-src:///browser/components/customizableui/PanelMultiView.sys.mjs",
 PrivateBrowsingUtils: "resource://gre/modules/PrivateBrowsingUtils.sys.mjs",
 ShortcutUtils: "resource://gre/modules/ShortcutUtils.sys.mjs",
});

ChromeUtils.defineLazyGetter(lazy, "gWidgetsBundle", function () {
 const kUrl =
   "chrome://browser/locale/customizableui/customizableWidgets.properties";
 return Services.strings.createBundle(kUrl);
});

const kDefaultThemeID = "default-theme@mozilla.org";

const kSpecialWidgetPfx = "customizableui-special-";

const kPrefCustomizationState = "browser.uiCustomization.state";
const kPrefCustomizationHorizontalTabstrip =
 "browser.uiCustomization.horizontalTabstrip";
const kPrefCustomizationHorizontalTabsBackup =
 "browser.uiCustomization.horizontalTabsBackup";
const kPrefCustomizationNavBarWhenVerticalTabs =
 "browser.uiCustomization.navBarWhenVerticalTabs";
const kPrefCustomizationAutoAdd = "browser.uiCustomization.autoAdd";
const kPrefCustomizationDebug = "browser.uiCustomization.debug";
const kPrefDrawInTitlebar = "browser.tabs.inTitlebar";
const kPrefUIDensity = "browser.uidensity";
const kPrefAutoTouchMode = "browser.touchmode.auto";
const kPrefAutoHideDownloadsButton = "browser.download.autohideButton";
const kPrefProtonToolbarVersion = "browser.proton.toolbar.version";
const kPrefHomeButtonUsed = "browser.engagement.home-button.has-used";
const kPrefLibraryButtonUsed = "browser.engagement.library-button.has-used";
const kPrefSidebarButtonUsed = "browser.engagement.sidebar-button.has-used";
const kPrefSidebarRevampEnabled = "sidebar.revamp";
const kPrefSidebarVerticalTabsEnabled = "sidebar.verticalTabs";
const kPrefSidebarPositionStartEnabled = "sidebar.position_start";

const kExpectedWindowURL = AppConstants.BROWSER_CHROME_URL;

var gDefaultTheme;
var gSelectedTheme;

/**
* The keys are the handlers that are fired when the event type (the value)
* is fired on the subview. A widget that provides a subview has the option
* of providing onViewShowing and onViewHiding event handlers.
*/
const kSubviewEvents = ["ViewShowing", "ViewHiding"];

/**
* The current version. We can use this to auto-add new default widgets as necessary.
* (would be const but isn't because of testing purposes)
*/
var kVersion = 23;

/**
* The current version for base browser.
*/
var kVersionBaseBrowser = 2;
const NoScriptId = "_73a6fe31-595d-460b-a920-fcc0f8843232_-browser-action";

/**
* The current version for tor browser.
*/
var kVersionTorBrowser = 1;

/**
* Buttons removed from built-ins by version they were removed. kVersion must be
* bumped any time a new id is added to this. Use the button id as key, and
* version the button is removed in as the value.  e.g. "pocket-button": 5
*/
var ObsoleteBuiltinButtons = {
 "feed-button": 15,
};

/**
* gPalette is a map of every widget that CustomizableUI.sys.mjs knows about, keyed
* on their IDs.
*/
var gPalette = new Map();

/**
* gAreas maps area IDs to Sets of properties about those areas. An area is a
* place where a widget can be put.
*/
var gAreas = new Map();

/**
* gPlacements maps area IDs to Arrays of widget IDs, indicating that the widgets
* are placed within that area (either directly in the area node, or in the
* customizationTarget of the node).
*/
var gPlacements = new Map();

/**
* gFuturePlacements represent placements that will happen for areas that have
* not yet loaded (due to lazy-loading). This can occur when add-ons register
* widgets.
*/
var gFuturePlacements = new Map();

var gSupportedWidgetTypes = new Set([
 // A button that does a command.
 "button",

 // A button that opens a view in a panel (or in a subview of the panel).
 "view",

 // A combination of the above, which looks different depending on whether it's
 // located in the toolbar or in the panel: When located in the toolbar, shown
 // as a combined item of a button and a dropmarker button. The button triggers
 // the command and the dropmarker button opens the view. When located in the
 // panel, shown as one item which opens the view, and the button command
 // cannot be triggered separately.
 "button-and-view",

 // A custom widget that defines its own markup.
 "custom",
]);

/**
* gPanelsForWindow is a list of known panels in a window which we may need to close
* should command events fire which target them.
*
* @type {WeakMap<Element, Set<Element>>}
*/
var gPanelsForWindow = new WeakMap();

/**
* gSeenWidgets remembers which widgets the user has seen for the first time
* before. This way, if a new widget is created, and the user has not seen it
* before, it can be put in its default location. Otherwise, it remains in the
* palette.
*/
var gSeenWidgets = new Set();

/**
* gDirtyAreaCache is a set of area IDs for areas where items have been added,
* moved or removed at least once. This set is persisted, and is used to
* optimize building of toolbars in the default case where no toolbars should
* be "dirty".
*/
var gDirtyAreaCache = new Set();

/**
* gPendingBuildAreas is a map from area IDs to map from build nodes to their
* existing children at the time of node registration, that are waiting
* for the area to be registered
*/
var gPendingBuildAreas = new Map();

var gSavedState = null;
var gRestoring = false;
var gDirty = false;
var gInBatchStack = 0;
var gResetting = false;
var gUndoResetting = false;

/**
* gBuildAreas maps area IDs to actual area nodes within browser windows.
*/
var gBuildAreas = new Map();

/**
* gBuildWindows is a map of windows that have registered build areas, mapped
* to a Set of known toolboxes in that window.
*/
var gBuildWindows = new Map();

var gNewElementCount = 0;
var gGroupWrapperCache = new Map();
var gSingleWrapperCache = new WeakMap();
var gListeners = new Set();

var gUIStateBeforeReset = {
 uiCustomizationState: null,
 drawInTitlebar: null,
 currentTheme: null,
 uiDensity: null,
 autoTouchMode: null,
 sidebarPositionStart: null,
};

/*
* The current tab orientation: initially null until initialization,
* true for vertical, false for horizontal
*/
var gCurrentVerticalTabs = null;

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "gDebuggingEnabled",
 kPrefCustomizationDebug,
 false,
 (pref, oldVal, newVal) => {
   if (typeof lazy.log != "undefined") {
     lazy.log.maxLogLevel = newVal ? "all" : "log";
   }
 }
);

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "resetPBMToolbarButtonEnabled",
 "browser.privatebrowsing.resetPBM.enabled",
 false
);

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "sidebarRevampEnabled",
 "sidebar.revamp",
 false,
 (pref, oldVal, newVal) => {
   if (!newVal) {
     return;
   }
   let navbarPlacements = CustomizableUI.getWidgetIdsInArea(
     CustomizableUI.AREA_NAVBAR
   );
   if (!navbarPlacements.includes("sidebar-button")) {
     CustomizableUI.addWidgetToArea(
       "sidebar-button",
       CustomizableUI.AREA_NAVBAR,
       Services.prefs.getBoolPref(kPrefSidebarPositionStartEnabled, true)
         ? 0
         : undefined // Adds to the end of navbar if position_start is false.
     );
   }
   // Ensure CUI knows to not restore this button if the user later removes it
   let prefId = "browser.toolbarbuttons.introduced.sidebar-button";
   Services.prefs.setBoolPref(prefId, true);
 }
);

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "verticalTabsPref",
 "sidebar.verticalTabs",
 false,
 (pref, oldVal, newVal) => {
   lazy.log.debug(
     `sidebar.verticalTabs change handler, calling updateTabStripOrientation with value: ${newVal}, gCurrentVerticalTabs: ${gCurrentVerticalTabs}`
   );
   CustomizableUIInternal.updateTabStripOrientation();
 }
);

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "horizontalPlacementsPref",
 kPrefCustomizationHorizontalTabstrip,
 ""
);

XPCOMUtils.defineLazyPreferenceGetter(
 lazy,
 "verticalPlacementsPref",
 kPrefCustomizationNavBarWhenVerticalTabs,
 ""
);

ChromeUtils.defineLazyGetter(lazy, "log", () => {
 let { ConsoleAPI } = ChromeUtils.importESModule(
   "resource://gre/modules/Console.sys.mjs"
 );
 let consoleOptions = {
   maxLogLevel: lazy.gDebuggingEnabled ? "all" : "log",
   prefix: "CustomizableUI",
 };
 return new ConsoleAPI(consoleOptions);
});

/**
* This is the internal, private implementation of most of the CustomizableUI
* API. This is intentionally not exported, but is instead called directly
* from within this module via the exported CustomizableUI object, which
* allows us to get a type of encapsulation.
*/
var CustomizableUIInternal = {
 /**
  * Main entrypoint to initializing the CustomizableUI singleton. This is
  * called once the very first time this module is evaluated anywhere, via a
  * a call at the very end of this module file.
  *
  * This sets up observers, registers built-in widgets, and loads the saved
  * customization state from preferences, and performs any migration on that
  * loaded state.
  */
 initialize() {
   lazy.log.debug("Initializing");

   lazy.AddonManagerPrivate.databaseReady.then(async () => {
     lazy.AddonManager.addAddonListener(this);

     let addons = await lazy.AddonManager.getAddonsByTypes(["theme"]);
     gDefaultTheme = addons.find(addon => addon.id == kDefaultThemeID);
     gSelectedTheme = addons.find(addon => addon.isActive) || gDefaultTheme;
   });

   this.addListener(this);
   this.defineBuiltInWidgets();
   this.loadSavedState();
   this.updateForNewVersion();
   this.updateForNewProtonVersion();
   this.markObsoleteBuiltinButtonsSeen();
   this.updateForBaseBrowser();
   this.updateForTorBrowser();

   this.registerArea(
     CustomizableUI.AREA_FIXED_OVERFLOW_PANEL,
     {
       type: CustomizableUI.TYPE_PANEL,
       defaultPlacements: [],
       anchor: "nav-bar-overflow-button",
     },
     true
   );

   this.registerArea(
     CustomizableUI.AREA_ADDONS,
     {
       type: CustomizableUI.TYPE_PANEL,
       defaultPlacements: [],
       anchor: "unified-extensions-button",
     },
     false
   );

   let navbarPlacements = [
     lazy.sidebarRevampEnabled ? "sidebar-button" : null,
     "back-button",
     "forward-button",
     "stop-reload-button",
     Services.policies.isAllowed("removeHomeButtonByDefault")
       ? null
       : "home-button",
     "vertical-spacer",
     "urlbar-container",
     // Don't want springs either side of the urlbar. tor-browser#41736
     // Base-browser additions tor-browser#41736. If you want to add to, remove
     // from, or rearrange this list, then bump the kVersionBaseBrowser and
     // update existing saved states in _updateForBaseBrowser.
     // Or if the change is only meant for tor-browser, bump kVersionTorBrowser
     // instead and update the existing saved states in _updateForTorBrowser.
     "security-level-button",
     "new-identity-button",
     "downloads-button",
     AppConstants.MOZ_DEV_EDITION ? "developer-button" : null,
     "fxa-toolbar-menu-button",
     lazy.resetPBMToolbarButtonEnabled ? "reset-pbm-toolbar-button" : null,
   ].filter(name => name);

   this.registerArea(
     CustomizableUI.AREA_NAVBAR,
     {
       type: CustomizableUI.TYPE_TOOLBAR,
       overflowable: true,
       defaultPlacements: navbarPlacements,
       verticalTabsDefaultPlacements: [
         "firefox-view-button",
         "alltabs-button",
       ],
       defaultCollapsed: false,
     },
     true
   );
   // navbarPlacements does not match the initial default XHTML layout.
   // Therefore we always need to rebuild the navbar area when
   // registerToolbarNode is called. tor-browser#41736
   gDirtyAreaCache.add(CustomizableUI.AREA_NAVBAR);

   if (!Services.appinfo.nativeMenubar) {
     this.registerArea(
       CustomizableUI.AREA_MENUBAR,
       {
         type: CustomizableUI.TYPE_TOOLBAR,
         defaultPlacements: ["menubar-items"],
         defaultCollapsed: true,
       },
       true
     );
   }

   this.registerArea(
     CustomizableUI.AREA_TABSTRIP,
     {
       type: CustomizableUI.TYPE_TOOLBAR,
       defaultPlacements: [
         "firefox-view-button",
         "tabbrowser-tabs",
         "new-tab-button",
         "alltabs-button",
       ],
       verticalTabsDefaultPlacements: [],
       defaultCollapsed: null,
     },
     true
   );

   this.registerArea(
     CustomizableUI.AREA_VERTICAL_TABSTRIP,
     {
       type: "toolbar",
       defaultPlacements: [],
       verticalTabsDefaultPlacements: ["tabbrowser-tabs"],
       defaultCollapsed: null,
     },
     true
   );

   this.registerArea(
     CustomizableUI.AREA_BOOKMARKS,
     {
       type: CustomizableUI.TYPE_TOOLBAR,
       defaultPlacements: ["personal-bookmarks"],
       defaultCollapsed: "newtab",
     },
     true
   );
   lazy.log.debug(`All the areas registered: ${[...gAreas.keys()]}`);

   // At initialization, if we find vertical tabs enabled but not sidebar.revamp
   // we'll enable revamp rather than disable vertical tabs.
   this.reconcileSidebarPrefs(kPrefSidebarVerticalTabsEnabled);

   this.initializeForTabsOrientation(CustomizableUI.verticalTabsEnabled);

   SearchWidgetTracker.init();

   Services.obs.addObserver(this, "browser-set-toolbar-visibility");

   Services.prefs.addObserver(kPrefSidebarVerticalTabsEnabled, this);
   Services.prefs.addObserver(kPrefSidebarRevampEnabled, this);
   Services.prefs.addObserver(kPrefSidebarPositionStartEnabled, this);
 },

 /**
  * Implements the onEnabled method for the AddonListener interface. Called
  * when an add-on is marked as enabled.
  *
  * @param {AddonInternal} addon
  *   The add-on that was enabled.
  */
 onEnabled(addon) {
   if (addon.type == "theme") {
     gSelectedTheme = addon;
   }
 },

 /**
  * Returns a new Set that contains the IDs of all built-in customizable areas.
  *
  * @type {Set<string>}
  */
 get builtinAreas() {
   return new Set([
     ...this.builtinToolbars,
     CustomizableUI.AREA_FIXED_OVERFLOW_PANEL,
     CustomizableUI.AREA_ADDONS,
   ]);
 },

 /**
  * Returns a new Set that contains the IDs of all built-in customizable
  * toolbar areas.
  *
  * @type {Set<string>}
  */
 get builtinToolbars() {
   let toolbars = new Set([
     CustomizableUI.AREA_NAVBAR,
     CustomizableUI.AREA_BOOKMARKS,
     CustomizableUI.AREA_TABSTRIP,
   ]);
   if (AppConstants.platform != "macosx") {
     toolbars.add(CustomizableUI.AREA_MENUBAR);
   }
   return toolbars;
 },

 /**
  * Goes through the list of widgets defined in CustomizableWidgets and
  * registers them with CustomizableUI.
  */
 defineBuiltInWidgets() {
   for (let widgetDefinition of lazy.CustomizableWidgets) {
     this.createBuiltinWidget(widgetDefinition);
   }
 },

 /**
  * Runs any necessary migrations on the current saved customization state
  * to get us to a kVersion compatible state.
  */
 // eslint-disable-next-line complexity
 updateForNewVersion() {
   // We should still enter even if gSavedState.currentVersion >= kVersion
   // because the per-widget pref facility is independent of versioning.
   if (!gSavedState) {
     // Flip all the prefs so we don't try to re-introduce later:
     for (let [, widget] of gPalette) {
       if (widget.defaultArea && widget._introducedInVersion === "pref") {
         let prefId = "browser.toolbarbuttons.introduced." + widget.id;
         Services.prefs.setBoolPref(prefId, true);
       }
     }
     return;
   }

   let currentVersion = gSavedState.currentVersion;
   for (let [id, widget] of gPalette) {
     if (widget.defaultArea) {
       let shouldAdd = false;
       let shouldSetPref = false;
       let prefId = "browser.toolbarbuttons.introduced." + widget.id;
       if (widget._introducedInVersion === "pref") {
         try {
           shouldAdd = !Services.prefs.getBoolPref(prefId);
         } catch (ex) {
           // Pref doesn't exist:
           shouldAdd = true;
         }
         shouldSetPref = shouldAdd;
       } else if (widget._introducedInVersion > currentVersion) {
         shouldAdd = true;
       } else if (
         widget._introducedByPref &&
         Services.prefs.getBoolPref(widget._introducedByPref)
       ) {
         shouldSetPref = shouldAdd = !Services.prefs.getBoolPref(
           prefId,
           false
         );
       }

       if (shouldAdd) {
         let futurePlacements = gFuturePlacements.get(widget.defaultArea);
         if (futurePlacements) {
           futurePlacements.add(id);
         } else {
           gFuturePlacements.set(widget.defaultArea, new Set([id]));
         }
         if (shouldSetPref) {
           Services.prefs.setBoolPref(prefId, true);
         }
       }
     }
   }

   // Nothing to migrate now if we don't have placements.
   if (!gSavedState.placements) {
     return;
   }

   if (
     currentVersion < 7 &&
     gSavedState.placements[CustomizableUI.AREA_NAVBAR]
   ) {
     let placements = gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     let newPlacements = [
       "back-button",
       "forward-button",
       "stop-reload-button",
       "home-button",
     ];
     for (let button of placements) {
       if (!newPlacements.includes(button)) {
         newPlacements.push(button);
       }
     }

     if (!newPlacements.includes("sidebar-button")) {
       newPlacements.unshift("sidebar-button");
     }

     gSavedState.placements[CustomizableUI.AREA_NAVBAR] = newPlacements;
   }

   if (currentVersion < 8 && gSavedState.placements["PanelUI-contents"]) {
     let savedPanelPlacements = gSavedState.placements["PanelUI-contents"];
     delete gSavedState.placements["PanelUI-contents"];
     let defaultPlacements = [
       "edit-controls",
       "zoom-controls",
       "new-window-button",
       "privatebrowsing-button",
       "save-page-button",
       "print-button",
       "history-panelmenu",
       "fullscreen-button",
       "find-button",
       "preferences-button",
       // This widget no longer exists as of 2023, see Bug 1799009.
       "add-ons-button",
       "sync-button",
     ];

     if (!AppConstants.MOZ_DEV_EDITION) {
       defaultPlacements.splice(-1, 0, "developer-button");
     }

     savedPanelPlacements = savedPanelPlacements.filter(
       id => !defaultPlacements.includes(id)
     );

     if (savedPanelPlacements.length) {
       gSavedState.placements[CustomizableUI.AREA_FIXED_OVERFLOW_PANEL] =
         savedPanelPlacements;
     }
   }

   if (currentVersion < 9 && gSavedState.placements["nav-bar"]) {
     let placements = gSavedState.placements["nav-bar"];
     if (placements.includes("urlbar-container")) {
       let urlbarIndex = placements.indexOf("urlbar-container");
       let secondSpringIndex = urlbarIndex + 1;
       // Insert if there isn't already a spring before the urlbar
       if (
         urlbarIndex == 0 ||
         !placements[urlbarIndex - 1].startsWith(kSpecialWidgetPfx + "spring")
       ) {
         placements.splice(urlbarIndex, 0, "spring");
         // The url bar is now 1 index later, so increment the insertion point for
         // the second spring.
         secondSpringIndex++;
       }
       // If the search container is present, insert after the search container
       // instead of after the url bar
       let searchContainerIndex = placements.indexOf("search-container");
       if (searchContainerIndex != -1) {
         secondSpringIndex = searchContainerIndex + 1;
       }
       if (
         secondSpringIndex == placements.length ||
         !placements[secondSpringIndex].startsWith(
           kSpecialWidgetPfx + "spring"
         )
       ) {
         placements.splice(secondSpringIndex, 0, "spring");
       }
     }

     // Finally, replace the bookmarks menu button with the library one if present
     if (placements.includes("bookmarks-menu-button")) {
       let bmbIndex = placements.indexOf("bookmarks-menu-button");
       placements.splice(bmbIndex, 1);
       let downloadButtonIndex = placements.indexOf("downloads-button");
       let libraryIndex =
         downloadButtonIndex == -1 ? bmbIndex : downloadButtonIndex + 1;
       placements.splice(libraryIndex, 0, "library-button");
     }
   }

   if (currentVersion < 10) {
     for (let placements of Object.values(gSavedState.placements)) {
       if (placements.includes("webcompat-reporter-button")) {
         placements.splice(placements.indexOf("webcompat-reporter-button"), 1);
         break;
       }
     }
   }

   // Move the downloads button to the default position in the navbar if it's
   // not there already.
   if (currentVersion < 11) {
     let navbarPlacements = gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     // First remove from wherever it currently lives, if anywhere:
     for (let placements of Object.values(gSavedState.placements)) {
       let existingIndex = placements.indexOf("downloads-button");
       if (existingIndex != -1) {
         placements.splice(existingIndex, 1);
         break; // It can only be in 1 place, so no point looking elsewhere.
       }
     }

     // Now put the button in the navbar in the correct spot:
     if (navbarPlacements) {
       let insertionPoint = navbarPlacements.indexOf("urlbar-container");
       // Deliberately iterate to 1 past the end of the array to insert at the
       // end if need be.
       while (++insertionPoint < navbarPlacements.length) {
         let widget = navbarPlacements[insertionPoint];
         // If we find a non-searchbar, non-spacer node, break out of the loop:
         if (
           widget != "search-container" &&
           !this.matchingSpecials(widget, "spring")
         ) {
           break;
         }
       }
       // We either found the right spot, or reached the end of the
       // placements, so insert here:
       navbarPlacements.splice(insertionPoint, 0, "downloads-button");
     }
   }

   if (currentVersion < 12) {
     const removedButtons = [
       "loop-call-button",
       "loop-button-throttled",
       "pocket-button",
     ];
     for (let placements of Object.values(gSavedState.placements)) {
       for (let button of removedButtons) {
         let buttonIndex = placements.indexOf(button);
         if (buttonIndex != -1) {
           placements.splice(buttonIndex, 1);
         }
       }
     }
   }

   // Remove the old placements from the now-gone Nightly-only
   // "New non-e10s window" button.
   if (currentVersion < 13) {
     for (let placements of Object.values(gSavedState.placements)) {
       let buttonIndex = placements.indexOf("e10s-button");
       if (buttonIndex != -1) {
         placements.splice(buttonIndex, 1);
       }
     }
   }

   // Remove unsupported custom toolbar saved placements
   if (currentVersion < 14) {
     for (let area in gSavedState.placements) {
       if (!this.builtinAreas.has(area)) {
         delete gSavedState.placements[area];
       }
     }
   }

   // Add the FxA toolbar menu as the right most button item
   if (currentVersion < 16) {
     let navbarPlacements = gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     // Place the menu item as the first item to the left of the hamburger menu
     if (navbarPlacements) {
       navbarPlacements.push("fxa-toolbar-menu-button");
     }
   }

   // Add firefox-view if not present
   if (currentVersion < 18) {
     let tabstripPlacements =
       gSavedState.placements[CustomizableUI.AREA_TABSTRIP];
     if (
       tabstripPlacements &&
       !tabstripPlacements.includes("firefox-view-button")
     ) {
       tabstripPlacements.unshift("firefox-view-button");
     }
   }

   // Unified Extensions addon button migration, which puts any browser action
   // buttons in the overflow menu into the addons panel instead.
   if (currentVersion < 19) {
     let overflowPlacements =
       gSavedState.placements[CustomizableUI.AREA_FIXED_OVERFLOW_PANEL] || [];
     // The most likely case is that there are no AREA_ADDONS placements, in which case the
     // array won't exist.
     let addonsPlacements =
       gSavedState.placements[CustomizableUI.AREA_ADDONS] || [];

     // Migration algorithm for transitioning to Unified Extensions:
     //
     // 1. Create two arrays, one for extension widgets, one for built-in widgets.
     // 2. Iterate all items in the overflow panel, and push them into the
     //    appropriate array based on whether or not its an extension widget.
     // 3. Overwrite the overflow panel placements with the built-in widgets array.
     // 4. Prepend the extension widgets to the addonsPlacements array. Note that this
     //    does not overwrite this array as a precaution because it's possible
     //    (though pretty unlikely) that some widgets are already there.
     //
     // For extension widgets that were in the palette, they will be appended to the
     // addons area when they're created within createWidget.
     let extWidgets = [];
     let builtInWidgets = [];
     for (let widgetId of overflowPlacements) {
       if (CustomizableUI.isWebExtensionWidget(widgetId)) {
         extWidgets.push(widgetId);
       } else {
         builtInWidgets.push(widgetId);
       }
     }
     gSavedState.placements[CustomizableUI.AREA_FIXED_OVERFLOW_PANEL] =
       builtInWidgets;
     gSavedState.placements[CustomizableUI.AREA_ADDONS] = [
       ...extWidgets,
       ...addonsPlacements,
     ];
   }

   // Add the PBM reset button as the right most button item
   if (currentVersion < 20) {
     let navbarPlacements = gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     // Place the button as the first item to the left of the hamburger menu
     if (
       navbarPlacements &&
       !navbarPlacements.includes("reset-pbm-toolbar-button")
     ) {
       navbarPlacements.push("reset-pbm-toolbar-button");
     }
   }

   if (currentVersion < 21) {
     // If the vertical-spacer has not yet been added, ensure its to the left of the urlbar initially
     let navbarPlacements = gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     if (!navbarPlacements.includes("vertical-spacer")) {
       let urlbarContainerPosition =
         navbarPlacements.indexOf("urlbar-container");
       gSavedState.placements[CustomizableUI.AREA_NAVBAR].splice(
         urlbarContainerPosition - 1,
         0,
         "vertical-spacer"
       );
     }
   }

   if (currentVersion < 22) {
     if (!Services.prefs.getBoolPref(kPrefSidebarPositionStartEnabled, true)) {
       // If the sidebar is on the right, the toolbar button is also on the right.
       const navbarPlacements =
         gSavedState.placements[CustomizableUI.AREA_NAVBAR];
       if (navbarPlacements[0] === "sidebar-button") {
         navbarPlacements.shift();
         navbarPlacements.push("sidebar-button");
       }
     }
   }

   if (currentVersion < 23) {
     const navbarPlacements =
       gSavedState.placements[CustomizableUI.AREA_NAVBAR];

     let buttonIndex = navbarPlacements.indexOf("save-to-pocket-button");
     if (buttonIndex != -1) {
       navbarPlacements.splice(buttonIndex, 1);
     }
   }
 },

 /**
  * A separate state migration method for when we introduced the Proton
  * retheme in 2021. Because the Proton retheme was toggle-able via a pref,
  * it was important to have the migration separated out. Like most old
  * migrations, this is probably a historical artifact at this point.
  */
 updateForNewProtonVersion() {
   const VERSION = 3;
   let currentVersion = Services.prefs.getIntPref(
     kPrefProtonToolbarVersion,
     0
   );
   if (currentVersion >= VERSION) {
     return;
   }

   let placements = gSavedState?.placements?.[CustomizableUI.AREA_NAVBAR];

   if (!placements) {
     // The profile was created with this version, so no need to migrate.
     Services.prefs.setIntPref(kPrefProtonToolbarVersion, VERSION);
     return;
   }

   // Remove the home button if it hasn't been used and is set to about:home
   if (currentVersion < 1) {
     let homePage = lazy.HomePage.get();
     if (
       placements.includes("home-button") &&
       !Services.prefs.getBoolPref(kPrefHomeButtonUsed) &&
       (homePage == "about:home" || homePage == "about:blank") &&
       Services.policies.isAllowed("removeHomeButtonByDefault")
     ) {
       placements.splice(placements.indexOf("home-button"), 1);
     }
   }

   // Remove the library button if it hasn't been used
   if (currentVersion < 2) {
     if (
       placements.includes("library-button") &&
       !Services.prefs.getBoolPref(kPrefLibraryButtonUsed)
     ) {
       placements.splice(placements.indexOf("library-button"), 1);
     }
   }

   // Remove the library button if it hasn't been used
   if (currentVersion < 3) {
     if (
       placements.includes("sidebar-button") &&
       !Services.prefs.getBoolPref(kPrefSidebarButtonUsed)
     ) {
       placements.splice(placements.indexOf("sidebar-button"), 1);
     }
   }

   Services.prefs.setIntPref(kPrefProtonToolbarVersion, VERSION);
 },

 /**
  * When upgrading, checks to see if any built-in button definitions were
  * just removed / marked obsolete (see ObsoleteBuiltinButtons) for the
  * current kVersion. If so, marks those buttons as seen.
  */
 markObsoleteBuiltinButtonsSeen() {
   if (!gSavedState) {
     return;
   }
   let currentVersion = gSavedState.currentVersion;
   if (currentVersion >= kVersion) {
     return;
   }
   // we're upgrading, update state if necessary
   for (let id in ObsoleteBuiltinButtons) {
     let version = ObsoleteBuiltinButtons[id];
     if (version == kVersion) {
       gSeenWidgets.add(id);
       gDirty = true;
     }
   }
 },

 updateForBaseBrowser() {
   if (!gSavedState) {
     // Use the defaults.
     return;
   }

   const currentVersion = gSavedState.currentVersionBaseBrowser;

   if (currentVersion < 1) {
     // NOTE: In base-browser/tor-browser version 12.5a5, and earlier, the
     // toolbar was configured by setting the full JSON string for the default
     // "browser.uiCustomization.state" preference value. The disadvantage is
     // that we could not update this value in a way that existing users (who
     // would have non-default preference values) would also get the desired
     // change (e.g. for adding or removing a button).
     //
     // With tor-browser#41736 we want to switch to changing the toolbar
     // dynamically like firefox. Therefore, this first version transfer simply
     // gets the toolbar into the same state we wanted before, away from the
     // default firefox state.
     //
     // If an existing user state aligned with the previous default
     // "browser.uiCustomization.state" then this shouldn't visibly change
     // anything.
     // If a user explicitly customized the toolbar to go back to the firefox
     // default, then this may undo those changes.
     const navbarPlacements =
       gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     if (navbarPlacements) {
       const getBeforeAfterUrlbar = () => {
         // NOTE: The urlbar is non-removable from the navbar, so should have
         // an index.
         const index = navbarPlacements.indexOf("urlbar-container");
         let after = index + 1;
         if (
           after < navbarPlacements.length &&
           navbarPlacements[after] === "search-container"
         ) {
           // Skip past the search-container.
           after++;
         }
         return { before: index - 1, after };
       };

       // Remove the urlbar springs either side of the urlbar.
       const { before, after } = getBeforeAfterUrlbar();
       if (
         after < navbarPlacements.length &&
         this.matchingSpecials(navbarPlacements[after], "spring")
       ) {
         // Remove the spring after.
         navbarPlacements.splice(after, 1);
         // NOTE: The `before` index does not change.
       }
       if (
         before >= 0 &&
         this.matchingSpecials(navbarPlacements[before], "spring")
       ) {
         // Remove the spring before.
         navbarPlacements.splice(before, 1);
       }

       // Make sure the security-level-button and new-identity-button appears
       // in the toolbar.
       for (const id of ["new-identity-button", "security-level-button"]) {
         let alreadyAdded = false;
         for (const placements of Object.values(gSavedState.placements)) {
           if (placements.includes(id)) {
             alreadyAdded = true;
             break;
           }
         }
         if (alreadyAdded) {
           continue;
         }

         // Add to the nav-bar, after the urlbar-container.
         // NOTE: We have already removed the spring after the urlbar.
         navbarPlacements.splice(getBeforeAfterUrlbar().after, 0, id);
       }
     }

     // Remove save-to-pocket-button. See tor-browser#18886 and
     // tor-browser#31602.
     for (const placements of Object.values(gSavedState.placements)) {
       let buttonIndex = placements.indexOf("save-to-pocket-button");
       if (buttonIndex != -1) {
         placements.splice(buttonIndex, 1);
       }
     }

     // Remove unused fields that used to be part of
     // "browser.uiCustomization.state".
     delete gSavedState.placements["PanelUI-contents"];
     delete gSavedState.placements["addon-bar"];
   }

   if (currentVersion < 2) {
     // Matches against kVersion 19, i.e. when the unified-extensions-button
     // was introduced and extensions were moved from the palette to
     // AREA_ADDONS.
     // For base browser, we want the NoScript addon to be moved from the
     // default palette to AREA_NAVBAR, so that if it becomes shown through the
     // preference extensions.hideNoScript it will appear in the toolbar.
     // If the NoScript addon is already in AREA_NAVBAR, we instead flip the
     // extensions.hideNoScript preference so that it remains visible.
     // See tor-browser#41581.
     const navbarPlacements =
       gSavedState.placements[CustomizableUI.AREA_NAVBAR];
     if (navbarPlacements) {
       let noScriptVisible = false;
       for (const [area, placements] of Object.entries(
         gSavedState.placements
       )) {
         const index = placements.indexOf(NoScriptId);
         if (index === -1) {
           continue;
         }
         if (area === CustomizableUI.AREA_ADDONS) {
           // Has been placed in the ADDONS area.
           // Most likely, this is an alpha or nightly user who received the
           // firefox update in a run before this one. In this case, we want to
           // match the same behaviour as a stable user: hide the button and
           // move it to the NAVBAR instead.
           placements.splice(index, 1);
         } else {
           // It is in an area other than the ADDON (and not in the palette).
           noScriptVisible = true;
         }
       }
       if (noScriptVisible) {
         // Keep the button where it is and make sure it is visible.
         Services.prefs.setBoolPref("extensions.hideNoScript", false);
       } else {
         // Should appear just before unified-extensions-button, which is
         // currently not part of the default placements.
         const placeIndex = navbarPlacements.indexOf(
           "unified-extensions-button"
         );
         if (placeIndex === -1) {
           navbarPlacements.push(NoScriptId);
         } else {
           navbarPlacements.splice(placeIndex, 0, NoScriptId);
         }
       }
     }
   }
 },

 updateForTorBrowser() {
   if (!gSavedState) {
     // Use the defaults.
     return;
   }

   const currentVersion = gSavedState.currentVersionTorBrowser;

   if (currentVersion < 1) {
     // Remove torbutton-button, which no longer exists.
     for (const placements of Object.values(gSavedState.placements)) {
       let buttonIndex = placements.indexOf("torbutton-button");
       if (buttonIndex != -1) {
         placements.splice(buttonIndex, 1);
       }
     }
   }
 },

 /**
  * If a new area was defined, or new default widgets for an area are defined,
  * this reconciles the placements of those new default widgets with the
  * existing customization and toolbar state of the browser.
  *
  * @param {string} aArea
  *   The ID of the area to reconcile the default widget state for.
  */
 placeNewDefaultWidgetsInArea(aArea) {
   let futurePlacedWidgets = gFuturePlacements.get(aArea);
   let savedPlacements =
     gSavedState && gSavedState.placements && gSavedState.placements[aArea];
   let defaultPlacements;
   if (
     CustomizableUI.verticalTabsEnabled &&
     gAreas.get(aArea).has("verticalTabsDefaultPlacements")
   ) {
     defaultPlacements = gAreas
       .get(aArea)
       .get("verticalTabsDefaultPlacements");
   } else {
     defaultPlacements = gAreas.get(aArea).get("defaultPlacements");
   }
   if (
     !savedPlacements ||
     !savedPlacements.length ||
     !futurePlacedWidgets ||
     !defaultPlacements ||
     !defaultPlacements.length
   ) {
     return;
   }
   let defaultWidgetIndex = -1;

   for (let widgetId of futurePlacedWidgets) {
     let widget = gPalette.get(widgetId);
     if (
       !widget ||
       widget.source !== CustomizableUI.SOURCE_BUILTIN ||
       !widget.defaultArea ||
       !(widget._introducedInVersion || widget._introducedByPref) ||
       savedPlacements.includes(widget.id)
     ) {
       continue;
     }
     defaultWidgetIndex = defaultPlacements.indexOf(widget.id);
     if (defaultWidgetIndex === -1) {
       continue;
     }
     // Now we know that this widget should be here by default, was newly introduced,
     // and we have a saved state to insert into, and a default state to work off of.
     // Try introducing after widgets that come before it in the default placements:
     for (let i = defaultWidgetIndex; i >= 0; i--) {
       // Special case: if the defaults list this widget as coming first, insert at the beginning:
       if (i === 0 && i === defaultWidgetIndex) {
         savedPlacements.splice(0, 0, widget.id);
         // Before you ask, yes, deleting things inside a let x of y loop where y is a Set is
         // safe, and we won't skip any items.
         futurePlacedWidgets.delete(widget.id);
         gDirty = true;
         break;
       }
       // Otherwise, if we're somewhere other than the beginning, check if the previous
       // widget is in the saved placements.
       if (i) {
         let previousWidget = defaultPlacements[i - 1];
         let previousWidgetIndex = savedPlacements.indexOf(previousWidget);
         if (previousWidgetIndex != -1) {
           savedPlacements.splice(previousWidgetIndex + 1, 0, widget.id);
           futurePlacedWidgets.delete(widget.id);
           gDirty = true;
           break;
         }
       }
     }
     // The loop above either inserts the item or doesn't - either way, we can get away
     // with doing nothing else now; if the item remains in gFuturePlacements, we'll
     // add it at the end in restoreStateForArea.
   }
   this.saveState();
 },

 /**
  * @see CustomizableUI.getCustomizationTarget
  * @param {Element|null} aElement
  * @returns {Element|null}
  */
 getCustomizationTarget(aElement) {
   if (!aElement) {
     return null;
   }

   if (
     !aElement._customizationTarget &&
     aElement.hasAttribute("customizable")
   ) {
     let id = aElement.getAttribute("customizationtarget");
     if (id) {
       aElement._customizationTarget =
         aElement.ownerDocument.getElementById(id);
     }

     if (!aElement._customizationTarget) {
       aElement._customizationTarget = aElement;
     }
   }

   return aElement._customizationTarget;
 },

 /**
  * Given a customizable widget ID, creates and returns a WidgetGroupWrapper
  * or a XULGroupWrapper for that widget (depending on how the widget is
  * provided). This wrapper is then cached and returned for future calls
  * for that same widget ID.
  *
  * If the customizable widget ID cannot be resolved to a particular provider,
  * null is returned.
  *
  * @param {string} aWidgetId
  *   The ID of the customizable widget to get the WidgetGroupWrapper /
  *   XULGroupWrapper for.
  * @returns {WidgetGroupWrapper|XULGroupWrapper|null}
  *   The appropriate GroupWrapper for the widget, or null if no such wrapper
  *   can be found.
  */
 wrapWidget(aWidgetId) {
   if (gGroupWrapperCache.has(aWidgetId)) {
     return gGroupWrapperCache.get(aWidgetId);
   }

   let provider = this.getWidgetProvider(aWidgetId);
   if (!provider) {
     return null;
   }

   if (provider == CustomizableUI.PROVIDER_API) {
     let widget = gPalette.get(aWidgetId);
     if (!widget.wrapper) {
       widget.wrapper = new WidgetGroupWrapper(widget);
       gGroupWrapperCache.set(aWidgetId, widget.wrapper);
     }
     return widget.wrapper;
   }

   // PROVIDER_SPECIAL gets treated the same as PROVIDER_XUL.
   // XXXgijs: this causes bugs in code that depends on widgetWrapper.provider
   // giving an accurate answer... filed as bug 1379821
   let wrapper = new XULWidgetGroupWrapper(aWidgetId);
   gGroupWrapperCache.set(aWidgetId, wrapper);
   return wrapper;
 },

 /**
  * @see CustomizableUI.registerArea
  * @param {string} aName
  * @param {object} aProperties
  * @param {boolean} aInternalCaller
  */
 registerArea(aName, aProperties, aInternalCaller) {
   if (typeof aName != "string" || !/^[a-z0-9-_]{1,}$/i.test(aName)) {
     throw new Error("Invalid area name");
   }

   let areaIsKnown = gAreas.has(aName);
   let props = areaIsKnown ? gAreas.get(aName) : new Map();
   const kImmutableProperties = new Set(["type", "overflowable"]);
   for (let key in aProperties) {
     if (
       areaIsKnown &&
       kImmutableProperties.has(key) &&
       props.get(key) != aProperties[key]
     ) {
       throw new Error("An area cannot change the property for '" + key + "'");
     }
     props.set(key, aProperties[key]);
   }
   // Default to a toolbar:
   if (!props.has("type")) {
     props.set("type", CustomizableUI.TYPE_TOOLBAR);
   }
   if (props.get("type") == CustomizableUI.TYPE_TOOLBAR) {
     // Check aProperties instead of props because this check is only interested
     // in the passed arguments, not the state of a potentially pre-existing area.
     if (!aInternalCaller && aProperties.defaultCollapsed) {
       throw new Error(
         "defaultCollapsed is only allowed for default toolbars."
       );
     }
     if (!props.has("defaultCollapsed")) {
       props.set("defaultCollapsed", true);
     }
   } else if (props.has("defaultCollapsed")) {
     throw new Error("defaultCollapsed only applies for TYPE_TOOLBAR areas.");
   }
   // Sanity check type:
   let allTypes = [CustomizableUI.TYPE_TOOLBAR, CustomizableUI.TYPE_PANEL];
   if (!allTypes.includes(props.get("type"))) {
     throw new Error("Invalid area type " + props.get("type"));
   }

   // And to no placements:
   if (!props.has("defaultPlacements")) {
     props.set("defaultPlacements", []);
   }
   // Sanity check default placements array:
   if (!Array.isArray(props.get("defaultPlacements"))) {
     throw new Error("Should provide an array of default placements");
   }

   if (!areaIsKnown) {
     gAreas.set(aName, props);

     // Reconcile new default widgets. Have to do this before we start restoring things.
     this.placeNewDefaultWidgetsInArea(aName);

     if (
       props.get("type") == CustomizableUI.TYPE_TOOLBAR &&
       !gPlacements.has(aName)
     ) {
       lazy.log.debug(
         `registerArea ${aName}, no gPlacements yet, nothing to restore`
       );
       // Guarantee this area exists in gFuturePlacements, to avoid checking it in
       // various places elsewhere.
       if (!gFuturePlacements.has(aName)) {
         gFuturePlacements.set(aName, new Set());
       }
     } else {
       this.restoreStateForArea(aName);
     }

     // If we have pending build area nodes, register all of them
     if (gPendingBuildAreas.has(aName)) {
       let pendingNodes = gPendingBuildAreas.get(aName);
       for (let pendingNode of pendingNodes) {
         this.registerToolbarNode(pendingNode);
       }
       gPendingBuildAreas.delete(aName);
     }
   }
 },

 /**
  * @see CustomizableUI.unregisterArea
  * @param {string} aName
  * @param {boolean} [aDestroyPlacements]
  */
 unregisterArea(aName, aDestroyPlacements) {
   if (typeof aName != "string" || !/^[a-z0-9-_]{1,}$/i.test(aName)) {
     throw new Error("Invalid area name");
   }
   if (!gAreas.has(aName) && !gPlacements.has(aName)) {
     throw new Error("Area not registered");
   }

   // Move all the widgets out
   this.beginBatchUpdate();
   try {
     let placements = gPlacements.get(aName);
     if (placements) {
       // Need to clone this array so removeWidgetFromArea doesn't modify it
       placements = [...placements];
       placements.forEach(this.removeWidgetFromArea, this);
     }

     // Delete all remaining traces.
     gAreas.delete(aName);
     // Only destroy placements when necessary:
     if (aDestroyPlacements) {
       gPlacements.delete(aName);
     } else {
       // Otherwise we need to re-set them, as removeFromArea will have emptied
       // them out:
       gPlacements.set(aName, placements);
     }
     gFuturePlacements.delete(aName);
     let existingAreaNodes = gBuildAreas.get(aName);
     if (existingAreaNodes) {
       for (let areaNode of existingAreaNodes) {
         this.notifyListeners(
           "onAreaNodeUnregistered",
           aName,
           this.getCustomizationTarget(areaNode),
           CustomizableUI.REASON_AREA_UNREGISTERED
         );
       }
     }
     gBuildAreas.delete(aName);
   } finally {
     this.endBatchUpdate(true);
   }
 },

 /**
  * @see CustomizableUI.registerToolbarNode
  * @param {Element} aToolbar
  */
 registerToolbarNode(aToolbar) {
   let area = aToolbar.id;
   if (gBuildAreas.has(area) && gBuildAreas.get(area).has(aToolbar)) {
     return;
   }
   let areaProperties = gAreas.get(area);

   // If this area is not registered, try to do it automatically:
   if (!areaProperties) {
     if (!gPendingBuildAreas.has(area)) {
       gPendingBuildAreas.set(area, []);
     }
     gPendingBuildAreas.get(area).push(aToolbar);
     return;
   }

   this.beginBatchUpdate();
   try {
     let placements = gPlacements.get(area);
     if (
       !placements &&
       areaProperties.get("type") == CustomizableUI.TYPE_TOOLBAR
     ) {
       this.restoreStateForArea(area);
       placements = gPlacements.get(area);
     }

     // For toolbars that need it, mark as dirty.
     let defaultPlacements = areaProperties.get("defaultPlacements");
     if (
       !this.builtinToolbars.has(area) ||
       placements.length != defaultPlacements.length ||
       !placements.every((id, i) => id == defaultPlacements[i])
     ) {
       gDirtyAreaCache.add(area);
     }

     if (areaProperties.get("overflowable")) {
       aToolbar.overflowable = new OverflowableToolbar(aToolbar);
     }

     this.registerBuildArea(area, aToolbar);

     // We only build the toolbar if it's been marked as "dirty". Dirty means
     // one of the following things:
     // 1) Items have been added, moved or removed from this toolbar before.
     // 2) The number of children of the toolbar does not match the length of
     //    the placements array for that area.
     //
     // This notion of being "dirty" is stored in a cache which is persisted
     // in the saved state.
     //
     // Secondly, if the list of placements contains an API-provided widget,
     // we need to call `buildArea` or it won't be built and put in the toolbar.
     if (
       gDirtyAreaCache.has(area) ||
       placements.some(id => gPalette.has(id))
     ) {
       this.buildArea(area, placements, aToolbar);
     } else {
       // We must have a builtin toolbar that's in the default state. We need
       // to only make sure that all the special nodes are correct.
       let specials = placements.filter(p => this.isSpecialWidget(p));
       if (specials.length) {
         this.updateSpecialsForBuiltinToolbar(aToolbar, specials);
       }
     }
     this.notifyListeners(
       "onAreaNodeRegistered",
       area,
       this.getCustomizationTarget(aToolbar)
     );
   } finally {
     lazy.log.debug(
       `registerToolbarNode for ${area}, tabstripAreasReady? ${this.tabstripAreasReady}`
     );
     this.endBatchUpdate();
   }
 },

 /**
  * For each "special" node in a toolbar (any spring, spacer, separator, or
  * element with an ID prefixed with kSpecialWidgetPfx), assigns the unique
  * ID from the saved state to the DOM nodes. These unique IDs are things like
  * "customizableui-special-spring30".
  *
  * @param {Element} aToolbar
  *   The <xul:toolbar> node to update the special widget children IDs for.
  * @param {string[]} aSpecialIDs
  *   An array of special node IDs from the saved placements state.
  */
 updateSpecialsForBuiltinToolbar(aToolbar, aSpecialIDs) {
   // Nodes are going to be in the correct order, so we can do this straightforwardly:
   let { children } = this.getCustomizationTarget(aToolbar);
   for (let kid of children) {
     if (
       this.matchingSpecials(aSpecialIDs[0], kid) &&
       kid.getAttribute("skipintoolbarset") != "true"
     ) {
       kid.id = aSpecialIDs.shift();
     }
     if (!aSpecialIDs.length) {
       return;
     }
   }
 },

 /**
  * This does the work of causing a customizable area to reflect the placements
  * that have been computed for that area. This means taking the initial
  * default DOM state of the area, and then modifying it to match the computed
  * state (either the state that had been saved in preferences, or the state
  * computed after doing runtime checks during initialization).
  *
  * @param {string} aAreaId
  *   The ID of the customizable area to "build".
  * @param {string[]} aPlacements
  *   The IDs of the customizable widgets that are expected to be in the
  *   customizable area.
  * @param {Element} aAreaNode
  *   The node associated with the area (as opposed to the customization
  *   target within that area).
  */
 buildArea(aAreaId, aPlacements, aAreaNode) {
   let document = aAreaNode.ownerDocument;
   let window = document.defaultView;
   let inPrivateWindow = lazy.PrivateBrowsingUtils.isWindowPrivate(window);
   let container = this.getCustomizationTarget(aAreaNode);
   let areaIsPanel =
     gAreas.get(aAreaId).get("type") == CustomizableUI.TYPE_PANEL;

   if (!container) {
     throw new Error(
       "Expected area " + aAreaId + " to have a customizationTarget attribute."
     );
   }

   // Restore nav-bar visibility since it may have been hidden
   // through a migration path (bug 938980) or an add-on.
   if (aAreaId == CustomizableUI.AREA_NAVBAR) {
     aAreaNode.collapsed = false;
   }

   this.beginBatchUpdate();

   try {
     let currentNode = container.firstElementChild;
     let placementsToRemove = new Set();
     for (let id of aPlacements) {
       while (
         currentNode &&
         currentNode.getAttribute("skipintoolbarset") == "true"
       ) {
         currentNode = currentNode.nextElementSibling;
       }

       // Fix ids for specials and continue, for correctly placed specials.
       if (
         currentNode &&
         (!currentNode.id || CustomizableUI.isSpecialWidget(currentNode)) &&
         this.matchingSpecials(id, currentNode)
       ) {
         currentNode.id = id;
       }
       if (currentNode && currentNode.id == id) {
         currentNode = currentNode.nextElementSibling;
         continue;
       }

       if (this.isSpecialWidget(id) && areaIsPanel) {
         placementsToRemove.add(id);
         continue;
       }

       let [provider, node] = this.getWidgetNode(id, window);
       if (!node) {
         lazy.log.debug("Unknown widget: " + id);
         continue;
       }

       let widget = null;
       // If the placements have items in them which are (now) no longer removable,
       // we shouldn't be moving them:
       if (provider == CustomizableUI.PROVIDER_API) {
         widget = gPalette.get(id);
         if (!widget.removable && aAreaId != widget.defaultArea) {
           placementsToRemove.add(id);
           continue;
         }
       } else if (
         provider == CustomizableUI.PROVIDER_XUL &&
         node.parentNode != container &&
         !this.isWidgetRemovable(node)
       ) {
         placementsToRemove.add(id);
         continue;
       } // Special widgets are always removable, so no need to check them

       if (inPrivateWindow && widget && !widget.showInPrivateBrowsing) {
         continue;
       }

       if (!inPrivateWindow && widget?.hideInNonPrivateBrowsing) {
         continue;
       }

       this.ensureButtonContextMenu(node, aAreaNode);

       // This needs updating in case we're resetting / undoing a reset.
       if (widget) {
         widget.currentArea = aAreaId;
       }
       this.insertWidgetBefore(node, currentNode, container, aAreaId);
       if (gResetting) {
         this.notifyListeners("onWidgetReset", node, container);
       } else if (gUndoResetting) {
         this.notifyListeners("onWidgetUndoMove", node, container);
       }
     }

     if (currentNode) {
       let palette = window.gNavToolbox ? window.gNavToolbox.palette : null;
       let limit = currentNode.previousElementSibling;
       let node = container.lastElementChild;
       while (node && node != limit) {
         let previousSibling = node.previousElementSibling;
         // Nodes opt-in to removability. If they're removable, and we haven't
         // seen them in the placements array, then we toss them into the palette
         // if one exists. If no palette exists, we just remove the node. If the
         // node is not removable, we leave it where it is. However, we can only
         // safely touch elements that have an ID - both because we depend on
         // IDs (or are specials), and because such elements are not intended to
         // be widgets (eg, titlebar-spacer elements).
         if (
           (node.id || this.isSpecialWidget(node)) &&
           node.getAttribute("skipintoolbarset") != "true"
         ) {
           if (this.isWidgetRemovable(node)) {
             if (node.id && (gResetting || gUndoResetting)) {
               let widget = gPalette.get(node.id);
               if (widget) {
                 widget.currentArea = null;
               }
             }
             this.notifyDOMChange(node, null, container, true, () => {
               if (palette && !this.isSpecialWidget(node.id)) {
                 palette.appendChild(node);
                 this.removeLocationAttributes(node);
               } else {
                 container.removeChild(node);
               }
             });
           } else {
             node.setAttribute("removable", false);
             lazy.log.debug(
               "Adding non-removable widget to placements of " +
                 aAreaId +
                 ": " +
                 node.id
             );
             gPlacements.get(aAreaId).push(node.id);
             gDirty = true;
           }
         }
         node = previousSibling;
       }
     }

     // If there are placements in here which aren't removable from their original area,
     // we remove them from this area's placement array. They will (have) be(en) added
     // to their original area's placements array in the block above this one.
     if (placementsToRemove.size) {
       let placementAry = gPlacements.get(aAreaId);
       for (let id of placementsToRemove) {
         let index = placementAry.indexOf(id);
         placementAry.splice(index, 1);
       }
     }

     if (gResetting) {
       this.notifyListeners("onAreaReset", aAreaId, container);
     }
   } finally {
     this.endBatchUpdate();
   }
 },

 /**
  * @see CustomizableUI.addPanelCloseListeners
  * @param {Element} aPanel
  */
 addPanelCloseListeners(aPanel) {
   aPanel.addEventListener("click", this, { mozSystemGroup: true });
   aPanel.addEventListener("keypress", this, { mozSystemGroup: true });
   let win = aPanel.ownerGlobal;
   if (!gPanelsForWindow.has(win)) {
     gPanelsForWindow.set(win, new Set());
   }
   gPanelsForWindow.get(win).add(this._getPanelForNode(aPanel));
 },

 /**
  * @see CustomizableUI.removePanelCloseListeners
  * @param {Element} aPanel
  */
 removePanelCloseListeners(aPanel) {
   aPanel.removeEventListener("click", this, { mozSystemGroup: true });
   aPanel.removeEventListener("keypress", this, { mozSystemGroup: true });
   let win = aPanel.ownerGlobal;
   let panels = gPanelsForWindow.get(win);
   if (panels) {
     panels.delete(this._getPanelForNode(aPanel));
   }
 },

 /**
  * Given a customizable widget node, attempts to assign it the correct
  * context / contextmenu attributes for the current placement of that
  * widget.
  *
  * @param {Element} aNode
  *   The node to set the context / contextmenu attributes for.
  * @param {Element} aAreaNode
  *   The node representing the area that aNode is currently placed within.
  * @param {boolean} forcePanel
  *   True if we should force the panel context menu, regardless of the
  *   current placement. This is mainly useful for the overflow panel, where
  *   the placement may be the overflowable toolbar, but visually the widget
  *   is within the overflowable toolbar panel.
  */
 ensureButtonContextMenu(aNode, aAreaNode, forcePanel) {
   const kPanelItemContextMenu = "customizationPanelItemContextMenu";

   let currentContextMenu =
     aNode.getAttribute("context") || aNode.getAttribute("contextmenu");
   let contextMenuForPlace;

   if (
     CustomizableUI.isWebExtensionWidget(aNode.id) &&
     (aAreaNode?.id == CustomizableUI.AREA_ADDONS ||
       aNode.getAttribute("overflowedItem") == "true")
   ) {
     contextMenuForPlace = null;
   } else {
     contextMenuForPlace =
       forcePanel || "panel" == CustomizableUI.getPlaceForItem(aAreaNode)
         ? kPanelItemContextMenu
         : null;
   }
   if (contextMenuForPlace && !currentContextMenu) {
     aNode.setAttribute("context", contextMenuForPlace);
   } else if (
     currentContextMenu == kPanelItemContextMenu &&
     contextMenuForPlace != kPanelItemContextMenu
   ) {
     aNode.removeAttribute("context");
     aNode.removeAttribute("contextmenu");
   }
 },

 /**
  * Returns the ID of the provider for a given widget. This is one of the
  * CustomizableUI.PROVIDER_* constants.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to get the provider for.
  * @returns {string}
  *   One of the CustomizableUI.PROVIDER_* constants.
  */
 getWidgetProvider(aWidgetId) {
   if (this.isSpecialWidget(aWidgetId)) {
     return CustomizableUI.PROVIDER_SPECIAL;
   }
   if (gPalette.has(aWidgetId)) {
     return CustomizableUI.PROVIDER_API;
   }
   // If this was an API widget that was destroyed, return null:
   if (gSeenWidgets.has(aWidgetId)) {
     return null;
   }

   // We fall back to the XUL provider, but we don't know for sure (at this
   // point) whether it exists there either. So the API is technically lying.
   // Ideally, it would be able to return an error value (or throw an
   // exception) if it really didn't exist. Our code calling this function
   // handles that fine, but this is a public API.
   return CustomizableUI.PROVIDER_XUL;
 },

 /**
  * @typedef {string|null} GetWidgetNodeIndex0
  *   The ID of the provider for the widget node. This is one of the constants
  *   in CustomizableUI.PROVIDER_*. This is null if no node is found for the
  *   widget ID.
  * @typedef {Element|null} GetWidgetNodeIndex1
  *   The found node associated with a widget ID, or null if no such node can
  *   be found.
  * @typedef {[GetWidgetNodeIndex0, GetWidgetNodeIndex1]} GetWidgetNodeResult
  */

 /**
  * For a given window, returns the node associated with a widget ID.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to get the associated node for in the window.
  * @param {DOMWindow} aWindow
  *   The window to find the node for, associated with aWidgetId.
  * @returns {GetWidgetNodeResult}
  *   The found node information.
  */
 getWidgetNode(aWidgetId, aWindow) {
   let document = aWindow.document;

   if (this.isSpecialWidget(aWidgetId)) {
     let widgetNode =
       document.getElementById(aWidgetId) ||
       this.createSpecialWidget(aWidgetId, document);
     return [CustomizableUI.PROVIDER_SPECIAL, widgetNode];
   }

   let widget = gPalette.get(aWidgetId);
   if (widget) {
     // If we have an instance of this widget already, just use that.
     if (widget.instances.has(document)) {
       lazy.log.debug(
         "An instance of widget " +
           aWidgetId +
           " already exists in this " +
           "document. Reusing."
       );
       return [CustomizableUI.PROVIDER_API, widget.instances.get(document)];
     }

     return [
       CustomizableUI.PROVIDER_API,
       this.buildWidgetNode(document, widget),
     ];
   }

   lazy.log.debug("Searching for " + aWidgetId + " in toolbox.");
   let node = this.findXULWidgetInWindow(aWidgetId, aWindow);
   if (node) {
     return [CustomizableUI.PROVIDER_XUL, node];
   }

   lazy.log.debug("No node for " + aWidgetId + " found.");
   return [null, null];
 },

 /**
  * @see CustomizableUI.registerPanelNode
  * @param {Element} aNode
  * @param {Element} aAreaId
  */
 registerPanelNode(aNode, aAreaId) {
   if (gBuildAreas.has(aAreaId) && gBuildAreas.get(aAreaId).has(aNode)) {
     return;
   }

   aNode._customizationTarget = aNode;
   this.addPanelCloseListeners(this._getPanelForNode(aNode));

   let placements = gPlacements.get(aAreaId);
   this.buildArea(aAreaId, placements, aNode);
   this.notifyListeners("onAreaNodeRegistered", aAreaId, aNode);

   for (let child of aNode.children) {
     if (child.localName != "toolbarbutton") {
       if (child.localName == "toolbaritem") {
         this.ensureButtonContextMenu(child, aNode, true);
       }
       continue;
     }
     this.ensureButtonContextMenu(child, aNode, true);
   }

   this.registerBuildArea(aAreaId, aNode);
 },

 /**
  * @type {CustomizableUIOnWidgetAddedCallback}
  */
 onWidgetAdded(aWidgetId, aArea, _aPosition) {
   this.insertNode(aWidgetId, aArea, true);

   if (!gResetting) {
     this._clearPreviousUIState();
   }
 },

 /**
  * @type {CustomizableUIOnWidgetRemovedCallback}
  */
 onWidgetRemoved(aWidgetId, aArea) {
   let areaNodes = gBuildAreas.get(aArea);
   if (!areaNodes) {
     return;
   }

   let area = gAreas.get(aArea);
   let isToolbar = area.get("type") == CustomizableUI.TYPE_TOOLBAR;
   let isOverflowable = isToolbar && area.get("overflowable");
   let showInPrivateBrowsing = gPalette.has(aWidgetId)
     ? gPalette.get(aWidgetId).showInPrivateBrowsing
     : true;
   let hideInNonPrivateBrowsing =
     gPalette.get(aWidgetId)?.hideInNonPrivateBrowsing ?? false;

   for (let areaNode of areaNodes) {
     let window = areaNode.ownerGlobal;
     if (
       !showInPrivateBrowsing &&
       lazy.PrivateBrowsingUtils.isWindowPrivate(window)
     ) {
       continue;
     }

     if (
       hideInNonPrivateBrowsing &&
       !lazy.PrivateBrowsingUtils.isWindowPrivate(window)
     ) {
       continue;
     }

     let container = this.getCustomizationTarget(areaNode);
     let widgetNode = window.document.getElementById(aWidgetId);
     if (widgetNode && isOverflowable) {
       container = areaNode.overflowable.getContainerFor(widgetNode);
     }

     if (!widgetNode || !container.contains(widgetNode)) {
       lazy.log.info(
         "Widget " + aWidgetId + " not found, unable to remove from " + aArea
       );
       continue;
     }

     this.notifyDOMChange(widgetNode, null, container, true, () => {
       // We remove location attributes here to make sure they're gone too when a
       // widget is removed from a toolbar to the palette. See bug 930950.
       this.removeLocationAttributes(widgetNode);
       // We also need to remove the panel context menu if it's there:
       this.ensureButtonContextMenu(widgetNode);
       if (gPalette.has(aWidgetId) || this.isSpecialWidget(aWidgetId)) {
         container.removeChild(widgetNode);
       } else {
         window.gNavToolbox.palette.appendChild(widgetNode);
       }
     });

     let windowCache = gSingleWrapperCache.get(window);
     if (windowCache) {
       windowCache.delete(aWidgetId);
     }
   }
   if (!gResetting) {
     this._clearPreviousUIState();
   }
 },

 /**
  * @type {CustomizableUIOnWidgetMovedCallback}
  */
 onWidgetMoved(aWidgetId, aArea, _aOldPosition, _aNewPosition) {
   this.insertNode(aWidgetId, aArea);
   if (!gResetting) {
     this._clearPreviousUIState();
   }
 },

 /**
  * @type {CustomizableUIOnCustomizeEnd}
  */
 onCustomizeEnd() {
   this._clearPreviousUIState();
 },

 /**
  * Registers a customizable area of a window with CustomizableUI such that it
  * can then be "built" to reflect the current stored state.
  *
  * @param {string} aAreaId
  *   The ID of the area to be registered.
  * @param {Element} aAreaNode
  *   The element for the area in the window being registered.
  */
 registerBuildArea(aAreaId, aAreaNode) {
   // We ensure that the window is registered to have its customization data
   // cleaned up when unloading.
   let window = aAreaNode.ownerGlobal;
   if (window.closed) {
     return;
   }
   this.registerBuildWindow(window);

   // Also register this build area's toolbox.
   if (window.gNavToolbox) {
     gBuildWindows.get(window).add(window.gNavToolbox);
   }

   if (!gBuildAreas.has(aAreaId)) {
     gBuildAreas.set(aAreaId, new Set());
   }

   gBuildAreas.get(aAreaId).add(aAreaNode);

   // Give a class to all customize targets to be used for styling in Customize Mode
   let customizableNode = this.getCustomizeTargetForArea(aAreaId, window);
   customizableNode.classList.add("customization-target");
 },

 /**
  * Registers a browser window with customizable elements with CustomizableUI.
  * This is mainly used to set up event handlers to perform cleanups if and
  * when the window closes. If the window is already registered, this is a
  * no-op.
  *
  * @param {DOMWindow} aWindow
  *   The window to register.
  */
 registerBuildWindow(aWindow) {
   if (!gBuildWindows.has(aWindow)) {
     gBuildWindows.set(aWindow, new Set());

     aWindow.addEventListener("unload", this);
     aWindow.addEventListener("command", this, true);

     this.notifyListeners("onWindowOpened", aWindow);
   }
 },

 /**
  * Unregisters a browser window that was registered with registerBuildWindow.
  * The onAreaNodeUnregistered callback will be called for each customizable
  * area within the window being unregistered. The onWidgetInstanceRemoved
  * will be called for each widget in the window being unregistered. Finally,
  * the onWindowClosed listener will be called with the window.
  *
  * @param {DOMWindow} aWindow
  *   The window to unregister.
  */
 unregisterBuildWindow(aWindow) {
   aWindow.removeEventListener("unload", this);
   aWindow.removeEventListener("command", this, true);
   gPanelsForWindow.delete(aWindow);
   gBuildWindows.delete(aWindow);
   gSingleWrapperCache.delete(aWindow);
   let document = aWindow.document;

   for (let [areaId, areaNodes] of gBuildAreas) {
     let areaProperties = gAreas.get(areaId);
     for (let node of areaNodes) {
       if (node.ownerDocument == document) {
         this.notifyListeners(
           "onAreaNodeUnregistered",
           areaId,
           this.getCustomizationTarget(node),
           CustomizableUI.REASON_WINDOW_CLOSED
         );
         if (areaProperties.get("overflowable")) {
           node.overflowable.uninit();
           node.overflowable = null;
         }
         areaNodes.delete(node);
       }
     }
   }

   for (let [, widget] of gPalette) {
     widget.instances.delete(document);
     this.notifyListeners("onWidgetInstanceRemoved", widget.id, document);
   }

   for (let [, pendingNodes] of gPendingBuildAreas) {
     for (let i = pendingNodes.length - 1; i >= 0; i--) {
       if (pendingNodes[i].ownerDocument == document) {
         pendingNodes.splice(i, 1);
       }
     }
   }

   this.notifyListeners("onWindowClosed", aWindow);
 },

 /**
  * @see CustomizableUI.handleNewBrowserWindow
  * @param {DOMWindow} aWindow
  */
 handleNewBrowserWindow(aWindow) {
   let { gNavToolbox, document, gBrowser } = aWindow;
   gNavToolbox.palette = document.getElementById(
     "BrowserToolbarPalette"
   ).content;

   let isVerticalTabs = Services.prefs.getBoolPref(
     kPrefSidebarVerticalTabsEnabled,
     false
   );
   let nonRemovables;

   // We don't want these normally non-removable elements to get put back into the
   // tabstrip if we're initializing with vertical tabs.
   // We do this for all windows, including popups, as otherwise it's possible for
   // us to get confused about window state and save a blank state to prefs.
   if (isVerticalTabs) {
     nonRemovables = [gBrowser.tabContainer];
     for (let elem of nonRemovables) {
       elem.setAttribute("removable", "true");
       // tell CUI to ignore this element when it builds the toolbar areas
       elem.setAttribute("skipintoolbarset", "true");
     }
   }

   // Now register all the toolbars
   for (let area of CustomizableUI.areas) {
     let type = CustomizableUI.getAreaType(area);
     if (type == CustomizableUI.TYPE_TOOLBAR) {
       let node = document.getElementById(area);
       this.registerToolbarNode(node);
     }
   }

   // Handle initial state of vertical tabs.
   if (isVerticalTabs) {
     // Show the vertical tabs toolbar
     aWindow.setToolbarVisibility(
       document.getElementById(CustomizableUI.AREA_VERTICAL_TABSTRIP),
       true,
       false,
       false
     );
     let tabstripToolbar = document.getElementById(
       CustomizableUI.AREA_TABSTRIP
     );
     let wasCollapsed = tabstripToolbar.collapsed;
     aWindow.TabBarVisibility.update();
     if (tabstripToolbar.collapsed !== wasCollapsed) {
       let eventParams = {
         detail: {
           visible: !tabstripToolbar.collapsed,
         },
         bubbles: true,
       };
       let event = new CustomEvent("toolbarvisibilitychange", eventParams);
       tabstripToolbar.dispatchEvent(event);
     }

     for (let elem of nonRemovables) {
       elem.setAttribute("removable", "false");
       elem.removeAttribute("skipintoolbarset");
     }
   }
 },

 /**
  * Sets some attributes on a customizable widget when it is introduced into
  * the DOM or moved around within it. Those attributes are "cui-anchorid"
  * and "cui-areatype".
  *
  * @param {Element} aNode
  *   The customizable widget node being inserted or moved within the DOM.
  * @param {string} aAreaId
  *   The area that the customizable widget is being moved into or within.
  */
 setLocationAttributes(aNode, aAreaId) {
   let props = gAreas.get(aAreaId);
   if (!props) {
     throw new Error(
       "Expected area " +
         aAreaId +
         " to have a properties Map " +
         "associated with it."
     );
   }

   aNode.setAttribute("cui-areatype", props.get("type") || "");
   let anchor = props.get("anchor");
   if (anchor) {
     aNode.setAttribute("cui-anchorid", anchor);
   } else {
     aNode.removeAttribute("cui-anchorid");
   }
 },

 /**
  * Removes any location attributes from a customizable widget node when the
  * node is removed from any of the registered customizable areas.
  *
  * @param {Element} aNode
  *   The node being removed from the customizable area.
  */
 removeLocationAttributes(aNode) {
   aNode.removeAttribute("cui-areatype");
   aNode.removeAttribute("cui-anchorid");
 },

 /**
  * Inserts a node associated with the customizable widget with ID aWidgetId
  * into all the areas with aAreaId across all windows.
  *
  * @param {string} aWidgetId
  *   The ID of the customizable widget to insert into aAreaId across all
  *   windows.
  * @param {string} aAreaId
  *   The ID of the area to insert the widget into across all windows.
  *   This method is a no-op if aAreaId is not associated with a registered
  *   area.
  * @param {boolean} isNew
  *   True if the widget is being newly inserted as opposed to moved.
  */
 insertNode(aWidgetId, aAreaId, isNew) {
   let areaNodes = gBuildAreas.get(aAreaId);
   if (!areaNodes) {
     return;
   }

   let placements = gPlacements.get(aAreaId);
   if (!placements) {
     lazy.log.error(
       "Could not find any placements for " +
         aAreaId +
         " when moving a widget."
     );
     return;
   }

   // Go through each of the nodes associated with this area and move the
   // widget to the requested location.
   for (let areaNode of areaNodes) {
     this.insertNodeInWindow(aWidgetId, areaNode, isNew);
   }
 },

 /**
  * Inserts a widget with ID aWidgetId into the passed area node in the
  * position dictated by CustomizableUI's internal positioning state for
  * widgets.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to insert into aAreaNode.
  * @param {Element} aAreaNode
  *   The customizable area node to insert aWidgetId into.
  * @param {boolean} isNew
  *   True if the widget is being inserted for the first time, instead of
  *   moved.
  */
 insertNodeInWindow(aWidgetId, aAreaNode, isNew) {
   let window = aAreaNode.ownerGlobal;
   let showInPrivateBrowsing = gPalette.has(aWidgetId)
     ? gPalette.get(aWidgetId).showInPrivateBrowsing
     : true;
   let hideInNonPrivateBrowsing =
     gPalette.get(aWidgetId)?.hideInNonPrivateBrowsing ?? false;

   if (
     !showInPrivateBrowsing &&
     lazy.PrivateBrowsingUtils.isWindowPrivate(window)
   ) {
     return;
   }

   if (
     hideInNonPrivateBrowsing &&
     !lazy.PrivateBrowsingUtils.isWindowPrivate(window)
   ) {
     return;
   }

   let [, widgetNode] = this.getWidgetNode(aWidgetId, window);
   if (!widgetNode) {
     lazy.log.error("Widget '" + aWidgetId + "' not found, unable to move");
     return;
   }

   let areaId = aAreaNode.id;
   if (isNew) {
     this.ensureButtonContextMenu(widgetNode, aAreaNode);
   }

   let [insertionContainer, nextNode] = this.findInsertionPoints(
     widgetNode,
     aAreaNode
   );
   this.insertWidgetBefore(widgetNode, nextNode, insertionContainer, areaId);
 },

 /**
  * @typedef {Element|null} FindInsertionPointsIndex0
  *   The container that the node should be inserted into, or null if no such
  *   container can be found.
  * @typedef {Element|null} FindInsertionPointsIndex1
  *   The node that the insertion should occur before, or null if no such
  *   sibling can be found.
  * @typedef {[FindInsertionPointsIndex0, FindInsertionPointsIndex1]} FindInsertionPointsResult
  */

 /**
  * Given a node for a customizable widget that may have a placement within an
  * area, find the location in the DOM where it makes the most sense to insert
  * that node. In the event of there being a placement for aNode in aAreaNode,
  * this insertion point will reflect the index of the node in that area's
  * placements array. In the event of there not being a pre-existing placement
  * for aNode in aAreaNode, the node will be prepended to the area.
  *
  * @param {Element} aNode
  * @param {Element} aAreaNode
  * @returns {FindInsertionPointsResult}
  */
 findInsertionPoints(aNode, aAreaNode) {
   let areaId = aAreaNode.id;
   let props = gAreas.get(areaId);

   // For overflowable toolbars, rely on them (because the work is more complicated):
   if (
     props.get("type") == CustomizableUI.TYPE_TOOLBAR &&
     props.get("overflowable")
   ) {
     return aAreaNode.overflowable.findOverflowedInsertionPoints(aNode);
   }

   let container = this.getCustomizationTarget(aAreaNode);
   let placements = gPlacements.get(areaId);
   let nodeIndex = placements.indexOf(aNode.id);

   while (++nodeIndex < placements.length) {
     let nextNodeId = placements[nodeIndex];
     // We use aAreaNode here, because if aNode is in a template, its
     // `ownerDocument` is *not* going to be the browser.xhtml document,
     // so we cannot rely on it.
     let nextNode = aAreaNode.ownerDocument.getElementById(nextNodeId);
     // If the next placed widget exists, and is a direct child of the
     // container, or wrapped in a customize mode wrapper (toolbarpaletteitem)
     // inside the container, insert beside it.
     // We have to check the parent to avoid errors when the placement ids
     // are for nodes that are no longer customizable.
     if (
       nextNode &&
       (nextNode.parentNode == container ||
         (nextNode.parentNode.localName == "toolbarpaletteitem" &&
           nextNode.parentNode.parentNode == container))
     ) {
       return [container, nextNode];
     }
   }

   return [container, null];
 },

 /**
  * Inserts a node associated with a widget before some other node within a
  * container within a customizable area.
  *
  * @param {Element} aNode
  *   The customizable widget node to insert.
  * @param {Element|null} aNextNode
  *   The node that the inserted node should be inserted before, or null if
  *   it should be inserted at the end of aContainer.
  * @param {Element} aContainer
  *   The parent node of both aNode and aNextNode.
  * @param {string} aAreaId
  *   The identifier string of the area that aNode is being inserted into.
  */
 insertWidgetBefore(aNode, aNextNode, aContainer, aAreaId) {
   this.notifyDOMChange(aNode, aNextNode, aContainer, false, () => {
     this.setLocationAttributes(aNode, aAreaId);
     aContainer.insertBefore(aNode, aNextNode);
   });
 },

 /**
  * Fires the onWidgetBeforeDOMChange event, then calls aCallback, before
  * firing the onWidgetAfterDOMChange event.
  *
  * @param {Element} aNode
  *   The node that is being changed.
  * @param {Element|null} aNextNode
  *   The node immediately after the one changing, or null if there is no next
  *   node in the container.
  * @param {Element} aContainer
  *   The container of the node that is being changed.
  * @param {boolean} aIsRemove
  *   True iff the action about to happen is the removal of the DOM node.
  * @param {Function} aCallback
  *   A synchronous function that will be called after the
  *   onWidgetBeforeDOMChange event is fired, but before onWidgetAfterDOMChange
  *   is fired.
  */
 notifyDOMChange(aNode, aNextNode, aContainer, aIsRemove, aCallback) {
   this.notifyListeners(
     "onWidgetBeforeDOMChange",
     aNode,
     aNextNode,
     aContainer,
     aIsRemove
   );
   aCallback();
   this.notifyListeners(
     "onWidgetAfterDOMChange",
     aNode,
     aNextNode,
     aContainer,
     aIsRemove
   );
 },

 /**
  * General event handler for CustomizableUIInternal that mostly just
  * dispatches to more specialized event handlers based on the event type.
  *
  * @param {CommandEvent|MouseEvent|KeyEvent|Event} aEvent
  */
 handleEvent(aEvent) {
   switch (aEvent.type) {
     case "command":
       if (!this._originalEventInPanel(aEvent)) {
         break;
       }
       aEvent = aEvent.sourceEvent;
     // Fall through
     case "click":
     case "keypress":
       this.maybeAutoHidePanel(aEvent);
       break;
     case "unload":
       this.unregisterBuildWindow(aEvent.currentTarget);
       break;
   }
 },

 /**
  * Returns true if the CommandEvent is being fired on a target that exists
  * in one of the panels that CustomizableUI tracks in gPanelsForWindow.
  *
  * @param {CommandEvent} aEvent
  * @returns {boolean}
  */
 _originalEventInPanel(aEvent) {
   let e = aEvent.sourceEvent;
   if (!e) {
     return false;
   }
   let node = this._getPanelForNode(e.target);
   if (!node) {
     return false;
   }
   let win = e.view;
   let panels = gPanelsForWindow.get(win);
   return !!panels && panels.has(node);
 },

 /**
  * If passed a DOM node, this will return the ID attribute for the node if it
  * exists. If it doesn't, it will check to see if the element localName starts
  * with "toolbar", and if so, return the rest of the localName after that
  * string. This means that for a <toolbarseparator> without an ID, this will
  * return "separator". If the element does not have a localName that starts
  * with "toolbar", this will return the empty string.
  *
  * If aNode happens to be a string instead of a DOM node, this simply returns
  * the string back.
  *
  * @param {Element|string} aStringOrNode
  *   A node to try to get the special identifier for, or a string that will
  *   be echoed back to the caller.
  * @returns {string}
  *   The special identifier for the node, the empty string, or aStringOrNode
  *   in the event that aStringOrNode happened to already be a string.
  */
 _getSpecialIdForNode(aStringOrNode) {
   if (typeof aStringOrNode == "object" && aStringOrNode.localName) {
     if (aStringOrNode.id) {
       return aStringOrNode.id;
     }
     if (aStringOrNode.localName.startsWith("toolbar")) {
       return aStringOrNode.localName.substring(7);
     }
     return "";
   }
   return aStringOrNode;
 },

 /**
  * Returns true if the passed in ID or node happens to be one of the "special"
  * widget types (a separator, a spring, or a spacer).
  *
  * @param {string|Element} aStringOrNode
  *   An ID for a node, or an actual node itself to check for special-ness.
  * @returns {boolean}
  *   True if the ID or node resolves to a "special" widget type.
  */
 isSpecialWidget(aStringOrNode) {
   if (aStringOrNode === null) {
     lazy.log.debug("isSpecialWidget was passed null");
     return false;
   }
   aStringOrNode = this._getSpecialIdForNode(aStringOrNode);
   return (
     aStringOrNode.startsWith(kSpecialWidgetPfx) ||
     aStringOrNode.startsWith("separator") ||
     aStringOrNode.startsWith("spring") ||
     aStringOrNode.startsWith("spacer")
   );
 },

 /**
  * Returns true if the passed in strings (or nodes) happen to be the same
  * special widget.
  *
  * @param {string|Element} aId1
  *   The first ID or element to compare to the second.
  * @param {string|Element} aId2
  *   The second ID or element to compare to the first.
  * @returns {boolean}
  *   True if the two strings or elements being compared refer to the same
  *   special widget.
  */
 matchingSpecials(aId1, aId2) {
   aId1 = this._getSpecialIdForNode(aId1);
   aId2 = this._getSpecialIdForNode(aId2);

   return (
     this.isSpecialWidget(aId1) &&
     this.isSpecialWidget(aId2) &&
     aId1.match(/spring|spacer|separator/)[0] ==
       aId2.match(/spring|spacer|separator/)[0]
   );
 },

 /**
  * If the aId string starts with any of "spring", "spacer" or "separator" (any
  * of the special widget types), this will add a the special widget prefix
  * to the id, as well as a unique numeric suffix at the end and return it.
  *
  * Otherwise, this simply echoes back the aId string.
  *
  * @param {string} aId
  * @returns {string}
  *   The aId string with the special widget prefix and unique numeric suffix
  *   if the aId string is for a special widget, otherwise this just echoes
  *   back aId.
  */
 ensureSpecialWidgetId(aId) {
   let nodeType = aId.match(/spring|spacer|separator/)[0];
   // If the ID we were passed isn't a generated one, generate one now:
   if (nodeType == aId) {
     // Ids are differentiated through a unique count suffix.
     return kSpecialWidgetPfx + aId + ++gNewElementCount;
   }
   return aId;
 },

 /**
  * @see CustomizableUI.createSpecialWidget
  * @param {string} aId
  * @param {Document} aDocument
  * @returns {Element}
  */
 createSpecialWidget(aId, aDocument) {
   let nodeName = "toolbar" + aId.match(/spring|spacer|separator/)[0];
   let node = aDocument.createXULElement(nodeName);
   node.className = "chromeclass-toolbar-additional";
   node.id = this.ensureSpecialWidgetId(aId);
   return node;
 },

 /**
  * Find a XUL-provided widget node in a window. Don't try to use this
  * for an API-provided widget or a special widget.
  *
  * @param {string} aId
  *   The ID of the XUL-provided widget to find the node for in aWindow.
  * @param {DOMWindow} aWindow
  *   The window to find the XUL-provided widget node for.
  * @returns {Element|null}
  *   The found XUL widget node, or null if it cannot be found.
  * @throws {Error}
  *   Throws if aWindow is not a registered build window.
  */
 findXULWidgetInWindow(aId, aWindow) {
   if (!gBuildWindows.has(aWindow)) {
     throw new Error("Build window not registered");
   }

   if (!aId) {
     lazy.log.error("findWidgetInWindow was passed an empty string.");
     return null;
   }

   let document = aWindow.document;

   // look for a node with the same id, as the node may be
   // in a different toolbar.
   let node = document.getElementById(aId);
   if (node) {
     let parent = node.parentNode;
     while (
       parent &&
       !(
         this.getCustomizationTarget(parent) ||
         parent == aWindow.gNavToolbox.palette
       )
     ) {
       parent = parent.parentNode;
     }

     if (parent) {
       let nodeInArea =
         node.parentNode.localName == "toolbarpaletteitem"
           ? node.parentNode
           : node;
       // Check if we're in a customization target, or in the palette:
       if (
         (this.getCustomizationTarget(parent) == nodeInArea.parentNode &&
           gBuildWindows.get(aWindow).has(aWindow.gNavToolbox)) ||
         aWindow.gNavToolbox.palette == nodeInArea.parentNode
       ) {
         // Normalize the removable attribute. For backwards compat, if
         // the widget is not located in a toolbox palette then absence
         // of the "removable" attribute means it is not removable.
         if (!node.hasAttribute("removable")) {
           // If we first see this in customization mode, it may be in the
           // customization palette instead of the toolbox palette.
           node.setAttribute(
             "removable",
             !this.getCustomizationTarget(parent)
           );
         }
         return node;
       }
     }
   }

   let toolboxes = gBuildWindows.get(aWindow);
   for (let toolbox of toolboxes) {
     if (toolbox.palette) {
       // Attempt to locate an element with a matching ID within
       // the palette.
       let element = toolbox.palette.getElementsByAttribute("id", aId)[0];
       if (element) {
         // Normalize the removable attribute. For backwards compat, this
         // is optional if the widget is located in the toolbox palette,
         // and defaults to *true*, unlike if it was located elsewhere.
         if (!element.hasAttribute("removable")) {
           element.setAttribute("removable", true);
         }
         return element;
       }
     }
   }
   return null;
 },

 /**
  * Constructs a node for a customizable UI widget that can be placed within
  * aDocument.
  *
  * @param {Document} aDocument
  *   The document that the node will be inserted into.
  * @param {string|WidgetGroupWrapper|XULWidgetGroupWrapper} aWidget
  *   The customizable UI widget wrapper or widget ID of the widget to
  *   construct.
  * @returns {Element|null}
  *   Returns the constructed node for the widget to be placed in aDocument.
  *   Will return null if the widget node is not allowed to be placed in
  *   aDocument (for example, if aDocument is a private browsing window
  *   document, and the widget is not allowed to be placed in such a window).
  * @throws {Error}
  *   Can throw if the document is not a browser window document, or if
  *   aWidget is null.
  */
 buildWidgetNode(aDocument, aWidget) {
   if (aDocument.documentURI != kExpectedWindowURL) {
     throw new Error("buildWidget was called for a non-browser window!");
   }
   if (typeof aWidget == "string") {
     aWidget = gPalette.get(aWidget);
   }
   if (!aWidget) {
     throw new Error("buildWidget was passed a non-widget to build.");
   }
   if (
     !aWidget.showInPrivateBrowsing &&
     lazy.PrivateBrowsingUtils.isWindowPrivate(aDocument.defaultView)
   ) {
     return null;
   }
   if (
     aWidget.hideInNonPrivateBrowsing &&
     !lazy.PrivateBrowsingUtils.isWindowPrivate(aDocument.defaultView)
   ) {
     return null;
   }

   lazy.log.debug("Building " + aWidget.id + " of type " + aWidget.type);

   let node;
   let button;
   if (aWidget.type == "custom") {
     if (aWidget.onBuild) {
       node = aWidget.onBuild(aDocument);
     }
     if (
       !node ||
       !aDocument.defaultView.XULElement.isInstance(node) ||
       (aWidget.viewId && !node.viewButton)
     ) {
       lazy.log.error(
         "Custom widget with id " +
           aWidget.id +
           " does not return a valid node"
       );
     }
     // A custom widget can define a viewId for the panel and a viewButton
     // property for the panel anchor.  With that, it will be treated as a view
     // type where necessary to hook up the view panel.
     if (aWidget.viewId) {
       button = node.viewButton;
     }
   }
   // Button and view widget types, plus custom widgets that have a viewId and thus a button.
   if (button || aWidget.type != "custom") {
     if (
       aWidget.onBeforeCreated &&
       aWidget.onBeforeCreated(aDocument) === false
     ) {
       return null;
     }

     if (!button) {
       button = aDocument.createXULElement("toolbarbutton");
       node = button;
     }
     button.classList.add("toolbarbutton-1");
     button.setAttribute("delegatesanchor", "true");

     let viewbutton = null;
     if (aWidget.type == "button-and-view") {
       button.setAttribute("id", aWidget.id + "-button");
       let dropmarker = aDocument.createXULElement("toolbarbutton");
       dropmarker.setAttribute("id", aWidget.id + "-dropmarker");
       dropmarker.setAttribute("delegatesanchor", "true");
       dropmarker.classList.add(
         "toolbarbutton-1",
         "toolbarbutton-combined-buttons-dropmarker"
       );
       node = aDocument.createXULElement("toolbaritem");
       node.classList.add("toolbaritem-combined-buttons");
       node.append(button, dropmarker);
       viewbutton = dropmarker;
     } else if (aWidget.viewId) {
       // Also set viewbutton for anything with a view
       viewbutton = button;
     }

     node.setAttribute("id", aWidget.id);
     node.setAttribute("widget-id", aWidget.id);
     node.setAttribute("widget-type", aWidget.type);
     node.toggleAttribute("disabled", !!aWidget.disabled);
     node.setAttribute("removable", aWidget.removable);
     node.setAttribute("overflows", aWidget.overflows);
     if (aWidget.tabSpecific) {
       node.setAttribute("tabspecific", aWidget.tabSpecific);
     }
     if (aWidget.locationSpecific) {
       node.setAttribute("locationspecific", aWidget.locationSpecific);
     }
     if (aWidget.keepBroadcastAttributesWhenCustomizing) {
       node.setAttribute(
         "keepbroadcastattributeswhencustomizing",
         aWidget.keepBroadcastAttributesWhenCustomizing
       );
     }

     let shortcut;
     if (aWidget.shortcutId) {
       let keyEl = aDocument.getElementById(aWidget.shortcutId);
       if (keyEl) {
         shortcut = lazy.ShortcutUtils.prettifyShortcut(keyEl);
       } else {
         lazy.log.error(
           "Key element with id '" +
             aWidget.shortcutId +
             "' for widget '" +
             aWidget.id +
             "' not found!"
         );
       }
     }

     if (aWidget.l10nId) {
       aDocument.l10n.setAttributes(node, aWidget.l10nId);
       if (button != node) {
         // This is probably a "button-and-view" widget, such as the Profiler
         // button. In that case, "node" is the "toolbaritem" container, and
         // "button" the main button (see above).
         // In this case, the values on the "node" is used in the Customize
         // view, as well as the tooltips over both buttons; the values on the
         // "button" are used in the overflow menu.
         aDocument.l10n.setAttributes(button, aWidget.l10nId);
       }

       if (shortcut) {
         node.setAttribute("data-l10n-args", JSON.stringify({ shortcut }));
         if (button != node) {
           // This is probably a "button-and-view" widget.
           button.setAttribute("data-l10n-args", JSON.stringify({ shortcut }));
         }
       }
     } else {
       node.setAttribute("label", this.getLocalizedProperty(aWidget, "label"));
       if (button != node) {
         // This is probably a "button-and-view" widget.
         button.setAttribute("label", node.getAttribute("label"));
       }

       let tooltip = this.getLocalizedProperty(
         aWidget,
         "tooltiptext",
         shortcut ? [shortcut] : []
       );
       if (tooltip) {
         node.setAttribute("tooltiptext", tooltip);
         if (button != node) {
           // This is probably a "button-and-view" widget.
           button.setAttribute("tooltiptext", tooltip);
         }
       }
     }

     let commandHandler = this.handleWidgetCommand.bind(this, aWidget, node);
     node.addEventListener("command", commandHandler);
     let clickHandler = this.handleWidgetClick.bind(this, aWidget, node);
     node.addEventListener("click", clickHandler);

     node.classList.add("chromeclass-toolbar-additional");

     // If the widget has a view, register a keypress handler because opening
     // a view with the keyboard has slightly different focus handling than
     // opening a view with the mouse. (When opened with the keyboard, the
     // first item in the view should be focused after opening.)
     if (viewbutton) {
       lazy.log.debug(
         "Widget " +
           aWidget.id +
           " has a view. Auto-registering event handlers."
       );

       if (aWidget.source == CustomizableUI.SOURCE_BUILTIN) {
         node.classList.add("subviewbutton-nav");
       }
     }

     if (aWidget.onCreated) {
       aWidget.onCreated(node);
     }
   }

   aWidget.instances.set(aDocument, node);
   return node;
 },

 /**
  * @see CustomizableUI.ensureSubviewListeners
  * @param {Element} viewNode
  */
 ensureSubviewListeners(viewNode) {
   if (viewNode._addedEventListeners) {
     return;
   }
   let viewId = viewNode.id;
   let widget = [...gPalette.values()].find(w => w.viewId == viewId);
   if (!widget) {
     return;
   }
   for (let eventName of kSubviewEvents) {
     let handler = "on" + eventName;
     if (typeof widget[handler] == "function") {
       viewNode.addEventListener(eventName, widget[handler]);
     }
   }
   viewNode._addedEventListeners = true;
   lazy.log.debug(
     "Widget " + widget.id + " showing and hiding event handlers set."
   );
 },

 /**
  * @see CustomizableUI.getLocalizedProperty
  * @param {string|object} aWidget
  * @param {string} aProp
  * @param {string[]} [aFormatArgs]
  * @param {string} [aDef]
  * @returns {string}
  */
 getLocalizedProperty(aWidget, aProp, aFormatArgs, aDef) {
   const kReqStringProps = ["label"];

   if (typeof aWidget == "string") {
     aWidget = gPalette.get(aWidget);
   }
   if (!aWidget) {
     throw new Error(
       "getLocalizedProperty was passed a non-widget to work with."
     );
   }
   let def, name;
   // Let widgets pass their own string identifiers or strings, so that
   // we can use strings which aren't the default (in case string ids change)
   // and so that non-builtin-widgets can also provide labels, tooltips, etc.
   if (aWidget[aProp] != null) {
     name = aWidget[aProp];
     // By using this as the default, if a widget provides a full string rather
     // than a string ID for localization, we will fall back to that string
     // and return that.
     def = aDef || name;
   } else {
     name = aWidget.id + "." + aProp;
     def = aDef || "";
   }
   if (aWidget.localized === false) {
     return def;
   }
   try {
     if (Array.isArray(aFormatArgs) && aFormatArgs.length) {
       return (
         lazy.gWidgetsBundle.formatStringFromName(name, aFormatArgs) || def
       );
     }
     return lazy.gWidgetsBundle.GetStringFromName(name) || def;
   } catch (ex) {
     // If an empty string was explicitly passed, treat it as an actual
     // value rather than a missing property.
     if (!def && (name != "" || kReqStringProps.includes(aProp))) {
       lazy.log.error("Could not localize property '" + name + "'.");
     }
   }
   return def;
 },

 /**
  * @see CustomizableUI.addShortcut
  * @param {Element} aShortcutNode
  * @param {Element|null} aTargetNode
  */
 addShortcut(aShortcutNode, aTargetNode = aShortcutNode) {
   // Detect if we've already been here before.
   if (aTargetNode.hasAttribute("shortcut")) {
     return;
   }

   // Use ownerGlobal.document to ensure we get the right doc even for
   // elements in template tags.
   let { document } = aShortcutNode.ownerGlobal;
   let shortcutId = aShortcutNode.getAttribute("key");
   let shortcut;
   if (shortcutId) {
     shortcut = document.getElementById(shortcutId);
   } else {
     let commandId = aShortcutNode.getAttribute("command");
     if (commandId) {
       shortcut = lazy.ShortcutUtils.findShortcut(
         document.getElementById(commandId)
       );
     }
   }
   if (!shortcut) {
     return;
   }

   aTargetNode.setAttribute(
     "shortcut",
     lazy.ShortcutUtils.prettifyShortcut(shortcut)
   );
 },

 /**
  * Executes a customizable UI widget's command handler to handle aEvent.
  *
  * @param {WidgetGroupWrapper|XULWidgetGroupWrapper} aWidget
  *   The customizable UI widget to call the command handler for.
  * @param {Element} aNode
  *   The node that the aEvent command event fired on.
  * @param {CommandEvent} aEvent
  *   The command event to handle.
  */
 doWidgetCommand(aWidget, aNode, aEvent) {
   if (aWidget.onCommand) {
     try {
       aWidget.onCommand.call(null, aEvent);
     } catch (e) {
       lazy.log.error(e);
     }
   } else {
     // XXXunf Need to think this through more, and formalize.
     Services.obs.notifyObservers(
       aNode,
       "customizedui-widget-command",
       aWidget.id
     );
   }
 },

 /**
  * Handles an event on a customizable UI widget node that has a panelview
  * associated with it. This routine will cause the panelview to be displayed.
  *
  * @param {WidgetGroupWrapper|XULWidgetGroupWrapper} aWidget
  *   The customizable UI widget to show the panelview for.
  * @param {Element} aNode
  *   The node that is handling the event that is causing the panelview to
  *   show.
  * @param {Event} aEvent
  *   The event that the node is handlign that is causing the panelview to
  *   show.
  */
 showWidgetView(aWidget, aNode, aEvent) {
   let ownerWindow = aNode.ownerGlobal;
   let area = this.getPlacementOfWidget(aNode.id).area;
   let areaType = CustomizableUI.getAreaType(area);
   let anchor = aNode;

   if (
     aWidget.disallowSubView &&
     (areaType == CustomizableUI.TYPE_PANEL ||
       aNode.hasAttribute("overflowedItem"))
   ) {
     // Close the containing panel (e.g. overflow), PanelUI will reopen.
     let wrapper = this.wrapWidget(aWidget.id).forWindow(ownerWindow);
     if (wrapper?.anchor) {
       this.hidePanelForNode(aNode);
       anchor = wrapper.anchor;
     }
   } else if (areaType != CustomizableUI.TYPE_PANEL) {
     let wrapper = this.wrapWidget(aWidget.id).forWindow(ownerWindow);

     let hasMultiView = !!aNode.closest("panelmultiview");
     if (!hasMultiView && wrapper?.anchor) {
       this.hidePanelForNode(aNode);
       anchor = wrapper.anchor;
     }
   }
   ownerWindow.PanelUI.showSubView(aWidget.viewId, anchor, aEvent);
 },

 /**
  * Handles a command event on a customizable ui widget node, and does the
  * action that best suits the type of widget.
  *
  * @param {WidgetGroupWrapper|XULWidgetGroupWrapper} aWidget
  *   The widget to handle the command event for.
  * @param {Element} aNode
  *   The node that the command event is being fired on.
  * @param {CommandEvent} aEvent
  *   The command event to be handled.
  */
 handleWidgetCommand(aWidget, aNode, aEvent) {
   // Note that aEvent can be a keypress event for widgets of type "view".
   lazy.log.debug("handleWidgetCommand");

   let action;
   if (aWidget.onBeforeCommand) {
     try {
       action = aWidget.onBeforeCommand.call(null, aEvent, aNode);
     } catch (e) {
       lazy.log.error(e);
     }
   }

   if (aWidget.type == "button" || action == "command") {
     this.doWidgetCommand(aWidget, aNode, aEvent);
   } else if (aWidget.type == "view" || action == "view") {
     this.showWidgetView(aWidget, aNode, aEvent);
   } else if (aWidget.type == "button-and-view") {
     // Do the command if we're in the toolbar and the button was clicked.
     // Otherwise, including when we have currently overflowed out of the
     // toolbar, open the view. There is no way to trigger the command while
     // the widget is in the panel, by design.
     let button = aNode.firstElementChild;
     let area = this.getPlacementOfWidget(aNode.id).area;
     let areaType = CustomizableUI.getAreaType(area);
     if (
       areaType == CustomizableUI.TYPE_TOOLBAR &&
       button.contains(aEvent.target) &&
       !aNode.hasAttribute("overflowedItem")
     ) {
       this.doWidgetCommand(aWidget, aNode, aEvent);
     } else {
       this.showWidgetView(aWidget, aNode, aEvent);
     }
   }
 },

 /**
  * Handles a click event on a customizable ui widget node, and redirects to
  * the widgets onClick event handler, if such a handler exists.
  *
  * @param {WidgetGroupWrapper|XULWidgetGroupWrapper} aWidget
  *   The widget to call the onClick event handler for if such a handler
  *   exists. If the handler does not exist, nothing is called.
  * @param {Element} aNode
  *   The node that fired the click event.
  * @param {MouseEvent} aEvent
  *   The click event to be handled.
  */
 handleWidgetClick(aWidget, aNode, aEvent) {
   lazy.log.debug("handleWidgetClick");
   if (aWidget.onClick) {
     try {
       aWidget.onClick.call(null, aEvent);
     } catch (e) {
       console.error(e);
     }
   } else {
     // XXXunf Need to think this through more, and formalize.
     Services.obs.notifyObservers(
       aNode,
       "customizedui-widget-click",
       aWidget.id
     );
   }
 },

 /**
  * Returns the closest <xul:panel> element to aNode in its ancestry, or null
  * if no such node can be found.
  *
  * @param {Element} aNode
  *   The node to check the ancestry for.
  * @returns {Element|null}
  */
 _getPanelForNode(aNode) {
   return aNode.closest("panel");
 },

 /**
  * If people put things in the panel which need more than single-click
  * interaction, we don't want to close it. Right now we check for text inputs
  * and menu buttons. We also check for being outside of any
  * toolbaritem/toolbarbutton, ie on a blank part of the menu, or on another
  * menu (like a context menu inside the panel).
  *
  * So this returns true if the event being handled is on one of these
  * interactive things that should NOT result in the associated panel closing.
  *
  * @param {Event} aEvent
  *   The event that is occurring that we're evaluating.
  * @returns {boolean}
  *   True if the event occurred on an item we consider "interactive" such
  *   that the enclosing panel should remain open. False if the panel should
  *   close.
  */
 _isOnInteractiveElement(aEvent) {
   let panel = this._getPanelForNode(aEvent.currentTarget);
   // This can happen in e.g. customize mode. If there's no panel,
   // there's clearly nothing for us to close; pretend we're interactive.
   if (!panel) {
     return true;
   }

   function getNextTarget(target) {
     if (target.nodeType == target.DOCUMENT_NODE) {
       if (!target.defaultView) {
         // Err, we're done.
         return null;
       }
       // Find containing browser or iframe element in the parent doc.
       return target.defaultView.docShell.chromeEventHandler;
     }
     // Skip any parent shadow roots
     return target.parentNode?.host?.parentNode || target.parentNode;
   }

   // While keeping track of that, we go from the original target back up,
   // to the panel if we have to. We bail as soon as we find an input,
   // a toolbarbutton/item, or a menuItem.
   for (
     let target = aEvent.originalTarget;
     target && target != panel;
     target = getNextTarget(target)
   ) {
     if (target.nodeType == target.DOCUMENT_NODE) {
       // Skip out of iframes etc:
       continue;
     }

     // Skip out of shadow roots
     if (
       target.nodeType == target.DOCUMENT_FRAGMENT_NODE &&
       target.containingShadowRoot == target
     ) {
       continue;
     }

     // Break out of the loop immediately for disabled items, as we need to
     // keep the menu open in that case.
     if (target.getAttribute("disabled") == "true") {
       return true;
     }

     let tagName = target.localName;
     if (tagName == "input" || tagName == "searchbar") {
       return true;
     }
     if (tagName == "toolbaritem" || tagName == "toolbarbutton") {
       // If we are in a type="menu" toolbarbutton, we'll now interact with
       // the menu.
       return target.getAttribute("type") == "menu";
     }
     if (tagName == "menuitem") {
       // If we're in a nested menu we don't need to close this panel.
       return true;
     }
   }

   // We don't know what we interacted with, assume interactive.
   return true;
 },

 /**
  * Finds the associated panel (if any) enclosing a given element, and
  * closes it.
  *
  * @param {Element} aNode
  *   The node to close the panel ancestor for.
  */
 hidePanelForNode(aNode) {
   let panel = this._getPanelForNode(aNode);
   if (panel) {
     lazy.PanelMultiView.hidePopup(panel);
   }
 },

 /**
  * For an event that occurs for a node within a panel, this routine will
  * check to see if that event should cause the panel to close.
  *
  * @param {Event} aEvent
  *   The event that is being fired on the node. This could be a keyboard,
  *   mouse or command event, for example.
  */
 maybeAutoHidePanel(aEvent) {
   let eventType = aEvent.type;
   if (eventType == "keypress" && aEvent.keyCode != aEvent.DOM_VK_RETURN) {
     return;
   }

   if (eventType == "click" && aEvent.button != 0) {
     return;
   }

   // We don't check preventDefault - it makes sense that this was prevented,
   // but we probably still want to close the panel. If consumers don't want
   // this to happen, they should specify the closemenu attribute.
   if (eventType != "command" && this._isOnInteractiveElement(aEvent)) {
     return;
   }

   // We can't use event.target because we might have passed an anonymous
   // content boundary as well, and so target points to the outer element in
   // that case. Unfortunately, this means we get anonymous child nodes instead
   // of the real ones, so looking for the 'stoooop, don't close me' attributes
   // is more involved.
   let target = aEvent.originalTarget;
   while (target.parentNode && target.localName != "panel") {
     if (
       target.getAttribute("closemenu") == "none" ||
       target.getAttribute("widget-type") == "view" ||
       target.getAttribute("widget-type") == "button-and-view" ||
       target.hasAttribute("view-button-id")
     ) {
       return;
     }

     target = target.parentNode;

     // If we reached the shadow boundry, let's cross it while we head up
     // the tree.
     if (ShadowRoot.isInstance(target)) {
       target = target.host;
     }
   }

   // If we get here, we can actually hide the popup:
   this.hidePanelForNode(aEvent.target);
 },

 /**
  * @see CustomizableUI.getUnusedWidgets
  * @param {DOMElement} aWindowPalette
  * @returns {Array<WidgetGroupWrapper|XULWidgetGroupWrapper>}
  */
 getUnusedWidgets(aWindowPalette) {
   let window = aWindowPalette.ownerGlobal;
   let isWindowPrivate = lazy.PrivateBrowsingUtils.isWindowPrivate(window);
   // We use a Set because there can be overlap between the widgets in
   // gPalette and the items in the palette, especially after the first
   // customization, since programmatically generated widgets will remain
   // in the toolbox palette.
   let widgets = new Set();

   // It's possible that some widgets have been defined programmatically and
   // have not been overlayed into the palette. We can find those inside
   // gPalette.
   for (let [id, widget] of gPalette) {
     if (!widget.currentArea) {
       if (
         (isWindowPrivate && widget.showInPrivateBrowsing) ||
         (!isWindowPrivate && !widget.hideInNonPrivateBrowsing)
       ) {
         widgets.add(id);
       }
     }
   }

   lazy.log.debug("Iterating the actual nodes of the window palette");
   for (let node of aWindowPalette.children) {
     lazy.log.debug("In palette children: " + node.id);
     if (node.id && !this.getPlacementOfWidget(node.id)) {
       widgets.add(node.id);
     }
   }

   return [...widgets];
 },

 /**
  * @see CustomizableUI.getPlacementOfWidget
  * @param {string} aWidgetId
  * @param {boolean} [aOnlyRegistered=true]
  * @param {boolean} [aDeadAreas=false]
  * @returns {CustomizableUIPlacementInfo|null}
  */
 getPlacementOfWidget(aWidgetId, aOnlyRegistered, aDeadAreas) {
   if (aOnlyRegistered && !this.widgetExists(aWidgetId)) {
     return null;
   }

   for (let [area, placements] of gPlacements) {
     if (!gAreas.has(area) && !aDeadAreas) {
       continue;
     }
     let index = placements.indexOf(aWidgetId);
     if (index != -1) {
       return { area, position: index };
     }
   }

   return null;
 },

 /**
  * Check for the current existance of a widget by ID.
  *
  * @see CustomizableUIInternal.isSpecialWidget
  * @param {string} aWidgetId
  * @returns {boolean}
  *   Returns true if the widget ID belongs to a widget that is registered or
  *   is a "special" widget (see isSpecialWidget). This will return false for
  *   widget IDs belonging to widgets we have seen in the past, but are no
  *   longer registered.
  */
 widgetExists(aWidgetId) {
   if (gPalette.has(aWidgetId) || this.isSpecialWidget(aWidgetId)) {
     return true;
   }

   // Destroyed API widgets are in gSeenWidgets, but not in gPalette:
   // If it's not in gPalette, it doesn't exist.
   if (gSeenWidgets.has(aWidgetId)) {
     return false;
   }

   // We're assuming XUL widgets always exist, as it's much harder to check,
   // and checking would be much more error prone.
   return true;
 },

 /**
  * @see CustomizableUI.addWidgetToArea
  * @param {string} aWidgetId
  * @param {string} aArea
  * @param {number} aPosition
  * @param {boolean} [aInitialAdd=false]
  *   True if this is the first time the widget is being added to the area
  *   for the first time during initialization, or after a state reset.
  */
 addWidgetToArea(aWidgetId, aArea, aPosition, aInitialAdd = false) {
   if (aArea == CustomizableUI.AREA_NO_AREA) {
     throw new Error(
       "AREA_NO_AREA is only used as an argument for " +
         "canWidgetMoveToArea. Use removeWidgetFromArea instead."
     );
   }
   if (!gAreas.has(aArea)) {
     throw new Error("Unknown customization area: " + aArea);
   }

   // Hack: don't want special widgets in the panel (need to check here as well
   // as in canWidgetMoveToArea because the menu panel is lazy):
   if (
     gAreas.get(aArea).get("type") == CustomizableUI.TYPE_PANEL &&
     this.isSpecialWidget(aWidgetId)
   ) {
     return;
   }

   // If this is a lazy area that hasn't been restored yet, we can't yet modify
   // it - would would at least like to add to it. So we keep track of it in
   // gFuturePlacements,  and use that to add it when restoring the area. We
   // throw away aPosition though, as that can only be bogus if the area hasn't
   // yet been restorted (caller can't possibly know where its putting the
   // widget in relation to other widgets).
   if (this.isAreaLazy(aArea)) {
     gFuturePlacements.get(aArea).add(aWidgetId);
     return;
   }

   if (this.isSpecialWidget(aWidgetId)) {
     aWidgetId = this.ensureSpecialWidgetId(aWidgetId);
   }

   let oldPlacement = this.getPlacementOfWidget(aWidgetId, false, true);
   if (oldPlacement && oldPlacement.area == aArea) {
     this.moveWidgetWithinArea(aWidgetId, aPosition);
     return;
   }

   // Do nothing if the widget is not allowed to move to the target area.
   if (!this.canWidgetMoveToArea(aWidgetId, aArea)) {
     return;
   }

   if (oldPlacement) {
     this.removeWidgetFromArea(aWidgetId);
   }

   if (!gPlacements.has(aArea)) {
     gPlacements.set(aArea, [aWidgetId]);
     aPosition = 0;
   } else {
     let placements = gPlacements.get(aArea);
     if (typeof aPosition != "number") {
       aPosition = placements.length;
     }
     if (aPosition < 0) {
       aPosition = 0;
     }
     placements.splice(aPosition, 0, aWidgetId);
   }

   let widget = gPalette.get(aWidgetId);
   if (widget) {
     widget.currentArea = aArea;
     widget.currentPosition = aPosition;
   }

   // We initially set placements with addWidgetToArea, so in that case
   // we don't consider the area "dirtied".
   if (!aInitialAdd) {
     gDirtyAreaCache.add(aArea);
   }

   gDirty = true;
   this.saveState();

   this.notifyListeners("onWidgetAdded", aWidgetId, aArea, aPosition);
 },

 /**
  * @see CustomizableUI.removeWidgetFromArea
  * @param {string} aWidgetId
  */
 removeWidgetFromArea(aWidgetId) {
   let oldPlacement = this.getPlacementOfWidget(aWidgetId, false, true);
   if (!oldPlacement) {
     return;
   }

   if (!this.isWidgetRemovable(aWidgetId)) {
     return;
   }

   let placements = gPlacements.get(oldPlacement.area);
   let position = placements.indexOf(aWidgetId);
   if (position != -1) {
     placements.splice(position, 1);
   }

   let widget = gPalette.get(aWidgetId);
   if (widget) {
     widget.currentArea = null;
     widget.currentPosition = null;
   }

   gDirty = true;
   this.saveState();
   gDirtyAreaCache.add(oldPlacement.area);

   // If we're in vertical tabs, ensure we don't restore the widget when we toggle back
   // to horizontal tabs.
   if (!gInBatchStack && CustomizableUI.verticalTabsEnabled) {
     if (oldPlacement.area == CustomizableUI.AREA_TABSTRIP) {
       this.deleteWidgetInSavedHorizontalTabStripState(aWidgetId);
     } else if (
       oldPlacement.area == CustomizableUI.AREA_NAVBAR &&
       this.getSavedHorizontalSnapshotState().includes(aWidgetId)
     ) {
       this.deleteWidgetInSavedHorizontalTabStripState(aWidgetId);
       this.deleteWidgetInSavedNavBarWhenVerticalTabsState(aWidgetId);
     }
   }

   this.notifyListeners("onWidgetRemoved", aWidgetId, oldPlacement.area);
 },

 /**
  * @see CustomizableUI.moveWidgetWithinArea
  * @param {string} aWidgetId
  * @param {number} aPosition
  */
 moveWidgetWithinArea(aWidgetId, aPosition) {
   let oldPlacement = this.getPlacementOfWidget(aWidgetId);
   if (!oldPlacement) {
     return;
   }

   let placements = gPlacements.get(oldPlacement.area);
   if (typeof aPosition != "number") {
     aPosition = placements.length;
   } else if (aPosition < 0) {
     aPosition = 0;
   } else if (aPosition > placements.length) {
     aPosition = placements.length;
   }

   let widget = gPalette.get(aWidgetId);
   if (widget) {
     widget.currentPosition = aPosition;
     widget.currentArea = oldPlacement.area;
   }

   if (aPosition == oldPlacement.position) {
     return;
   }

   placements.splice(oldPlacement.position, 1);
   // If we just removed the item from *before* where it is now added,
   // we need to compensate the position offset for that:
   if (oldPlacement.position < aPosition) {
     aPosition--;
   }
   placements.splice(aPosition, 0, aWidgetId);

   gDirty = true;
   gDirtyAreaCache.add(oldPlacement.area);

   this.saveState();

   this.notifyListeners(
     "onWidgetMoved",
     aWidgetId,
     oldPlacement.area,
     oldPlacement.position,
     aPosition
   );
 },

 /**
  * Returns the horizontal tab strip's placements state that was saved the
  * last time we switched to vertical tabs mode. This state is an array of
  * widget IDs that had been in the tab strip prior to switching to vertical
  * tabs.
  *
  * @returns {string[]}
  */
 getSavedHorizontalSnapshotState() {
   let state = [];
   let prefValue = lazy.horizontalPlacementsPref;
   if (prefValue) {
     try {
       state = JSON.parse(prefValue);
     } catch (e) {
       lazy.log.warn(
         `Failed to parse value of ${kPrefCustomizationHorizontalTabstrip}`,
         e
       );
     }
   }
   return state;
 },

 /**
  * Returns the vertical tab strip's placements state that was saved the
  * last time we switched to horizontal tabs mode. This state is an array of
  * widget IDs that had been in the vertical tab strip prior to switching to
  * horizontal tabs.
  *
  * @returns {string[]}
  */
 getSavedVerticalSnapshotState() {
   let state = [];
   let prefValue = lazy.verticalPlacementsPref;
   if (prefValue) {
     try {
       state = JSON.parse(prefValue);
     } catch (e) {
       lazy.log.warn(
         `Failed to parse value of ${kPrefCustomizationNavBarWhenVerticalTabs}`,
         e
       );
     }
   }
   return state;
 },

 /**
  * Loads the saved customization state objects from preferences or sets them
  * to their defaults if no such state can be found.
  *
  * Note that this does not populate gPlacements, which is done lazily.
  */
 loadSavedState() {
   let state = Services.prefs.getCharPref(kPrefCustomizationState, "");
   if (!state) {
     lazy.log.debug("No saved state found");
     // Nothing has been customized, so silently fall back to the defaults.
     return;
   }
   try {
     gSavedState = JSON.parse(state);
     if (typeof gSavedState != "object" || gSavedState === null) {
       throw new Error("Invalid saved state");
     }
   } catch (e) {
     Services.prefs.clearUserPref(kPrefCustomizationState);
     gSavedState = {};
     lazy.log.debug(
       "Error loading saved UI customization state, falling back to defaults."
     );
   }

   if (!("placements" in gSavedState)) {
     gSavedState.placements = {};
   }

   if (!("currentVersion" in gSavedState)) {
     gSavedState.currentVersion = 0;
   }

   if (!("currentVersionBaseBrowser" in gSavedState)) {
     gSavedState.currentVersionBaseBrowser = 0;
   }

   if (!("currentVersionTorBrowser" in gSavedState)) {
     gSavedState.currentVersionTorBrowser = 0;
   }

   gSeenWidgets = new Set(gSavedState.seen || []);
   gDirtyAreaCache = new Set(gSavedState.dirtyAreaCache || []);
   gNewElementCount = gSavedState.newElementCount || 0;
 },

 /**
  * Restores the placements of widgets within an area with ID aAreaId from
  * saved state, or sets the default placements if no such saved state exists.
  * This should be called during area registration, or after a state reset.
  *
  * @param {string} aAreaId
  *   The ID of the area to restore the state for.
  */
 restoreStateForArea(aAreaId) {
   let placementsPreexisted = gPlacements.has(aAreaId);

   this.beginBatchUpdate();
   try {
     gRestoring = true;

     let restored = false;
     if (placementsPreexisted) {
       lazy.log.debug(
         "Restoring " + aAreaId + " from pre-existing placements"
       );
       for (let [position, id] of gPlacements.get(aAreaId).entries()) {
         this.moveWidgetWithinArea(id, position);
       }
       gDirty = false;
       restored = true;
     } else {
       gPlacements.set(aAreaId, []);
     }

     if (!restored && gSavedState && aAreaId in gSavedState.placements) {
       lazy.log.debug("Restoring " + aAreaId + " from saved state");
       let placements = gSavedState.placements[aAreaId];
       for (let id of placements) {
         this.addWidgetToArea(id, aAreaId);
       }
       gDirty = false;
       restored = true;
     }

     if (!restored) {
       lazy.log.debug("Restoring " + aAreaId + " from default state");
       let defaults = gAreas.get(aAreaId).get("defaultPlacements");
       if (
         CustomizableUI.verticalTabsEnabled &&
         gAreas.get(aAreaId).has("verticalTabsDefaultPlacements")
       ) {
         lazy.log.debug(
           "Using verticalTabsDefaultPlacements to restore " + aAreaId
         );
         defaults = gAreas.get(aAreaId).get("verticalTabsDefaultPlacements");
       }

       if (defaults) {
         for (let id of defaults) {
           this.addWidgetToArea(id, aAreaId, null, true);
         }
       }
       gDirty = false;
     }

     // Finally, add widgets to the area that were added before the it was able
     // to be restored. This can occur when add-ons register widgets for a
     // lazily-restored area before it's been restored.
     if (gFuturePlacements.has(aAreaId)) {
       let areaPlacements = gPlacements.get(aAreaId);
       for (let id of gFuturePlacements.get(aAreaId)) {
         if (areaPlacements.includes(id)) {
           continue;
         }
         this.addWidgetToArea(id, aAreaId);
       }
       gFuturePlacements.delete(aAreaId);
     }

     lazy.log.debug(
       "Placements for " +
         aAreaId +
         ":\n\t" +
         gPlacements.get(aAreaId).join("\n\t")
     );

     gRestoring = false;
   } finally {
     this.endBatchUpdate();
   }
 },

 /**
  * Adds widgets to the AREA_TABSTRIP area that were saved when switching away
  * from horizontal tabs. This will effectively rebuild AREA_TABSTRIP to
  * match the state in savedPlacements, and then clear the saved horizontal
  * tab state.
  *
  * @param {string[]} [savedPlacements=this.getSavedHorizontalSnapshotState()]
  *   The array of widget IDs to add to the AREA_TABSTRIP, in order. If this
  *   set of placements doesn't include "tabbrowser-tabs" for some reason, the
  *   whole set of placements is ignored and the tab strip is reset to the
  *   defaults.
  * @param {boolean} [isInitializing = false]
  *   True if the horizontal tab strip is being rebuilt during CustomizableUI
  *   initialization as opposed to via a pref-flip at runtime.
  */
 restoreSavedHorizontalTabStripState(
   savedPlacements = this.getSavedHorizontalSnapshotState(),
   isInitializing = false
 ) {
   const tabstripAreaId = CustomizableUI.AREA_TABSTRIP;
   lazy.log.debug(
     `restoreSavedHorizontalTabStripState, ${kPrefCustomizationHorizontalTabstrip} contained:`,
     savedPlacements
   );
   // If there's no saved state, or it doesn't pass the sniff test, use
   // default placements instead
   if (!savedPlacements.includes("tabbrowser-tabs")) {
     savedPlacements = gAreas.get(tabstripAreaId).get("defaultPlacements");
     lazy.log.debug(`Using defaultPlacements for ${tabstripAreaId}`);
   }

   lazy.log.debug(
     `Replacing existing placements: ${gPlacements.get(
       tabstripAreaId
     )}, with ${savedPlacements}.`
   );

   // Restore the tabstrip to either saved or default placements
   this.beginBatchUpdate();
   for (let [index, widgetId] of savedPlacements.entries()) {
     this.addWidgetToArea(widgetId, tabstripAreaId, index, isInitializing);
   }

   // Wipe the pref now that state is restored
   Services.prefs.clearUserPref(kPrefCustomizationHorizontalTabstrip);

   // The vertical tabstrip area is supposed to be empty when we switch back to horizontal
   if (gPlacements.get(CustomizableUI.AREA_VERTICAL_TABSTRIP)?.length) {
     lazy.log.warn(
       `Widgets remain in ${CustomizableUI.AREA_VERTICAL_TABSTRIP}:`,
       gPlacements.get(CustomizableUI.AREA_VERTICAL_TABSTRIP)
     );
   }

   this.endBatchUpdate();
 },

 /**
  * Looks for a widget with a matching ID to aWidgetId within the saved
  * horizontal tab strip state, and then deletes it from that state before
  * saving that state to preferences.
  *
  * @see CustomizableUIInternal.saveHorizontalTabStripState
  * @param {string} aWidgetId
  *   The ID of the widget to remove from the saved horizontal tabstrip state.
  */
 deleteWidgetInSavedHorizontalTabStripState(aWidgetId) {
   const savedPlacements = this.getSavedHorizontalSnapshotState();
   let position = savedPlacements.indexOf(aWidgetId);
   if (position != -1) {
     savedPlacements.splice(position, 1);
     this.saveHorizontalTabStripState(savedPlacements);
   }
 },

 /**
  * Looks for a widget with a matching ID to aWidgetId within the navbar state
  * that was saved when switching away from vertical tabs mode, and then
  * deletes it from that state before saving that state to preferences.
  *
  * @see CustomizableUIInternal.saveNavBarWhenVerticalTabsState
  * @param {string} aWidgetId
  *   The ID of the widget to remove from the saved navbar state.
  */
 deleteWidgetInSavedNavBarWhenVerticalTabsState(aWidgetId) {
   const savedPlacements = this.getSavedVerticalSnapshotState();
   let position = savedPlacements.indexOf(aWidgetId);
   if (position != -1) {
     savedPlacements.splice(position, 1);
     this.saveNavBarWhenVerticalTabsState(savedPlacements);
   }
 },

 /**
  * Takes the current set of widgets placed within the horizontal tab strip
  * and saves their IDs to a preference. This is used just before switching
  * to vertical tabs mode (which moves some widgets around), and the saved
  * state is used to restore the horizontal tab mode state of the tab
  * strip.
  *
  * @param {string[]} [placements=[]]
  *   The placements within the horizontal tab strip to save to preferences.
  *   If this is the empty array, this method will use the current placements
  *   of the tab strip automatically.
  */
 saveHorizontalTabStripState(placements = []) {
   if (!placements.length) {
     placements = this.getAreaPlacementsForSaving(
       CustomizableUI.AREA_TABSTRIP
     );
   }
   let serialized = JSON.stringify(placements, this.serializerHelper);
   lazy.log.debug("Saving horizontal tabstrip state.", serialized);
   Services.prefs.setCharPref(
     kPrefCustomizationHorizontalTabstrip,
     serialized
   );
 },

 /**
  * Takes the current set of widgets placed within the navbar while in
  * vertical tabs mode, and and saves their IDs to a preference. This is used
  * just before switching to horizontal tabs mode (which moves some widgets
  * around), and the saved state is used to restore the navbar's widget
  * placements if the user switches back to vertical tabs.
  *
  * @param {string[]} [placements=[]]
  *   The placements within the navbar to save to preferences. If this is the
  *   empty array, this method will use the current placements of the navbar
  *   automatically.
  */
 saveNavBarWhenVerticalTabsState(placements = []) {
   if (!placements.length) {
     placements = this.getAreaPlacementsForSaving(CustomizableUI.AREA_NAVBAR);
   }
   let serialized = JSON.stringify(placements, this.serializerHelper);
   lazy.log.debug("Saving vertical navbar state.", serialized);
   Services.prefs.setCharPref(
     kPrefCustomizationNavBarWhenVerticalTabs,
     serialized
   );
 },

 /**
  * Returns the placements of widgets within a known area, regardless of
  * whether or not the area has already been built, or is still registered.
  * This means that we can get the placements for an area that was registered
  * in the past, is no longer registered, but still exists within the
  * saved state.
  *
  * @param {string} aAreaId
  *   The ID of the area to get the placements for.
  * @returns {string[]|undefined}
  *   Returns the placements for the area, or undefined if the area is not
  *   recognized.
  */
 getAreaPlacementsForSaving(aAreaId) {
   // An early call to saveState can occur before all the lazy-area building is complete
   let placements;
   if (this.isAreaLazy(aAreaId) && gFuturePlacements.get(aAreaId)?.size) {
     placements = [...gFuturePlacements.get(aAreaId)];
   } else if (gPlacements.has(aAreaId)) {
     placements = gPlacements.get(aAreaId);
   }

   // Merge in previously saved areas if not present in gPlacements/gFuturePlacements.
   // This way, state is still persisted for e.g. temporarily disabled
   // add-ons - see bug 989338.
   if (!placements && gSavedState && gSavedState.placements?.[aAreaId]) {
     placements = gSavedState.placements[aAreaId];
   }
   lazy.log.debug(
     `getAreaPlacementsForSaving for area: ${aAreaId}, gPlacements for area: ${gPlacements.get(
       aAreaId
     )}, returning: ${placements}`
   );
   return placements;
 },

 /**
  * Saves the current state of all customizable areas to preferences.
  */
 saveState() {
   if (gInBatchStack || !gDirty) {
     return;
   }
   // Clone because we want to modify this map:
   let placements = new Map();
   // Because of Bug 989338 and the risk of having area ids that aren't yet registered,
   // we collect the areas from both gPlacements and gSavedState rather than gAreas.
   let allAreaIds = new Set([...gPlacements.keys()]);
   if (gSavedState?.placements) {
     for (let area of Object.keys(gSavedState.placements)) {
       allAreaIds.add(area);
     }
   }
   for (let area of allAreaIds) {
     placements.set(area, this.getAreaPlacementsForSaving(area));
   }
   let state = {
     placements,
     seen: gSeenWidgets,
     dirtyAreaCache: gDirtyAreaCache,
     currentVersion: kVersion,
     currentVersionBaseBrowser: kVersionBaseBrowser,
     currentVersionTorBrowser: kVersionTorBrowser,
     newElementCount: gNewElementCount,
   };

   lazy.log.debug("Saving state.");
   let serialized = JSON.stringify(state, this.serializerHelper);
   lazy.log.debug("State saved as: " + serialized);
   Services.prefs.setCharPref(kPrefCustomizationState, serialized);
   gDirty = false;
 },

 /**
  * This helper is passed to JSON.stringify when serializing the current
  * customizable areas to preferences in saveState(). This does the work
  * of serializing Map and Sets to objects and arrays, respectively.
  *
  * @see CustomizableUIInternal.saveState()
  * @param {string|symbol} _aKey
  * @param {any} aValue
  * @returns {any}
  */
 serializerHelper(_aKey, aValue) {
   if (typeof aValue == "object" && aValue.constructor.name == "Map") {
     let result = {};
     for (let [mapKey, mapValue] of aValue) {
       result[mapKey] = mapValue;
     }
     return result;
   }

   if (typeof aValue == "object" && aValue.constructor.name == "Set") {
     return [...aValue];
   }

   return aValue;
 },

 /**
  * @see CustomizableUI.beginBatchUpdate()
  */
 beginBatchUpdate() {
   gInBatchStack++;
 },

 /**
  * @see CustomizableUI.endBatchUpdate()
  * @param {boolean} aForceDirty
  */
 endBatchUpdate(aForceDirty) {
   gInBatchStack--;
   if (aForceDirty === true) {
     gDirty = true;
   }
   if (gInBatchStack == 0) {
     this.saveState();
   } else if (gInBatchStack < 0) {
     throw new Error(
       "The batch editing stack should never reach a negative number."
     );
   }
 },

 /**
  * @see CustomizableUI.addListener
  * @param {CustomizableUIListener} aListener
  */
 addListener(aListener) {
   gListeners.add(aListener);
 },

 /**
  * @see CustomizableUI.removeListener
  * @param {CustomizableUIListener} aListener
  */
 removeListener(aListener) {
   if (aListener == this) {
     return;
   }

   gListeners.delete(aListener);
 },

 /**
  * For any listeners registered via `addListener` or `removeListener`, this
  * calls the appropriate listener function for a particular CustomizableUI
  * event if it is defined on the listener, passing along the arguments.
  *
  * @param {string} aListenerName
  *   The name of the listener that should be called. This is a string
  *   identifier of something that can be listened for via a
  *   CustomizableUIListener - for example, "onWidgetCreated".
  * @param  {...any} aArgs
  *   The arguments to pass to the CustomizableUIListener function.
  */
 notifyListeners(aListenerName, ...aArgs) {
   if (gRestoring) {
     return;
   }

   for (let listener of gListeners) {
     try {
       if (typeof listener[aListenerName] == "function") {
         listener[aListenerName].apply(listener, aArgs);
       }
     } catch (e) {
       lazy.log.error(e + " -- " + e.fileName + ":" + e.lineNumber);
     }
   }
 },

 /**
  * Constructs a CustomEvent with the aEventType type that is bubbling and
  * cancelable, and includes the details passed on aDetails. This event is
  * then dispatched on the gNavToolbox in aWindow.
  *
  * @see CustomizableUIInternal.dispatchToolboxEvent
  * @param {string} aEventType
  *   The type of the CustomEvent to fire.
  * @param {any} aDetails
  *   The details to assign to the event being fired.
  * @param {DOMWindow} aWindow
  *   The browser window containing the gNavToolbox which will have the event
  *   dispatched on it.
  */
 _dispatchToolboxEventToWindow(aEventType, aDetails, aWindow) {
   let evt = new aWindow.CustomEvent(aEventType, {
     bubbles: true,
     cancelable: true,
     detail: aDetails,
   });
   aWindow.gNavToolbox.dispatchEvent(evt);
 },

 /**
  * Constructs a CustomEvent with the aEventType type that is bubbling and
  * cancelable, and includes the details passed on aDetails. This event is
  * then dispatched on the gNavToolbox in aWindow if one is provided. If no
  * window is provided, this is dispatched on the gNavToolbox for all
  * registered windows.
  *
  * @param {string} aEventType
  *   The type of the CustomEvent to fire.
  * @param {any} [aDetails={}]
  *   The details to assign to the event being fired.
  * @param {DOMWindow} [aWindow=null]
  *   The browser window containing the gNavToolbox which will have the event
  *   dispatched on it, or null to dispatch to all gNavToolbox elements in
  *   all registered windows.
  */
 dispatchToolboxEvent(aEventType, aDetails = {}, aWindow = null) {
   if (aWindow) {
     this._dispatchToolboxEventToWindow(aEventType, aDetails, aWindow);
     return;
   }
   for (let [win] of gBuildWindows) {
     this._dispatchToolboxEventToWindow(aEventType, aDetails, win);
   }
 },

 /**
  * @see CustomizableUI.createWidget
  * @param {CustomizableUICreateWidgetProperties} aProperties
  * @returns {string}
  *   The ID of the created widget.
  */
 createWidget(aProperties) {
   let widget = this.normalizeWidget(
     aProperties,
     CustomizableUI.SOURCE_EXTERNAL
   );
   // XXXunf This should probably throw.
   if (!widget) {
     lazy.log.error("unable to normalize widget");
     return undefined;
   }

   gPalette.set(widget.id, widget);

   // Clear our caches:
   gGroupWrapperCache.delete(widget.id);
   for (let [win] of gBuildWindows) {
     let cache = gSingleWrapperCache.get(win);
     if (cache) {
       cache.delete(widget.id);
     }
   }

   this.notifyListeners("onWidgetCreated", widget.id);

   if (widget.defaultArea) {
     let addToDefaultPlacements = false;
     let area = gAreas.get(widget.defaultArea);
     if (
       !CustomizableUI.isBuiltinToolbar(widget.defaultArea) &&
       widget.defaultArea != CustomizableUI.AREA_FIXED_OVERFLOW_PANEL
     ) {
       addToDefaultPlacements = true;
     }

     if (addToDefaultPlacements) {
       if (area.has("defaultPlacements")) {
         area.get("defaultPlacements").push(widget.id);
       } else {
         area.set("defaultPlacements", [widget.id]);
       }
     }
   }

   // Look through previously saved state to see if we're restoring a widget.
   let seenAreas = new Set();
   let widgetMightNeedAutoAdding = true;
   for (let [area] of gPlacements) {
     seenAreas.add(area);
     let areaIsRegistered = gAreas.has(area);
     let index = gPlacements.get(area).indexOf(widget.id);
     if (index != -1) {
       widgetMightNeedAutoAdding = false;
       if (areaIsRegistered) {
         widget.currentArea = area;
         widget.currentPosition = index;
       }
       break;
     }
   }

   // Also look at saved state data directly in areas that haven't yet been
   // restored. Can't rely on this for restored areas, as they may have
   // changed.
   if (widgetMightNeedAutoAdding && gSavedState) {
     for (let area of Object.keys(gSavedState.placements)) {
       if (seenAreas.has(area)) {
         continue;
       }

       let areaIsRegistered = gAreas.has(area);
       let index = gSavedState.placements[area].indexOf(widget.id);
       if (index != -1) {
         widgetMightNeedAutoAdding = false;
         if (areaIsRegistered) {
           widget.currentArea = area;
           widget.currentPosition = index;
         }
         break;
       }
     }
   }

   // If we're restoring the widget to it's old placement, fire off the
   // onWidgetAdded event - our own handler will take care of adding it to
   // any build areas.
   this.beginBatchUpdate();
   try {
     if (widget.currentArea) {
       this.notifyListeners(
         "onWidgetAdded",
         widget.id,
         widget.currentArea,
         widget.currentPosition
       );
     } else if (widgetMightNeedAutoAdding) {
       let autoAdd = Services.prefs.getBoolPref(
         kPrefCustomizationAutoAdd,
         true
       );

       // If the widget doesn't have an existing placement, and it hasn't been
       // seen before, then add it to its default area so it can be used.
       // If the widget is not removable, we *have* to add it to its default
       // area here.
       let canBeAutoAdded = autoAdd && !gSeenWidgets.has(widget.id);
       if (!widget.currentArea && (!widget.removable || canBeAutoAdded)) {
         if (widget.defaultArea) {
           if (this.isAreaLazy(widget.defaultArea)) {
             gFuturePlacements.get(widget.defaultArea).add(widget.id);
           } else {
             this.addWidgetToArea(widget.id, widget.defaultArea);
           }
         }
       }

       // Extension widgets cannot enter the customization palette, so if
       // at this point, we haven't found an area for them, move them into
       // AREA_ADDONS.
       if (
         !widget.currentArea &&
         CustomizableUI.isWebExtensionWidget(widget.id)
       ) {
         this.addWidgetToArea(widget.id, CustomizableUI.AREA_ADDONS);
       }
     }
   } finally {
     // Ensure we always have this widget in gSeenWidgets, and save
     // state in case this needs to be done here.
     gSeenWidgets.add(widget.id);
     this.endBatchUpdate(true);
   }

   this.notifyListeners(
     "onWidgetAfterCreation",
     widget.id,
     widget.currentArea
   );
   return widget.id;
 },

 /**
  * Creates the widgets that are defined statically within the browser in
  * CustomizableWidgets.
  *
  * @param {CustomizableUICreateWidgetProperties} aData
  */
 createBuiltinWidget(aData) {
   // This should only ever be called on startup, before any windows are
   // opened - so we know there's no build areas to handle. Also, builtin
   // widgets are expected to be (mostly) static, so shouldn't affect the
   // current placement settings.

   // This allows a widget to be both built-in by default but also able to be
   // destroyed and removed from the area based on criteria that may not be
   // available when the widget is created -- for example, because some other
   // feature in the browser supersedes the widget.
   let conditionalDestroyPromise = aData.conditionalDestroyPromise || null;
   delete aData.conditionalDestroyPromise;

   let widget = this.normalizeWidget(aData, CustomizableUI.SOURCE_BUILTIN);
   if (!widget) {
     lazy.log.error("Error creating builtin widget: " + aData.id);
     return;
   }

   lazy.log.debug("Creating built-in widget with id: " + widget.id);
   gPalette.set(widget.id, widget);

   if (conditionalDestroyPromise) {
     conditionalDestroyPromise.then(
       shouldDestroy => {
         if (shouldDestroy) {
           this.destroyWidget(widget.id);
           this.removeWidgetFromArea(widget.id);
         }
       },
       err => {
         console.error(err);
       }
     );
   }
 },

 /**
  * Returns true if the associated area will eventually lazily restore (but
  * hasn't yet).
  *
  * @param {string} aAreaId
  * @returns {boolean}
  */
 isAreaLazy(aAreaId) {
   if (gPlacements.has(aAreaId) || !gAreas.has(aAreaId)) {
     return false;
   }
   return gAreas.get(aAreaId).get("type") == CustomizableUI.TYPE_TOOLBAR;
 },

 /**
  * Given a set of CustomizableUICreateWidgetProperties, attempts to
  * create a "normalized" version of that object with default values where
  * aData failed to define values, as well as properly wrapped event handlers.
  *
  * @param {CustomizableUICreateWidgetProperties} aData
  * @param {string} aSource
  *   One of the CustomizableUI.SOURCE_* constants, for example
  *   CustomizableUI.SOURCE_EXTERNAL.
  * @returns {object}
  *   The normalized widget representation. Notably, the `implementation`
  *   property of this widget will point to the original aData structure.
  */
 normalizeWidget(aData, aSource) {
   let widget = {
     implementation: aData,
     source: aSource || CustomizableUI.SOURCE_EXTERNAL,
     instances: new Map(),
     currentArea: null,
     localized: true,
     removable: true,
     overflows: true,
     defaultArea: null,
     shortcutId: null,
     tabSpecific: false,
     locationSpecific: false,
     tooltiptext: null,
     l10nId: null,
     showInPrivateBrowsing: true,
     hideInNonPrivateBrowsing: false,
     _introducedInVersion: -1,
     _introducedByPref: null,
     keepBroadcastAttributesWhenCustomizing: false,
     disallowSubView: false,
     webExtension: false,
   };

   if (typeof aData.id != "string" || !/^[a-z0-9-_]{1,}$/i.test(aData.id)) {
     lazy.log.error("Given an illegal id in normalizeWidget: " + aData.id);
     return null;
   }

   delete widget.implementation.currentArea;
   widget.implementation.__defineGetter__(
     "currentArea",
     () => widget.currentArea
   );

   const kReqStringProps = ["id"];
   for (let prop of kReqStringProps) {
     if (typeof aData[prop] != "string") {
       lazy.log.error(
         "Missing required property '" +
           prop +
           "' in normalizeWidget: " +
           aData.id
       );
       return null;
     }
     widget[prop] = aData[prop];
   }

   const kOptStringProps = ["l10nId", "label", "tooltiptext", "shortcutId"];
   for (let prop of kOptStringProps) {
     if (typeof aData[prop] == "string") {
       widget[prop] = aData[prop];
     }
   }

   const kOptBoolProps = [
     "removable",
     "showInPrivateBrowsing",
     "hideInNonPrivateBrowsing",
     "overflows",
     "tabSpecific",
     "locationSpecific",
     "localized",
     "keepBroadcastAttributesWhenCustomizing",
     "disallowSubView",
     "webExtension",
   ];
   for (let prop of kOptBoolProps) {
     if (typeof aData[prop] == "boolean") {
       widget[prop] = aData[prop];
     }
   }

   // When we normalize builtin widgets, areas have not yet been registered:
   if (
     aData.defaultArea &&
     (aSource == CustomizableUI.SOURCE_BUILTIN ||
       gAreas.has(aData.defaultArea))
   ) {
     widget.defaultArea = aData.defaultArea;
   } else if (!widget.removable) {
     lazy.log.error(
       "Widget '" +
         widget.id +
         "' is not removable but does not specify " +
         "a valid defaultArea. That's not possible; it must specify a " +
         "valid defaultArea as well."
     );
     return null;
   }

   if ("type" in aData && gSupportedWidgetTypes.has(aData.type)) {
     widget.type = aData.type;
   } else {
     widget.type = "button";
   }

   widget.disabled = aData.disabled === true;

   if (aSource == CustomizableUI.SOURCE_BUILTIN) {
     widget._introducedInVersion = aData.introducedInVersion || 0;

     if (aData._introducedByPref) {
       widget._introducedByPref = aData._introducedByPref;
     }
   }

   this.wrapWidgetEventHandler("onBeforeCreated", widget);
   this.wrapWidgetEventHandler("onClick", widget);
   this.wrapWidgetEventHandler("onCreated", widget);
   this.wrapWidgetEventHandler("onDestroyed", widget);

   if (typeof aData.onBeforeCommand == "function") {
     widget.onBeforeCommand = aData.onBeforeCommand;
   }

   if (typeof aData.onCommand == "function") {
     widget.onCommand = aData.onCommand;
   }
   if (
     widget.type == "view" ||
     widget.type == "button-and-view" ||
     aData.viewId
   ) {
     if (typeof aData.viewId != "string") {
       lazy.log.error(
         "Expected a string for widget " +
           widget.id +
           " viewId, but got " +
           aData.viewId
       );
       return null;
     }
     widget.viewId = aData.viewId;

     this.wrapWidgetEventHandler("onViewShowing", widget);
     this.wrapWidgetEventHandler("onViewHiding", widget);
   }
   if (widget.type == "custom") {
     this.wrapWidgetEventHandler("onBuild", widget);
   }

   if (gPalette.has(widget.id)) {
     return null;
   }

   return widget;
 },

 /**
  * Given some widget definition object, forwards calls to functions with the
  * name aEventName to the underlying implementation objects copy of that
  * function.
  *
  * @param {string} aEventName
  *   The name of the function to redirect to the underlying implementations
  *   version of that same named function.
  * @param {object} aWidget
  *   A "normalized" widget definition as computed by `normalizeWidget()`.
  */
 wrapWidgetEventHandler(aEventName, aWidget) {
   if (typeof aWidget.implementation[aEventName] != "function") {
     aWidget[aEventName] = null;
     return;
   }
   aWidget[aEventName] = function (...aArgs) {
     try {
       // Don't copy the function to the normalized widget object, instead
       // keep it on the original object provided to the API so that
       // additional methods can be implemented and used by the event
       // handlers.
       return aWidget.implementation[aEventName].apply(
         aWidget.implementation,
         aArgs
       );
     } catch (e) {
       console.error(e);
       return undefined;
     }
   };
 },

 /**
  * @see CustomizableUI.destroyWidget
  * @param {string} aWidgetId
  */
 destroyWidget(aWidgetId) {
   let widget = gPalette.get(aWidgetId);
   if (!widget) {
     gGroupWrapperCache.delete(aWidgetId);
     for (let [window] of gBuildWindows) {
       let windowCache = gSingleWrapperCache.get(window);
       if (windowCache) {
         windowCache.delete(aWidgetId);
       }
     }
     return;
   }

   // Remove it from the default placements of an area if it was added there:
   if (widget.defaultArea) {
     let area = gAreas.get(widget.defaultArea);
     if (area) {
       let defaultPlacements = area.get("defaultPlacements");
       // We can assume this is present because if a widget has a defaultArea,
       // we automatically create a defaultPlacements array for that area.
       let widgetIndex = defaultPlacements.indexOf(aWidgetId);
       if (widgetIndex != -1) {
         defaultPlacements.splice(widgetIndex, 1);
       }
     }
   }

   // This will not remove the widget from gPlacements - we want to keep the
   // setting so the widget gets put back in it's old position if/when it
   // returns.
   for (let [window] of gBuildWindows) {
     let windowCache = gSingleWrapperCache.get(window);
     if (windowCache) {
       windowCache.delete(aWidgetId);
     }
     let widgetNode =
       window.document.getElementById(aWidgetId) ||
       window.gNavToolbox.palette.getElementsByAttribute("id", aWidgetId)[0];
     if (widgetNode) {
       let container = widgetNode.parentNode;
       this.notifyListeners(
         "onWidgetBeforeDOMChange",
         widgetNode,
         null,
         container,
         true
       );
       widgetNode.remove();
       this.notifyListeners(
         "onWidgetAfterDOMChange",
         widgetNode,
         null,
         container,
         true
       );
     }
     if (
       widget.type == "view" ||
       widget.type == "button-and-view" ||
       widget.viewId
     ) {
       let viewNode = window.document.getElementById(widget.viewId);
       if (viewNode) {
         for (let eventName of kSubviewEvents) {
           let handler = "on" + eventName;
           if (typeof widget[handler] == "function") {
             viewNode.removeEventListener(eventName, widget[handler]);
           }
         }
         viewNode._addedEventListeners = false;
       }
     }
     if (widgetNode && widget.onDestroyed) {
       widget.onDestroyed(window.document);
     }
   }

   gPalette.delete(aWidgetId);
   gGroupWrapperCache.delete(aWidgetId);

   this.notifyListeners("onWidgetDestroyed", aWidgetId);
 },

 /**
  * @see CustomizableUI.getCustomizeTargetForArea
  * @param {string} aArea
  * @param {DOMWindow} aWindow
  * @returns {Element}
  */
 getCustomizeTargetForArea(aArea, aWindow) {
   let buildAreaNodes = gBuildAreas.get(aArea);
   if (!buildAreaNodes) {
     return null;
   }

   for (let node of buildAreaNodes) {
     if (node.ownerGlobal == aWindow) {
       return this.getCustomizationTarget(node) || node;
     }
   }

   return null;
 },

 /**
  * @see CustomizableUI.reset()
  */
 reset() {
   gResetting = true;
   // CUI reset also implies resetting verticalTabs back to false.
   // We do this before the rest of the reset so widgets are reset to their non-vertical
   // positions.
   Services.prefs.setBoolPref("sidebar.verticalTabs", false);
   this._resetUIState();

   // Rebuild each registered area (across windows) to reflect the state that
   // was reset above.
   this._rebuildRegisteredAreas();

   for (let [widgetId, widget] of gPalette) {
     if (widget.source == CustomizableUI.SOURCE_EXTERNAL) {
       gSeenWidgets.add(widgetId);
     }
   }
   if (gSeenWidgets.size || gNewElementCount) {
     gDirty = true;
     this.saveState();
   }

   gResetting = false;
 },

 /**
  * Persists the current state to gUIStateBeforeReset (in order to temporarily
  * allow for undoing CustomizableUI resets) and then blows away the current
  * CustomizableUI state (including saved prefs) and sets them to their
  * defaults. This also rebuilds all of the registered areas to reflect the
  * defaults.
  */
 _resetUIState() {
   try {
     gUIStateBeforeReset.drawInTitlebar =
       Services.prefs.getIntPref(kPrefDrawInTitlebar);
     gUIStateBeforeReset.uiCustomizationState = Services.prefs.getCharPref(
       kPrefCustomizationState
     );
     gUIStateBeforeReset.uiDensity = Services.prefs.getIntPref(kPrefUIDensity);
     gUIStateBeforeReset.autoTouchMode =
       Services.prefs.getBoolPref(kPrefAutoTouchMode);
     gUIStateBeforeReset.currentTheme = gSelectedTheme;
     gUIStateBeforeReset.autoHideDownloadsButton = Services.prefs.getBoolPref(
       kPrefAutoHideDownloadsButton
     );
     gUIStateBeforeReset.newElementCount = gNewElementCount;
     gUIStateBeforeReset.sidebarPositionStart = Services.prefs.getBoolPref(
       kPrefSidebarPositionStartEnabled
     );
   } catch (e) {}

   Services.prefs.clearUserPref(kPrefCustomizationState);
   Services.prefs.clearUserPref(kPrefDrawInTitlebar);
   Services.prefs.clearUserPref(kPrefUIDensity);
   Services.prefs.clearUserPref(kPrefAutoTouchMode);
   Services.prefs.clearUserPref(kPrefAutoHideDownloadsButton);
   Services.prefs.clearUserPref(kPrefSidebarPositionStartEnabled);
   gDefaultTheme.enable();
   gNewElementCount = 0;
   lazy.log.debug("State reset");

   // Later in the function, we're going to add any area-less extension
   // buttons to the AREA_ADDONS area. We'll remember the old placements
   // for that area so that we don't need to re-add widgets that are already
   // in there in the DOM.
   let oldAddonPlacements = gPlacements[CustomizableUI.AREA_ADDONS] || [];

   // Reset placements to make restoring default placements possible.
   gPlacements = new Map();
   gDirtyAreaCache = new Set();
   gSeenWidgets = new Set();
   // Clear the saved state to ensure that defaults will be used.
   gSavedState = null;
   // Restore the state for each area to its defaults
   for (let [areaId] of gAreas) {
     // If the Unified Extensions UI is enabled, we'll be adding any
     // extension buttons that aren't already in AREA_ADDONS there,
     // so we can skip restoring the state for it.
     if (areaId != CustomizableUI.AREA_ADDONS) {
       this.restoreStateForArea(areaId);
     }
   }

   // restoreStateForArea will have normally set an array for the placements
   // for each area, but since we skip AREA_ADDONS intentionally, that array
   // doesn't get set, so we do that manually here.
   gPlacements.set(CustomizableUI.AREA_ADDONS, []);

   for (let [widgetId] of gPalette) {
     if (
       CustomizableUI.isWebExtensionWidget(widgetId) &&
       !oldAddonPlacements.includes(widgetId)
     ) {
       // When resetting, NoScript goes to the toolbar instead. This matches
       // its initial placement anyway. And since the button may be hidden by
       // default by extensions.hideNoScript, we want to make sure that if it
       // becomes unhidden it is shown rather than in the unified extensions
       // panel. See tor-browser#41581.
       this.addWidgetToArea(
         widgetId,
         widgetId === NoScriptId
           ? CustomizableUI.AREA_NAVBAR
           : CustomizableUI.AREA_ADDONS
       );
     }
   }
 },

 /**
  * For all registered areas, builds those areas to reflect the current
  * placement state of all widgets.
  */
 _rebuildRegisteredAreas() {
   for (let [areaId, areaNodes] of gBuildAreas) {
     let placements = gPlacements.get(areaId);
     let isFirstChangedToolbar = true;
     for (let areaNode of areaNodes) {
       this.buildArea(areaId, placements, areaNode);

       let area = gAreas.get(areaId);
       if (area.get("type") == CustomizableUI.TYPE_TOOLBAR) {
         let defaultCollapsed = area.get("defaultCollapsed");
         let win = areaNode.ownerGlobal;
         if (defaultCollapsed !== null) {
           win.setToolbarVisibility(
             areaNode,
             typeof defaultCollapsed == "string"
               ? defaultCollapsed
               : !defaultCollapsed,
             isFirstChangedToolbar
           );
         }
       }
       isFirstChangedToolbar = false;
     }
   }
 },

 /**
  * Undoes a previous reset, restoring the state of the UI to the state prior
  * to the reset.
  */
 undoReset() {
   if (
     gUIStateBeforeReset.uiCustomizationState == null ||
     gUIStateBeforeReset.drawInTitlebar == null
   ) {
     return;
   }
   gUndoResetting = true;

   const {
     uiCustomizationState,
     drawInTitlebar,
     currentTheme,
     uiDensity,
     autoTouchMode,
     autoHideDownloadsButton,
     sidebarPositionStart,
   } = gUIStateBeforeReset;
   gNewElementCount = gUIStateBeforeReset.newElementCount;

   // Need to clear the previous state before setting the prefs
   // because pref observers may check if there is a previous UI state.
   this._clearPreviousUIState();

   Services.prefs.setCharPref(kPrefCustomizationState, uiCustomizationState);
   Services.prefs.setIntPref(kPrefDrawInTitlebar, drawInTitlebar);
   Services.prefs.setIntPref(kPrefUIDensity, uiDensity);
   Services.prefs.setBoolPref(kPrefAutoTouchMode, autoTouchMode);
   Services.prefs.setBoolPref(
     kPrefAutoHideDownloadsButton,
     autoHideDownloadsButton
   );
   Services.prefs.setBoolPref(
     kPrefSidebarPositionStartEnabled,
     sidebarPositionStart
   );
   currentTheme.enable();
   this.loadSavedState();
   // If the user just customizes toolbar/titlebar visibility, gSavedState will be null
   // and we don't need to do anything else here:
   if (gSavedState) {
     for (let areaId of Object.keys(gSavedState.placements)) {
       let placements = gSavedState.placements[areaId];
       gPlacements.set(areaId, placements);
     }
     this._rebuildRegisteredAreas();
   }

   gUndoResetting = false;
 },

 /**
  * Clears the persisted state that was snapshotted just before the most
  * recent reset of the state.
  */
 _clearPreviousUIState() {
   Object.getOwnPropertyNames(gUIStateBeforeReset).forEach(prop => {
     gUIStateBeforeReset[prop] = null;
   });
 },

 /**
  * @param {string|Node} aWidget
  *   Widget ID or a widget node (preferred for performance).
  * @returns {boolean}
  *   True if the widget is removable.
  */
 isWidgetRemovable(aWidget) {
   let widgetId;
   let widgetNode;
   if (typeof aWidget == "string") {
     widgetId = aWidget;
   } else {
     // Skipped items could just not have ids.
     if (!aWidget.id && aWidget.getAttribute("skipintoolbarset") == "true") {
       return false;
     }
     if (
       !aWidget.id &&
       !["toolbarspring", "toolbarspacer", "toolbarseparator"].includes(
         aWidget.nodeName
       )
     ) {
       throw new Error(
         "No nodes without ids that aren't special widgets should ever come into contact with CUI"
       );
     }
     // Use "spring" / "spacer" / "separator" for special widgets without ids
     widgetId =
       aWidget.id || aWidget.nodeName.substring(7 /* "toolbar".length */);
     widgetNode = aWidget;
   }
   let provider = this.getWidgetProvider(widgetId);

   if (provider == CustomizableUI.PROVIDER_API) {
     return gPalette.get(widgetId).removable;
   }

   if (provider == CustomizableUI.PROVIDER_XUL) {
     if (gBuildWindows.size == 0) {
       // We don't have any build windows to look at, so just assume for now
       // that its removable.
       return true;
     }

     if (!widgetNode) {
       // Pick any of the build windows to look at.
       let [window] = [...gBuildWindows][0];
       [, widgetNode] = this.getWidgetNode(widgetId, window);
     }
     // If we don't have a node, we assume it's removable. This can happen because
     // getWidgetProvider returns PROVIDER_XUL by default, but this will also happen
     // for API-provided widgets which have been destroyed.
     if (!widgetNode) {
       return true;
     }
     return widgetNode.getAttribute("removable") == "true";
   }

   // Otherwise this is either a special widget, which is always removable, or
   // an API widget which has already been removed from gPalette. Returning true
   // here allows us to then remove its ID from any placements where it might
   // still occur.
   return true;
 },

 /**
  * @see CustomizableUI.canWidgetMoveToArea
  * @param {string} aWidgetId
  * @param {string} aArea
  * @returns {boolean}
  */
 canWidgetMoveToArea(aWidgetId, aArea) {
   // Special widgets can't move to the menu panel.
   if (
     this.isSpecialWidget(aWidgetId) &&
     gAreas.has(aArea) &&
     gAreas.get(aArea).get("type") == CustomizableUI.TYPE_PANEL
   ) {
     return false;
   }

   if (
     aArea == CustomizableUI.AREA_ADDONS &&
     !CustomizableUI.isWebExtensionWidget(aWidgetId)
   ) {
     return false;
   }

   if (CustomizableUI.isWebExtensionWidget(aWidgetId)) {
     // Extension widgets cannot move to the customization palette.
     if (aArea == CustomizableUI.AREA_NO_AREA) {
       return false;
     }

     // Extension widgets cannot move to panels, with the exception of the
     // AREA_ADDONS area.
     if (
       gAreas.get(aArea).get("type") == CustomizableUI.TYPE_PANEL &&
       aArea != CustomizableUI.AREA_ADDONS
     ) {
       return false;
     }
   }

   let placement = this.getPlacementOfWidget(aWidgetId);
   // Items in the palette can move, and items can move within their area:
   if (!placement || placement.area == aArea) {
     return true;
   }
   // For everything else, just return whether the widget is removable.
   return this.isWidgetRemovable(aWidgetId);
 },

 /**
  * @see CustomizableUI.ensureWidgetPlacedInWindow
  * @param {string} aWidgetId
  * @param {DOMWindow} aWindow
  * @returns {boolean}
  */
 ensureWidgetPlacedInWindow(aWidgetId, aWindow) {
   let placement = this.getPlacementOfWidget(aWidgetId);
   if (!placement) {
     return false;
   }
   let areaNodes = gBuildAreas.get(placement.area);
   if (!areaNodes) {
     return false;
   }
   let container = [...areaNodes].filter(n => n.ownerGlobal == aWindow);
   if (!container.length) {
     return false;
   }
   let existingNode = container[0].getElementsByAttribute("id", aWidgetId)[0];
   if (existingNode) {
     return true;
   }

   this.insertNodeInWindow(aWidgetId, container[0], true);
   return true;
 },

 /**
  * Returns a list of all the widget IDs actively in this container, including
  * any that are overflown for overflowable containers. Notably, this does NOT
  * include IDs of widgets that have been previously placed within this
  * container but are not currently registered (for example, for uninstalled
  * extensions).
  *
  * @param {Element} container
  * @returns {string[]}
  *   The list of widget IDs that currently exist within container.
  */
 _getCurrentWidgetsInContainer(container) {
   let currentWidgets = new Set();
   function addUnskippedChildren(parent) {
     for (let node of parent.children) {
       let realNode =
         node.localName == "toolbarpaletteitem"
           ? node.firstElementChild
           : node;
       if (realNode.getAttribute("skipintoolbarset") != "true") {
         currentWidgets.add(realNode.id);
       }
     }
   }
   addUnskippedChildren(this.getCustomizationTarget(container));
   if (container.getAttribute("overflowing") == "true") {
     let overflowTarget = container.getAttribute("default-overflowtarget");
     addUnskippedChildren(
       container.ownerDocument.getElementById(overflowTarget)
     );
     let webExtOverflowTarget = container.getAttribute(
       "addon-webext-overflowtarget"
     );
     addUnskippedChildren(
       container.ownerDocument.getElementById(webExtOverflowTarget)
     );
   }
   // Then get the sorted list of placements, and filter based on the nodes
   // that are present. This avoids including items that don't exist (e.g. ids
   // of add-on items that the user has uninstalled).
   let orderedPlacements = CustomizableUI.getWidgetIdsInArea(container.id);
   return orderedPlacements.filter(w => {
     return (
       currentWidgets.has(w) ||
       this.getWidgetProvider(w) == CustomizableUI.PROVIDER_API
     );
   });
 },

 /**
  * @type {boolean}
  *   True if the CustomizableUI state of the browser is in the stock state
  *   that is shipped by default.
  */
 get inDefaultState() {
   if (CustomizableUI.verticalTabsEnabled) {
     return false;
   }
   for (let [areaId, props] of gAreas) {
     let defaultPlacements = props
       .get("defaultPlacements")
       .filter(item => this.widgetExists(item));
     let currentPlacements = gPlacements.get(areaId);
     // We're excluding all of the placement IDs for items that do not exist,
     // and items that have removable="false",
     // because we don't want to consider them when determining if we're
     // in the default state. This way, if an add-on introduces a widget
     // and is then uninstalled, the leftover placement doesn't cause us to
     // automatically assume that the buttons are not in the default state.
     let buildAreaNodes = gBuildAreas.get(areaId);
     if (buildAreaNodes && buildAreaNodes.size) {
       let container = [...buildAreaNodes][0];
       let removableOrDefault = itemNodeOrItem => {
         let item = (itemNodeOrItem && itemNodeOrItem.id) || itemNodeOrItem;
         let isRemovable = this.isWidgetRemovable(itemNodeOrItem);
         let isInDefault = defaultPlacements.includes(item);
         return isRemovable || isInDefault;
       };
       // Toolbars need to deal with overflown widgets (if any) - so
       // specialcase them:
       if (props.get("type") == CustomizableUI.TYPE_TOOLBAR) {
         currentPlacements =
           this._getCurrentWidgetsInContainer(container).filter(
             removableOrDefault
           );
       } else {
         currentPlacements = currentPlacements.filter(item => {
           let itemNode = container.getElementsByAttribute("id", item)[0];
           return itemNode && removableOrDefault(itemNode || item);
         });
       }

       if (props.get("type") == CustomizableUI.TYPE_TOOLBAR) {
         let collapsed = null;
         let defaultCollapsed = props.get("defaultCollapsed");
         let nondefaultState = false;
         if (areaId == CustomizableUI.AREA_BOOKMARKS) {
           collapsed = Services.prefs.getCharPref(
             "browser.toolbars.bookmarks.visibility"
           );
           nondefaultState = Services.prefs.prefHasUserValue(
             "browser.toolbars.bookmarks.visibility"
           );
         } else {
           let attribute =
             container.getAttribute("type") == "menubar"
               ? "autohide"
               : "collapsed";
           collapsed = container.hasAttribute(attribute);
           nondefaultState = collapsed != defaultCollapsed;
         }
         if (defaultCollapsed !== null && nondefaultState) {
           lazy.log.debug(
             "Found " +
               areaId +
               " had non-default toolbar visibility" +
               "(expected " +
               defaultCollapsed +
               ", was " +
               collapsed +
               ")"
           );
           return false;
         }
       }
     }
     lazy.log.debug(
       "Checking default state for " +
         areaId +
         ":\n" +
         currentPlacements.join(",") +
         "\nvs.\n" +
         defaultPlacements.join(",")
     );

     if (currentPlacements.length != defaultPlacements.length) {
       return false;
     }

     for (let i = 0; i < currentPlacements.length; ++i) {
       if (
         currentPlacements[i] != defaultPlacements[i] &&
         !this.matchingSpecials(currentPlacements[i], defaultPlacements[i])
       ) {
         lazy.log.debug(
           "Found " +
             currentPlacements[i] +
             " in " +
             areaId +
             " where " +
             defaultPlacements[i] +
             " was expected!"
         );
         return false;
       }
     }
   }

   if (Services.prefs.prefHasUserValue(kPrefUIDensity)) {
     lazy.log.debug(kPrefUIDensity + " pref is non-default");
     return false;
   }

   if (Services.prefs.prefHasUserValue(kPrefAutoTouchMode)) {
     lazy.log.debug(kPrefAutoTouchMode + " pref is non-default");
     return false;
   }

   if (Services.prefs.prefHasUserValue(kPrefDrawInTitlebar)) {
     lazy.log.debug(kPrefDrawInTitlebar + " pref is non-default");
     return false;
   }

   // This should just be `gDefaultTheme.isActive`, but bugs...
   if (gDefaultTheme && gDefaultTheme.id != gSelectedTheme.id) {
     lazy.log.debug(gSelectedTheme.id + " theme is non-default");
     return false;
   }

   if (Services.prefs.prefHasUserValue(kPrefSidebarPositionStartEnabled)) {
     lazy.log.debug(kPrefSidebarPositionStartEnabled + " pref is non-default");
     return false;
   }

   return true;
 },

 /**
  * @see CustomizableUI.getCollapsedToolbarIds
  * @param {Window} window
  * @returns {Set<string>}
  */
 getCollapsedToolbarIds(window) {
   let collapsedToolbars = new Set();
   for (let toolbarId of CustomizableUIInternal.builtinToolbars) {
     let toolbar = window.document.getElementById(toolbarId);

     // Menubar toolbars are special in that they're hidden with the autohide
     // attribute.
     let hidingAttribute =
       toolbar.getAttribute("type") == "menubar" ? "autohide" : "collapsed";

     if (toolbar.hasAttribute(hidingAttribute)) {
       collapsedToolbars.add(toolbarId);
     }
   }

   return collapsedToolbars;
 },

 /**
  * @see CustomizableUI.setToolbarVisibility
  * @param {string} aToolbarId
  * @param {boolean} aIsVisible
  */
 setToolbarVisibility(aToolbarId, aIsVisible) {
   // We only persist the attribute the first time.
   let isFirstChangedToolbar = true;
   for (let window of CustomizableUI.windows) {
     let toolbar = window.document.getElementById(aToolbarId);
     if (toolbar) {
       window.setToolbarVisibility(toolbar, aIsVisible, isFirstChangedToolbar);
       isFirstChangedToolbar = false;
     }
   }
 },

 /**
  * @see CustomizableUI.widgetIsLikelyVisible
  * @param {string} aWidgetId
  * @param {Window} window
  * @returns {boolean}
  */
 widgetIsLikelyVisible(aWidgetId, window) {
   let placement = this.getPlacementOfWidget(aWidgetId);

   if (!placement) {
     return false;
   }

   switch (placement.area) {
     case CustomizableUI.AREA_NAVBAR:
       return true;
     case CustomizableUI.AREA_MENUBAR:
       return !this.getCollapsedToolbarIds(window).has(
         CustomizableUI.AREA_MENUBAR
       );
     case CustomizableUI.AREA_TABSTRIP:
       return !CustomizableUI.verticalTabsEnabled;
     case CustomizableUI.AREA_BOOKMARKS:
       return (
         Services.prefs.getCharPref(
           "browser.toolbars.bookmarks.visibility"
         ) === "always"
       );
     default:
       return false;
   }
 },

 /**
  * nsIObserver implementation that observes for toolbar visibility changes
  * or preference changes.
  *
  * @param {nsISupports} aSubject
  * @param {string} aTopic
  * @param {string} aData
  */
 observe(aSubject, aTopic, aData) {
   if (aTopic == "browser-set-toolbar-visibility") {
     let [toolbar, visibility] = JSON.parse(aData);
     CustomizableUI.setToolbarVisibility(toolbar, visibility == "true");
   }

   if (aTopic === "nsPref:changed") {
     this.reconcileSidebarPrefs(aData);
   }
 },

 /**
  * Initializes CustomizableUI for the current tab orientation.
  *
  * @param {boolean} toVertical
  *   True if the tab orientation is vertical, false if horizontal.
  */
 initializeForTabsOrientation(toVertical) {
   lazy.log.debug(
     `initializeForTabsOrientation, toVertical: ${toVertical}, gCurrentVerticalTabs: ${gCurrentVerticalTabs}`
   );
   if (!toVertical) {
     const savedPlacements = this.getSavedHorizontalSnapshotState();
     lazy.log.debug(
       "initializeForTabsOrientation, savedPlacements",
       savedPlacements
     );
     if (savedPlacements.length) {
       // We're startup up with horizontal tabs, but there are saved placements for the
       // horizontal tab strip, so its possible the verticalTabs pref was updated outside
       // of normal use. Make sure to restore those tabstrip widget placements
       this.restoreSavedHorizontalTabStripState(savedPlacements, true);
     } else {
       // This is the default state and normal initialization will do everything necessary
     }
     gCurrentVerticalTabs = false;
     return;
   }

   // If the UI was already customized and saved, the earlier call to loadSavedState will
   // have populated gSavedState from the pref. If not, we need to move the tabs into the
   // vertical tabs area in the gSavedState. Then, the normal build-areas lifecycle
   // can populate the needed toolbar placements and elements.
   lazy.log.debug(
     "initializeForTabsOrientation, toVertical=true, gSavedState",
     gSavedState
   );

   // If there are saved placement customizations, we need to manually move widgets
   // around before we restore this state
   let savedPlacements = gSavedState?.placements || {};
   if (!savedPlacements[CustomizableUI.AREA_VERTICAL_TABSTRIP]?.length) {
     savedPlacements[CustomizableUI.AREA_VERTICAL_TABSTRIP] =
       gAreas
         .get(CustomizableUI.AREA_VERTICAL_TABSTRIP)
         .get("verticalTabsDefaultPlacements") || [];
     lazy.log.debug(
       "initializeForTabsOrientation, using defaults for AREA_VERTICAL_TABSTRIP",
       savedPlacements[CustomizableUI.AREA_VERTICAL_TABSTRIP]
     );
   }
   let tabstripPlacements =
     savedPlacements[CustomizableUI.AREA_TABSTRIP] || [];
   // also pick up any widgets already in gFuturePlacements so we can wipe that
   if (gFuturePlacements.has(CustomizableUI.AREA_TABSTRIP)) {
     for (let id of gFuturePlacements.get(CustomizableUI.AREA_TABSTRIP)) {
       if (!tabstripPlacements.includes(id)) {
         tabstripPlacements.push(id);
       }
     }
     gFuturePlacements.delete(CustomizableUI.AREA_TABSTRIP);
   }
   // Take a copy we can save and restore to, ensuring there's a sane default
   let savedTabstripPlacements = tabstripPlacements.length
     ? [...tabstripPlacements]
     : gAreas.get(CustomizableUI.AREA_TABSTRIP).get("defaultPlacements");

   // now we can remove the saved placements so they don't get picked back up again later in startup
   delete savedPlacements[CustomizableUI.AREA_TABSTRIP];

   let widgetsMoved = [];
   for (let widgetId of tabstripPlacements) {
     if (widgetId == "tabbrowser-tabs") {
       lazy.log.debug(
         `Moving saved tabbrowser-tabs to AREA_VERTICAL_TABSTRIP`
       );
       this.addWidgetToArea(
         widgetId,
         CustomizableUI.AREA_VERTICAL_TABSTRIP,
         null,
         true
       );
       continue;
     }
     // if this is a extension, those are handled in a toolbarvisibilitychange handler in browser-addons.js
     if (CustomizableUI.isWebExtensionWidget(widgetId)) {
       lazy.log.debug(`Skipping a webextension saved placement ${widgetId}`);
       continue;
     }
     // Everything else gets moved to the nav-bar area while tabs are vertical
     lazy.log.debug(`Moving saved placement ${widgetId} to nav-bar`);
     this.addWidgetToArea(widgetId, CustomizableUI.AREA_NAVBAR, null, true);
     widgetsMoved.push(widgetId);
   }
   lazy.log.debug(
     "initializeForTabsOrientation, widgets moved:",
     widgetsMoved
   );
   if (widgetsMoved.length) {
     // We've updated the areas, so we don't need to do this again post-initialization
     gCurrentVerticalTabs = true;
   }

   // Remove new tab from AREA_NAVBAR when vertical tabs enabled.
   this.removeWidgetFromArea("new-tab-button");

   // If we've ended up with a non-default CUI state and vertical tabs enabled, ensure
   // there's a sane snapshot to revert to
   if (!lazy.horizontalPlacementsPref) {
     lazy.log.debug(
       `verticalTabsEnabled but ${kPrefCustomizationHorizontalTabstrip} is empty`
     );
     CustomizableUIInternal.saveHorizontalTabStripState(
       savedTabstripPlacements
     );
   }
 },

 /**
  * Currently, the new sidebar and vertical tabs have a tight relationship
  * with one another (specifically, the new sidebar is a dependency for
  * vertical tabs). They are, however, controlled by two separate preferences.
  * This function does the work of changing the vertical tabs state if the
  * sidebar pref changes, and vice-versa.
  *
  * @param {string} prefChanged
  *   The key for the preference that changed.
  */
 reconcileSidebarPrefs(prefChanged) {
   let sidebarRevampEnabled = Services.prefs.getBoolPref(
     kPrefSidebarRevampEnabled,
     false
   );
   let verticalTabsEnabled = Services.prefs.getBoolPref(
     kPrefSidebarVerticalTabsEnabled,
     false
   );
   let positionStartEnabled = Services.prefs.getBoolPref(
     kPrefSidebarPositionStartEnabled,
     true
   );
   lazy.log.debug(
     `reconcileSidebarPrefs, kPrefSidebarRevampEnabled: {sidebarRevampEnabled}, kPrefSidebarVerticalTabsEnabled: ${verticalTabsEnabled}`
   );
   switch (prefChanged) {
     case kPrefSidebarVerticalTabsEnabled: {
       // We need to also enable sidebar.revamp if vertical tabs gets enabled
       if (verticalTabsEnabled && !sidebarRevampEnabled) {
         Services.prefs.setBoolPref(kPrefSidebarRevampEnabled, true);
       }
       break;
     }
     case kPrefSidebarRevampEnabled: {
       // If we are changing the pref after startup, update the nav bar defaultPlacements to include/exclude sidebar-button
       let props = gAreas.get(CustomizableUI.AREA_NAVBAR);
       let defaults = props.get("defaultPlacements");
       let sidebarButtonIndex = defaults.indexOf("sidebar-button");
       if (sidebarRevampEnabled && sidebarButtonIndex < 0) {
         defaults.unshift("sidebar-button");
       } else if (!sidebarRevampEnabled && sidebarButtonIndex > -1) {
         defaults.splice(sidebarButtonIndex, 1);
       }
       props.set("defaultPlacements", defaults);
       gAreas.set(CustomizableUI.AREA_NAVBAR, props);
       // We need to also disable vertical tabs if sidebar.revamp is no longer enabled
       if (!sidebarRevampEnabled && verticalTabsEnabled) {
         lazy.log.debug(
           `{kPrefSidebarRevampEnabled} disabled, so also disabling ${kPrefSidebarVerticalTabsEnabled}`
         );
         Services.prefs.setBoolPref(kPrefSidebarVerticalTabsEnabled, false);
       }
       break;
     }
     case kPrefSidebarPositionStartEnabled: {
       // If the sidebar moves to the left or right, move the toolbar button along with it.
       const navbarPlacements = gPlacements.get(CustomizableUI.AREA_NAVBAR);
       const index = navbarPlacements.indexOf("sidebar-button");
       if (!positionStartEnabled && index === 0) {
         this.moveWidgetWithinArea("sidebar-button", navbarPlacements.length);
       }
       if (positionStartEnabled && index === navbarPlacements.length - 1) {
         this.moveWidgetWithinArea("sidebar-button", 0);
       }
     }
   }
 },

 /**
  * @type {boolean}
  *   True if the horizontal and vertical tabstrips have been registered.
  */
 get tabstripAreasReady() {
   return (
     gBuildAreas.get(CustomizableUI.AREA_TABSTRIP)?.size &&
     gBuildAreas.get(CustomizableUI.AREA_VERTICAL_TABSTRIP)?.size
   );
 },

 /**
  * Updates the vertical or horizontal state of the tabstrip to best match
  * the current preference value.
  */
 updateTabStripOrientation() {
   if (!this.tabstripAreasReady) {
     lazy.log.debug("tabstrip build areas not yet ready");
     return;
   }
   let toVertical = CustomizableUI.verticalTabsEnabled;
   if (toVertical === gCurrentVerticalTabs) {
     lazy.log.debug("early return as the value hasn't changed");
     return;
   }
   lazy.log.debug(
     `verticalTabs changed, from ${gCurrentVerticalTabs}, to ${toVertical}`
   );

   if (toVertical && gCurrentVerticalTabs !== null) {
     // Stash current placements as a state we can restore to when going back to horizontal tabs
     lazy.log.debug(
       "Switching to vertical tabs post-initialization, so capturing tabstrip placements snapshot"
     );
     CustomizableUIInternal.saveHorizontalTabStripState();
   }
   gCurrentVerticalTabs = toVertical;

   function changeWidgetRemovability(widgetId, removable) {
     let widget = CustomizableUI.getWidget(widgetId);
     for (let { node } of widget.instances) {
       if (node) {
         node.setAttribute("removable", removable.toString());
       }
     }
   }

   // Normally these aren't removable, but for this operation only we need to move them
   changeWidgetRemovability("tabbrowser-tabs", true);

   if (toVertical) {
     lazy.log.debug(
       `Switching to verticalTabs=true in updateTabStripOrientation`
     );
     gDirty = true;

     if (
       !Services.prefs.getCharPref(kPrefCustomizationHorizontalTabsBackup, "")
     ) {
       // Before we switch for the first time, take a back up just in case we need an escape hatch
       Services.prefs.setCharPref(
         kPrefCustomizationHorizontalTabsBackup,
         Services.prefs.getCharPref(kPrefCustomizationState, "")
       );
     }

     CustomizableUI.beginBatchUpdate();
     let customVerticalNavbarPlacements = this.getSavedVerticalSnapshotState();
     let tabstripPlacements = this.getSavedHorizontalSnapshotState();
     const isSidebarLast =
       gPlacements.get(CustomizableUI.AREA_NAVBAR).at(-1) === "sidebar-button";
     // Remove non-default widgets to the nav-bar
     for (let id of CustomizableUI.getWidgetIdsInArea("TabsToolbar")) {
       if (id == "tabbrowser-tabs") {
         CustomizableUI.addWidgetToArea(
           id,
           CustomizableUI.AREA_VERTICAL_TABSTRIP
         );
         continue;
       }
       // We add the tab strip placements later in the case they have a custom position
       if (
         tabstripPlacements.includes(id) &&
         customVerticalNavbarPlacements.includes(id)
       ) {
         continue;
       }
       if (!CustomizableUI.isWidgetRemovable(id)) {
         continue;
       }
       // if this is a extension, those are handled in a toolbarvisibilitychange handler in browser-addons.js
       if (CustomizableUI.isWebExtensionWidget(id)) {
         continue;
       }
       // Everything else gets moved to the nav-bar area while tabs are vertical
       CustomizableUI.addWidgetToArea(id, CustomizableUI.AREA_NAVBAR);
     }
     // Remove new tab from nav-bar when vertical tabs enabled
     this.removeWidgetFromArea("new-tab-button");
     customVerticalNavbarPlacements.forEach((id, index) => {
       if (tabstripPlacements.includes(id)) {
         CustomizableUI.addWidgetToArea(id, CustomizableUI.AREA_NAVBAR, index);
       }
     });
     // If sidebar was previously the last widget in navbar, carry it over to
     // the end of the newly constructed navbar.
     if (isSidebarLast) {
       this.addWidgetToArea("sidebar-button", CustomizableUI.AREA_NAVBAR);
     }
     CustomizableUI.endBatchUpdate();
   } else {
     this.saveNavBarWhenVerticalTabsState();
     // We're switching to vertical in this session; pull saved state from pref and update placements
     this.restoreSavedHorizontalTabStripState();
   }
   // Give the sidebar a chance to adjust before we show/hide the toolbars
   lazy.log.debug("CustomizableUI notifying tabstrip-orientation-change");
   Services.obs.notifyObservers(null, "tabstrip-orientation-change", {
     isVertical: toVertical,
   });

   this.setToolbarVisibility(
     CustomizableUI.AREA_VERTICAL_TABSTRIP,
     toVertical
   );
   this.setToolbarVisibility(CustomizableUI.AREA_TABSTRIP, !toVertical);
   changeWidgetRemovability("tabbrowser-tabs", false);

   for (let [win] of gBuildWindows) {
     win.TabBarVisibility.update(true);
   }
 },
};
Object.freeze(CustomizableUIInternal);

/**
* This is the publicly exposed interface CustomizableUI. It uses old-school
* encapsulation by forwarding most method calls to CustomizableUIInternal,
* which is not exported.
*/
export var CustomizableUI = {
 /**
  * Constant reference to the ID of the navigation toolbar.
  */
 AREA_NAVBAR: "nav-bar",
 /**
  * Constant reference to the ID of the menubar's toolbar.
  */
 AREA_MENUBAR: "toolbar-menubar",
 /**
  * Constant reference to the ID of the tabstrip toolbar.
  */
 AREA_TABSTRIP: "TabsToolbar",

 /**
  * Constant reference to the ID of the vertical tabstrip toolbar.
  */
 AREA_VERTICAL_TABSTRIP: "vertical-tabs",

 /**
  * Constant reference to the ID of the bookmarks toolbar.
  */
 AREA_BOOKMARKS: "PersonalToolbar",
 /**
  * Constant reference to the ID of the non-dymanic (fixed) list in the overflow panel.
  */
 AREA_FIXED_OVERFLOW_PANEL: "widget-overflow-fixed-list",
 /**
  * Constant reference to the ID of the addons area.
  */
 AREA_ADDONS: "unified-extensions-area",
 /**
  * Constant reference to the ID of the customization palette, which is
  * where widgets go when they're not assigned to an area. Note that this
  * area is "virtual" in that it's never set as a value for a widgets
  * currentArea or defaultArea. It's only used for the `canWidgetMoveToArea`
  * function to check if widgets can be moved to the palette. Callers who
  * wish to move items to the palette should use `removeWidgetFromArea`.
  */
 AREA_NO_AREA: "customization-palette",
 /**
  * Constant indicating the area is a panel.
  */
 TYPE_PANEL: "panel",
 /**
  * Constant indicating the area is a toolbar.
  */
 TYPE_TOOLBAR: "toolbar",

 /**
  * Constant indicating a XUL-type provider.
  */
 PROVIDER_XUL: "xul",
 /**
  * Constant indicating an API-type provider.
  */
 PROVIDER_API: "api",
 /**
  * Constant indicating dynamic (special) widgets: spring, spacer, and separator.
  */
 PROVIDER_SPECIAL: "special",

 /**
  * Constant indicating the widget is built-in
  */
 SOURCE_BUILTIN: "builtin",
 /**
  * Constant indicating the widget is externally provided
  * (e.g. by add-ons or other items not part of the builtin widget set).
  */
 SOURCE_EXTERNAL: "external",

 /**
  * Constant indicating the reason the event was fired was a window closing
  */
 REASON_WINDOW_CLOSED: "window-closed",
 /**
  * Constant indicating the reason the event was fired was an area being
  * unregistered separately from window closing mechanics.
  */
 REASON_AREA_UNREGISTERED: "area-unregistered",

 /**
  * An iteratable property of windows managed by CustomizableUI.
  * Note that this can *only* be used as an iterator. ie:
  *     for (let window of CustomizableUI.windows) { ... }
  */
 windows: {
   *[Symbol.iterator]() {
     for (let [window] of gBuildWindows) {
       yield window;
     }
   },
 },

 get verticalTabsEnabled() {
   return lazy.verticalTabsPref;
 },

 /**
  * Fired when a widget is added to an area.
  *
  * @callback CustomizableUIOnWidgetAddedCallback
  * @param {string} aWidgetId
  *   The ID of the widget that was added to an area.
  * @param {string} aArea
  *   The ID of the area that the widget was added to.
  * @param {number} aPosition
  *   The position of the widget in the area that it was added to.
  */

 /**
  * Fired when a widget is moved within its area.
  *
  * @callback CustomizableUIOnWidgetMovedCallback
  * @param {string} aWidgetId
  *   The ID of the widget that was moved.
  * @param {string} aArea
  *   The ID of the area that the widget was moved within.
  * @param {number} aOldPosition
  *   The original position of the widget before being moved.
  * @param {number} aNewPosition
  *   The new position of the widget after being moved.
  */

 /**
  * Fired when a widget is removed from an area.
  *
  * @callback CustomizableUIOnWidgetRemovedCallback
  * @param {string} aWidgetId
  *   The ID of the widget that was removed.
  * @param {string} aArea
  *   The ID of the area that the widget was removed from.
  */

 /**
  * Fired *before* a widget's DOM node is acted upon by CustomizableUI
  * (to add, move or remove it).
  *
  * @callback CustomizableUIOnWidgetBeforeDOMChange
  * @param {Element} aNode
  *   The DOM node being acted upon.
  * @param {Element|null} aNextNode
  *   The DOM node (if any) before which a widget will be inserted.
  * @param {Element} aContainer
  *   The *actual* DOM container for the widget (could be an overflow panel in
  *   case of an overflowable toolbar).
  * @param {boolean} aWasRemoval
  *   True iff the action about to happen is the removal of the DOM node.
  */

 /**
  * Fired *after* a widget's DOM node is acted upon by CustomizableUI
  * (to add, move or remove it).
  *
  * @callback CustomizableUIOnWidgetAfterDOMChange
  * @param {Element} aNode
  *   The DOM node that was acted upon.
  * @param {Element|null} aNextNode
  *   The DOM node (if any) that the widget was inserted before.
  * @param {Element} aContainer
  *   The *actual* DOM container for the widget (could be an overflow panel in
  *   case of an overflowable toolbar).
  * @param {boolean} aWasRemoval
  *   True iff the action that happened was the removal of the DOM node.
  */

 /**
  * Fired after a reset to default placements moves a widget's node to a
  * different location.
  *
  * @callback CustomizableUIOnWidgetReset
  * @param {Element} aNode
  *   The DOM node for the widget that was moved.
  * @param {Element} aContainer
  *   The *actual* DOM container for the widget (could be an overflow panel in
  *   case of an overflowable toolbar) after the reset. (NB: it might already
  *   have been there and been moved to a different position!)
  */

 /**
  * Fired after undoing a reset to default placements moves a widget's
  * node to a different location.
  *
  * @callback CustomizableUIOnWidgetUndoMove
  * @param {Element} aNode
  *   The DOM node for the widget that was moved after the undo.
  * @param {Element} aContainer
  *   The *actual* DOM container for the widget (could be an overflow panel in
  *   case of an overflowable toolbar) after the undo-move. (NB: it might
  *   already have been there and been moved to a different position!)
  */

 /**
  * Fired when a widget with id aWidgetId has been created, but before it
  * is added to any placements or any DOM nodes have been constructed.
  * Only fired for API-based widgets.
  *
  * @callback CustomizableUIOnWidgetCreated
  * @param {string} aWidgetId
  *   The ID of the widget that was created.
  */

 /**
  * Fired after a reset to default placements is complete on an area's
  * DOM node. Note that this is fired for each DOM node across all windows.
  *
  * @callback CustomizableUIOnAreaReset
  * @param {string} aArea
  *   The ID for the area that was reset.
  * @param {Element} aContainer
  *   The DOM node for the area that was reset.
  */

 /**
  * Fired after a widget with id aWidgetId has been created, and has been
  * added to either its default area or the area in which it was placed
  * previously. If the widget has no default area and/or it has never
  * been placed anywhere, aArea may be null. Only fired for API-based
  * widgets.
  *
  * @callback CustomizableUIOnWidgetAfterCreation
  * @param {string} aWidgetId
  *   The ID of the widget that was just created.
  * @param {string|null} aArea
  *   The ID of the area that the widget was placed in, or null if it is
  *   now in the customization palette.
  */

 /**
  * Fired when a widget is destroyed. Only fired for API-based widgets.
  *
  * @callback CustomizableUIOnWidgetDestroyed
  * @param {string} aWidgetId
  *   The ID of the widget that was destroyed.
  */

 /**
  * Fired when a window is unloaded and a widget's instance is destroyed
  * because of this. Only fired for API-based widgets.
  *
  * @callback CustomizableUIOnWidgetInstanceRemoved
  * @param {string} aWidgetId
  *   The ID of the widget that was just removed.
  * @param {Document} aDocument
  *   The Document that the widget belonged to that was just unloaded.
  */

 /**
  * Fired when entering customize mode in aWindow.
  *
  * @callback CustomizableUIOnCustomizeStart
  * @param {DOMWindow} aWindow
  *   The window in which customize mode was entered.
  */

 /**
  * Fired when exiting customize mode in aWindow.
  *
  * @callback CustomizableUIOnCustomizeEnd
  * @param {DOMWindow} aWindow
  *   The window in which customize mode was exited.
  */

 /**
  * Fired when a widget's DOM node is overflowing its toolbar and will be
  * displayed in an overflow panel.
  *
  * @callback CustomizableUIOnWidgetOverflow
  * @param {Element} aNode
  *   The DOM node for the widget that overflowed.
  * @param {Element} aContainer
  *   The DOM container that the widget just overflowed out of.
  */

 /**
  * Fired when a widget that was overflowed out of its toolbar container
  * "underflows" back.
  *
  * @callback CustomizableUIOnWidgetUnderflow
  * @param {Element} aNode
  *   The DOM node for the widget that had overflowed out.
  * @param {Element} aContainer
  *   The DOM container that the widget is underflowing back into.
  */

 /**
  * Fired when a window has been opened that is managed by CustomizableUI,
  * once all of the prerequisite setup has been done.
  *
  * @callback CustomizableUIOnWindowOpened
  * @param {DOMWindow} aWindow
  *   The window that opened.
  */

 /**
  * Fired when a window that has been managed by CustomizableUI has been
  * closed.
  *
  * @callback CustomizableUIOnWindowClosed
  * @param {DOMWindow} aWindow
  *   The window that closed.
  */

 /**
  * Fired after an area node is first built when it is registered. This is
  * often when the window has opened, but in the case of add-ons, could fire
  * when the node has just been registered with CustomizableUI after an add-on
  * update or disable/enable sequence.
  *
  * @callback CustomizableUIOnAreaNodeRegistered
  * @param {string} aArea
  *   The ID for the area that was just registered.
  * @param {Element} aContainer
  *   The DOM node for the customizable area.
  */

 /**
  * Fired when an area node is explicitly unregistered by an API caller, or by
  * a window closing. The aReason parameter indicates which of these is the
  * case.
  *
  * @callback CustomizableUIOnAreaNodeUnregistered
  * @param {string} aArea
  *   The ID for the area that was just registered.
  * @param {Element} aContainer
  *   The DOM node for the customizable area.
  * @param {string} aReason
  *   One of either CustomizableUI.REASON_WINDOW_CLOSED or
  *   CustomizableUI.REASON_AREA_UNREGISTERED.
  */

 /**
  * @typedef {object} CustomizableUIListener
  * @property {CustomizableUIOnWidgetAddedCallback} [onWidgetAdded]
  * @property {CustomizableUIOnWidgetMovedCallback} [onWidgetMoved]
  * @property {CustomizableUIOnWidgetRemovedCallback} [onWidgetRemoved]
  * @property {CustomizableUIOnWidgetBeforeDOMChange} [onWidgetBeforeDOMChange]
  * @property {CustomizableUIOnWidgetAfterDOMChange} [onWidgetAfterDOMChange]
  * @property {CustomizableUIOnWidgetReset} [onWidgetReset]
  * @property {CustomizableUIOnWidgetUndoMove} [onWidgetUndoMove]
  * @property {CustomizableUIOnWidgetCreated} [onWidgetCreated]
  * @property {CustomizableUIOnAreaReset} [onAreaReset]
  * @property {CustomizableUIOnWidgetAfterCreation} [onWidgetAfterCreation]
  * @property {CustomizableUIOnWidgetDestroyed} [onWidgetDestroyed]
  * @property {CustomizableUIOnWidgetInstanceRemoved} [onWidgetInstanceRemoved]
  * @property {CustomizableUIOnWidgetDrag} [onWidgetDrag]
  * @property {CustomizableUIOnCustomizeStart} [onCustomizeStart]
  * @property {CustomizableUIOnCustomizeEnd} [onCustomizeEnd]
  * @property {CustomizableUIOnWidgetOverflow} [onWidgetOverflow]
  * @property {CustomizableUIOnWindowOpened} [onWindowOpened]
  * @property {CustomizableUIOnWindowClosed} [onWindowClosed]
  * @property {CustomizableUIOnAreaNodeRegistered} [onAreaNodeRegistered]
  * @property {CustomizableUIOnAreaNodeUnregistered} [onAreaNodeUnregistered]
  */

 /**
  * Add a listener object that will get fired for various events regarding
  * window, area, and window lifetimes / events, as well as customization
  * events.
  *
  * @param {CustomizableUIListener} aListener
  *   The listener object to add. Not all event handler methods need to be
  *   defined. CustomizableUI will catch exceptions. Events are dispatched
  *   synchronously on the UI thread, so if you can delay any/some of your
  *   processing, that is advisable.
  */
 addListener(aListener) {
   CustomizableUIInternal.addListener(aListener);
 },

 /**
  * Remove a listener that was previously added with addListener.
  *
  * @param {CustomizableUIListener} aListener
  *   The listener object to remove.
  */
 removeListener(aListener) {
   CustomizableUIInternal.removeListener(aListener);
 },

 /**
  * Register a customizable area with CustomizableUI.
  *
  * @param {string} aName
  *   The name of the area to register. Can only contain alphanumeric
  *   characters, dashes (-) and underscores (_).
  * @param {object} aProperties
  *   The properties of the area to register.
  * @param {string} [aProperties.type=CustomizableUI.TYPE_TOOLBAR]
  *   The type of area being registered. Either CustomizableUI.TYPE_TOOLBAR
  *   (default) or CustomizableUI.TYPE_PANEL.
  * @param {Element|undefined} [aProperties.anchor]
  *   For a menu panel or overflowable toolbar area, the anchoring node for the
  *   panel.
  * @param {boolean} [aProperties.overflowable]
  *   Set to true if your toolbar is overflowable. This requires an anchor, and
  *   only has an effect for toolbars.
  * @param {string[]} [aProperties.defaultPlacements]
  *   An array of widget IDs making up the default contents of the area.
  * @param {boolean|null} [aProperties.defaultCollapsed=true]
  *   (INTERNAL ONLY) applies if the type is CustomizableUI.TYPE_TOOLBAR,
  *   specifies if the toolbar is collapsed by default (defaults to true).
  *   Specify `null` to ensure that reset/inDefaultArea don't care
  *   about a toolbar's collapsed state
  */
 registerArea(aName, aProperties) {
   CustomizableUIInternal.registerArea(aName, aProperties);
 },
 /**
  * Register a concrete node for a registered area. This method needs to be called
  * with any toolbar in the main browser window that has its "customizable" attribute
  * set to true.
  *
  * Note that ideally, you should register your toolbar using registerArea
  * before calling this. If you don't, the node will be saved for processing when
  * you call registerArea. Note that CustomizableUI won't restore state in the area,
  * allow the user to customize it in customize mode, or otherwise deal
  * with it, until the area has been registered.
  *
  * @param {Element} aToolbar
  *   The <xul:toolbar> node to register.
  */
 registerToolbarNode(aToolbar) {
   CustomizableUIInternal.registerToolbarNode(aToolbar);
 },
 /**
  * Register a panel node. A panel treated slightly differently from a toolbar in
  * terms of what items can be moved into it. For example, a panel cannot have a
  * spacer or a spring put into it.
  *
  * @param {Element} aNode
  *   The panel contents DOM node being registered.
  * @param {string} aArea
  *   The name of the area for which to register this node.
  */
 registerPanelNode(aNode, aArea) {
   CustomizableUIInternal.registerPanelNode(aNode, aArea);
 },
 /**
  * Unregister a customizable area. The inverse of registerArea.
  *
  * Unregistering an area will remove all the (removable) widgets in the
  * area, which will return to the panel, and destroy all other traces
  * of the area within CustomizableUI. Note that this means the *contents*
  * of the area's DOM nodes will be moved to the panel or removed, but
  * the area's DOM nodes *themselves* will stay.
  *
  * Furthermore, by default the placements of the area will be kept in the
  * saved state (!) and restored if you re-register the area at a later
  * point. This is useful for e.g. add-ons that get disabled and then
  * re-enabled (e.g. when they update).
  *
  * You can override this last behaviour (and destroy the placements
  * information in the saved state) by passing true for aDestroyPlacements.
  *
  * @param {string} aName
  *   The name of the area to unregister.
  * @param {boolean} [aDestroyPlacements]
  *   True if the placements information for the area should be destroyed
  *   too. Defaults to not destroying the placements information.
  */
 unregisterArea(aName, aDestroyPlacements) {
   CustomizableUIInternal.unregisterArea(aName, aDestroyPlacements);
 },
 /**
  * Add a widget to an area.
  * If the area to which you try to add is not known to CustomizableUI,
  * this will throw.
  * If the area to which you try to add is the same as the area in which
  * the widget is currently placed, this will do the same as
  * moveWidgetWithinArea.
  * If the widget cannot be removed from its original location, this will
  * no-op.
  *
  * This will fire an onWidgetAdded notification,
  * and an onWidgetBeforeDOMChange and onWidgetAfterDOMChange notification
  * for each window CustomizableUI knows about.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to add to the area.
  * @param {string} aArea
  *   The name of the area to add the widget to.
  * @param {number} [aPosition]
  *   The position at which to add the widget. If you do not pass a position,
  *   the widget will be added to the end of the area.
  */
 addWidgetToArea(aWidgetId, aArea, aPosition) {
   CustomizableUIInternal.addWidgetToArea(aWidgetId, aArea, aPosition);
 },
 /**
  * Remove a widget from its area. If the widget cannot be removed from its
  * area, or is not in any area, this will no-op. Otherwise, this will fire an
  * onWidgetRemoved notification, and an onWidgetBeforeDOMChange and
  * onWidgetAfterDOMChange notification for each window CustomizableUI knows
  * about.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to remove from its area.
  */
 removeWidgetFromArea(aWidgetId) {
   CustomizableUIInternal.removeWidgetFromArea(aWidgetId);
 },
 /**
  * Move a widget within an area.
  * If the widget is not in any area, this will no-op.
  * If the widget is already at the indicated position, this will no-op.
  *
  * Otherwise, this will move the widget and fire an onWidgetMoved notification,
  * and an onWidgetBeforeDOMChange and onWidgetAfterDOMChange notification for
  * each window CustomizableUI knows about.
  *
  * @param {string} aWidgetId
  *   The ID of the widget to move.
  * @param {number} aPosition
  *   The position to move the widget to. Negative values or values greater
  *   than the number of widgets will be interpreted to mean moving the widget
  *   to respectively the first or last position.
  */
 moveWidgetWithinArea(aWidgetId, aPosition) {
   CustomizableUIInternal.moveWidgetWithinArea(aWidgetId, aPosition);
 },
 /**
  * Ensure a XUL-based widget created in a window after areas were
  * initialized moves to its correct position.
  * Always prefer this over moving items in the DOM yourself.
  *
  * NB: why is this API per-window, you wonder? Because if you need this,
  * presumably you yourself need to create the widget in all the windows
  * and need to loop through them anyway.
  *
  * @param {string} aWidgetId
  *   The ID of the widget that was just created.
  * @param {DOMWindow} aWindow
  *   The window in which you want to ensure it was added.
  * @returns {boolean}
  *   True if the widget was successfully placed in the window (or was already
  *   placed in the window). False if something goes wrong with checking for
  *   the presence of the widget in the window.
  */
 ensureWidgetPlacedInWindow(aWidgetId, aWindow) {
   return CustomizableUIInternal.ensureWidgetPlacedInWindow(
     aWidgetId,
     aWindow
   );
 },
 /**
  * Start a batch update of items.
  * During a batch update, the customization state is not saved to the user's
  * preferences file, in order to reduce (possibly sync) IO.
  * Calls to begin/endBatchUpdate may be nested.
  *
  * Callers should ensure that NO MATTER WHAT they call endBatchUpdate once
  * for each call to beginBatchUpdate, even if there are exceptions in the
  * code in the batch update. Otherwise, for the duration of the
  * Firefox session, customization state is never saved. Typically, you
  * would do this using a try...finally block.
  */
 beginBatchUpdate() {
   CustomizableUIInternal.beginBatchUpdate();
 },
 /**
  * End a batch update. See the documentation for beginBatchUpdate above.
  *
  * State is not saved if we believe it is identical to the last known
  * saved state. State is only ever saved when all batch updates have
  * finished (ie there has been 1 endBatchUpdate call for each
  * beginBatchUpdate call). If any of the endBatchUpdate calls pass
  * aForceDirty=true, we will flush to the prefs file.
  *
  * @param {boolean} [aForceDirty=false]
  *   Force CustomizableUI to flush to the prefs file when all batch updates
  *   have finished. Defaults to false.
  */
 endBatchUpdate(aForceDirty = false) {
   CustomizableUIInternal.endBatchUpdate(aForceDirty);
 },

 /**
  * A function that will be invoked with the document in which to build a
  * widget. Should return the DOM node that has been constructed.
  *
  * @callback CustomizableUICreateWidgetOnBuild
  * @param {Document} aDoc
  *   The document to create the widget in.
  * @returns {Element}
  *   The DOM node that was constructed for the widget.
  */

 /**
  * Invoked before the widget gets a DOM node constructed for it, passing the
  * document in which that will happen. This is useful especially for 'view'
  * type widgets that need to construct their views on the fly (e.g. from
  * bootstrapped add-ons). If the function returns `false`, the widget will
  * not be created.
  *
  * @callback CustomizableUICreateWidgetOnBeforeCreated
  * @param {Document} aDoc
  *   The document that the widget might be created in.
  * @returns {boolean}
  *   True if the widget should be created.
  */

 /**
  * A function that will be invoked whenever the widget has a DOM node
  * constructed, passing the constructed node as an argument.
  *
  * @callback CustomizableUICreateWidgetOnCreated
  * @param {Element} aNode
  *   The DOM node that was constructed for the widget in a document.
  */

 /**
  * A function that will be invoked after the widget has a DOM node destroyed,
  * passing the document from which it was removed. This is useful especially
  * for 'view' type widgets that need to cleanup after views that were
  * constructed on the fly.
  *
  * @callback CustomizableUICreateWidgetOnDestroyed
  * @param {Document} aDoc
  *   The document that the widget was destroyed in.
  */

 /**
  * A function that will be invoked when the user activates the button but
  * before the command is evaluated. Useful if code needs to run to change the
  * button's icon in preparation to the pending command action. Called for any
  * type that supports the handler.  The command type, either "view" or
  * "command", may be returned to force the action that will occur.  View will
  * open the panel and command will result in calling onCommand.
  *
  * @callback CustomizableUICreateWidgetOnBeforeCommand
  * @param {Event} aEvent
  *   The command event that occurred on the button.
  * @param {Element} aNode
  *   The element upon which the command event occurred.
  * @returns {string}
  *   One of "action" or "view".
  */

 /**
  * Useful for custom, button and button-and-view widgets; a function that will
  * be invoked when the user activates the button.
  *
  * @callback CustomizableUICreateWidgetOnCommand
  * @param {Event} aEvent
  *   The command event that was fired for the node.
  */

 /**
  * A function that will be invoked when the user clicks a widget node.
  *
  * @callback CustomizableUICreateWidgetOnClick
  * @param {Event} aEvent
  *   The click event that was fired for the widget node.
  */

 /**
  * A function that will be invoked when a user shows your view. If any event
  * handler calls aEvt.preventDefault(), the view will not be shown.
  *
  * The event's `detail` property is an object with an `addBlocker` method.
  * Handlers which need to perform asynchronous operations before the view is
  * shown may pass this method a Promise, which will prevent the view from
  * showing until it resolves. Additionally, if the promise resolves to the
  * exact value `false`, the view will not be shown.
  *
  * @callback CustomizableUICreateWidgetOnViewShowing
  * @param {Event} aEvent
  *   The ViewShowing event. See PanelMultiView.sys.mjs.
  */

 /**
  * A function that will be invoked when a user hides your view.
  *
  * @callback CustomizableUICreateWidgetOnViewHiding
  * @param {Event} aEvent
  *   The ViewHiding event. See PanelMultiView.sys.mjs.
  */

 /**
  * @typedef {object} CustomizableUICreateWidgetProperties
  * @property {string} id
  *   The ID of the widget to be created.
  * @property {string} [type="button"]
  *   The type of widget to create. The valid types are:
  *     'button' - for simple button widgets (the default)
  *     'view'   - for buttons that open a panel or subview,
  *                depending on where they are placed.
  *     'button-and-view' - A combination of 'button' and 'view',
  *                which looks different depending on whether it's
  *                located in the toolbar or in the panel: When
  *                located in the toolbar, the widget is shown as
  *                a combined item of a button and a dropmarker
  *                button. The button triggers the command and the
  *                dropmarker button opens the view. When located
  *                in the panel, shown as one item which opens the
  *                view, and the button command cannot be
  *                triggered separately.
  *     'custom' - for fine-grained control over the creation
  *                of the widget.
  * @property {string} [viewId]
  *   Only useful for views and button-and-view widgets (and required in those
  *   cases). Should be set to the id of the <panelview> that should be shown
  *   when clicking the widget.  If used with a custom widget, the widget must
  *   also provide a toolbaritem where the first child is the view button.
  * @property {CustomizableUICreateWidgetOnBuild} [onBuild]
  *   Only useful for custom widgets (and required there).
  * @property {CustomizableUICreateWidgetOnBeforeCreated} [onBeforeCreated]
  *   Called for all button and non-custom widgets.
  * @property {CustomizableUICreateWidgetOnCreated} [onCreated]
  * @property {CustomizableUICreateWidgetOnDestroyed} [onDestroyed]
  * @property {CustomizableUICreateWidgetOnBeforeCommand} [onBeforeCommand]
  * @property {CustomizableUICreateWidgetOnCommand} [onCommand]
  * @property {CustomizableUICreateWidgetOnClick} [onClick]
  * @property {CustomizableUICreateWidgetOnViewShowing} [onViewShowing]
  *   Only useful for view and button-and-view widgets.
  * @property {CustomizableUICreateWidgetOnViewHiding} [onViewHiding]
  *   Only useful for view and button-and-view widgets.
  * @property {string} [l10nId]
  *   A Fluent string identifier to use for localizing attributes on the
  *   widget. If present, preferred over the label/tooltiptext parameters.
  * @property {string} [tooltiptext]
  *   **Deprecated** - use l10nId and Fluent instead. A string to use for the
  *   tooltip of the widget.
  * @property {string} [label]
  *   **Deprecated** - use l10nId and Fluent instead. A string to use for the
  *   label of the widget.
  * @property {string} [localized]
  *   **Deprecated** - use l10nId and Fluent instead. If true, or undefined,
  *   attempt to retrieve the widget's string properties from the customizable
  *   widgets string bundle.
  * @property {boolean} [removable=true]
  *   Whether the widget can be removed from a customizable area.
  *   Note: if you specify false here, you must provide a defaultArea, too.
  * @property {boolean} [overflows=true]
  *   Whether widget can overflow when placed within an overflowable toolbar.
  * @property {string} [defaultArea]
  *   The default area to add the widget to. If not supplied, this widget will
  *   be placed in the palette by default. A valid default area is required if
  *   the widget is not removable.
  * @property {string} [shortcutId]
  *   The id of an element that has a shortcut for this widget. This is only
  *   used to display the shortcut as part of the tooltip for builtin widgets
  *   (which have strings inside customizableWidgets.properties). If you're in
  *   an add-on, you should not set this property. If l10nId is provided, the
  *   resulting shortcut is passed as the "$shortcut" variable to the Fluent
  *   message.
  * @property {boolean} [showInPrivateBrowsing=true]
  *   True to show the widget in private browsing mode windows.
  * @property {boolean} [hideInNonPrivateBrowsing=false]
  *   True to hide the widget in non-private browsing mode windows.
  * @property {boolean} [tabSpecific]
  *   True to close any widget view panels if the selected tab changes.
  * @property {boolean} [locationSpecific]
  *   True to close any widget view panels if the location changes.
  * @property {boolean} [webExtension]
  *   True if this widget is being created on behalf of a WebExtension.
  */

 /**
  * Create a widget.
  *
  * To create a widget, you should pass an object with its desired
  * properties.
  *
  * @param {CustomizableUICreateWidgetProperties} aProperties
  *   The properties for the widget to be created.
  * @returns {WidgetGroupWrapper|XULWidgetGroupWrapper}
  */
 createWidget(aProperties) {
   return CustomizableUIInternal.wrapWidget(
     CustomizableUIInternal.createWidget(aProperties)
   );
 },
 /**
  * Destroy a widget
  *
  * If the widget is part of the default placements in an area, this will
  * remove it from there. It will also remove any DOM instances. However,
  * it will keep the widget in the placements for whatever area it was
  * in at the time. You can remove it from there yourself by calling
  * CustomizableUI.removeWidgetFromArea(aWidgetId).
  *
  * @param {string} aWidgetId
  *   The ID of the widget to destroy.
  */
 destroyWidget(aWidgetId) {
   CustomizableUIInternal.destroyWidget(aWidgetId);
 },
 /**
  * Get a wrapper object with information about the widget.
  * The object provides the following properties
  * (all read-only unless otherwise indicated):
  *
  * - id:            the widget's ID;
  * - type:          the type of widget (button, view, custom). For
  *                  XUL-provided widgets, this is always 'custom';
  * - provider:      the provider type of the widget, id est one of
  *                  PROVIDER_API or PROVIDER_XUL;
  * - forWindow(w):  a method to obtain a single window wrapper for a widget,
  *                  in the window w passed as the only argument;
  * - instances:     an array of all instances (single window wrappers)
  *                  of the widget. This array is NOT live;
  * - areaType:      the type of the widget's current area
  * - isGroup:       true; will be false for wrappers around single widget nodes;
  * - source:        for API-provided widgets, whether they are built-in to
  *                  Firefox or add-on-provided;
  * - disabled:      for API-provided widgets, whether the widget is currently
  *                  disabled. NB: this property is writable, and will toggle
  *                  all the widgets' nodes' disabled states;
  * - label:         for API-provied widgets, the label of the widget;
  * - tooltiptext:   for API-provided widgets, the tooltip of the widget;
  * - showInPrivateBrowsing: for API-provided widgets, whether the widget is
  *                          visible in private browsing;
  * - hideInNonPrivateBrowsing: for API-provided widgets, whether the widget is
  *                             hidden in non-private browsing;
  *
  * Single window wrappers obtained through forWindow(someWindow) or from the
  * instances array have the following properties
  * (all read-only unless otherwise indicated):
  *
  * - id:            the widget's ID;
  * - type:          the type of widget (button, view, custom). For
  *                  XUL-provided widgets, this is always 'custom';
  * - provider:      the provider type of the widget, id est one of
  *                  PROVIDER_API or PROVIDER_XUL;
  * - node:          reference to the corresponding DOM node;
  * - anchor:        the anchor on which to anchor panels opened from this
  *                  node. This will point to the overflow chevron on
  *                  overflowable toolbars if and only if your widget node
  *                  is overflowed, to the anchor for the panel menu
  *                  if your widget is inside the panel menu, and to the
  *                  node itself in all other cases;
  * - overflowed:    boolean indicating whether the node is currently in the
  *                  overflow panel of the toolbar;
  * - isGroup:       false; will be true for the group widget;
  * - label:         for API-provided widgets, convenience getter for the
  *                  label attribute of the DOM node;
  * - tooltiptext:   for API-provided widgets, convenience getter for the
  *                  tooltiptext attribute of the DOM node;
  * - disabled:      for API-provided widgets, convenience getter *and setter*
  *                  for the disabled state of this single widget. Note that
  *                  you may prefer to use the group wrapper's getter/setter
  *                  instead.
  *
  * @param {string} aWidgetId
  *   The ID of the widget whose information you need.
  * @returns {WidgetGroupWrapper|XULWidgetGroupWrapper|null}
  *   A wrapper around the widget as described above, or null if the widget is
  *   known not to exist (anymore). NB: A non-null return is no guarantee the
  *   widget exists because we cannot know in advance if a XUL widget exists or
  *   not.
  */
 getWidget(aWidgetId) {
   return CustomizableUIInternal.wrapWidget(aWidgetId);
 },
 /**
  * Get an array of widget wrappers (see getWidget) for all the widgets
  * which are currently not in any area (so which are in the palette).
  *
  * @param {DOMElement} aWindowPalette
  *   The palette element (and by extension, the window) in which
  *   CustomizableUI should look. This matters because of course XUL-provided
  *   widgets could be available in some windows but not others, and likewise
  *   API-provided widgets might not exist in a private window (because of the
  *   showInPrivateBrowsing property).
  * @returns {Array<WidgetGroupWrapper|XULWidgetGroupWrapper>}
  *   An array of widget wrappers (see getWidget)
  */
 getUnusedWidgets(aWindowPalette) {
   return CustomizableUIInternal.getUnusedWidgets(aWindowPalette).map(
     CustomizableUIInternal.wrapWidget,
     CustomizableUIInternal
   );
 },
 /**
  * Get an array of all the widget IDs placed in an area.
  * Modifying the array will not affect CustomizableUI.
  *
  * NB: will throw if called too early (before placements have been fetched)
  *     or if the area is not currently known to CustomizableUI.
  *
  * @param {string} aArea
  *   The name of the area whose placements you want to obtain.
  * @returns {string[]}
  *   An array containing the widget IDs that are in the area.
  */
 getWidgetIdsInArea(aArea) {
   if (!gAreas.has(aArea)) {
     throw new Error("Unknown customization area: " + aArea);
   }
   if (!gPlacements.has(aArea)) {
     throw new Error(`Area ${aArea} not yet restored`);
   }

   // We need to clone this, as we don't want to let consumers muck with placements
   return [...gPlacements.get(aArea)];
 },
 /**
  * Get an array of all the widget IDs in the default placements for an area.
  * Modifying the array will not affect CustomizableUI.
  *
  * @param {string} aArea
  *   The ID of the area whose default placements you want to obtain.
  * @returns {string[]}
  *   An array containing the widget IDs that are in the default placements for
  *   that area.
  */
 getDefaultPlacementsForArea(aArea) {
   return [...gAreas.get(aArea).get("defaultPlacements")];
 },
 /**
  * Get an array of widget wrappers for all the widgets in an area. This is
  * the same as calling getWidgetIdsInArea and .map() ing the result through
  * CustomizableUI.getWidget. Careful: this means that if there are IDs in there
  * which don't have corresponding DOM nodes, there might be nulls in this array,
  * or items for which wrapper.forWindow(win) will return null.
  *
  * @param {string} aArea
  *   The ID of the area whose widgets you want to obtain.
  * @returns {Array<WidgetGroupWrapper|XULWidgetGroupWrapper|null>}
  *   An array of widget wrappers and/or null values for the widget IDs
  *   placed in an area.
  *
  * NB: will throw if called too early (before placements have been fetched)
  *     or if the area is not currently known to CustomizableUI.
  */
 getWidgetsInArea(aArea) {
   return this.getWidgetIdsInArea(aArea).map(
     CustomizableUIInternal.wrapWidget,
     CustomizableUIInternal
   );
 },

 /**
  * Ensure the customizable widget that matches up with this view node
  * will get the right subview showing/shown/hiding/hidden events when
  * they fire.
  *
  * @param {Element} aViewNode
  *   The view node to add listeners to if they haven't been added already.
  */
 ensureSubviewListeners(aViewNode) {
   return CustomizableUIInternal.ensureSubviewListeners(aViewNode);
 },
 /**
  * Obtain an array of all the area IDs known to CustomizableUI.
  * This array is created for you, so is modifiable without CustomizableUI
  * being affected.
  */
 get areas() {
   return [...gAreas.keys()];
 },
 /**
  * Check what kind of area (toolbar or menu panel) an area is. This is
  * useful if you have a widget that needs to behave differently depending
  * on its location. Note that widget wrappers have a convenience getter
  * property (areaType) for this purpose.
  *
  * @param {string} aArea
  *   The ID of the area whose type you want to know
  * @returns {string}
  *   Returns CustomizableUI.TYPE_TOOLBAR or CustomizableUI.TYPE_PANEL
  *   depending on the area, null if the area is unknown.
  */
 getAreaType(aArea) {
   let area = gAreas.get(aArea);
   return area ? area.get("type") : null;
 },
 /**
  * Check if a toolbar is collapsed by default.
  *
  * @param {string} aArea
  *   The ID of the area whose default-collapsed state you want to know.
  * @returns {boolean}
  *   Returns true if the toolbar area is collapsed by default, false if
  *   not collapsed by default, and null if the area is unknown its collapsed
  *   state cannot normally be controlled by the user.
  */
 isToolbarDefaultCollapsed(aArea) {
   let area = gAreas.get(aArea);
   return area ? area.get("defaultCollapsed") : null;
 },
 /**
  * Obtain the DOM node that is the customize target for an area in a
  * specific window.
  *
  * Areas can have a customization target that does not correspond to the
  * node itself. In particular, toolbars that have a customizationtarget
  * attribute set will have their customization target set to that node.
  * This means widgets will end up in the customization target, not in the
  * DOM node with the ID that corresponds to the area ID. This is useful
  * because it lets you have fixed content in a toolbar (e.g. the panel
  * menu item in the navbar) and have all the customizable widgets use
  * the customization target.
  *
  * Using this API yourself is discouraged; you should generally not need
  * to be asking for the DOM container node used for a particular area.
  * In particular, if you're wanting to check it in relation to a widget's
  * node, your DOM node might not be a direct child of the customize target
  * in a window if, for instance, the window is in customization mode, or if
  * this is an overflowable toolbar and the widget has been overflowed.
  *
  * @param {string} aArea
  *   The ID of the area whose customize target you want to have
  * @param {DOMWindow} aWindow
  *   The window where you want to fetch the DOM node.
  * @returns {Element}
  *   The customize target DOM node for aArea in aWindow
  */
 getCustomizeTargetForArea(aArea, aWindow) {
   return CustomizableUIInternal.getCustomizeTargetForArea(aArea, aWindow);
 },
 /**
  * Reset the customization state back to its default.
  *
  * This is the nuclear option. You should never call this except if the user
  * explicitly requests it. Firefox does this when the user clicks the
  * "Restore Defaults" button in customize mode.
  */
 reset() {
   CustomizableUIInternal.reset();
 },

 /**
  * Undo the previous reset, can only be called immediately after a reset.
  *
  * @returns {Promise<undefined>}
  *   A promise that will be resolved when the operation is complete.
  */
 undoReset() {
   CustomizableUIInternal.undoReset();
 },

 /**
  * Remove a custom toolbar added in a previous version of Firefox or using
  * an add-on. NB: only works on the customizable toolbars generated by
  * the toolbox itself. Intended for use from CustomizeMode, not by
  * other consumers.
  *
  * @param {string} aToolbarId
  *   The ID of the toolbar to remove.
  */
 removeExtraToolbar(aToolbarId) {
   CustomizableUIInternal.removeExtraToolbar(aToolbarId);
 },

 /**
  * Can the last Restore Defaults operation be undone.
  *
  * @returns {boolean}
  *   True if the last Restore Defaults operation can be undone.
  */
 get canUndoReset() {
   return (
     gUIStateBeforeReset.uiCustomizationState != null ||
     gUIStateBeforeReset.drawInTitlebar != null ||
     gUIStateBeforeReset.currentTheme != null ||
     gUIStateBeforeReset.autoTouchMode != null ||
     gUIStateBeforeReset.uiDensity != null ||
     gUIStateBeforeReset.sidebarPositionStart != null
   );
 },

 /**
  * @typedef {object} CustomizableUIPlacementInfo
  * @param {string} area
  *   The ID of the area where the widget is placed.
  * @param {number} position
  *   The 0-indexed position of the widget according to the placements area
  *   of the area that it's in.
  */

 /**
  * Get the placement of a widget. This is by far the best way to obtain
  * information about what the state of your widget is. The internals of
  * this call are cheap (no DOM necessary) and you will know where the user
  * has put your widget.
  *
  * @param {string} aWidgetId
  *   The ID of the widget whose placement you want to know.
  * @param {boolean} [aOnlyRegistered=true]
  *   Set to false to return placements for widgets that aren't registered,
  *   but still exist within the placements state, having been registered and
  *   placed in the past.
  * @param {boolean} [aDeadAreas=false]
  *   Set to true to include placements within "dead" areas that are no longer
  *   registered, but still exist in the placement state.
  * @returns {CustomizableUIPlacementInfo|null}
  *   Returns null if the widget is not placed anywhere (ie in the palette).
  */
 getPlacementOfWidget(aWidgetId, aOnlyRegistered = true, aDeadAreas = false) {
   return CustomizableUIInternal.getPlacementOfWidget(
     aWidgetId,
     aOnlyRegistered,
     aDeadAreas
   );
 },
 /**
  * Check if a widget can be removed from the area it's in.
  *
  * Note that if you're wanting to move the widget somewhere, you should
  * generally be checking canWidgetMoveToArea, because that will return
  * true if the widget is already in the area where you want to move it (!).
  *
  * NB: oh, also, this method might lie if the widget in question is a
  *     XUL-provided widget and there are no windows open, because it
  *     can obviously not check anything in this case. It will return
  *     true. You will be able to move the widget elsewhere. However,
  *     once the user reopens a window, the widget will move back to its
  *     'proper' area automagically.
  *
  * @param {string} aWidgetId
  *   A widget ID or DOM node to check.
  * @returns {boolean}
  *   True if the widget can be removed from its area.
  */
 isWidgetRemovable(aWidgetId) {
   return CustomizableUIInternal.isWidgetRemovable(aWidgetId);
 },
 /**
  * Check if a widget can be moved to a particular area. Like
  * isWidgetRemovable but better, because it'll return true if the widget
  * is already in the right area.
  *
  * @param {string} aWidgetId
  *   The ID of the widget that you want to move somewhere.
  * @param {string} aArea
  *   The area ID you want to move the widget to. This can also be
  *   CustomizableUI.AREA_NO_AREA to see if the widget can move to the
  *   customization palette, whether it's removable or not.
  * @returns {boolean}
  *   True if this is possible. The same caveats as for isWidgetRemovable
  *   apply, however, if no windows are open.
  */
 canWidgetMoveToArea(aWidgetId, aArea) {
   return CustomizableUIInternal.canWidgetMoveToArea(aWidgetId, aArea);
 },
 /**
  * Whether we're in a default state. Note that non-removable non-default
  * widgets and non-existing widgets are not taken into account in determining
  * whether we're in the default state.
  *
  * NB: this is a property with a getter. The getter is NOT cheap, because
  * it does smart things with non-removable non-default items, non-existent
  * items, and so forth. Please don't call unless necessary.
  */
 get inDefaultState() {
   return CustomizableUIInternal.inDefaultState;
 },

 /**
  * Set a toolbar's visibility state in all windows.
  *
  * @param {string} aToolbarId
  *   The toolbar whose visibility should be adjusted.
  * @param {boolean} aIsVisible
  *   Whether the toolbar should be made visible.
  */
 setToolbarVisibility(aToolbarId, aIsVisible) {
   CustomizableUIInternal.setToolbarVisibility(aToolbarId, aIsVisible);
 },

 /**
  * Returns a Set with the IDs of any registered toolbar areas that are
  * currently collapsed in a particular window. Menubars that are set to
  * autohide and are in the temporary "open" state are still considered
  * collapsed by default.
  *
  * @param {Window} window The browser window to check for collapsed toolbars.
  * @returns {Set<string>}
  */
 getCollapsedToolbarIds(window) {
   return CustomizableUIInternal.getCollapsedToolbarIds(window);
 },

 /**
  * Checks if a widget is likely visible in a given window.
  *
  * This method returns true when a widget is:
  *  - Not pinned to the overflow menu
  *  - Not in a collapsed toolbar (e.g. bookmarks toolbar, menu bar)
  *  - Not in the customization palette
  *
  * Note: A widget that is moved into the overflow menu due to
  *       the window being small might be considered visible by
  *       this method, because a widget's placement does not
  *       change when it overflows into the overflow menu.
  *
  * @param {string} aWidgetId the widget ID to check.
  * @param {Window} window The browser window to check for widget visibility.
  * @returns {boolean} whether the given widget is likely visible or not.
  */
 widgetIsLikelyVisible(aWidgetId, window) {
   return CustomizableUIInternal.widgetIsLikelyVisible(aWidgetId, window);
 },

 /**
  * DEPRECATED! Use fluent instead.
  *
  * Get a localized property off a (widget?) object.
  *
  * NB: this is unlikely to be useful unless you're in Firefox code, because
  *     this code uses the builtin widget stringbundle, and can't be told
  *     to use add-on-provided strings. It's mainly here as convenience for
  *     custom builtin widgets that build their own DOM but use the same
  *     stringbundle as the other builtin widgets.
  *
  * @param {string|object} aWidget
  *   The ID of a widget, or a widget object whose properties we should use to
  *   fetch a localizable string.
  * @param {string} aProp
  *   The property on the object to use for the fetching from
  *   customizableWidgets.properties.
  * @param {string[]} [aFormatArgs]
  *   Any extra arguments to use for a formatted string.
  * @param {string} [aDef]
  *   The default to return if we don't find the string in the stringbundle.
  * @returns {string}
  *   The localized string, or aDef if the string isn't in the bundle. If no
  *   default is provided, if aProp exists on aWidget, we'll return that,
  *   otherwise we'll return the empty string.
  */
 getLocalizedProperty(aWidget, aProp, aFormatArgs, aDef) {
   return CustomizableUIInternal.getLocalizedProperty(
     aWidget,
     aProp,
     aFormatArgs,
     aDef
   );
 },
 /**
  * Utility function to detect, find and set a keyboard shortcut for a menuitem
  * or (toolbar)button.
  *
  * @param {Element} aShortcutNode
  *   The XUL node where the shortcut will be derived from;
  * @param {Element|null} aTargetNode
  *   The XUL node on which the `shortcut` attribute will be set. If NULL, the
  *   shortcut will be set on aShortcutNode.
  */
 addShortcut(aShortcutNode, aTargetNode) {
   return CustomizableUIInternal.addShortcut(aShortcutNode, aTargetNode);
 },
 /**
  * Given a node, walk up to the first panel in its ancestor chain, and
  * close it.
  *
  * @param {Element} aNode a node whose panel should be closed.
  */
 hidePanelForNode(aNode) {
   CustomizableUIInternal.hidePanelForNode(aNode);
 },
 /**
  * Check if a widget is a "special" widget: a spring, spacer or separator.
  *
  * @param {string} aWidgetId the widget ID to check.
  * @returns {boolean} true if the widget is 'special', false otherwise.
  */
 isSpecialWidget(aWidgetId) {
   return CustomizableUIInternal.isSpecialWidget(aWidgetId);
 },
 /**
  * Check if a widget is provided by an extension. This effectively checks
  * whether `webExtension: true` passed when the widget was being created.
  *
  * If the widget being referred to hasn't yet been created, or has been
  * destroyed, we fallback to checking the ID for the "-browser-action"
  * suffix.
  *
  * @param {string} aWidgetId the widget ID to check.
  * @returns {boolean}
  *   True if the widget was provided by an extension, false otherwise.
  */
 isWebExtensionWidget(aWidgetId) {
   if (typeof aWidgetId !== "string") {
     return false;
   }
   let widget = CustomizableUI.getWidget(aWidgetId);
   return widget?.webExtension || aWidgetId.endsWith("-browser-action");
 },
 /**
  * Add listeners to a panel that will close it. For use from the menu panel
  * and overflowable toolbar implementations, unlikely to be useful for other
  * consumers.
  *
  * @param {Element} aPanel
  *   The panel to which listeners should be attached.
  */
 addPanelCloseListeners(aPanel) {
   CustomizableUIInternal.addPanelCloseListeners(aPanel);
 },
 /**
  * Remove close listeners that have been added to a panel with
  * addPanelCloseListeners. For use from the menu panel and overflowable
  * toolbar implementations, unlikely to be useful for consumers.
  *
  * @param {Element} aPanel
  *   The panel from which listeners should be removed.
  */
 removePanelCloseListeners(aPanel) {
   CustomizableUIInternal.removePanelCloseListeners(aPanel);
 },
 /**
  * Notify listeners a widget is about to be dragged to an area. For use from
  * Customize Mode only, do not use otherwise.
  *
  * @param {string} aWidgetId
  *   The ID of the widget that is being dragged to an area.
  * @param {string} aArea
  *   The ID of the area to which the widget is being dragged.
  */
 onWidgetDrag(aWidgetId, aArea) {
   CustomizableUIInternal.notifyListeners("onWidgetDrag", aWidgetId, aArea);
 },
 /**
  * Notify listeners that a window is entering customize mode. For use from
  * Customize Mode only, do not use otherwise.
  *
  * @param {DOMWindow} aWindow
  *   The window entering customize mode.
  */
 notifyStartCustomizing(aWindow) {
   CustomizableUIInternal.notifyListeners("onCustomizeStart", aWindow);
 },
 /**
  * Notify listeners that a window is exiting customize mode. For use from
  * Customize Mode only, do not use otherwise.
  *
  * @param {DOMWindow} aWindow
  *   The window exiting customize mode.
  */
 notifyEndCustomizing(aWindow) {
   CustomizableUIInternal.notifyListeners("onCustomizeEnd", aWindow);
 },

 /**
  * Notify toolbox(es) of a particular event. If you don't pass aWindow,
  * all toolboxes will be notified. For use from Customize Mode only,
  * do not use otherwise.
  *
  * @param {string} aEvent
  *   The name of the event to send.
  * @param {object} [aDetails={}]
  *   The details of the event.
  * @param {DOMWindow|null} [aWindow=null]
  *   The window in which to send the event.
  */
 dispatchToolboxEvent(aEvent, aDetails = {}, aWindow = null) {
   CustomizableUIInternal.dispatchToolboxEvent(aEvent, aDetails, aWindow);
 },

 /**
  * Check whether an area is overflowable.
  *
  * @param {string} aAreaId
  *   The ID of an area to check for overflowable-ness.
  * @returns {boolean}
  *   True if the area is overflowable, false otherwise.
  */
 isAreaOverflowable(aAreaId) {
   let area = gAreas.get(aAreaId);
   return area
     ? area.get("type") == this.TYPE_TOOLBAR && area.get("overflowable")
     : false;
 },
 /**
  * Obtain a string indicating the place of an element. This is intended
  * for use from customize mode; You should generally use getPlacementOfWidget
  * instead, which is cheaper because it does not use the DOM.
  *
  * @param {DOMElement} aElement
  *   The DOM node whose place we need to check.
  * @returns {string|undefined}
  *   "toolbar" if the node is in a toolbar, "panel" if it is in the menu
  *   panel, "palette" if it is in the (visible!) customization palette,
  *   undefined otherwise.
  */
 getPlaceForItem(aElement) {
   let place;
   let node = aElement;
   while (node && !place) {
     if (node.localName == "toolbar") {
       place = "toolbar";
     } else if (node.id == CustomizableUI.AREA_FIXED_OVERFLOW_PANEL) {
       place = "panel";
     } else if (node.id == "customization-palette") {
       place = "palette";
     }

     node = node.parentNode;
   }
   return place;
 },

 /**
  * Check if a toolbar is builtin or not.
  *
  * @param {string} aToolbarId
  *   The ID of the toolbar you want to check.
  */
 isBuiltinToolbar(aToolbarId) {
   return CustomizableUIInternal.builtinToolbars.has(aToolbarId);
 },

 /**
  * Create an instance of a spring, spacer or separator.
  *
  * @param {string} aId
  *   The type of special widget (spring, spacer or separator).
  * @param {Document} aDocument
  *   The document in which to create it.
  * @returns {Element}
  *   The created spring, spacer or separator node.
  */
 createSpecialWidget(aId, aDocument) {
   return CustomizableUIInternal.createSpecialWidget(aId, aDocument);
 },

 /**
  * Fills a submenu with menu items.
  *
  * @param {Element[]} aMenuItems
  *   The array of menu items to display.
  * @param {Element} aSubview
  *   The subview to fill with the menu items.
  */
 fillSubviewFromMenuItems(aMenuItems, aSubview) {
   let attrs = [
     "oncommand",
     "onclick",
     "label",
     "key",
     "disabled",
     "command",
     "observes",
     "hidden",
     "class",
     "origin",
     "image",
     "checked",
     "style",
   ];

   // Use ownerGlobal.document to ensure we get the right doc even for
   // elements in template tags.
   let doc = aSubview.ownerGlobal.document;
   let fragment = doc.createDocumentFragment();
   for (let menuChild of aMenuItems) {
     if (menuChild.hidden) {
       continue;
     }

     let subviewItem;
     if (menuChild.localName == "menuseparator") {
       // Don't insert duplicate or leading separators. This can happen if there are
       // menus (which we don't copy) above the separator.
       if (
         !fragment.lastElementChild ||
         fragment.lastElementChild.localName == "toolbarseparator"
       ) {
         continue;
       }
       subviewItem = doc.createXULElement("toolbarseparator");
     } else if (menuChild.localName == "menuitem") {
       subviewItem = doc.createXULElement("toolbarbutton");
       CustomizableUI.addShortcut(menuChild, subviewItem);

       let item = menuChild;
       if (!item.hasAttribute("onclick")) {
         subviewItem.addEventListener("click", event => {
           let newEvent = new doc.ownerGlobal.PointerEvent("click", event);

           // Telemetry should only pay attention to the original event.
           lazy.BrowserUsageTelemetry.ignoreEvent(newEvent);
           item.dispatchEvent(newEvent);
         });
       }

       if (!item.hasAttribute("oncommand")) {
         subviewItem.addEventListener("command", event => {
           let newEvent = doc.createEvent("XULCommandEvent");
           newEvent.initCommandEvent(
             event.type,
             event.bubbles,
             event.cancelable,
             event.view,
             event.detail,
             event.ctrlKey,
             event.altKey,
             event.shiftKey,
             event.metaKey,
             0,
             event.sourceEvent,
             0
           );

           // Telemetry should only pay attention to the original event.
           lazy.BrowserUsageTelemetry.ignoreEvent(newEvent);
           item.dispatchEvent(newEvent);
         });
       }
     } else {
       continue;
     }
     for (let attr of attrs) {
       let attrVal = menuChild.getAttribute(attr);
       if (attrVal) {
         subviewItem.setAttribute(attr, attrVal);
       }
     }
     // We do this after so the .subviewbutton class doesn't get overriden.
     if (menuChild.localName == "menuitem") {
       subviewItem.classList.add("subviewbutton");
     }

     // We make it possible to supply an alternative Fluent key when cloning
     // this menuitem into the AppMenu or panel contexts. This is because
     // we often use Title Case in menuitems in native menus, but want to use
     // Sentence case in the AppMenu / panels.
     let l10nId = menuChild.getAttribute("appmenu-data-l10n-id");
     if (l10nId) {
       doc.l10n.setAttributes(subviewItem, l10nId);
     }

     fragment.appendChild(subviewItem);
   }
   aSubview.appendChild(fragment);
 },

 /**
  * A helper function for clearing subviews.
  *
  * @param {Element} aSubview
  *   The subview to clear.
  */
 clearSubview(aSubview) {
   let parent = aSubview.parentNode;
   // We'll take the container out of the document before cleaning it out
   // to avoid reflowing each time we remove something.
   parent.removeChild(aSubview);

   while (aSubview.firstChild) {
     aSubview.firstChild.remove();
   }

   parent.appendChild(aSubview);
 },

 /**
  * Called when DOMContentLoaded fires for a new browser window.
  *
  * @param {DOMWindow} aWindow
  *   The DOM Window that has just opened.
  */
 handleNewBrowserWindow(aWindow) {
   return CustomizableUIInternal.handleNewBrowserWindow(aWindow);
 },

 /**
  * Given a DOM node with the `customizable` attribute, will attempt to resolve
  * it to the associated "customization target" for that DOM node via its
  * `customizationtarget` attribute. If no such attribute exists, the DOM node
  * itself is returned.
  *
  * If the DOM node is null, is not customizable, or cannot be resolved to
  * a customization target, then null is returned.
  *
  * @param {Element|null} aElement
  *   The DOM node to resolve to a customization target DOM node.
  * @returns {Element|null}
  *   The customization target DOM node, or null if one cannot be found.
  */
 getCustomizationTarget(aElement) {
   return CustomizableUIInternal.getCustomizationTarget(aElement);
 },

 /**
  * This is a test-only method that allows tests to violate encapsulation and
  * gain access to some state internal to this module. If not running in test
  * automation, this will always return null.
  *
  * @param {string} aProp
  *   The string representation of the internal property to retrieve. Only some
  *   properties are supported - see the method code.
  * @returns {any|null}
  */
 getTestOnlyInternalProp(aProp) {
   if (!Cu.isInAutomation) {
     return null;
   }
   switch (aProp) {
     case "CustomizableUIInternal":
       return CustomizableUIInternal;
     case "gAreas":
       return gAreas;
     case "gFuturePlacements":
       return gFuturePlacements;
     case "gPalette":
       return gPalette;
     case "gPlacements":
       return gPlacements;
     case "gSavedState":
       return gSavedState;
     case "gSeenWidgets":
       return gSeenWidgets;
     case "kVersion":
       return kVersion;
   }
   return null;
 },

 /**
  * This is a test-only method that allows tests to violate encapsulation and
  * write to some state internal to this module. If not running in test
  * automation, this will always just immediately return without making any
  * changes.
  *
  * @param {string} aProp
  *   The string representation of the internal property to change. Only some
  *   properties are supported - see the method code.
  * @param {any} aValue
  *   The value to set the property to.
  */
 setTestOnlyInternalProp(aProp, aValue) {
   if (!Cu.isInAutomation) {
     return;
   }
   switch (aProp) {
     case "gSavedState":
       gSavedState = aValue;
       break;
     case "kVersion":
       kVersion = aValue;
       break;
     case "gDirty":
       gDirty = aValue;
       break;
   }
 },
};

Object.freeze(CustomizableUI);
Object.freeze(CustomizableUI.windows);

/**
* All external consumers of widgets are really interacting with these wrappers
* which provide a common interface.
*/

/**
* WidgetGroupWrapper is the common interface for interacting with an entire
* widget group - AKA, all instances of a widget across a series of windows.
* This particular wrapper is only used for widgets created via the provider
* API.
*/
function WidgetGroupWrapper(aWidget) {
 this.isGroup = true;

 const kBareProps = [
   "id",
   "source",
   "type",
   "disabled",
   "label",
   "tooltiptext",
   "showInPrivateBrowsing",
   "hideInNonPrivateBrowsing",
   "viewId",
   "disallowSubView",
   "webExtension",
 ];
 for (let prop of kBareProps) {
   let propertyName = prop;
   this.__defineGetter__(propertyName, () => aWidget[propertyName]);
 }

 this.__defineGetter__("provider", () => CustomizableUI.PROVIDER_API);

 this.__defineSetter__("disabled", function (aValue) {
   aValue = !!aValue;
   aWidget.disabled = aValue;
   for (let [, instance] of aWidget.instances) {
     instance.disabled = aValue;
   }
 });

 this.forWindow = function WidgetGroupWrapper_forWindow(aWindow) {
   let wrapperMap;
   if (!gSingleWrapperCache.has(aWindow)) {
     wrapperMap = new Map();
     gSingleWrapperCache.set(aWindow, wrapperMap);
   } else {
     wrapperMap = gSingleWrapperCache.get(aWindow);
   }
   if (wrapperMap.has(aWidget.id)) {
     return wrapperMap.get(aWidget.id);
   }

   let instance = aWidget.instances.get(aWindow.document);
   if (!instance) {
     instance = CustomizableUIInternal.buildWidgetNode(
       aWindow.document,
       aWidget
     );
   }

   let wrapper = new WidgetSingleWrapper(aWidget, instance);
   wrapperMap.set(aWidget.id, wrapper);
   return wrapper;
 };

 this.__defineGetter__("instances", function () {
   // Can't use gBuildWindows here because some areas load lazily:
   let placement = CustomizableUIInternal.getPlacementOfWidget(aWidget.id);
   if (!placement) {
     return [];
   }
   let area = placement.area;
   let buildAreas = gBuildAreas.get(area);
   if (!buildAreas) {
     return [];
   }
   return Array.from(buildAreas, node => this.forWindow(node.ownerGlobal));
 });

 this.__defineGetter__("areaType", function () {
   let areaProps = gAreas.get(aWidget.currentArea);
   return areaProps && areaProps.get("type");
 });

 Object.freeze(this);
}

/**
* A WidgetSingleWrapper is a wrapper around a single instance of a widget in
* a particular window.
*/
function WidgetSingleWrapper(aWidget, aNode) {
 this.isGroup = false;

 this.node = aNode;
 this.provider = CustomizableUI.PROVIDER_API;

 const kGlobalProps = ["id", "type"];
 for (let prop of kGlobalProps) {
   this[prop] = aWidget[prop];
 }

 const kNodeProps = ["label", "tooltiptext"];
 for (let prop of kNodeProps) {
   let propertyName = prop;
   // Look at the node for these, instead of the widget data, to ensure the
   // wrapper always reflects this live instance.
   this.__defineGetter__(propertyName, () => aNode.getAttribute(propertyName));
 }

 this.__defineGetter__("disabled", () => aNode.disabled);
 this.__defineSetter__("disabled", function (aValue) {
   aNode.disabled = !!aValue;
 });

 this.__defineGetter__("anchor", function () {
   let anchorId;
   // First check for an anchor for the area:
   let placement = CustomizableUIInternal.getPlacementOfWidget(aWidget.id);
   if (placement) {
     anchorId = gAreas.get(placement.area).get("anchor");
   }
   if (!anchorId) {
     anchorId = aNode.getAttribute("cui-anchorid");
   }
   if (!anchorId) {
     anchorId = aNode.getAttribute("view-button-id");
   }
   if (anchorId) {
     return aNode.ownerDocument.getElementById(anchorId);
   }
   if (aWidget.type == "button-and-view") {
     return aNode.lastElementChild;
   }
   return aNode;
 });

 this.__defineGetter__("overflowed", function () {
   return aNode.getAttribute("overflowedItem") == "true";
 });

 Object.freeze(this);
}

/**
* XULWidgetGroupWrapper is the common interface for interacting with an entire
* widget group - AKA, all instances of a widget across a series of windows.
* This particular wrapper is only used for widgets created via the old-school
* XUL method (overlays, or programmatically injecting toolbaritems, or other
* such things).
*/
// XXXunf Going to need to hook this up to some events to keep it all live.
function XULWidgetGroupWrapper(aWidgetId) {
 this.isGroup = true;
 this.id = aWidgetId;
 this.type = "custom";
 // XUL Widgets can never be provided by extensions.
 this.webExtension = false;
 this.provider = CustomizableUI.PROVIDER_XUL;

 this.forWindow = function XULWidgetGroupWrapper_forWindow(aWindow) {
   let wrapperMap;
   if (!gSingleWrapperCache.has(aWindow)) {
     wrapperMap = new Map();
     gSingleWrapperCache.set(aWindow, wrapperMap);
   } else {
     wrapperMap = gSingleWrapperCache.get(aWindow);
   }
   if (wrapperMap.has(aWidgetId)) {
     return wrapperMap.get(aWidgetId);
   }

   let instance = aWindow.document.getElementById(aWidgetId);
   if (!instance) {
     // Toolbar palettes aren't part of the document, so elements in there
     // won't be found via document.getElementById().
     instance = aWindow.gNavToolbox.palette.getElementsByAttribute(
       "id",
       aWidgetId
     )[0];
   }

   let wrapper = new XULWidgetSingleWrapper(
     aWidgetId,
     instance,
     aWindow.document
   );
   wrapperMap.set(aWidgetId, wrapper);
   return wrapper;
 };

 this.__defineGetter__("areaType", function () {
   let placement = CustomizableUIInternal.getPlacementOfWidget(aWidgetId);
   if (!placement) {
     return null;
   }

   let areaProps = gAreas.get(placement.area);
   return areaProps && areaProps.get("type");
 });

 this.__defineGetter__("instances", function () {
   return Array.from(gBuildWindows, wins => this.forWindow(wins[0]));
 });

 Object.freeze(this);
}

/**
* A XULWidgetSingleWrapper is a wrapper around a single instance of a XUL
* widget in a particular window.
*/
function XULWidgetSingleWrapper(aWidgetId, aNode, aDocument) {
 this.isGroup = false;

 this.id = aWidgetId;
 this.type = "custom";
 this.provider = CustomizableUI.PROVIDER_XUL;

 let weakDoc = Cu.getWeakReference(aDocument);
 // If we keep a strong ref, the weak ref will never die, so null it out:
 aDocument = null;

 this.__defineGetter__("node", function () {
   // If we've set this to null (further down), we're sure there's nothing to
   // be gotten here, so bail out early:
   if (!weakDoc) {
     return null;
   }
   if (aNode) {
     // Return the last known node if it's still in the DOM...
     if (aNode.isConnected) {
       return aNode;
     }
     // ... or the toolbox
     let toolbox = aNode.ownerGlobal.gNavToolbox;
     if (toolbox && toolbox.palette && aNode.parentNode == toolbox.palette) {
       return aNode;
     }
     // If it isn't, clear the cached value and fall through to the "slow" case:
     aNode = null;
   }

   let doc = weakDoc.get();
   if (doc) {
     // Store locally so we can cache the result:
     aNode = CustomizableUIInternal.findXULWidgetInWindow(
       aWidgetId,
       doc.defaultView
     );
     return aNode;
   }
   // The weakref to the document is dead, we're done here forever more:
   weakDoc = null;
   return null;
 });

 this.__defineGetter__("anchor", function () {
   let anchorId;
   // First check for an anchor for the area:
   let placement = CustomizableUIInternal.getPlacementOfWidget(aWidgetId);
   if (placement) {
     anchorId = gAreas.get(placement.area).get("anchor");
   }

   let node = this.node;
   if (!anchorId && node) {
     anchorId = node.getAttribute("cui-anchorid");
   }

   return anchorId && node
     ? node.ownerDocument.getElementById(anchorId)
     : node;
 });

 this.__defineGetter__("overflowed", function () {
   let node = this.node;
   if (!node) {
     return false;
   }
   return node.getAttribute("overflowedItem") == "true";
 });

 Object.freeze(this);
}

/**
* OverflowableToolbar is a class that gives a <xul:toolbar> the ability to send
* toolbar items that are "overflowable" to lists in separate panels if and
* when the toolbar shrinks enough so that those items overflow out of bounds.
* Secondly, this class manages moving things out from those panels and back
* into the toolbar once it underflows and has the space to accommodate the
* items that had originally overflowed out.
*
* There are two panels that toolbar items can be overflowed to:
*
* 1. The default items overflow panel
*   This is where built-in default toolbar items will go to.
* 2. The Unified Extensions panel
*   This is where browser_action toolbar buttons created by extensions will
*   go to if the Unified Extensions UI is enabled - otherwise, those items will
*   go to the default items overflow panel.
*
* Finally, OverflowableToolbar manages the showing of the default items
* overflow panel when the associated anchor is clicked or dragged over. The
* Unified Extensions panel is managed separately by the extension code.
*
* In theory, we could have multiple overflowable toolbars, but in practice,
* only the nav-bar (CustomizableUI.AREA_NAVBAR) makes use of this class.
*/
class OverflowableToolbar {
 /**
  * The OverflowableToolbar class is constructed during browser window
  * creation, but to optimize for window painting, we defer most work until
  * after the window has painted. This property is set to true once
  * initialization has completed.
  *
  * @type {boolean}
  */
 #initialized = false;

 /**
  * A reference to the <xul:toolbar> that is overflowable.
  *
  * @type {Element}
  */
 #toolbar = null;

 /**
  * A reference to the part of the <xul:toolbar> that accepts CustomizableUI
  * widgets.
  *
  * @type {Element}
  */
 #target = null;

 /**
  * A mapping from the ID of a toolbar item that has overflowed to the width
  * that the toolbar item occupied in the toolbar at the time of overflow. Any
  * item that is currently overflowed will have an entry in this map.
  *
  * @type {Map<string, number>}
  */
 #overflowedInfo = new Map();

 /**
  * The set of overflowed DOM nodes that were hidden at the time of overflowing.
  */
 #hiddenOverflowedNodes = new WeakSet();

 /**
  * True if the overflowable toolbar is actively handling overflows and
  * underflows. This value is set internally by the private #enable() and
  * #disable() methods.
  *
  * @type {boolean}
  */
 #enabled = true;

 /**
  * A reference to the element that overflowed toolbar items will be
  * appended to as children upon overflow.
  *
  * @type {Element}
  */
 #defaultList = null;

 /**
  * A reference to the button that opens the overflow panel. This is also
  * the element that the panel will anchor to.
  *
  * @type {Element}
  */
 #defaultListButton = null;

 /**
  * A reference to the <xul:panel> overflow panel that contains the #defaultList
  * element.
  *
  * @type {Element}
  */
 #defaultListPanel = null;

 /**
  * A reference to the the element that overflowed extension browser action
  * toolbar items will be appended to as children upon overflow if the
  * Unified Extension UI is enabled. This is created lazily and might be null,
  * so you should use the #webExtList memoizing getter instead to get this.
  *
  * @type {Element|null}
  */
 #webExtListRef = null;

 /**
  * An empty object that is created in #checkOverflow to identify individual
  * calls to #checkOverflow and avoid re-entrancy (since #checkOverflow is
  * asynchronous, and in theory, could be called multiple times before any of
  * those times have a chance to fully exit).
  *
  * @type {object}
  */
 #checkOverflowHandle = null;

 /**
  * A timeout ID returned by setTimeout that identifies a timeout function that
  * runs to hide the #defaultListPanel if the user happened to open the panel by dragging
  * over the #defaultListButton and then didn't hover any part of the #defaultListPanel.
  *
  * @type {number}
  */
 #hideTimeoutId = null;

 /**
  * Public methods start here.
  */

 /**
  * OverflowableToolbar constructor. This is run very early on in the lifecycle
  * of a browser window, so it tries to defer most work to the init() method
  * instead after first paint.
  *
  * Upon construction, a "overflowable" attribute will be set on the
  * toolbar, set to the value of "true".
  *
  * Part of the API for OverflowableToolbar is declarative, in that it expects
  * certain attributes to be set on the <xul:toolbar> that is overflowable.
  * Those attributes are:
  *
  * default-overflowbutton:
  *   The ID of the button that is used to open and anchor the overflow panel.
  * default-overflowtarget:
  *   The ID of the element that overflowed items will be appended to as
  *   children. Note that the overflowed toolbar items are moved into and out
  *   of this overflow target, so it is definitely advisable to let
  *   OverflowableToolbar own managing the children of default-overflowtarget,
  *   and to not modify it outside of this class.
  * default-overflowpanel:
  *   The ID of the <xul:panel> that contains the default-overflowtarget.
  * addon-webext-overflowbutton:
  *   The ID of the button that is used to open and anchor the Unified
  *   Extensions panel.
  * addon-webext-overflowtarget:
  *   The ID of the element that overflowed extension toolbar buttons will
  *   be appended to as children if the Unified Extensions UI is enabled.
  *   Note that the overflowed toolbar items are moved into and out of this
  *   overflow target, so it is definitely advisable to let OverflowableToolbar
  *   own managing the children of addon-webext-overflowtarget, and to not
  *   modify it outside of this class.
  *
  * @param {Element} aToolbarNode The <xul:toolbar> that will be overflowable.
  * @throws {Error} Throws if the customization target of the toolbar somehow
  *   isn't a direct descendent of the toolbar.
  */
 constructor(aToolbarNode) {
   this.#toolbar = aToolbarNode;
   this.#target = CustomizableUI.getCustomizationTarget(this.#toolbar);
   if (this.#target.parentNode != this.#toolbar) {
     throw new Error(
       "Customization target must be a direct child of an overflowable toolbar."
     );
   }

   this.#toolbar.setAttribute("overflowable", "true");
   let doc = this.#toolbar.ownerDocument;
   this.#defaultList = doc.getElementById(
     this.#toolbar.getAttribute("default-overflowtarget")
   );
   this.#defaultList._customizationTarget = this.#defaultList;

   let window = this.#toolbar.ownerGlobal;

   if (window.gBrowserInit.delayedStartupFinished) {
     this.init();
   } else {
     Services.obs.addObserver(this, "browser-delayed-startup-finished");
   }
 }

 /**
  * Does final initialization of the OverflowableToolbar after the window has
  * first painted. This will also kick off the first check to see if overflow
  * has already occurred at the time of initialization.
  */
 init() {
   let doc = this.#toolbar.ownerDocument;
   let window = doc.defaultView;
   window.addEventListener("resize", this);
   window.gNavToolbox.addEventListener("customizationstarting", this);
   window.gNavToolbox.addEventListener("aftercustomization", this);

   let defaultListButton = this.#toolbar.getAttribute(
     "default-overflowbutton"
   );
   this.#defaultListButton = doc.getElementById(defaultListButton);
   this.#defaultListButton.addEventListener("mousedown", this);
   this.#defaultListButton.addEventListener("keypress", this);
   this.#defaultListButton.addEventListener("dragover", this);
   this.#defaultListButton.addEventListener("dragend", this);

   let panelId = this.#toolbar.getAttribute("default-overflowpanel");
   this.#defaultListPanel = doc.getElementById(panelId);
   this.#defaultListPanel.addEventListener("popuphiding", this);
   CustomizableUIInternal.addPanelCloseListeners(this.#defaultListPanel);

   CustomizableUI.addListener(this);

   this.#checkOverflow();

   this.#initialized = true;
 }

 /**
  * Almost the exact reverse of init(). This is called when the browser window
  * is unloading.
  */
 uninit() {
   this.#toolbar.removeAttribute("overflowable");

   if (!this.#initialized) {
     Services.obs.removeObserver(this, "browser-delayed-startup-finished");
     Services.prefs.removeObserver(kPrefSidebarVerticalTabsEnabled, this);
     Services.prefs.removeObserver(kPrefSidebarRevampEnabled, this);
     return;
   }

   this.#disable();

   let window = this.#toolbar.ownerGlobal;
   window.removeEventListener("resize", this);
   window.gNavToolbox.removeEventListener("customizationstarting", this);
   window.gNavToolbox.removeEventListener("aftercustomization", this);
   this.#defaultListButton.removeEventListener("mousedown", this);
   this.#defaultListButton.removeEventListener("keypress", this);
   this.#defaultListButton.removeEventListener("dragover", this);
   this.#defaultListButton.removeEventListener("dragend", this);
   this.#defaultListPanel.removeEventListener("popuphiding", this);

   CustomizableUI.removeListener(this);
   CustomizableUIInternal.removePanelCloseListeners(this.#defaultListPanel);
 }

 /**
  * Opens the overflow #defaultListPanel if it's not already open. If the panel is in
  * the midst of hiding when this is called, the panel will be re-opened.
  *
  * @returns {Promise<undefined>}
  *  Resolves once the panel is open.
  */
 show(aEvent) {
   if (this.#defaultListPanel.state == "open") {
     return Promise.resolve();
   }
   return new Promise(resolve => {
     let doc = this.#defaultListPanel.ownerDocument;
     this.#defaultListPanel.hidden = false;
     let multiview = this.#defaultListPanel.querySelector("panelmultiview");
     let mainViewId = multiview.getAttribute("mainViewId");
     let mainView = doc.getElementById(mainViewId);
     let contextMenu = doc.getElementById(mainView.getAttribute("context"));
     contextMenu.addEventListener("command", this, {
       capture: true,
       mozSystemGroup: true,
     });
     let anchor = this.#defaultListButton.icon;

     let popupshown = false;
     this.#defaultListPanel.addEventListener(
       "popupshown",
       () => {
         popupshown = true;
         this.#defaultListPanel.addEventListener("dragover", this);
         this.#defaultListPanel.addEventListener("dragend", this);
         // Wait until the next tick to resolve so all popupshown
         // handlers have a chance to run before our promise resolution
         // handlers do.
         Services.tm.dispatchToMainThread(resolve);
       },
       { once: true }
     );

     let openPanel = () => {
       // Ensure we update the gEditUIVisible flag when opening the popup, in
       // case the edit controls are in it.
       this.#defaultListPanel.addEventListener(
         "popupshowing",
         () => {
           doc.defaultView.updateEditUIVisibility();
         },
         { once: true }
       );

       this.#defaultListPanel.addEventListener(
         "popuphidden",
         () => {
           if (!popupshown) {
             // The panel was hidden again before it was shown. This can break
             // consumers waiting for the panel to show. So we try again.
             openPanel();
           }
         },
         { once: true }
       );

       lazy.PanelMultiView.openPopup(
         this.#defaultListPanel,
         anchor || this.#defaultListButton,
         {
           triggerEvent: aEvent,
         }
       );
       this.#defaultListButton.open = true;
     };

     openPanel();
   });
 }

 /**
  * Exposes whether #checkOverflow is currently running.
  *
  * @returns {boolean} True if #checkOverflow is currently running.
  */
 isHandlingOverflow() {
   return !!this.#checkOverflowHandle;
 }

 /**
  * Finds the most appropriate place to insert toolbar item aNode if we've been
  * asked to put it into the overflowable toolbar without being told exactly
  * where.
  *
  * @param {Element} aNode The toolbar item being inserted.
  * @returns {Array} [parent, nextNode]
  *   parent: {Element} The parent element that should contain aNode.
  *   nextNode: {Element|null} The node that should follow aNode after
  *     insertion, if any. If this is null, aNode should be placed at the end
  *     of parent.
  */
 findOverflowedInsertionPoints(aNode) {
   let newNodeCanOverflow = aNode.getAttribute("overflows") != "false";
   let areaId = this.#toolbar.id;
   let placements = gPlacements.get(areaId);
   let nodeIndex = placements.indexOf(aNode.id);
   let nodeBeforeNewNodeIsOverflown = false;

   let loopIndex = -1;
   // Loop through placements to find where to insert this item.
   // As soon as we find an overflown widget, we will only
   // insert in the overflow panel (this is why we check placements
   // before the desired location for the new node). Once we pass
   // the desired location of the widget, we look for placement ids
   // that actually have DOM equivalents to insert before. If all
   // else fails, we insert at the end of either the overflow list
   // or the toolbar target.
   while (++loopIndex < placements.length) {
     let nextNodeId = placements[loopIndex];
     if (loopIndex > nodeIndex) {
       // Note that if aNode is in a template, its `ownerDocument` is *not*
       // going to be the browser.xhtml document, so we cannot rely on it.
       let nextNode = this.#toolbar.ownerDocument.getElementById(nextNodeId);
       // If the node we're inserting can overflow, and the next node
       // in the toolbar is overflown, we should insert this node
       // in the overflow panel before it.
       if (
         newNodeCanOverflow &&
         this.#overflowedInfo.has(nextNodeId) &&
         nextNode &&
         nextNode.parentNode == this.#defaultList
       ) {
         return [this.#defaultList, nextNode];
       }
       // Otherwise (if either we can't overflow, or the previous node
       // wasn't overflown), and the next node is in the toolbar itself,
       // insert the node in the toolbar.
       if (
         (!nodeBeforeNewNodeIsOverflown || !newNodeCanOverflow) &&
         nextNode &&
         (nextNode.parentNode == this.#target ||
           // Also check if the next node is in a customization wrapper
           // (toolbarpaletteitem). We don't need to do this for the
           // overflow case because overflow is disabled in customize mode.
           (nextNode.parentNode.localName == "toolbarpaletteitem" &&
             nextNode.parentNode.parentNode == this.#target))
       ) {
         return [this.#target, nextNode];
       }
     } else if (
       loopIndex < nodeIndex &&
       this.#overflowedInfo.has(nextNodeId)
     ) {
       nodeBeforeNewNodeIsOverflown = true;
     }
   }

   let overflowList = CustomizableUI.isWebExtensionWidget(aNode.id)
     ? this.#webExtList
     : this.#defaultList;

   let containerForAppending =
     this.#overflowedInfo.size && newNodeCanOverflow
       ? overflowList
       : this.#target;
   return [containerForAppending, null];
 }

 /**
  * Allows callers to query for the current parent of a toolbar item that may
  * or may not be overflowed. That parent will either be #defaultList,
  * #webExtList (if it's an extension button) or #target.
  *
  * Note: It is assumed that the caller has verified that aNode is placed
  * within the toolbar customizable area according to CustomizableUI.
  *
  * @param {Element} aNode the node that can be overflowed by this
  *   OverflowableToolbar.
  * @returns {Element} The current containing node for aNode.
  */
 getContainerFor(aNode) {
   if (aNode.getAttribute("overflowedItem") == "true") {
     return CustomizableUI.isWebExtensionWidget(aNode.id)
       ? this.#webExtList
       : this.#defaultList;
   }
   return this.#target;
 }

 /**
  * Private methods start here.
  */

 /**
  * Handle overflow in the toolbar by moving items to the overflow menu.
  */
 async #onOverflow() {
   if (!this.#enabled) {
     return;
   }

   let win = this.#target.ownerGlobal;
   let checkOverflowHandle = this.#checkOverflowHandle;
   let webExtButtonID = this.#toolbar.getAttribute(
     "addon-webext-overflowbutton"
   );

   let { isOverflowing, targetContentWidth } = await this.#getOverflowInfo();

   // Stop if the window has closed or if we re-enter while waiting for
   // layout.
   if (win.closed || this.#checkOverflowHandle != checkOverflowHandle) {
     lazy.log.debug("Window closed or another overflow handler started.");
     return;
   }

   let webExtList = this.#webExtList;

   let child = this.#target.lastElementChild;
   while (child && isOverflowing) {
     let prevChild = child.previousElementSibling;

     if (child.getAttribute("overflows") != "false") {
       this.#overflowedInfo.set(child.id, targetContentWidth);
       let { width: childWidth } =
         win.windowUtils.getBoundsWithoutFlushing(child);
       if (!childWidth) {
         this.#hiddenOverflowedNodes.add(child);
       }

       child.setAttribute("overflowedItem", true);
       CustomizableUIInternal.ensureButtonContextMenu(
         child,
         this.#toolbar,
         true
       );
       CustomizableUIInternal.notifyListeners(
         "onWidgetOverflow",
         child,
         this.#target
       );

       if (webExtList && CustomizableUI.isWebExtensionWidget(child.id)) {
         child.setAttribute("cui-anchorid", webExtButtonID);
         webExtList.insertBefore(child, webExtList.firstElementChild);
       } else {
         child.setAttribute("cui-anchorid", this.#defaultListButton.id);
         this.#defaultList.insertBefore(
           child,
           this.#defaultList.firstElementChild
         );
         if (!CustomizableUI.isSpecialWidget(child.id) && childWidth) {
           this.#toolbar.setAttribute("overflowing", "true");
         }
       }
     }
     child = prevChild;
     ({ isOverflowing, targetContentWidth } = await this.#getOverflowInfo());
     // Stop if the window has closed or if we re-enter while waiting for
     // layout.
     if (win.closed || this.#checkOverflowHandle != checkOverflowHandle) {
       lazy.log.debug("Window closed or another overflow handler started.");
       return;
     }
   }

   win.UpdateUrlbarSearchSplitterState();
 }

 /**
  * @typedef {object} CustomizableUIOverflowInfo
  * @property {boolean} isOverflowing
  *   True if at least one toolbar item has overflowed into an overflow panel.
  * @property {number} targetContentWidth
  *   The total width of the items within the customization target area of the
  *   overflowable toolbar toolbar.
  * @property {number} totalAvailWidth
  *   The maximum width items in the overflowable toolbar may occupy before
  *   causing an overflow.
  */

 /**
  * Returns a Promise that resolves to a an object that describes the state
  * that this OverflowableToolbar is currently in.
  *
  * @returns {Promise<CustomizableUIOverflowInfo>}
  */
 async #getOverflowInfo() {
   function getInlineSize(aElement) {
     return aElement.getBoundingClientRect().width;
   }

   function sumChildrenInlineSize(aParent, aExceptChild = null) {
     let sum = 0;
     for (let child of aParent.children) {
       let style = win.getComputedStyle(child);
       if (
         style.display == "none" ||
         win.XULPopupElement.isInstance(child) ||
         (style.position != "static" && style.position != "relative")
       ) {
         continue;
       }
       sum += parseFloat(style.marginLeft) + parseFloat(style.marginRight);
       if (child != aExceptChild) {
         sum += getInlineSize(child);
       }
     }
     return sum;
   }

   let win = this.#target.ownerGlobal;
   let totalAvailWidth;
   let targetWidth;
   let targetChildrenWidth;

   await win.promiseDocumentFlushed(() => {
     let style = win.getComputedStyle(this.#toolbar);
     let toolbarChildrenWidth = sumChildrenInlineSize(
       this.#toolbar,
       this.#target
     );
     totalAvailWidth =
       getInlineSize(this.#toolbar) -
       parseFloat(style.paddingLeft) -
       parseFloat(style.paddingRight) -
       toolbarChildrenWidth;
     targetWidth = getInlineSize(this.#target);
     targetChildrenWidth =
       this.#target == this.#toolbar
         ? toolbarChildrenWidth
         : sumChildrenInlineSize(this.#target);
   });

   lazy.log.debug(
     `Getting overflow info: target width: ${targetWidth} (${targetChildrenWidth}); avail: ${totalAvailWidth}`
   );

   // If the target has min-width: 0, their children might actually overflow
   // it, so check for both cases explicitly.
   // We don't care about <1px differences, so ceil the avail width and floor
   // the content width to deal with it.
   let targetContentWidth = Math.floor(
     Math.max(targetWidth, targetChildrenWidth)
   );
   totalAvailWidth = Math.ceil(totalAvailWidth);
   let isOverflowing = targetContentWidth > totalAvailWidth;
   return { isOverflowing, targetContentWidth, totalAvailWidth };
 }

 /**
  * Tries to move toolbar items back to the toolbar from the overflow panel.
  *
  * @param {boolean} shouldMoveAllItems
  *        Whether we should move everything (e.g. because we're being
  *        disabled)
  * @param {number} [totalAvailWidth=undefined]
  *        Optional; the width of the toolbar area in which we can put things.
  *        Some consumers pass this to avoid reflows.
  *
  *        While there are items in the list, this width won't change, and so
  *        we can avoid flushing layout by providing it and/or caching it.
  *        Note that if `shouldMoveAllItems` is true, we never need the width
  *        anyway, and this value is ignored.
  * @returns {Promise<undefined>}
  *   Resolves once moving of items has completed.
  */
 async #moveItemsBackToTheirOrigin(shouldMoveAllItems, totalAvailWidth) {
   lazy.log.debug(
     `Attempting to move ${shouldMoveAllItems ? "all" : "some"} items back`
   );
   let placements = gPlacements.get(this.#toolbar.id);
   let win = this.#target.ownerGlobal;
   let doc = this.#target.ownerDocument;
   let checkOverflowHandle = this.#checkOverflowHandle;

   let overflowedItemStack = Array.from(this.#overflowedInfo.entries());

   for (let i = overflowedItemStack.length - 1; i >= 0; --i) {
     let [childID, minSize] = overflowedItemStack[i];

     // The item may have been placed inside of a <xul:panel> that is lazily
     // loaded and still in the view cache. PanelMultiView.getViewNode will
     // do the work of checking the DOM for the child, and then falling back to
     // the cache if that is the case.
     let child = lazy.PanelMultiView.getViewNode(doc, childID);

     if (!child) {
       this.#overflowedInfo.delete(childID);
       continue;
     }

     lazy.log.debug(
       `Considering moving ${child.id} back, minSize: ${minSize}`
     );

     if (!shouldMoveAllItems && minSize) {
       if (!totalAvailWidth) {
         ({ totalAvailWidth } = await this.#getOverflowInfo());

         // If the window has closed or if we re-enter because we were waiting
         // for layout, stop.
         if (win.closed || this.#checkOverflowHandle != checkOverflowHandle) {
           lazy.log.debug("Window closed or #checkOverflow called again.");
           return;
         }
       }
       if (totalAvailWidth <= minSize) {
         lazy.log.debug(
           `Need ${minSize} but width is ${totalAvailWidth} so bailing`
         );
         break;
       }
     }

     lazy.log.debug(`Moving ${child.id} back`);
     this.#overflowedInfo.delete(child.id);
     let beforeNodeIndex = placements.indexOf(child.id) + 1;
     // If this is a skipintoolbarset item, meaning it doesn't occur in the placements list,
     // we're inserting it at the end. This will mean first-in, first-out (more or less)
     // leading to as little change in order as possible.
     if (beforeNodeIndex == 0) {
       beforeNodeIndex = placements.length;
     }
     let inserted = false;
     for (; beforeNodeIndex < placements.length; beforeNodeIndex++) {
       let beforeNode = this.#target.getElementsByAttribute(
         "id",
         placements[beforeNodeIndex]
       )[0];
       // Unfortunately, XUL add-ons can mess with nodes after they are inserted,
       // and this breaks the following code if the button isn't where we expect
       // it to be (ie not a child of the target). In this case, ignore the node.
       if (beforeNode && this.#target == beforeNode.parentElement) {
         this.#target.insertBefore(child, beforeNode);
         inserted = true;
         break;
       }
     }
     if (!inserted) {
       this.#target.appendChild(child);
     }
     child.removeAttribute("cui-anchorid");
     child.removeAttribute("overflowedItem");
     CustomizableUIInternal.ensureButtonContextMenu(child, this.#target);
     CustomizableUIInternal.notifyListeners(
       "onWidgetUnderflow",
       child,
       this.#target
     );
   }

   win.UpdateUrlbarSearchSplitterState();

   let defaultListItems = Array.from(this.#defaultList.children);
   if (
     defaultListItems.every(
       item =>
         CustomizableUI.isSpecialWidget(item.id) ||
         this.#hiddenOverflowedNodes.has(item)
     )
   ) {
     this.#toolbar.removeAttribute("overflowing");
   }
 }

 /**
  * Checks to see if there are overflowable items within the customization
  * target of the toolbar that should be moved into the overflow panel, and
  * if there are, moves them.
  *
  * Note that since this is an async function that can be called in bursts
  * by resize events on the window, this function is often re-called even
  * when a prior call hasn't yet resolved. In that situation, the older calls
  * resolve early without doing any work and leave any DOM manipulation to the
  * most recent call.
  *
  * This function is a no-op if the OverflowableToolbar is disabled or the
  * DOM fullscreen UI is currently being used.
  *
  * @returns {Promise<undefined>}
  *   Resolves once any movement of toolbar items has completed.
  */
 async #checkOverflow() {
   if (!this.#enabled) {
     return;
   }

   let win = this.#target.ownerGlobal;
   if (win.document.documentElement.hasAttribute("inDOMFullscreen")) {
     // Toolbars are hidden and cannot be made visible in DOM fullscreen mode
     // so there's nothing to do here.
     return;
   }

   let checkOverflowHandle = (this.#checkOverflowHandle = {});

   lazy.log.debug("Checking overflow");
   let { isOverflowing, totalAvailWidth } = await this.#getOverflowInfo();
   if (win.closed || this.#checkOverflowHandle != checkOverflowHandle) {
     return;
   }

   if (isOverflowing) {
     await this.#onOverflow();
   } else {
     await this.#moveItemsBackToTheirOrigin(false, totalAvailWidth);
   }

   if (checkOverflowHandle == this.#checkOverflowHandle) {
     this.#checkOverflowHandle = null;
   }
 }

 /**
  * Makes the OverflowableToolbar inert and moves all overflowable items back
  * into the customization target of the toolbar.
  */
 #disable() {
   // Abort any ongoing overflow check. #enable() will #checkOverflow()
   // anyways, so this is enough.
   this.#checkOverflowHandle = {};
   this.#moveItemsBackToTheirOrigin(true);
   this.#enabled = false;
 }

 /**
  * Puts the OverflowableToolbar into the enabled state and then checks to see
  * if any of the items in the customization target should be overflowed into
  * the overflow panel list.
  */
 #enable() {
   this.#enabled = true;
   this.#checkOverflow();
 }

 /**
  * Shows the overflow panel and sets a timeout to automatically re-hide the
  * panel if it is not being hovered.
  */
 #showWithTimeout() {
   const OVERFLOW_PANEL_HIDE_DELAY_MS = 500;

   this.show().then(() => {
     let window = this.#toolbar.ownerGlobal;
     if (this.#hideTimeoutId) {
       window.clearTimeout(this.#hideTimeoutId);
     }
     this.#hideTimeoutId = window.setTimeout(() => {
       if (!this.#defaultListPanel.firstElementChild.matches(":hover")) {
         lazy.PanelMultiView.hidePopup(this.#defaultListPanel);
       }
     }, OVERFLOW_PANEL_HIDE_DELAY_MS);
   });
 }

 /**
  * Gets and caches a reference to the DOM node with the ID set as the value
  * of addon-webext-overflowtarget. If a cache already exists, that's returned
  * instead. If addon-webext-overflowtarget has no value, null is returned.
  *
  * @returns {Element|null} the list that overflowed extension toolbar
  *   buttons should go to if the Unified Extensions UI is enabled, or null
  *   if no such list exists.
  */
 get #webExtList() {
   if (!this.#webExtListRef) {
     let targetID = this.#toolbar.getAttribute("addon-webext-overflowtarget");
     if (!targetID) {
       throw new Error(
         "addon-webext-overflowtarget was not defined on the " +
           `overflowable toolbar with id: ${this.#toolbar.id}`
       );
     }
     let win = this.#toolbar.ownerGlobal;
     let { panel } = win.gUnifiedExtensions;
     this.#webExtListRef = panel.querySelector(`#${targetID}`);
   }
   return this.#webExtListRef;
 }

 /**
  * Returns true if aNode is not null and is one of either this.#webExtList or
  * this.#defaultList.
  *
  * @param {DOMElement} aNode The node to test.
  * @returns {boolean}
  */
 #isOverflowList(aNode) {
   return aNode == this.#defaultList || aNode == this.#webExtList;
 }

 /**
  * Private event handlers start here.
  */

 /**
  * Handles clicks on the #defaultListButton element.
  *
  * @param {MouseEvent} aEvent the click event.
  */
 #onClickDefaultListButton(aEvent) {
   if (this.#defaultListButton.open) {
     this.#defaultListButton.open = false;
     lazy.PanelMultiView.hidePopup(this.#defaultListPanel);
   } else if (
     this.#defaultListPanel.state != "hiding" &&
     !this.#defaultListButton.disabled
   ) {
     this.show(aEvent);
   }
 }

 /**
  * Handles the popuphiding event firing on the #defaultListPanel.
  *
  * @param {WidgetMouseEvent} aEvent the popuphiding event that fired on the
  *   #defaultListPanel.
  */
 #onPanelHiding(aEvent) {
   if (aEvent.target != this.#defaultListPanel) {
     // Ignore context menus, <select> popups, etc.
     return;
   }
   this.#defaultListButton.open = false;
   this.#defaultListPanel.removeEventListener("dragover", this);
   this.#defaultListPanel.removeEventListener("dragend", this);
   let doc = aEvent.target.ownerDocument;
   doc.defaultView.updateEditUIVisibility();
   let contextMenuId = this.#defaultListPanel.getAttribute("context");
   if (contextMenuId) {
     let contextMenu = doc.getElementById(contextMenuId);
     contextMenu.removeEventListener("command", this, {
       capture: true,
       mozSystemGroup: true,
     });
   }
 }

 /**
  * Handles a resize event fired on the window hosting this
  * OverflowableToolbar.
  *
  * @param {UIEvent} aEvent the resize event.
  */
 #onResize(aEvent) {
   // Ignore bubbled-up resize events.
   if (aEvent.target != aEvent.currentTarget) {
     return;
   }
   this.#checkOverflow();
 }

 /**
  * CustomizableUI listener methods start here.
  */

 onWidgetBeforeDOMChange(aNode, aNextNode, aContainer) {
   // This listener method is used to handle the case where a widget is
   // moved or removed from an area via the CustomizableUI API while
   // overflowed. It reorganizes the internal state of this OverflowableToolbar
   // to handle that change.
   if (!this.#enabled || !this.#isOverflowList(aContainer)) {
     return;
   }
   // When we (re)move an item, update all the items that come after it in the list
   // with the minsize *of the item before the to-be-removed node*. This way, we
   // ensure that we try to move items back as soon as that's possible.
   let updatedMinSize;
   if (aNode.previousElementSibling) {
     updatedMinSize = this.#overflowedInfo.get(
       aNode.previousElementSibling.id
     );
   } else {
     // Force (these) items to try to flow back into the bar:
     updatedMinSize = 1;
   }
   let nextItem = aNode.nextElementSibling;
   while (nextItem) {
     this.#overflowedInfo.set(nextItem.id, updatedMinSize);
     nextItem = nextItem.nextElementSibling;
   }
 }

 onWidgetAfterDOMChange(aNode, aNextNode, aContainer) {
   // This listener method is used to handle the case where a widget is
   // moved or removed from an area via the CustomizableUI API while
   // overflowed. It updates the DOM in the event that the movement or removal
   // causes overflow or underflow of the toolbar.
   if (
     !this.#enabled ||
     (aContainer != this.#target && !this.#isOverflowList(aContainer))
   ) {
     return;
   }

   let nowOverflowed = this.#isOverflowList(aNode.parentNode);
   let wasOverflowed = this.#overflowedInfo.has(aNode.id);

   // If this wasn't overflowed before...
   if (!wasOverflowed) {
     // ... but it is now, then we added to one of the overflow panels.
     if (nowOverflowed) {
       // We could be the first item in the overflow panel if we're being inserted
       // before the previous first item in it. We can't assume the minimum
       // size is the same (because the other item might be much wider), so if
       // there is no previous item, just allow this item to be put back in the
       // toolbar immediately by specifying a very low minimum size.
       let sourceOfMinSize = aNode.previousElementSibling;
       let minSize = sourceOfMinSize
         ? this.#overflowedInfo.get(sourceOfMinSize.id)
         : 1;
       this.#overflowedInfo.set(aNode.id, minSize);
       aNode.setAttribute("cui-anchorid", this.#defaultListButton.id);
       aNode.setAttribute("overflowedItem", true);
       CustomizableUIInternal.ensureButtonContextMenu(aNode, aContainer, true);
       CustomizableUIInternal.notifyListeners(
         "onWidgetOverflow",
         aNode,
         this.#target
       );
     }
   } else if (!nowOverflowed) {
     // If it used to be overflowed...
     // ... and isn't anymore, let's remove our bookkeeping:
     this.#overflowedInfo.delete(aNode.id);
     aNode.removeAttribute("cui-anchorid");
     aNode.removeAttribute("overflowedItem");
     CustomizableUIInternal.ensureButtonContextMenu(aNode, aContainer);
     CustomizableUIInternal.notifyListeners(
       "onWidgetUnderflow",
       aNode,
       this.#target
     );

     let collapsedWidgetIds = Array.from(this.#overflowedInfo.keys());
     if (collapsedWidgetIds.every(w => CustomizableUI.isSpecialWidget(w))) {
       this.#toolbar.removeAttribute("overflowing");
     }
   } else if (aNode.previousElementSibling) {
     // but if it still is, it must have changed places. Bookkeep:
     let prevId = aNode.previousElementSibling.id;
     let minSize = this.#overflowedInfo.get(prevId);
     this.#overflowedInfo.set(aNode.id, minSize);
   }

   // We might overflow now if an item was added, or we may be able to move
   // stuff back into the toolbar if an item was removed.
   this.#checkOverflow();
 }

 /**
  * @returns {boolean} whether the given node is in the overflow list.
  */
 isInOverflowList(node) {
   return node.parentNode == this.#defaultList;
 }

 /**
  * nsIObserver implementation starts here.
  */

 observe(aSubject, aTopic) {
   // This nsIObserver method allows us to defer initialization until after
   // this window has finished painting and starting up.
   if (
     aTopic == "browser-delayed-startup-finished" &&
     aSubject == this.#toolbar.ownerGlobal
   ) {
     Services.obs.removeObserver(this, "browser-delayed-startup-finished");
     this.init();
   }
 }

 /**
  * nsIDOMEventListener implementation starts here.
  */

 handleEvent(aEvent) {
   switch (aEvent.type) {
     case "aftercustomization": {
       this.#enable();
       break;
     }
     case "mousedown": {
       if (aEvent.button != 0) {
         break;
       }
       if (aEvent.target == this.#defaultListButton) {
         this.#onClickDefaultListButton(aEvent);
       } else {
         lazy.PanelMultiView.hidePopup(this.#defaultListPanel);
       }
       break;
     }
     case "keypress": {
       if (
         aEvent.target == this.#defaultListButton &&
         (aEvent.key == " " || aEvent.key == "Enter")
       ) {
         this.#onClickDefaultListButton(aEvent);
       }
       break;
     }
     case "customizationstarting": {
       this.#disable();
       break;
     }
     case "dragover": {
       if (this.#enabled) {
         this.#showWithTimeout();
       }
       break;
     }
     case "dragend": {
       lazy.PanelMultiView.hidePopup(this.#defaultListPanel);
       break;
     }
     case "popuphiding": {
       this.#onPanelHiding(aEvent);
       break;
     }
     case "resize": {
       this.#onResize(aEvent);
       break;
     }
   }
 }
}

CustomizableUIInternal.initialize();