refactor: type set_active_layer return + propagate PaletteContext

Cascades a typed `*mut PaletteContext` return through the chain that
starts at `DisplayGfx::set_active_layer` (slot 5) and feeds the GfxDir
loaders.

- Slot 5 vtable signature retyped from `*mut u8` to
`*mut PaletteContext`. Doc-comment promoted from one line to
explain what the result is used for downstream.

- `gfx_resource_create` (`FUN_004F6300` port), `call_gfx_find_and_load`,
and `call_gfx_load_and_wrap` now take `display_ctx: *mut PaletteContext`
instead of `*mut u8`. The single internal `IMG_Decode` call still
casts back to `*mut u8` since `IMG_Decode` is WA-side.

- `compute_complex_gradient` (`render/display/gradient.rs`) takes
`layer3_ctx: *mut PaletteContext` and passes it through to
`call_gfx_find_and_load` without any casts.

- `wa_load_sprites` naked-asm bridge's `_layer_ctx` parameter retyped
to `*mut PaletteContext` to match what its only caller passes after
`set_active_layer`. The naked asm body is unchanged — pointer types
are zero-cost on x86.

- The `+0x606` byte arithmetic at
`ddgame_constructor.rs:969` (the gradient sky-height read) is now
a clean `(*layer3_ctx).cache_count` field access. The cast/offset
pair `*(layer3_ctx.add(0x606) as *const i16)` is gone.

- One redundant `as *mut PaletteContext` cast removed from
`load_sprite_by_layer`'s call to `set_active_layer`.

- `gfx_resource_create_trampoline`'s impl wrapper in DLL adds one
explicit `as *mut PaletteContext` cast since the trampoline catches
an opaque stack pointer from the WA-side caller. Documented in a
comment that all known WA call sites pass a `set_active_layer`
return value (i.e. a `PaletteContext*`).

No behavior changes — all pointer ops are zero-cost casts on x86.
Headless replay tests pass 15/15.

crates/openwa-core/src/engine/ddgame_constructor.rs

