Rapid Diffs: Define error handling strategy

Summary

Rapid Diffs does not have a documented error handling strategy. Review discussions across multiple MRs have surfaced a recurring question: should Rapid Diffs code use guard clauses for graceful degradation, or remove them to surface errors as crashes? This question is currently being answered ad hoc in individual MR reviews, producing inconsistent results.

Context

The rapid_diffs JavaScript codebase currently uses three distinct error handling patterns:

  1. Guard clauses (if (!x) return;) - 32 instances. Used for missing DOM elements, optional features, and runtime state checks.
  2. createAlert() via try/catch - ~10 instances. Used for user-facing runtime failures (failed HTTP requests, streaming errors).
  3. throw new Error() - 2 instances. Used for programmer invariant violations (undeclared adapter event names, invalid enum values).

There is no documented guidance on when to use which pattern. There are no error boundaries or centralized error reporting mechanisms for client-side JavaScript failures.

Proposal

Define and document an error handling strategy for Rapid Diffs that answers:

  1. What conditions are fatal vs. recoverable? When should the application crash vs. degrade gracefully?
  2. How are errors surfaced to developers? If guard clauses are insufficient for diagnostic visibility, what reporting mechanism should replace or supplement them? (e.g., createAlert, console.error, Sentry integration, a custom error reporter)
  3. What infrastructure is needed? If the team wants a fail-fast approach, what error boundaries or recovery mechanisms need to exist first?
  4. How does this affect users? The strategy should prioritize the end user's ability to continue working. A degraded page is preferable to a broken one.

References