diff --git a/.github/prompts/plan-logoReverseEngineeringAvaloniaPlayer.prompt.md b/.github/prompts/plan-logoReverseEngineeringAvaloniaPlayer.prompt.md new file mode 100644 index 0000000..dfdcfc6 --- /dev/null +++ b/.github/prompts/plan-logoReverseEngineeringAvaloniaPlayer.prompt.md @@ -0,0 +1,86 @@ +## Plan: Full LOGO Reverse Engineering And Independent Avalonia Player + +Deliver a complete understanding of LOGO.EXE and LOGO.HNM by combining static analysis, runtime tracing with Spice86 MCP using UseCodeOverride false, and deterministic data extraction using the UnHsq workflow, then build a standalone Avalonia 11.2.x MVVM player that reproduces playback behavior without emulator dependencies. For MCP, rely primarily on CFG CPU graph analysis (`read_cfg_cpu_graph`) and use other MCP tools as supporting evidence. + +**Steps** +1. Phase 1 - Ground truth setup and reproducibility +1.0 Execution precedence for this plan: complete Phase 1 and steps 2.1-2.3 before executing step 3.3 and later dynamic trace steps. +1.1 Verify exact inputs and hashes for LOGO.EXE and LOGO.HNM, then lock a reproducible baseline run profile with emulator overrides disabled (UseCodeOverride false). +1.2 Produce a run manifest that records CLI options, Spice86 version, MCP endpoint and ports, and capture locations for traces and screenshots. +1.3 Define canonical playback checkpoints (for example first frame, palette transition points, end frame, early keypress exit path) to compare all future outputs against. + +2. Phase 2 - Artifact preparation and static inventory (2.1-2.3 precede 3.3+, and 2.4 overlaps with Phase 3) +2.1 Decompress LOGO.HNM with the existing UnHsq tool workflow and generate LOGO.UNHSQ as the primary offline artifact. +2.2 Build binary maps for both LOGO.HNM and LOGO.UNHSQ: offsets, repeating patterns, candidate headers, candidate frame boundaries, and entropy regions. +2.3 Create a function inventory from existing dump files and generated code references: startup path, file I/O handlers, decompression path, VGA palette writes, frame blit path, and keyboard polling path. +2.4 Tag unknown functions by role hypotheses and confidence levels so dynamic tracing can explicitly confirm or reject each hypothesis. + +3. Phase 3 - Dynamic behavior tracing via Spice86 MCP with no override code (starts after 2.1-2.3; overlaps only with 2.4) +3.0 MCP priority: use CFG CPU graph (`read_cfg_cpu_graph`) as the primary discovery and control-flow truth source; treat disassembly, memory reads, and screenshots as secondary validation signals. +3.1 Start Spice86 MCP and run LOGO.EXE with UseCodeOverride false to observe original behavior only. +3.1.1 Capture CFG snapshots over time (startup, first decode loop, mid-playback, termination) and diff them to identify newly activated nodes/edges. +3.1.2 Cluster CFG nodes into behavior regions (file I/O, decode, palette, blit, input polling) before deep-diving with any other MCP tool. +3.2 Capture baseline CPU and DOS state at entry, before file open, during each file read, during decode, and during render loops. +3.3 Add execution breakpoints around known hot addresses from dump files and around interrupt handlers (INT 21h and INT 10h paths) to capture call chronology. +3.4 At each read/decode/render step, use CFG-selected hotspots first, then snapshot memory ranges used as source and destination buffers; correlate with file offsets to reconstruct data flow. +3.5 Capture VGA DAC palette state and periodic screenshots across timeline checkpoints; store paired evidence with cycle counts. +3.6 Build a chronological event ledger: read chunk, decode call, palette load, frame presentation, keyboard check, loop control decision. + +4. Phase 4 - Reconstruction and complete specification (depends on 2 and 3) +4.1 Produce an executable behavior spec for LOGO.EXE: startup, resource open, decode loop, render loop, input handling, and termination state machine. +4.2 Produce a binary format spec for LOGO.HNM and LOGO.UNHSQ: header schema, chunk types, frame payload encoding, palette encoding, timing semantics, and termination markers. +4.3 Resolve all previously unknown high-impact functions by mapping each to a named responsibility and documented side effects. +4.4 Validate spec completeness by replaying full animation from spec-derived parser outputs and confirming all playback-critical bytes are explained; any non-critical unknown regions are explicitly documented. + +5. Phase 5 - Standalone player architecture and implementation plan (depends on 4) +5.1 Create a separate desktop app architecture with clear layers: format parser, decode pipeline, playback engine, and Avalonia MVVM presentation. +5.2 Define domain models: container metadata, frame descriptor, palette command stream, decoded frame surface, and playback cursor/timing model. +5.3 Implement parser and decoder as pure library components with deterministic outputs and no UI dependencies. +5.4 Implement playback engine that reproduces original sequencing rules: frame cadence, palette transition timing, key interrupt semantics, and end-of-stream behavior. +5.5 Build Avalonia 11.2.x MVVM app shell with controls for open/play/pause/stop/seek/frame-step, timeline state, and diagnostics panel for frame and palette indices. +5.6 Integrate pixel pipeline for indexed-color rendering and palette application to display frame-accurate output. + +6. Phase 6 - Parity validation and hardening (depends on 5) +6.1 Create golden baseline set from Spice86 run: selected screenshots, palette snapshots, and event timestamps. +6.2 Compare standalone output against baseline at checkpoints: frame content parity (pixel diff = 0 at checkpoint frames), palette parity (byte-exact DAC values), ordering parity (identical checkpoint sequence), and total playback duration tolerance (within +/-50 ms). +6.3 Test edge paths: malformed inputs, truncated file, unexpected markers, and user interruption behavior. +6.4 Document residual differences if any and classify as intentional, acceptable variance, or bug. + +7. Phase 7 - Documentation and handoff (depends on 6) +7.1 Write reverse engineering dossier with evidence links from each behavioral claim to static and dynamic proof. +7.2 Write format specification document for LOGO.HNM and LOGO.UNHSQ suitable for independent implementation. +7.3 Write developer guide for the standalone player architecture, extension points, and verification workflow. +7.4 Publish a repeatable validation checklist so future refactors preserve parity with original LOGO.EXE behavior. + +**Relevant files** +- c:/Users/noalm/source/repos/LOGO/README.md — baseline behavior narrative and run entry guidance. +- c:/Users/noalm/source/repos/LOGO/Program.cs — current Spice86 launch entry point and checksum guard. +- c:/Users/noalm/source/repos/LOGO/CodeGeneratorConfig.json — known injection and event-check anchor addresses useful for trace waypoints. +- c:/Users/noalm/source/repos/LOGO/GeneratedCode.cs — current manually lifted behavior reference for naming and semantic hints. +- c:/Users/noalm/source/repos/LOGO/GeneratedCode_OriginalAsm.cs — closest generated representation of original executable control flow. +- c:/Users/noalm/source/repos/LOGO/spice86dumpExecutionFlow.json — observed execution graph and path coverage hints. +- c:/Users/noalm/source/repos/LOGO/spice86dumpFunctionsDetails.txt — callers/callees/return contract map for prioritizing investigation. +- c:/Users/noalm/source/repos/LOGO/spice86dumpGhidraSymbols.txt — symbol naming anchors for mapping unknown functions. +- c:/Users/noalm/source/repos/LOGO/tools/UnHsq/Program.cs — authoritative HSQ decompression implementation already used in this repo. +- c:/Users/noalm/source/repos/LOGO/.github/skills/dune-dat-and-hsq-decompression/SKILL.md — required decompression workflow and reporting discipline. +- c:/Users/noalm/source/repos/LOGO/.github/skills/spice86-mcp/SKILL.md — MCP handshake and tool usage requirements. +- c:/Users/noalm/source/repos/LOGO/.github/instructions/reverse-engineering.instructions.md — evidence-first and contract-preservation rules. +- Primary MCP tool emphasis: `read_cfg_cpu_graph` for coverage-first analysis, then `read_disassembly` / `read_memory` for node-level validation. + +**Verification** +1. Reproducibility check: two independent runs with UseCodeOverride false produce the same event ledger structure and equivalent frame checkpoint outputs. +2. Format coverage check: parser can account for all bytes in LOGO.HNM and LOGO.UNHSQ relevant to playback, with unknown regions explicitly documented. +3. Behavioral parity check: standalone player matches checkpoint screenshots and palette states from Spice86 with checkpoint pixel diff = 0, byte-exact palette values, and total playback duration within +/-50 ms. +4. Control-flow completeness check: all high-frequency runtime functions in dump data have assigned semantic roles and evidence citations. +5. Robustness check: corrupted and truncated input cases fail gracefully with deterministic errors. + +**Decisions** +- Included scope: full reverse-engineering of playback path and complete standalone playback implementation for logo.hnm. +- Included scope: no dependency on Spice86 or override code at runtime for the final player. +- Excluded scope: adding new emulator features inside Spice86 itself. +- Excluded scope: broad Dune engine reverse engineering outside LOGO.EXE and logo.hnm playback concerns. + +**Further Considerations** +1. Timing fidelity default: dual mode with switchable timing profile; default runtime mode is strict original cadence emulation. +2. Packaging default: produce both self-contained and framework-dependent builds using a CI matrix. +3. Decoder strategy default: strict by default with an explicit optional recovery mode for damaged files. diff --git a/LOGO.EXE b/LOGO.EXE new file mode 100644 index 0000000..3f1598e Binary files /dev/null and b/LOGO.EXE differ diff --git a/LOGO.HNM b/LOGO.HNM new file mode 100644 index 0000000..43d9d4a Binary files /dev/null and b/LOGO.HNM differ