Feature: Deep SAGE Replay Parser & Rich Match Inspection UI

[undead2146]

Overview & Motivation

Currently, GenHub includes basic replay header and CRC detection (PR #422), but lacks a comprehensive, deep binary replay parser and a rich match inspection UI.

This feature will implement a pure C# SAGE .rep body packet parser, match outcome analyzer, and modern Avalonia inspection view inspired by the match details layout from GameReplays and research across leading community replay decoders.

---

Investigation of Community Implementations

1. rhaivorn/replay-info

   • Winner & Match Outcome Determination: Extracts player quit/self-destruct message indices (e.g., messages 27, 1001-1097), tracks last CRC sync frames, checks for idle kicks and disconnects, and evaluates the true match winner/loser across teams and FFA formats.
   • PRNG Tracking (prng.py): Simulates the SAGE engine's deterministic pseudo-random number generator to follow randomized events and match state changes.
   • Match Configuration: Parses the SAGE game options string (M=, S=, H=, SC=, CH=, SR=, G=, O=) for map dimensions, starting cash, camera height, slot settings, colors, and player factions/armies.

2. dsalzner/cnc-generals-replay-parser

   • Packet & Order Stream Parsing: Decodes low-level binary command packets for Zero Hour (unit creations, building construction, move commands, multi-unit selections, attack orders).
   • Action & Build Timeline: Traces build sequences over time, unit queue arrival estimates, and command frequencies.

3. drag0nD/generals-replay-parser

   • Winner Check & Replay Analysis Pipeline (parseV2.py, check_winner.py): Demonstrates offline batch processing, statistical aggregation, filtering corrupted/AI replays, and calculating player performance metrics.

---

UI & UX Specification (Match Details View)

Based on modern match detail designs (such as GameReplays):

• Hero Banner / Header:
  • Match Title (e.g., [AS][🛡️] 4 VS 4 50K No Rules)
  • Map Preview Thumbnail with Map Name (e.g., Destruction Station) and starting spawn positions.
• Match Summary Grid:
  • Game Version (e.g., 082826_QFE1) & Data Pack (e.g., Community Patch 1.0.1)
  • Match Type (e.g., 1v1, 2v2, 3v3, 4v4, FFA)
  • Duration (e.g., 34m 32s)
  • Date & Time Played (e.g., Aug 30, 2026 19:13 – 19:47 GMT)
  • Starting Cash (e.g., $50,000)
  • Camera Height (e.g., 510)
• Teams & Players Breakdown:
  • Segmented tables per team (Team 1, Team 2, etc.)
  • Player Row:
    • Expandable arrow for detailed player stats
    • Player Name & color indicator
    • Faction / General Army badge (e.g., GLA, USA Airforce, China Infantry, GLA Demo, USA Super Weapon, USA Laser, China Tank)
    • Outcome Badge (Won in green, Lost in red, Observer)
    • Individual player replay download / export action
• Expanded Player Drawer / Tabs:
  • Actions Per Minute (APM) and total command count
  • Build Order Timeline: Chronological queue of buildings, upgrades, and units
  • Chat Log: In-game chat transcript with timestamps and channel indicators (All / Team)

---

Technical Architecture & Requirements

1. IReplayParserService & Packet Decoder (GenHub.Core/Interfaces/Tools/ReplayManager/):

   • Parse GENREP binary chunk stream into strongly typed frame packets (ReplayPacket, CommandPacket).
   • Decode order types (move, attack, construct, train unit, trigger special power, surrender/self-destruct).
   • Compute player APM, effective action frequency, and command distribution.

2. Outcome & Winner Determination Engine:

   • C# port of the community winner detection algorithm:
     • Scan for self-destruct packets (Type 1003 / 1058 / quit frames).
     • Track remaining active players per team across the timeline.
     • Detect desync frames, disconnected players, and idle kicks.
     • Assign MatchResult (Won, Lost, Draw, Desync, NoResult).

3. Replay Viewer Dialog & Inspection ViewModel (GenHub/Features/Tools/ReplayManager/):

   • ReplayInspectionViewModel and ReplayInspectionWindow.axaml (or integrated split-pane inspector).
   • Async background parsing with cancellation support and progress reporting.
   • Dynamic theme binding via semantic tokens (ThemeResources.axaml).

4. Unit & Integration Tests (GenHub.Tests.Core):

   • Full test suite covering 1v1, 2v2, 4v4, FFA, surrender mid-game, disconnect, and desync replay files.

---

Acceptance Criteria

• Complete binary replay stream parser implemented in C# adhering to GenHub's OperationResult<T> pattern.
• Winner, loser, and match duration correctly resolved for standard and custom maps.
• Match options extracted: starting cash, camera height, rules, seed, map size, and game version.
• Avalonia UI matches the GameReplays-style overview: map preview, hero metadata grid, team tables with faction badges, and Won/Lost badges.
• Expandable details for APM, build orders, and in-game chat.
• Clean asynchronous parsing without blocking UI threads.
• Comprehensive unit test coverage for replay packet decoding and winner evaluation.

[coderabbitai]

Coding Plan

Summary

Build the domain contract first: format constants, GeneralFaction/MatchResult enums, and rich ReplayMetadata/packet/player models with a progress POCO.

Implement IReplayParserService/ReplayParserService using OperationResult<T>, IProgress<ReplayParseProgress>, and CancellationToken, with defensive bounds checks and untrusted-input budgets modeled on the TGA parsers and ZIP validators.

Determine outcomes with a heuristic winner engine (quit/self-destruct, per-team active tracking, desync/disconnect detection) and defer PRNG simulation behind the stable contract.

Add a standalone ReplayInspectionWindow with hero banner, summary grid, team tables, faction/outcome badges, and expandable APM/build-order/chat drawers, then enable the existing PARSE button; cover all scenarios with a new ReplayFixtures builder and unit tests.

Design Choices

Design Choice 1: Winner and outcome engine handling of uncertain packet semantics

Options Considered:

1. Implement a full PRNG simulation (port of prng.py) to follow deterministic events precisely.
2. Implement heuristic winner determination from quit/self-destruct/last-CRC-sync markers plus per-team active-player tracking, and add Desync/NoResult fallbacks.

Chosen Option: 2

Rationale: Community documentation for SAGE order codes (chat, surrender, special power, 1003, 1058) is empirical and not fully reliable. Some codes cannot be resolved with certainty. Heuristic determination matches the reliability of available format knowledge, avoids high-risk PRNG porting, and still satisfies the MatchResult acceptance criteria. The parser must allow addition of a PRNG module later without changing the public contract.

Design Choice 2: Inspection UI as a separate window or an integrated split-pane

Options Considered:

1. Standalone resizable ReplayInspectionWindow opened from the DataGrid row.
2. Inline detail pane inside ReplayManagerView.

Chosen Option: 1

Rationale: The ticket allows either option. A standalone window follows the existing GameProfileSettingsWindow pattern. It supports tabs and expandable rows without crowding the list view. It keeps the list UI unchanged except for enabling the PARSE action.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Replay Domain Models, Enums, and Format Constants

This phase defines the data contract that the parser produces and the UI consumes. It introduces the binary-format constants, the new enums, and the extended metadata models. Group these together because the parser, engine, and UI all depend on them.

Task 1: Add format constants for the SAGE `.rep` binary layout

Define the magic signature, offsets, and known type codes used by the parser.

• Create GenHub.Core/Constants/ReplayFormatConstants.cs for format-specific values, separate from the file-management values in ReplayManagerConstants.cs.
• Add the "GENREP" magic signature bytes, the game-options string key names (M=, S=, H=, SC=, CH=, SR=, G=, O=), and the known/empirical order type codes documented in research (for example 1047 production, 1049 construction, 1068 move, 1003/1058 selection/quit-related).
• Add a MaxReplayBodySizeBytes (and, if needed, a max-packet-count) budget constant to bound parsing of untrusted .rep files, consistent with the existing MaxReplaySizeBytes convention.
• Add clear comments that several codes are empirical and may need validation against samples.

Task 2: Add `GeneralFaction` and `MatchResult` enums

Introduce the enums required by faction badges and outcome badges.

• Create GenHub.Core/Models/Enums/GeneralFaction.cs with members for the factions listed in the ticket (for example GLA, USAAirforce, ChinaInfantry, GLADemo, USASuperWeapon, USALaser, ChinaTank) plus an Unknown fallback, following the style of GameType.cs.
• Create GenHub.Core/Models/Enums/MatchResult.cs with Won, Lost, Draw, Desync, NoResult, and Observer, following the same enum style.

Task 3: Extend the replay metadata model set

Replace the placeholder metadata with rich, strongly typed models.

• Update GenHub.Core/Models/Tools/ReplayManager/ReplayMetadata.cs to add header fields (game version string in MMddyy_QFE# form, build date, CRC/hash, begin/end timestamps), match-configuration fields (map name, map size/dimensions, starting cash, camera height, seed, rules/options, match type such as 1v1/FFA), duration, and collections of teams/players.
• Create new models in GenHub.Core/Models/Tools/ReplayManager/: ReplayHeader, ReplayPacket, CommandPacket, ReplayPlayerInfo (name, color, GeneralFaction, MatchResult, APM, command count), ReplayTeamInfo, BuildOrderEntry (timestamp, item name, category), and ChatMessage (timestamp, sender, channel All/Team, text).
• Create GenHub.Core/Models/Tools/ReplayManager/ReplayParseProgress.cs as a small POCO with phase, percentage, and current-step fields, following WorkspacePreparationProgress.
• Keep ReplayFile.Metadata as the attachment point for the parsed ReplayMetadata.

🤖 Prompt for AI agents

Implement the data contract for replay parsing: format constants, new enums, and
extended metadata models. This phase has no logic, only types that later phases
depend on.

- Create `GenHub.Core/Constants/ReplayFormatConstants.cs`. Add the `"GENREP"`
magic signature bytes. Add the game-options string key names: `M=`, `S=`, `H=`,
`SC=`, `CH=`, `SR=`, `G=`, `O=`. Add the known and empirical order type codes
(for example `1047` production, `1049` construction, `1068` move, `1003`/`1058`
selection/quit-related). Add a `MaxReplayBodySizeBytes` constant and, if needed,
a max-packet-count constant, to bound parsing of untrusted `.rep` files,
consistent with the existing `MaxReplaySizeBytes` convention. Add comments that
mark empirical codes as requiring validation against samples.

- Create `GenHub.Core/Models/Enums/GeneralFaction.cs` with members for each
faction (for example `GLA`, `USAAirforce`, `ChinaInfantry`, `GLADemo`,
`USASuperWeapon`, `USALaser`, `ChinaTank`) plus an `Unknown` fallback. Follow
the style of `GameType.cs`.

- Create `GenHub.Core/Models/Enums/MatchResult.cs` with members `Won`, `Lost`,
`Draw`, `Desync`, `NoResult`, `Observer`. Follow the same enum style as
`GeneralFaction`.

- Update `GenHub.Core/Models/Tools/ReplayManager/ReplayMetadata.cs` to add:
header fields (game version string in `MMddyy_QFE#` form, build date, CRC/hash,
begin/end timestamps), match-configuration fields (map name, map
size/dimensions, starting cash, camera height, seed, rules/options, match type
such as `1v1`/`FFA`), duration, and collections of teams and players.

- Create new model classes in `GenHub.Core/Models/Tools/ReplayManager/`:
`ReplayHeader`, `ReplayPacket`, `CommandPacket`, `ReplayPlayerInfo` (fields:
name, color, `GeneralFaction`, `MatchResult`, APM, command count),
`ReplayTeamInfo`, `BuildOrderEntry` (fields: timestamp, item name, category),
`ChatMessage` (fields: timestamp, sender, channel All/Team, text).

- Create `GenHub.Core/Models/Tools/ReplayManager/ReplayParseProgress.cs` as a
small POCO with phase, percentage, and current-step fields, following the
pattern of `WorkspacePreparationProgress`.

- Keep `ReplayFile.Metadata` as the attachment point for the parsed
`ReplayMetadata`; do not change its role.

Phase 2: Parser Service, Game-Options Decoder, and Winner Engine

This phase implements the parsing logic behind the new contract. It reads the header, decodes the game-options string, walks the body packet stream, computes APM, and determines the match outcome. Group these because they form one cohesive service.

Task 1: Define the `IReplayParserService` contract

Add the interface that the ViewModel and tests depend on.

• Create GenHub.Core/Interfaces/Tools/ReplayManager/IReplayParserService.cs.
• Expose Task<OperationResult<ReplayMetadata>> ParseReplayAsync(string filePath, IProgress<ReplayParseProgress>? progress = null, CancellationToken cancellationToken = default) and a Stream-based overload to support in-memory test fixtures.
• Mirror the signature conventions of IReplayImportService/IContentOrchestrator.

Task 2: Implement header and game-options parsing

Read the GENREP header and decode the configuration string.

• Create GenHub/Features/Tools/ReplayManager/Services/ReplayParserService.cs.
• Validate the "GENREP" magic signature before further parsing, following the signature-sniffing convention in ZipValidation.cs.
• Read header fields with BinaryReader and explicit bounds checks, following TgaImageParser/TgaParser conventions; return failure with a logged warning on malformed structure.
• Parse the NUL-terminated game-options string into map, slots, starting cash, camera height, seed, and options, using the key names from Task 1.1.
• Reuse or generalize GameVersionHelper QFE logic to normalize and format the embedded game version (082826_QFE1 style).
• Map slot faction values to GeneralFaction and defensively screen extracted player/map name strings before display (per ArchiveEntryName guidance).

Task 3: Implement body packet decoding, APM, build order, and chat

Walk the timestamp/command stream and produce per-player data.

• Decode the body as a sequence of ReplayPacket/CommandPacket items using the framing described in research (time code, chunk code, player, command count, per-command signatures, then arguments), determining packet size from command signatures because there is no length field.
• Attribute commands to players to compute APM and total command count.
• Build a chronological BuildOrderEntry timeline from production/construction/train order codes.
• Extract ChatMessage entries with timestamp and channel where chat codes are identifiable.
• Enforce the MaxReplayBodySizeBytes/packet-count budget and honor CancellationToken; report ReplayParseProgress at phase boundaries.
• On malformed packets, stop body parsing, log a warning, and still return the header/config data already parsed rather than failing the whole operation.

Task 4: Implement the winner/outcome engine

Determine the match result per player and team.

• Add outcome logic inside ReplayParserService (or a private collaborator in the same folder) that scans for quit/self-destruct markers, tracks remaining active players per team across the timeline, and detects disconnects, idle kicks, and desync frames.
• Assign each player a MatchResult and derive the overall match type (1v1, 2v2, 4v4, FFA) from team/slot counts.
• Return Desync/NoResult when the outcome cannot be resolved, per Assumption 1.

Task 5: Register the parser in DI and wire it into the tool

Make the service available to the ViewModel.

• Register AddSingleton<IReplayParserService, ReplayParserService>() in GenHub/Infrastructure/DependencyInjection/ReplayManagerModule.cs, alongside the existing services.
• Inject IReplayParserService into ReplayManagerViewModel via constructor, following the existing DI pattern.

🤖 Prompt for AI agents

Implement the `IReplayParserService` contract and its `ReplayParserService`
implementation, covering header parsing, body packet decoding, and outcome
determination. This phase depends on the models and constants from Phase 1.

- Create `GenHub.Core/Interfaces/Tools/ReplayManager/IReplayParserService.cs`.
Expose `Task<OperationResult<ReplayMetadata>> ParseReplayAsync(string filePath,
IProgress<ReplayParseProgress>? progress = null, CancellationToken
cancellationToken = default)` and a `Stream`-based overload to support in-memory
test fixtures. Mirror the signature conventions of `IReplayImportService` and
`IContentOrchestrator`.

- Create `GenHub/Features/Tools/ReplayManager/Services/ReplayParserService.cs`.
Validate the `"GENREP"` magic signature before further parsing, following the
signature-sniffing convention in `ZipValidation.cs`. Read header fields with
`BinaryReader` and explicit bounds checks, following
`TgaImageParser`/`TgaParser` conventions. Return failure with a logged warning
on malformed structure.

- Parse the NUL-terminated game-options string into map, slots, starting cash,
camera height, seed, and options, using the key names defined in
`ReplayFormatConstants`. Reuse or generalize `GameVersionHelper` QFE logic to
normalize and format the embedded game version (`082826_QFE1` style). Map slot
faction values to `GeneralFaction`. Defensively screen extracted player and map
name strings before display, following `ArchiveEntryName` guidance.

- Decode the body as a sequence of `ReplayPacket`/`CommandPacket` items. Use the
framing: time code, chunk code, player, command count, per-command signatures,
then arguments. Determine packet size from command signatures because there is
no length field. Attribute commands to players to compute APM and total command
count. Build a chronological `BuildOrderEntry` timeline from production,
construction, and train order codes. Extract `ChatMessage` entries with
timestamp and channel where chat codes are identifiable. Enforce the
`MaxReplayBodySizeBytes` and packet-count budgets, and honor
`CancellationToken`. Report `ReplayParseProgress` at phase boundaries. On
malformed packets, stop body parsing, log a warning, and return the
header/config data already parsed instead of failing the whole operation.

- Add outcome logic inside `ReplayParserService`, or in a private collaborator
in the same folder, that scans for quit, self-destruct, and last-CRC-sync
markers, and tracks remaining active players per team across the timeline.
Detect disconnects, idle kicks, and desync frames. Assign each player a
`MatchResult`. Derive the overall match type (`1v1`, `2v2`, `4v4`, `FFA`) from
team and slot counts. Return `Desync` or `NoResult` when the outcome cannot be
resolved.

- Register `AddSingleton<IReplayParserService, ReplayParserService>()` in
`GenHub/Infrastructure/DependencyInjection/ReplayManagerModule.cs`, alongside
the existing services. Inject `IReplayParserService` into
`ReplayManagerViewModel` via constructor, following the existing DI pattern.

Phase 3: Match Inspection UI

This phase adds the inspection window, converters, and the command that opens it. It consumes the parsed ReplayMetadata from Phase 2. Group these because they form the user-facing feature.

Task 1: Add UI converters for badges

Provide color mapping for outcome and faction display.

• Create GenHub/Infrastructure/Converters/MatchResultToBrushConverter.cs following GameTypeToBrushConverter/TrustLevelToColorConverter (static Instance, switch expression, ConvertBack throws).
• Add a faction-to-icon or faction-to-brush mapping for faction badges, following the same converter conventions, or reuse an existing icon lookup if suitable.

Task 2: Implement `ReplayInspectionViewModel`

Drive the inspection window with parsed data and async parsing.

• Create GenHub/Features/Tools/ReplayManager/ViewModels/ReplayInspectionViewModel.cs.
• Accept a ReplayFile, call IReplayParserService.ParseReplayAsync on a background thread, expose parse progress, and surface parsed header/config, team/player collections, and per-player build order, APM, and chat.
• Add IsExpanded plus a ToggleExpandCommand per player row, following the PublisherCardViewModel expand pattern.
• Expose a CloseRequested event and per-player export/download command.

Task 3: Implement `ReplayInspectionWindow`

Present the GameReplays-style layout.

• Create GenHub/Features/Tools/ReplayManager/Views/ReplayInspectionWindow.axaml(.cs) following the GameProfileSettingsWindow pattern (resizable, saved size, CloseRequested wiring, custom header).
• Build the hero banner (match title, map preview thumbnail with spawn positions), the match summary grid (game version, data pack, match type, duration, date/time, starting cash, camera height), and per-team player tables with color indicator, faction badge, and Won/Lost/Observer badge using the converters from Task 3.1.
• Implement the expandable player drawer with APM/command count, build order timeline, and chat log. Use the existing RadioButton/TabButton tab pattern or themed Expander sections, because there is no native TabControl in the codebase.
• Reuse TgaImageParser.LoadTgaThumbnail and the Map Manager map index to resolve the map preview thumbnail on demand.
• Bind colors through semantic theme tokens from ThemeResources.axaml.

Task 4: Enable the PARSE action in the list view

Open the inspection window from the replay list.

• Add a ParseReplayCommand (and a SelectedReplay binding if needed) to ReplayManagerViewModel that constructs a ReplayInspectionViewModel and shows ReplayInspectionWindow, following the DialogService/window-open conventions.
• Update GenHub/Features/Tools/ReplayManager/Views/ReplayManagerView.axaml to enable the currently disabled "PARSE" button, bind it to ParseReplayCommand, and remove the "Coming Soon" tooltip.

🤖 Prompt for AI agents

Implement the match inspection UI that consumes the parsed `ReplayMetadata` from
Phase 2: badge converters, the `ReplayInspectionViewModel`, the
`ReplayInspectionWindow`, and the enabled PARSE action.

- Create `GenHub/Infrastructure/Converters/MatchResultToBrushConverter.cs`
following the pattern of
`GameTypeToBrushConverter`/`TrustLevelToColorConverter`: static `Instance`,
switch expression, `ConvertBack` throws. Add a faction-to-icon or
faction-to-brush mapping for faction badges, following the same converter
conventions, or reuse an existing icon lookup if suitable.

- Create
`GenHub/Features/Tools/ReplayManager/ViewModels/ReplayInspectionViewModel.cs`.
Accept a `ReplayFile`. Call `IReplayParserService.ParseReplayAsync` on a
background thread. Expose parse progress. Surface parsed header/config data,
team and player collections, and per-player build order, APM, and chat. Add an
`IsExpanded` property plus a `ToggleExpandCommand` per player row, following the
`PublisherCardViewModel` expand pattern. Expose a `CloseRequested` event and a
per-player export/download command.

- Create
`GenHub/Features/Tools/ReplayManager/Views/ReplayInspectionWindow.axaml` and its
code-behind, following the `GameProfileSettingsWindow` pattern: resizable, saved
size, `CloseRequested` wiring, custom header. Build the hero banner containing
the match title and a map preview thumbnail with spawn positions. Build the
match summary grid showing game version, data pack, match type, duration,
date/time, starting cash, and camera height. Build per-team player tables with a
color indicator, faction badge, and Won/Lost/Observer badge, using the
converters from the badge task. Implement the expandable player drawer with APM,
command count, build order timeline, and chat log, using the existing
`RadioButton`/`TabButton` tab pattern or themed `Expander` sections, since there
is no native `TabControl` in the codebase. Reuse
`TgaImageParser.LoadTgaThumbnail` and the Map Manager map index to resolve the
map preview thumbnail on demand. Bind colors through semantic theme tokens from
`ThemeResources.axaml`.

- Add a `ParseReplayCommand`, and a `SelectedReplay` binding if needed, to
`ReplayManagerViewModel`. The command must construct a
`ReplayInspectionViewModel` and show the `ReplayInspectionWindow`, following the
`DialogService`/window-open conventions. Update
`GenHub/Features/Tools/ReplayManager/Views/ReplayManagerView.axaml` to enable
the currently disabled "PARSE" button, bind it to `ParseReplayCommand`, and
remove the "Coming Soon" tooltip.

Phase 4: Tests

This phase adds byte-level fixtures and covers parsing, outcome, and the ViewModel. Group these because they validate all prior phases.

Task 1: Add a reusable replay fixture builder

Provide synthetic .rep byte streams for tests.

• Create GenHub.Tests/GenHub.Tests.Core/Infrastructure/ReplayFixtures.cs, following ArchiveFixtures.cs.
• Expose builders that emit a valid minimal GENREP header plus configurable team/player layout and a terminal event (normal end, surrender, disconnect, desync), returning byte[].
• Add offset-patching mutators that produce truncated/corrupted variants for negative tests.

Task 2: Add parser and winner-engine tests

Cover the decoding and outcome logic.

• Create GenHub.Tests/GenHub.Tests.Core/Features/Tools/Services/ReplayParserServiceTests.cs, following the xUnit + Moq + temp-directory conventions in ReplayImportServiceTests.
• Cover 1v1, 2v2, 4v4, FFA, surrender mid-game, disconnect, and desync scenarios by calling a fixture factory per case.
• Assert header fields, extracted config (starting cash, camera height, seed, map size, game version), computed duration, APM, build order, chat, and MatchResult.
• Add malformed-input tests that assert graceful failure or partial-header return, and a cancellation test using an IProgress<ReplayParseProgress> that cancels mid-parse, asserting OperationCanceledException.

Task 3: Add inspection ViewModel tests

Verify UI-facing behavior.

• Create GenHub.Tests/GenHub.Tests.Core/Features/Tools/ViewModels/ReplayInspectionViewModelTests.cs.
• Mock IReplayParserService with Moq and assert that parsed data populates the team/player collections, that progress updates surface, and that the row expand command toggles IsExpanded.

🤖 Prompt for AI agents

Add byte-level fixtures and test coverage for the parser, the winner engine, and
the inspection ViewModel, validating all prior phases.

- Create `GenHub.Tests/GenHub.Tests.Core/Infrastructure/ReplayFixtures.cs`,
following the pattern of `ArchiveFixtures.cs`. Expose builders that emit a valid
minimal `GENREP` header plus a configurable team/player layout and a terminal
event (normal end, surrender, disconnect, desync), returning `byte[]`. Add
offset-patching mutators that produce truncated or corrupted variants for
negative tests.

- Create
`GenHub.Tests/GenHub.Tests.Core/Features/Tools/Services/ReplayParserServiceTests.cs`,
following the xUnit and Moq temp-directory conventions used in
`ReplayImportServiceTests`. Cover 1v1, 2v2, 4v4, FFA, surrender mid-game,
disconnect, and desync scenarios by calling a fixture factory per case. Assert
header fields, extracted config values (starting cash, camera height, seed, map
size, game version), computed duration, APM, build order, chat, and
`MatchResult`. Add malformed-input tests that assert graceful failure or
partial-header return. Add a cancellation test using an
`IProgress<ReplayParseProgress>` that cancels mid-parse, asserting
`OperationCanceledException`.

- Create
`GenHub.Tests/GenHub.Tests.Core/Features/Tools/ViewModels/ReplayInspectionViewModelTests.cs`.
Mock `IReplayParserService` with Moq. Assert that parsed data populates the team
and player collections. Assert that progress updates surface correctly. Assert
that the row expand command toggles `IsExpanded`.

Research

GenHub organizes tools under Features/Tools/<ToolName>/ with interfaces and models split into GenHub.Core. The ReplayManager tool currently supports file import, export, upload, delete, and list only. ReplayMetadata is an empty placeholder that is never populated. The UI has a disabled "PARSE" button labeled "Coming Soon".

There is no replay binary parser, no format constants, no faction or match-result enums, and no detail or inspection view. Services follow the OperationResult<T> pattern with optional IProgress<T> and a trailing CancellationToken.

Binary parsing conventions come from TgaParser and TgaImageParser. These conventions require bounds checks, return null on malformed data, and log a warning.

DI registration follows the pattern in ReplayManagerModule.cs and MapManagerModule.cs. Dialogs and windows follow the DialogService and GameProfileSettingsWindow patterns.

Tests use xUnit and Moq with temp directories. ArchiveFixtures.cs is the template for byte-level fixtures.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the data contract for replay parsing: format constants, new enums, and
extended metadata models. This phase has no logic, only types that later phases
depend on.

- Create `GenHub.Core/Constants/ReplayFormatConstants.cs`. Add the `"GENREP"`
magic signature bytes. Add the game-options string key names: `M=`, `S=`, `H=`,
`SC=`, `CH=`, `SR=`, `G=`, `O=`. Add the known and empirical order type codes
(for example `1047` production, `1049` construction, `1068` move, `1003`/`1058`
selection/quit-related). Add a `MaxReplayBodySizeBytes` constant and, if needed,
a max-packet-count constant, to bound parsing of untrusted `.rep` files,
consistent with the existing `MaxReplaySizeBytes` convention. Add comments that
mark empirical codes as requiring validation against samples.

- Create `GenHub.Core/Models/Enums/GeneralFaction.cs` with members for each
faction (for example `GLA`, `USAAirforce`, `ChinaInfantry`, `GLADemo`,
`USASuperWeapon`, `USALaser`, `ChinaTank`) plus an `Unknown` fallback. Follow
the style of `GameType.cs`.

- Create `GenHub.Core/Models/Enums/MatchResult.cs` with members `Won`, `Lost`,
`Draw`, `Desync`, `NoResult`, `Observer`. Follow the same enum style as
`GeneralFaction`.

- Update `GenHub.Core/Models/Tools/ReplayManager/ReplayMetadata.cs` to add:
header fields (game version string in `MMddyy_QFE#` form, build date, CRC/hash,
begin/end timestamps), match-configuration fields (map name, map
size/dimensions, starting cash, camera height, seed, rules/options, match type
such as `1v1`/`FFA`), duration, and collections of teams and players.

- Create new model classes in `GenHub.Core/Models/Tools/ReplayManager/`:
`ReplayHeader`, `ReplayPacket`, `CommandPacket`, `ReplayPlayerInfo` (fields:
name, color, `GeneralFaction`, `MatchResult`, APM, command count),
`ReplayTeamInfo`, `BuildOrderEntry` (fields: timestamp, item name, category),
`ChatMessage` (fields: timestamp, sender, channel All/Team, text).

- Create `GenHub.Core/Models/Tools/ReplayManager/ReplayParseProgress.cs` as a
small POCO with phase, percentage, and current-step fields, following the
pattern of `WorkspacePreparationProgress`.

- Keep `ReplayFile.Metadata` as the attachment point for the parsed
`ReplayMetadata`; do not change its role.
===============================================================================

Task: 2

Implement the `IReplayParserService` contract and its `ReplayParserService`
implementation, covering header parsing, body packet decoding, and outcome
determination. This phase depends on the models and constants from Phase 1.

- Create `GenHub.Core/Interfaces/Tools/ReplayManager/IReplayParserService.cs`.
Expose `Task<OperationResult<ReplayMetadata>> ParseReplayAsync(string filePath,
IProgress<ReplayParseProgress>? progress = null, CancellationToken
cancellationToken = default)` and a `Stream`-based overload to support in-memory
test fixtures. Mirror the signature conventions of `IReplayImportService` and
`IContentOrchestrator`.

- Create `GenHub/Features/Tools/ReplayManager/Services/ReplayParserService.cs`.
Validate the `"GENREP"` magic signature before further parsing, following the
signature-sniffing convention in `ZipValidation.cs`. Read header fields with
`BinaryReader` and explicit bounds checks, following
`TgaImageParser`/`TgaParser` conventions. Return failure with a logged warning
on malformed structure.

- Parse the NUL-terminated game-options string into map, slots, starting cash,
camera height, seed, and options, using the key names defined in
`ReplayFormatConstants`. Reuse or generalize `GameVersionHelper` QFE logic to
normalize and format the embedded game version (`082826_QFE1` style). Map slot
faction values to `GeneralFaction`. Defensively screen extracted player and map
name strings before display, following `ArchiveEntryName` guidance.

- Decode the body as a sequence of `ReplayPacket`/`CommandPacket` items. Use the
framing: time code, chunk code, player, command count, per-command signatures,
then arguments. Determine packet size from command signatures because there is
no length field. Attribute commands to players to compute APM and total command
count. Build a chronological `BuildOrderEntry` timeline from production,
construction, and train order codes. Extract `ChatMessage` entries with
timestamp and channel where chat codes are identifiable. Enforce the
`MaxReplayBodySizeBytes` and packet-count budgets, and honor
`CancellationToken`. Report `ReplayParseProgress` at phase boundaries. On
malformed packets, stop body parsing, log a warning, and return the
header/config data already parsed instead of failing the whole operation.

- Add outcome logic inside `ReplayParserService`, or in a private collaborator
in the same folder, that scans for quit, self-destruct, and last-CRC-sync
markers, and tracks remaining active players per team across the timeline.
Detect disconnects, idle kicks, and desync frames. Assign each player a
`MatchResult`. Derive the overall match type (`1v1`, `2v2`, `4v4`, `FFA`) from
team and slot counts. Return `Desync` or `NoResult` when the outcome cannot be
resolved.

- Register `AddSingleton<IReplayParserService, ReplayParserService>()` in
`GenHub/Infrastructure/DependencyInjection/ReplayManagerModule.cs`, alongside
the existing services. Inject `IReplayParserService` into
`ReplayManagerViewModel` via constructor, following the existing DI pattern.
===============================================================================

Task: 3

Implement the match inspection UI that consumes the parsed `ReplayMetadata` from
Phase 2: badge converters, the `ReplayInspectionViewModel`, the
`ReplayInspectionWindow`, and the enabled PARSE action.

- Create `GenHub/Infrastructure/Converters/MatchResultToBrushConverter.cs`
following the pattern of
`GameTypeToBrushConverter`/`TrustLevelToColorConverter`: static `Instance`,
switch expression, `ConvertBack` throws. Add a faction-to-icon or
faction-to-brush mapping for faction badges, following the same converter
conventions, or reuse an existing icon lookup if suitable.

- Create
`GenHub/Features/Tools/ReplayManager/ViewModels/ReplayInspectionViewModel.cs`.
Accept a `ReplayFile`. Call `IReplayParserService.ParseReplayAsync` on a
background thread. Expose parse progress. Surface parsed header/config data,
team and player collections, and per-player build order, APM, and chat. Add an
`IsExpanded` property plus a `ToggleExpandCommand` per player row, following the
`PublisherCardViewModel` expand pattern. Expose a `CloseRequested` event and a
per-player export/download command.

- Create
`GenHub/Features/Tools/ReplayManager/Views/ReplayInspectionWindow.axaml` and its
code-behind, following the `GameProfileSettingsWindow` pattern: resizable, saved
size, `CloseRequested` wiring, custom header. Build the hero banner containing
the match title and a map preview thumbnail with spawn positions. Build the
match summary grid showing game version, data pack, match type, duration,
date/time, starting cash, and camera height. Build per-team player tables with a
color indicator, faction badge, and Won/Lost/Observer badge, using the
converters from the badge task. Implement the expandable player drawer with APM,
command count, build order timeline, and chat log, using the existing
`RadioButton`/`TabButton` tab pattern or themed `Expander` sections, since there
is no native `TabControl` in the codebase. Reuse
`TgaImageParser.LoadTgaThumbnail` and the Map Manager map index to resolve the
map preview thumbnail on demand. Bind colors through semantic theme tokens from
`ThemeResources.axaml`.

- Add a `ParseReplayCommand`, and a `SelectedReplay` binding if needed, to
`ReplayManagerViewModel`. The command must construct a
`ReplayInspectionViewModel` and show the `ReplayInspectionWindow`, following the
`DialogService`/window-open conventions. Update
`GenHub/Features/Tools/ReplayManager/Views/ReplayManagerView.axaml` to enable
the currently disabled "PARSE" button, bind it to `ParseReplayCommand`, and
remove the "Coming Soon" tooltip.
===============================================================================

Task: 4

Add byte-level fixtures and test coverage for the parser, the winner engine, and
the inspection ViewModel, validating all prior phases.

- Create `GenHub.Tests/GenHub.Tests.Core/Infrastructure/ReplayFixtures.cs`,
following the pattern of `ArchiveFixtures.cs`. Expose builders that emit a valid
minimal `GENREP` header plus a configurable team/player layout and a terminal
event (normal end, surrender, disconnect, desync), returning `byte[]`. Add
offset-patching mutators that produce truncated or corrupted variants for
negative tests.

- Create
`GenHub.Tests/GenHub.Tests.Core/Features/Tools/Services/ReplayParserServiceTests.cs`,
following the xUnit and Moq temp-directory conventions used in
`ReplayImportServiceTests`. Cover 1v1, 2v2, 4v4, FFA, surrender mid-game,
disconnect, and desync scenarios by calling a fixture factory per case. Assert
header fields, extracted config values (starting cash, camera height, seed, map
size, game version), computed duration, APM, build order, chat, and
`MatchResult`. Add malformed-input tests that assert graceful failure or
partial-header return. Add a cancellation test using an
`IProgress<ReplayParseProgress>` that cancels mid-parse, asserting
`OperationCanceledException`.

- Create
`GenHub.Tests/GenHub.Tests.Core/Features/Tools/ViewModels/ReplayInspectionViewModelTests.cs`.
Mock `IReplayParserService` with Moq. Assert that parsed data populates the team
and player collections. Assert that progress updates surface correctly. Assert
that the row expand command toggles `IsExpanded`.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---