feat: migrate SDL2 → SDL3 (3.4.2) (#53)

* feat: migrate SDL2 → SDL3 (3.4.2) with build-from-source

Replace sdl2 v0.37 with sdl3 v0.17.3 (sdl3-sys v0.6.1+SDL-3.4.2).
SDL3 is now compiled from bundled C source via cmake, eliminating the
need for system-installed SDL dev packages.

Key API changes:
- Canvas creation: remove builder pattern, use raw FFI for VSync
- All drawing calls use FRect/FPoint (f32) via frect()/fpoint() helpers
- PixelFormatEnum → PixelFormat (struct with associated constants)
- read_pixels returns Surface, extract bytes with pitch-aware row copy
- ClippingRect enum replaces Option<Rect> for clip_rect()
- Audio: AudioQueue<i16> → AudioStreamOwner with put_data_i16()
- Mouse/wheel coordinates: i32 → f32 (truncated back to i32)
- surface.without_lock() is now unsafe

Docker CI image updated with cmake, make, and X11/Wayland/audio dev
headers. All documentation updated to reflect SDL3 migration.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: add altimit skin to live demo skin selector

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address AI review feedback (iteration 1)

Automated fix by Claude in response to Gemini/Codex review.

Iteration: 1/5

Co-Authored-By: AI Review Agent <noreply@anthropic.com>

* fix: resolve CI pipeline failures

Automated fix by Claude in response to pipeline failures.

Failures addressed:
- format
- lint
- test-suite

Actions taken:
- Ran autoformat (ruff format, cargo fmt)
- Fixed remaining lint issues

Iteration: 1/5

Co-Authored-By: AI Pipeline Agent <noreply@anthropic.com>

---------

Co-authored-by: AI Agent Bot <ai-agent@localhost>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: AI Review Agent <ai-review-agent@localhost>
Co-authored-by: AI Pipeline Agent <ai-pipeline-agent@localhost>

Author: 5 people

AGENTS.md

@@ -12,7 +12,7 @@ All code changes are authored by AI agents under human direction. No external co
 
 ## Build and Test Commands
 
-All CI commands run inside Docker containers. Local development works with cargo directly if SDL2 dev libs are installed.
+All CI commands run inside Docker containers. Local development works with cargo directly (SDL3 is compiled from source; requires cmake, g++, and X11/audio dev headers).
 
 ```bash
 # Build
@@ -80,7 +80,7 @@ oasis-types     (foundation: Color, Button, InputEvent, backend traits, error ty
 ├── oasis-js         (JavaScript engine: QuickJS-NG runtime, console API)
 ├── oasis-video      (MP4/H.264+AAC decode; features: h264, no-std-demux, video-decode)
 └── oasis-core       (coordination: 16 apps, dashboard, agent, plugin, script)
-    ├── oasis-backend-sdl  (SDL2 desktop/Pi rendering + input + audio)
+    ├── oasis-backend-sdl  (SDL3 desktop/Pi rendering + input + audio)
     │   └── oasis-app      (binary entry points: oasis-app, oasis-screenshot; oasis-video[video-decode])
     ├── oasis-backend-wasm (Canvas 2D + DOM input + Web Audio, iframe overlay)
     ├── oasis-backend-ue5  (software RGBA framebuffer for Unreal Engine 5)
@@ -208,7 +208,7 @@ To re-enable at your own risk: set `CODEX_ENABLED=true` in your environment.
 ## Docker Services
 
 `docker-compose.yml` profiles:
-- **`ci`** -- rust-ci container (rust:1.93-slim + SDL2 dev libs + nightly + cargo-deny)
+- **`ci`** -- rust-ci container (rust:1.93-slim + cmake + X11/audio dev libs + nightly + cargo-deny)
 - **`psp`** -- PPSSPP emulator (multi-stage build, NVIDIA GPU passthrough, X11 forwarding)
 - **`services`** -- All MCP server containers
 - **`memory`** -- AgentCore memory service (also included in `services`)

CLAUDE.md

@@ -10,7 +10,7 @@ Default virtual resolution is 480x272 (PSP native). Skins may override this (e.g
 
 ## Build Commands
 
-All CI commands run inside Docker containers. For local development you can run cargo directly if SDL2 dev libs are installed, or use the Docker wrapper.
+All CI commands run inside Docker containers. For local development you can run cargo directly (SDL3 is compiled from source automatically via the `build-from-source` feature), or use the Docker wrapper.
 
 ```bash
 # Build (desktop)
@@ -90,7 +90,7 @@ oasis-types     (foundation: Color, Button, InputEvent, backend traits, error ty
 ├── oasis-video      (MP4/H.264+AAC decode; features: h264, no-std-demux, video-decode)
 ├── oasis-vector     (vector graphics: scene graph, path ops, icons, frame-driven animations)
 └── oasis-core       (coordination: 16 apps, dashboard, agent, plugin, script)
-    ├── oasis-backend-sdl  (SDL2 desktop/Pi rendering + input + audio)
+    ├── oasis-backend-sdl  (SDL3 desktop/Pi rendering + input + audio)
     │   └── oasis-app      (binary entry points: oasis-app, oasis-screenshot; oasis-video[video-decode])
     ├── oasis-backend-wasm (Canvas 2D + DOM input + Web Audio, iframe overlay)
     ├── oasis-backend-ue5  (software RGBA framebuffer for Unreal Engine 5)
@@ -178,7 +178,7 @@ Exports C-ABI functions: `oasis_create`, `oasis_destroy`, `oasis_tick`, `oasis_s
 ## Docker Services
 
 `docker-compose.yml` profiles:
-- `ci` -- rust-ci container (rust:1.93-slim + SDL2 dev libs + nightly + cargo-deny)
+- `ci` -- rust-ci container (rust:1.93-slim + cmake + X11/audio dev libs + nightly + cargo-deny)
 - `psp` -- PPSSPP emulator (multi-stage build, NVIDIA GPU passthrough)
 - `services` -- MCP server containers (code-quality, content-creation, gemini, etc.)
 

CONTRIBUTING.md

@@ -13,7 +13,7 @@ Feature requests, guidance, consulting, and support are not provided. This polic
 ## What You Can Do
 
 - **Fork it.** Clone the repo and adapt it however you want. This is the recommended path if you need features that don't exist here.
-- **Study it.** The codebase demonstrates an embeddable OS framework in edition 2024 Rust with pluggable rendering backends (SDL2, WASM, UE5, PSP hardware), a window manager, HTML/CSS/Gemini browser engine, 13-skin theming system, virtual filesystem, and command interpreter.
+- **Study it.** The codebase demonstrates an embeddable OS framework in edition 2024 Rust with pluggable rendering backends (SDL3, WASM, UE5, PSP hardware), a window manager, HTML/CSS/Gemini browser engine, 13-skin theming system, virtual filesystem, and command interpreter.
 - **Use it.** You are free to use any component under the terms of the [MIT License](LICENSE).
 
 You do so entirely at your own risk and without any expectation of support, maintenance, or acknowledgment from the maintainer.

Cargo.lock

@@ -60,7 +60,7 @@ thiserror = "2.0"
 anyhow = "1.0"
 
 # Graphics (desktop / Pi)
-sdl2 = "0.37"
+sdl3 = { version = "0.17", features = ["build-from-source"] }
 
 # Image encoding/decoding
 png = "0.17"

Cargo.toml

@@ -36,7 +36,7 @@ OASIS_OS originated as a Rust port of a PSP homebrew shell OS written in C circa
 
 | Target | Backend | Renderer | Input | Status |
 |--------|---------|----------|-------|--------|
-| Desktop / Raspberry Pi | `oasis-backend-sdl` | SDL2 window | Keyboard, mouse, gamepad | Implemented |
+| Desktop / Raspberry Pi | `oasis-backend-sdl` | SDL3 window | Keyboard, mouse, gamepad | Implemented |
 | WebAssembly (Browser) | `oasis-backend-wasm` | Canvas 2D API | DOM events (keyboard, mouse, touch) | Implemented |
 | PSP / PPSSPP | `oasis-backend-psp` | sceGu hardware sprites | PSP controller | Implemented |
 | Unreal Engine 5 | `oasis-backend-ue5` | Software RGBA framebuffer | FFI input queue | Implemented |
@@ -115,7 +115,7 @@ oasis-os/
 |   +-- oasis-core/                   # Coordination layer: 16 apps, dashboard, agent, plugin, script, etc.
 |   +-- oasis-video/                  # Software MP4/H.264+AAC decode pipeline (symphonia + openh264)
 |   +-- oasis-vector/                 # Vector graphics: scene graph, path ops, icons, animations
-|   +-- oasis-backend-sdl/            # SDL2 rendering and input (desktop + Pi)
+|   +-- oasis-backend-sdl/            # SDL3 rendering and input (desktop + Pi)
 |   +-- oasis-backend-wasm/           # Canvas 2D rendering, DOM input, Web Audio (browser)
 |   +-- oasis-backend-ue5/            # UE5 software framebuffer + FFI input queue
 |   +-- oasis-backend-psp/            # [excluded from workspace] sceGu hardware rendering, PSP controller, UMD browsing
@@ -157,26 +157,26 @@ oasis-os/
 | `oasis-js` | JavaScript engine wrapping QuickJS-NG via rquickjs: `console` API, inline `<script>` execution, DOM manipulation from JS |
 | `oasis-core` | Coordination layer: app runner (16 apps), dashboard, agent/MCP, plugin, scripting, status/bottom bars |
 | `oasis-video` | Software MP4/H.264+AAC decode pipeline: streaming `VideoSource` API, symphonia for demux + AAC, optional openh264 for H.264. Consumed by `oasis-app` (desktop) and `oasis-ffi` (UE5) via `video-decode` feature |
-| `oasis-backend-sdl` | SDL2 rendering and input backend for desktop and Raspberry Pi |
+| `oasis-backend-sdl` | SDL3 rendering and input backend for desktop and Raspberry Pi (built from source via cmake) |
 | `oasis-backend-wasm` | WebAssembly backend -- Canvas 2D rendering, DOM event input, Web Audio, iframe overlay for real web pages |
 | `oasis-backend-ue5` | UE5 render target backend -- software RGBA framebuffer and FFI input queue |
 | `oasis-vector` | Resolution-independent vector graphics: scene graph, path operations, Altimit-style icons, frame-driven animations |
 | `oasis-backend-psp` | PSP hardware backend -- sceGu sprite rendering, SDI scene-graph integration, TLS 1.3 via embedded-tls, in-memory MP4 streaming with AAC hardware decode, PSP controller input, std via [rust-psp](https://github.com/AndrewAltimit/rust-psp) SDK |
 | `oasis-plugin-psp` | PSP overlay plugin PRX -- kernel-mode companion module for in-game overlay UI and background MP3 playback |
 | `oasis-ffi` | C-ABI FFI boundary (`cdylib`) for UE5 and external integrations. Optional `video-decode` feature adds `oasis_video_play/stop/is_playing` |
-| `oasis-app` | Desktop entry point (SDL2) and screenshot capture tool. `video-decode` feature (default) enables software video decode for TV Guide without ffmpeg |
+| `oasis-app` | Desktop entry point (SDL3) and screenshot capture tool. `video-decode` feature (default) enables software video decode for TV Guide without ffmpeg |
 
 The PSP crates are excluded from the workspace (require `mipsel-sony-psp` target) and depend on the standalone [rust-psp SDK](https://github.com/AndrewAltimit/rust-psp) via git dependency. The backend compiles to an EBOOT.PBP (standalone application) with TV Guide, Internet Radio, and all core apps, while the plugin compiles to a kernel-mode PRX (resident overlay module loaded by CFW via `PLUGINS.TXT`). The WASM backend compiles to a `cdylib` via `wasm-pack` and runs in any modern browser with in-canvas video rendering for TV Guide.
 
 ## Building
 
-### Desktop (SDL2)
+### Desktop (SDL3)
 
 ```bash
 # Via Docker (container-first)
 docker compose --profile ci run --rm rust-ci cargo build --release -p oasis-app
 
-# Or natively (requires libsdl2-dev, libsdl2-mixer-dev)
+# Or natively (requires cmake, g++, and X11/audio dev headers)
 cargo build --release -p oasis-app
 ```
 

README.md

@@ -12,7 +12,7 @@ documentation = "https://docs.rs/oasis-backend-sdl"
 oasis-core = { workspace = true, features = ["tls-rustls", "javascript"] }
 oasis-audio = { workspace = true }
 oasis-types = { workspace = true }
-sdl2 = { workspace = true }
+sdl3 = { workspace = true }
 rmp3 = { workspace = true }
 log = { workspace = true }
 

crates/oasis-backend-sdl/Cargo.toml

@@ -1,13 +1,11 @@
-//! Texture blitting operations for the SDL2 backend.
+//! Texture blitting operations for the SDL3 backend.
 //!
 //! Contains sub-rect, tinted, and flipped blit methods.
 
-use sdl2::rect::Rect;
-
 use oasis_core::backend::{BackendErrExt, Color, TextureId, texture_not_found};
 use oasis_core::error::Result;
 
-use super::SdlBackend;
+use super::{SdlBackend, frect};
 
 impl SdlBackend {
     #[allow(clippy::too_many_arguments)]
@@ -28,8 +26,8 @@ impl SdlBackend {
             .textures
             .get(&tex.0)
             .ok_or_else(|| texture_not_found(tex.0))?;
-        let src_rect = Rect::new(src_x as i32, src_y as i32, src_w, src_h);
-        let dst_rect = Rect::new(tx, ty, dst_w, dst_h);
+        let src_rect = frect(src_x as i32, src_y as i32, src_w, src_h);
+        let dst_rect = frect(tx, ty, dst_w, dst_h);
         self.canvas
             .copy(texture, src_rect, dst_rect)
             .backend_err()?;
@@ -53,7 +51,7 @@ impl SdlBackend {
             .ok_or_else(|| texture_not_found(tex.0))?;
         texture.set_color_mod(tint.r, tint.g, tint.b);
         texture.set_alpha_mod(tint.a);
-        let dst_rect = Rect::new(tx, ty, w, h);
+        let dst_rect = frect(tx, ty, w, h);
         self.canvas.copy(texture, None, dst_rect).backend_err()?;
         // Reset modulation on the same texture.
         texture.set_color_mod(255, 255, 255);
@@ -82,8 +80,8 @@ impl SdlBackend {
             .ok_or_else(|| texture_not_found(tex.0))?;
         texture.set_color_mod(tint.r, tint.g, tint.b);
         texture.set_alpha_mod(tint.a);
-        let src_rect = Rect::new(src_x as i32, src_y as i32, src_w, src_h);
-        let dst_rect = Rect::new(tx, ty, dst_w, dst_h);
+        let src_rect = frect(src_x as i32, src_y as i32, src_w, src_h);
+        let dst_rect = frect(tx, ty, dst_w, dst_h);
         self.canvas
             .copy(texture, src_rect, dst_rect)
             .backend_err()?;
@@ -109,7 +107,7 @@ impl SdlBackend {
             .textures
             .get(&tex.0)
             .ok_or_else(|| texture_not_found(tex.0))?;
-        let dst_rect = Rect::new(tx, ty, w, h);
+        let dst_rect = frect(tx, ty, w, h);
         self.canvas
             .copy_ex(texture, None, dst_rect, 0.0, None, flip_h, flip_v)
             .backend_err()?;

crates/oasis-backend-sdl/src/blitting.rs

@@ -1,9 +1,9 @@
-//! Input event handling for the SDL2 backend.
+//! Input event handling for the SDL3 backend.
 //!
-//! Maps SDL2 keyboard, mouse, and window events to OASIS_OS `InputEvent`s.
+//! Maps SDL3 keyboard, mouse, and window events to OASIS_OS `InputEvent`s.
 
-use sdl2::event::Event;
-use sdl2::keyboard::Keycode;
+use sdl3::event::Event;
+use sdl3::keyboard::Keycode;
 
 use oasis_core::input::{Button, InputEvent, Trigger};
 
@@ -21,7 +21,7 @@ impl oasis_core::backend::InputBackend for SdlBackend {
     }
 }
 
-/// Map an SDL2 event to an OASIS_OS input event.
+/// Map an SDL3 event to an OASIS_OS input event.
 pub(crate) fn map_sdl_event(event: Event) -> Option<InputEvent> {
     match event {
         Event::Quit { .. } => Some(InputEvent::Quit),
@@ -31,16 +31,27 @@ pub(crate) fn map_sdl_event(event: Event) -> Option<InputEvent> {
         Event::KeyUp {
             keycode: Some(key), ..
         } => map_key_up(key),
-        Event::MouseMotion { x, y, .. } => Some(InputEvent::CursorMove { x, y }),
-        Event::MouseButtonDown { x, y, .. } => Some(InputEvent::PointerClick { x, y }),
-        Event::MouseButtonUp { x, y, .. } => Some(InputEvent::PointerRelease { x, y }),
-        Event::MouseWheel { y, .. } => Some(InputEvent::MouseWheel { delta: -y }),
+        // SDL3 mouse coordinates are f32; truncate to i32.
+        Event::MouseMotion { x, y, .. } => Some(InputEvent::CursorMove {
+            x: x as i32,
+            y: y as i32,
+        }),
+        Event::MouseButtonDown { x, y, .. } => Some(InputEvent::PointerClick {
+            x: x as i32,
+            y: y as i32,
+        }),
+        Event::MouseButtonUp { x, y, .. } => Some(InputEvent::PointerRelease {
+            x: x as i32,
+            y: y as i32,
+        }),
+        // SDL3 mouse wheel y is f32; truncate to i32.
+        Event::MouseWheel { y, .. } => Some(InputEvent::MouseWheel { delta: -(y as i32) }),
         Event::Window {
-            win_event: sdl2::event::WindowEvent::FocusGained,
+            win_event: sdl3::event::WindowEvent::FocusGained,
             ..
         } => Some(InputEvent::FocusGained),
         Event::Window {
-            win_event: sdl2::event::WindowEvent::FocusLost,
+            win_event: sdl3::event::WindowEvent::FocusLost,
             ..
         } => Some(InputEvent::FocusLost),
         Event::TextInput { text, .. } => text.chars().next().map(InputEvent::TextInput),