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_gui/lib/main.dart

@@ -1,7 +1,14 @@
+/// Flutter entry point for the GUI host application.
+///
+/// The GUI bootstraps bundled and discoverable game data through [Wolf3d]
+/// before presenting the game-selection flow.
+library;
+
 import 'package:flutter/material.dart';
-import 'package:wolf_3d_flutter/wolf_3d.dart';
+import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 import 'package:wolf_3d_gui/screens/game_select_screen.dart';
 
+/// Creates the application shell after loading available Wolf3D data sets.
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
 

apps/wolf_3d_gui/lib/screens/difficulty_screen.dart

@@ -1,11 +1,17 @@
+/// Difficulty picker shown after the player chooses an episode.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
-import 'package:wolf_3d_flutter/wolf_3d.dart';
+import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 import 'package:wolf_3d_gui/screens/game_screen.dart';
 
+/// Starts a new game session using the active game and episode from [Wolf3d].
 class DifficultyScreen extends StatefulWidget {
+  /// Shared application facade carrying the active game, input, and audio.
   final Wolf3d wolf3d;
 
+  /// Creates the difficulty-selection screen for [wolf3d].
   const DifficultyScreen({
     super.key,
     required this.wolf3d,
@@ -25,6 +31,7 @@ class _DifficultyScreenState extends State<DifficultyScreen> {
     super.dispose();
   }
 
+  /// Replaces the menu flow with an active [GameScreen] using [difficulty].
   void _startGame(Difficulty difficulty, {bool showGallery = false}) {
     widget.wolf3d.audio.stopMusic();
 

apps/wolf_3d_gui/lib/screens/episode_screen.dart

@@ -1,13 +1,19 @@
+/// Episode picker and asset-browser entry point for the selected game version.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
-import 'package:wolf_3d_flutter/wolf_3d.dart';
+import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 import 'package:wolf_3d_gui/screens/difficulty_screen.dart';
 import 'package:wolf_3d_gui/screens/sprite_gallery.dart';
 import 'package:wolf_3d_gui/screens/vga_gallery.dart';
 
+/// Presents the episode list and shortcuts into the asset gallery screens.
 class EpisodeScreen extends StatefulWidget {
+  /// Shared application facade whose active game must already be set.
   final Wolf3d wolf3d;
 
+  /// Creates the episode-selection screen for [wolf3d].
   const EpisodeScreen({super.key, required this.wolf3d});
 
   @override
@@ -21,6 +27,7 @@ class _EpisodeScreenState extends State<EpisodeScreen> {
     widget.wolf3d.audio.playMenuMusic();
   }
 
+  /// Persists the chosen episode in [Wolf3d] and advances to difficulty select.
   void _selectEpisode(int index) {
     widget.wolf3d.setActiveEpisode(index);
     Navigator.of(context).push(

apps/wolf_3d_gui/lib/screens/game_screen.dart

@@ -1,3 +1,6 @@
+/// Active gameplay screen for the Flutter host.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
@@ -6,13 +9,24 @@ import 'package:wolf_3d_flutter/wolf_3d_input_flutter.dart';
 import 'package:wolf_3d_renderer/wolf_3d_ascii_renderer.dart';
 import 'package:wolf_3d_renderer/wolf_3d_flutter_renderer.dart';
 
+/// Owns a [WolfEngine] instance and exposes renderer/input integrations to Flutter.
 class GameScreen extends StatefulWidget {
+  /// Fully parsed game data for the selected version.
   final WolfensteinData data;
+
+  /// Difficulty applied when creating the engine session.
   final Difficulty difficulty;
+
+  /// Episode index used as the starting world.
   final int startingEpisode;
+
+  /// Shared audio backend reused across menu and gameplay screens.
   final EngineAudio audio;
+
+  /// Flutter input adapter that translates widget events into engine input.
   final Wolf3dFlutterInput input;
 
+  /// Creates a gameplay screen with the supplied game session configuration.
   const GameScreen({
     required this.data,
     required this.difficulty,
@@ -55,6 +69,8 @@ class _GameScreenState extends State<GameScreen> {
         onPointerHover: widget.input.onPointerMove,
         child: Stack(
           children: [
+            // Keep both renderers behind the same engine so mode switching does
+            // not reset level state or audio playback.
             _useAsciiMode
                 ? WolfAsciiRenderer(engine: _engine)
                 : WolfFlutterRenderer(engine: _engine),
@@ -80,7 +96,7 @@ class _GameScreenState extends State<GameScreen> {
                 ),
               ),
 
-            // TAB listener
+            // Tab toggles the renderer implementation for quick visual debugging.
             Focus(
               autofocus: true,
               onKeyEvent: (node, event) {
@@ -94,7 +110,8 @@ class _GameScreenState extends State<GameScreen> {
               child: const SizedBox.shrink(),
             ),
 
-            // Loading Overlay
+            // A second full-screen overlay keeps the presentation simple while
+            // the engine is still warming up or decoding the first frame.
             if (!_engine.isInitialized)
               Container(
                 color: Colors.black,

apps/wolf_3d_gui/lib/screens/game_select_screen.dart

@@ -1,11 +1,17 @@
+/// Game-selection screen shown after the GUI host discovers available assets.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
-import 'package:wolf_3d_flutter/wolf_3d.dart';
+import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 import 'package:wolf_3d_gui/screens/episode_screen.dart';
 
+/// Lists every discovered data set and lets the user choose the active one.
 class GameSelectScreen extends StatelessWidget {
+  /// Shared application facade that owns discovered games, audio, and input.
   final Wolf3d wolf3d;
 
+  /// Creates the game-selection screen for the supplied [wolf3d] session.
   const GameSelectScreen({super.key, required this.wolf3d});
 
   @override

apps/wolf_3d_gui/lib/screens/sprite_gallery.dart

@@ -1,12 +1,18 @@
+/// Visual browser for decoded sprite assets and their inferred gameplay roles.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
 import 'package:wolf_3d_dart/wolf_3d_entities.dart';
-import 'package:wolf_3d_flutter/wolf_3d.dart';
+import 'package:wolf_3d_flutter/wolf_3d_flutter.dart';
 import 'package:wolf_3d_renderer/wolf_3d_asset_painter.dart';
 
+/// Displays every sprite frame in the active game along with enemy metadata.
 class SpriteGallery extends StatelessWidget {
+  /// Shared application facade used to access the active game's sprite set.
   final Wolf3d wolf3d;
 
+  /// Creates the sprite gallery for [wolf3d].
   const SpriteGallery({super.key, required this.wolf3d});
 
   bool get isShareware => wolf3d.activeGame.version == GameVersion.shareware;
@@ -29,6 +35,8 @@ class SpriteGallery extends StatelessWidget {
         itemBuilder: (context, index) {
           String label = "Sprite Index: $index";
           for (final enemy in EnemyType.values) {
+            // The gallery infers likely ownership from sprite index ranges so
+            // debugging art packs does not require cross-referencing source.
             if (enemy.claimsSpriteIndex(index, isShareware: isShareware)) {
               final EnemyAnimation? animation = enemy.getAnimationFromSprite(
                 index,

apps/wolf_3d_gui/lib/screens/vga_gallery.dart

@@ -1,10 +1,16 @@
+/// Visual browser for decoded VGA pictures and UI art.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:wolf_3d_dart/wolf_3d_data_types.dart';
 import 'package:wolf_3d_renderer/wolf_3d_asset_painter.dart';
 
+/// Shows each VGA image extracted from the currently selected game data set.
 class VgaGallery extends StatelessWidget {
+  /// Raw VGA images decoded from the active asset pack.
   final List<VgaImage> images;
 
+  /// Creates the gallery for [images].
   const VgaGallery({super.key, required this.images});
 
   @override