Explorer: modal focus management and non-duplicated drag redraw

The two follow-ups worth taking from the review of the previous change.
Both were listed in that commit as deliberately deferred.

Modal focus management (WCAG 2.4.3, 4.1.2)
  The overlays had no dialog semantics and no focus handling: opening one
  left focus behind on the page, closing it dropped the user at the top
  of the document, and Tab walked straight out into the page behind the
  dialog. Added role="dialog" + aria-modal + an accessible name, focus
  into the dialog on open, restore to the trigger on close, and a Tab
  trap in both directions.

  aria-modal hides the background from assistive tech but does nothing
  about the tab order, which is why the trap is also needed.

  One non-obvious interaction: the previous change hid the closed
  overlays with `transition: opacity, visibility 0.25s`. Transitioning
  visibility symmetrically keeps the overlay non-visible for the whole
  250 ms after opening, and a visibility:hidden element cannot take
  focus -- the focus() call was silently rejected, with focus() invoked
  but no focusin event. Visibility now flips immediately on open and is
  delayed only on close, so the fade-out still reads correctly.

Drag redraw no longer runs twice per frame
  onSliderChange both schedules a coalesced redraw and keeps the
  animation loop alive, and the loop already redraws both canvases every
  frame -- so update() from the coalesced callback drew them again.
  Measured over a sustained drag: 1.68 canvas redraws per animation
  frame, i.e. ~40% wasted work on the one interaction path that the
  worker, mean-only and crossfade work never touched.

  The loop owns the canvases while it is running; the coalesced callback
  still performs the non-canvas work, since dropping it would freeze the
  readouts and the screen-reader summary mid-drag.

  1.68 -> 1.08 redraws per frame, and 47 -> 65 frames completed in the
  same 2 s window.

Not taken, with reasons, so this does not get re-litigated:
- #scatter-canvas still has no text equivalent. It is the primary
  surface, but a 149-row table helps nobody; exposing it well means
  deciding what to surface (Pareto frontier summary? keyboard navigation
  between points?) and is a design task, not a small fix.
- _reduceMotion is still sampled once at module load. Live-updating it
  is ~5 lines, but the only way to hit the gap is flipping the OS
  setting mid-session.

Verification: lint 0, test-js 13/13, e2e 105 on macOS and 109 on Linux
in the matching Playwright image, both Lighthouse profiles green with
zero failing accessibility audits. The new modal-focus and drag-redraw
tests were each confirmed to fail against the defect they pin.

Author: SebastianAment

docs/index.html

@@ -126,9 +126,9 @@ <h1>BOxCrete</h1>
 
   <!-- About Modal Overlay -->
   <div class="about-overlay" id="about-overlay">
-    <div class="about-modal">
+    <div class="about-modal" role="dialog" aria-modal="true" aria-labelledby="about-modal-title">
       <button class="about-close" aria-label="Close" data-modal-close>&times;</button>
-      <h2>About This Explorer</h2>
+      <h2 id="about-modal-title">About This Explorer</h2>
       <p>This tool predicts concrete compressive strength using a Gaussian Process model trained on laboratory mortar and concrete specimens. Predictions reflect controlled lab conditions and <strong>may differ from field performance</strong> due to batching variability, curing environment, and aggregate properties.</p>
       <h3>How to Use</h3>
       <ul>
@@ -147,7 +147,7 @@ <h3>Papers</h3>
 
   <!-- Video Modal Overlay -->
   <div class="video-overlay" id="video-overlay">
-    <div class="video-modal">
+    <div class="video-modal" role="dialog" aria-modal="true" aria-label="BOxCrete video">
       <button class="video-close" aria-label="Close" data-modal-close>&times;</button>
       <div class="video-frame-wrap">
         <iframe id="video-iframe"
@@ -454,23 +454,66 @@ <h3>References</h3>
     // Generic modal: handles close button ([data-modal-close]), backdrop click,
     // and Escape key. Optional onOpen/onClose hooks let callers run side effects
     // (e.g. lazy-loading the video iframe).
