From 68fb7e68f24365f83e12d88ee31d378f717e878a Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Tue, 26 Jan 2021 14:29:15 -0600
Subject: [PATCH 01/16] format scss files

---
 .vscode/settings.json      | 8 ++++----
 src/components/app.scss    | 2 +-
 src/components/editor.scss | 6 +++---
 src/index.scss             | 4 +++-
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 62604942..38041163 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,8 +1,4 @@
 {
-    "[css]": {
-        "editor.suggest.insertMode": "replace",
-        "editor.formatOnSave": true
-    },
     "[json]": {
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "esbenp.prettier-vscode"
@@ -11,6 +7,10 @@
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "esbenp.prettier-vscode"
     },
+    "[scss]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
     "editor.codeActionsOnSave": {
         "source.fixAll.eslint": true
     },
diff --git a/src/components/app.scss b/src/components/app.scss
index ecc1a7d8..6a740de6 100644
--- a/src/components/app.scss
+++ b/src/components/app.scss
@@ -5,7 +5,7 @@
 
 @import '../variables.scss';
 
-.#{$ns}-dark .splitter-layout > .layout-splitter  {
+.#{$ns}-dark .splitter-layout > .layout-splitter {
     // make layout splitter match app color scheme
     background-color: $pt-dark-app-background-color;
 }
diff --git a/src/components/editor.scss b/src/components/editor.scss
index 5cb49f28..b501d877 100644
--- a/src/components/editor.scss
+++ b/src/components/editor.scss
@@ -24,13 +24,13 @@
 // add "BETA" watermark
 
 .pb-beta .ace_scroller::after {
-    content: "";
-    background: url("./images/beta.svg");
+    content: '';
+    background: url('./images/beta.svg');
     opacity: 1;
     top: 0;
     left: 0;
     bottom: 0;
     right: 0;
     position: absolute;
-    pointer-events: none
+    pointer-events: none;
 }