@@ -182,7 +182,7 @@ unsafe extern "C" fn wa_load_sprites(
     _sprite_data: *mut u8,
     _display_flags: u32,
     _param4: u32,
-    _layer_ctx: *mut u8, // → ESI
+    _layer_ctx: *mut crate::render::palette::PaletteContext, // → ESI
 ) {
     core::arch::naked_asm!(
         "push esi",
@@ -664,7 +664,7 @@ unsafe fn init_graphics_and_resources(
         gfx_resource = gfx_resource_create(
             gfx_dir,
             rb(va::STR_MASKS_IMG) as *const core::ffi::c_char,
-            palette_ctx,
+            palette_ctx as *mut crate::render::palette::PaletteContext,
         );
     }
 
@@ -966,7 +966,7 @@ unsafe fn init_graphics_and_resources(
         // ── Gradient image (0x030) ──
         let level_height = (*ddgame).level_height as i32;
         let layer3_ctx = (*disp).set_active_layer(3);
-        let s_var1 = *(layer3_ctx.add(0x606) as *const i16);
+        let s_var1 = (*layer3_ctx).cache_count;
 
         if s_var1 < 0x61 && level_height == 0x2B8 {
             // Simple gradient: load gradient.img directly

crates/openwa-core/src/render/display/gradient.rs

@@ -111,7 +111,7 @@ impl PaletteContext {
 pub(crate) unsafe fn compute_complex_gradient(
     ddgame: *mut DDGame,
     land_dir: *mut GfxDir,
-    layer3_ctx: *mut u8,
+    layer3_ctx: *mut crate::render::palette::PaletteContext,
     sky_height: i16,
 ) {
     let mut palette = PaletteContext::new();

crates/openwa-core/src/render/display/vtable.rs

@@ -67,9 +67,14 @@ pub struct DisplayGfxVtable {
     /// set layer color (0x5231E0, RET 0x8)
     #[slot(4)]
     pub set_layer_color: fn(this: *mut DisplayGfx, layer: i32, color: i32),
-    /// set active layer, returns layer context ptr (0x523270, RET 0x4)
+    /// set active layer, returns layer context ptr (0x523270, RET 0x4).
+    ///
+    /// Returns the `PaletteContext*` for the requested layer (1-3),
+    /// or null if the index is out of range. Callers feed the result to
+    /// `update_palette` (slot 24) and to GfxDir loaders that need a
+    /// palette context for color remapping.
     #[slot(5)]
-    pub set_active_layer: fn(this: *mut DisplayGfx, layer: i32) -> *mut u8,
+    pub set_active_layer: fn(this: *mut DisplayGfx, layer: i32) -> *mut PaletteContext,
     /// get sprite info by layer and id (0x523500, RET 0x10)
     ///
     /// Looks up sprite metadata for the given layer ID. Checks sprite_ptrs
@@ -1457,9 +1462,12 @@ unsafe fn palette_context_init(ctx: *mut PaletteContext, range_min: i16, range_m
 ///
 /// Returns the `PaletteContext*` for `layer` (1-3), or null if out of
 /// range. Used as palette data input for `update_palette`.
-pub unsafe extern "thiscall" fn set_active_layer(this: *mut DisplayGfx, layer: i32) -> *mut u8 {
+pub unsafe extern "thiscall" fn set_active_layer(
+    this: *mut DisplayGfx,
+    layer: i32,
+) -> *mut PaletteContext {
     match Layer::try_from_i32(layer) {
-        Some(layer) => (*this).base.layer_contexts[layer.idx()] as *mut u8,
+        Some(layer) => (*this).base.layer_contexts[layer.idx()],
         None => core::ptr::null_mut(),
     }
 }
@@ -1902,7 +1910,7 @@ pub unsafe fn load_sprite_by_layer(
         return 1;
     }
 
-    let palette_ctx = set_active_layer(this, layer as i32) as *mut PaletteContext;
+    let palette_ctx = set_active_layer(this, layer as i32);
 
     if !is_valid_sprite_id(id as i32) {
         return 0;

crates/openwa-core/src/render/sprite/gfx_dir.rs

@@ -350,7 +350,7 @@ pub unsafe fn gfx_dir_load_dir(handler: *mut u8) -> i32 {
 pub unsafe fn gfx_resource_create(
     gfx_dir: *mut GfxDir,
     name: *const core::ffi::c_char,
-    output: *mut u8,
+    output: *mut crate::render::palette::PaletteContext,
 ) -> *mut u8 {
     // 1. Try FindEntry → cached load → DisplayGfx wrap
     let entry = gfx_dir_find_entry(name, gfx_dir);
@@ -375,7 +375,7 @@ pub unsafe fn gfx_resource_create(
     // IMG_Decode: stdcall(output, raw_image, 1), RET 0xC
     let decode: unsafe extern "stdcall" fn(*mut u8, *mut u8, i32) -> *mut u8 =
         core::mem::transmute(rb(va::IMG_DECODE) as usize);
-    let result = decode(output, raw_image as *mut u8, 1);
+    let result = decode(output as *mut u8, raw_image as *mut u8, 1);
 
     GfxDirStream::destroy_raw(raw_image);
 
@@ -388,7 +388,7 @@ pub unsafe fn gfx_resource_create(
 pub(crate) unsafe fn call_gfx_find_and_load(
     gfx_dir: *mut GfxDir,
     name: &core::ffi::CStr,
-    display_ctx: *mut u8,
+    display_ctx: *mut crate::render::palette::PaletteContext,
 ) -> *mut u8 {
     let name_ptr = name.as_ptr() as *const u8;
     let entry = gfx_dir_find_entry(name_ptr.cast(), gfx_dir);
@@ -415,7 +415,7 @@ pub(crate) unsafe fn call_gfx_find_and_load(
 pub(crate) unsafe fn call_gfx_load_and_wrap(
     gfx_dir: *mut GfxDir,
     name: *const core::ffi::c_char,
-    display_ctx: *mut u8,
+    display_ctx: *mut crate::render::palette::PaletteContext,
 ) -> *mut u8 {
     let image = call_gfx_load_image(gfx_dir, name);
     if image.is_null() {
@@ -424,7 +424,7 @@ pub(crate) unsafe fn call_gfx_load_and_wrap(
     // FUN_004F5F80(display_ctx, image, 1) — stdcall, RET 0xC (3 params)
     let f: unsafe extern "stdcall" fn(*mut u8, *mut u8, u32) -> *mut u8 =
         core::mem::transmute(rb(va::IMG_DECODE) as usize);
-    let result = f(display_ctx, image as *mut u8, 1);
+    let result = f(display_ctx as *mut u8, image as *mut u8, 1);
     GfxDirStream::destroy_raw(image);
     result
 }

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

@@ -102,6 +102,10 @@ extern "cdecl" fn impl_gfx_resource_create(
     name: *const c_char,
     output: *mut u8,
 ) -> u32 {
+    // The trampoline catches an opaque stack pointer; the underlying
+    // WA caller always passes a `PaletteContext*` (verified at all known
+    // call sites — `set_active_layer`'s return value).
+    let output = output as *mut openwa_core::render::palette::PaletteContext;
     let result = unsafe { gfx_resource_create(gfx_dir, name, output) };
     result as u32
 }