feat: complete 8bpp blit — color-table LUT, additive & subtractive modes

Port all remaining 8bpp blend modes in the core sprite blit hook:
- Mode 1 with non-null color_table pointer now passes the LUT through
instead of falling back to native WA
- Mode 2 (additive mask): write src where both src and dst are non-zero
- Mode 3 (subtractive mask): write src where src non-zero and dst is zero
- Update color_table parameter type from u32 to *const u8 (FFI style)
- Snapshot capture now uses ORIG_BLIT to call unhooked native function

34 tests (up from 25): 5 new unit tests + 4 new snapshot tests verified
byte-exact against native WA output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crates/openwa-core/src/display/sprite_blit.rs

@@ -98,9 +98,11 @@ pub enum BlitBlend {
     /// Color-table blend — each source pixel is remapped through a 256-byte LUT.
     /// If `color_table` is None, uses direct copy with transparency.
     ColorTable,
-    /// Additive color mix — source pixel index used as a fixed-point X scale.
+    /// Additive mask — copy source pixel only where both src and dst are non-zero.
+    /// Used for overlay effects (paint only on existing content).
     Additive,
-    /// Subtractive color mix.
+    /// Subtractive mask — copy source pixel only where src is non-zero and dst is zero.
+    /// Used for gap-fill effects (paint only where destination is empty).
     Subtractive,
 }
 
@@ -237,10 +239,64 @@ pub fn blit_sprite_rect(
             }
         }
         BlitBlend::Additive => {
-            // TODO: port additive blend
+            // WA's mode 2: forward scan only (orientation ignored in inner loop).
+            let (sx_start, sy_start) = adjust_source_for_clip(
+                BlitOrientation::Normal,
+                src_x,
+                src_y,
+                dst_x,
+                dst_y,
+                width,
+                height,
+                vis_left,
+                vis_top,
+                vis_right,
+                vis_bottom,
+            );
+            blit_masked(
+                dst,
+                src,
+                vis_left,
+                vis_top,
+                vis_w,
+                vis_h,
+                sx_start,
+                sy_start,
+                |s, d| {
+                    // Write src where both src and dst are non-zero
+                    s != 0 && d != 0
+                },
+            );
         }
         BlitBlend::Subtractive => {
-            // TODO: port subtractive blend
+            // WA's mode 3: forward scan only (orientation ignored in inner loop).
+            let (sx_start, sy_start) = adjust_source_for_clip(
+                BlitOrientation::Normal,
+                src_x,
+                src_y,
+                dst_x,
+                dst_y,
+                width,
+                height,
+                vis_left,
+                vis_top,
+                vis_right,
+                vis_bottom,
+            );
+            blit_masked(
+                dst,
+                src,
+                vis_left,
+                vis_top,
+                vis_w,
+                vis_h,
+                sx_start,
+                sy_start,
+                |s, d| {
+                    // Write src where src is non-zero and dst is zero
+                    s != 0 && d == 0
+                },
+            );
         }
     }
 
@@ -434,6 +490,43 @@ fn blit_color_table_swapped(
     }
 }
 
