Forem: Hasnaat Iftikhar

Why AI backend code breaks when specs are vague (and what I’m building to fix it)

Hasnaat Iftikhar — Tue, 13 Jan 2026 14:57:01 +0000

AI tools like Cursor and ChatGPT are incredibly useful, but while building backend features I kept running into the same problem.

When backend requirements are vague, AI starts guessing.

That usually leads to:

Incorrect business logic
APIs that don’t match real product needs
Auth and data rules breaking
Rewriting the same code multiple times

I realized the issue isn’t AI.

The issue is unclear backend specifications.

Instead of jumping straight into code generation, I started defining things first:

Data models and relationships
API contracts
Authentication and authorization rules
Error handling and edge cases

This approach worked far better.

So I built Onvyo.

Onvyo is an AI-powered developer tool that generates end-to-end, implementation-ready backend specifications before you write or generate any code.

It uses a structured interview flow (not free-text prompting) and outputs a detailed backend spec in Markdown that you can paste directly into tools like Cursor or ChatGPT.

The goal is simple:

Give AI clear, deterministic instructions so it stops guessing and starts generating correct backend code.

Onvyo is now live and still early:
👉 https://onvyo.com

I’m building this in public and actively collecting feedback.

If you’ve struggled with AI-generated backend code due to unclear specs, I’d love to hear how you’re handling it today.

Building Resilient Loading States: Beyond Simple Spinners

Hasnaat Iftikhar — Tue, 13 Jan 2026 13:54:17 +0000

Building Resilient Loading States: Beyond Simple Spinners

You know that moment when you click "delete" on something, and it disappears from the screen, but then you refresh the page and it's still there? Or worse, you see a "deleted" label on something that's actually still being created in the background?

I've been there. We all have. And it's frustrating for users.

Recently, I was working on a feature where users could create content that loads in the background. The problem? Sometimes the content wasn't immediately available in the API, even though we'd already shown it on screen. When we checked if something existed, we'd get a 404 error, and our code would assume it was deleted. But really, it was just still being created.

That's when I realized: simple loading states aren't enough. We need resilient loading states that handle edge cases, network failures, and the messy reality of background operations.

In this article, I'll walk you through the patterns I used to build loading states that actually work in production. We'll cover polling with max timeouts, retry mechanisms, caching strategies, and error recovery. By the end, you'll have a toolkit for handling loading states that don't break when things go wrong.

The Problem with Simple Loading States

Let me explain the issue. You have a feature where users can create items. The creation happens on the server, and it takes time. Maybe it takes a few seconds, maybe the server needs to process it, or maybe there's a queue involved.

Here's what happens with a basic approach:

const checkIfItemExists = async (itemId: string) => {
  try {
    const response = await fetch(`/api/items/${itemId}`);
    if (response.ok) {
      return true; // Item exists
    } else if (response.status === 404) {
      return false; // Item doesn't exist (must be deleted)
    }
  } catch (error) {
    // Network error - assume it doesn't exist?
    return false;
  }
};

The problem? This code can't tell the difference between:

Situation	What the Code Thinks	What's Actually Happening
Item was deleted	Item doesn't exist	✅ Correct
Item is still being created	Item doesn't exist	❌ Wrong - it's loading
Network error	Item doesn't exist	❌ Wrong - we don't know
Server is down	Item doesn't exist	❌ Wrong - temporary issue

So when you check for an item that was just created, you might get a 404, and your code assumes it's deleted. You show a "deleted" label, the user gets confused, and everyone's frustrated.

Why Simple Spinners Fail

The typical loading state looks like this:

const [loading, setLoading] = useState(false);
const [item, setItem] = useState(null);

useEffect(() => {
  setLoading(true);
  fetchItem(id)
    .then(setItem)
    .finally(() => setLoading(false));
}, [id]);

if (loading) return <Spinner />;
if (!item) return <div>Item not found</div>;
return <ItemDisplay item={item} />;

This works fine when everything goes smoothly. But what about when:

The network is slow?
The request times out?
The item is still being created?
There's a temporary server error?

Your users see "Item not found" when really, the item just needs a few more seconds. Or they see a spinner forever because the network is having issues.

We need something better.

The Solution: Polling with Max Timeout

My first thought was to use a "grace period" - if an item was just created, give it a few seconds before assuming it doesn't exist. But this approach has a fatal flaw: we're guessing how long creation takes.

What if the API needs 10 seconds, but we set a 5-second grace period? We'd mark items as "deleted" when they're still being created.

The real solution: Don't guess. Keep polling until we get a definitive answer, with a maximum timeout as a safety net.

Instead of relying on a grace period guess, we should:

Keep polling - Continue checking until we get a definitive answer
Set a maximum timeout - Only give up after a reasonable time (e.g., 30-60 seconds)
Grace period is optional - It's just a mental model, not the core logic

Here's a better implementation that doesn't rely on guessing:

interface ItemCheckOptions {
  itemId: string;
  createdAt: number;
  maxWaitTimeMs?: number; // Maximum time to wait (default: 30000ms = 30 seconds)
}

const checkItemWithPolling = async (
  options: ItemCheckOptions
): Promise<'exists' | 'loading' | 'deleted'> => {
  const { 
    itemId, 
    createdAt, 
    maxWaitTimeMs = 30000 // 30 seconds
  } = options;

  const now = Date.now();
  const age = now - createdAt;

  // If we've waited too long, assume it's deleted
  if (age > maxWaitTimeMs) {
    return 'deleted';
  }

  try {
    const response = await fetch(`/api/items/${itemId}`);

    if (response.ok) {
      return 'exists'; // Found it!
    }

    if (response.status === 404) {
      // Not found yet - but we're still within max wait time
      // Keep polling (handled by the component)
      return 'loading';
    }

    // Other error - treat as loading
    return 'loading';
  } catch (error) {
    // Network error - if within max timeout, keep trying
    if (age < maxWaitTimeMs) {
      return 'loading';
    }
    return 'deleted';
  }
};

