Show layout-aware keyboard labels

Display keyboard tutorial labels for the active layout while keeping the existing physical bindings. Fall back to QWERTY/AZERTY labels when layout data is unavailable.

Tested with `npm test` and `npm run build`.

app/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
+    "test": "node --test \"test/**/*.test.js\"",
     "build": "vite build",
     "preview": "vite preview"
   },

app/src/ui/TitleMenu.jsx

@@ -15,6 +15,7 @@ import { useGame } from "../store.js";
 import { signed } from "../game/signed.js";
 import { INK, ORANGE, MONO } from "../theme.js";
 import { ComicButton, ComicTitle, HalftoneRamp, ANTON } from "./comic.jsx";
+import { readLayoutMap, resolveKeycaps } from "./keyboard-layout.js";
 
 const rowIn = keyframes`
   from { transform: translateY(12px); opacity: 0; }
@@ -49,13 +50,14 @@ const Kbd = styled("kbd")(({ round }) => ({
   boxShadow: "0 0 0 2px rgba(255, 255, 255, 0.82)",
 }));
 
+// Letter keycaps are resolved from physical codes for the active layout.
 const TILES = {
   kb: [
-    { caps: "cluster-arrows", name: "Move", hint: "arrows or ZQSD" },
-    { caps: ["A", "E"], name: "Kick", hint: "left / right" },
-    { caps: ["R"], name: "Sit", hint: "tap again to stand" },
-    { caps: ["G"], name: "Pick up", hint: "beak to the ground" },
-    { caps: ["C"], name: "Camera", hint: "toggle chase" },
+    { caps: "cluster-arrows", name: "Move" },
+    { codes: ["KeyQ", "KeyE"], name: "Kick", hint: "left / right" },
+    { codes: ["KeyR"], name: "Sit", hint: "tap again to stand" },
+    { codes: ["KeyG"], name: "Pick up", hint: "beak to the ground" },
+    { codes: ["KeyC"], name: "Camera", hint: "toggle chase" },
     { caps: ["Space"], name: "Reset", hint: "fresh start" },
   ],
   pad: [
@@ -77,6 +79,33 @@ const HINTS = {
   touch: "drag to orbit \u00b7 pinch to zoom",
 };
 
+const KB_CODES = TILES.kb.flatMap((t) => t.codes ?? []);
+
+function useKeycaps(enabled) {
+  const [keycaps, setKeycaps] = useState(() => resolveKeycaps(KB_CODES, null));
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    let latest = 0;
+    const read = async () => {
+      const ticket = ++latest;
+      const map = await readLayoutMap();
+      // Overlapping reads can settle out of order; only the newest paints.
+      if (!cancelled && ticket === latest) setKeycaps(resolveKeycaps(KB_CODES, map));
+    };
+    read();
+    const keyboard = navigator.keyboard;
+    keyboard?.addEventListener?.("layoutchange", read);
+    return () => {
+      cancelled = true;
+      keyboard?.removeEventListener?.("layoutchange", read);
+    };
+  }, [enabled]);
+
+  return keycaps;
+}
+
 function closeMenu() {
   useGame.setState({ menuOpen: false });
   if (!useGame.getState().entered) useGame.setState({ entered: true });
@@ -89,6 +118,9 @@ export default function TitleMenu() {
   const touchMode = useGame((s) => s.touchMode);
   const [closing, setClosing] = useState(false);
   const prevOpen = useRef(menuOpen);
+  // A plugged-in gamepad wins over the touch tutorial.
+  const tutorialVariant = padConnected ? "pad" : touchMode ? "touch" : "kb";
+  const { labels, moveHint } = useKeycaps(tutorialVariant === "kb");
 
   // Keep the overlay mounted through the 0.35 s closing fade.
   useEffect(() => {
@@ -126,9 +158,14 @@ export default function TitleMenu() {
 
   if (!menuOpen && !closing) return null;
 
-  // A plugged-in gamepad wins over the touch tutorial.
-  const tutorialVariant = padConnected ? "pad" : touchMode ? "touch" : "kb";
-  const tiles = TILES[tutorialVariant];
+  const tiles =
+    tutorialVariant === "kb"
+      ? TILES.kb.map((t) => ({
+          ...t,
+          caps: t.codes ? t.codes.map((code) => labels[code]) : t.caps,
+          hint: t.hint ?? moveHint,
+        }))
+      : TILES[tutorialVariant];
   const ctaLabel = entered ? "Resume" : "Waddle in";
 
   return (
@@ -320,8 +357,8 @@ export default function TitleMenu() {
                   </Box>
                 ) : (
                   <Box sx={{ display: "flex", gap: "0.22rem", justifyContent: "center" }}>
-                    {t.caps.map((c) => (
-                      <Kbd key={c} round={t.round ? 1 : 0}>{c}</Kbd>
+                    {t.caps.map((c, i) => (
+                      <Kbd key={i} round={t.round ? 1 : 0}>{c}</Kbd>
                     ))}
                   </Box>
                 )}

app/src/ui/keyboard-layout.js

@@ -0,0 +1,41 @@
+// Controls use physical KeyboardEvent.code positions; getLayoutMap() provides
+// the characters printed on those keys for the active layout.
+const FALLBACK_LABELS = Object.freeze({ KeyW: "W/Z", KeyA: "A/Q", KeyQ: "Q/A" });
+
+const MOVEMENT_CODES = ["KeyW", "KeyA", "KeyS", "KeyD"];
+const MOVEMENT_FALLBACK_HINT = "arrows or WASD / ZQSD";
+
+function keycap(value) {
+  if (typeof value !== "string") return null;
+  const glyph = value.trim();
+  if ([...glyph].length !== 1 || /[\p{M}\p{C}\p{Z}]/u.test(glyph)) return null;
+  const upper = glyph.toUpperCase();
+  return [...upper].length === 1 ? upper : glyph; // "ß" must not become "SS"
+}
+
+export function resolveKeycaps(codes, layoutMap) {
+  const labels = {};
+  const fromLayout = new Set();
+  for (const code of new Set([...MOVEMENT_CODES, ...codes])) {
+    let label = null;
+    try {
+      label = keycap(layoutMap?.get?.(code));
+    } catch {
+      label = null;
+    }
+    if (label) fromLayout.add(code);
+    labels[code] = label ?? FALLBACK_LABELS[code] ?? code.replace(/^Key/, "");
+  }
+  const moveHint = MOVEMENT_CODES.every((code) => fromLayout.has(code))
+    ? `arrows or ${MOVEMENT_CODES.map((code) => labels[code]).join("")}`
+    : MOVEMENT_FALLBACK_HINT;
+  return { labels, moveHint };
+}
+
+export async function readLayoutMap(nav = globalThis.navigator) {
+  try {
+    return (await nav?.keyboard?.getLayoutMap?.()) ?? null;
+  } catch {
+    return null;
+  }
+}

app/test/keyboard-layout.test.js

@@ -0,0 +1,77 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { readLayoutMap, resolveKeycaps } from "../src/ui/keyboard-layout.js";
+
+const AZERTY = new Map(
+  Object.entries({ KeyW: "z", KeyA: "q", KeyS: "s", KeyD: "d", KeyQ: "a", KeyE: "e" }),
+);
+const QWERTY = new Map(
+  Object.entries({ KeyW: "w", KeyA: "a", KeyS: "s", KeyD: "d", KeyQ: "q", KeyE: "e" }),
+);
+const DVORAK = new Map(
+  Object.entries({ KeyW: ",", KeyA: "a", KeyS: "o", KeyD: "e", KeyQ: "'", KeyE: "." }),
+);
+
+const CODES = ["KeyQ", "KeyE"];
+
+test("resolves caps and the movement hint from the active layout", () => {
+  assert.deepEqual(resolveKeycaps(CODES, QWERTY), {
+    labels: { KeyW: "W", KeyA: "A", KeyS: "S", KeyD: "D", KeyQ: "Q", KeyE: "E" },
+    moveHint: "arrows or WASD",
+  });
+  const azerty = resolveKeycaps(CODES, AZERTY);
+  assert.deepEqual(azerty.labels, {
+    KeyW: "Z", KeyA: "Q", KeyS: "S", KeyD: "D", KeyQ: "A", KeyE: "E",
+  });
+  assert.equal(azerty.moveHint, "arrows or ZQSD");
+
+  const dvorak = resolveKeycaps(CODES, DVORAK);
+  assert.equal(dvorak.labels.KeyQ, "'");
+  assert.equal(dvorak.moveHint, "arrows or ,AOE");
+});
+
+test("falls back to labels naming both layouts without a map", () => {
+  assert.deepEqual(resolveKeycaps(CODES, null), {
+    labels: { KeyW: "W/Z", KeyA: "A/Q", KeyS: "S", KeyD: "D", KeyQ: "Q/A", KeyE: "E" },
+    moveHint: "arrows or WASD / ZQSD",
+  });
+  assert.equal(resolveKeycaps(["KeyX"], null).labels.KeyX, "X");
+});
+
+test("keeps the inclusive hint when the map misses a movement key", () => {
+  const partial = new Map([["KeyW", "z"], ["KeyA", "q"], ["KeyS", "s"]]);
+  const { labels, moveHint } = resolveKeycaps(CODES, partial);
+  assert.equal(labels.KeyW, "Z");
+  assert.equal(labels.KeyD, "D");
+  assert.equal(moveHint, "arrows or WASD / ZQSD");
+});
+
+test("rejects layout values that cannot sit on a keycap", () => {
+  const junk = new Map(
+    Object.entries({ KeyQ: "", KeyE: "  ", KeyW: "Dead", KeyA: "́", KeyS: 7 }),
+  );
+  const { labels } = resolveKeycaps(CODES, junk);
+  assert.deepEqual(labels, {
+    KeyW: "W/Z", KeyA: "A/Q", KeyS: "S", KeyD: "D", KeyQ: "Q/A", KeyE: "E",
+  });
+});
+
+test("a throwing map cannot break the menu", () => {
+  const hostile = { get: () => { throw new Error("nope"); } };
+  assert.equal(resolveKeycaps(CODES, hostile).labels.KeyQ, "Q/A");
+});
+
+test("readLayoutMap yields null when the API is absent or refuses", async () => {
+  assert.equal(await readLayoutMap({}), null);
+  assert.equal(await readLayoutMap({ keyboard: {} }), null);
+  const rejects = { keyboard: { getLayoutMap: () => Promise.reject(new Error("blocked")) } };
+  assert.equal(await readLayoutMap(rejects), null);
+  const throws = { keyboard: { getLayoutMap: () => { throw new Error("framed"); } } };
+  assert.equal(await readLayoutMap(throws), null);
+});
+
+test("readLayoutMap returns the map where the API is supported", async () => {
+  const nav = { keyboard: { getLayoutMap: async () => AZERTY } };
+  assert.equal(await readLayoutMap(nav), AZERTY);
+});