feat(klondike): add optional serde feature for instruction/pile serialization

Adds serde Serialize/Deserialize derives (behind the `serde` feature flag)
to Tableau, Foundation, KlondikePile, SkipCards, TableauStack,
KlondikePileStack, DstFoundation, DstTableau, and KlondikeInstruction.

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

card_game/Cargo.toml

@@ -8,8 +8,12 @@ description = "Card game library."
 authors = ["Rhys Lloyd <krakow20@gmail.com>"]
 keywords = ["card", "cards", "solitaire", "klondike"]
 
+[features]
+serde = ["dep:serde"]
+
 [dependencies]
 arrayvec = { version = "0.7.6", registry = "Quaternions", features = ["len_u8"], default-features = false }
+serde = { version = "1", optional = true, default-features = false, features = ["derive"] }
 
 [lints]
 workspace = true

card_game/src/lib.rs

@@ -28,6 +28,7 @@ pub trait Game: Clone {
 
 /// card_game supports up to 4 identifiably separate decks.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Deck {
 	Deck1 = 0b00,
 	Deck2 = 0b01,
@@ -48,6 +49,7 @@ impl Deck {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Suit {
 	Spades = 0b00,
 	Hearts = 0b01,
@@ -70,6 +72,10 @@ impl Suit {
 	pub const fn is_red(self) -> bool {
 		self as u8 & 0b01 != 0
 	}
+	/// Is the suit black.
+	pub const fn is_black(self) -> bool {
+		!self.is_red()
+	}
 	/// Suit value is 2 bits, is_red is the low bit.
 	pub const fn suit_high_bit(self) -> bool {
 		self as u8 & 0b10 != 0
@@ -77,6 +83,7 @@ impl Suit {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Rank {
 	Ace = 1,
 	Two = 2,
@@ -127,6 +134,10 @@ impl Rank {
 			_ => return None,
 		})
 	}
+	/// Numeric value: Ace = 1, King = 13.
+	pub const fn value(self) -> u8 {
+		self as u8
+	}
 	pub const fn checked_add(self, offset: u8) -> Option<Rank> {
 		match (self as u8).checked_add(offset) {
 			Some(rank) => Self::new(rank),
@@ -146,6 +157,8 @@ impl Rank {
 /// 2 bits for suit ID
 /// 4 bits for card Value
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", serde(transparent))]
 pub struct Card(core::num::NonZeroU8);
 impl Card {
 	pub const fn new(deck: Deck, suit: Suit, rank: Rank) -> Self {

klondike/Cargo.toml

@@ -3,9 +3,13 @@ name = "klondike"
 version = "0.3.0"
 edition = "2024"
 
+[features]
+serde = ["dep:serde"]
+
 [dependencies]
 card_game.workspace = true
 rand = { version = "0.10.1", default-features = false, features = ["std_rng"] }
+serde = { version = "1", optional = true, default-features = false, features = ["derive"] }
 
 [lints]
 workspace = true

klondike/src/lib.rs

@@ -121,6 +121,7 @@ impl KlondikeStats {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Tableau {
 	Tableau1,
 	Tableau2,
@@ -147,6 +148,7 @@ impl Tableau {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Foundation {
 	Foundation1,
 	Foundation2,
@@ -167,6 +169,7 @@ impl Foundation {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum KlondikePile {
 	Tableau(Tableau),
 	Stock,
@@ -200,6 +203,7 @@ impl From<Foundation> for KlondikePile {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum SkipCards {
 	Skip0,
 	Skip1,
@@ -238,6 +242,7 @@ impl SkipCards {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct TableauStack {
 	pub tableau: Tableau,
 	pub skip_cards: SkipCards,
@@ -271,6 +276,7 @@ impl TableauStack {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum KlondikePileStack {
 	Tableau(TableauStack),
 	Stock,
@@ -294,6 +300,7 @@ impl KlondikePileStack {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct DstFoundation {
 	pub src: KlondikePile,
 	pub foundation: Foundation,
@@ -317,6 +324,7 @@ impl DstFoundation {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct DstTableau {
 	pub src: KlondikePileStack,
 	pub tableau: Tableau,
@@ -340,6 +348,7 @@ impl DstTableau {
 }
 
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum KlondikeInstruction {
 	DstFoundation(DstFoundation),
 	DstTableau(DstTableau),