Key insight: We don't need to guess how long creation takes. We just keep checking until either:

✅ Item appears (success!)
❌ Max timeout expires (assume deleted)

How This Works Better

Here's the improved timeline:

Time	What Happens	Status
0s	User creates item	Creating...
5s	Check API - 404 error	Still loading (keep polling)
10s	Check API - 404 error	Still loading (keep polling)
15s	Check API - 200 success	✅ Item exists!
35s	Check API - 404 error	❌ Item deleted (max timeout reached)

Notice: We don't give up at 5 seconds. We keep checking until either success or the max timeout.

Using Polling in Components

Here's how you'd use this in a React component with polling:

const ItemStatus = ({ itemId, createdAt }: Props) => {
  const [status, setStatus] = useState<'exists' | 'loading' | 'deleted'>('loading');

  useEffect(() => {
    const checkStatus = async () => {
      const result = await checkItemWithPolling({
        itemId,
        createdAt,
        maxWaitTimeMs: 30000  // Stop after 30 seconds
      });
      setStatus(result);

      // Stop polling if item exists or is confirmed deleted
      if (result === 'exists' || result === 'deleted') {
        return false; // Signal to stop polling
      }
      return true; // Continue polling
    };

    // Initial check
    checkStatus();

    // Poll every second while loading
    const interval = setInterval(async () => {
      const shouldContinue = await checkStatus();
      if (!shouldContinue) {
        clearInterval(interval);
      }
    }, 1000);

    return () => clearInterval(interval);
  }, [itemId, createdAt]);

  if (status === 'loading') {
    return <div>Creating item...</div>;
  }

  if (status === 'deleted') {
    return <div>Item was deleted</div>;
  }

  return <div>Item exists!</div>;
};

Understanding the Time Windows

Here's how it works:

Time Period	Purpose	Example Value
Polling Interval	How often we check the API	1 second
Max Wait Time	When to give up and assume deleted	30 seconds

The key insight: We don't need to guess how long creation takes. We just keep polling until either:

✅ The item appears (success!)
❌ The max wait time expires (assume deleted)

Choosing the right max wait time:

Should be longer than your longest expected creation time
If items sometimes take 20 seconds, use 30-60 seconds
This gives slow operations time to complete without waiting forever

Handling Network Failures

Network requests fail. Sometimes it's temporary, sometimes the server is slow. For critical checks, you might want simple retry logic.

Here's a basic approach:

const fetchWithRetry = async (
  url: string,
  maxRetries: number = 3
): Promise<Response> => {
  let lastError: Error | null = null;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url);

      // Retry on server errors (5xx) but not client errors (4xx)
      if (response.status >= 500 && attempt < maxRetries) {
        // Wait a bit before retrying
        await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
        continue;
      }

      return response;
    } catch (error) {
      lastError = error as Error;
      if (attempt < maxRetries) {
        // Wait before retrying
        await new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
      }
    }
  }

  throw lastError || new Error('Max retries exceeded');
};

When to retry:

✅ Network errors (usually temporary)
✅ Server errors (5xx - temporary issues)
❌ Client errors (4xx - user or code problem)
❌ Creating new items (might create duplicates)

Caching for Performance

If you're checking the same items multiple times, caching can dramatically improve performance and reduce server load.

Simple Cache Implementation

Here's a basic cache for item existence checks:

interface CacheEntry {
  result: boolean;
  timestamp: number;
  ttl: number; // Time to live in milliseconds
}

class ItemExistenceCache {
  private cache = new Map<string, CacheEntry>();
  private defaultTtl = 5 * 60 * 1000; // 5 minutes

  get(itemId: string): boolean | null {
    const entry = this.cache.get(itemId);

    if (!entry) {
      return null; // Not in cache
    }

    const age = Date.now() - entry.timestamp;
    if (age > entry.ttl) {
      this.cache.delete(itemId);
      return null; // Expired
    }

    return entry.result;
  }

  set(itemId: string, exists: boolean, ttl?: number): void {
    this.cache.set(itemId, {
      result: exists,
      timestamp: Date.now(),
      ttl: ttl || this.defaultTtl
    });
  }

  invalidate(itemId: string): void {
    this.cache.delete(itemId);
  }

  clear(): void {
    this.cache.clear();
  }
}

const itemCache = new ItemExistenceCache();

Using Cache in Your Checks

Now we can use the cache to avoid unnecessary API calls:

const checkItemWithCache = async (
  itemId: string,
  conversationId: string
): Promise<boolean> => {
  // Check cache first
  const cacheKey = `${conversationId}:${itemId}`;
  const cached = itemCache.get(cacheKey);

  if (cached !== null) {
    return cached; // Return cached result
  }

  // Not in cache, fetch from API
  try {
    const response = await fetch(`/api/items/${itemId}`);
    const exists = response.ok;

    // Cache the result
    itemCache.set(cacheKey, exists);

    return exists;
  } catch (error) {
    // On error, don't cache (we don't know the real state)
    throw error;
  }
};

Cache Benefits

Here's how caching helps:

Scenario	Without Cache	With Cache
First check	API call	API call
Second check (same item)	API call	✅ Instant (from cache)
Third check (same item)	API call	✅ Instant (from cache)
After 5 minutes	API call	API call (cache expired)

Cache Invalidation

Knowing when to clear your cache is important:

// Clear cache when item is deleted
const deleteItem = async (itemId: string) => {
  await fetch(`/api/items/${itemId}`, { method: 'DELETE' });
  itemCache.invalidate(itemId);
};

// Don't cache immediately when item is created
const createItem = async (item: Item) => {
  const newItem = await fetch('/api/items', {
    method: 'POST',
    body: JSON.stringify(item)
  }).then(r => r.json());

  // Don't cache immediately - might still be creating
  // Cache will be saved on first successful check
};