+/// Masked blit — forward scan only (no orientation).
+///
+/// Copies source pixels to destination where the predicate `should_write(src, dst)` is true.
+/// Used by modes 2 (additive) and 3 (subtractive).
+fn blit_masked(
+    dst: &mut PixelGrid,
+    src: &BlitSource,
+    vis_left: i32,
+    vis_top: i32,
+    vis_w: i32,
+    vis_h: i32,
+    sx_start: i32,
+    sy_start: i32,
+    should_write: impl Fn(u8, u8) -> bool,
+) {
+    let dst_stride = dst.row_stride as usize;
+    let src_stride = src.row_stride as usize;
+
+    let mut sy = sy_start;
+    for dy in 0..vis_h {
+        let dst_row = (vis_top + dy) as usize * dst_stride + vis_left as usize;
+        let src_row = sy as usize * src_stride;
+
+        let mut sx = sx_start;
+        for dx in 0..vis_w {
+            let src_pixel = src.data[src_row + sx as usize];
+            let dst_pixel = dst.data[dst_row + dx as usize];
+            if should_write(src_pixel, dst_pixel) {
+                dst.data[dst_row + dx as usize] = src_pixel;
+            }
+            sx += 1;
+        }
+
+        sy += 1;
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Test sprite creation from images
 // ---------------------------------------------------------------------------
@@ -708,6 +801,198 @@ mod tests {
         assert_eq!(p(4, 3), 99, "transparent pixel preserved background");
     }
 
+    #[test]
+    fn blit_color_table_lut_remaps_pixels() {
+        // Verify that a non-identity LUT actually remaps pixel values.
+        let sprite = make_test_sprite(); // quadrants: TL=1, TR=2, BL=3, BR=4
+        let src = BlitSource::from(&sprite);
+        let mut dst = PixelGrid::new(16, 16);
+        dst.data.fill(99); // background
+
+        // LUT: remap 1->10, 2->20, 3->30, 4->40, 0->0 (transparent)
+        let mut lut = [0u8; 256];
+        lut[1] = 10;
+        lut[2] = 20;
+        lut[3] = 30;
+        lut[4] = 40;
+
+        blit_sprite_rect(
+            &mut dst,
+            &src,
+            4,
+            4,
+            8,
+            8,
+            0,
+            0,
+            Some(&lut),
+            BlitOrientation::Normal,
+            BlitBlend::ColorTable,
+        );
+
+        let p = |x: i32, y: i32| dst.data[(y as u32 * dst.row_stride + x as u32) as usize];
+        assert_eq!(p(4, 4), 10, "TL remapped 1->10");
+        assert_eq!(p(8, 4), 20, "TR remapped 2->20");
+        assert_eq!(p(4, 8), 30, "BL remapped 3->30");
+        assert_eq!(p(8, 8), 40, "BR remapped 4->40");
+        // Background outside sprite preserved
+        assert_eq!(p(3, 4), 99, "background unchanged");
+    }
+
+    #[test]
+    fn blit_color_table_lut_with_mirror() {
+        let sprite = make_test_sprite();
+        let src = BlitSource::from(&sprite);
+        let mut dst = PixelGrid::new(16, 16);
+
+        let mut lut = [0u8; 256];
+        lut[1] = 10;
+        lut[2] = 20;
+        lut[3] = 30;
+        lut[4] = 40;
+
+        blit_sprite_rect(
+            &mut dst,
+            &src,
+            4,
+            4,
+            8,
+            8,
+            0,
+            0,
+            Some(&lut),
+            BlitOrientation::MirrorX,
+            BlitBlend::ColorTable,
+        );
+
+        let p = |x: i32, y: i32| dst.data[(y as u32 * dst.row_stride + x as u32) as usize];
+        // MirrorX flips left/right: TL<->TR, BL<->BR
+        assert_eq!(p(4, 4), 20, "mirror: TR->TL remapped 2->20");
+        assert_eq!(p(8, 4), 10, "mirror: TL->TR remapped 1->10");
+        assert_eq!(p(4, 8), 40, "mirror: BR->BL remapped 4->40");
+        assert_eq!(p(8, 8), 30, "mirror: BL->BR remapped 3->30");
+    }
+
+    #[test]
+    fn blit_additive_writes_only_where_both_nonzero() {
+        let sprite = make_test_sprite(); // all pixels 1-4 (non-zero)
+        let src = BlitSource::from(&sprite);
+        let mut dst = PixelGrid::new(16, 16);
+        // Fill only the right half of the destination with non-zero
+        for y in 0..16u32 {
+            for x in 8..16u32 {
+                dst.data[(y * dst.row_stride + x) as usize] = 99;
+            }
+        }
+
+        blit_sprite_rect(
+            &mut dst,
+            &src,
+            4,
+            4,
+            8,
+            8,
+            0,
+            0,
+            None,
+            BlitOrientation::Normal,
+            BlitBlend::Additive,
+        );
+
+        let p = |x: i32, y: i32| dst.data[(y as u32 * dst.row_stride + x as u32) as usize];
+        // Left half of sprite (dst_x 4-7): dst was 0, so additive skips
+        assert_eq!(p(4, 4), 0, "dst was 0, additive should not write");
+        assert_eq!(p(7, 7), 0, "dst was 0, additive should not write");
+        // Right half of sprite (dst_x 8-11): dst was 99, so additive writes src
+        assert_eq!(p(8, 4), 2, "dst was non-zero, additive writes src (TR)");
+        assert_eq!(p(8, 8), 4, "dst was non-zero, additive writes src (BR)");
+        // Outside sprite: unchanged
+        assert_eq!(p(12, 4), 99, "outside sprite, right half preserved");
+        assert_eq!(p(3, 4), 0, "outside sprite, left half preserved");
+    }
+
+    #[test]
+    fn blit_subtractive_writes_only_where_dst_zero() {
+        let sprite = make_test_sprite(); // all pixels 1-4 (non-zero)
+        let src = BlitSource::from(&sprite);
+        let mut dst = PixelGrid::new(16, 16);
+        // Fill only the right half with non-zero
+        for y in 0..16u32 {
+            for x in 8..16u32 {
+                dst.data[(y * dst.row_stride + x) as usize] = 99;
+            }
+        }
+
+        blit_sprite_rect(
+            &mut dst,
+            &src,
+            4,
+            4,
+            8,
+            8,
+            0,
+            0,
+            None,
+            BlitOrientation::Normal,
+            BlitBlend::Subtractive,
+        );
+
+        let p = |x: i32, y: i32| dst.data[(y as u32 * dst.row_stride + x as u32) as usize];
+        // Left half of sprite (dst_x 4-7): dst was 0, so subtractive writes
+        assert_eq!(p(4, 4), 1, "dst was 0, subtractive writes src pixel");
+        assert_eq!(
+            p(7, 7),
+            1,
+            "dst was 0, subtractive writes src (TL quadrant)"
+        );
+        // Right half of sprite (dst_x 8-11): dst was 99, so subtractive skips
+        assert_eq!(
+            p(8, 4),
+            99,
+            "dst was non-zero, subtractive should not write"
+        );
+        assert_eq!(
+            p(8, 8),
+            99,
+            "dst was non-zero, subtractive should not write"
+        );
+    }
+
+    #[test]
+    fn blit_additive_skips_transparent_src() {
+        // Sprite with transparent (0) pixels should never write them
+        let mut pixels = vec![0u8; 8 * 8];
+        for i in 0..8 {
+            pixels[i * 8 + i] = 5; // diagonal only
+        }
+        let sprite = pixel_grid_from_indexed(8, 8, &pixels);
+        let src = BlitSource::from(&sprite);
+        let mut dst = PixelGrid::new(8, 8);
+        dst.data.fill(99); // all non-zero
+
+        blit_sprite_rect(
+            &mut dst,
+            &src,
+            0,
+            0,
+            8,
+            8,
+            0,
+            0,
+            None,
+            BlitOrientation::Normal,
+            BlitBlend::Additive,
+        );
+
+        let p = |x: i32, y: i32| dst.data[(y as u32 * dst.row_stride + x as u32) as usize];
+        // Diagonal: src=5, dst=99 → both non-zero → writes 5
+        assert_eq!(p(0, 0), 5, "diagonal written");
+        assert_eq!(p(3, 3), 5, "diagonal written");
+        // Off-diagonal: src=0 → skipped even though dst is non-zero
+        assert_eq!(p(1, 0), 99, "transparent src not written");
+        assert_eq!(p(0, 1), 99, "transparent src not written");
+    }
+
     // =======================================================================
     // Image loading helpers (for snapshot tests with real images)
     // =======================================================================
@@ -1269,4 +1554,60 @@ mod tests {
             77,
         );
     }
+    #[test]
+    fn snap_blit_opaque_additive() {
+        run_snapshot_test(
+            "sprite_test.gif",
+            "blit_opaque_additive",
+            16,
+            16,
+            None,
+            (0, 0),
+            BlitOrientation::Normal,
+            BlitBlend::Additive,
+            77,
+        );
+    }
+    #[test]
+    fn snap_blit_opaque_subtractive() {
+        run_snapshot_test(
+            "sprite_test.gif",
+            "blit_opaque_subtractive",
+            16,
+            16,
+            None,
+            (0, 0),
+            BlitOrientation::Normal,
+            BlitBlend::Subtractive,
+            0,
+        );
+    }
+    #[test]
+    fn snap_blit_transparent_additive() {
+        run_snapshot_test(
+            "sprite_transparent_test.gif",
+            "blit_transparent_additive",
+            16,
+            16,
+            None,
+            (0, 0),
+            BlitOrientation::Normal,
+            BlitBlend::Additive,
+            77,
+        );
+    }
+    #[test]
+    fn snap_blit_transparent_subtractive() {
+        run_snapshot_test(
+            "sprite_transparent_test.gif",
+            "blit_transparent_subtractive",
+            16,
+            16,
+            None,
+            (0, 0),
+            BlitOrientation::Normal,
+            BlitBlend::Subtractive,
+            0,
+        );
+    }
 }

