Re-enable the red box to show available space

mgeisler · mgeisler · commit 5f3010d88a14 · 2025-09-28T10:17:07.000+02:00
Way back in #187, I introduced a hacky tool to show the available space on a slide: it was a `mdbook` plugin which injected the necessary CSS on each slide. Crude, but it got the job done. The logic was moved from Python to a real CSS file with associated JavaScript in #1842. In #1917, the functionality was moved to a dedicated “instructor menu”, together with functionality for saving the state of the Playground on each slide. Unfortunately, the whole thing was disabled in #1935 since I found that the Playgrounds lost their code with the saving logic. I was also not 100% happy with dedicating space on each slide for a menu only used by instructors. However, I really think we need a tool to let slide editors know about the available space, so I would like to re-introduce the red box. This time via a keyboard shortcut to make it easy to toggle as needed. I’m suggesting enabling this for everyone, with the expectation that most people won’t find the shortcut and will quickly disable the box if they do (there is a dedicated button to hide it again). End-to-end tests have been added for the new functionality.
diff --git a/.github/workflows/build.sh b/.github/workflows/build.sh
@@ -43,9 +43,6 @@ export MDBOOK_OUTPUT__PANDOC__DISABLED=false
 
 mdbook build -d "$dest_dir"
 
-# Disable the redbox button in built versions of the course
-echo '// Disabled in published builds, see build.sh' > "${dest_dir}/html/theme/redbox.js"
-
 mv "$dest_dir/pandoc/pdf/comprehensive-rust.pdf" "$dest_dir/html/"
 (cd "$dest_dir/exerciser" && zip --recurse-paths ../html/comprehensive-rust-exercises.zip comprehensive-rust-exercises/)
 
diff --git a/GEMINI.md b/GEMINI.md
@@ -171,3 +171,86 @@ its tasks correctly.
   snippet, treat it as a self-contained program. Do not assume it shares a scope
   or context with other snippets in the same file unless the surrounding text
   explicitly states otherwise.
