feat: the 3D cube visualizer has no keyboard shortcut documentation or help overlay — new users don't know about spacebar timing, inspection phase, or modifier keys, making the app inaccessible to first-time speedcubers

[prince-pokharna]

📋 Problem Statement

CubeIt documents the following controls:

"Features a standard 15-second inspection phase, keyboard spacebar controls, and mobile tap-to-start precision."

However, these controls are not discoverable within the app itself. There is no:

• Help overlay or tooltip explaining the spacebar hold-to-start mechanic
• Visual indicator of the WCA inspection phase countdown behaviour
• Documentation of penalty keys (+2 for inspection timeout, DNF)
• Explanation of what Ao5/Ao12 means for new speedcubers
• Mobile gesture guide

First-time users land on the app, see a timer and a 3D cube, and have no idea that they need to hold spacebar (not press it) to start, or that releasing during inspection triggers a +2 penalty.

💡 Proposed Fix

1. Add a first-visit help overlay (shown once, dismissible)

// src/components/HelpOverlay.jsx

const SHORTCUTS = [
  { keys: 'Hold Space', action: 'Start inspection phase (15s WCA timer)' },
  { keys: 'Release Space', action: 'Start solve timer' },
  { keys: 'Space (during solve)', action: 'Stop timer' },
  { keys: '+', action: 'Mark last solve as +2 penalty' },
  { keys: 'D', action: 'Mark last solve as DNF' },
  { keys: 'Delete', action: 'Delete last solve' },
];

export function HelpOverlay({ onClose }) {
  return (
    <div className="help-overlay" role="dialog" aria-label="CubeIt controls">
      <h2>⌨️ Keyboard Controls</h2>
      <table>
        {SHORTCUTS.map(({ keys, action }) => (
          <tr key={keys}>
            <td><kbd>{keys}</kbd></td>
            <td>{action}</td>
          </tr>
        ))}
      </table>
      <p>📱 On mobile: tap and hold the screen to start inspection.</p>
      <button onClick={onClose}>Got it!</button>
    </div>
  );
}

Show it on first visit using localStorage:

const hasSeenHelp = localStorage.getItem('cubeit_help_seen');
if (!hasSeenHelp) {
  setShowHelp(true);
  localStorage.setItem('cubeit_help_seen', 'true');
}

2. Add a persistent ? button in the corner to re-open the overlay

<button
  className="help-button"
  onClick={() => setShowHelp(true)}
  aria-label="Show keyboard shortcuts"
>
  ?
</button>

3. Add inline Ao5/Ao12 tooltips in the Analytics panel

<span title="Average of your last 5 solves (excluding best and worst)">Ao5 ⓘ</span>

📁 Files to Create/Modify

File	Change
src/components/HelpOverlay.jsx	New — keyboard shortcut reference overlay
src/components/Timer.jsx	Show overlay on first visit; add ? button
src/components/Analytics.jsx	Add tooltips for Ao5, Ao12, PB
src/App.css	Style the help overlay and ? button

Suggested labels: enhancement, ux, accessibility, good first issue

I would like to work on this. Could you please assign it to me?

[prince-pokharna]

Hey @vasanth642 ,
Please assign it to me under GSSoC 2026.
/claim /assign /claim-assignment