+    // Focusable descendants, in DOM order. Recomputed per use because the
+    // video modal's iframe is populated lazily on open.
+    const FOCUSABLE =
+      'a[href], button:not([disabled]), iframe, input:not([disabled]), ' +
+      'select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    function focusablesIn(root) {
+      return Array.from(root.querySelectorAll(FOCUSABLE))
+        .filter((el) => el.offsetWidth > 0 || el.offsetHeight > 0 || el === document.activeElement);
+    }
+
     function setupModal(overlay, { onOpen, onClose } = {}) {
+      const dialog = overlay.querySelector('[role="dialog"]') || overlay;
+      // Element to hand focus back to on close. Without this, dismissing a
+      // dialog drops the keyboard user back at the top of the document.
+      let lastFocused = null;
+
       const close = () => {
         overlay.classList.remove('visible');
         onClose?.();
+        if (lastFocused && document.contains(lastFocused)) lastFocused.focus();
+        lastFocused = null;
       };
       const open = () => {
+        lastFocused = document.activeElement;
         onOpen?.();
         overlay.classList.add('visible');
+        // Focus must land inside the dialog, or the user is told a dialog
+        // opened while their focus is still behind it. The close button is the
+        // conventional target and is always present.
+        //
+        // Works synchronously because .visible flips visibility with no
+        // transition delay; a visibility:hidden element cannot take focus.
+        const first = dialog.querySelector('[data-modal-close]') || focusablesIn(dialog)[0];
+        first?.focus();
       };
+
       for (const btn of overlay.querySelectorAll('[data-modal-close]')) {
         btn.addEventListener('click', close);
       }
       overlay.addEventListener('click', (e) => {
         if (e.target === overlay) close();
       });
       document.addEventListener('keydown', (e) => {
-        if (e.key === 'Escape' && overlay.classList.contains('visible')) close();
+        if (!overlay.classList.contains('visible')) return;
+        if (e.key === 'Escape') { close(); return; }
+        if (e.key !== 'Tab') return;
+        // Trap: aria-modal hides the background from assistive tech, but it
+        // does not stop Tab walking out into the page behind the dialog.
+        const items = focusablesIn(dialog);
+        if (items.length === 0) return;
+        const first = items[0];
+        const last = items[items.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey && (active === first || !dialog.contains(active))) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && (active === last || !dialog.contains(active))) {
+          e.preventDefault();
+          first.focus();
+        }
       });
       return { open, close };
     }

docs/style.css