crates/openwa-dll/src/replacements/bitgrid.rs

@@ -382,9 +382,21 @@ pub unsafe fn capture_blit_snapshots() {
                 0x0000_0000,
                 0,
             ),
+            // Additive mask (mode 2) — writes only where both src and dst are non-zero
+            ("additive", 16, 16, sw, sh, 0, 0, 0x0000_0002, 77),
+            // Subtractive mask (mode 3) — writes only where src != 0 and dst == 0
+            ("subtractive", 16, 16, sw, sh, 0, 0, 0x0000_0003, 0),
         ];
 
-        let blit_target = rb(va::BLIT_SPRITE_RECT);
+        // Use the original (unhooked) blit function for ground-truth captures.
+        // ORIG_BLIT is set by MinHook when the hook is installed; if not hooked
+        // yet (shouldn't happen), fall back to the raw address.
+        let orig = ORIG_BLIT.load(core::sync::atomic::Ordering::Relaxed);
+        let blit_target = if orig != 0 {
+            orig
+        } else {
+            rb(va::BLIT_SPRITE_RECT)
+        };
 
         for &(suffix, dx, dy, w, h, sx, sy, flags, bg) in test_cases {
             // Clear destination
@@ -400,7 +412,7 @@ pub unsafe fn capture_blit_snapshots() {
                 src,
                 sx,
                 sy,
-                0, // color_table = 0 (none) for mode 0; ignored for mode 1 without table
+                core::ptr::null(), // no color table
                 flags,
                 blit_target,
             );
@@ -478,7 +490,7 @@ unsafe extern "cdecl" fn wa_blit_sprite_rect(
     _src: *mut openwa_core::bitgrid::DisplayBitGrid,
     _src_x: i32,
     _src_y: i32,
-    _color_table: u32,
+    _color_table: *const u8,
     _flags: u32,
     _target: u32,
 ) {
@@ -539,8 +551,8 @@ unsafe extern "C" fn blit_hook_trampoline() {
 
 /// Rust implementation of the core sprite blit.
 ///
-/// Handles 8bpp blend modes 0 (copy) and 1 (color table / transparency).
-/// Falls through to the original WA function for unsupported modes.
+/// Handles all 8bpp blend modes: 0 (copy), 1 (color table), 2 (additive mask), 3 (subtractive mask).
+/// Falls through to the original WA function for non-8bpp surfaces.
 unsafe extern "cdecl" fn blit_impl(
     dst: *mut openwa_core::bitgrid::DisplayBitGrid,
     dst_x: i32,
@@ -550,7 +562,7 @@ unsafe extern "cdecl" fn blit_impl(
     src: *mut openwa_core::bitgrid::DisplayBitGrid,
     src_x: i32,
     src_y: i32,
-    color_table: u32,
+    color_table: *const u8,
     flags: u32,
 ) -> u32 {
     use openwa_core::display::sprite_blit::{
@@ -565,8 +577,8 @@ unsafe extern "cdecl" fn blit_impl(
     let src_cpp = (*src).cells_per_unit;
     let dst_cpp = (*dst).cells_per_unit;
 
-    // Only handle 8bpp surfaces with blend modes 0 and 1
-    if dst_cpp != 8 || src_cpp != 8 || blend_mode > 1 {
+    // Only handle 8bpp surfaces with blend modes 0-3
+    if dst_cpp != 8 || src_cpp != 8 || blend_mode > 3 {
         return call_original_blit(
             dst,
             dst_x,
@@ -581,22 +593,12 @@ unsafe extern "cdecl" fn blit_impl(
         );
     }
 
-    // For mode 1 with a color table pointer, fall through for now
-    // (we'd need to read 256 bytes from the pointer, which could be a mixing LUT)
-    if blend_mode == 1 && color_table != 0 {
-        return call_original_blit(
-            dst,
-            dst_x,
-            dst_y,
-            width,
-            height,
-            src,
-            src_x,
-            src_y,
-            color_table,
-            flags,
-        );
-    }
+    // Convert color_table from raw pointer to typed reference
+    let color_table_ref: Option<&[u8; 256]> = if !color_table.is_null() {
+        Some(&*(color_table as *const [u8; 256]))
+    } else {
+        None
+    };
 
     let orientation = BlitOrientation::from_flags(flags);
     let blend = BlitBlend::from_flags(flags);
@@ -641,7 +643,7 @@ unsafe extern "cdecl" fn blit_impl(
         height,
         src_x,
         src_y,
-        None, // no color table for modes we handle
+        color_table_ref,
         orientation,
         blend,
     );
@@ -663,7 +665,7 @@ unsafe fn call_original_blit(
     src: *mut openwa_core::bitgrid::DisplayBitGrid,
     src_x: i32,
     src_y: i32,
-    color_table: u32,
+    color_table: *const u8,
     flags: u32,
 ) -> u32 {
     let orig = ORIG_BLIT.load(Ordering::Relaxed);
@@ -693,7 +695,7 @@ unsafe extern "cdecl" fn call_original_blit_asm(
     _src: *mut openwa_core::bitgrid::DisplayBitGrid,
     _src_x: i32,
     _src_y: i32,
-    _color_table: u32,
+    _color_table: *const u8,
     _flags: u32,
     _target: u32,
 ) -> u32 {

testdata/snapshots/blit_opaque_additive.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:674b3978de2a4221bc70426270b04d787919b514a9d4d936862eac33c5708088
+size 25612

testdata/snapshots/blit_opaque_subtractive.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:373212b13209d949dc01ec5da36d7ce2cd20f62420f35fded1c5fb351e50898c
+size 25612

testdata/snapshots/blit_transparent_additive.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:943144ddded70c2c54ece1b7b5713247d4c36d042f9e8cd301e4355b2646b519
+size 25612

testdata/snapshots/blit_transparent_subtractive.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f892414f33d882e46788ba903eb5ebb9b29f3548d7a946b140e230ba1db37ce3
+size 25612