+
+## Interacting with the `mdbook` Theme
+
+The `mdbook` theme has several interactive elements. Here's how to interact with
+them:
+
+- **Sidebar Toggle:** The sidebar can be opened and closed by clicking the
+  "hamburger" button in the top-left of the body text. This button has the ID
+  `sidebar-toggle`. You can use the following JavaScript to toggle the sidebar:
+
+  ```javascript
+  const button = document.getElementById("sidebar-toggle");
+  button.click();
+  ```
+
+## WebdriverIO Testing
+
+This project uses WebdriverIO for browser-based integration tests. Here are some
+key findings about the test environment:
+
+### Test Environments
+
+The `tests/` directory contains two primary configurations:
+
+- `npm test` (runs `wdio.conf.ts`): This is the standard for self-contained
+  integration tests. It uses `@wdio/static-server-service` to create a temporary
+  web server on port 8080.
+- `npm run test-mdbook` (runs `wdio.conf-mdbook.ts`): This is for testing
+  against a live `mdbook serve` instance, which typically runs on port 3000.
+
+It is important to use the standard `npm test` command for most test development
+to ensure the tests are self-contained.
+
+### Writing Stable Tests
+
+Tests can be flaky if they don't correctly handle the asynchronous nature of the
+web browser and the test environment's state management.
+
+- **State Leakage Between Tests:** Despite what the WebdriverIO documentation
+  might suggest, `browser.url()` is not always sufficient to guarantee a clean
+  slate between tests. Lingering state, such as inline CSS styles applied by
+  JavaScript, can leak from one test into the next, causing unexpected failures.
+  The most effective solution found for this project is to add
+  `await browser.refresh();` to the `beforeEach` hook. This forces a full page
+  reload that properly clears the old state.
+
+- **Race Conditions with Dynamic Elements:** Many elements in this project are
+  created dynamically by JavaScript after the initial page load. If a test tries
+  to access an element immediately after navigation, it may fail because the
+  script hasn't finished running and the element doesn't exist in the DOM yet.
+  This creates a race condition. To prevent this, always use
+  `await element.waitForExist()` to ensure the element is present before trying
+  to interact with it or assert its state (e.g., `toBeDisplayed()`).
+
+### Handling Redirects
+
+`mdbook` uses a redirect map defined in `book.toml` under the
+`[output.html.redirect]` section. When writing tests, it is crucial to use the
+final, non-redirecting URL for navigation. Navigating to a URL that is a
+redirect will cause the browser to follow it, but this process can strip URL
+query parameters, leading to test failures for features that depend on them.
+
+### Running and Debugging Tests
+
+To run a single test file, use the `--spec` flag with the a string matching the
+file name:
+
+```bash
+npm test -- --spec redbox
+```
+
+To check for flakiness, you can repeat a test multiple times using the
+`--repeat` flag:
+
+```bash
+npm test -- --spec redbox --repeat 100
+```
+
+Use `--mochaOpts.grep` to run a single test within a file:
+
+```bash
+npm test -- --spec redbox --mochaOpts.grep "should be hidden by default"
+```
diff --git a/book.toml b/book.toml
@@ -60,6 +60,7 @@ urlcolor = "red"
 smart-punctuation = true
 additional-js = [
   "theme/speaker-notes.js",
+  "theme/redbox.js",
 ]
 additional-css = [
   "theme/css/svgbob.css",
diff --git a/src/running-the-course.md b/src/running-the-course.md
@@ -55,6 +55,7 @@ better. Your students are also very welcome to [send us feedback][2]!
 [1]: https://github.com/google/comprehensive-rust/discussions/86
 [2]: https://github.com/google/comprehensive-rust/discussions/100
 [3]: https://github.com/google/comprehensive-rust#building
+[red-box]: ?show-red-box=true
 
 <details>
 
@@ -69,6 +70,11 @@ better. Your students are also very welcome to [send us feedback][2]!
 - **Familiarize yourself with `mdbook`:** The course is presented using
   `mdbook`. Knowing how to navigate, search, and use its features will make the
   presentation smoother.
+- **Slice size helper:** Press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>B</kbd>
+  to toggle a visual guide showing the amount of space available when
+  presenting. Expect any content outside of the red box to be hidden initially.
+  Use this as a guide when editing slides. You can also
+  [enable it via this link][red-box].
 
 ### Creating a Good Learning Environment
 
diff --git a/tests/src/redbox.test.ts b/tests/src/redbox.test.ts
@@ -0,0 +1,98 @@
+import { describe, it } from "mocha";
+import { expect, browser } from "@wdio/globals";
+
+describe("Red Box", () => {
+  const redBox = () => $("#aspect-ratio-helper");
+  const redBoxButton = () => $("#turn-off-red-box");
+
+  beforeEach(async () => {
+    await browser.url("/hello-world.html");
+    await browser.execute(() => sessionStorage.clear());
+    // Clear any lingering state (like inline styles) from previous
+    // tests. Reading https://webdriver.io/docs/api/browser/url,
+    // this should not be necessary, but tests fail without it.
+    await browser.refresh();
+  });
+
+  it("should be hidden by default", async () => {
+    await expect(redBox()).not.toBeDisplayed();
+  });
+
+  describe("Keyboard Shortcut", () => {
+    it("should show the red box when toggled on", async () => {
+      await browser.toggleRedBox();
+      await expect(redBox()).toBeDisplayed();
+      await expect(redBoxButton()).toBeDisplayed();
+    });
+
+    it("should hide the red box when toggled off", async () => {
+      // Toggle on first
+      await browser.toggleRedBox();
+      await expect(redBox()).toBeDisplayed();
+
+      // Then toggle off
+      await browser.toggleRedBox();
+      await expect(redBox()).not.toBeDisplayed();
+    });
+  });
+
+  describe("URL Parameter", () => {
+    it("should show red box", async () => {
+      await browser.url("/hello-world.html?show-red-box=true");
+      await expect(redBox()).toBeDisplayed();
+    });
+
+    it("should override session storage", async () => {
+      // Set session storage first to ensure the URL parameter takes precedence.
+      await browser.execute(() => sessionStorage.setItem("showRedBox", "true"));
+      await browser.url("/hello-world.html?show-red-box=false");
+      await expect(redBox()).not.toBeDisplayed();
+    });
+  });
+
+  describe("Hide Button", () => {
+    it("should hide the red box when clicked", async () => {
+      await browser.toggleRedBox();
+      await expect(redBox()).toBeDisplayed();
+
+      await (await redBoxButton()).click();
+      await expect(redBox()).not.toBeDisplayed();
+    });
+  });
+
+  describe("Session Storage", () => {
+    it("should persist being shown after a reload", async () => {
+      await browser.toggleRedBox();
+      await expect(redBox()).toBeDisplayed();
+
+      await browser.refresh();
+
+      await expect(redBox()).toBeDisplayed();
+    });
+
+    it("should persist being hidden after a reload", async () => {
+      await browser.toggleRedBox(); // turn on
+      await browser.toggleRedBox(); // turn off
+      await expect(redBox()).not.toBeDisplayed();
+
+      // Explicitly check that storage is cleared before reloading
+      const storage = await browser.execute(() =>
+        sessionStorage.getItem("showRedBox"),
+      );
+      expect(storage).toBeNull();
+
+      await browser.refresh();
+      await expect(redBox()).not.toBeDisplayed();
+    });
+  });
+
+  describe("Interactions", () => {
+    it("should be able to be hidden with the keyboard after being shown with the URL", async () => {
+      await browser.url("/hello-world.html?show-red-box=true");
+      await expect(redBox()).toBeDisplayed();
+
+      await browser.toggleRedBox();
+      await expect(redBox()).not.toBeDisplayed();
+    });
+  });
+});
diff --git a/tests/src/speaker-notes.test.ts b/tests/src/speaker-notes.test.ts
@@ -3,7 +3,17 @@ import { $, expect, browser } from "@wdio/globals";
 
 describe("speaker-notes", () => {
   beforeEach(async () => {
-    await browser.url("/");
+    await browser.url("/welcome-day-1.html");
+    await browser.refresh();
+  });
+
+  afterEach(async () => {
+    const handles = await browser.getWindowHandles();
+    if (handles.length > 1) {
+      await browser.switchToWindow(handles[1]);
+      await browser.closeWindow();
+      await browser.switchToWindow(handles[0]);
+    }
   });
 
   it("contains summary with heading and button", async () => {
@@ -17,7 +27,7 @@ describe("speaker-notes", () => {
     const details$ = await $("details");
     const button$ = await $("details summary .pop-out");
     await expect(details$).toBeDisplayed();
-    button$.scrollIntoView();
+    await button$.scrollIntoView();
     await button$.click();
     await expect(details$).not.toBeDisplayed();
 
@@ -28,4 +38,16 @@ describe("speaker-notes", () => {
       expect.stringContaining("#speaker-notes-open"),
     );
   });
+
+  it("should not show the red box in the speaker notes window", async () => {
+    const button$ = await $("details summary .pop-out");
+    await button$.scrollIntoView();
+    await button$.click();
+
+    const handles = await browser.getWindowHandles();
+    await browser.switchToWindow(handles[1]);
+
+    const redBox = await $("#aspect-ratio-helper");
+    await expect(redBox).not.toExist();
+  });
 });
diff --git a/tests/wdio.conf.ts b/tests/wdio.conf.ts
@@ -213,8 +213,37 @@ export const config: WebdriverIO.Config = {
    * @param {Array.<String>} specs        List of spec file paths that are to be run
    * @param {object}         browser      instance of created browser/device session
    */
-  before: function (capabilities, specs) {
-    browser.setWindowSize(2560, 1440);
+  before: async function (capabilities, specs) {
+    await browser.setWindowSize(2560, 1440);
+
+    /**
+     * Adds a custom `browser.toggleRedBox()` command.
+     *
+     * This command is necessary to reliably test the red box toggle
+     * functionality. A direct `browser.keys()` call proved to be
+     * flaky, causing intermittent test failures. This custom command
+     * will wait for the UI to reflect the state change, thus
+     * eliminating race conditions.
+     */
+    browser.addCommand("toggleRedBox", async function () {
+      const redBox = await $("#aspect-ratio-helper");
+      const initialVisibility = await redBox.isDisplayed();
+
+      // Perform the toggle action.
+      await browser.keys(["Control", "Alt", "b"]);
+
+      // Wait until the visibility state has changed.
+      await browser.waitUntil(
+        async function () {
+          const currentVisibility = await redBox.isDisplayed();
+          return currentVisibility !== initialVisibility;
+        },
+        {
+          timeout: 5000,
+          timeoutMsg: `Red box display state did not toggle after 5s. Initial state: ${initialVisibility}`,
+        },
+      );
+    });
   },
   /**
    * Runs before a WebdriverIO command gets executed.
diff --git a/theme/css/redbox.css b/theme/css/redbox.css
@@ -8,7 +8,8 @@ div#aspect-ratio-helper {
 }
 
 div#aspect-ratio-helper div {
-  outline: 3px dashed red;
+  position: relative;
+  outline: 2em solid rgba(255, 0, 0, 0.2);
   margin: 0 auto;
   /* At this width, the theme fonts are readable in a 16
        person conference room. If the browser is wider, the
@@ -19,6 +20,16 @@ div#aspect-ratio-helper div {
   aspect-ratio: 16/8.5;
 }
 
-#instructor-menu-list {
-  margin-left: 55px;
+#turn-off-red-box {
+  position: absolute;
+  bottom: 10px;
+  right: 10px;
+  z-index: 10000;
+  padding: 10px;
+  background-color: #f44336;
+  color: white;
+  border: none;
+  border-radius: 5px;
+  cursor: pointer;
+  pointer-events: auto;
 }
diff --git a/theme/instructor-menu.js b/theme/instructor-menu.js
diff --git a/theme/redbox.js b/theme/redbox.js

Original file line number	Diff line number	Diff line change
`@@ -60,6 +60,7 @@ urlcolor = "red"`
`60`	`60`	`smart-punctuation = true`
`61`	`61`	`additional-js = [`
`62`	`62`	`"theme/speaker-notes.js",`
	`63`	`+ "theme/redbox.js",`
`63`	`64`	`]`
`64`	`65`	`additional-css = [`
`65`	`66`	`"theme/css/svgbob.css",`