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>

apps/wolf_3d_cli/bin/main.dart

@@ -1,3 +1,9 @@
+/// CLI entry point for the terminal Wolf3D host.
+///
+/// This executable locates bundled retail assets, constructs a [WolfEngine]
+/// configured for terminal rendering, and then hands control to [CliGameLoop].
+library;
+
 import 'dart:io';
 
 import 'package:wolf_3d_cli/cli_game_loop.dart';
@@ -6,7 +12,7 @@ import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
 import 'package:wolf_3d_dart/wolf_3d_engine.dart';
 import 'package:wolf_3d_dart/wolf_3d_input.dart';
 
-// Helper to gracefully exit and restore the terminal
+/// Restores terminal state before exiting the process with [code].
 void exitCleanly(int code) {
   stdout.write('\x1b[0m'); // Reset color
   stdout.write('\x1b[2J\x1b[H'); // Clear screen
@@ -14,12 +20,13 @@ void exitCleanly(int code) {
   exit(code);
 }
 
+/// Launches the CLI renderer against the bundled retail asset set.
 void main() async {
   stdout.write("Discovering game data...");
-  // 1. Get the absolute URI of where this exact script lives
+  // Resolve the asset package relative to this executable so the CLI can run
+  // from the repo without additional configuration.
   final scriptUri = Platform.script;
 
-  // 2. Resolve the path mathematically.
   final targetUri = scriptUri.resolve(
     '../../../packages/wolf_3d_assets/assets/retail',
   );

apps/wolf_3d_cli/lib/cli_game_loop.dart

@@ -1,3 +1,6 @@
+/// Terminal game loop that ties engine ticks, raw input, and CLI rendering together.
+library;
+
 import 'dart:async';
 import 'dart:io';
 
@@ -5,6 +8,11 @@ import 'package:wolf_3d_dart/wolf_3d_engine.dart';
 import 'package:wolf_3d_dart/wolf_3d_input.dart';
 import 'package:wolf_3d_dart/wolf_3d_rasterizer.dart';
 
+/// Runs the Wolf3D engine inside a terminal using CLI-specific rasterizers.
+///
+/// The loop owns raw-stdin handling, renderer switching, terminal size checks,
+/// and frame pacing. It expects [engine.input] to be a [CliInput] instance so
+/// raw key bytes can be queued directly into the engine input adapter.
 class CliGameLoop {
   CliGameLoop({
     required this.engine,
@@ -35,6 +43,7 @@ class CliGameLoop {
   bool _isRunning = false;
   Duration _lastTick = Duration.zero;
 
+  /// Starts terminal probing, enters raw input mode, and begins the frame timer.
   Future<void> start() async {
     if (_isRunning) {
       return;
@@ -64,6 +73,7 @@ class CliGameLoop {
     _isRunning = true;
   }
 
+  /// Stops the timer, unsubscribes from stdin, and restores terminal settings.
   void stop() {
     if (!_isRunning) {
       return;
@@ -102,6 +112,8 @@ class CliGameLoop {
     }
 
     if (bytes.contains(9)) {
+      // Tab swaps between rasterizers so renderer debugging stays available
+      // without restarting the process.
       _rasterizer = identical(_rasterizer, secondaryRasterizer)
           ? primaryRasterizer
           : secondaryRasterizer;
@@ -125,6 +137,8 @@ class CliGameLoop {
         columns: cols,
         rows: rows,
       )) {
+        // Size warnings are rendered instead of running the simulation so the
+        // game does not keep advancing while the user resizes the terminal.
         stdout.write('\x1b[2J\x1b[H');
         stdout.write(
           _rasterizer.buildTerminalSizeWarning(columns: cols, rows: rows),