Watch Valorant replays in Icarus and capture moments into strategies

.github/workflows/ci.yml

@@ -22,6 +22,55 @@ env:
   PUB_CACHE: ${{ github.workspace }}/.pub-cache
 
 jobs:
+  native-replay:
+    runs-on: ubuntu-latest
+    # Cargo build scripts run here: no write token, none left in .git.
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: native/replay
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # The version in native/replay/rust-toolchain.toml.
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.96.1
+        with:
+          components: clippy, rustfmt
+
+      - name: Cache Cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            native/replay/target
+          key: ${{ runner.os }}-cargo-replay-${{ hashFiles('native/replay/Cargo.lock', 'native/replay/rust-toolchain.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-replay-
+
+      # oozextract is GPL-derived: it must never enter the build
+      # (docs/adr/0006-replay-decoder.md).
+      - name: Keep oozextract out
+        run: |
+          if grep -q oozextract Cargo.lock; then
+            echo "::error::oozextract is in native/replay/Cargo.lock"
+            exit 1
+          fi
+
+      - name: Clippy
+        run: |
+          cargo clippy --locked --all-targets -- -D warnings
+          cargo clippy --locked --all-targets --features dev-vectors -- -D warnings
+
+      - name: Test
+        run: |
+          cargo test --locked
+          cargo test --locked --features dev-vectors
+
   # Decides which lanes a run needs. Every lane runs for manual runs, PRs into
   # main, PRs that change CI itself, and PRs whose files can't be listed.
   # Pushes run every lane but the desktop builds: the release runs the upgrade

.github/workflows/release-desktop.yml

@@ -116,6 +116,13 @@ jobs:
         shell: pwsh
         run: fvm install
 
+      # windows/CMakeLists.txt builds the replay decoder (native/replay) with
+      # cargo, on the version in native/replay/rust-toolchain.toml.
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.96.1
+        with:
+          components: clippy, rustfmt
+
       - name: Build Windows Release Binaries
         shell: pwsh
         env:

.github/workflows/release-store.yml

@@ -59,6 +59,13 @@ jobs:
         shell: pwsh
         run: powershell -ExecutionPolicy Bypass -File scripts/bump_version.ps1 -Bump ${{ inputs.version_bump }}
 
+      # windows/CMakeLists.txt builds the replay decoder (native/replay) with
+      # cargo, on the version in native/replay/rust-toolchain.toml.
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.96.1
+        with:
+          components: clippy, rustfmt
+
       - name: Build Store Package
         shell: pwsh
         env:

CONTEXT.md

@@ -57,6 +57,23 @@ into lineup groups.
 Icarus's zip-based strategy interchange format for import/export of whole
 strategies. Unrelated to video export.
 _Avoid_: archive (ambiguous with library backups)
+
+**Replay**:
+A Valorant match recording (a `.vrf` file) that Valorant downloads from a
+player's career page. Icarus plays it back on the map. Replays are files, not
+part of the library; decoding one only fills a rebuildable cache.
+_Avoid_: demo, VOD, recording
+
+**Perspective**:
+The team a replay is watched from. Its players are allies, the other team's
+are enemies, and its side each round decides which way up the map is drawn.
+_Avoid_: point of view, team view
+
+**Capture**:
+Saving the replay's current moment as a page of a strategy: players, their
+facing, and the utility on the map at that instant.
+_Avoid_: snapshot, export
+
 **Op**:
 One queued change to cloud data. An op lands when the server accepts it.
 Its op ID names that exact change. Changing the intended work creates a new op

docs/adr/0006-replay-decoder.md

@@ -0,0 +1,48 @@
+# 6. Valorant replays are decoded by a native library built on vrfkit
+
+Status: accepted, 2026-10-01
+
+## Context
+
+Valorant writes match replays as `.vrf` files: an Unreal local replay, its
+replication payloads Oodle-compressed and scrambled by a transform Riot
+rotates every patch or two. We spent June and July reverse engineering the
+format in Node (`codex/valorant-replay-file-reverse-engineering`). That work
+proved the layers and decoded movement for build 13.00, but it ran 30 to 300
+seconds per match, knew three builds, and shelled out to Node, which no user
+has installed.
+
+Since then two open-source parsers have caught up and track every patch:
+vrfkit (Rust, Apache-2.0, builds 11.06 to 13.06) and Michel Giehl's
+ValorantReplayParser (C#, MIT, which vrfkit derives from). vrfkit decodes one
+of our 13.00 replays in about a second with no decode errors.
+
+Every open-source Oodle decoder (powzix/ooz and its ports: ooz-wasm,
+oozextract, OozSharp, oozle) is GPL-3.0 or derived from it, including the ones
+labelled MIT. Valorant only uses a narrow Oodle subset: Mermaid/Selkie blocks
+with raw, un-entropy-coded streams.
+
+## Decision
+
+- `native/replay` is a Rust library, loaded over FFI like `native/height`.
+  It depends on vrfkit's library crates pinned to a release tag, with the
+  `oodle` feature off, and vendors the CLI's packet pass with attribution.
+- Its Oodle decoder is our own, written clean-room for the Selkie subset from
+  a facts-only format spec. ooz-derived code never enters the repo or the
+  build. Any block outside the subset fails loudly.
+- The library emits Valorant facts only (subjects, agent UUIDs, class paths,
+  game-world centimetres) in the format described in
+  [`docs/replay-format.md`](../replay-format.md). Mapping those facts onto
+  Icarus agents, abilities and map coordinates is Dart's job, so the decoded
+  document stays readable by code that has never seen our widgets.
+- A replay from an unknown build is refused, never guessed. Keeping up with
+  patches means bumping the vrfkit tag.
+
+## Consequences
+
+- Building the desktop app needs a Rust toolchain on Windows and macOS.
+  Unit tests that do not touch decoding stay pure Dart.
+- New Valorant patches reach users when vrfkit registers the build and we
+  ship a release with the bumped tag. Until then that patch's replays show a
+  clear "not supported yet" state.
+- The same crate can compile to WASM if the web app ever decodes replays.