Error States and Recovery

When things go wrong, users need to know what happened and how to fix it. Vague error messages like "Something went wrong" don't help anyone.

Clear Error Messages

const getErrorMessage = (error: Error, context: string): string => {
  if (error.message.includes('network')) {
    return 'Network error. Please check your connection and try again.';
  }

  if (error.message.includes('timeout')) {
    return 'Request timed out. The server might be slow right now.';
  }

  if (error.message.includes('404')) {
    return `${context} not found. It may have been deleted.`;
  }

  if (error.message.includes('500')) {
    return 'Server error. Please try again in a moment.';
  }

  return `Unable to load ${context}. Please try again.`;
};

Error Message Examples

Here's how different errors are shown to users:

Error Type	Technical Message	User-Friendly Message
Network error	`NetworkError: Failed to fetch`	"Network error. Please check your connection and try again."
Timeout	`TimeoutError: Request timed out`	"Request timed out. The server might be slow right now."
404	`404: Not Found`	"Item not found. It may have been deleted."
500	`500: Internal Server Error`	"Server error. Please try again in a moment."

Error Recovery UI

Give users a way to recover:

const ItemWithErrorRecovery = ({ itemId }: Props) => {
  const [status, setStatus] = useState<'loading' | 'exists' | 'error'>('loading');
  const [error, setError] = useState<Error | null>(null);
  const { retry, canRetry } = useItemChecker(itemId);

  if (status === 'loading') {
    return <div>Loading item...</div>;
  }

  if (status === 'error') {
    return (
      <div className="error-container">
        <p>{getErrorMessage(error!, 'Item')}</p>
        {canRetry && (
          <button onClick={retry}>
            Try Again
          </button>
        )}
      </div>
    );
  }

  return <ItemDisplay itemId={itemId} />;
};

Putting It All Together

Here's a simplified example that combines the core patterns:

interface ItemCheckerOptions {
  itemId: string;
  createdAt?: number;
  maxWaitTimeMs?: number;
}

const useItemChecker = (options: ItemCheckerOptions) => {
  const {
    itemId,
    createdAt,
    maxWaitTimeMs = 30000 // 30 seconds max
  } = options;

  const [status, setStatus] = useState<'loading' | 'exists' | 'deleted' | 'error'>('loading');
  const [error, setError] = useState<Error | null>(null);

  const checkItem = useCallback(async () => {
    // Check if we've exceeded max wait time
    if (createdAt) {
      const age = Date.now() - createdAt;
      if (age > maxWaitTimeMs) {
        setStatus('deleted');
        return;
      }
    }

    try {
      const response = await fetch(`/api/items/${itemId}`);

      if (response.ok) {
        setStatus('exists');
      } else if (response.status === 404) {
        // Check if still within max wait time
        if (createdAt) {
          const age = Date.now() - createdAt;
          if (age < maxWaitTimeMs) {
            // Still within max wait time - keep polling
            setStatus('loading');
            return;
          }
        }

        // Exceeded max wait time - assume deleted
        setStatus('deleted');
      } else {
        setStatus('error');
        setError(new Error(`Server returned ${response.status}`));
      }
    } catch (err) {
      // Network error - check if still within max wait time
      if (createdAt) {
        const age = Date.now() - createdAt;
        if (age < maxWaitTimeMs) {
          setStatus('loading');
          return;
        }
      }

      setStatus('error');
      setError(err as Error);
    }
  }, [itemId, createdAt, maxWaitTimeMs]);

  useEffect(() => {
    checkItem();

    // Re-check every second if still loading
    if (status === 'loading') {
      const interval = setInterval(checkItem, 1000);
      return () => clearInterval(interval);
    }
  }, [checkItem, status]);

  const retry = useCallback(() => {
    setError(null);
    checkItem();
  }, [checkItem]);

  return {
    status,
    error,
    retry,
    isLoading: status === 'loading',
    exists: status === 'exists'
  };
};

This hook combines:

✅ Polling with max timeout
✅ Clear error states
✅ Manual retry capability

Best Practices

Here are some lessons I learned while implementing these patterns:

1. Always Show a Loading State

Don't leave users guessing. Even if you're not sure, show something.

Bad:

if (!item) return null; // User sees nothing

Good:

if (!item) return <div>Loading...</div>; // User knows something is happening

2. Handle Edge Cases

404s aren't always "not found" - they might mean "not created yet" or "not accessible".

3. Provide Recovery Mechanisms

Give users a way to retry or refresh when things go wrong.

4. Cache When Possible

But be smart about clearing cache. Old data is worse than no data.

5. Use Appropriate Timeouts

Choose your max wait time based on your API's behavior:

Max Wait Time:

Should be longer than your longest expected creation time
Gives slow operations time to complete
Only assume deletion after this time expires

Typical Creation Time	Recommended Max Wait Time
1-2 seconds	20 seconds
3-5 seconds	30 seconds
5-10 seconds	60 seconds

Too short, and you'll give up on slow operations. Too long, and users wait unnecessarily.

6. Log Errors for Debugging

But don't show technical errors to users. Translate them into user-friendly messages.

7. Test Failure Scenarios

Network failures, timeouts, server errors - test them all.

Common Pitfalls

Here's what to avoid:

Mistake	Why It's Bad	How to Fix
Assuming 404 means deleted	Item might still be creating	Use polling with max timeout
Not handling network errors	Network failures are common	Add retry logic
Forgetting to clear cache	Old cache causes confusion	Clear cache on updates
Retrying operations that create things	Might create duplicates	Only retry safe operations
No user feedback	Users don't know what's happening	Always show loading/error states

Conclusion

Simple loading states work fine for simple cases. But real applications need resilient loading states that handle edge cases, network failures, and the messy reality of background operations.

By combining polling with max timeouts, retry mechanisms, caching, and clear error handling, you can build loading states that actually work in production. Your users will thank you for it.

