feature(lambda-rs): Refactor the current event system to allow components to only implement handlers for events they care about

[vmarcella]

Summary

Replace the monolithic Component::on_event entry point with opt-in per-category
event handlers (on_window_event, on_keyboard_event, etc.) and introduce
EventMask for O(1) event filtering at the runtime level. This reduces
boilerplate pattern matching in components and allows runtimes to skip dispatch
for components that do not declare interest in a given event category.

Related Issues

• [Feature] Bitmask-Based Component Event Filtering with Granular Handlers #91

Changes

• Add EventMask bitmask type with category constants (WINDOW, KEYBOARD,
  MOUSE, RUNTIME, COMPONENT) and contains/union operations
• Add Events::mask() method to map event variants to their category
• Remove Component::on_event from the public API
• Add Component::event_mask() with default returning EventMask::NONE
• Add per-category on_*_event handlers with default no-op implementations
• Update ApplicationRuntime to filter dispatch using EventMask
• Update all examples to use the new event handling API
• Update docs/rendering.md with new component examples
• Add unit tests for EventMask behavior and runtime dispatch filtering
• Add Default derive to EventMask for convenience

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (updates to docs, specs, tutorials, or comments)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Performance (change that improves performance)
• Test (adding or updating tests)
• Build/CI (changes to build process or CI configuration)

Affected Crates

• lambda-rs
• lambda-rs-platform
• lambda-rs-args
• lambda-rs-logging
• Other:

Checklist

• Code follows the repository style guidelines (cargo +nightly fmt --all)
• Code passes clippy (cargo clippy --workspace --all-targets -- -D warnings)
• Tests pass (cargo test --workspace)
• New code includes appropriate documentation
• Public API changes are documented
• Breaking changes are noted in this PR description

Testing

Commands run:

cargo build --workspace
cargo test --workspace
cargo +nightly fmt --all
cargo clippy --workspace --all-targets -- -D warnings

Manual verification steps (if applicable):

1. Run examples to verify event handling still works:
   • cargo run -p lambda-rs --example minimal
   • cargo run -p lambda-rs --example triangle
   • cargo run -p lambda-rs --example reflective_room
2. Verify window resize events update viewports correctly
3. Verify keyboard input toggles work in reflective_room example

Screenshots/Recordings

N/A - No visual changes; API refactor only.

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

Breaking Change Migration

Components must migrate from on_event to the new per-category handlers:

Before:

fn on_event(&mut self, event: Events) -> Result<R, E> {
  match event {
    Events::Window { event: WindowEvent::Resize { width, height }, .. } => {
      self.width = width;
      self.height = height;
    }
    Events::Keyboard { event: Key::Pressed { virtual_key, .. }, .. } => {
      // handle key
    }
    _ => {}
  }
  Ok(())
}

After:

fn event_mask(&self) -> EventMask {
  return EventMask::WINDOW | EventMask::KEYBOARD;
}

fn on_window_event(&mut self, event: &WindowEvent) -> Result<(), E> {
  if let WindowEvent::Resize { width, height } = event {
    self.width = *width;
    self.height = *height;
  }
  return Ok(());
}

fn on_keyboard_event(&mut self, event: &Key) -> Result<(), E> {
  if let Key::Pressed { virtual_key, .. } = event {
    // handle key
  }
  return Ok(());
}

Key API Changes

Old API	New API
Component::on_event(&mut self, event: Events)	Removed
N/A	Component::event_mask(&self) -> EventMask
N/A	Component::on_window_event(&mut self, event: &WindowEvent)
N/A	Component::on_keyboard_event(&mut self, event: &Key)
N/A	Component::on_mouse_event(&mut self, event: &Mouse)
N/A	Component::on_runtime_event(&mut self, event: &RuntimeEvent)
N/A	Component::on_component_event(&mut self, event: &ComponentEvent)

Performance

• Event dispatch now skips components whose event_mask() does not include the
  event category, reducing unnecessary handler invocations
• EventMask is a u8 bitmask with #[repr(transparent)], ensuring minimal
  overhead for the filtering check

[Copilot]

Pull request overview

This PR refactors the component event handling system to replace the monolithic Component::on_event method with opt-in per-category event handlers and introduces EventMask for efficient O(1) event filtering. The changes reduce boilerplate in components and allow the runtime to skip dispatch to components that don't declare interest in specific event categories.

Changes:

• Introduced EventMask bitmask type with category constants and operations
• Replaced Component::on_event with event_mask() and per-category on_*_event handlers
• Updated ApplicationRuntime to filter event dispatch using EventMask

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
crates/lambda-rs/src/events.rs	Adds EventMask type with bitmask operations and Events::mask() method
crates/lambda-rs/src/component.rs	Removes on_event, adds event_mask() and per-category handlers with default implementations
crates/lambda-rs/src/runtimes/application.rs	Implements dispatch filtering logic and adds comprehensive unit tests
tools/obj_loader/src/main.rs	Migrates to new event handling API
crates/lambda-rs/examples/*.rs	Updates all examples to use new per-category handlers
docs/tutorials/*.md	Updates tutorial code examples and documentation to reflect new API
docs/specs/component-event-handling.md	New specification document detailing the event handling architecture

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.