Refactor and enhance documentation across the Wolf3D project

- Updated library imports to use the correct package paths for consistency.
- Added detailed documentation comments to various classes and methods, improving code readability and maintainability.
- Refined the GameSelectScreen, SpriteGallery, and VgaGallery classes with clearer descriptions of their functionality.
- Enhanced the CliInput class to better explain the input handling process and its interaction with the engine.
- Improved the SixelRasterizer and Opl2Emulator classes with comprehensive comments on their operations and state management.
- Removed the deprecated wolf_3d.dart file and consolidated its functionality into wolf_3d_flutter.dart for a cleaner architecture.
- Updated the Wolf3dFlutterInput class to clarify its role in merging keyboard and pointer events.
- Enhanced the rendering classes to provide better context on their purpose and usage within the Flutter framework.

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>

packages/wolf_3d_dart/lib/src/input/cli_input.dart

@@ -1,8 +1,13 @@
+/// CLI-specific input adapter that converts raw key bytes into engine actions.
+library;
+
 import 'package:wolf_3d_dart/src/input/wolf_3d_input.dart';
 import 'package:wolf_3d_dart/wolf_3d_entities.dart';
 
+/// Buffers one-frame terminal key presses for consumption by the engine loop.
 class CliInput extends Wolf3dInput {
-  // Pending buffer for asynchronous stdin events
+  // Raw stdin arrives asynchronously, so presses are staged here until the
+  // next engine frame snapshots them into the active state.
   bool _pForward = false;
   bool _pBackward = false;
   bool _pLeft = false;
@@ -11,7 +16,7 @@ class CliInput extends Wolf3dInput {
   bool _pInteract = false;
   WeaponType? _pWeapon;
 
-  /// Call this directly from the stdin listener to queue inputs for the next frame
+  /// Queues a raw terminal key sequence for the next engine frame.
   void handleKey(List<int> bytes) {
     String char = String.fromCharCodes(bytes).toLowerCase();
 
@@ -20,7 +25,8 @@ class CliInput extends Wolf3dInput {
     if (char == 'a') _pLeft = true;
     if (char == 'd') _pRight = true;
 
-    // --- NEW MAPPINGS ---
+    // Fire and interact stay on separate keys so the terminal host can avoid
+    // ambiguous control sequences used by some shells and terminals.
     if (char == 'j') _pFire = true;
     if (char == ' ') _pInteract = true;
 
@@ -32,7 +38,7 @@ class CliInput extends Wolf3dInput {
 
   @override
   void update() {
-    // 1. Move pending inputs to the active state
+    // Promote buffered presses into the engine-visible state for this frame.
     isMovingForward = _pForward;
     isMovingBackward = _pBackward;
     isTurningLeft = _pLeft;
@@ -41,7 +47,7 @@ class CliInput extends Wolf3dInput {
     isInteracting = _pInteract;
     requestedWeapon = _pWeapon;
 
-    // 2. Wipe the pending slate clean for the next frame
+    // Reset the pending buffer so each keypress behaves like a frame impulse.
     _pForward = _pBackward = _pLeft = _pRight = _pFire = _pInteract = false;
     _pWeapon = null;
   }