The patterns I've shared here are tested and production-ready. Start with polling for new content, add retries for network failures, implement caching for performance, and always provide clear error messages with recovery options.

Remember: the goal isn't to handle every possible edge case perfectly. It's to handle the common cases well and gracefully handle problems when things go wrong.

Have you implemented similar patterns? What challenges did you face? I'd love to hear about your experiences in the comments below.

Building a Centralized Keyboard Shortcut System in React: A Priority-Based Approach

Hasnaat Iftikhar — Tue, 06 Jan 2026 12:01:17 +0000

Building a Centralized Keyboard Shortcut System in React: A Priority-Based Approach

Have you ever pressed Escape in your React app and wondered why nothing happened? Or worse, the wrong thing happened? Maybe you had a modal open, but pressing Escape closed something else entirely. Or perhaps you had multiple panels open, and Escape closed the wrong one first.

I recently ran into this exact problem while working on a complex React application with nested panels, modals, and various UI components. Each component was handling keyboard events independently, leading to conflicts, unpredictable behavior, and a frustrating user experience.

After some trial and error, I built a centralized keyboard shortcut system using a priority-based approach. It solved all my problems, and I think it might help you too.

The Problem with Scattered Handlers

Let me show you what I was dealing with. Initially, I had keyboard handlers scattered across different components:

// ComponentA.tsx - This component handles Escape key to close Panel A
useEffect(() => {
  // Create a function that will handle keyboard events
  const handler = (e) => { 
    // Check if the pressed key is Escape
    if (e.key === 'Escape') { 
      // If yes, close Panel A
      closePanelA(); 
    } 
  };
  // Register this handler to listen for keydown events on the entire document
  document.addEventListener('keydown', handler);
  // Cleanup: Remove the listener when component unmounts
  return () => document.removeEventListener('keydown', handler);
}, []); // Empty array means this effect runs only once when component mounts

// ComponentB.tsx - This component ALSO handles Escape key to close Panel B
useEffect(() => {
  // Another handler for the same Escape key
  const handler = (e) => { 
    if (e.key === 'Escape') { 
      closePanelB(); // This closes Panel B instead
    } 
  };
  document.addEventListener('keydown', handler);
  return () => document.removeEventListener('keydown', handler);
}, []);

This approach has several problems:

No clear execution order - When both panels are open, which handler runs first? It's unpredictable. The browser might call them in any order, or both might execute, causing confusion.
Conflicts - Multiple handlers might try to handle the same key, causing unexpected behavior. Both panels might close at once, or neither might close.
Hard to maintain - Adding a new keyboard shortcut means finding the right component and hoping it doesn't conflict with existing ones. You have to search through multiple files.
Difficult to debug - When something goes wrong, you have to check multiple files to understand what's happening. There's no single place to see all keyboard shortcuts.

In my case, I had a complex UI with nested panels, modals, and various overlays. The Escape key needed to close things in a specific order - the most nested panel first, then work its way out. But with scattered handlers, this was impossible to guarantee.

The Solution: A Centralized Registry

Instead of having handlers scattered everywhere, I created a single registry (think of it as a list or database) that contains all keyboard shortcuts. Each shortcut has:

A key (or key combination) - like "Escape" or "Ctrl+K"
A condition that determines when it should be active - a function that checks if the shortcut should work right now
A handler function that executes the action - what to do when the shortcut is pressed
A priority number (lower = higher priority) - which shortcut should run first if multiple match

Here's the basic structure:

// This interface (TypeScript type definition) describes what each keyboard shortcut looks like
export interface Keybinding {
  // The main key being pressed (e.g., "Escape", "Enter", "k")
  key: string;

  // Optional modifier keys (like Ctrl, Shift, Alt, Cmd)
  // The "?" means these are optional - you don't have to provide them
  modifiers?: {
    meta?: boolean; // Cmd key on Mac (⌘)
    ctrl?: boolean; // Ctrl key on Windows/Linux
    shift?: boolean; // Shift key
    alt?: boolean; // Alt key (Option on Mac)
  };

  // A function that returns true/false to determine if this shortcut should be active
  // It receives the current app context (what's open, what's closed, etc.)
  condition: (context: AppContext) => boolean;

  // The function that runs when this shortcut is pressed
  // It receives: the keyboard event, current context, and available actions
  handler: (event: KeyboardEvent, context: AppContext, actions: Actions) => void;

  // Should we prevent the browser's default behavior for this key?
  // For example, prevent Escape from closing the browser tab
  preventDefault?: boolean;

  // Priority number: lower number = higher priority (runs first)
  // Example: priority 1 runs before priority 2
  priority?: number;
}

The key insight here is the priority system. When a key is pressed, the system evaluates all keybindings in priority order (lowest number first). The first matching keybinding wins and gets executed. This ensures predictable behavior - you always know which shortcut will run first.

Building the Context System

Before we can evaluate conditions (check if shortcuts should be active), we need to know the current state of the application. I created a context object (a simple JavaScript object) that contains boolean flags (true/false values) representing the current UI state:

// This type definition describes what our context object looks like
// It's like a snapshot of what's currently open or closed in the app
type AppContext = {
  IS_MODAL_OPEN: boolean;      // Is a modal dialog open? (true/false)
  IS_SIDEBAR_OPEN: boolean;    // Is the sidebar open? (true/false)
  IS_PANEL_A_OPEN: boolean;    // Is Panel A open? (true/false)
  IS_PANEL_B_OPEN: boolean;    // Is Panel B open? (true/false)
  // ... more flags for other UI elements
};

I compute this context from my application state using a custom hook (a reusable React function):