diff --git a/src/index.scss b/src/index.scss
index 310284fd..1292ab1c 100644
--- a/src/index.scss
+++ b/src/index.scss
@@ -19,7 +19,9 @@ body {
 
 .h-body {
     // height makes everything fit without scrolling
-    height: calc(100vh - #{$pt-navbar-height} - #{$pb-status-bar-height} - var(--mobile-pad)) !important;
+    height: calc(
+        100vh - #{$pt-navbar-height} - #{$pb-status-bar-height} - var(--mobile-pad)
+    ) !important;
 }
 
 .h-100 {

From c7803fed199a99292a21ab8b3d76a4d6d0ebf5ec Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Tue, 26 Jan 2021 15:37:58 -0600
Subject: [PATCH 02/16] fix wrong event type on switch

Fixes:

    index.js:1 Warning: Failed prop type: You provided a `checked` prop to a form field without an `onChange` handler. This will render a read-only field. If the field should be mutable use `defaultChecked`. Otherwise, set either `onChange` or `readOnly`.
---
 src/components/SettingsDrawer.tsx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/components/SettingsDrawer.tsx b/src/components/SettingsDrawer.tsx
index b24da192..52dbdde7 100644
--- a/src/components/SettingsDrawer.tsx
+++ b/src/components/SettingsDrawer.tsx
@@ -211,7 +211,9 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
                             <FormGroup label="Developer">
                                 <Switch
                                     checked={i18n.pseudolocalize !== false}
-                                    onClick={() => pseudolocalize(!i18n.pseudolocalize)}
+                                    onChange={() =>
+                                        pseudolocalize(!i18n.pseudolocalize)
+                                    }
                                     label="Pseudolocalize"
                                 />
                             </FormGroup>

From eebeec509cb6a857d6e833d8a4a3c5354b9b164f Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Tue, 26 Jan 2021 17:41:44 -0600
Subject: [PATCH 03/16] don't focus buttons on click

This prevents the navbar buttons from gaining focus when clicked.
This way it prevents losing focus from the editor or terminal.
It also prevents the settings button from being highlighted after
the settings menu is closed.
---
 src/components/ActionButton.tsx   | 1 +
 src/components/OpenFileButton.tsx | 1 +
 2 files changed, 2 insertions(+)

diff --git a/src/components/ActionButton.tsx b/src/components/ActionButton.tsx
index 7377dcb6..4b21ecde 100644
--- a/src/components/ActionButton.tsx
+++ b/src/components/ActionButton.tsx
@@ -51,6 +51,7 @@ class ActionButton extends React.Component<Props> {
                 <Button
                     ref={this.buttonRef}
                     intent={Intent.PRIMARY}
+                    onMouseDown={(e) => e.preventDefault()} // prevent focus
                     onClick={(): void => this.props.onAction()}
                     disabled={this.props.enabled === false}
                     className="no-box-shadow"
diff --git a/src/components/OpenFileButton.tsx b/src/components/OpenFileButton.tsx
index 28402120..bf8ac93c 100644
--- a/src/components/OpenFileButton.tsx
+++ b/src/components/OpenFileButton.tsx
@@ -114,6 +114,7 @@ class OpenFileButton extends React.Component<Props> {
                                         ? { pointerEvents: 'none' }
                                         : undefined
                                 }
+                                onMouseDown={(e) => e.preventDefault()} // prevent focus
                                 // onClick={this.props.onClick}
                                 // breaks Dropzone when this.props.onClick is undefined
                                 // so we have to do it the long way

From 45ac41b398e5990993cc1c65fa7e2fca7992a2bb Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Tue, 26 Jan 2021 17:45:29 -0600
Subject: [PATCH 04/16] use ~ in scss imports

this allows proper click-link to files in node_modules
---
 src/index.scss     | 2 +-
 src/variables.scss | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/index.scss b/src/index.scss
index 1292ab1c..6303d817 100644
--- a/src/index.scss
+++ b/src/index.scss
@@ -3,7 +3,7 @@
 
 @import './variables.scss';
 @import '~normalize.css';
-@import '@blueprintjs/core/src/blueprint.scss';
+@import '~@blueprintjs/core/src/blueprint.scss';
 
 :root {
     --mobile-pad: 0px;
diff --git a/src/variables.scss b/src/variables.scss
index 80abb973..d94d51f5 100644
--- a/src/variables.scss
+++ b/src/variables.scss
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2020-2021 The Pybricks Authors
 
-@import '@blueprintjs/core/lib/scss/variables.scss';
+@import '~@blueprintjs/core/lib/scss/variables.scss';
 
 // override variables here
 // See https://blueprintjs.com/docs/#core/variables

From 4f00c962e1c62e738595f3808b00b9ff73266039 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Tue, 26 Jan 2021 18:35:06 -0600
Subject: [PATCH 05/16] finish TODO for checking bluetooth availability

---
 src/actions/ble.ts                       | 4 ++++
 src/actions/lwp3-bootloader.ts           | 5 +++++
 src/components/notification-i18n.en.json | 1 +
 src/components/notification-i18n.ts      | 1 +
 src/sagas/ble-uart.ts                    | 6 +++++-
 src/sagas/lwp3-bootloader-ble.ts         | 6 +++++-
 src/sagas/notification.test.ts           | 2 ++
 src/sagas/notification.ts                | 6 ++++++
 8 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/src/actions/ble.ts b/src/actions/ble.ts
index d6ad1ec1..19f4785d 100644
--- a/src/actions/ble.ts
+++ b/src/actions/ble.ts
@@ -51,6 +51,7 @@ export function didConnect(): BleDeviceDidConnectAction {
 
 export enum BleDeviceFailToConnectReasonType {
     NoWebBluetooth = 'ble.device.didFailToConnect.noWebBluetooth',
+    NoBluetooth = 'ble.device.didFailToConnect.noBluetooth',
     Canceled = 'ble.device.didFailToConnect.canceled',
     NoGatt = 'ble.device.didFailToConnect.noGatt',
     NoService = 'ble.device.didFailToConnect.noService',
@@ -63,6 +64,8 @@ type Reason<T extends BleDeviceFailToConnectReasonType> = {
 
 export type BleDeviceFailToConnectNoWebBluetoothReason = Reason<BleDeviceFailToConnectReasonType.NoWebBluetooth>;
 
+export type BleDeviceFailToConnectNoBluetoothReason = Reason<BleDeviceFailToConnectReasonType.NoBluetooth>;
+
 export type BleDeviceFailToConnectCanceledReason = Reason<BleDeviceFailToConnectReasonType.Canceled>;
 
 export type BleDeviceFailToConnectNoGattReason = Reason<BleDeviceFailToConnectReasonType.NoGatt>;
@@ -75,6 +78,7 @@ export type BleDeviceFailToConnectUnknownReason = Reason<BleDeviceFailToConnectR
 
 export type BleDeviceDidFailToConnectReason =
     | BleDeviceFailToConnectNoWebBluetoothReason
+    | BleDeviceFailToConnectNoBluetoothReason
     | BleDeviceFailToConnectCanceledReason
     | BleDeviceFailToConnectNoGattReason
     | BleDeviceFailToConnectNoServiceReason
diff --git a/src/actions/lwp3-bootloader.ts b/src/actions/lwp3-bootloader.ts
index 07c74789..9bf35a9f 100644
--- a/src/actions/lwp3-bootloader.ts
+++ b/src/actions/lwp3-bootloader.ts
@@ -79,6 +79,8 @@ export function disconnect(): BootloaderConnectionDisconnectAction {
 export enum BootloaderConnectionFailureReason {
     /** Web Bluetooth is not available */
     NoWebBluetooth = 'no-web-bluetooth',
+    /** Bluetooth is not available */
+    NoBluetooth = 'no-bluetooth',
     /** Connected but failed to find the bootloader GATT service */
     GattServiceNotFound = 'gatt-service-not-found',
     /** The connection was canceled */
@@ -93,6 +95,8 @@ type Reason<T extends BootloaderConnectionFailureReason> = {
 
 export type BootloaderConnectionFailToConnectNoWebBluetoothReason = Reason<BootloaderConnectionFailureReason.NoWebBluetooth>;
 
+export type BootloaderConnectionFailToConnectNoBluetoothReason = Reason<BootloaderConnectionFailureReason.NoBluetooth>;
+
 export type BootloaderConnectionFailToConnectGattServiceNotFoundReason = Reason<BootloaderConnectionFailureReason.GattServiceNotFound>;
 
 export type BootloaderConnectionFailToConnectCanceledReason = Reason<BootloaderConnectionFailureReason.Canceled>;
@@ -103,6 +107,7 @@ export type BootloaderConnectionFailToConnectUnknownReason = Reason<BootloaderCo
 
 export type BootloaderConnectionDidFailToConnectReason =
     | BootloaderConnectionFailToConnectNoWebBluetoothReason
+    | BootloaderConnectionFailToConnectNoBluetoothReason
     | BootloaderConnectionFailToConnectGattServiceNotFoundReason
     | BootloaderConnectionFailToConnectCanceledReason
     | BootloaderConnectionFailToConnectUnknownReason;
diff --git a/src/components/notification-i18n.en.json b/src/components/notification-i18n.en.json
index 7555b749..e5fb0bd5 100644
--- a/src/components/notification-i18n.en.json
+++ b/src/components/notification-i18n.en.json
@@ -5,6 +5,7 @@
         "gattPermission": "The web browser did not give permission to use Bluetooth Low Energy",
         "gattServiceNotFound": "Connected to hub but failed to get {serviceName} service. Try removing the \"{hubName}\" device in your OS Bluetooth settings, then try again.",
         "noWebBluetooth": "This web browser does not support Web Bluetooth or it is not enabled.",
+        "noBluetooth": "No Bluetooth adapter could be found. Bluetooth won't work.",
         "unexpectedError": "Unexpected error while trying to connect: {errorMessage}"
     },
     "editor": {
diff --git a/src/components/notification-i18n.ts b/src/components/notification-i18n.ts
index c519a1f6..8e39bf64 100644
--- a/src/components/notification-i18n.ts
+++ b/src/components/notification-i18n.ts
@@ -10,6 +10,7 @@ export enum MessageId {
     BleGattPermission = 'ble.gattPermission',
     BleGattServiceNotFound = 'ble.gattServiceNotFound',
     BleNoWebBluetooth = 'ble.noWebBluetooth',
+    BleNoBluetooth = 'ble.noBluetooth',
     FlashFirmwareTimedOut = 'flashFirmware.timedOut',
     FlashFirmwareBleError = 'flashFirmware.bleError',
     FlashFirmwareDisconnected = 'flashFirmware.disconnected',
diff --git a/src/sagas/ble-uart.ts b/src/sagas/ble-uart.ts
index a1b81493..8b346520 100644
--- a/src/sagas/ble-uart.ts
+++ b/src/sagas/ble-uart.ts
@@ -70,7 +70,11 @@ function* connect(_action: BleDeviceConnectAction): Generator {
         return;
     }
 
-    // TODO: check navigator.bluetooth.getAvailability()
+    const available = yield* call(() => navigator.bluetooth.getAvailability());
+    if (!available) {
+        yield* put(didFailToConnect({ reason: Reason.NoBluetooth }));
+        return;
+    }
 
     let device: BluetoothDevice;
     try {
diff --git a/src/sagas/lwp3-bootloader-ble.ts b/src/sagas/lwp3-bootloader-ble.ts
index 69ad67cd..338064fb 100644
--- a/src/sagas/lwp3-bootloader-ble.ts
+++ b/src/sagas/lwp3-bootloader-ble.ts
@@ -45,7 +45,11 @@ function* connect(_action: BootloaderConnectionAction): Generator {
         return;
     }
 
-    // TODO: check navigator.bluetooth.getAvailability()
+    const available = yield* call(() => navigator.bluetooth.getAvailability());
+    if (!available) {
+        yield* put(didFailToConnect(Reason.NoBluetooth));
+        return;
+    }
 
     let device: BluetoothDevice;
     try {
diff --git a/src/sagas/notification.test.ts b/src/sagas/notification.test.ts
index b7b114bc..0f456bc9 100644
--- a/src/sagas/notification.test.ts
+++ b/src/sagas/notification.test.ts
@@ -28,6 +28,7 @@ import notification from './notification';
 
 test.each([
     bleDidFailToConnect({ reason: BleDeviceFailToConnectReasonType.NoWebBluetooth }),
+    bleDidFailToConnect({ reason: BleDeviceFailToConnectReasonType.NoBluetooth }),
     bleDidFailToConnect({ reason: BleDeviceFailToConnectReasonType.NoGatt }),
     bleDidFailToConnect({ reason: BleDeviceFailToConnectReasonType.NoService }),
     bleDidFailToConnect({
@@ -38,6 +39,7 @@ test.each([
         message: 'test',
     }),
     bootloaderDidFailToConnect(BootloaderConnectionFailureReason.NoWebBluetooth),
+    bootloaderDidFailToConnect(BootloaderConnectionFailureReason.NoBluetooth),
     bootloaderDidFailToConnect(BootloaderConnectionFailureReason.GattServiceNotFound),
     storageChanged('test'),
     didFailToCompile(['reason']),
diff --git a/src/sagas/notification.ts b/src/sagas/notification.ts
index b9fb0c7a..d976198b 100644
--- a/src/sagas/notification.ts
+++ b/src/sagas/notification.ts
@@ -171,6 +171,9 @@ function* showBleDeviceDidFailToConnectError(
                 hubName: 'Pybricks Hub',
             });
             break;
+        case BleDeviceFailToConnectReasonType.NoBluetooth:
+            yield* showSingleton(Level.Error, MessageId.BleNoBluetooth);
+            break;
         case BleDeviceFailToConnectReasonType.NoWebBluetooth:
             yield* showSingleton(
                 Level.Error,
@@ -207,6 +210,9 @@ function* showBootloaderDidFailToConnectError(
                 ),
             );
             break;
+        case BootloaderConnectionFailureReason.NoBluetooth:
+            yield* showSingleton(Level.Error, MessageId.BleNoBluetooth);
+            break;
         case BootloaderConnectionFailureReason.Unknown:
             yield* showUnexpectedError(MessageId.BleUnexpectedError, action.err);
             break;

From 64e6b3739ef26a028ff223cc84ee7b963ea560a9 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Wed, 27 Jan 2021 11:48:51 -0600
Subject: [PATCH 06/16] add keyboard shortcut to toggle docs

this is useful for users with small screens
---
 src/actions/settings.ts    | 12 ++++++++++++
 src/components/Editor.tsx  | 20 +++++++++++++++++++-
 src/sagas/settings.test.ts | 28 +++++++++++++++++++++++++++-
 src/sagas/settings.ts      |  8 ++++++++
 4 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/src/actions/settings.ts b/src/actions/settings.ts
index e2f477d9..eb624360 100644
--- a/src/actions/settings.ts
+++ b/src/actions/settings.ts
@@ -7,6 +7,7 @@ import { SettingId } from '../settings/user';
 /** Actions related to settings. */
 export enum SettingsActionType {
     SetBoolean = 'settings.action.setBoolean',
+    ToggleBoolean = 'settings.action.toggleBoolean',
     DidFailToSetBoolean = 'settings.action.didFailToSetBoolean',
     DidBooleanChange = 'settings.action.didBooleanChange',
 }
@@ -27,6 +28,16 @@ export function setBoolean(id: SettingId, newState: boolean): SettingsSetBoolean
     return { type: SettingsActionType.SetBoolean, id, newState };
 }
 
+/** Action to toggle a setting. */
+export type SettingsToggleBooleanAction = Action<SettingsActionType.ToggleBoolean> & {
+    id: SettingId;
+};
+
+/** Creates an action to toggle a setting. */
+export function toggleBoolean(id: SettingId): SettingsToggleBooleanAction {
+    return { type: SettingsActionType.ToggleBoolean, id };
+}
+
 /** Action that indicates setting/storing a setting failed. */
 export type SettingsDidFailToSetBooleanAction = Action<SettingsActionType.DidFailToSetBoolean> & {
     id: SettingId;
@@ -56,5 +67,6 @@ export function didBooleanChange(
 /** Common type for all settings actions. */
 export type SettingsAction =
     | SettingsSetBooleanAction
+    | SettingsToggleBooleanAction
     | SettingsDidFailToSetBooleanAction
     | SettingsDidBooleanChangeAction;
diff --git a/src/components/Editor.tsx b/src/components/Editor.tsx
index c6588c7d..222b51f0 100644
--- a/src/components/Editor.tsx
+++ b/src/components/Editor.tsx
@@ -17,7 +17,9 @@ import { connect } from 'react-redux';
 import { Action, Dispatch } from '../actions';
 import { setEditSession, storageChanged } from '../actions/editor';
 import { compile } from '../actions/mpy';
+import { toggleBoolean } from '../actions/settings';
 import { RootState } from '../reducers';
+import { SettingId } from '../settings/user';
 import { isMacOS } from '../utils/os';
 import { EditorStringId } from './editor-i18n';
 import en from './editor-i18n.en.json';
@@ -34,12 +36,14 @@ import './editor.scss';
 
 type StateProps = {
     darkMode: boolean;
+    showDocs: boolean;
 };
 
 type DispatchProps = {
     onSessionChanged: (session?: Ace.EditSession) => void;
     onProgramStorageChanged: (newValue: string) => void;
     onCheck: (script: string) => void;
+    onToggleDocs: () => void;
 };
 
 type EditorProps = StateProps & DispatchProps & WithI18nProps;
@@ -78,7 +82,7 @@ class Editor extends React.Component<EditorProps> {
     }
 
     render(): JSX.Element {
-        const { darkMode, i18n, onSessionChanged, onCheck } = this.props;
+        const { i18n, darkMode, onSessionChanged, onCheck, onToggleDocs } = this.props;
         return (
             <div className="h-100">
                 <ResizeSensor onResize={(): void => this.editor?.resize()}>
@@ -105,6 +109,13 @@ class Editor extends React.Component<EditorProps> {
                                 mac: 'Shift-F2',
                             };
 
+                            // we want to use Ctrl-D for docs toggle, so change
+                            // delete line to VSCode default
+                            e.commands.byName['removeline'].bindKey = {
+                                win: 'Ctrl-Shift-K',
+                                mac: 'Cmd-Shift-K',
+                            };
+
                             config.loadModule(
                                 'ace/ext/menu_tools/get_editor_keyboard_shortcuts',
                                 (m) => {
@@ -129,6 +140,11 @@ class Editor extends React.Component<EditorProps> {
                                 bindKey: { win: 'F2', mac: 'F2' },
                                 exec: (editor) => onCheck(editor.getValue()),
                             },
+                            {
+                                name: 'toggleDocs',
+                                bindKey: { win: 'Ctrl-D', mac: 'Cmd-D' },
+                                exec: () => onToggleDocs(),
+                            },
                             {
                                 name: 'save',
                                 bindKey: { win: 'Ctrl-S', mac: 'Cmd-S' },
@@ -202,6 +218,7 @@ class Editor extends React.Component<EditorProps> {
 
 const mapStateToProps = (state: RootState): StateProps => ({
     darkMode: state.settings.darkMode,
+    showDocs: state.settings.showDocs,
 });
 
 const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
@@ -210,6 +227,7 @@ const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
     // REVISIT: the options here might need to be changed - hopefully there is
     // one setting that works for all hub types for cases where we aren't connected.
     onCheck: (script) => dispatch(compile(script)),
+    onToggleDocs: () => dispatch(toggleBoolean(SettingId.ShowDocs)),
 });
 
 export default connect(
diff --git a/src/sagas/settings.test.ts b/src/sagas/settings.test.ts
index da9dea7c..00c1e623 100644
--- a/src/sagas/settings.test.ts
+++ b/src/sagas/settings.test.ts
@@ -5,7 +5,12 @@
 
 import { AsyncSaga } from '../../test';
 import { didStart } from '../actions/app';
-import { didBooleanChange, didFailToSetBoolean, setBoolean } from '../actions/settings';
+import {
+    didBooleanChange,
+    didFailToSetBoolean,
+    setBoolean,
+    toggleBoolean,
+} from '../actions/settings';
 import { SettingId } from '../settings/user';
 import settings from './settings';
 
@@ -345,3 +350,24 @@ describe('storage monitor', () => {
         await saga.end();
     });
 });
+
+describe('toggle', () => {
+    test('showDocs', async () => {
+        const saga = new AsyncSaga(settings, { settings: { showDocs: false } });
+
+        const mockSetItem = jest
+            .spyOn(Object.getPrototypeOf(window.localStorage), 'setItem')
+            .mockImplementation((key, value) => {
+                expect(key).toBe('setting.showDocs');
+                expect(value).toBe('true');
+            });
+
+        saga.put(toggleBoolean(SettingId.ShowDocs));
+        expect(mockSetItem).toHaveBeenCalled();
+
+        const action = await saga.take();
+        expect(action).toEqual(didBooleanChange(SettingId.ShowDocs, true));
+
+        await saga.end();
+    });
+});
diff --git a/src/sagas/settings.ts b/src/sagas/settings.ts
index 3bd84274..394c9475 100644
--- a/src/sagas/settings.ts
+++ b/src/sagas/settings.ts
@@ -11,8 +11,10 @@ import { AppActionType } from '../actions/app';
 import {
     SettingsActionType,
     SettingsSetBooleanAction,
+    SettingsToggleBooleanAction,
     didBooleanChange,
     didFailToSetBoolean,
+    setBoolean,
 } from '../actions/settings';
 import { RootState } from '../reducers';
 import { SettingId, getDefaultBooleanValue } from '../settings/user';
@@ -97,8 +99,14 @@ function* storeSetting(action: SettingsSetBooleanAction): Generator {
     }
 }
 
+function* toggleSetting(action: SettingsToggleBooleanAction): Generator {
+    const oldValue = yield* select((s: RootState) => s.settings[action.id]);
+    yield* storeSetting(setBoolean(action.id, !oldValue));
+}
+
 export default function* (): Generator {
     yield* fork(monitorLocalStorage);
     yield* takeEvery(AppActionType.DidStart, loadSettings);
     yield* takeEvery(SettingsActionType.SetBoolean, storeSetting);
+    yield* takeEvery(SettingsActionType.ToggleBoolean, toggleSetting);
 }

From ca8192084de1733edc0222e6382754d1aec94259 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Wed, 27 Jan 2021 15:38:51 -0600
Subject: [PATCH 07/16] restore docs position after hide/show

Previously, the docs iframe was removed from the DOM when the docs
were hidden. This caused the docs to always go back to the main page
when shown.

This fixes it by using CSS to hide the docs instead of removing them
from the DOM. However, this comes with its own complications regarding
maintaining the scroll position.
---
 src/components/App.tsx  | 95 +++++++++++++++++++++++++++++++++++------
 src/components/app.scss |  6 +++
 2 files changed, 87 insertions(+), 14 deletions(-)

diff --git a/src/components/App.tsx b/src/components/App.tsx
index 2a982ba1..46276288 100644
--- a/src/components/App.tsx
+++ b/src/components/App.tsx
@@ -22,7 +22,7 @@ function App(): JSX.Element {
         <div className="app">
             <Toolbar />
             <SplitterLayout
-                customClassName="h-body"
+                customClassName={`h-body ${showDocs ? 'pb-show-docs' : 'pb-hide-docs'}`}
                 onDragStart={(): void => setDragging(true)}
                 onDragEnd={(): void => setDragging(false)}
                 percentage={true}
@@ -48,19 +48,86 @@ function App(): JSX.Element {
                         <Terminal />
                     </div>
                 </SplitterLayout>
-                {showDocs && (
-                    <div className="h-100 w-100">
-                        {dragging && <div className="h-100 w-100 p-absolute" />}
-                        <iframe
-                            src="static/docs/index.html"
-                            allowFullScreen={true}
-                            title="docs"
-                            width="100%"
-                            height="100%"
-                            frameBorder="none"
-                        />
-                    </div>
-                )}
+                <div className="h-100 w-100">
+                    {dragging && <div className="h-100 w-100 p-absolute" />}
+                    <iframe
+                        onLoad={(e) => {
+                            // HACK: this mess restores the scroll position when
+                            // the documentation iframe visibility is toggled.
+                            // The iframe will be automatically scrolled to 0 when
+                            // CSS `display: none` is set.
+
+                            const target = e.target as HTMLIFrameElement;
+                            const contentWindow = target.contentWindow;
+                            if (!contentWindow) {
+                                console.error('could not get iframe content window');
+                                return;
+                            }
+
+                            // the last "good" scrollY value of the iframe
+                            let iframeScroll = 0;
+
+                            // This bit monitors the visibility.
+                            // https://stackoverflow.com/a/44670818/1976323
+                            const observer = new IntersectionObserver(
+                                (entries) => {
+                                    entries.forEach((entry) => {
+                                        // Restore the scroll position when the
+                                        // iframe is shown. Toggling the visibility
+                                        // prevents flashing the contents from the
+                                        // top of the page before the scroll is
+                                        // done.
+                                        if (entry.intersectionRatio > 0) {
+                                            contentWindow.scrollTo(0, iframeScroll);
+                                            contentWindow.document.documentElement.style.visibility =
+                                                'visible';
+                                        } else {
+                                            contentWindow.document.documentElement.style.visibility =
+                                                'hidden';
+                                        }
+                                    });
+                                },
+                                {
+                                    root: target.parentElement,
+                                },
+                            );
+
+                            observer.observe(target);
+
+                            // Have to remove he observer, otherwise we end up
+                            // with conflicting values when a new page is loaded
+                            // in the iframe.
+                            contentWindow.addEventListener('unload', () => {
+                                observer.unobserve(target);
+                            });
+
+                            // And this keeps track of the scroll position.
+                            contentWindow.addEventListener('scroll', () => {
+                                if (contentWindow.scrollY !== 0) {
+                                    // Record the current scroll position.
+                                    // If it is 0, it could be that the iframe
+                                    // has been hidden or the user scrolled
+                                    // there. So we have to ignore 0. But we
+                                    // don't want to be one pixel off if the
+                                    // user really did scroll there, so we
+                                    // assume that if the last scroll is 1, then
+                                    // the user probably went all the way to 0.
+                                    if (contentWindow.scrollY === 1) {
+                                        iframeScroll = 0;
+                                    } else {
+                                        iframeScroll = contentWindow.scrollY;
+                                    }
+                                }
+                            });
+                        }}
+                        src="static/docs/index.html"
+                        allowFullScreen={true}
+                        title="docs"
+                        width="100%"
+                        height="100%"
+                        frameBorder="none"
+                    />
+                </div>
             </SplitterLayout>
             <StatusBar />
             <SettingsDrawer />
diff --git a/src/components/app.scss b/src/components/app.scss
index 6a740de6..a3b07472 100644
--- a/src/components/app.scss
+++ b/src/components/app.scss
@@ -22,3 +22,9 @@
 .terminal-padding {
     padding-left: 10px;
 }
+
+// hide the docs and resize separator
+
+div.pb-hide-docs > :not(.layout-pane-primary) {
+    display: none;
+}

From 1d7414bd8355215f0c59a8369824bf4f96b22ff6 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Wed, 27 Jan 2021 16:02:37 -0600
Subject: [PATCH 08/16] add Ctrl-D keyboard shortcut in docs iframe

This way it still works when the docs are focused. Otherwise the browser
would try to bookmark the page.
---
 src/components/App.tsx | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/components/App.tsx b/src/components/App.tsx
index 46276288..a04b7daf 100644
--- a/src/components/App.tsx
+++ b/src/components/App.tsx
@@ -2,9 +2,12 @@
 // Copyright (c) 2020 The Pybricks Authors
 
 import React, { useState } from 'react';
-import { useSelector } from 'react-redux';
+import { useDispatch, useSelector } from 'react-redux';
 import SplitterLayout from 'react-splitter-layout';
+import { toggleBoolean } from '../actions/settings';
 import { RootState } from '../reducers';
+import { SettingId } from '../settings/user';
+import { isMacOS } from '../utils/os';
 import Editor from './Editor';
 import SettingsDrawer from './SettingsDrawer';
 import StatusBar from './StatusBar';
@@ -17,6 +20,7 @@ import './app.scss';
 function App(): JSX.Element {
     const showDocs = useSelector((s: RootState): boolean => s.settings.showDocs);
     const [dragging, setDragging] = useState(false);
+    const dispatch = useDispatch();
 
     return (
         <div className="app">
@@ -119,6 +123,21 @@ function App(): JSX.Element {
                                     }
                                 }
                             });
+
+                            // Override browser default key bindings in iframe.
+                            contentWindow.document.addEventListener('keydown', (e) => {
+                                // use Ctrl-D/Cmd-D to toggle docs
+                                if (
+                                    (isMacOS()
+                                        ? e.metaKey && !e.ctrlKey
+                                        : e.ctrlKey && !e.metaKey) &&
+                                    !e.altKey &&
+                                    e.key == 'd'
+                                ) {
+                                    e.preventDefault();
+                                    dispatch(toggleBoolean(SettingId.ShowDocs));
+                                }
+                            });
                         }}
                         src="static/docs/index.html"
                         allowFullScreen={true}

From eb2cf3c956d1149018f3dea3de78d82b0e98d46c Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Wed, 27 Jan 2021 16:33:03 -0600
Subject: [PATCH 09/16] add global keyboard shortcut for toggling docs

This handles the cases when the editor is not active and the docs pane
is not active and the terminal is not active.
---
 src/components/SettingsDrawer.tsx | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/src/components/SettingsDrawer.tsx b/src/components/SettingsDrawer.tsx
index 52dbdde7..da4b665d 100644
--- a/src/components/SettingsDrawer.tsx
+++ b/src/components/SettingsDrawer.tsx
@@ -8,6 +8,9 @@ import {
     Classes,
     Drawer,
     FormGroup,
+    Hotkey,
+    Hotkeys,
+    HotkeysTarget,
     Position,
     Switch,
     Tooltip,
@@ -17,7 +20,7 @@ import React from 'react';
 import { connect } from 'react-redux';
 import { Action, Dispatch } from '../actions';
 import { closeSettings, openAboutDialog } from '../actions/app';
-import { setBoolean } from '../actions/settings';
+import { setBoolean, toggleBoolean } from '../actions/settings';
 import { RootState } from '../reducers';
 import { pseudolocalize } from '../settings/i18n';
 import {
@@ -47,10 +50,12 @@ type DispatchProps = {
     onDarkModeChanged: (checked: boolean) => void;
     onFlashCurrentProgramChanged: (checked: boolean) => void;
     onAbout: () => void;
+    onToggleDocs: () => void;
 };
 
 type SettingsProps = StateProps & DispatchProps & WithI18nProps;
 
+@HotkeysTarget
 class SettingsDrawer extends React.PureComponent<SettingsProps> {
     render(): JSX.Element {
         const {
@@ -223,6 +228,22 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
             </Drawer>
         );
     }
+
+    renderHotkeys(): JSX.Element {
+        return (
+            <Hotkeys>
+                <Hotkey
+                    combo="mod+d"
+                    label={this.props.i18n.translate(
+                        SettingsStringId.AppearanceDocumentationTooltip,
+                    )}
+                    global={true}
+                    preventDefault={true}
+                    onKeyDown={() => this.props.onToggleDocs()}
+                />
+            </Hotkeys>
+        );
+    }
 }
 
 const mapStateToProps = (state: RootState): StateProps => ({
@@ -241,6 +262,7 @@ const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
     onFlashCurrentProgramChanged: (checked): Action =>
         dispatch(setBoolean(SettingId.FlashCurrentProgram, checked)),
     onAbout: (): Action => dispatch(openAboutDialog()),
+    onToggleDocs: (): Action => dispatch(toggleBoolean(SettingId.ShowDocs)),
 });
 
 export default connect(

From 952416f36b3000f248141134ff3b25aecefc462b Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Wed, 27 Jan 2021 18:07:36 -0600
Subject: [PATCH 10/16] apply scroll bar styling to docs iframe

---
 src/components/App.tsx | 59 ++++++++++++++++++++++++++++++++++++++++++
 src/index.tsx          | 12 +++++++++
 2 files changed, 71 insertions(+)

diff --git a/src/components/App.tsx b/src/components/App.tsx
index a04b7daf..ec56eb0b 100644
--- a/src/components/App.tsx
+++ b/src/components/App.tsx
@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2020 The Pybricks Authors
 
+import { Classes } from '@blueprintjs/core';
 import React, { useState } from 'react';
 import { useDispatch, useSelector } from 'react-redux';
 import SplitterLayout from 'react-splitter-layout';
@@ -55,6 +56,11 @@ function App(): JSX.Element {
                 <div className="h-100 w-100">
                     {dragging && <div className="h-100 w-100 p-absolute" />}
                     <iframe
+                        // REVISIT: some of this could be moved to the docs repo
+                        // so that it runs earlier to prevent flashing in the UI.
+                        // The load event doesn't run until after the page is fully
+                        // loaded and there doesn't seem to be a reasonable way to
+                        // hook into the iframe to know when it has a new document.
                         onLoad={(e) => {
                             // HACK: this mess restores the scroll position when
                             // the documentation iframe visibility is toggled.
@@ -138,6 +144,59 @@ function App(): JSX.Element {
                                     dispatch(toggleBoolean(SettingId.ShowDocs));
                                 }
                             });
+
+                            const style = document.createElement('style');
+
+                            // TODO: how to get these programmatically from values set in variables.scss?
+                            const iconColor = '#5c7080';
+                            const iconColorHover = '#182026';
+                            const appBackgroundColor = '#e8e8e8';
+                            const darkIconColor = '#a7b6c2';
+                            const darkIconColorHover = '#f5f8fa';
+                            const darkAppBackgroundColor = '#293742';
+
+                            // This is scrollbar style coped from index.scss.
+                            style.innerText = `
+::-webkit-scrollbar {
+    width: 16px;
+}
+
+.${Classes.DARK} ::-webkit-scrollbar-track {
+    background: ${darkAppBackgroundColor};
+}
+
+::-webkit-scrollbar-track {
+    background: ${appBackgroundColor};
+}
+
+.${Classes.DARK} ::-webkit-scrollbar-thumb {
+    border-color: ${darkAppBackgroundColor};
+    background: ${darkIconColor};
+}
+
+::-webkit-scrollbar-thumb {
+    border-width: 3px;
+    border-style: solid;
+    border-radius: 8px;
+    border-color: ${appBackgroundColor};
+    background: ${iconColor};
+}
+
+.${Classes.DARK} ::-webkit-scrollbar-thumb:hover {
+    background: ${darkIconColorHover};
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: ${iconColorHover};
+}
+`;
+                            contentWindow.document.head.appendChild(style);
+
+                            if (document.body.classList.contains(Classes.DARK)) {
+                                contentWindow.document.documentElement.classList.add(
+                                    Classes.DARK,
+                                );
+                            }
                         }}
                         src="static/docs/index.html"
                         allowFullScreen={true}
diff --git a/src/index.tsx b/src/index.tsx
index 974b0cf1..94154f7f 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -44,8 +44,20 @@ store.subscribe(() => {
     if (newDarkMode !== oldDarkMode) {
         if (newDarkMode) {
             document.body.classList.add(Classes.DARK);
+            for (const frame of document.getElementsByTagName('iframe')) {
+                console.log('dark');
+                frame.contentWindow?.document.documentElement.classList.add(
+                    Classes.DARK,
+                );
+            }
         } else {
             document.body.classList.remove(Classes.DARK);
+            for (const frame of document.getElementsByTagName('iframe')) {
+                console.log('light');
+                frame.contentWindow?.document.documentElement.classList.remove(
+                    Classes.DARK,
+                );
+            }
         }
         oldDarkMode = newDarkMode;
     }

From 066a6c7d3d44feb494fcdccf514947876f9c6004 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 12:45:17 -0600
Subject: [PATCH 11/16] move scrollbar styling to @pybricks/ide-docs

This makes the scrollbar flashing less noticeable, but there is still
a bit of a flash in dark mode due to the fact that we are still
injecting the class in the load event in that case.
---
 package.json           |  2 +-
 src/components/App.tsx | 47 ------------------------------------------
 yarn.lock              |  8 +++----
 3 files changed, 5 insertions(+), 52 deletions(-)

diff --git a/package.json b/package.json
index 353b949a..6e35fd59 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
         "@blueprintjs/core": "^3.38.1",
         "@craco/craco": "^6.0.0",
         "@pybricks/firmware": "4.5.0",
-        "@pybricks/ide-docs": "1.0.0",
+        "@pybricks/ide-docs": "1.1.0",
         "@pybricks/mpy-cross-v5": "^2.0.0",
         "@shopify/react-i18n": "^5.2.1",
         "@testing-library/dom": "^7.29.2",
diff --git a/src/components/App.tsx b/src/components/App.tsx
index ec56eb0b..7fcfe8c3 100644
--- a/src/components/App.tsx
+++ b/src/components/App.tsx
@@ -145,53 +145,6 @@ function App(): JSX.Element {
                                 }
                             });
 
-                            const style = document.createElement('style');
-
-                            // TODO: how to get these programmatically from values set in variables.scss?
-                            const iconColor = '#5c7080';
-                            const iconColorHover = '#182026';
-                            const appBackgroundColor = '#e8e8e8';
-                            const darkIconColor = '#a7b6c2';
-                            const darkIconColorHover = '#f5f8fa';
-                            const darkAppBackgroundColor = '#293742';
-
-                            // This is scrollbar style coped from index.scss.
-                            style.innerText = `
-::-webkit-scrollbar {
-    width: 16px;
-}
-
-.${Classes.DARK} ::-webkit-scrollbar-track {
-    background: ${darkAppBackgroundColor};
-}
-
-::-webkit-scrollbar-track {
-    background: ${appBackgroundColor};
-}
-
-.${Classes.DARK} ::-webkit-scrollbar-thumb {
-    border-color: ${darkAppBackgroundColor};
-    background: ${darkIconColor};
-}
-
-::-webkit-scrollbar-thumb {
-    border-width: 3px;
-    border-style: solid;
-    border-radius: 8px;
-    border-color: ${appBackgroundColor};
-    background: ${iconColor};
-}
-
-.${Classes.DARK} ::-webkit-scrollbar-thumb:hover {
-    background: ${darkIconColorHover};
-}
-
-::-webkit-scrollbar-thumb:hover {
-    background: ${iconColorHover};
-}
-`;
-                            contentWindow.document.head.appendChild(style);
-
                             if (document.body.classList.contains(Classes.DARK)) {
                                 contentWindow.document.documentElement.classList.add(
                                     Classes.DARK,
diff --git a/yarn.lock b/yarn.lock
index 81986879..d8f8d0c4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1462,10 +1462,10 @@
   dependencies:
     jszip "^3.5.0"
 
-"@pybricks/ide-docs@1.0.0":
-  version "1.0.0"
-  resolved "https://registry.yarnpkg.com/@pybricks/ide-docs/-/ide-docs-1.0.0.tgz#e93ff78c65730bbdd26b9deaf3110799d46de8e6"
-  integrity sha512-pe52fHG3S2QIx7RLX8+a+5oQo5A/svR2bxJWWImwZ2unAbPYmZ2G/25zgtYb9JF4Fec2f9mLT2zRiGqUjiCjiw==
+"@pybricks/ide-docs@1.1.0":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@pybricks/ide-docs/-/ide-docs-1.1.0.tgz#15c46def964ad8e92805bc3746a1d418d145e5c4"
+  integrity sha512-NwEPoAnMSvNShtzXSSuf+zOf3COPzXb0DQiD7RV6p3edCPvcgZn53JZvZscXdyudAruOMHZciw/jW8X4dJee2g==
 
 "@pybricks/mpy-cross-v5@^2.0.0":
   version "2.0.0"

From 447e7e901bad614ce119648c8eab2cbf1954f938 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 14:00:09 -0600
Subject: [PATCH 12/16] pass registration to reload action

---
 src/actions/app.ts        |  8 +++++---
 src/sagas/app.test.ts     |  7 +------
 src/sagas/app.ts          | 13 +++----------
 src/sagas/notification.ts | 11 ++++++++---
 4 files changed, 17 insertions(+), 22 deletions(-)

diff --git a/src/actions/app.ts b/src/actions/app.ts
index e4143d25..48e370d7 100644
--- a/src/actions/app.ts
+++ b/src/actions/app.ts
@@ -26,11 +26,13 @@ export enum AppActionType {
 }
 
 /** Action that requests the app to reload. */
-export type AppReloadAction = Action<AppActionType.Reload>;
+export type AppReloadAction = Action<AppActionType.Reload> & {
+    registration: ServiceWorkerRegistration;
+};
 
 /** Creates an action that requests the app to reload. */
-export function reload(): AppReloadAction {
-    return { type: AppActionType.Reload };
+export function reload(registration: ServiceWorkerRegistration): AppReloadAction {
+    return { type: AppActionType.Reload, registration };
 }
 
 /** Action that indicates the app has just started. */
diff --git a/src/sagas/app.test.ts b/src/sagas/app.test.ts
index 44fa538e..6443a394 100644
--- a/src/sagas/app.test.ts
+++ b/src/sagas/app.test.ts
@@ -13,11 +13,6 @@ test('reload', async () => {
         unregister: jest.fn(),
     };
 
-    // @ts-expect-error: navigator.serviceWorker is not implemented in JSDOM
-    navigator.serviceWorker = {
-        getRegistrations: jest.fn().mockResolvedValue([registration]),
-    };
-
     // @ts-expect-error: JSDOM implementation of location.reload() causes error
     delete window.location;
     // @ts-expect-error: JSDOM implementation of location.reload() causes error
@@ -25,7 +20,7 @@ test('reload', async () => {
         reload: jest.fn(),
     };
 
-    saga.put(reload());
+    saga.put(reload(registration as ServiceWorkerRegistration));
 
     // yield to allow generators to complete
     await delay(0);
diff --git a/src/sagas/app.ts b/src/sagas/app.ts
index 192b92de..8e8ced7a 100644
--- a/src/sagas/app.ts
+++ b/src/sagas/app.ts
@@ -2,17 +2,10 @@
 // Copyright (c) 2021 The Pybricks Authors
 
 import { call, takeEvery } from 'typed-redux-saga/macro';
-import { AppActionType } from '../actions/app';
-
-function* reload(): Generator {
-    // unregister the service worker so that when the page reloads, it uses
-    // the new version
-    const registrations = yield* call(() => navigator.serviceWorker.getRegistrations());
-
-    for (const r of registrations) {
-        yield* call(() => r.unregister());
-    }
+import { AppActionType, AppReloadAction } from '../actions/app';
 
+function* reload(action: AppReloadAction): Generator {
+    yield* call(() => action.registration.unregister());
     location.reload();
 }
 
diff --git a/src/sagas/notification.ts b/src/sagas/notification.ts
index d976198b..30e637c2 100644
--- a/src/sagas/notification.ts
+++ b/src/sagas/notification.ts
@@ -33,7 +33,10 @@ import {
 } from '../actions/lwp3-bootloader';
 import { MpyActionType, MpyDidFailToCompileAction } from '../actions/mpy';
 import { NotificationActionType, NotificationAddAction } from '../actions/notification';
-import { ServiceWorkerActionType } from '../actions/service-worker';
+import {
+    ServiceWorkerAction,
+    ServiceWorkerActionType,
+} from '../actions/service-worker';
 import Notification from '../components/Notification';
 import UnexpectedErrorNotification from '../components/UnexpectedErrorNotification';
 import { MessageId } from '../components/notification-i18n';
@@ -323,7 +326,9 @@ function* addNotification(action: NotificationAddAction): Generator {
     });
 }
 
-function* showServiceWorkerUpdate(): Generator {
+function* showServiceWorkerUpdate(
+    updateAction: ServiceWorkerAction<ServiceWorkerActionType.DidUpdate>,
+): Generator {
     const ch = channel<React.MouseEvent<HTMLElement>>();
     const action = dispatchAction(
         MessageId.ServiceWorkerUpdateAction,
@@ -343,7 +348,7 @@ function* showServiceWorkerUpdate(): Generator {
 
     yield* take(ch);
 
-    yield* put(reload());
+    yield* put(reload(updateAction.registration));
 }
 
 export default function* (): Generator {

From e59bfd4474632078676fc6ac5e894f8ffee342cc Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 15:37:40 -0600
Subject: [PATCH 13/16] add UI to manually check for update

This adds a button to call the ServiceWorkerRegistration.update()
function. This button will be hidden if there is already an update
pending.

This also adds a button to restart the app to apply the update. This
is nice in case users accidentally close the notification that asks
to restart.

The about button is moved to the new app group in the setting menu.
---
 src/actions/app.ts                       | 28 ++++++++++++
 src/components/SettingsDrawer.tsx        | 58 +++++++++++++++++++++---
 src/components/notification-i18n.en.json |  3 ++
 src/components/notification-i18n.ts      |  1 +
 src/components/settings-i18n.en.json     |  9 ++++
 src/components/settings-i18n.ts          |  5 +-
 src/reducers/app.ts                      | 51 ++++++++++++++++++++-
 src/sagas/app.test.ts                    | 24 +++++++++-
 src/sagas/app.ts                         | 16 ++++++-
 src/sagas/notification.test.ts           |  3 ++
 src/sagas/notification.ts                | 20 +++++++-
 11 files changed, 205 insertions(+), 13 deletions(-)

diff --git a/src/actions/app.ts b/src/actions/app.ts
index 48e370d7..34e92b2a 100644
--- a/src/actions/app.ts
+++ b/src/actions/app.ts
@@ -9,6 +9,10 @@ import { Action } from 'redux';
 export enum AppActionType {
     /** Reload the app. */
     Reload = 'app.action.reload',
+    /** Checks for an available update. */
+    CheckForUpdate = 'app.action.checkForUpdate',
+    /** Indicates that checking for update finished. */
+    DidCheckForUpdate = 'app.action.didCheckForUpdate',
     /** The app has just ben started. */
     DidStart = 'app.action.didStart',
     /** Open settings dialog. */
@@ -35,6 +39,28 @@ export function reload(registration: ServiceWorkerRegistration): AppReloadAction
     return { type: AppActionType.Reload, registration };
 }
 
+/** Action that requests to check for updates. */
+export type AppCheckForUpdatesAction = Action<AppActionType.CheckForUpdate> & {
+    registration: ServiceWorkerRegistration;
+};
+
+/** Action that requests to check for updates. */
+export function checkForUpdate(
+    registration: ServiceWorkerRegistration,
+): AppCheckForUpdatesAction {
+    return { type: AppActionType.CheckForUpdate, registration };
+}
+
+/** Action that indicates that checking for an update has completed. */
+export type AppDidCheckForUpdateAction = Action<AppActionType.DidCheckForUpdate> & {
+    updateFound: boolean;
+};
+
+/** Action that indicates that checking for an update has completed. */
+export function didCheckForUpdate(updateFound: boolean): AppDidCheckForUpdateAction {
+    return { type: AppActionType.DidCheckForUpdate, updateFound };
+}
+
 /** Action that indicates the app has just started. */
 export type AppDidStartAction = Action<AppActionType.DidStart>;
 
@@ -94,6 +120,8 @@ export function closeLicenseDialog(): AppCloseLicenseDialogAction {
 /** common type for all app actions. */
 export type AppAction =
     | AppReloadAction
+    | AppCheckForUpdatesAction
+    | AppDidCheckForUpdateAction
     | AppDidStartAction
     | AppOpenSettingsAction
     | AppCloseSettingsAction
diff --git a/src/components/SettingsDrawer.tsx b/src/components/SettingsDrawer.tsx
index da4b665d..8020fdad 100644
--- a/src/components/SettingsDrawer.tsx
+++ b/src/components/SettingsDrawer.tsx
@@ -19,7 +19,7 @@ import { WithI18nProps, withI18n } from '@shopify/react-i18n';
 import React from 'react';
 import { connect } from 'react-redux';
 import { Action, Dispatch } from '../actions';
-import { closeSettings, openAboutDialog } from '../actions/app';
+import { checkForUpdate, closeSettings, openAboutDialog, reload } from '../actions/app';
 import { setBoolean, toggleBoolean } from '../actions/settings';
 import { RootState } from '../reducers';
 import { pseudolocalize } from '../settings/i18n';
@@ -42,6 +42,9 @@ type StateProps = {
     showDocs: boolean;
     darkMode: boolean;
     flashCurrentProgram: boolean;
+    serviceWorker: ServiceWorkerRegistration | null;
+    checkingForUpdate: boolean;
+    updateAvailable: boolean;
 };
 
 type DispatchProps = {
@@ -51,6 +54,8 @@ type DispatchProps = {
     onFlashCurrentProgramChanged: (checked: boolean) => void;
     onAbout: () => void;
     onToggleDocs: () => void;
+    onCheckForUpdate: (registration: ServiceWorkerRegistration) => void;
+    onReload: (registration: ServiceWorkerRegistration) => void;
 };
 
 type SettingsProps = StateProps & DispatchProps & WithI18nProps;
@@ -59,16 +64,21 @@ type SettingsProps = StateProps & DispatchProps & WithI18nProps;
 class SettingsDrawer extends React.PureComponent<SettingsProps> {
     render(): JSX.Element {
         const {
-            i18n,
             open,
-            onClose,
             showDocs,
-            onShowDocsChanged,
             darkMode,
-            onDarkModeChanged,
+            serviceWorker,
             flashCurrentProgram,
+            checkingForUpdate,
+            updateAvailable,
+            onClose,
+            onShowDocsChanged,
+            onDarkModeChanged,
             onFlashCurrentProgramChanged,
             onAbout,
+            onCheckForUpdate,
+            onReload,
+            i18n,
         } = this.props;
         return (
             <Drawer
@@ -200,6 +210,36 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
                                     &nbsp;
                                     <ExternalLinkIcon />
                                 </AnchorButton>
+                                <AboutDialog />
+                            </ButtonGroup>
+                        </FormGroup>
+                        <FormGroup label={i18n.translate(SettingsStringId.AppTitle)}>
+                            <ButtonGroup
+                                minimal={true}
+                                vertical={true}
+                                alignText="left"
+                            >
+                                {serviceWorker && !updateAvailable && (
+                                    <Button
+                                        icon="refresh"
+                                        onClick={() => onCheckForUpdate(serviceWorker)}
+                                        loading={checkingForUpdate}
+                                    >
+                                        {i18n.translate(
+                                            SettingsStringId.AppCheckForUpdateLabel,
+                                        )}
+                                    </Button>
+                                )}
+                                {serviceWorker && updateAvailable && (
+                                    <Button
+                                        icon="refresh"
+                                        onClick={() => onReload(serviceWorker)}
+                                    >
+                                        {i18n.translate(
+                                            SettingsStringId.AppRestartLabel,
+                                        )}
+                                    </Button>
+                                )}
                                 <Button
                                     icon="info-sign"
                                     onClick={() => {
@@ -207,9 +247,8 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
                                         return true;
                                     }}
                                 >
-                                    {i18n.translate(SettingsStringId.HelpAboutLabel)}
+                                    {i18n.translate(SettingsStringId.AppAboutLabel)}
                                 </Button>
-                                <AboutDialog />
                             </ButtonGroup>
                         </FormGroup>
                         {process.env.NODE_ENV === 'development' && (
@@ -251,6 +290,9 @@ const mapStateToProps = (state: RootState): StateProps => ({
     showDocs: state.settings.showDocs,
     darkMode: state.settings.darkMode,
     flashCurrentProgram: state.settings.flashCurrentProgram,
+    serviceWorker: state.app.serviceWorker,
+    checkingForUpdate: state.app.checkingForUpdate,
+    updateAvailable: state.app.updateAvailable,
 });
 
 const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
@@ -263,6 +305,8 @@ const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
         dispatch(setBoolean(SettingId.FlashCurrentProgram, checked)),
     onAbout: (): Action => dispatch(openAboutDialog()),
     onToggleDocs: (): Action => dispatch(toggleBoolean(SettingId.ShowDocs)),
+    onCheckForUpdate: (registration) => dispatch(checkForUpdate(registration)),
+    onReload: (registration) => dispatch(reload(registration)),
 });
 
 export default connect(
diff --git a/src/components/notification-i18n.en.json b/src/components/notification-i18n.en.json
index e5fb0bd5..c1ab03e6 100644
--- a/src/components/notification-i18n.en.json
+++ b/src/components/notification-i18n.en.json
@@ -1,6 +1,9 @@
 {
     "copyErrorMessage": "Copy Error Message",
     "reportBug": "Report Bug",
+    "app": {
+        "noUpdateFound": "{appName} is already up to date."
+    },
     "ble": {
         "gattPermission": "The web browser did not give permission to use Bluetooth Low Energy",
         "gattServiceNotFound": "Connected to hub but failed to get {serviceName} service. Try removing the \"{hubName}\" device in your OS Bluetooth settings, then try again.",
diff --git a/src/components/notification-i18n.ts b/src/components/notification-i18n.ts
index 8e39bf64..132562ea 100644
--- a/src/components/notification-i18n.ts
+++ b/src/components/notification-i18n.ts
@@ -4,6 +4,7 @@
 // Notification translation keys.
 
 export enum MessageId {
+    AppNoUpdateFound = 'app.noUpdateFound',
     CopyErrorMessage = 'copyErrorMessage',
     ReportBug = 'reportBug',
     BleUnexpectedError = 'ble.unexpectedError',
diff --git a/src/components/settings-i18n.en.json b/src/components/settings-i18n.en.json
index d3996591..6d5488cb 100644
--- a/src/components/settings-i18n.en.json
+++ b/src/components/settings-i18n.en.json
@@ -35,6 +35,15 @@
             },
             "bugs": {
                 "label": "Bug Reports"
+            }
+        },
+        "app": {
+            "title": "App",
+            "checkForUpdate": {
+                "label": "Check for Update"
+            },
+            "restart": {
+                "label": "Restart to Install Update"
             },
             "about": {
                 "label": "About"
diff --git a/src/components/settings-i18n.ts b/src/components/settings-i18n.ts
index bc16e13c..9f49fbb6 100644
--- a/src/components/settings-i18n.ts
+++ b/src/components/settings-i18n.ts
@@ -19,5 +19,8 @@ export enum SettingsStringId {
     HelpSupportLabel = 'settings.help.support.label',
     HelpChatLabel = 'settings.help.chat.label',
     HelpBugsLabel = 'settings.help.bugs.label',
-    HelpAboutLabel = 'settings.help.about.label',
+    AppTitle = 'settings.app.title',
+    AppCheckForUpdateLabel = 'settings.app.checkForUpdate.label',
+    AppRestartLabel = 'settings.app.restart.label',
+    AppAboutLabel = 'settings.app.about.label',
 }
diff --git a/src/reducers/app.ts b/src/reducers/app.ts
index 3bcce3ea..44436048 100644
--- a/src/reducers/app.ts
+++ b/src/reducers/app.ts
@@ -6,11 +6,15 @@
 import { Reducer, combineReducers } from 'redux';
 import { Action } from '../actions';
 import { AppActionType } from '../actions/app';
+import { ServiceWorkerActionType } from '../actions/service-worker';
 
 export interface AppState {
     readonly showSettings: boolean;
     readonly showAboutDialog: boolean;
     readonly showLicenseDialog: boolean;
+    readonly serviceWorker: ServiceWorkerRegistration | null;
+    readonly checkingForUpdate: boolean;
+    readonly updateAvailable: boolean;
 }
 
 const showSettings: Reducer<boolean, Action> = (state = false, action) => {
@@ -46,4 +50,49 @@ const showLicenseDialog: Reducer<boolean, Action> = (state = false, action) => {
     }
 };
 
-export default combineReducers({ showSettings, showAboutDialog, showLicenseDialog });
+const serviceWorker: Reducer<ServiceWorkerRegistration | null, Action> = (
+    state = null,
+    action,
+) => {
+    switch (action.type) {
+        case ServiceWorkerActionType.DidSucceed:
+            return action.registration;
+        default:
+            return state;
+    }
+};
+
+const checkingForUpdate: Reducer<boolean, Action> = (state = false, action) => {
+    switch (action.type) {
+        case AppActionType.CheckForUpdate:
+            return true;
+        case AppActionType.DidCheckForUpdate:
+            if (!action.updateFound) {
+                return false;
+            }
+            // otherwise we wait for service worker to download everything
+            return state;
+        case ServiceWorkerActionType.DidUpdate:
+            return false;
+        default:
+            return state;
+    }
+};
+
+const updateAvailable: Reducer<boolean, Action> = (state = false, action) => {
+    switch (action.type) {
+        case ServiceWorkerActionType.DidUpdate:
+            return true;
+        default:
+            return state;
+    }
+};
+
+export default combineReducers({
+    showSettings,
+    showAboutDialog,
+    showLicenseDialog,
+    serviceWorker,
+    checkingForUpdate,
+    updateAvailable,
+});
diff --git a/src/sagas/app.test.ts b/src/sagas/app.test.ts
index 6443a394..86a50431 100644
--- a/src/sagas/app.test.ts
+++ b/src/sagas/app.test.ts
@@ -2,7 +2,7 @@
 // Copyright (c) 2021 The Pybricks Authors
 
 import { AsyncSaga, delay } from '../../test';
-import { reload } from '../actions/app';
+import { checkForUpdate, didCheckForUpdate, reload } from '../actions/app';
 import app from './app';
 
 test('reload', async () => {
@@ -30,3 +30,25 @@ test('reload', async () => {
 
     await saga.end();
 });
+
+test('checkForUpdates', async () => {
+    const saga = new AsyncSaga(app);
+
+    // mock registration as if service worker was register on app startup
+    const registration: Partial<ServiceWorkerRegistration> = {
+        update: jest.fn(),
+        installing: null,
+    };
+
+    saga.put(checkForUpdate(registration as ServiceWorkerRegistration));
+
+    // yield to allow generators to complete
+    await delay(0);
+
+    expect(registration.update).toHaveBeenCalled();
+
+    const action = await saga.take();
+    expect(action).toStrictEqual(didCheckForUpdate(false));
+
+    await saga.end();
+});
diff --git a/src/sagas/app.ts b/src/sagas/app.ts
index 8e8ced7a..1f069fb7 100644
--- a/src/sagas/app.ts
+++ b/src/sagas/app.ts
@@ -1,14 +1,26 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2021 The Pybricks Authors
 
-import { call, takeEvery } from 'typed-redux-saga/macro';
-import { AppActionType, AppReloadAction } from '../actions/app';
+import { call, put, takeEvery } from 'typed-redux-saga/macro';
+import {
+    AppActionType,
+    AppCheckForUpdatesAction,
+    AppReloadAction,
+    didCheckForUpdate,
+} from '../actions/app';
 
 function* reload(action: AppReloadAction): Generator {
     yield* call(() => action.registration.unregister());
     location.reload();
 }
 
+function* checkForUpdate(action: AppCheckForUpdatesAction): Generator {
+    yield* call(() => action.registration.update());
+    const updateFound = action.registration.installing !== null;
+    yield* put(didCheckForUpdate(updateFound));
+}
+
 export default function* app(): Generator {
     yield* takeEvery(AppActionType.Reload, reload);
+    yield* takeEvery(AppActionType.CheckForUpdate, checkForUpdate);
 }
diff --git a/src/sagas/notification.test.ts b/src/sagas/notification.test.ts
index 0f456bc9..0431e5f5 100644
--- a/src/sagas/notification.test.ts
+++ b/src/sagas/notification.test.ts
@@ -5,6 +5,7 @@ import { IToaster } from '@blueprintjs/core';
 import { FirmwareReaderError, FirmwareReaderErrorCode } from '@pybricks/firmware';
 import { AsyncSaga } from '../../test';
 import { Action } from '../actions';
+import { didCheckForUpdate } from '../actions/app';
 import {
     BleDeviceFailToConnectReasonType,
     didFailToConnect as bleDidFailToConnect,
@@ -71,6 +72,7 @@ test.each([
     didFailToFinish(FailToFinishReasonType.FailedToCompile),
     didFailToFinish(FailToFinishReasonType.FirmwareSize),
     didFailToFinish(FailToFinishReasonType.Unknown, new Error('test error')),
+    didCheckForUpdate(false),
 ])('actions that should show notification: %o', async (action: Action) => {
     const getToasts = jest.fn().mockReturnValue([]);
     const show = jest.fn();
@@ -100,6 +102,7 @@ test.each([
     bootloaderDidFailToConnect(BootloaderConnectionFailureReason.Canceled),
     didFailToFinish(FailToFinishReasonType.FailedToConnect),
     didSucceed({} as ServiceWorkerRegistration),
+    didCheckForUpdate(true),
 ])('actions that should not show a notification: %o', async (action: Action) => {
     const getToasts = jest.fn().mockReturnValue([]);
     const show = jest.fn();
diff --git a/src/sagas/notification.ts b/src/sagas/notification.ts
index 30e637c2..96073b07 100644
--- a/src/sagas/notification.ts
+++ b/src/sagas/notification.ts
@@ -14,7 +14,7 @@ import { Replacements } from '@shopify/react-i18n';
 import React from 'react';
 import { channel } from 'redux-saga';
 import { delay, getContext, put, take, takeEvery } from 'typed-redux-saga/macro';
-import { reload } from '../actions/app';
+import { AppActionType, AppDidCheckForUpdateAction, reload } from '../actions/app';
 import {
     BleDeviceActionType,
     BleDeviceDidFailToConnectAction,
@@ -351,6 +351,23 @@ function* showServiceWorkerUpdate(
     yield* put(reload(updateAction.registration));
 }
 
+function* showNoUpdateInfo(action: AppDidCheckForUpdateAction): Generator {
+    if (action.updateFound) {
+        // this will be handled by ServiceWorkerActionType.DidUpdate action
+        return;
+    }
+
+    const { toaster } = yield* getContext<NotificationContext>('notification');
+    toaster.show({
+        intent: mapIntent(Level.Info),
+        icon: mapIcon(Level.Info),
+        message: React.createElement(Notification, {
+            messageId: MessageId.AppNoUpdateFound,
+            replacements: { appName },
+        }),
+    });
+}
+
 export default function* (): Generator {
     yield* takeEvery(
         BleDeviceActionType.DidFailToConnect,
@@ -366,4 +383,5 @@ export default function* (): Generator {
     yield* takeEvery(MpyActionType.DidFailToCompile, showCompilerError);
     yield* takeEvery(NotificationActionType.Add, addNotification);
     yield* takeEvery(ServiceWorkerActionType.DidUpdate, showServiceWorkerUpdate);
+    yield* takeEvery(AppActionType.DidCheckForUpdate, showNoUpdateInfo);
 }

From 252c741180a8fd06e2d216f6ade342dd11cdf816 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 20:14:36 -0600
Subject: [PATCH 14/16] add app install button

---
 src/actions/app.ts                   | 51 ++++++++++++++++++++++++++
 src/components/SettingsDrawer.tsx    | 29 ++++++++++++++-
 src/components/settings-i18n.en.json |  3 ++
 src/components/settings-i18n.ts      |  1 +
 src/reducers/app.ts                  | 30 +++++++++++++++
 src/sagas/app.test.ts                | 55 ++++++++++++++++++++++++++--
 src/sagas/app.ts                     | 52 +++++++++++++++++++++++++-
 src/utils/dom.ts                     | 13 +++++++
 8 files changed, 228 insertions(+), 6 deletions(-)
 create mode 100644 src/utils/dom.ts

diff --git a/src/actions/app.ts b/src/actions/app.ts
index 34e92b2a..cd09b533 100644
--- a/src/actions/app.ts
+++ b/src/actions/app.ts
@@ -4,6 +4,7 @@
 // Actions for the app in general.
 
 import { Action } from 'redux';
+import { BeforeInstallPromptEvent } from '../utils/dom';
 
 /** App action types. */
 export enum AppActionType {
@@ -13,6 +14,14 @@ export enum AppActionType {
     CheckForUpdate = 'app.action.checkForUpdate',
     /** Indicates that checking for update finished. */
     DidCheckForUpdate = 'app.action.didCheckForUpdate',
+    /* Indicates the browser wants to prompt the use to install the app. */
+    DidBeforeInstallPrompt = 'app.action.didBeforeInstallPrompt',
+    /* Requests to prompt the user to install the app. */
+    InstallPrompt = 'app.action.installPrompt',
+    /* Indicates that the user responded to the install prompt. */
+    DidInstallPrompt = 'app.action.didInstallPrompt',
+    /* Indicates that the app was installed. */
+    DidInstall = 'app.action.didInstallPrompt',
     /** The app has just ben started. */
     DidStart = 'app.action.didStart',
     /** Open settings dialog. */
@@ -61,6 +70,44 @@ export function didCheckForUpdate(updateFound: boolean): AppDidCheckForUpdateAct
     return { type: AppActionType.DidCheckForUpdate, updateFound };
 }
 
+/* Action that indicates the browser wants to prompt the use to install the app. */
+export type AppDidBeforeInstallPromptAction = Action<AppActionType.DidBeforeInstallPrompt> & {
+    event: BeforeInstallPromptEvent;
+};
+
+/* Action that indicates the browser wants to prompt the use to install the app. */
+export function didBeforeInstallPrompt(
+    event: BeforeInstallPromptEvent,
+): AppDidBeforeInstallPromptAction {
+    return { type: AppActionType.DidBeforeInstallPrompt, event };
+}
+
+/* Action that requests to prompt the user to install the app. */
+export type AppInstallPromptAction = Action<AppActionType.InstallPrompt> & {
+    event: BeforeInstallPromptEvent;
+};
+
+/* Action that requests to prompt the user to install the app. */
+export function installPrompt(event: BeforeInstallPromptEvent): AppInstallPromptAction {
+    return { type: AppActionType.InstallPrompt, event };
+}
+
+/* Action that indicates that the user responded to the install prompt. */
+export type AppDidInstallPromptAction = Action<AppActionType.DidInstallPrompt>;
+
+/* Action that indicates that the user responded to the install prompt. */
+export function didInstallPrompt(): AppDidInstallPromptAction {
+    return { type: AppActionType.DidInstallPrompt };
+}
+
+/* Action that indicates app was installed. */
+export type AppDidInstallAction = Action<AppActionType.DidInstall>;
+
+/* Action that indicates app was installed. */
+export function didInstall(): AppDidInstallAction {
+    return { type: AppActionType.DidInstall };
+}
+
 /** Action that indicates the app has just started. */
 export type AppDidStartAction = Action<AppActionType.DidStart>;
 
@@ -122,6 +169,10 @@ export type AppAction =
     | AppReloadAction
     | AppCheckForUpdatesAction
     | AppDidCheckForUpdateAction
+    | AppDidBeforeInstallPromptAction
+    | AppInstallPromptAction
+    | AppDidInstallPromptAction
+    | AppDidInstallAction
     | AppDidStartAction
     | AppOpenSettingsAction
     | AppCloseSettingsAction
diff --git a/src/components/SettingsDrawer.tsx b/src/components/SettingsDrawer.tsx
index 8020fdad..a9192332 100644
--- a/src/components/SettingsDrawer.tsx
+++ b/src/components/SettingsDrawer.tsx
@@ -19,7 +19,13 @@ import { WithI18nProps, withI18n } from '@shopify/react-i18n';
 import React from 'react';
 import { connect } from 'react-redux';
 import { Action, Dispatch } from '../actions';
-import { checkForUpdate, closeSettings, openAboutDialog, reload } from '../actions/app';
+import {
+    checkForUpdate,
+    closeSettings,
+    installPrompt,
+    openAboutDialog,
+    reload,
+} from '../actions/app';
 import { setBoolean, toggleBoolean } from '../actions/settings';
 import { RootState } from '../reducers';
 import { pseudolocalize } from '../settings/i18n';
@@ -31,6 +37,7 @@ import {
     tooltipDelay,
 } from '../settings/ui';
 import { SettingId } from '../settings/user';
+import { BeforeInstallPromptEvent } from '../utils/dom';
 import { isMacOS } from '../utils/os';
 import AboutDialog from './AboutDialog';
 import ExternalLinkIcon from './ExternalLinkIcon';
@@ -45,6 +52,8 @@ type StateProps = {
     serviceWorker: ServiceWorkerRegistration | null;
     checkingForUpdate: boolean;
     updateAvailable: boolean;
+    beforeInstallPrompt: BeforeInstallPromptEvent | null;
+    promptingInstall: boolean;
 };
 
 type DispatchProps = {
@@ -56,6 +65,7 @@ type DispatchProps = {
     onToggleDocs: () => void;
     onCheckForUpdate: (registration: ServiceWorkerRegistration) => void;
     onReload: (registration: ServiceWorkerRegistration) => void;
+    onInstallPrompt: (event: BeforeInstallPromptEvent) => void;
 };
 
 type SettingsProps = StateProps & DispatchProps & WithI18nProps;
@@ -71,6 +81,8 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
             flashCurrentProgram,
             checkingForUpdate,
             updateAvailable,
+            beforeInstallPrompt,
+            promptingInstall,
             onClose,
             onShowDocsChanged,
             onDarkModeChanged,
@@ -78,6 +90,7 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
             onAbout,
             onCheckForUpdate,
             onReload,
+            onInstallPrompt: onInstall,
             i18n,
         } = this.props;
         return (
@@ -219,6 +232,17 @@ class SettingsDrawer extends React.PureComponent<SettingsProps> {
                                 vertical={true}
                                 alignText="left"
                             >
+                                {beforeInstallPrompt && (
+                                    <Button
+                                        icon="add"
+                                        onClick={() => onInstall(beforeInstallPrompt)}
+                                        loading={promptingInstall}
+                                    >
+                                        {i18n.translate(
+                                            SettingsStringId.AppInstallLabel,
+                                        )}
+                                    </Button>
+                                )}
                                 {serviceWorker && !updateAvailable && (
                                     <Button
                                         icon="refresh"
@@ -293,6 +317,8 @@ const mapStateToProps = (state: RootState): StateProps => ({
     serviceWorker: state.app.serviceWorker,
     checkingForUpdate: state.app.checkingForUpdate,
     updateAvailable: state.app.updateAvailable,
+    beforeInstallPrompt: state.app.beforeInstallPrompt,
+    promptingInstall: state.app.promptingInstall,
 });
 
 const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
@@ -307,6 +333,7 @@ const mapDispatchToProps = (dispatch: Dispatch): DispatchProps => ({
     onToggleDocs: (): Action => dispatch(toggleBoolean(SettingId.ShowDocs)),
     onCheckForUpdate: (registration) => dispatch(checkForUpdate(registration)),
     onReload: (registration) => dispatch(reload(registration)),
+    onInstallPrompt: (event) => dispatch(installPrompt(event)),
 });
 
 export default connect(
diff --git a/src/components/settings-i18n.en.json b/src/components/settings-i18n.en.json
index 6d5488cb..fc418949 100644
--- a/src/components/settings-i18n.en.json
+++ b/src/components/settings-i18n.en.json
@@ -39,6 +39,9 @@
         },
         "app": {
             "title": "App",
+            "install": {
+                "label": "Install as App"
+            },
             "checkForUpdate": {
                 "label": "Check for Update"
             },
diff --git a/src/components/settings-i18n.ts b/src/components/settings-i18n.ts
index 9f49fbb6..9c89b66e 100644
--- a/src/components/settings-i18n.ts
+++ b/src/components/settings-i18n.ts
@@ -20,6 +20,7 @@ export enum SettingsStringId {
     HelpChatLabel = 'settings.help.chat.label',
     HelpBugsLabel = 'settings.help.bugs.label',
     AppTitle = 'settings.app.title',
+    AppInstallLabel = 'settings.app.install.label',
     AppCheckForUpdateLabel = 'settings.app.checkForUpdate.label',
     AppRestartLabel = 'settings.app.restart.label',
     AppAboutLabel = 'settings.app.about.label',
diff --git a/src/reducers/app.ts b/src/reducers/app.ts
index 44436048..1ff47bd7 100644
--- a/src/reducers/app.ts
+++ b/src/reducers/app.ts
@@ -7,6 +7,7 @@ import { Reducer, combineReducers } from 'redux';
 import { Action } from '../actions';
 import { AppActionType } from '../actions/app';
 import { ServiceWorkerActionType } from '../actions/service-worker';
+import { BeforeInstallPromptEvent } from '../utils/dom';
 
 export interface AppState {
     readonly showSettings: boolean;
@@ -15,6 +16,8 @@ export interface AppState {
     readonly serviceWorker: ServiceWorkerRegistration | null;
     readonly checkingForUpdate: boolean;
     readonly updateAvailable: boolean;
+    readonly beforeInstallPrompt: BeforeInstallPromptEvent;
+    readonly promptingInstall: boolean;
 }
 
 const showSettings: Reducer<boolean, Action> = (state = false, action) => {
@@ -88,6 +91,31 @@ const updateAvailable: Reducer<boolean, Action> = (state = false, action) => {
     }
 };
 
+const beforeInstallPrompt: Reducer<BeforeInstallPromptEvent | null, Action> = (
+    state = null,
+    action,
+) => {
+    switch (action.type) {
+        case AppActionType.DidBeforeInstallPrompt:
+            return action.event;
+        case AppActionType.DidInstall:
+            return null;
+        default:
+            return state;
+    }
+};
+
+const promptingInstall: Reducer<boolean, Action> = (state = false, action) => {
+    switch (action.type) {
+        case AppActionType.InstallPrompt:
+            return true;
+        case AppActionType.DidInstallPrompt:
+            return false;
+        default:
+            return state;
+    }
+};
+
 export default combineReducers({
     showSettings,
     showAboutDialog,
@@ -95,4 +123,6 @@ export default combineReducers({
     serviceWorker,
     checkingForUpdate,
     updateAvailable,
+    beforeInstallPrompt,
+    promptingInstall,
 });
diff --git a/src/sagas/app.test.ts b/src/sagas/app.test.ts
index 86a50431..0bcfd496 100644
--- a/src/sagas/app.test.ts
+++ b/src/sagas/app.test.ts
@@ -2,9 +2,40 @@
 // Copyright (c) 2021 The Pybricks Authors
 
 import { AsyncSaga, delay } from '../../test';
-import { checkForUpdate, didCheckForUpdate, reload } from '../actions/app';
+import {
+    checkForUpdate,
+    didBeforeInstallPrompt,
+    didCheckForUpdate,
+    didInstallPrompt,
+    installPrompt,
+    reload,
+} from '../actions/app';
+import { BeforeInstallPromptEvent } from '../utils/dom';
 import app from './app';
 
+test('monitorAppInstalled', async () => {
+    const saga = new AsyncSaga(app);
+
+    window.dispatchEvent(new Event('appinstalled'));
+
+    const action = await saga.take();
+    expect(action).toStrictEqual(didInstallPrompt());
+
+    await saga.end();
+});
+
+test('monitorBeforeInstallPrompt', async () => {
+    const saga = new AsyncSaga(app);
+
+    const event = new Event('beforeinstallprompt') as BeforeInstallPromptEvent;
+    window.dispatchEvent(event);
+
+    const action = await saga.take();
+    expect(action).toStrictEqual(didBeforeInstallPrompt(event));
+
+    await saga.end();
+});
+
 test('reload', async () => {
     const saga = new AsyncSaga(app);
 
@@ -22,9 +53,6 @@ test('reload', async () => {
 
     saga.put(reload(registration as ServiceWorkerRegistration));
 
-    // yield to allow generators to complete
-    await delay(0);
-
     expect(registration.unregister).toHaveBeenCalled();
     expect(location.reload).toHaveBeenCalled();
 
@@ -52,3 +80,22 @@ test('checkForUpdates', async () => {
 
     await saga.end();
 });
+
+test('installPrompt', async () => {
+    const saga = new AsyncSaga(app);
+
+    // mock registration as if service worker was register on app startup
+    const event: Partial<BeforeInstallPromptEvent> = {
+        prompt: jest.fn(),
+        userChoice: Promise.resolve({ outcome: 'accepted', platform: 'web' }),
+    };
+
+    saga.put(installPrompt(event as BeforeInstallPromptEvent));
+
+    expect(event.prompt).toHaveBeenCalled();
+
+    const action = await saga.take();
+    expect(action).toStrictEqual(didInstallPrompt());
+
+    await saga.end();
+});
diff --git a/src/sagas/app.ts b/src/sagas/app.ts
index 1f069fb7..85eac92d 100644
--- a/src/sagas/app.ts
+++ b/src/sagas/app.ts
@@ -1,13 +1,54 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2021 The Pybricks Authors
 
-import { call, put, takeEvery } from 'typed-redux-saga/macro';
+import { eventChannel } from 'redux-saga';
+import { call, fork, put, take, takeEvery } from 'typed-redux-saga/macro';
 import {
     AppActionType,
     AppCheckForUpdatesAction,
+    AppInstallPromptAction,
     AppReloadAction,
+    didBeforeInstallPrompt,
     didCheckForUpdate,
+    didInstall,
+    didInstallPrompt,
 } from '../actions/app';
+import { BeforeInstallPromptEvent } from '../utils/dom';
+
+function* monitorAppInstalled(): Generator {
+    const chan = eventChannel<Event>((emit) => {
+        const listener = (e: Event) => {
+            emit(e);
+        };
+        // chromium-only event
+        window.addEventListener('appinstalled', listener);
+        // istanbul ignore next: currently we don't ever stop monitoring
+        return () => window.removeEventListener('appinstalled', listener);
+    });
+
+    while (true) {
+        yield* take(chan);
+        yield* put(didInstall());
+    }
+}
+
+function* monitorBeforeInstallPrompt(): Generator {
+    const chan = eventChannel<BeforeInstallPromptEvent>((emit) => {
+        const listener = (e: BeforeInstallPromptEvent) => {
+            emit(e);
+        };
+        // @ts-expect-error: chromium-only event
+        window.addEventListener('beforeinstallprompt', listener);
+        // istanbul ignore next: currently we don't ever stop monitoring
+        // @ts-expect-error: chromium-only event
+        return () => window.removeEventListener('beforeinstallprompt', listener);
+    });
+
+    while (true) {
+        const event = yield* take(chan);
+        yield* put(didBeforeInstallPrompt(event));
+    }
+}
 
 function* reload(action: AppReloadAction): Generator {
     yield* call(() => action.registration.unregister());
@@ -20,7 +61,16 @@ function* checkForUpdate(action: AppCheckForUpdatesAction): Generator {
     yield* put(didCheckForUpdate(updateFound));
 }
 
+function* installPrompt(action: AppInstallPromptAction): Generator {
+    yield* call(() => action.event.prompt());
+    yield* call(() => action.event.userChoice);
+    yield* put(didInstallPrompt());
+}
+
 export default function* app(): Generator {
+    yield* fork(monitorAppInstalled);
+    yield* fork(monitorBeforeInstallPrompt);
     yield* takeEvery(AppActionType.Reload, reload);
     yield* takeEvery(AppActionType.CheckForUpdate, checkForUpdate);
+    yield* takeEvery(AppActionType.InstallPrompt, installPrompt);
 }
diff --git a/src/utils/dom.ts b/src/utils/dom.ts
new file mode 100644
index 00000000..de9082d0
--- /dev/null
+++ b/src/utils/dom.ts
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2021 The Pybricks Authors
+
+// Chromium-only API
+// https://developer.mozilla.org/en-US/docs/Web/API/BeforeInstallPromptEvent
+export interface BeforeInstallPromptEvent extends Event {
+    readonly platforms: string[];
+    readonly userChoice: Promise<{
+        outcome: 'accepted' | 'dismissed';
+        platform: string;
+    }>;
+    prompt(): Promise<void>;
+}

From 8b3606c3976d42fac23e2238fef99b3ceae10f28 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 20:37:51 -0600
Subject: [PATCH 15/16] fix check for update button not showing

this happened when the app starts when it is already up to date
---
 src/serviceWorkerRegistration.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/serviceWorkerRegistration.ts b/src/serviceWorkerRegistration.ts
index bbeffa3e..b2323922 100644
--- a/src/serviceWorkerRegistration.ts
+++ b/src/serviceWorkerRegistration.ts
@@ -63,6 +63,13 @@ function registerValidSW(swUrl: string, config?: Config): void {
     navigator.serviceWorker
         .register(swUrl)
         .then((registration) => {
+            if (registration.active) {
+                // Execute callback
+                if (config && config.onSuccess) {
+                    config.onSuccess(registration);
+                }
+            }
+
             registration.onupdatefound = () => {
                 const installingWorker = registration.installing;
                 if (installingWorker == null) {

From 128be05761a1c82777ac329c877a31ec7f08de49 Mon Sep 17 00:00:00 2001
From: David Lechner <david@pybricks.com>
Date: Thu, 28 Jan 2021 20:47:56 -0600
Subject: [PATCH 16/16] v1.0.0-beta.5

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 6e35fd59..aacb4eff 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@pybricks/pybricks-code",
-    "version": "1.0.0-beta.4",
+    "version": "1.0.0-beta.5",
     "license": "MIT",
     "author": "The Pybricks Authors",
     "repository": {