From 86bafdd67940efbfb5c3eec233e53ccbabd92094 Mon Sep 17 00:00:00 2001
From: funman300 <funman300@gmail.com>
Date: Wed, 27 May 2026 16:58:42 -0700
Subject: [PATCH] feat(engine): add platform abstraction trait skeleton (closes
 #47)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds solitaire_engine::platform::{StorageBackend, PlatformTime} traits.
No implementations yet — native and WASM impls follow in #48.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 solitaire_engine/src/lib.rs              |  2 ++
 solitaire_engine/src/platform/mod.rs     | 11 +++++++++++
 solitaire_engine/src/platform/storage.rs | 19 +++++++++++++++++++
 solitaire_engine/src/platform/time.rs    | 11 +++++++++++
 4 files changed, 43 insertions(+)
 create mode 100644 solitaire_engine/src/platform/mod.rs
 create mode 100644 solitaire_engine/src/platform/storage.rs
 create mode 100644 solitaire_engine/src/platform/time.rs

diff --git a/solitaire_engine/src/lib.rs b/solitaire_engine/src/lib.rs
index 71a678b..b13d1d5 100644
--- a/solitaire_engine/src/lib.rs
+++ b/solitaire_engine/src/lib.rs
@@ -31,6 +31,7 @@ pub mod onboarding_plugin;
 pub mod pause_plugin;
 pub mod pending_hint;
 pub mod play_by_seed_plugin;
+pub mod platform;
 pub mod profile_plugin;
 pub mod radial_menu;
 pub mod replay_overlay;
@@ -111,6 +112,7 @@ pub use events::{
 };
 pub use difficulty_plugin::{DifficultyIndexResource, DifficultyPlugin};
 pub use play_by_seed_plugin::{PlayBySeedPlugin, PlayBySeedScreen};
+pub use platform::{PlatformTime, StorageBackend};
 pub use game_plugin::{
     ConfirmNewGameScreen, GameMutation, GameOverScreen, GamePlugin, GameStatePath, RecordingReplay,
     ReplayPath,
diff --git a/solitaire_engine/src/platform/mod.rs b/solitaire_engine/src/platform/mod.rs
new file mode 100644
index 0000000..1e7ebaa
--- /dev/null
+++ b/solitaire_engine/src/platform/mod.rs
@@ -0,0 +1,11 @@
+//! Platform abstraction layer.
+//!
+//! Traits defined here are implemented by:
+//! - `solitaire_data` for native targets (filesystem, `std::time`)
+//! - future WASM-specific impls for browser targets (`localStorage`, `js_sys::Date`)
+
+pub mod storage;
+pub mod time;
+
+pub use storage::StorageBackend;
+pub use time::PlatformTime;
diff --git a/solitaire_engine/src/platform/storage.rs b/solitaire_engine/src/platform/storage.rs
new file mode 100644
index 0000000..d5edc2e
--- /dev/null
+++ b/solitaire_engine/src/platform/storage.rs
@@ -0,0 +1,19 @@
+use std::io;
+
+/// Abstracts platform-specific key-value / file storage.
+///
+/// Native: backed by the filesystem (via `solitaire_data`).
+/// WASM: backed by `localStorage` / `sessionStorage`.
+pub trait StorageBackend: Send + Sync + 'static {
+    /// Read bytes for the given key. Returns `None` if the key does not exist.
+    fn read(&self, key: &str) -> io::Result<Option<Vec<u8>>>;
+
+    /// Write bytes for the given key atomically.
+    fn write(&self, key: &str, data: &[u8]) -> io::Result<()>;
+
+    /// Delete a key. No-op if the key does not exist.
+    fn delete(&self, key: &str) -> io::Result<()>;
+
+    /// List all known keys (for migration / debug purposes).
+    fn keys(&self) -> io::Result<Vec<String>>;
+}
diff --git a/solitaire_engine/src/platform/time.rs b/solitaire_engine/src/platform/time.rs
new file mode 100644
index 0000000..c7492d3
--- /dev/null
+++ b/solitaire_engine/src/platform/time.rs
@@ -0,0 +1,11 @@
+/// Abstracts platform-specific wall-clock time.
+///
+/// Native: backed by `std::time::SystemTime`.
+/// WASM: backed by `js_sys::Date::now()`.
+pub trait PlatformTime: Send + Sync + 'static {
+    /// Returns the current Unix timestamp in seconds.
+    fn now_unix_secs(&self) -> u64;
+
+    /// Returns the current Unix timestamp in milliseconds.
+    fn now_unix_millis(&self) -> u128;
+}