// This custom hook creates and returns the current app context
export const useAppShortcuts = () => {
  // Get the current state from our app store (state management)
  // The "??" operator means "if this is null/undefined, use false instead"
  const isModalOpen = useAppStore((state) => state.MODAL?.isOpen ?? false);
  const isSidebarOpen = useAppStore((state) => state.SIDEBAR?.isOpen ?? false);
  // ... more state selectors for other UI elements

  // useMemo: Only recalculate the context object when dependencies change
  // This prevents creating a new object on every render, which improves performance
  const context = useMemo<AppContext>(() => ({
    IS_MODAL_OPEN: isModalOpen,      // Map state to context flag
    IS_SIDEBAR_OPEN: isSidebarOpen,  // Map state to context flag
    // ... map more state values to context flags
  }), [isModalOpen, isSidebarOpen]); // Only recalculate when these values change

  return { context }; // Return the context so other components can use it
};

Why use useMemo? The useMemo hook ensures we only recompute the context when the actual state values change. Without it, we'd create a new context object on every render, even if nothing changed. This helps with performance and prevents unnecessary re-renders.

The Priority-Based Evaluation

Now for the fun part - the evaluation logic. When a key is pressed, we:

Sort all keybindings by priority (lowest number first, like 1, 2, 3)
Loop through them in order (check priority 1, then 2, then 3, etc.)
Check if the condition matches the current context (should this shortcut be active right now?)
Check if the key and modifiers match (is the right key being pressed?)
Execute the first matching handler and stop (don't check any more shortcuts)

Here's the implementation with detailed comments:

// This function is called whenever a key is pressed
// It takes: the keyboard event, current app context, and available actions
// Returns: true if a shortcut was executed, false if nothing matched
export const executeKeybinding = (
  event: KeyboardEvent,    // The keyboard event (which key was pressed, etc.)
  context: AppContext,     // Current app state (what's open, what's closed)
  actions: Actions         // Available actions (closeModal, closeSidebar, etc.)
): boolean => {
  // Step 1: Sort all keybindings by priority
  // [...KEYBINDINGS] creates a copy of the array (so we don't modify the original)
  // .sort() arranges them by priority number
  // (a.priority ?? 999) means "use priority if it exists, otherwise use 999"
  // Lower numbers come first (priority 1 before priority 2)
  const sortedKeybindings = [...KEYBINDINGS].sort((a, b) => 
    (a.priority ?? 999) - (b.priority ?? 999)
  );

  // Step 2: Loop through sorted keybindings and find the first match
  for (const keybinding of sortedKeybindings) {
    // Step 3: Check if this shortcut's condition is met
    // The condition function returns true/false based on current context
    // Example: condition might check "is modal open?"
    if (!keybinding.condition(context)) {
      continue; // Skip this shortcut, check the next one
    }

    // Step 4: Check if the pressed key matches this shortcut's key
    // Also check if modifier keys (Ctrl, Shift, etc.) match
    if (!matchesKeybinding(event, keybinding)) {
      continue; // Keys don't match, skip to next shortcut
    }

    // Step 5: We found a match! Execute the handler

    // If preventDefault is true, stop the browser's default behavior
    // (e.g., prevent Escape from closing the browser tab)
    if (keybinding.preventDefault) {
      event.preventDefault();
    }

    // Call the handler function with the event, context, and actions
    // This is where the actual work happens (closing panels, etc.)
    keybinding.handler(event, context, actions);

    // Return true to indicate we handled the keypress
    // Don't check any more shortcuts - first match wins!
    return true;
  }

  // No shortcuts matched, return false
  return false;
};

The matchesKeybinding function checks if the pressed key matches what the shortcut expects. I also added special handling for cross-platform shortcuts (Cmd on Mac, Ctrl on Windows/Linux):

// This function checks if a keyboard event matches a keybinding definition
// Returns true if they match, false otherwise
const matchesKeybinding = (event: KeyboardEvent, keybinding: Keybinding): boolean => {
  // Step 1: Check if the main key matches
  // event.key is the key that was pressed (e.g., "Escape", "k", "Enter")
  // keybinding.key is what the shortcut expects
  if (event.key !== keybinding.key) {
    return false; // Keys don't match, this shortcut doesn't apply
  }

  // Step 2: Check modifier keys (Ctrl, Shift, Alt, Cmd) if they're specified
  // Modifiers are optional - some shortcuts don't need them
  if (keybinding.modifiers) {
    // Extract the modifier requirements from the keybinding
    const { meta, ctrl, shift, alt } = keybinding.modifiers;

    // Special case: Cross-platform shortcuts
    // If both meta (Cmd) and ctrl are set to true, we use OR logic
    // This means: "Cmd OR Ctrl" - works on both Mac (Cmd) and Windows/Linux (Ctrl)
    // Example: Cmd+K on Mac OR Ctrl+K on Windows should both work
    if (meta === true && ctrl === true) {
      // Check if EITHER Cmd (Mac) OR Ctrl (Windows/Linux) is pressed
      if (!event.metaKey && !event.ctrlKey) {
        return false; // Neither modifier is pressed, doesn't match
      }
    } else {
      // Standard AND logic for other modifier combinations
      // If meta is specified, check if it matches what was pressed
      // Boolean() converts to true/false, !== checks for exact match
      if (meta !== undefined && Boolean(event.metaKey) !== meta) return false;
      if (ctrl !== undefined && Boolean(event.ctrlKey) !== ctrl) return false;
    }

    // Other modifiers (Shift, Alt) always use AND logic
    // They must match exactly what's specified
    if (shift !== undefined && Boolean(event.shiftKey) !== shift) return false;
    if (alt !== undefined && Boolean(event.altKey) !== alt) return false;
  }

  // All checks passed! The key and modifiers match
  return true;
};

Understanding the cross-platform logic: On Mac, the Command key (⌘) is called metaKey. On Windows/Linux, it's ctrlKey. When we set both meta: true and ctrl: true, we're saying "accept either one" - making the shortcut work on all platforms.

Using Refs to Prevent Stale Closures

Alright, here's where we need to get a bit clever. This section might seem complex at first, but stick with me, I'll explain it in a way that makes sense.

The Challenge We're Solving

When you create an event listener in React, you want it to always know the current state of your app. But React has a quirk: functions created inside components "remember" the values they had when they were first created.

Let me show you what happens if we do this the naive way:

// ❌ This looks simple, but it has problems!
const handleKeyDown = useCallback((event: KeyboardEvent) => {
  executeKeybinding(event, context, actions);
}, [context, actions]); // ← Including these causes trouble

The problem: Every time context or actions change (which happens whenever your app state changes), React creates a brand new handleKeyDown function. This triggers our useEffect to remove the old event listener and add a new one.

Imagine you're listening to a radio, but every time the song changes, someone unplugs your radio and plugs it back in. That's what's happening here, constant re-subscription is inefficient and can cause performance issues.

What's a "Stale Closure"?

A closure is JavaScript's way of letting functions "remember" variables from their surroundings. It's like a function taking a snapshot of the world around it when it's created.

A stale closure happens when that snapshot is outdated. Your function thinks the modal is closed because that's what it saw when it was created, but actually the modal opened five minutes ago.

Here's a simple example:

// Component renders, modal is closed
const isModalOpen = false;

// We create a handler that "remembers" isModalOpen = false
const handleKeyDown = () => {
  if (isModalOpen) { // This will ALWAYS be false, even after modal opens!
    closeModal();
  }
};

// Later, modal opens, component re-renders
// But handleKeyDown still thinks isModalOpen is false!

This is why we need refs, they let us always access the latest values without recreating our functions.

The Solution: Refs (React's Secret Weapon)

Refs are React's way of storing values that survive re-renders without causing them. Think of a ref like a shared notebook that everyone can read and update, but updating it doesn't cause a commotion (no re-renders).

The key insight: We keep the handler function the same (so the listener stays attached), but we always read the latest values from refs.

Step-by-Step: Building Our Ref-Based Solution

Let's build this piece by piece. I'll explain each part and why it matters.

Step 1: Create a ref to store our context

First, we create a "box" (ref) to store the current context. This box persists across renders, and we can update it without causing re-renders.

// Create a ref - think of it as a box that holds our context
const contextRef = useRef(context);

// Whenever context changes, update the box
// This happens silently - no re-renders, no listener re-subscription
useEffect(() => {
  contextRef.current = context; // Put the latest context in the box
}, [context]);

Step 2: Create a ref to store our actions

Same idea for our action functions. We store them in a ref so they don't cause our handler to be recreated.

// Create another box for our action functions
const actionsRef = useRef<Actions>({
  closeModal: selectors.modal.close,
  closeSidebar: selectors.sidebar.close,
  // ... more actions
});

// Update the box whenever action functions change
useEffect(() => {
  actionsRef.current = {
    closeModal: selectors.modal.close,
    closeSidebar: selectors.sidebar.close,
    // ... update more actions
  };
}, [
  selectors.modal.close,
  selectors.sidebar.close,
  // ... more dependencies
]);

Step 3: Create the handler function (the magic happens here)

This is where the magic happens. We create the handler function once, with an empty dependency array. This means React creates it once and never recreates it.

// Create the handler function ONCE and never recreate it
// Empty array [] = "create this once, never change it"
const handleKeyDown = useCallback((event: KeyboardEvent) => {
  // When a key is pressed, read from our refs
  // .current gets the latest value from the ref
  // Even though handleKeyDown was created once, it always reads fresh data!
  executeKeybinding(event, contextRef.current, actionsRef.current);
}, []); // ← Empty array = stable function reference

Step 4: Register the event listener

Finally, we attach our handler to the document. Because handleKeyDown never changes (empty dependency array), this effect only runs once.

// Set up the event listener
useEffect(() => {
  // Add listener when component mounts
  document.addEventListener('keydown', handleKeyDown);

  // Remove listener when component unmounts (cleanup)
  return () => document.removeEventListener('keydown', handleKeyDown);
}, [handleKeyDown]); // Only re-run if handleKeyDown changes (it won't!)

The Complete Picture

Here's the full implementation all together:

export const useAppShortcutHandler = (context: AppContext) => {
  const selectors = useAppSelectors();

  // Step 1: Store context in a ref
  const contextRef = useRef(context);
  useEffect(() => {
    contextRef.current = context;
  }, [context]);

  // Step 2: Store actions in a ref
  const actionsRef = useRef<Actions>({
    closeModal: selectors.modal.close,
    closeSidebar: selectors.sidebar.close,
    // ... more actions
  });

  useEffect(() => {
    actionsRef.current = {
      closeModal: selectors.modal.close,
      closeSidebar: selectors.sidebar.close,
      // ... update more actions
    };
  }, [
    selectors.modal.close,
    selectors.sidebar.close,
    // ... more dependencies
  ]);

  // Step 3: Create handler that reads from refs
  const handleKeyDown = useCallback((event: KeyboardEvent) => {
    executeKeybinding(event, contextRef.current, actionsRef.current);
  }, []); // Empty deps = create once, never recreate

  // Step 4: Register listener (only once!)
  useEffect(() => {
    document.addEventListener('keydown', handleKeyDown);
    return () => document.removeEventListener('keydown', handleKeyDown);
  }, [handleKeyDown]);
};

Why This Works So Well

This pattern gives us three huge benefits:

The listener is registered once - Because handleKeyDown never changes (empty dependency array), the listener is added once and stays attached. No constant removal and re-addition.
Always fresh data - Even though handleKeyDown was created once, it always reads the latest values from contextRef.current and actionsRef.current. It's like having a window that always shows the current weather, even though the window itself never changes.
No infinite loops - Refs update silently without triggering re-renders or function recreations. Your component stays stable.

A Real-World Analogy

Imagine you're a security guard at a building. You have a clipboard (the handler function) that you fill out once. But instead of writing the current information on the clipboard, you write "check the whiteboard" (the ref).

The clipboard never changes (stable handler function)
The whiteboard gets updated with the latest information (ref updates)
Every time you need information, you check the whiteboard (reading from .current)

This way, you always have the latest information without needing a new clipboard every time something changes!

A Real-World Example: Escape Key Hierarchy

Now let's see this system in action! I'll show you how I handled the Escape key in my application.

The Scenario

I had a complex UI with multiple layers:

A modal dialog
A sidebar
Primary panels
Secondary panels
Nested panels (panels within panels)

When a user pressed Escape, I wanted it to close things in a logical order, like peeling an onion, from the inside out. The most nested thing should close first, then work outward.

The Priority System

I organized my Escape key handlers by priority. Lower numbers run first:

Priority 1: Most nested panel - The deepest panel closes first
Priority 2: Secondary panel - Next level up
Priority 3: Primary panel - The main panel
Priority 4: Sidebar - Only if no panels are open
Priority 5: Modal - Only if nothing else is open

Think of it like a stack of plates. When you press Escape, you remove the top plate first, then the next one, and so on.

The Implementation

Here's how I defined these shortcuts in my registry:

export const KEYBINDINGS: Keybinding[] = [
  // Priority 1: Close nested panel first (highest priority)
  {
    key: 'Escape',
    condition: (ctx) => ctx.IS_NESTED_PANEL_OPEN, // Only if nested panel is open
    handler: (event, ctx, actions) => {
      actions.closeNestedPanel?.(); // Close it!
    },
    preventDefault: true,
    priority: 1, // Check this first
  },

  // Priority 2: Close secondary panel
  {
    key: 'Escape',
    condition: (ctx) => ctx.IS_SECONDARY_PANEL_OPEN,
    handler: (event, ctx, actions) => {
      actions.closeSecondaryPanel?.();
    },
    preventDefault: true,
    priority: 2,
  },

  // Priority 3: Close primary panel
  {
    key: 'Escape',
    condition: (ctx) => ctx.IS_PRIMARY_PANEL_OPEN,
    handler: (event, ctx, actions) => {
      actions.closePrimaryPanel?.();
    },
    preventDefault: true,
    priority: 3,
  },

  // Priority 4: Close sidebar (only if no panels are open)
  {
    key: 'Escape',
    // This condition checks: sidebar open AND all panels closed
    condition: (ctx) => ctx.IS_SIDEBAR_OPEN && 
                       !ctx.IS_PRIMARY_PANEL_OPEN &&
                       !ctx.IS_SECONDARY_PANEL_OPEN &&
                       !ctx.IS_NESTED_PANEL_OPEN,
    handler: (event, ctx, actions) => {
      actions.closeSidebar?.();
    },
    preventDefault: true,
    priority: 4,
  },

  // Priority 5: Close modal (only if nothing else is open)
  {
    key: 'Escape',
    // Most restrictive: modal open AND everything else closed
    condition: (ctx) => ctx.IS_MODAL_OPEN && 
                       !ctx.IS_SIDEBAR_OPEN &&
                       !ctx.IS_PRIMARY_PANEL_OPEN &&
                       !ctx.IS_SECONDARY_PANEL_OPEN &&
                       !ctx.IS_NESTED_PANEL_OPEN,
    handler: (event, ctx, actions) => {
      actions.closeModal?.();
    },
    preventDefault: true,
    priority: 5, // Check this last
  },
];

How It Works: A Walkthrough

Let's trace through what happens when a user presses Escape in different scenarios:

Scenario 1: Nested panel is open

System checks Priority 1 → IS_NESTED_PANEL_OPEN is true ✅
Condition matches! → Close nested panel
Stop checking (first match wins)

Scenario 2: Only sidebar and modal are open

System checks Priority 1 → Nested panel? No ❌
System checks Priority 2 → Secondary panel? No ❌
System checks Priority 3 → Primary panel? No ❌
System checks Priority 4 → Sidebar open AND no panels? Yes ✅
Condition matches! → Close sidebar
Stop checking

Scenario 3: Only modal is open

System checks Priorities 1-4 → All fail ❌
System checks Priority 5 → Modal open AND everything closed? Yes ✅
Condition matches! → Close modal

The Key Insight

Notice how the lower priority handlers (sidebar and modal) explicitly check that higher priority panels aren't open. This ensures the correct order, panels always close before sidebar, and sidebar closes before modal.

The result? Predictable, intuitive behavior. Users press Escape, and the most nested thing closes first, just like they expect. It's like closing windows on your computer, the topmost window closes first.

Best Practices: Lessons Learned

After using this system in production, here are the key lessons I learned:

1. Use Sequential Priority Numbers

Don't skip numbers! Use 1, 2, 3, 4, 5 instead of 1, 5, 10, 20. Why? Because you'll inevitably need to insert a new priority between existing ones. If you've used 1, 5, 10, where do you put priority 3? You end up with decimals or awkward numbering.

Good: priority: 1, 2, 3, 4, 5

Bad: priority: 1, 5, 10, 20

2. Document Your Priority Order

Add comments explaining why each priority is set the way it is. Six months from now, when you're wondering why the sidebar closes before the modal, you'll thank yourself.

// Priority 4: Sidebar closes before modal because users expect
// panels to close first, then sidebar, then modal
{
  priority: 4,
  // ...
}

3. Keep Conditions Explicit and Clear

If your condition is complex, break it down or add comments. Future you (and your teammates) will appreciate it.

// Good: Clear and explicit
condition: (ctx) => ctx.IS_MODAL_OPEN && 
                   !ctx.IS_SIDEBAR_OPEN &&
                   !ctx.IS_PANEL_OPEN

// Better: With explanation
condition: (ctx) => {
  // Modal must be open, and nothing else should be open
  return ctx.IS_MODAL_OPEN && 
         !ctx.IS_SIDEBAR_OPEN &&
         !ctx.IS_PANEL_OPEN;
}

4. Always Prevent Default for Custom Shortcuts

If you're handling a key that the browser also uses (like Escape, Ctrl+S, etc.), always set preventDefault: true. Otherwise, both your handler and the browser's default behavior might run, causing unexpected results.

5. Use TypeScript

The type safety catches errors early. When you mistype a context property or forget a required field, TypeScript will tell you immediately. It's worth the setup.

6. Test Your Priority Order Thoroughly

When you add a new shortcut, test it with all relevant UI state combinations. Open a modal and a panel, then press Escape. Does it close the right thing? Test edge cases, you'll find bugs you didn't expect.

Common Mistakes I Made (So You Don't Have To)

I made my fair share of mistakes while building this system. Here are the big ones, and how to avoid them:

Mistake 1: Forgetting to Use Refs

The Problem: I initially included context and actions directly in my useCallback dependency array. This caused the event listener to be removed and re-added constantly, killing performance.

Why it happens: Every time your app state changes, React creates a new context object. Even if the values are the same, it's a new object reference. useCallback sees this as a change and recreates the handler, which triggers the useEffect to re-subscribe the listener.

The Fix: Use refs! Store context and actions in refs, and read from them in your handler. The handler function stays stable, but always reads fresh data.

Mistake 2: Action Functions Changing Every Render

The Problem: If your action functions are recreated on every render (common with arrow functions or functions that depend on state), and you use them in dependencies, you'll get infinite loops.

Why it happens:

// This creates a new function on every render
const closeModal = () => { /* ... */ };

// If you use it in dependencies:
useCallback(() => { /* ... */ }, [closeModal]); // ❌ Infinite loop!

The Fix: Store actions in refs, just like context. Update the ref when actions change, but don't include them in the handler's dependencies.

Mistake 3: Conditions That Are Too Broad

The Problem: I had a shortcut with a condition like ctx.IS_MODAL_OPEN. It would match even when a panel was open, causing the wrong thing to close.

Why it happens: You forget to check that higher priority items aren't open. The system finds a match and stops checking, even though a higher priority item should have handled it.

The Fix: Always check that higher priority items are closed:

// ❌ Too broad
condition: (ctx) => ctx.IS_MODAL_OPEN

// ✅ Specific enough
condition: (ctx) => ctx.IS_MODAL_OPEN && 
                   !ctx.IS_PANEL_OPEN &&
                   !ctx.IS_SIDEBAR_OPEN

Mistake 4: Forgetting preventDefault

The Problem: I handled Escape key presses, but forgot to prevent the browser's default behavior. Sometimes my handler ran, sometimes the browser's default ran, sometimes both, chaos!

Why it happens: Browsers have default behaviors for many keys. Escape closes dialogs, Ctrl+S saves pages, etc. If you don't prevent these, you get unpredictable behavior.

The Fix: Always set preventDefault: true for keys you're handling:

{
  key: 'Escape',
  preventDefault: true, // ← Don't forget this!
  // ...
}

Mistake 5: Wrong Priority Order

The Problem: I put modal closing at priority 1 and panel closing at priority 2. When both were open, the modal would close first, which felt wrong to users.

Why it happens: You think about what's "most important" rather than what should close first. Users expect the topmost/most nested thing to close first.

The Fix: Think about the user's mental model. What's on top? What's most nested? That should close first. Test with all combinations of UI states to verify the order feels right.

Quick Reference: Key Terms

Here's a handy glossary of terms we've used:

Term	What It Means
Registry	The central list/array where all keyboard shortcuts are stored
Keybinding	A single keyboard shortcut definition (key + modifiers + condition + handler)
Context	An object representing your app's current state (what's open, what's closed)
Condition	A function that returns true/false to determine if a shortcut should be active
Handler	The function that runs when a shortcut is triggered
Priority	A number that determines execution order (lower = runs first)
Ref	React's way to store values without triggering re-renders
Stale Closure	When a function remembers old values instead of current ones
useMemo	React hook that only recalculates when dependencies change
useCallback	React hook that memoizes (remembers) a function
useEffect	React hook that runs side effects (like adding event listeners)
useRef	React hook that creates a ref to store values
Modifiers	Special keys like Ctrl, Shift, Alt, Cmd that modify the main key
preventDefault	Stops the browser's default behavior for a key

Wrapping Up

Building this centralized keyboard shortcut system completely changed how I handle keyboard events in React. What started as a frustrating problem with conflicting handlers became a clean, maintainable solution.

What We Built

We created a system that:

✅ Centralizes all shortcuts in one place (easy to find and maintain)
✅ Uses priority ordering for predictable behavior (always know what runs first)
✅ Uses context-driven conditions (shortcuts only activate when they should)
✅ Leverages refs to avoid performance issues (no constant re-subscriptions)
✅ Provides type safety with TypeScript (catch errors early)

The Big Picture

The core idea is simple: one registry, priority-based execution, context-aware conditions, and refs for performance. Once you understand these concepts, the whole system clicks into place.

Is This Right for You?

If you're dealing with:

Multiple keyboard shortcuts that might conflict
Complex UI with nested panels, modals, and overlays
Need for predictable shortcut behavior
Performance concerns with event listeners

Then yes, this approach is worth the initial setup. It might seem like overkill for simple apps, but once you have it, adding new shortcuts is trivial, and debugging is much easier.

Next Steps

Start with a simple registry for your most important shortcuts
Add priorities as you discover conflicts
Build your context system based on your app's state
Use refs from the start (trust me, you'll need them)

Final Thoughts

The best part? Once this system is in place, adding a new keyboard shortcut is just adding an object to an array. No more hunting through components, no more conflicts, no more "why isn't this working?" moments.

Have you built something similar? I'd love to hear about your approach, or if you have questions, drop them in the comments below!