fix(web): focus routes before keyboard interaction

Author: Yannam-Builds

README.md

@@ -31,7 +31,7 @@ The August 31 website update includes:
 - Opaque modal sheets with keyboard focus wrapping, Escape dismissal and blocked background taps; mobile safe-area layouts and accessible numeric entry.
 - A six-paper research bibliography with limitations, separate software/font notices, and optional Home Screen installation.
 
-**Preview, not full native parity.** The appearance update passes 94 unit tests, all 47 browser tests, the production build and scoped scan of 95 output files on Windows. Browser coverage includes desktop Chromium/WebKit and Pixel 7 Chrome emulation, all 21 actual font files, 320px/200%-text layouts, both spacing extremes, preference failures, shared appearance and completed workouts after switching fonts. Both supplemental origin-stopped workout checks also pass. These results do not verify physical Android/iPhone devices, installed Home Screen lifecycle or VoiceOver. See the [acceptance record](web/docs/acceptance.md), [native parity gaps](web/docs/domain-parity.md) and [offline investigation](web/diagnostics/OFFLINE-WEBKIT.md).
+**Preview, not full native parity.** The appearance update passes 94 unit tests, all 49 browser tests, the production build and scoped scan of 95 output files on Windows. Browser coverage includes desktop Chromium/WebKit and Pixel 7 Chrome emulation, all 21 actual font files, 320px/200%-text layouts, both spacing extremes, preference failures, shared appearance and completed workouts after switching fonts. Both supplemental origin-stopped workout checks also pass. These results do not verify physical Android/iPhone devices, installed Home Screen lifecycle or VoiceOver. See the [acceptance record](web/docs/acceptance.md), [native parity gaps](web/docs/domain-parity.md) and [offline investigation](web/diagnostics/OFFLINE-WEBKIT.md).
 
 **Live deployment verified, 31 August 2026:** [workflow run for `974ed50`](https://github.com/Yannam-Builds/Ironlog/actions/runs/33373046339) passed 85 unit tests, 29 browser tests, both supplemental offline tests, build/output checks and deployment. Pages now uses **GitHub Actions** and serves only the built `web/dist`, not the legacy README renderer. All nine phone-preview tests also passed against the public website, including embedded workout completion in Chromium, WebKit and Android Chrome emulation. The app-independent WebKit offline-emulation failure remains a diagnostic; the application gate closes its actual HTTP origin and verifies cached startup and workout persistence without it.
 

docs/superpowers/plans/2026-08-31-shared-typography.md

@@ -36,17 +36,17 @@ Files: create `web/src/ui/typography.ts`, `web/src/ui/FontPicker.tsx`, `web/src/
 
 Files: `ui/theme/IronLogTypography.kt`, new typography registry/runtime/preferences and picker files, `ui/IronLogApp.kt`, `ui/screens/settings/SettingsScreen.kt`, affected centralized text wrappers and tests under `app/src/test`/`app/src/androidTest`.
 
-- [ ] Write failing JVM tests for registry/preset normalization, range clamping and invalid stored preference recovery.
-- [ ] Implement persistent selection in existing settings or isolated SharedPreferences, never requiring ObjectBox schema changes; load before screen rendering and update the root immediately after a successful save.
-- [ ] Map all Material text styles to the chosen family and preset, including explicit screen weights through a centralized wrapper if needed. Audit custom Canvas/Paint text separately; never replace icon glyphs.
-- [ ] Add a scrollable opaque picker with family names, preview, selected state and weight preset. Preserve all pre-existing dirty edits.
-- [ ] Run focused tests, complete JVM tests/lint/build and emulator checks where available. No phone install/uninstall/clear and no release publication in this task.
+- [x] Write failing JVM tests for registry/preset normalization, range clamping and invalid stored preference recovery.
+- [x] Implement persistent selection in existing settings or isolated SharedPreferences, never requiring ObjectBox schema changes; load before screen rendering and update the root immediately after a successful save.
+- [x] Map all Material text styles to the chosen family and preset, including explicit screen weights through a centralized wrapper if needed. Audit custom Canvas/Paint text separately; never replace icon glyphs.
+- [x] Add a scrollable opaque picker with family names, preview, selected state and weight preset. Preserve all pre-existing dirty edits.
+- [x] Run focused tests, complete JVM tests/lint/build and emulator checks where available. No phone install/uninstall/clear and no release publication in this task.
 
 ## 4. Verification, review and publication
 
 - [ ] Browser tests: all 21 families load, persisted preference across landing/iframe/full-screen, invalid storage, all presets, 320px/large text, menus/inputs and complete workout after switching; offline reload retains the choice.
 - [ ] Run `npm test`, `npm run build`, `npm run verify:output`, complete Playwright suite and separate origin-stopped tests. Check screenshots and font payload totals.
-- [ ] Independent spec review followed by code-quality review; resolve findings and rerun affected gates.
+- [x] Independent spec review followed by code-quality review; resolve findings and rerun affected gates.
 - [ ] Update README and font acknowledgments. Publish only website-scoped changes via existing verified GitHub Pages workflow; native changes stay separate from unrelated Android work.
 - [ ] Verify the live website. Report native build/emulator evidence separately from physical-device testing and distinguish bundled font choices from platform-controlled text.
 

web/README.md

@@ -81,7 +81,7 @@ The PWA uses prompt updates. Pending writes and active workouts disable update c
 
 **Preview publication requested by the owner on 31 August 2026.** Repository publication is separate from full product acceptance. The workflow must pass before Pages deployment; never skip a failed test to publish. Real iPhone testing and the documented parity/acceptance gaps remain open. Do not include unrelated Android edits, APKs, keystores or user backups.
 
-On Windows, the appearance update passed 94 unit tests and all 47 main browser tests (2 workers, 2 minutes); CI retains its single-worker configuration. All 21 fonts and presets are checked on the landing/embedded app at 320px and 200% text in Chromium/WebKit/Pixel 7 Chrome emulation. Settings changes, completed workouts, failed font/preference loads, both spacing extremes, unchanged text/icon dimensions and control minimums are covered. Both supplemental origin-unavailable workout tests pass (2/2, 21 seconds). The main offline test closes its actual HTTP server; the standalone WebKit offline-emulation failure remains documented and reproducible. See [the diagnostic evidence and limitations](diagnostics/OFFLINE-WEBKIT.md); this is not physical-device or installed-PWA verification.
+On Windows, the appearance update passed 94 unit tests and all 49 main browser tests (2 workers, 2.1 minutes); CI retains its single-worker configuration. All 21 fonts and presets are checked on the landing/embedded app at 320px and 200% text in Chromium/WebKit/Pixel 7 Chrome emulation. Settings changes, completed workouts, failed font/preference loads, both spacing extremes, unchanged text/icon dimensions and control minimums are covered. Both supplemental origin-unavailable workout tests pass (2/2, 23.1 seconds). The main offline test closes its actual HTTP server; the standalone WebKit offline-emulation failure remains documented and reproducible. See [the diagnostic evidence and limitations](diagnostics/OFFLINE-WEBKIT.md); this is not physical-device or installed-PWA verification.
 
 OpenGym exercise pictures/GIFs are not included. Its [media notice](https://gitlab.com/DuarteSantos8/opengym/-/blob/main/NOTICE.md) and the [upstream dataset terms](https://github.com/hasaneyldrm/exercises-dataset#license--usage) require separate media permission; software licenses do not grant those image rights.
 

web/docs/acceptance.md

@@ -18,10 +18,11 @@ Status: implementation and hardening in progress; **not fully accepted**. The ow
 ### Appearance update — 31 August 2026
 
 - 94 JVM-independent web unit tests pass; production build and scoped scan of 95 output files pass. Original font bytes total 5.84 MiB; revisioned offline precache is approximately 7.75 MiB.
-- All 47 browser tests pass on Windows with two workers. CI remains single-worker. New coverage loads every actual font family, all explicit weight presets, semantic heading weights, malformed preferences, storage denial, font-load failure, landing/iframe/full-screen synchronization, a complete workout after changing fonts, and offline selection of a previously unused font with the HTTP origin stopped.
+- All 49 browser tests pass on Windows with two workers. CI remains single-worker. New coverage loads every actual font family, all explicit weight presets, semantic heading weights, malformed preferences, storage denial, font-load failure, landing/iframe/full-screen synchronization, a complete workout after changing fonts, and offline selection of a previously unused font with the HTTP origin stopped.
 - Global spacing is tested at 85% and 125%, with reset/reload, 320px and 200% text, preserved text/icon sizes and representative 48px-or-larger controls. WebKit testing exposed and fixed long header/tab/link overflow and native-select overflow; navigation labels now wrap and bottom clearance accommodates enlarged text.
-- Both supplemental origin-stopped workout tests pass (2/2, 21 seconds). Typography and spacing received independent spec/code reviews; heading-role findings were fixed. Native code is developed in a separate dirty workspace and is not part of this website deployment.
+- Both supplemental origin-stopped workout tests pass (2/2, 23.1 seconds). Typography and spacing received independent spec/code reviews; heading-role findings were fixed. Native code is developed in a separate dirty workspace and is not part of this website deployment.
 - These are automated/emulated checks, not physical Safari, Home Screen or VoiceOver acceptance. Existing broader parity gaps below remain open.
+- The first appearance CI run exposed a route-focus race in the existing keyboard-overlay test. A delayed animation frame could steal focus between Enter events. Route focus now runs after the React route commit, before paint; a controlled delayed-frame regression failed before the fix and passes afterward. The complete local suite passes without weakening the original keyboard assertions.
 
 The final run results should accompany this document. Current covered cases include:
 

web/src/App.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState, lazy, Suspense } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, lazy, Suspense } from "react";
 import { readSnapshot, subscribeSnapshot, reconcileBadges } from "./data/store";
 import type { AppSnapshot } from "./domain/types";
 import { deriveSnapshot } from "./domain/engine";
@@ -37,6 +37,12 @@ export function App() {
   const [now, setNow] = useState(Date.now());
   const [online, setOnline] = useState(navigator.onLine);
   const main = useRef<HTMLElement>(null);
+  useLayoutEffect(() => {
+    // Focus the committed route before it can be interacted with. A deferred
+    // animation frame can otherwise steal focus between Enter's key events.
+    window.scrollTo(0, 0);
+    main.current?.focus({ preventScroll: true });
+  }, [route]);
   useEffect(() => {
     applyTheme(currentTheme());
     return subscribeSnapshot(setData, (e) =>
@@ -48,8 +54,6 @@ export function App() {
   useEffect(() => {
     const hash = () => {
       setRoute(location.hash.replace(/^#\//, "") || "home");
-      window.scrollTo(0, 0);
-      requestAnimationFrame(() => main.current?.focus());
     };
     const visible = () => {
       if (document.visibilityState === "visible") {

web/tests/browser/overlays.spec.ts

@@ -17,6 +17,30 @@ async function onboard(page: Page) {
   await expect(page.getByRole("heading", { name: "Overlay QA" })).toBeVisible();
 }
 
+test("route focus does not steal a newly focused control on a delayed frame", async ({ page }) => {
+  await onboard(page);
+  await page.evaluate(() => {
+    const callbacks: FrameRequestCallback[] = [];
+    const original = window.requestAnimationFrame;
+    window.requestAnimationFrame = (callback) => callbacks.push(callback);
+    Object.assign(window, {
+      flushRouteFrames: () => {
+        window.requestAnimationFrame = original;
+        callbacks.splice(0).forEach((callback) => callback(performance.now()));
+      },
+    });
+    location.hash = "#/plans";
+  });
+  const opener = page.getByRole("button", { name: "Import JSON", exact: true });
+  await opener.focus();
+  await page.evaluate(() => {
+    (window as unknown as { flushRouteFrames: () => void }).flushRouteFrames();
+  });
+  await expect(opener).toBeFocused();
+  await page.keyboard.press("Enter");
+  await expect(page.getByRole("dialog", { name: "Import a plan" })).toBeVisible();
+});
+
 test("all themes keep sheets opaque, modal and keyboard dismissible", async ({
   page,
 }, info) => {