PixelPilot uiux-easter-eggs.instructions.md

Easter Eggs & Delightful Surprises

The best interfaces reward curiosity. This file covers hidden features, secret interactions, achievement unlocks, and delightful surprises that make users smile — without being annoying or inaccessible.

---

CRITICAL RULES

1. Never hide essential features — Easter eggs are bonuses, not requirements.
2. Accessible alternatives — If a secret is useful, provide another path to it.
3. Don't break flow — Surprises should delight, not disrupt.
4. Respect context — No easter eggs in serious/medical/legal contexts.
5. Performance — Hidden features shouldn't load until triggered.

---

KONAMI CODE DETECTOR

The classic: ↑ ↑ ↓ ↓ ← → ← → B A

// useKonamiCode.ts
const KONAMI_CODE = [
  'ArrowUp', 'ArrowUp',
  'ArrowDown', 'ArrowDown',
  'ArrowLeft', 'ArrowRight',
  'ArrowLeft', 'ArrowRight',
  'KeyB', 'KeyA',
];

export function useKonamiCode(callback: () => void) {
  const [index, setIndex] = useState(0);

  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      const expectedKey = KONAMI_CODE[index];
      
      if (e.code === expectedKey) {
        const nextIndex = index + 1;
        
        if (nextIndex === KONAMI_CODE.length) {
          callback();
          setIndex(0);
        } else {
          setIndex(nextIndex);
        }
      } else {
        setIndex(0);
      }
    };

    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [index, callback]);
}

// Usage
function App() {
  const [partyMode, setPartyMode] = useState(false);

  useKonamiCode(() => {
    setPartyMode(true);
    swal.toast('🎉 Party mode activated!');
  });

  return (
    <div className={partyMode ? 'party-mode' : ''}>
      {/* ... */}
    </div>
  );
}

---

CUSTOM SECRET CODES

Create your own activation sequences:

// useSecretCode.ts
interface SecretCodeOptions {
  sequence: string[];      // Keys to detect
  timeout?: number;        // Reset after X ms of inactivity
  onActivate: () => void;
  onProgress?: (progress: number) => void;
}

export function useSecretCode({
  sequence,
  timeout = 2000,
  onActivate,
  onProgress,
}: SecretCodeOptions) {
  const [index, setIndex] = useState(0);
  const timeoutRef = useRef<number>();

  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      // Clear previous timeout
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }

      const expectedKey = sequence[index];
      
      if (e.code === expectedKey || e.key.toLowerCase() === expectedKey.toLowerCase()) {
        const nextIndex = index + 1;
        onProgress?.(nextIndex / sequence.length);
        
        if (nextIndex === sequence.length) {
          onActivate();
          setIndex(0);
        } else {
          setIndex(nextIndex);
          
          // Reset after timeout
          timeoutRef.current = window.setTimeout(() => {
            setIndex(0);
            onProgress?.(0);
          }, timeout);
        }
      } else if (e.key.length === 1) {
        // Wrong key - reset (but ignore modifier keys)
        setIndex(0);
        onProgress?.(0);
      }
    };

    window.addEventListener('keydown', handleKeyDown);
    return () => {
      window.removeEventListener('keydown', handleKeyDown);
      if (timeoutRef.current) clearTimeout(timeoutRef.current);
    };
  }, [sequence, index, timeout, onActivate, onProgress]);

  return { progress: index / sequence.length };
}

// Usage: Type "debug" to open debug panel
function App() {
  const [showDebug, setShowDebug] = useState(false);

  useSecretCode({
    sequence: ['d', 'e', 'b', 'u', 'g'],
    onActivate: () => setShowDebug(true),
  });

  return (
    <>
      {/* ... */}
      {showDebug && <DebugPanel onClose={() => setShowDebug(false)} />}
    </>
  );
}