@@ -246,12 +246,19 @@ body {
      the app's own in the heading outline. `visibility` still animates, so the
      fade is preserved. */
   visibility: hidden;
-  transition: opacity 0.25s ease, visibility 0.25s ease;
+  /* Delay the flip to hidden until the fade-out finishes, but flip to visible
+     IMMEDIATELY on open (see .visible). Transitioning visibility symmetrically
+     keeps the overlay non-visible for the whole 250 ms, and a
+     visibility:hidden element cannot take focus -- the focus() call on open is
+     silently rejected. */
+  transition: opacity 0.25s ease, visibility 0s linear 0.25s;
 }
 .about-overlay.visible {
   opacity: 1;
   pointer-events: all;
   visibility: visible;
+  /* No delay in this direction: focusable as soon as the class lands. */
+  transition: opacity 0.25s ease, visibility 0s linear 0s;
 }
 .about-modal {
   background: var(--glass-bg);
@@ -346,12 +353,19 @@ body {
      the app's own in the heading outline. `visibility` still animates, so the
      fade is preserved. */
   visibility: hidden;
-  transition: opacity 0.25s ease, visibility 0.25s ease;
+  /* Delay the flip to hidden until the fade-out finishes, but flip to visible
+     IMMEDIATELY on open (see .visible). Transitioning visibility symmetrically
+     keeps the overlay non-visible for the whole 250 ms, and a
+     visibility:hidden element cannot take focus -- the focus() call on open is
+     silently rejected. */
+  transition: opacity 0.25s ease, visibility 0s linear 0.25s;
 }
 .video-overlay.visible {
   opacity: 1;
   pointer-events: all;
   visibility: visible;
+  /* No delay in this direction: focusable as soon as the class lands. */
+  transition: opacity 0.25s ease, visibility 0s linear 0s;
 }
 .video-modal {
   background: var(--glass-bg);

docs/ui.mjs

@@ -667,7 +667,21 @@ function requestRedraw() {
   if (_pendingRedraw !== null) return;
   _pendingRedraw = requestAnimationFrame(() => {
     _pendingRedraw = null;
-    update();
+    // When the animation loop is running it already redraws both canvases
+    // every frame, so calling update() here draws them a second time.
+    // Measured during a sustained drag: 1.68 canvas redraws per animation
+    // frame, i.e. ~40% of the work on the one hot path that none of the
+    // earlier optimisations touched.
+    //
+    // The loop only owns the CANVASES, so the rest of update() still has to
+    // run -- dropping it would freeze the readouts and the screen-reader
+    // summary mid-drag.
+    if (animLoopId !== null) {
+      updateReadouts();
+      scheduleCurveSummary();
+    } else {
+      update();
+    }
     updateMixInsight();
     checkExtrapolationWarning();
   });

test/e2e/drag-redraw.spec.ts

@@ -0,0 +1,77 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * Drag redraw efficiency.
+ *
+ * `onSliderChange` schedules a coalesced redraw AND keeps the animation loop
+ * alive. The loop already redraws both canvases every frame, so update() from
+ * the coalesced callback drew them a second time — measured at 1.68 canvas
+ * redraws per animation frame during a sustained drag, i.e. ~40% wasted work
+ * on the one interaction path that the earlier transition/worker optimisations
+ * never touched.
+ *
+ * The loop owns the canvases while it runs; the coalesced callback still has
+ * to do the non-canvas work, so this also pins that the readouts keep updating.
+ */
+test("drag does not redraw the canvases twice per frame", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name !== "desktop", "one project is enough");
+
+  await page.goto("/?test=1");
+  await page.waitForFunction(() => (window as any).__test?.modelReady === true, null, {
+    timeout: 30000,
+  });
+  await page.waitForTimeout(800);
+
+  const r = await page.evaluate(async () => {
+    // setupHiDPICanvas assigns canvas.width on every draw, so counting
+    // assignments counts redraws directly.
+    const counts: Record<string, number> = { curve: 0, scatter: 0 };
+    for (const [key, id] of [
+      ["curve", "curve-canvas"],
+      ["scatter", "scatter-canvas"],
+    ] as const) {
+      const c = document.getElementById(id) as HTMLCanvasElement;
+      let real = c.width;
+      Object.defineProperty(c, "width", {
+        get: () => real,
+        set: (v) => { counts[key]++; real = v; },
+        configurable: true,
+      });
+    }
+
+    let frames = 0;
+    let running = true;
+    const tick = () => { if (running) { frames++; requestAnimationFrame(tick); } };
+    requestAnimationFrame(tick);
+
+    // Drive input faster than 60 Hz, as a touch drag or high-polling mouse does.
+    const s = document.querySelector("#sliders input[type=range]") as HTMLInputElement;
+    const min = parseFloat(s.min);
+    const max = parseFloat(s.max);
+    const t0 = performance.now();
+    let events = 0;
+    while (performance.now() - t0 < 1500) {
+      s.value = String(min + (max - min) * ((events % 20) / 20));
+      s.dispatchEvent(new Event("input", { bubbles: true }));
+      events++;
+      await new Promise((res) => setTimeout(res, 8));
+    }
+    running = false;
+    await new Promise((res) => setTimeout(res, 300));
+
+    return { ...counts, frames, readout: document.getElementById("gwp-value")?.textContent };
+  });
+
+  expect(r.frames, "no animation frames observed").toBeGreaterThan(10);
+
+  const perFrame = r.curve / r.frames;
+  expect(
+    perFrame,
+    `${r.curve} curve redraws over ${r.frames} frames = ${perFrame.toFixed(2)}/frame ` +
+      "(was 1.68 when the loop and the coalesced callback both drew)",
+  ).toBeLessThan(1.35);
+
+  // The coalesced callback must still do the non-canvas work.
+  expect(r.readout, "readouts stopped updating during the drag").toBeTruthy();
+  expect(r.readout).not.toBe("–");
+});

test/e2e/modal-focus.spec.ts

@@ -0,0 +1,68 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * Modal focus management (WCAG 2.4.3 Focus Order, 4.1.2 Name/Role/Value).
+ *
+ * The overlays previously had no dialog semantics and no focus handling at
+ * all: opening one left focus behind on the page, closing it dropped the user
+ * at the top of the document, and Tab walked straight out into the page
+ * behind the dialog.
+ */
+test.describe("modal focus management", () => {
+  test.beforeEach(async ({ page }, testInfo) => {
+    test.skip(testInfo.project.name !== "desktop", "About link is desktop-visible");
+    await page.goto("/");
+    await page.locator("#sliders input[type=range]").first().waitFor({ timeout: 15000 });
+  });
+
+  test("the dialog is announced as a dialog and is labelled", async ({ page }) => {
+    const dialog = page.locator("#about-overlay [role=dialog]");
+    await expect(dialog).toHaveAttribute("aria-modal", "true");
+    const labelledby = await dialog.getAttribute("aria-labelledby");
+    expect(labelledby, "dialog needs an accessible name").toBeTruthy();
+    await expect(page.locator(`#${labelledby}`)).toHaveText(/About/i);
+  });
+
+  test("opening moves focus into the dialog", async ({ page }) => {
+    await page.locator("#about-link").click();
+    await expect(page.locator("#about-overlay")).toHaveClass(/visible/);
+    const inside = await page.evaluate(() => {
+      const d = document.querySelector("#about-overlay [role=dialog]")!;
+      return d.contains(document.activeElement);
+    });
+    expect(inside, "focus should land inside the dialog, not stay behind it").toBe(true);
+  });
+
+  test("closing restores focus to the trigger", async ({ page }) => {
+    await page.locator("#about-link").click();
+    await expect(page.locator("#about-overlay")).toHaveClass(/visible/);
+    await page.keyboard.press("Escape");
+    await expect(page.locator("#about-overlay")).not.toHaveClass(/visible/);
+    const id = await page.evaluate(() => document.activeElement?.id);
+    expect(id, "focus should return to the element that opened the dialog").toBe("about-link");
+  });
+
+  test("Tab is trapped inside the open dialog", async ({ page }) => {
+    await page.locator("#about-link").click();
+    await expect(page.locator("#about-overlay")).toHaveClass(/visible/);
+
+    // Walk well past the number of focusables; focus must never escape.
+    for (let i = 0; i < 12; i++) {
+      await page.keyboard.press("Tab");
+      const inside = await page.evaluate(() => {
+        const d = document.querySelector("#about-overlay [role=dialog]")!;
+        return d.contains(document.activeElement);
+      });
+      expect(inside, `focus escaped the dialog after ${i + 1} Tab presses`).toBe(true);
+    }
+    // And backwards.
+    for (let i = 0; i < 4; i++) {
+      await page.keyboard.press("Shift+Tab");
+      const inside = await page.evaluate(() => {
+        const d = document.querySelector("#about-overlay [role=dialog]")!;
+        return d.contains(document.activeElement);
+      });
+      expect(inside, `focus escaped backwards after ${i + 1} Shift+Tab presses`).toBe(true);
+    }
+  });
+});