klondike v0.4.0 tweaks + serde

Closes #15

Reviewed-on: #16
Co-authored-by: Rhys Lloyd <krakow20@gmail.com>
Co-committed-by: Rhys Lloyd <krakow20@gmail.com>

.cargo/config.toml

@@ -0,0 +1,2 @@
+[registries.Quaternions]
+index = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"

Cargo.lock

@@ -11,8 +11,14 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 [[package]]
 name = "arrayvec"
 version = "0.7.6"
+source = "sparse+https://git.aleshym.co/api/packages/Quaternions/cargo/"
+checksum = "813440870d646c57c222c1d713dc4e3ddcb2919c3801564d767d85d7bf2afee4"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c02d123df017efcdfbd739ef81735b36c5ba83ec3c59c80a9d7ecc718f92e50"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "bitflags"
@@ -22,10 +28,11 @@ checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
 [[package]]
 name = "card_game"
-version = "0.1.0"
+version = "0.4.1"
 dependencies = [
  "arrayvec",
- "rand",
+ "serde",
+ "serde_derive",
 ]
 
 [[package]]
@@ -45,6 +52,17 @@ dependencies = [
  "rand_core",
 ]
 
+[[package]]
+name = "console"
+version = "0.16.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d64e8af5551369d19cf50138de61f1c42074ab970f74e99be916646777f8fc87"
+dependencies = [
+ "encode_unicode",
+ "libc",
+ "windows-sys",
+]
+
 [[package]]
 name = "cpufeatures"
 version = "0.3.0"
@@ -54,12 +72,34 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "encode_unicode"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0"
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"
+
 [[package]]
 name = "foldhash"
 version = "0.1.5"
@@ -119,12 +159,55 @@ dependencies = [
  "serde_core",
 ]
 
+[[package]]
+name = "insta"
+version = "1.47.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b4a6248eb93a4401ed2f37dfe8ea592d3cf05b7cf4f8efa867b6895af7e094e"
+dependencies = [
+ "console",
+ "once_cell",
+ "similar",
+ "tempfile",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "klondike"
+version = "0.4.0"
+dependencies = [
+ "card_game",
+ "insta",
+ "rand",
+ "rmp-serde",
+ "serde",
+ "serde_derive",
+ "serde_json",
+]
+
+[[package]]
+name = "klondike-bench"
+version = "0.1.0"
+dependencies = [
+ "card_game",
+ "klondike",
+ "rand",
+]
+
+[[package]]
+name = "klondike-cli"
+version = "0.1.0"
+dependencies = [
+ "card_game",
+ "klondike",
+ "rand",
+]
+
 [[package]]
 name = "leb128fmt"
 version = "0.1.0"
@@ -137,6 +220,12 @@ version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
 [[package]]
 name = "log"
 version = "0.4.29"
@@ -149,6 +238,21 @@ version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
 [[package]]
 name = "prettyplease"
 version = "0.2.37"
@@ -200,6 +304,38 @@ version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
 
+[[package]]
+name = "rmp"
+version = "0.8.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ba8be72d372b2c9b35542551678538b562e7cf86c3315773cae48dfbfe7790c"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "rmp-serde"
+version = "1.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f81bee8c8ef9b577d1681a70ebbc962c232461e397b22c208c43c04b67a155"
+dependencies = [
+ "rmp",
+ "serde",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.28"
@@ -248,6 +384,12 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "similar"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbbb5d9659141646ae647b42fe094daf6c6192d1620870b449d9557f748b2daa"
+
 [[package]]
 name = "syn"
 version = "2.0.117"
@@ -259,6 +401,19 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "tempfile"
+version = "3.27.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
+dependencies = [
+ "fastrand",
+ "getrandom",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
@@ -323,6 +478,21 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"

Cargo.toml

@@ -1,8 +1,23 @@
-[package]
+[workspace]
-name = "card_game"
+members = [
-version = "0.1.0"
+	"card_game",
-edition = "2024"
+	"klondike",
+	"klondike-bench",
+	"klondike-cli",
+]
+resolver = "3"
 
-[dependencies]
+[workspace.dependencies]
-arrayvec = "0.7.6"
+card_game = { version = "0.4.1", path = "card_game", registry = "Quaternions" }
-rand = { version = "0.10.1", default-features = false, features = ["thread_rng"] }
+klondike = { version = "0.4.0", path = "klondike", registry = "Quaternions" }
+
+[workspace.lints.rust]
+# unsafe_code = "forbid"
+# missing_docs = "warn"
+# missing_debug_implementations = "warn"
+single_use_lifetimes = "warn"
+trivial_casts = "warn"
+unused_lifetimes = "warn"
+unused_qualifications = "warn"
+# variant_size_differences = "warn"
+unexpected_cfgs = "warn"

README.md

@@ -1,50 +0,0 @@
-Card Game
-=========
-
-`card_game` is a library to implement card games.  Mainly interesting for the `Game` trait and the `Session` type.  Contains klondike as the reference implementation.
-
-## Example
-
-```rust
-use card_game::Rng;
-use card_game::card_game::{Session, Game};
-use card_game::klondike::Klondike;
-
-// create game session
-let game = Klondike::new_random_default();
-let mut session = Session::new(game);
-
-// is winnable
-let is_winnable = session.is_winnable().is_some();
-
-// play game
-while let Some(instruction) = session.possible_instructions().next() {
-	session.process_instruction(instruction);
-}
-
-// did win
-let is_win = session.is_win();
-
-// print session history
-for (i, instruction) in session.history().iter().enumerate() {
-	println!("move {i} = {instruction:?}");
-}
-
-println!("is_winnable = {is_winnable}");
-println!("is_win = {is_win}");
-```
-
-#### License
-
-<sup>
-Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
-2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
-</sup>
-
-<br>
-
-<sub>
-Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
-be dual licensed as above, without any additional terms or conditions.
-</sub>

README.md

@@ -0,0 +1 @@
+card_game/README.md

card_game/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "card_game"
+version = "0.4.1"
+edition = "2024"
+repository = "https://git.aleshym.co/Quaternions/card_game"
+license = "MIT OR Apache-2.0"
+description = "Card game library."
+authors = ["Rhys Lloyd <krakow20@gmail.com>"]
+keywords = ["card", "cards", "solitaire", "klondike"]
+
+[dependencies]
+arrayvec = { version = "0.7.6", registry = "Quaternions", features = ["len_u8"], default-features = false }
+serde = { version = "1.0.228", default-features = false, optional = true }
+serde_derive = { version = "1.0.228", default-features = false, optional = true }
+
+[lints]
+workspace = true
+
+[features]
+default = ["serde"]
+serde = ["dep:serde", "dep:serde_derive"]

card_game/README.md

@@ -0,0 +1,32 @@
+Card Game
+=========
+
+`card_game` is a collection of algorithms, structs, and enums which are useful to implement card games.
+
+## Example
+
+```rust
+use card_game::{Card, Deck, Rank, Stack, Suit};
+
+// create a full deck (unshuffled)
+let mut deck = Stack::full_deck(Deck::Deck1);
+
+// inspect the top card
+let card = deck.pop().unwrap();
+assert_eq!(card, Card::new(Deck::Deck1, Suit::Diamonds, Rank::King));
+```
+
+#### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<br>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>

card_game/src/lib.rs

@@ -0,0 +1,747 @@
+// test readme
+#[doc = include_str!("../README.md")]
+#[cfg(doctest)]
+struct ReadmeDoctests;
+
+use core::ops::RangeBounds;
+
+// TODO: pub struct ValidInstruction<I>(I);
+pub trait Game: Clone {
+	type Score: Clone + core::fmt::Debug;
+	type Stats: Clone + core::fmt::Debug;
+	type Config: Clone + core::fmt::Debug;
+	type Instruction: Clone + core::fmt::Debug;
+	fn score(&self, stats: &Self::Stats, config: &Self::Config) -> Self::Score;
+	fn possible_instructions(
+		&self,
+		config: &Self::Config,
+	) -> impl Iterator<Item = Self::Instruction> + use<Self>;
+	fn is_instruction_valid(&self, config: &Self::Config, instruction: Self::Instruction) -> bool;
+	fn process_instruction(
+		&mut self,
+		stats: &mut Self::Stats,
+		config: &Self::Config,
+		instruction: Self::Instruction,
+	);
+	fn is_win(&self) -> bool;
+}
+
+/// card_game supports up to 4 identifiably separate decks.
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub enum Deck {
+	Deck1 = 0b00,
+	Deck2 = 0b01,
+	Deck3 = 0b10,
+	Deck4 = 0b11,
+}
+impl Deck {
+	pub const fn new(deck: u8) -> Option<Self> {
+		use Deck::*;
+		Some(match deck {
+			0b00 => Deck1,
+			0b01 => Deck2,
+			0b10 => Deck3,
+			0b11 => Deck4,
+			_ => return None,
+		})
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub enum Suit {
+	Spades = 0b00,
+	Hearts = 0b01,
+	Clubs = 0b10,
+	Diamonds = 0b11,
+}
+impl Suit {
+	pub const SUITS: [Self; 4] = [Self::Spades, Self::Hearts, Self::Clubs, Self::Diamonds];
+	pub const fn new(suit: u8) -> Option<Self> {
+		use Suit::*;
+		Some(match suit {
+			0b00 => Spades,
+			0b01 => Hearts,
+			0b10 => Clubs,
+			0b11 => Diamonds,
+			_ => return None,
+		})
+	}
+	/// Is the suit red.
+	pub const fn is_red(self) -> bool {
+		self as u8 & 0b01 != 0
+	}
+	/// Suit value is 2 bits, is_red is the low bit.
+	pub const fn suit_high_bit(self) -> bool {
+		self as u8 & 0b10 != 0
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub enum Rank {
+	Ace = 1,
+	Two = 2,
+	Three = 3,
+	Four = 4,
+	Five = 5,
+	Six = 6,
+	Seven = 7,
+	Eight = 8,
+	Nine = 9,
+	Ten = 10,
+	Jack = 11,
+	Queen = 12,
+	King = 13,
+}
+impl Rank {
+	pub const RANKS: [Self; 13] = [
+		Self::Ace,
+		Self::Two,
+		Self::Three,
+		Self::Four,
+		Self::Five,
+		Self::Six,
+		Self::Seven,
+		Self::Eight,
+		Self::Nine,
+		Self::Ten,
+		Self::Jack,
+		Self::Queen,
+		Self::King,
+	];
+	pub const fn new(rank: u8) -> Option<Self> {
+		use Rank::*;
+		Some(match rank {
+			1 => Ace,
+			2 => Two,
+			3 => Three,
+			4 => Four,
+			5 => Five,
+			6 => Six,
+			7 => Seven,
+			8 => Eight,
+			9 => Nine,
+			10 => Ten,
+			11 => Jack,
+			12 => Queen,
+			13 => King,
+			_ => return None,
+		})
+	}
+	pub const fn checked_add(self, offset: u8) -> Option<Rank> {
+		match (self as u8).checked_add(offset) {
+			Some(rank) => Self::new(rank),
+			None => None,
+		}
+	}
+	pub const fn checked_sub(self, offset: u8) -> Option<Rank> {
+		match (self as u8).checked_sub(offset) {
+			Some(rank) => Self::new(rank),
+			None => None,
+		}
+	}
+}
+
+/// A card which specifies the deck id, suit, and card value.
+/// 2 bits for deck ID
+/// 2 bits for suit ID
+/// 4 bits for card Value
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize),
+	serde(transparent)
+)]
+pub struct Card(core::num::NonZeroU8);
+impl Card {
+	pub const fn new(deck: Deck, suit: Suit, rank: Rank) -> Self {
+		let packed = (deck as u8) << 6 | (suit as u8) << 4 | (rank as u8);
+		Self(core::num::NonZeroU8::new(packed).unwrap())
+	}
+	pub const fn rank(&self) -> Rank {
+		let masked = self.0.get() & 0b1111;
+		Rank::new(masked).unwrap()
+	}
+	pub const fn suit(&self) -> Suit {
+		let low_bit = self.is_red();
+		let high_bit = self.suit_high_bit();
+		match (high_bit, low_bit) {
+			(false, false) => Suit::Spades,
+			(false, true) => Suit::Hearts,
+			(true, false) => Suit::Clubs,
+			(true, true) => Suit::Diamonds,
+		}
+	}
+	/// Is the suit red.
+	pub const fn is_red(&self) -> bool {
+		self.0.get() & 0b010000 != 0
+	}
+	/// Suit value is 2 bits, is_red is the low bit.
+	pub const fn suit_high_bit(&self) -> bool {
+		self.0.get() & 0b100000 != 0
+	}
+	pub const fn deck(&self) -> Deck {
+		Deck::new(self.0.get() >> 6).unwrap()
+	}
+}
+
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
+pub struct Stack<const CAP: usize>(arrayvec::ArrayVec<Card, CAP>);
+impl<const CAP: usize> Stack<CAP> {
+	pub const fn new() -> Self {
+		Self(arrayvec::ArrayVec::new_const())
+	}
+	pub fn take_range<R: RangeBounds<usize>>(&mut self, range: R) -> Self {
+		Stack::from_iter(self.drain(range))
+	}
+}
+impl Stack<52> {
+	/// Generate a full deck of cards with the specified deck id.
+	pub fn full_deck(deck: Deck) -> Self {
+		let mut stack = arrayvec::ArrayVec::new();
+		for suit in Suit::SUITS {
+			for rank in Rank::RANKS {
+				stack.push(Card::new(deck, suit, rank));
+			}
+		}
+		Stack(stack)
+	}
+}
+impl<const CAP: usize> From<arrayvec::ArrayVec<Card, CAP>> for Stack<CAP> {
+	fn from(value: arrayvec::ArrayVec<Card, CAP>) -> Self {
+		Self(value)
+	}
+}
+impl<const CAP: usize> FromIterator<Card> for Stack<CAP> {
+	fn from_iter<T: IntoIterator<Item = Card>>(iter: T) -> Self {
+		Self(arrayvec::ArrayVec::from_iter(iter))
+	}
+}
+impl<const CAP: usize> core::ops::Deref for Stack<CAP> {
+	type Target = arrayvec::ArrayVec<Card, CAP>;
+	fn deref(&self) -> &Self::Target {
+		&self.0
+	}
+}
+impl<const CAP: usize> core::ops::DerefMut for Stack<CAP> {
+	fn deref_mut(&mut self) -> &mut Self::Target {
+		&mut self.0
+	}
+}
+impl<const CAP: usize> IntoIterator for Stack<CAP> {
+	type Item = Card;
+	type IntoIter = arrayvec::IntoIter<Card, CAP>;
+	fn into_iter(self) -> Self::IntoIter {
+		self.0.into_iter()
+	}
+}
+
+#[cfg(feature = "serde")]
+impl<'de, const CAP: usize> serde::Deserialize<'de> for Stack<CAP> {
+	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+	where
+		D: serde::Deserializer<'de>,
+	{
+		struct StackVisitor<const CAP: usize>;
+		impl<'de, const CAP: usize> serde::de::Visitor<'de> for StackVisitor<CAP> {
+			type Value = Stack<CAP>;
+			fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+				write!(f, "Card Stack")
+			}
+			fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
+			where
+				A: serde::de::SeqAccess<'de>,
+			{
+				use serde::de::Error;
+				let mut stack = Stack::new();
+				while let Some(card) = seq.next_element()? {
+					stack.try_push(card).map_err(A::Error::custom)?;
+				}
+				Ok(stack)
+			}
+		}
+		deserializer.deserialize_seq(StackVisitor)
+	}
+}
+#[cfg(feature = "serde")]
+impl<const CAP: usize> serde::Serialize for Stack<CAP> {
+	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+	where
+		S: serde::Serializer,
+	{
+		use serde::ser::SerializeSeq;
+		let mut seq = serializer.serialize_seq(Some(self.len()))?;
+		for card in self.as_slice() {
+			seq.serialize_element(card)?;
+		}
+		seq.end()
+	}
+}
+
+/// A pile is a stack of face down cards and a stack of face up cards.
+#[derive(Clone, Debug, Default, Eq, Hash, PartialEq)]
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+pub struct Pile<const DN: usize, const UP: usize> {
+	face_down: Stack<DN>,
+	face_up: Stack<UP>,
+}
+impl<const DN: usize, const UP: usize> Pile<DN, UP> {
+	pub const fn new() -> Self {
+		Self {
+			face_down: Stack::new(),
+			face_up: Stack::new(),
+		}
+	}
+	pub const fn new_face_down(stack: Stack<DN>) -> Self {
+		Self {
+			face_down: stack,
+			face_up: Stack::new(),
+		}
+	}
+	/// Returns whether a card was flipped up.
+	pub fn flip_up(&mut self) -> bool {
+		if let Some(card) = self.face_down.pop() {
+			self.face_up.push(card);
+			return true;
+		}
+		false
+	}
+	pub fn is_empty(&self) -> bool {
+		self.face_down.is_empty() && self.face_up.is_empty()
+	}
+	pub fn pop(&mut self) -> Option<Card> {
+		self.face_up.pop()
+	}
+	/// Returns the popped card and whether a card was flipped up.
+	pub fn pop_flip_up(&mut self) -> (Option<Card>, bool) {
+		let card = match self.face_up.pop() {
+			Some(card) => card,
+			None => return (None, false),
+		};
+		let did_flip_up = if self.face_up.is_empty() {
+			self.flip_up()
+		} else {
+			false
+		};
+		(Some(card), did_flip_up)
+	}
+	pub fn take_range<R: RangeBounds<usize>>(&mut self, range: R) -> Stack<UP> {
+		self.face_up.take_range(range)
+	}
+	/// Returns the card range and whether a card was flipped up.
+	pub fn take_range_flip_up<R: RangeBounds<usize>>(&mut self, range: R) -> (Stack<UP>, bool) {
+		let cards = self.take_range(range);
+		let did_flip_up = if self.face_up.is_empty() {
+			self.flip_up()
+		} else {
+			false
+		};
+		(cards, did_flip_up)
+	}
+	pub fn push(&mut self, card: Card) {
+		self.face_up.push(card);
+	}
+	pub fn extend<I: IntoIterator<Item = Card>>(&mut self, cards: I) {
+		self.face_up.extend(cards);
+	}
+	pub fn face_up(&self) -> &[Card] {
+		&self.face_up
+	}
+	pub fn face_down(&self) -> &[Card] {
+		&self.face_down
+	}
+}
+impl<const CAP: usize> Pile<CAP, CAP> {
+	pub fn flip_it_and_reverse_it(&mut self) {
+		self.swap_up_down();
+		self.face_down.reverse();
+	}
+	pub const fn swap_up_down(&mut self) {
+		core::mem::swap(&mut self.face_up, &mut self.face_down);
+	}
+}
+
+#[derive(Clone, Debug)]
+pub enum SolveError {
+	MovesBudgetExceeded,
+	StatesBudgetExceeded,
+}
+impl core::fmt::Display for SolveError {
+	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+		write!(f, "{self:?}")
+	}
+}
+impl core::error::Error for SolveError {}
+
+/// The solution tends to be very large with long chains of moves that go back to the same state.
+/// It is recommended to call .clean_solution() if the solution is actually going to be shown to a user.
+pub struct Solution<G: Game> {
+	solution: Vec<StateSnapshot<G>>,
+}
+impl<G: Game + Eq + core::hash::Hash> Solution<G> {
+	pub const fn raw_solution(&self) -> &[StateSnapshot<G>] {
+		self.solution.as_slice()
+	}
+	/// Repeatedly remove the largest range of moves that goes back into the same state.
+	/// This is a very expensive operation when the solution is very long!
+	pub fn clean_solution(self) -> Vec<StateSnapshot<G>> {
+		let mut history = self.solution;
+		// history includes cycles
+		let mut state_index: std::collections::HashMap<_, _> = history
+			.iter()
+			.enumerate()
+			.map(|(i, snapshot)| (snapshot.state().clone(), i))
+			.collect();
+
+		// find the longest range where the start and end are the same state
+		while let Some(longest_range) = history
+			.iter()
+			.enumerate()
+			.filter_map(|(index, snapshot)| {
+				let &last_index = state_index.get(snapshot.state())?;
+				let longness = last_index - index;
+				(longness != 0).then_some(index..last_index)
+			})
+			.max_by_key(|range| range.len())
+		{
+			history.drain(longest_range);
+			for (i, snapshot) in history.iter().enumerate() {
+				state_index.insert(snapshot.state().clone(), i);
+			}
+		}
+
+		history
+	}
+}
+
+#[derive(Clone, Debug)]
+pub enum SessionInstruction<I> {
+	Undo,
+	InnerInstruction(I),
+}
+
+#[derive(Clone, Debug, Default)]
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+pub struct SessionStats<S> {
+	inner: S,
+	undos: u32,
+}
+impl<S> SessionStats<S> {
+	pub const fn stats(&self) -> &S {
+		&self.inner
+	}
+	const fn increment_undos(&mut self) {
+		self.undos += 1;
+	}
+	pub const fn undos(&self) -> u32 {
+		self.undos
+	}
+}
+#[derive(Clone, Debug)]
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+pub struct SessionConfig<C> {
+	pub inner: C,
+	pub undo_penalty: i32,
+	pub solve_moves_budget: u64,
+	pub solve_states_budget: u64,
+}
+impl<C> SessionConfig<C> {
+	fn new_default(inner: C) -> Self {
+		Self {
+			inner,
+			undo_penalty: -15,
+			solve_moves_budget: 100_000,
+			solve_states_budget: 100_000,
+		}
+	}
+}
+impl<C: Default> Default for SessionConfig<C> {
+	fn default() -> Self {
+		Self::new_default(C::default())
+	}
+}
+
+#[derive(Clone, Debug)]
+pub struct Session<G: Game> {
+	stats: SessionStats<G::Stats>,
+	config: SessionConfig<G::Config>,
+	state: SessionState<G>,
+}
+#[derive(Clone, Debug)]
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+pub struct StateSnapshot<G: Game> {
+	state: G,
+	instruction: G::Instruction,
+}
+impl<G: Game> StateSnapshot<G> {
+	pub const fn state(&self) -> &G {
+		&self.state
+	}
+	pub const fn instruction(&self) -> &G::Instruction {
+		&self.instruction
+	}
+}
+#[derive(Clone, Debug)]
+pub struct SessionState<G: Game> {
+	state: G,
+	history: Vec<StateSnapshot<G>>,
+}
+impl<G: Game + Clone> SessionState<G> {
+	fn new(state: G) -> Self {
+		Self {
+			state,
+			history: Vec::new(),
+		}
+	}
+}
+impl<G: Game> SessionState<G> {
+	pub const fn state(&self) -> &G {
+		&self.state
+	}
+}
+impl<G: Game<Score = i32>> Session<G>
+where
+	G: Eq + core::hash::Hash,
+	G::Stats: Default,
+	G::Instruction: Eq + core::hash::Hash,
+{
+	pub fn new(state: G, config: SessionConfig<G::Config>) -> Self {
+		Self {
+			stats: SessionStats::default(),
+			config,
+			state: SessionState::new(state),
+		}
+	}
+	pub fn new_default(state: G) -> Self
+	where
+		G::Config: Default,
+	{
+		Self::new(state, Default::default())
+	}
+	pub const fn stats(&self) -> &SessionStats<G::Stats> {
+		&self.stats
+	}
+	pub const fn state(&self) -> &SessionState<G> {
+		&self.state
+	}
+	pub const fn config(&self) -> &SessionConfig<G::Config> {
+		&self.config
+	}
+	pub fn history(&self) -> &[StateSnapshot<G>] {
+		&self.state.history
+	}
+	pub fn undo(&mut self) {
+		self.state
+			.process_instruction(&mut self.stats, &self.config, SessionInstruction::Undo)
+	}
+	pub fn possible_instructions(&self) -> impl Iterator<Item = G::Instruction> + use<G> {
+		self.state.state.possible_instructions(&self.config.inner)
+	}
+	pub fn process_instruction(&mut self, instruction: G::Instruction) {
+		self.state.process_instruction(
+			&mut self.stats,
+			&self.config,
+			SessionInstruction::InnerInstruction(instruction),
+		)
+	}
+	pub fn is_win(&self) -> bool {
+		self.state.is_win()
+	}
+	/// Attempt to produce a solution.
+	pub fn solve(&self) -> Result<Option<Solution<G>>, SolveError> {
+		let mut state_moves = std::collections::HashMap::new();
+		let mut session = self.clone();
+		let mut moves = 0;
+		while !session.is_win() {
+			moves += 1;
+			if self.config.solve_moves_budget < moves {
+				return Err(SolveError::MovesBudgetExceeded);
+			}
+			if self.config.solve_states_budget < state_moves.len() as u64 {
+				return Err(SolveError::StatesBudgetExceeded);
+			}
+			// Continue existing iterator if it exists
+			let it = state_moves
+				.entry(session.state().state().clone())
+				.or_insert_with(|| {
+					session
+						.state()
+						.state()
+						.possible_instructions(&self.config().inner)
+				});
+
+			// Run one possible move
+			if let Some(instruction) = it.next() {
+				session.process_instruction(instruction);
+				continue;
+			}
+
+			// No more moves. If we can't undo we're done
+			if session.history().is_empty() {
+				return Ok(None);
+			} else {
+				session.undo();
+			}
+		}
+		Ok(Some(Solution {
+			solution: session.state.history,
+		}))
+	}
+}
+impl<G: Game<Score = i32>> Game for SessionState<G>
+where
+	G::Stats: Default,
+{
+	type Score = G::Score;
+	type Stats = SessionStats<G::Stats>;
+	type Config = SessionConfig<G::Config>;
+	type Instruction = SessionInstruction<G::Instruction>;
+	fn score(&self, stats: &Self::Stats, config: &Self::Config) -> Self::Score {
+		self.state.score(&stats.inner, &config.inner) + stats.undos as i32 * config.undo_penalty
+	}
+	fn possible_instructions(
+		&self,
+		config: &Self::Config,
+	) -> impl Iterator<Item = Self::Instruction> + use<G> {
+		self.state
+			.possible_instructions(&config.inner)
+			.map(SessionInstruction::InnerInstruction)
+	}
+	fn is_instruction_valid(&self, config: &Self::Config, instruction: Self::Instruction) -> bool {
+		match instruction {
+			SessionInstruction::Undo => !self.history.is_empty(),
+			SessionInstruction::InnerInstruction(instruction) => {
+				self.state.is_instruction_valid(&config.inner, instruction)
+			}
+		}
+	}
+	fn process_instruction(
+		&mut self,
+		stats: &mut Self::Stats,
+		config: &Self::Config,
+		instruction: Self::Instruction,
+	) {
+		match instruction {
+			SessionInstruction::Undo => {
+				if let Some(snapshot) = self.history.pop() {
+					self.state = snapshot.state;
+					stats.increment_undos();
+				}
+			}
+			SessionInstruction::InnerInstruction(instruction) => {
+				self.history.push(StateSnapshot {
+					state: self.state.clone(),
+					instruction: instruction.clone(),
+				});
+				self.state
+					.process_instruction(&mut stats.inner, &config.inner, instruction);
+			}
+		}
+	}
+	fn is_win(&self) -> bool {
+		self.state.is_win()
+	}
+}
+
+#[cfg(feature = "serde")]
+impl<'de, G: Game<Score = i32>> serde::de::Deserialize<'de> for Session<G>
+where
+	G: serde::Deserialize<'de> + Clone + Eq + core::hash::Hash,
+	G::Stats: Default,
+	G::Instruction: serde::Deserialize<'de> + Eq + core::hash::Hash,
+	SessionConfig<G::Config>: serde::Deserialize<'de>,
+	Vec<G::Instruction>: serde::Deserialize<'de>,
+{
+	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+	where
+		D: serde::Deserializer<'de>,
+	{
+		#[derive(serde_derive::Deserialize)]
+		#[serde(bound(deserialize = "
+			G: serde::Deserialize<'de>,
+			SessionConfig<G::Config>: serde::Deserialize<'de>,
+			Vec<G::Instruction>: serde::Deserialize<'de>,
+		"))]
+		struct SerializedSession<G: Game> {
+			config: SessionConfig<G::Config>,
+			initial_state: G,
+			instructions: Vec<G::Instruction>,
+		}
+		let serialized = SerializedSession::deserialize(deserializer)?;
+		let mut session = Session::new(serialized.initial_state, serialized.config);
+		for instruction in serialized.instructions {
+			session.process_instruction(instruction);
+		}
+		Ok(session)
+	}
+}
+#[cfg(feature = "serde")]
+impl<G: Game> serde::Serialize for Session<G>
+where
+	G: serde::Serialize,
+	G::Config: serde::Serialize,
+	G::Instruction: serde::Serialize,
+{
+	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+	where
+		S: serde::Serializer,
+	{
+		struct History<'a, G: Game>(&'a [StateSnapshot<G>]);
+		impl<G: Game> serde::Serialize for History<'_, G>
+		where
+			G: serde::Serialize,
+			G::Instruction: serde::Serialize,
+		{
+			fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+			where
+				S: serde::Serializer,
+			{
+				let &History(history) = self;
+				use serde::ser::SerializeSeq;
+				let mut seq = serializer.serialize_seq(Some(history.len()))?;
+				for snapshot in history {
+					seq.serialize_element(&snapshot.instruction)?;
+				}
+				seq.end()
+			}
+		}
+
+		#[derive(serde_derive::Serialize)]
+		#[serde(bound(serialize = "
+			G: serde::Serialize,
+			SessionConfig<G::Config>: serde::Serialize,
+			G::Instruction: serde::Serialize,
+		"))]
+		struct SerializedSession<'a, G: Game> {
+			config: &'a SessionConfig<G::Config>,
+			initial_state: &'a G,
+			instructions: History<'a, G>,
+		}
+
+		// serialize the initial state of the game.
+		// if there is history, it is the first snapshot's state,
+		// otherwise it is the current game state since there are no moves.
+		let initial_state = if let Some(snapshot) = self.state.history.first() {
+			snapshot.state()
+		} else {
+			&self.state.state
+		};
+		let session = SerializedSession {
+			config: &self.config,
+			initial_state,
+			instructions: History(&self.state.history),
+		};
+		session.serialize(serializer)
+	}
+}

klondike-bench/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "klondike-bench"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+card_game.workspace = true
+klondike.workspace = true
+rand = { version = "0.10.1", default-features = false }
+
+[lints]
+workspace = true

klondike-bench/src/main.rs

@@ -0,0 +1,48 @@
+use card_game::Game;
+use klondike::{Klondike, KlondikeConfig, KlondikeStats, Rng, ScoringConfig};
+
+const MAX_MOVES: usize = 250;
+
+fn play_to_win(rng: &mut Rng) -> Option<KlondikeStats> {
+	// create game session
+	let mut game = Klondike::with_rng(rng);
+	let mut stats = KlondikeStats::new();
+	const CONFIG: KlondikeConfig = KlondikeConfig {
+		draw_stock: klondike::DrawStockConfig::DrawOne,
+		move_from_foundation: klondike::MoveFromFoundationConfig::Allowed,
+		scoring: ScoringConfig::DEFAULT,
+	};
+	// play game a bit
+	while let Some(instruction) = game.get_auto_move(&CONFIG)
+		&& !game.is_win()
+	{
+		// quit before 250 moves
+		if (MAX_MOVES as u32) < stats.moves() + 1 {
+			return None;
+		}
+
+		game.process_instruction(&mut stats, &CONFIG, instruction);
+	}
+	game.is_win().then_some(stats)
+}
+fn main() {
+	use rand::SeedableRng;
+	let mut rng = Rng::seed_from_u64(0);
+	const GAMES: u32 = 1000;
+	let mut wins = 0;
+	let mut score_tally = [0usize; MAX_MOVES * 10 / 5];
+	let mut recycle_tally = [0usize; MAX_MOVES];
+	let mut moves_tally = [0usize; MAX_MOVES];
+	for _ in 0..GAMES {
+		if let Some(stats) = play_to_win(&mut rng) {
+			wins += 1;
+			score_tally[(stats.score(&ScoringConfig::DEFAULT) / 5) as usize] += 1;
+			recycle_tally[stats.recycle_count() as usize] += 1;
+			moves_tally[stats.moves() as usize] += 1;
+		}
+	}
+	println!("score_tally={score_tally:?}");
+	println!("recycle_tally={recycle_tally:?}");
+	println!("moves_tally={moves_tally:?}");
+	println!("wins = {wins}/{GAMES} win_rate = {}%", wins * 100 / GAMES);
+}

klondike-cli/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "klondike-cli"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+card_game.workspace = true
+klondike.workspace = true
+rand = { version = "0.10.1", default-features = false, features = ["thread_rng"] }
+
+[lints]
+workspace = true

klondike-cli/src/main.rs

@@ -0,0 +1,301 @@
+use card_game::{Card, Game, Pile, Rank, Session, Suit};
+use klondike::{
+	DstFoundation, DstTableau, Foundation, Klondike, KlondikeConfig, KlondikeInstruction,
+	KlondikePile, KlondikePileStack, SkipCards, Tableau, TableauStack,
+};
+
+use std::fmt::Display;
+struct Displayed<T>(T);
+
+impl Display for Displayed<&Card> {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		match self.0.rank() {
+			Rank::Ace => write!(f, " A"),
+			Rank::Jack => write!(f, " J"),
+			Rank::Queen => write!(f, " Q"),
+			Rank::King => write!(f, " K"),
+			other => write!(f, "{:>2}", other as u8),
+		}?;
+		match self.0.suit() {
+			Suit::Spades => write!(f, "♠"),
+			Suit::Hearts => write!(f, "♡"),
+			Suit::Clubs => write!(f, "♣"),
+			Suit::Diamonds => write!(f, "♢"),
+		}
+	}
+}
+
+struct OptionalCard<'a>(Option<&'a Card>);
+impl Display for OptionalCard<'_> {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		match self {
+			&OptionalCard(Some(card)) => write!(f, "{}", Displayed(card)),
+			OptionalCard(None) => write!(f, " []"),
+		}
+	}
+}
+
+impl Display for Displayed<&Klondike> {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		// Stock
+		let stock_count = self.0.state().stock().face_down().len();
+
+		// Hand
+		let hand = self.0.state().stock().face_up().last();
+
+		// Foundations
+		writeln!(f, " STOCK       F1  F2  F3  F4")?;
+		write!(
+			f,
+			" {:>2} {}     {} {} {} {}",
+			stock_count,
+			OptionalCard(hand),
+			OptionalCard(self.0.state().foundation1().last()),
+			OptionalCard(self.0.state().foundation2().last()),
+			OptionalCard(self.0.state().foundation3().last()),
+			OptionalCard(self.0.state().foundation4().last()),
+		)?;
+		writeln!(f)?;
+
+		writeln!(f, " T1  T2  T3  T4  T5  T6  T7")?;
+
+		fn write_pile_card<const DN: usize, const UP: usize>(
+			f: &mut std::fmt::Formatter<'_>,
+			pile: &Pile<DN, UP>,
+			row: usize,
+		) -> std::fmt::Result {
+			if let Some(_card) = pile.face_down().get(row) {
+				return write!(f, " ⎾⏋"); // └┘ ⨽⨼ ⫭⫬
+			}
+			let Some(row) = row.checked_sub(pile.face_down().len()) else {
+				return write!(f, "   ");
+			};
+			if let Some(card) = pile.face_up().get(row) {
+				return write!(f, "{}", Displayed(card));
+			}
+			write!(f, "   ")
+		}
+
+		fn write_row(
+			f: &mut std::fmt::Formatter<'_>,
+			game: &Klondike,
+			row: usize,
+		) -> std::fmt::Result {
+			write_pile_card(f, game.state().tableau1(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau2(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau3(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau4(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau5(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau6(), row)?;
+			write!(f, " ")?;
+			write_pile_card(f, game.state().tableau7(), row)?;
+			writeln!(f)
+		}
+
+		for row in 0..7 + 13 {
+			write_row(f, self.0, row)?;
+		}
+
+		Ok(())
+	}
+}
+
+struct DisplayStats<'a>(&'a Session<Klondike>);
+impl Display for DisplayStats<'_> {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		write!(
+			f,
+			"recycles: {} moves: {} undos: {} score:{}",
+			self.0.stats().stats().recycle_count(),
+			self.0.stats().stats().moves(),
+			self.0.stats().undos(),
+			self.0.state().score(self.0.stats(), self.0.config()),
+		)
+	}
+}
+
+#[derive(Debug)]
+struct Invalid;
+struct Parsed<T>(T);
+struct NaiveInstruction {
+	src: KlondikePile,
+	dst: KlondikePile,
+}
+impl core::str::FromStr for NaiveInstruction {
+	type Err = Invalid;
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		let Parsed(src) = s.get(0..2).ok_or(Invalid)?.parse()?;
+		let Parsed(dst) = s.get(3..5).ok_or(Invalid)?.parse()?;
+		Ok(NaiveInstruction { src, dst })
+	}
+}
+impl core::str::FromStr for Parsed<KlondikePile> {
+	type Err = Invalid;
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(Parsed(match s {
+			"st" => KlondikePile::Stock,
+			"t1" => KlondikePile::Tableau(Tableau::Tableau1),
+			"t2" => KlondikePile::Tableau(Tableau::Tableau2),
+			"t3" => KlondikePile::Tableau(Tableau::Tableau3),
+			"t4" => KlondikePile::Tableau(Tableau::Tableau4),
+			"t5" => KlondikePile::Tableau(Tableau::Tableau5),
+			"t6" => KlondikePile::Tableau(Tableau::Tableau6),
+			"t7" => KlondikePile::Tableau(Tableau::Tableau7),
+			"f1" => KlondikePile::Foundation(Foundation::Foundation1),
+			"f2" => KlondikePile::Foundation(Foundation::Foundation2),
+			"f3" => KlondikePile::Foundation(Foundation::Foundation3),
+			"f4" => KlondikePile::Foundation(Foundation::Foundation4),
+			_ => return Err(Invalid),
+		}))
+	}
+}
+
+enum SessionInstruction {
+	New,
+	Undo,
+	Hint,
+	Auto,
+	Stock,
+	Exit,
+	Klondike(NaiveInstruction),
+}
+impl core::str::FromStr for SessionInstruction {
+	type Err = Invalid;
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		Ok(match s {
+			"new" | "n" => Self::New,
+			"undo" | "u" => Self::Undo,
+			"hint" | "h" => Self::Hint,
+			"auto" | "a" | "" => Self::Auto,
+			"exit" => Self::Exit,
+			"s" => Self::Stock,
+			other => Self::Klondike(other.parse()?),
+		})
+	}
+}
+
+fn find_valid_instruction(
+	config: &KlondikeConfig,
+	state: &Klondike,
+	naive_instruction: NaiveInstruction,
+) -> Option<KlondikeInstruction> {
+	const SKIP_LIST: [SkipCards; 13] = [
+		SkipCards::Skip0,
+		SkipCards::Skip1,
+		SkipCards::Skip2,
+		SkipCards::Skip3,
+		SkipCards::Skip4,
+		SkipCards::Skip5,
+		SkipCards::Skip6,
+		SkipCards::Skip7,
+		SkipCards::Skip8,
+		SkipCards::Skip9,
+		SkipCards::Skip10,
+		SkipCards::Skip11,
+		SkipCards::Skip12,
+	];
+	let instruction = match (naive_instruction.dst, naive_instruction.src) {
+		(KlondikePile::Tableau(tableau), src) => {
+			let src = match src {
+				KlondikePile::Tableau(src_tableau) => {
+					for skip_cards in SKIP_LIST {
+						let src = KlondikePileStack::Tableau(TableauStack {
+							tableau: src_tableau,
+							skip_cards,
+						});
+						let instruction =
+							KlondikeInstruction::DstTableau(DstTableau { tableau, src });
+						if state.is_instruction_valid(config, instruction) {
+							return Some(instruction);
+						}
+					}
+					return None;
+				}
+				KlondikePile::Stock => KlondikePileStack::Stock,
+				KlondikePile::Foundation(foundation) => KlondikePileStack::Foundation(foundation),
+			};
+			KlondikeInstruction::DstTableau(DstTableau { tableau, src })
+		}
+		(KlondikePile::Stock, KlondikePile::Stock) => KlondikeInstruction::RotateStock,
+		(KlondikePile::Foundation(foundation), src) => {
+			KlondikeInstruction::DstFoundation(DstFoundation { foundation, src })
+		}
+		_ => return None,
+	};
+	state
+		.is_instruction_valid(config, instruction)
+		.then_some(instruction)
+}
+
+fn main() -> Result<(), std::io::Error> {
+	use rand::RngExt;
+	let mut rng = rand::rng();
+	// seed from cli argument
+	let mut seed = if let Some(seed) = std::env::args().nth(1) {
+		seed.parse().expect("Invalid u64 seed")
+	} else {
+		rng.random()
+	};
+	let mut session = Session::new_default(Klondike::with_seed(seed));
+	let mut input = String::new();
+	loop {
+		// display stats
+		println!("seed: {seed} ");
+		println!("{}", DisplayStats(&session));
+		// display game
+		println!("{}", Displayed(session.state().state()));
+
+		// parse input
+		input.clear();
+		std::io::stdin().read_line(&mut input)?;
+		let Ok(instruction) = input.trim().parse() else {
+			println!("Invalid instruction.");
+			continue;
+		};
+
+		// run game
+		match instruction {
+			SessionInstruction::New => {
+				seed = rng.random();
+				session = Session::new_default(Klondike::with_seed(seed))
+			}
+			SessionInstruction::Undo => session.undo(),
+			SessionInstruction::Exit => break Ok(()),
+			SessionInstruction::Hint => {
+				for instruction in session.possible_instructions() {
+					println!("{instruction:?}");
+				}
+			}
+			SessionInstruction::Auto => {
+				if let Some(instruction) = session
+					.state()
+					.state()
+					.get_auto_move(&session.config().inner)
+				{
+					session.process_instruction(instruction);
+				} else {
+					println!("No valid moves!");
+				}
+			}
+			SessionInstruction::Stock => {
+				session.process_instruction(KlondikeInstruction::RotateStock)
+			}
+			SessionInstruction::Klondike(naive_instruction) => {
+				if let Some(instruction) = find_valid_instruction(
+					&session.config().inner,
+					session.state().state(),
+					naive_instruction,
+				) {
+					session.process_instruction(instruction);
+				} else {
+					println!("Invalid move!");
+				}
+			}
+		}
+	}
+}

klondike/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "klondike"
+version = "0.4.0"
+edition = "2024"
+
+[dependencies]
+card_game.workspace = true
+rand = { version = "0.10.1", default-features = false, features = ["std_rng"] }
+serde = { version = "1.0.228", default-features = false, optional = true }
+serde_derive = { version = "1.0.228", default-features = false, optional = true }
+
+[dev-dependencies]
+insta = "1.47.2"
+rmp-serde = "1.3.1"
+serde = { version = "1.0.228", default-features = false }
+serde_json = "1.0.149"
+
+[lints]
+workspace = true
+
+[features]
+default = ["serde"]
+serde = ["dep:serde", "dep:serde_derive", "card_game/serde"]

klondike/LICENSE-APACHE

@@ -0,0 +1,176 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

klondike/LICENSE-MIT

@@ -0,0 +1,23 @@
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

klondike/README.md

@@ -0,0 +1,51 @@
+Klondike
+========
+
+`klondike` is a pure-logic implementation of Klondike using `card_game`.  Graphics not included.
+
+## Example
+
+```rust
+use card_game::Session;
+use klondike::{Klondike, KlondikeConfig};
+
+// create game session
+let game = Klondike::with_seed(123);
+let config = KlondikeConfig::default();
+let mut session = Session::new_default(game);
+
+// play game a bit
+while let Some(instruction) = session.state().state().get_auto_move(&config) {
+	session.process_instruction(instruction);
+
+	// quit after 200 moves or win
+	if session.is_win() || 200 < session.stats().stats().moves() {
+		break;
+	}
+}
+
+// did win
+let is_win = session.is_win();
+
+// print session history
+for (i, instruction) in session.history().iter().enumerate() {
+	println!("move {i} = {instruction:?}");
+}
+
+println!("is_win = {is_win}");
+```
+
+#### License
+
+<sup>
+Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
+2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
+</sup>
+
+<br>
+
+<sub>
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
+</sub>

klondike/src/lib.rs

@@ -0,0 +1,852 @@
+pub type Rng = rand::rngs::StdRng;
+
+use card_game::{Card, Game, Pile, Rank, Stack};
+
+#[cfg(test)]
+mod test;
+
+// test readme
+#[doc = include_str!("../README.md")]
+#[cfg(doctest)]
+struct ReadmeDoctests;
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum DrawStockConfig {
+	#[default]
+	DrawOne = 1,
+	DrawThree = 3,
+}
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum MoveFromFoundationConfig {
+	#[default]
+	Allowed,
+	Disallowed,
+}
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+#[derive(Clone, Copy, Debug)]
+pub struct ScoringConfig {
+	pub move_to_foundation: i32,
+	pub flip_up_bonus: i32,
+	pub move_to_tableau: i32,
+	pub move_from_foundation: i32,
+	pub recycle: i32,
+}
+impl ScoringConfig {
+	pub const DEFAULT: Self = Self {
+		move_to_foundation: 10,
+		flip_up_bonus: 5,
+		move_to_tableau: 5,
+		move_from_foundation: -15,
+		recycle: 0,
+	};
+}
+impl Default for ScoringConfig {
+	fn default() -> Self {
+		Self::DEFAULT
+	}
+}
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+#[derive(Clone, Debug, Default)]
+pub struct KlondikeConfig {
+	pub draw_stock: DrawStockConfig,
+	pub move_from_foundation: MoveFromFoundationConfig,
+	pub scoring: ScoringConfig,
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct KlondikeStats {
+	moves: u32,
+	move_to_foundation_count: u32,
+	flip_up_bonus_count: u32,
+	move_to_tableau_count: u32,
+	move_from_foundation_count: u32,
+	recycle_count: u32,
+}
+impl KlondikeStats {
+	pub const fn new() -> Self {
+		KlondikeStats {
+			moves: 0,
+			move_to_foundation_count: 0,
+			flip_up_bonus_count: 0,
+			move_to_tableau_count: 0,
+			move_from_foundation_count: 0,
+			recycle_count: 0,
+		}
+	}
+	pub const fn score(&self, config: &ScoringConfig) -> i32 {
+		self.move_to_foundation_count as i32 * config.move_to_foundation
+			+ self.flip_up_bonus_count as i32 * config.flip_up_bonus
+			+ self.move_to_tableau_count as i32 * config.move_to_tableau
+			+ self.move_from_foundation_count as i32 * config.move_from_foundation
+			+ self.recycle_count as i32 * config.recycle
+	}
+	pub const fn moves(&self) -> u32 {
+		self.moves
+	}
+	pub const fn move_to_foundation_count(&self) -> u32 {
+		self.move_to_foundation_count
+	}
+	pub const fn flip_up_bonus_count(&self) -> u32 {
+		self.flip_up_bonus_count
+	}
+	pub const fn move_to_tableau_count(&self) -> u32 {
+		self.move_to_tableau_count
+	}
+	pub const fn move_from_foundation_count(&self) -> u32 {
+		self.move_from_foundation_count
+	}
+	pub const fn recycle_count(&self) -> u32 {
+		self.recycle_count
+	}
+	/// A card was moved to a foundation.
+	const fn increment_move_to_foundation(&mut self) {
+		self.move_to_foundation_count += 1;
+	}
+	/// A card on the tableau was flipped up.
+	const fn increment_flip_up_bonus(&mut self) {
+		self.flip_up_bonus_count += 1;
+	}
+	/// A card was moved from stock to tableau.
+	const fn increment_move_to_tableau(&mut self) {
+		self.move_to_tableau_count += 1;
+	}
+	/// A card was moved from foundation to tableau.
+	const fn increment_move_from_foundation(&mut self) {
+		self.move_from_foundation_count += 1;
+	}
+	const fn increment_recycle_count(&mut self) {
+		self.recycle_count += 1;
+	}
+	const fn increment_moves(&mut self) {
+		self.moves += 1;
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum Tableau {
+	Tableau1,
+	Tableau2,
+	Tableau3,
+	Tableau4,
+	Tableau5,
+	Tableau6,
+	Tableau7,
+}
+impl Tableau {
+	const ITER_BEGIN: Self = Self::Tableau1;
+	const fn next(self) -> Option<Self> {
+		use Tableau::*;
+		Some(match self {
+			Tableau1 => Tableau2,
+			Tableau2 => Tableau3,
+			Tableau3 => Tableau4,
+			Tableau4 => Tableau5,
+			Tableau5 => Tableau6,
+			Tableau6 => Tableau7,
+			Tableau7 => return None,
+		})
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum Foundation {
+	Foundation1,
+	Foundation2,
+	Foundation3,
+	Foundation4,
+}
+impl Foundation {
+	const ITER_BEGIN: Self = Self::Foundation1;
+	const fn next(self) -> Option<Self> {
+		use Foundation::*;
+		Some(match self {
+			Foundation1 => Foundation2,
+			Foundation2 => Foundation3,
+			Foundation3 => Foundation4,
+			Foundation4 => return None,
+		})
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum KlondikePile {
+	Tableau(Tableau),
+	Stock,
+	Foundation(Foundation),
+}
+impl KlondikePile {
+	const ITER_BEGIN: Self = Self::Tableau(Tableau::ITER_BEGIN);
+	const fn next(self) -> Option<Self> {
+		Some(match self {
+			Self::Tableau(tableau_stack) => match tableau_stack.next() {
+				Some(tableau_stack) => Self::Tableau(tableau_stack),
+				None => Self::Stock,
+			},
+			Self::Stock => Self::Foundation(Foundation::ITER_BEGIN),
+			Self::Foundation(foundation) => match foundation.next() {
+				Some(foundation) => Self::Foundation(foundation),
+				None => return None,
+			},
+		})
+	}
+}
+impl From<Tableau> for KlondikePile {
+	fn from(value: Tableau) -> Self {
+		KlondikePile::Tableau(value)
+	}
+}
+impl From<Foundation> for KlondikePile {
+	fn from(value: Foundation) -> Self {
+		KlondikePile::Foundation(value)
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum SkipCards {
+	Skip0,
+	Skip1,
+	Skip2,
+	Skip3,
+	Skip4,
+	Skip5,
+	Skip6,
+	Skip7,
+	Skip8,
+	Skip9,
+	Skip10,
+	Skip11,
+	Skip12,
+}
+impl SkipCards {
+	const ITER_BEGIN: Self = Self::Skip0;
+	const fn next(self) -> Option<Self> {
+		use SkipCards::*;
+		Some(match self {
+			Skip0 => Skip1,
+			Skip1 => Skip2,
+			Skip2 => Skip3,
+			Skip3 => Skip4,
+			Skip4 => Skip5,
+			Skip5 => Skip6,
+			Skip6 => Skip7,
+			Skip7 => Skip8,
+			Skip8 => Skip9,
+			Skip9 => Skip10,
+			Skip10 => Skip11,
+			Skip11 => Skip12,
+			Skip12 => return None,
+		})
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct TableauStack {
+	pub tableau: Tableau,
+	pub skip_cards: SkipCards,
+}
+
+impl TableauStack {
+	const ITER_BEGIN: Self = Self {
+		tableau: Tableau::ITER_BEGIN,
+		skip_cards: SkipCards::ITER_BEGIN,
+	};
+	const fn next(self) -> Option<Self> {
+		let TableauStack {
+			tableau,
+			skip_cards,
+		} = self;
+		if let Some(skip_cards) = skip_cards.next() {
+			return Some(Self {
+				tableau,
+				skip_cards,
+			});
+		}
+		if let Some(tableau) = tableau.next() {
+			let skip_cards = SkipCards::ITER_BEGIN;
+			return Some(Self {
+				tableau,
+				skip_cards,
+			});
+		}
+		None
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum KlondikePileStack {
+	Tableau(TableauStack),
+	Stock,
+	Foundation(Foundation),
+}
+impl KlondikePileStack {
+	const ITER_BEGIN: Self = Self::Tableau(TableauStack::ITER_BEGIN);
+	const fn next(self) -> Option<Self> {
+		Some(match self {
+			Self::Tableau(tableau_stack) => match tableau_stack.next() {
+				Some(tableau_stack) => Self::Tableau(tableau_stack),
+				None => Self::Stock,
+			},
+			Self::Stock => Self::Foundation(Foundation::ITER_BEGIN),
+			Self::Foundation(foundation) => match foundation.next() {
+				Some(foundation) => Self::Foundation(foundation),
+				None => return None,
+			},
+		})
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct DstFoundation {
+	pub src: KlondikePile,
+	pub foundation: Foundation,
+}
+impl DstFoundation {
+	const ITER_BEGIN: Self = Self {
+		src: KlondikePile::ITER_BEGIN,
+		foundation: Foundation::ITER_BEGIN,
+	};
+	const fn next(self) -> Option<Self> {
+		let DstFoundation { src, foundation } = self;
+		if let Some(src) = src.next() {
+			return Some(Self { src, foundation });
+		}
+		if let Some(foundation) = foundation.next() {
+			let src = KlondikePile::ITER_BEGIN;
+			return Some(Self { src, foundation });
+		}
+		None
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct DstTableau {
+	pub src: KlondikePileStack,
+	pub tableau: Tableau,
+}
+impl DstTableau {
+	const ITER_BEGIN: Self = Self {
+		src: KlondikePileStack::ITER_BEGIN,
+		tableau: Tableau::ITER_BEGIN,
+	};
+	const fn next(self) -> Option<Self> {
+		let DstTableau { src, tableau } = self;
+		if let Some(src) = src.next() {
+			return Some(Self { src, tableau });
+		}
+		if let Some(tableau) = tableau.next() {
+			let src = KlondikePileStack::ITER_BEGIN;
+			return Some(Self { src, tableau });
+		}
+		None
+	}
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum KlondikeInstruction {
+	DstFoundation(DstFoundation),
+	DstTableau(DstTableau),
+	RotateStock,
+}
+impl KlondikeInstruction {
+	const ITER_BEGIN: Self = Self::DstFoundation(DstFoundation::ITER_BEGIN);
+	const fn next(self) -> Option<Self> {
+		Some(match self {
+			Self::DstFoundation(dst_foundation) => match dst_foundation.next() {
+				Some(dst_foundation) => Self::DstFoundation(dst_foundation),
+				None => Self::DstTableau(DstTableau::ITER_BEGIN),
+			},
+			Self::DstTableau(tableau) => match tableau.next() {
+				Some(tableau) => Self::DstTableau(tableau),
+				None => Self::RotateStock,
+			},
+			Self::RotateStock => return None,
+		})
+	}
+	/// foundation -> foundation is a useless move
+	pub fn is_useless(&self) -> bool {
+		matches!(
+			self,
+			KlondikeInstruction::DstFoundation(DstFoundation {
+				src: KlondikePile::Foundation(_),
+				..
+			})
+		)
+	}
+}
+
+const TABLEAUS: usize = 7;
+const fn sum(n: usize) -> usize {
+	n * (n + 1) / 2
+}
+const STOCK: usize = 52 - sum(TABLEAUS);
+const NUM_RANKS: usize = Rank::RANKS.len();
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize)
+)]
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct KlondikeState {
+	stock: Pile<STOCK, STOCK>,
+	foundations: [Stack<NUM_RANKS>; 4],
+	tableau1: Pile<0, NUM_RANKS>,
+	tableau2: Pile<1, NUM_RANKS>,
+	tableau3: Pile<2, NUM_RANKS>,
+	tableau4: Pile<3, NUM_RANKS>,
+	tableau5: Pile<4, NUM_RANKS>,
+	tableau6: Pile<5, NUM_RANKS>,
+	tableau7: Pile<6, NUM_RANKS>,
+}
+impl KlondikeState {
+	pub const fn stock(&self) -> &Pile<STOCK, STOCK> {
+		&self.stock
+	}
+	pub const fn foundation1(&self) -> &Stack<NUM_RANKS> {
+		&self.foundations[Foundation::Foundation1 as usize]
+	}
+	pub const fn foundation2(&self) -> &Stack<NUM_RANKS> {
+		&self.foundations[Foundation::Foundation2 as usize]
+	}
+	pub const fn foundation3(&self) -> &Stack<NUM_RANKS> {
+		&self.foundations[Foundation::Foundation3 as usize]
+	}
+	pub const fn foundation4(&self) -> &Stack<NUM_RANKS> {
+		&self.foundations[Foundation::Foundation4 as usize]
+	}
+	pub const fn tableau1(&self) -> &Pile<0, NUM_RANKS> {
+		&self.tableau1
+	}
+	pub const fn tableau2(&self) -> &Pile<1, NUM_RANKS> {
+		&self.tableau2
+	}
+	pub const fn tableau3(&self) -> &Pile<2, NUM_RANKS> {
+		&self.tableau3
+	}
+	pub const fn tableau4(&self) -> &Pile<3, NUM_RANKS> {
+		&self.tableau4
+	}
+	pub const fn tableau5(&self) -> &Pile<4, NUM_RANKS> {
+		&self.tableau5
+	}
+	pub const fn tableau6(&self) -> &Pile<5, NUM_RANKS> {
+		&self.tableau6
+	}
+	pub const fn tableau7(&self) -> &Pile<6, NUM_RANKS> {
+		&self.tableau7
+	}
+	pub fn tableau_face_down_cards(&self, tableau: Tableau) -> &[Card] {
+		match tableau {
+			Tableau::Tableau1 => self.tableau1.face_down(),
+			Tableau::Tableau2 => self.tableau2.face_down(),
+			Tableau::Tableau3 => self.tableau3.face_down(),
+			Tableau::Tableau4 => self.tableau4.face_down(),
+			Tableau::Tableau5 => self.tableau5.face_down(),
+			Tableau::Tableau6 => self.tableau6.face_down(),
+			Tableau::Tableau7 => self.tableau7.face_down(),
+		}
+	}
+	pub fn tableau_face_up_cards(&self, tableau: Tableau) -> &[Card] {
+		match tableau {
+			Tableau::Tableau1 => self.tableau1.face_up(),
+			Tableau::Tableau2 => self.tableau2.face_up(),
+			Tableau::Tableau3 => self.tableau3.face_up(),
+			Tableau::Tableau4 => self.tableau4.face_up(),
+			Tableau::Tableau5 => self.tableau5.face_up(),
+			Tableau::Tableau6 => self.tableau6.face_up(),
+			Tableau::Tableau7 => self.tableau7.face_up(),
+		}
+	}
+	pub fn stack_bottom_card(&self, src: KlondikePileStack) -> Option<&Card> {
+		match src {
+			KlondikePileStack::Tableau(TableauStack {
+				tableau,
+				skip_cards,
+			}) => self.tableau_face_up_cards(tableau).get(skip_cards as usize),
+			KlondikePileStack::Foundation(foundation) => {
+				self.foundations[foundation as usize].last()
+			}
+			KlondikePileStack::Stock => self.stock.face_up().last(),
+		}
+	}
+	pub fn tableau_top_card(&self, tableau: Tableau) -> Option<&Card> {
+		self.tableau_face_up_cards(tableau).last()
+	}
+	pub fn foundation_top_card(&self, foundation: Foundation) -> Option<&Card> {
+		self.foundations[foundation as usize].last()
+	}
+	pub fn top_card(&self, pile: KlondikePile) -> Option<&Card> {
+		match pile {
+			KlondikePile::Tableau(tableau) => self.tableau_top_card(tableau),
+			KlondikePile::Foundation(foundation) => self.foundation_top_card(foundation),
+			KlondikePile::Stock => self.stock.face_up().last(),
+		}
+	}
+	fn take_stack_flip_up(&mut self, src: KlondikePileStack) -> (Stack<NUM_RANKS>, bool) {
+		match src {
+			KlondikePileStack::Tableau(TableauStack {
+				tableau,
+				skip_cards,
+			}) => match tableau {
+				Tableau::Tableau1 => self.tableau1.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau2 => self.tableau2.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau3 => self.tableau3.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau4 => self.tableau4.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau5 => self.tableau5.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau6 => self.tableau6.take_range_flip_up(skip_cards as usize..),
+				Tableau::Tableau7 => self.tableau7.take_range_flip_up(skip_cards as usize..),
+			},
+			KlondikePileStack::Foundation(foundation) => (
+				Stack::from_iter(self.foundations[foundation as usize].pop()),
+				false,
+			),
+			KlondikePileStack::Stock => (Stack::from_iter(self.stock.pop()), false),
+		}
+	}
+	fn take_top_card_flip_up(&mut self, pile: KlondikePile) -> (Option<Card>, bool) {
+		match pile {
+			KlondikePile::Tableau(tableau) => match tableau {
+				Tableau::Tableau1 => self.tableau1.pop_flip_up(),
+				Tableau::Tableau2 => self.tableau2.pop_flip_up(),
+				Tableau::Tableau3 => self.tableau3.pop_flip_up(),
+				Tableau::Tableau4 => self.tableau4.pop_flip_up(),
+				Tableau::Tableau5 => self.tableau5.pop_flip_up(),
+				Tableau::Tableau6 => self.tableau6.pop_flip_up(),
+				Tableau::Tableau7 => self.tableau7.pop_flip_up(),
+			},
+			KlondikePile::Foundation(foundation) => {
+				(self.foundations[foundation as usize].pop(), false)
+			}
+			KlondikePile::Stock => (self.stock.pop(), false),
+		}
+	}
+	fn extend_foundation<I: IntoIterator<Item = Card>>(
+		&mut self,
+		foundation: Foundation,
+		cards: I,
+	) {
+		self.foundations[foundation as usize].extend(cards)
+	}
+	fn extend_tableau<I: IntoIterator<Item = Card>>(&mut self, tableau: Tableau, cards: I) {
+		match tableau {
+			Tableau::Tableau1 => self.tableau1.extend(cards),
+			Tableau::Tableau2 => self.tableau2.extend(cards),
+			Tableau::Tableau3 => self.tableau3.extend(cards),
+			Tableau::Tableau4 => self.tableau4.extend(cards),
+			Tableau::Tableau5 => self.tableau5.extend(cards),
+			Tableau::Tableau6 => self.tableau6.extend(cards),
+			Tableau::Tableau7 => self.tableau7.extend(cards),
+		}
+	}
+	pub fn is_instruction_valid(
+		&self,
+		config: &KlondikeConfig,
+		instruction: KlondikeInstruction,
+	) -> bool {
+		match instruction {
+			// Stock -> Stock draws a card or resets the stock
+			KlondikeInstruction::RotateStock => {
+				// cannot move stock when stock is empty
+				!self.stock.is_empty()
+			}
+
+			// moving to foundation has special rules
+			KlondikeInstruction::DstFoundation(dst_foundation) => {
+				// get the top cards
+				if let Some(src_card) = self.top_card(dst_foundation.src) {
+					match self.foundation_top_card(dst_foundation.foundation) {
+						// destination card exists
+						Some(dst_card) => {
+							// suit matches?
+							src_card.suit() == dst_card.suit()
+							// value is +1?
+							&& dst_card.rank().checked_add(1) == Some(src_card.rank())
+						}
+						// only ace is allowed to go onto empty foundation
+						None => src_card.rank() == Rank::Ace,
+					}
+				} else {
+					false
+				}
+			}
+			// other = move to tableau
+			KlondikeInstruction::DstTableau(dst_tableau) => {
+				if config.move_from_foundation == MoveFromFoundationConfig::Disallowed
+					&& let KlondikePileStack::Foundation(_) = dst_tableau.src
+				{
+					return false;
+				}
+				// get the cards
+				if let Some(src_card) = self.stack_bottom_card(dst_tableau.src) {
+					match self.tableau_top_card(dst_tableau.tableau) {
+						// destination card exists
+						Some(dst_card) => {
+							// red-ness is opposite?
+							src_card.is_red() != dst_card.is_red()
+							// value is -1?
+							&& dst_card.rank().checked_sub(1) == Some(src_card.rank())
+						}
+						// only king is allowed to go onto empty tableau
+						None => src_card.rank() == Rank::King,
+					}
+				} else {
+					false
+				}
+			}
+		}
+	}
+}
+
+pub struct KlondikeIter {
+	instruction: Option<KlondikeInstruction>,
+}
+impl KlondikeIter {
+	const fn new() -> Self {
+		Self {
+			instruction: Some(KlondikeInstruction::ITER_BEGIN),
+		}
+	}
+}
+impl Iterator for KlondikeIter {
+	type Item = KlondikeInstruction;
+	fn next(&mut self) -> Option<Self::Item> {
+		let instruction = self.instruction;
+		self.instruction = instruction?.next();
+		instruction
+	}
+}
+#[test]
+fn test_klondike_iter() {
+	assert_eq!(KlondikeIter::new().count(), 721);
+}
+
+#[cfg_attr(
+	feature = "serde",
+	derive(serde_derive::Deserialize, serde_derive::Serialize),
+	serde(transparent)
+)]
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct Klondike {
+	state: KlondikeState,
+}
+impl Klondike {
+	pub fn with_seed(seed: u64) -> Self {
+		use rand::SeedableRng;
+		let mut rng = Rng::seed_from_u64(seed);
+		Self::with_rng(&mut rng)
+	}
+	pub fn with_rng(rng: &mut Rng) -> Self {
+		// shuffle a new deck
+		let mut deck = Stack::full_deck(card_game::Deck::Deck1);
+		use rand::seq::SliceRandom;
+		deck.shuffle(rng);
+		let mut deck = deck.into_iter();
+
+		// generate tableaus
+		fn pile<const DN: usize>(
+			deck: &mut <Stack<52> as IntoIterator>::IntoIter,
+		) -> Pile<DN, NUM_RANKS> {
+			let stack = Stack::from_iter(deck.take(DN));
+			let mut pile = Pile::new_face_down(stack);
+			pile.push(deck.next().unwrap());
+			pile
+		}
+		let tableau1 = pile(&mut deck);
+		let tableau2 = pile(&mut deck);
+		let tableau3 = pile(&mut deck);
+		let tableau4 = pile(&mut deck);
+		let tableau5 = pile(&mut deck);
+		let tableau6 = pile(&mut deck);
+		let tableau7 = pile(&mut deck);
+
+		// stock is remaining cards
+		let stock = Pile::new_face_down(Stack::from_iter(deck));
+
+		let state = KlondikeState {
+			stock,
+			foundations: core::array::from_fn(|_| Stack::new()),
+			tableau1,
+			tableau2,
+			tableau3,
+			tableau4,
+			tableau5,
+			tableau6,
+			tableau7,
+		};
+		Self { state }
+	}
+	pub const fn state(&self) -> &KlondikeState {
+		&self.state
+	}
+	/// Check if the game should be auto-completed
+	pub fn is_win_trivial(&self) -> bool {
+		// all face down cards empty means win
+		self.state.stock.is_empty()
+			&& self.state.tableau1.face_down().is_empty()
+			&& self.state.tableau2.face_down().is_empty()
+			&& self.state.tableau3.face_down().is_empty()
+			&& self.state.tableau4.face_down().is_empty()
+			&& self.state.tableau5.face_down().is_empty()
+			&& self.state.tableau6.face_down().is_empty()
+			&& self.state.tableau7.face_down().is_empty()
+	}
+	fn instruction_priority(&self, instruction: &KlondikeInstruction) -> usize {
+		// 1 Move into foundation
+		// 2 T->T Move to reveal new card (moving a non-king to reveal empty tableau also counts)
+		// 3 Move from stock
+		// 4 Rotate stock
+		// 5 T->T Move not revealing new card
+		// 6 Move from foundation
+		match instruction {
+			KlondikeInstruction::DstFoundation(_) => 1,
+			&KlondikeInstruction::DstTableau(dst_tableau) => match dst_tableau.src {
+				KlondikePileStack::Tableau(TableauStack {
+					tableau,
+					skip_cards: SkipCards::Skip0,
+				}) if !self.state().tableau_face_down_cards(tableau).is_empty()
+					|| self
+						.state()
+						.stack_bottom_card(dst_tableau.src)
+						.is_some_and(|card| card.rank() != Rank::King) =>
+				{
+					2
+				}
+				KlondikePileStack::Stock => 3,
+				KlondikePileStack::Tableau(_) => 5,
+				KlondikePileStack::Foundation(_) => 6,
+			},
+			KlondikeInstruction::RotateStock => 4,
+		}
+	}
+	/// A single move that usually makes progress towards a winning game
+	pub fn get_auto_move(&self, config: &KlondikeConfig) -> Option<KlondikeInstruction> {
+		self.possible_instructions(config)
+			.filter(|ins| !ins.is_useless())
+			.min_by_key(|ins| self.instruction_priority(ins))
+	}
+	/// A list of possible moves with useless moves filtered out and sorted by a simple priority function
+	pub fn get_sorted_moves(&self, config: &KlondikeConfig) -> Vec<KlondikeInstruction> {
+		let mut useful_moves: Vec<_> = self
+			.possible_instructions(config)
+			.filter(|ins| !ins.is_useless())
+			.collect();
+		useful_moves.sort_by_key(|ins| self.instruction_priority(ins));
+		useful_moves
+	}
+}
+
+impl Game for Klondike {
+	type Score = i32;
+	type Stats = KlondikeStats;
+	type Config = KlondikeConfig;
+	type Instruction = KlondikeInstruction;
+	fn score(&self, stats: &Self::Stats, config: &Self::Config) -> Self::Score {
+		stats.score(&config.scoring)
+	}
+	fn possible_instructions(
+		&self,
+		config: &Self::Config,
+	) -> impl Iterator<Item = Self::Instruction> + use<> {
+		let state = self.state.clone();
+		let config = config.clone();
+		KlondikeIter::new()
+			.filter(move |&instruction| state.is_instruction_valid(&config, instruction))
+	}
+	fn is_instruction_valid(&self, config: &Self::Config, instruction: Self::Instruction) -> bool {
+		self.state.is_instruction_valid(config, instruction)
+	}
+	fn process_instruction(
+		&mut self,
+		stats: &mut Self::Stats,
+		config: &Self::Config,
+		instruction: Self::Instruction,
+	) {
+		stats.increment_moves();
+		match instruction {
+			// Reset the stock if it's empty
+			KlondikeInstruction::RotateStock => {
+				if self.state.stock.face_down().is_empty() {
+					self.state.stock.flip_it_and_reverse_it();
+					stats.increment_recycle_count();
+				} else {
+					for _ in 0..config.draw_stock as usize {
+						self.state.stock.flip_up();
+					}
+				}
+			}
+			// Move a card from anywhere to a foundation
+			KlondikeInstruction::DstFoundation(DstFoundation { src, foundation }) => {
+				stats.increment_move_to_foundation();
+				let (card, did_flip_up) = self.state.take_top_card_flip_up(src);
+				if did_flip_up {
+					stats.increment_flip_up_bonus();
+				}
+				self.state.extend_foundation(foundation, card);
+			}
+			// Move a stack of cards from anywhere to a tableau
+			KlondikeInstruction::DstTableau(DstTableau { src, tableau }) => {
+				match src {
+					KlondikePileStack::Stock => stats.increment_move_to_tableau(),
+					KlondikePileStack::Foundation(_) => stats.increment_move_from_foundation(),
+					KlondikePileStack::Tableau(_) => {}
+				}
+				let (cards, did_flip_up) = self.state.take_stack_flip_up(src);
+				if did_flip_up {
+					stats.increment_flip_up_bonus();
+				}
+				self.state.extend_tableau(tableau, cards);
+			}
+		}
+	}
+	fn is_win(&self) -> bool {
+		// all foundations contain all ranks
+		self.state.foundations.iter().all(|foundation| {
+			foundation.len() == Rank::RANKS.len()
+				&& foundation
+					.iter()
+					.zip(Rank::RANKS)
+					.all(|(card, rank)| card.rank() == rank)
+		})
+	}
+}
+
+#[cfg(feature = "serde")]
+impl serde::Serialize for KlondikeInstruction {
+	fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+	where
+		S: serde::Serializer,
+	{
+		// There is 721 klondike instructions
+		let instruction_id = KlondikeIter::new()
+			.position(|instruction| &instruction == self)
+			.unwrap();
+		serializer.serialize_u16(instruction_id as u16)
+	}
+}
+#[cfg(feature = "serde")]
+impl<'de> serde::Deserialize<'de> for KlondikeInstruction {
+	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+	where
+		D: serde::Deserializer<'de>,
+	{
+		let instruction_id = u16::deserialize(deserializer)?;
+		let instruction = KlondikeIter::new().nth(instruction_id as usize).unwrap();
+		Ok(instruction)
+	}
+}

klondike/src/snapshots/klondike__test__json.snap

@@ -0,0 +1,5 @@
+---
+source: klondike/src/test.rs
+expression: serialized
+---
+{"config":{"inner":{"draw_stock":"DrawOne","move_from_foundation":"Allowed","scoring":{"move_to_foundation":10,"flip_up_bonus":5,"move_to_tableau":5,"move_from_foundation":-15,"recycle":0}},"undo_penalty":-15,"solve_moves_budget":100000,"solve_states_budget":100000},"initial_state":{"stock":{"face_down":[52,51,21,59,36,45,49,50,22,3,58,39,41,61,13,57,34,56,28,1,19,12,17,5],"face_up":[]},"foundations":[[],[],[],[]],"tableau1":{"face_down":[],"face_up":[40]},"tableau2":{"face_down":[9],"face_up":[4]},"tableau3":{"face_down":[35,8],"face_up":[60]},"tableau4":{"face_down":[11,27,44],"face_up":[25]},"tableau5":{"face_down":[6,7,23,18],"face_up":[29]},"tableau6":{"face_down":[2,55,10,42,24],"face_up":[54]},"tableau7":{"face_down":[26,43,38,53,37,33],"face_up":[20]}},"instructions":[336,100,720,619,606,6,720,19,16,388,497,580,388,720,139,720,19,720,17,31,720,720,720,7,720,720,523,458,720,720,720,720,720,720,720,720,43,43,720,720,720,139,720,19,720,43,720,43,720,720,720,720,720,720,720,720,720,623,619,720,720,720,720,720,720,720,720,720,720,693,281,333,253,209,113,87,720,720,720,720,720,720,720,720,75,223,619,533,74,2,720,116,331,279,279,305,305,29,25,24,12,37,25,222,24,42,126,471,720,720,720,362,292,331,253,720,19,720,183,151,12,67,336,61,93,235,720,7,2,0,7,38,26,14,27,15,26,36,0,7,3,6,18,43,36,24,12,0,1,19,38,26,39,27,15,38,26,36]}

klondike/src/snapshots/klondike__test__save_rmp.snap

@@ -0,0 +1,6 @@
+---
+source: klondike/src/test.rs
+expression: serialized
+extension: bin
+snapshot_kind: binary
+---

klondike/src/test.rs

@@ -0,0 +1,55 @@
+use crate::Klondike;
+use card_game::Session;
+
+#[test]
+fn test_is_winnable() {
+	// is winnable
+	let solution_result = Session::new_default(Klondike::with_seed(124)).solve();
+	if let Ok(Some(solution)) = solution_result {
+		let win_moves = solution.clean_solution();
+		// for (i, ins) in win_moves.into_iter().enumerate() {
+		// 	println!("{i} = {:?}", ins.instruction());
+		// }
+		println!("Game is winnable with {} moves", win_moves.len());
+	} else {
+		println!("Game is not winnable");
+	}
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_json() {
+	let mut session = Session::new_default(Klondike::with_seed(124));
+	let solution_result = session.solve();
+	if let Ok(Some(solution)) = solution_result {
+		for snapshot in solution.clean_solution() {
+			session.process_instruction(snapshot.instruction().clone());
+		}
+	}
+	let serialized = serde_json::to_string(&session).unwrap();
+	println!("serialized = {serialized}");
+	let round_trip_session: Session<Klondike> = serde_json::from_str(&serialized).unwrap();
+	let serialized2 = serde_json::to_string(&round_trip_session).unwrap();
+	assert_eq!(serialized, serialized2);
+
+	insta::assert_snapshot!(serialized);
+}
+
+#[cfg(feature = "serde")]
+#[test]
+fn test_rmp() {
+	let mut session = Session::new_default(Klondike::with_seed(124));
+	let solution_result = session.solve();
+	if let Ok(Some(solution)) = solution_result {
+		for snapshot in solution.clean_solution() {
+			session.process_instruction(snapshot.instruction().clone());
+		}
+	}
+	let serialized = rmp_serde::to_vec(&session).unwrap();
+	println!("serialized.len() = {}", serialized.len());
+	let round_trip_session: Session<Klondike> = rmp_serde::from_slice(&serialized).unwrap();
+	let serialized2 = rmp_serde::to_vec(&round_trip_session).unwrap();
+	assert_eq!(serialized, serialized2);
+
+	insta::assert_binary_snapshot!("save_rmp.bin", serialized);
+}

src/card_game.rs

@@ -1,307 +0,0 @@
-use core::ops::RangeBounds;
-
-// TODO: pub struct ValidInstruction<I>(I);
-pub trait Game {
-	type Instruction;
-	fn possible_instructions(&self) -> impl Iterator<Item = Self::Instruction> + use<Self>;
-	fn is_instruction_valid(&self, instruction: Self::Instruction) -> bool;
-	fn process_instruction(&mut self, instruction: Self::Instruction);
-	fn is_win(&self) -> bool;
-}
-
-#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
-pub enum Suit {
-	Spades = 0b00,
-	Hearts = 0b01,
-	Clubs = 0b10,
-	Diamonds = 0b11,
-}
-impl Suit {
-	pub const SUITS: [Self; 4] = [Self::Spades, Self::Hearts, Self::Clubs, Self::Diamonds];
-	/// Is the suit red.
-	pub fn is_red(self) -> bool {
-		self as u8 & 0b01 != 0
-	}
-	/// Is the suit shape spikey.  (Bouba/kiki)
-	pub fn is_kiki(self) -> bool {
-		self as u8 & 0b10 != 0
-	}
-}
-
-#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
-pub struct CardValue(u8);
-impl CardValue {
-	pub const ACE: Self = CardValue(1);
-	pub const TWO: Self = CardValue(2);
-	pub const THREE: Self = CardValue(3);
-	pub const FOUR: Self = CardValue(4);
-	pub const FIVE: Self = CardValue(5);
-	pub const SIX: Self = CardValue(6);
-	pub const SEVEN: Self = CardValue(7);
-	pub const EIGHT: Self = CardValue(8);
-	pub const NINE: Self = CardValue(9);
-	pub const TEN: Self = CardValue(10);
-	pub const JACK: Self = CardValue(11);
-	pub const QUEEN: Self = CardValue(12);
-	pub const KING: Self = CardValue(13);
-	pub fn get(self) -> u8 {
-		self.0
-	}
-	pub fn checked_add(self, offset: u8) -> Option<CardValue> {
-		let new_value = self.0.checked_add(offset)?;
-		if 13 < new_value {
-			None
-		} else {
-			Some(CardValue(new_value))
-		}
-	}
-	pub fn checked_sub(self, offset: u8) -> Option<CardValue> {
-		let new_value = self.0.checked_sub(offset)?;
-		if new_value < 1 {
-			None
-		} else {
-			Some(CardValue(new_value))
-		}
-	}
-}
-/// An identifier which specifies the deck id, suit, and card value.
-/// 2 bits for deck ID
-/// 2 bits for suit ID
-/// 4 bits for card Value
-/// TODO: better encoding for slightly more decks
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct Card(u8);
-impl Card {
-	pub fn new(deck: u8, suit: Suit, CardValue(value): CardValue) -> Self {
-		Self(deck << 6 | (suit as u8) << 4 | value)
-	}
-	pub fn value(&self) -> CardValue {
-		let masked = self.0 & 0b1111;
-		CardValue(masked)
-	}
-	pub fn suit(&self) -> Suit {
-		let red = self.is_red();
-		let kiki = self.is_kiki();
-		match (kiki, red) {
-			(false, false) => Suit::Spades,
-			(false, true) => Suit::Hearts,
-			(true, false) => Suit::Clubs,
-			(true, true) => Suit::Diamonds,
-		}
-	}
-	/// Is the suit red.
-	pub fn is_red(&self) -> bool {
-		self.0 & 0b010000 != 0
-	}
-	/// Is the suit shape spikey.  (Bouba/kiki)
-	pub fn is_kiki(&self) -> bool {
-		self.0 & 0b100000 != 0
-	}
-	pub fn deck(&self) -> u8 {
-		self.0 >> 6
-	}
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct Stack<const CAP: usize>(arrayvec::ArrayVec<Card, CAP>);
-impl<const CAP: usize> Stack<CAP> {
-	pub const fn new() -> Self {
-		Self(arrayvec::ArrayVec::new_const())
-	}
-	pub fn take_range<R: RangeBounds<usize>>(&mut self, range: R) -> Self {
-		Stack::from_iter(self.drain(range))
-	}
-}
-impl Stack<52> {
-	/// Generate a full deck of cards with the specified deck id.
-	pub fn full_deck(deck: u8) -> Self {
-		let mut stack = arrayvec::ArrayVec::new();
-		for suit in Suit::SUITS {
-			for value in 1..=13 {
-				stack.push(Card::new(deck, suit, CardValue(value)));
-			}
-		}
-		Stack(stack)
-	}
-}
-impl<const CAP: usize> From<arrayvec::ArrayVec<Card, CAP>> for Stack<CAP> {
-	fn from(value: arrayvec::ArrayVec<Card, CAP>) -> Self {
-		Self(value)
-	}
-}
-impl<const CAP: usize> FromIterator<Card> for Stack<CAP> {
-	fn from_iter<T: IntoIterator<Item = Card>>(iter: T) -> Self {
-		Self(arrayvec::ArrayVec::from_iter(iter))
-	}
-}
-impl<const CAP: usize> core::ops::Deref for Stack<CAP> {
-	type Target = arrayvec::ArrayVec<Card, CAP>;
-	fn deref(&self) -> &Self::Target {
-		&self.0
-	}
-}
-impl<const CAP: usize> core::ops::DerefMut for Stack<CAP> {
-	fn deref_mut(&mut self) -> &mut Self::Target {
-		&mut self.0
-	}
-}
-impl<const CAP: usize> IntoIterator for Stack<CAP> {
-	type Item = Card;
-	type IntoIter = arrayvec::IntoIter<Card, CAP>;
-	fn into_iter(self) -> Self::IntoIter {
-		self.0.into_iter()
-	}
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct Pile<const DN: usize, const UP: usize> {
-	face_down: Stack<DN>,
-	face_up: Stack<UP>,
-}
-impl<const DN: usize, const UP: usize> Pile<DN, UP> {
-	pub fn new() -> Self {
-		Self {
-			face_down: Stack::new(),
-			face_up: Stack::new(),
-		}
-	}
-	pub fn new_face_down(stack: Stack<DN>) -> Self {
-		Self {
-			face_down: stack,
-			face_up: Stack::new(),
-		}
-	}
-	pub fn flip_up(&mut self) {
-		if let Some(card) = self.face_down.pop() {
-			self.face_up.push(card);
-		}
-	}
-	pub fn is_empty(&self) -> bool {
-		self.face_down.is_empty() && self.face_up.is_empty()
-	}
-	pub fn pop(&mut self) -> Option<Card> {
-		self.face_up.pop()
-	}
-	pub fn take_range<R: RangeBounds<usize>>(&mut self, range: R) -> Stack<UP> {
-		// if self.face_up.get(range).is_none() {
-		// 	return None;
-		// }
-		self.face_up.take_range(range)
-	}
-	pub fn take_range_flip_up<R: RangeBounds<usize>>(&mut self, range: R) -> Stack<UP> {
-		let cards = self.take_range(range);
-		if self.face_up.is_empty() {
-			self.flip_up();
-		}
-		cards
-	}
-	pub fn push(&mut self, card: Card) {
-		self.face_up.push(card);
-	}
-	pub fn extend<I: IntoIterator<Item = Card>>(&mut self, cards: I) {
-		self.face_up.extend(cards);
-	}
-	pub fn face_up(&self) -> &[Card] {
-		&self.face_up
-	}
-	pub fn face_down(&self) -> &[Card] {
-		&self.face_down
-	}
-}
-impl<const CAP: usize> Pile<CAP, CAP> {
-	pub fn flip_it_and_reverse_it(&mut self) {
-		self.swap_up_down();
-		self.face_down.reverse();
-	}
-	pub fn swap_up_down(&mut self) {
-		core::mem::swap(&mut self.face_up, &mut self.face_down);
-	}
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct Session<G: Game> {
-	seed: G,
-	state: G,
-	history: Vec<G::Instruction>,
-}
-impl<G: Game + Clone + Eq + core::hash::Hash> Session<G>
-where
-	G::Instruction: Clone + Eq + core::hash::Hash,
-{
-	pub fn new(state: G) -> Self {
-		Self {
-			seed: state.clone(),
-			state,
-			history: Vec::new(),
-		}
-	}
-	pub fn state(&self) -> &G {
-		&self.state
-	}
-	pub fn history(&self) -> &[G::Instruction] {
-		&self.history
-	}
-	pub fn is_winnable(&self) -> Option<Vec<G::Instruction>> {
-		let mut observed = std::collections::HashSet::new();
-		struct StateMachine<G, P, I> {
-			state: G,
-			possible_instructions_iter: P,
-			instruction: I,
-		}
-		let mut state = self.state.clone();
-		let mut it = state.possible_instructions();
-		let mut path = Vec::new();
-		'outer: while !state.is_win() {
-			observed.insert(state.clone());
-			for instruction in &mut it {
-				let mut next_state = state.clone();
-				next_state.process_instruction(instruction.clone());
-				if !observed.contains(&next_state) {
-					let possible_instructions_iter =
-						core::mem::replace(&mut it, next_state.possible_instructions());
-					let state = core::mem::replace(&mut state, next_state);
-					path.push(StateMachine {
-						state,
-						possible_instructions_iter,
-						instruction,
-					});
-					continue 'outer;
-				}
-			}
-			let Some(last_state) = path.pop() else {
-				return None;
-			};
-			state = last_state.state;
-			it = last_state.possible_instructions_iter;
-		}
-		Some(path.into_iter().map(|state| state.instruction).collect())
-	}
-	pub fn undo(&mut self) {
-		// replay the entire history of the game except one move
-		self.history.pop();
-		let mut state = self.seed.clone();
-		for instruction in self.history() {
-			state.process_instruction(instruction.clone());
-		}
-		self.state = state;
-	}
-}
-impl<G: Game> Game for Session<G>
-where
-	G::Instruction: Clone,
-{
-	type Instruction = G::Instruction;
-	fn possible_instructions(&self) -> impl Iterator<Item = Self::Instruction> + use<G> {
-		self.state.possible_instructions()
-	}
-	fn is_instruction_valid(&self, instruction: Self::Instruction) -> bool {
-		self.state.is_instruction_valid(instruction)
-	}
-	fn process_instruction(&mut self, instruction: Self::Instruction) {
-		self.history.push(instruction.clone());
-		self.state.process_instruction(instruction);
-	}
-	fn is_win(&self) -> bool {
-		self.state.is_win()
-	}
-}

src/klondike.rs

@@ -1,590 +0,0 @@
-use crate::Rng;
-use crate::card_game::{Card, CardValue, Game, Pile, Stack};
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct KlondikeConfig {}
-impl Default for KlondikeConfig {
-	fn default() -> Self {
-		KlondikeConfig {}
-	}
-}
-
-#[repr(u8)]
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub enum KlondikePileId {
-	Tableau1,
-	Tableau2,
-	Tableau3,
-	Tableau4,
-	Tableau5,
-	Tableau6,
-	Tableau7,
-	Foundation1,
-	Foundation2,
-	Foundation3,
-	Foundation4,
-	Stock,
-}
-impl KlondikePileId {
-	const fn next(self) -> Option<Self> {
-		use KlondikePileId::*;
-		Some(match self {
-			Tableau1 => Tableau2,
-			Tableau2 => Tableau3,
-			Tableau3 => Tableau4,
-			Tableau4 => Tableau5,
-			Tableau5 => Tableau6,
-			Tableau6 => Tableau7,
-			Tableau7 => Foundation1,
-			Foundation1 => Foundation2,
-			Foundation2 => Foundation3,
-			Foundation3 => Foundation4,
-			Foundation4 => Stock,
-			Stock => return None,
-		})
-	}
-}
-
-/// high four bits for stack depth, low four bits for Pile Id
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub struct InstructionSrc(u8);
-impl InstructionSrc {
-	const STOCK: Self = InstructionSrc::new(KlondikePileStack::Stock);
-	pub const fn new(src: KlondikePileStack) -> Self {
-		match src {
-			KlondikePileStack::Tableau1(skip_cards) => {
-				Self(KlondikePileId::Tableau1 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau2(skip_cards) => {
-				Self(KlondikePileId::Tableau2 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau3(skip_cards) => {
-				Self(KlondikePileId::Tableau3 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau4(skip_cards) => {
-				Self(KlondikePileId::Tableau4 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau5(skip_cards) => {
-				Self(KlondikePileId::Tableau5 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau6(skip_cards) => {
-				Self(KlondikePileId::Tableau6 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Tableau7(skip_cards) => {
-				Self(KlondikePileId::Tableau7 as u8 + ((skip_cards as u8) << 4))
-			}
-			KlondikePileStack::Foundation1 => Self(KlondikePileId::Foundation1 as u8),
-			KlondikePileStack::Foundation2 => Self(KlondikePileId::Foundation2 as u8),
-			KlondikePileStack::Foundation3 => Self(KlondikePileId::Foundation3 as u8),
-			KlondikePileStack::Foundation4 => Self(KlondikePileId::Foundation4 as u8),
-			KlondikePileStack::Stock => Self(KlondikePileId::Stock as u8),
-		}
-	}
-	const fn into_spec(self) -> KlondikePileStack {
-		// SAFETY: there is no way to construct an invalid InstructionSrc
-		let pile = unsafe { core::mem::transmute(self.0 & 0b1111) };
-		match pile {
-			KlondikePileId::Tableau1 => {
-				KlondikePileStack::Tableau1(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau2 => {
-				KlondikePileStack::Tableau2(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau3 => {
-				KlondikePileStack::Tableau3(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau4 => {
-				KlondikePileStack::Tableau4(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau5 => {
-				KlondikePileStack::Tableau5(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau6 => {
-				KlondikePileStack::Tableau6(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Tableau7 => {
-				KlondikePileStack::Tableau7(unsafe { core::mem::transmute(self.0 >> 4) })
-			}
-			KlondikePileId::Foundation1 => KlondikePileStack::Foundation1,
-			KlondikePileId::Foundation2 => KlondikePileStack::Foundation2,
-			KlondikePileId::Foundation3 => KlondikePileStack::Foundation3,
-			KlondikePileId::Foundation4 => KlondikePileStack::Foundation4,
-			KlondikePileId::Stock => KlondikePileStack::Stock,
-		}
-	}
-	const fn next(self) -> Option<Self> {
-		match self.into_spec().next() {
-			Some(s) => Some(Self::new(s)),
-			None => None,
-		}
-	}
-}
-impl From<InstructionSrc> for KlondikePileId {
-	fn from(value: InstructionSrc) -> Self {
-		match value.into_spec() {
-			KlondikePileStack::Tableau1(_) => KlondikePileId::Tableau1,
-			KlondikePileStack::Tableau2(_) => KlondikePileId::Tableau2,
-			KlondikePileStack::Tableau3(_) => KlondikePileId::Tableau3,
-			KlondikePileStack::Tableau4(_) => KlondikePileId::Tableau4,
-			KlondikePileStack::Tableau5(_) => KlondikePileId::Tableau5,
-			KlondikePileStack::Tableau6(_) => KlondikePileId::Tableau6,
-			KlondikePileStack::Tableau7(_) => KlondikePileId::Tableau7,
-			KlondikePileStack::Foundation1 => KlondikePileId::Foundation1,
-			KlondikePileStack::Foundation2 => KlondikePileId::Foundation2,
-			KlondikePileStack::Foundation3 => KlondikePileId::Foundation3,
-			KlondikePileStack::Foundation4 => KlondikePileId::Foundation4,
-			KlondikePileStack::Stock => KlondikePileId::Stock,
-		}
-	}
-}
-
-#[repr(u8)]
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub enum SkipCards {
-	Zero,
-	One,
-	Two,
-	Three,
-	Four,
-	Five,
-	Six,
-	Seven,
-	Eight,
-	Nine,
-	Ten,
-	Eleven,
-	Twelve,
-	Thirteen,
-}
-impl SkipCards {
-	const fn next(self) -> Option<Self> {
-		use SkipCards::*;
-		Some(match self {
-			Zero => One,
-			One => Two,
-			Two => Three,
-			Three => Four,
-			Four => Five,
-			Five => Six,
-			Six => Seven,
-			Seven => Eight,
-			Eight => Nine,
-			Nine => Ten,
-			Ten => Eleven,
-			Eleven => Twelve,
-			Twelve => Thirteen,
-			Thirteen => return None,
-		})
-	}
-}
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub enum KlondikePileStack {
-	Tableau1(SkipCards),
-	Tableau2(SkipCards),
-	Tableau3(SkipCards),
-	Tableau4(SkipCards),
-	Tableau5(SkipCards),
-	Tableau6(SkipCards),
-	Tableau7(SkipCards),
-	Foundation1,
-	Foundation2,
-	Foundation3,
-	Foundation4,
-	Stock,
-}
-impl KlondikePileStack {
-	const fn next(self) -> Option<Self> {
-		use KlondikePileStack::*;
-		Some(match self {
-			Tableau1(skip) => match skip.next() {
-				Some(next) => Tableau1(next),
-				None => Tableau2(SkipCards::Zero),
-			},
-			Tableau2(skip) => match skip.next() {
-				Some(next) => Tableau2(next),
-				None => Tableau3(SkipCards::Zero),
-			},
-			Tableau3(skip) => match skip.next() {
-				Some(next) => Tableau3(next),
-				None => Tableau4(SkipCards::Zero),
-			},
-			Tableau4(skip) => match skip.next() {
-				Some(next) => Tableau4(next),
-				None => Tableau5(SkipCards::Zero),
-			},
-			Tableau5(skip) => match skip.next() {
-				Some(next) => Tableau5(next),
-				None => Tableau6(SkipCards::Zero),
-			},
-			Tableau6(skip) => match skip.next() {
-				Some(next) => Tableau6(next),
-				None => Tableau7(SkipCards::Zero),
-			},
-			Tableau7(skip) => match skip.next() {
-				Some(next) => Tableau7(next),
-				None => Foundation1,
-			},
-			Foundation1 => Foundation2,
-			Foundation2 => Foundation3,
-			Foundation3 => Foundation4,
-			Foundation4 => Stock,
-			Stock => return None,
-		})
-	}
-}
-
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub struct KlondikeInstruction {
-	pub src: InstructionSrc,
-	pub dst: KlondikePileId,
-}
-impl KlondikeInstruction {
-	pub const fn stock() -> Self {
-		Self {
-			src: InstructionSrc::STOCK,
-			dst: KlondikePileId::Stock,
-		}
-	}
-	const fn next(self) -> Option<Self> {
-		let KlondikeInstruction { src, dst } = self;
-		if let Some(next_dst) = dst.next() {
-			return Some(Self { src, dst: next_dst });
-		}
-		if let Some(next_src) = src.next() {
-			return Some(Self {
-				src: next_src,
-				dst: KlondikePileId::Tableau1,
-			});
-		}
-		None
-	}
-}
-
-const TABLEAUS: usize = 7;
-const fn sum(n: usize) -> usize {
-	n * (n + 1) / 2
-}
-const MAX_STACK: usize = 52 - sum(TABLEAUS);
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct KlondikeState {
-	stock: Pile<MAX_STACK, MAX_STACK>,
-	foundations: [Stack<13>; 4],
-	tableau1: Pile<0, 13>,
-	tableau2: Pile<1, 13>,
-	tableau3: Pile<2, 13>,
-	tableau4: Pile<3, 13>,
-	tableau5: Pile<4, 13>,
-	tableau6: Pile<5, 13>,
-	tableau7: Pile<6, 13>,
-}
-impl KlondikeState {
-	pub const fn stock(&self) -> &Pile<MAX_STACK, MAX_STACK> {
-		&self.stock
-	}
-	pub const fn foundation1(&self) -> &Stack<13> {
-		&self.foundations[1 - 1]
-	}
-	pub const fn foundation2(&self) -> &Stack<13> {
-		&self.foundations[2 - 1]
-	}
-	pub const fn foundation3(&self) -> &Stack<13> {
-		&self.foundations[3 - 1]
-	}
-	pub const fn foundation4(&self) -> &Stack<13> {
-		&self.foundations[4 - 1]
-	}
-	pub const fn tableau1(&self) -> &Pile<0, 13> {
-		&self.tableau1
-	}
-	pub const fn tableau2(&self) -> &Pile<1, 13> {
-		&self.tableau2
-	}
-	pub const fn tableau3(&self) -> &Pile<2, 13> {
-		&self.tableau3
-	}
-	pub const fn tableau4(&self) -> &Pile<3, 13> {
-		&self.tableau4
-	}
-	pub const fn tableau5(&self) -> &Pile<4, 13> {
-		&self.tableau5
-	}
-	pub const fn tableau6(&self) -> &Pile<5, 13> {
-		&self.tableau6
-	}
-	pub const fn tableau7(&self) -> &Pile<6, 13> {
-		&self.tableau7
-	}
-	fn src_card(&self, src: InstructionSrc) -> Option<&Card> {
-		match src.into_spec() {
-			KlondikePileStack::Tableau1(skip_cards) => {
-				self.tableau1.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau2(skip_cards) => {
-				self.tableau2.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau3(skip_cards) => {
-				self.tableau3.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau4(skip_cards) => {
-				self.tableau4.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau5(skip_cards) => {
-				self.tableau5.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau6(skip_cards) => {
-				self.tableau6.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Tableau7(skip_cards) => {
-				self.tableau7.face_up().get(skip_cards as usize)
-			}
-			KlondikePileStack::Foundation1 => self.foundations[1 - 1].last(),
-			KlondikePileStack::Foundation2 => self.foundations[2 - 1].last(),
-			KlondikePileStack::Foundation3 => self.foundations[3 - 1].last(),
-			KlondikePileStack::Foundation4 => self.foundations[4 - 1].last(),
-			KlondikePileStack::Stock => self.stock.face_up().last(),
-		}
-	}
-	fn take_src_cards(&mut self, src: InstructionSrc) -> Stack<13> {
-		match src.into_spec() {
-			KlondikePileStack::Tableau1(skip_cards) => {
-				self.tableau1.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau2(skip_cards) => {
-				self.tableau2.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau3(skip_cards) => {
-				self.tableau3.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau4(skip_cards) => {
-				self.tableau4.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau5(skip_cards) => {
-				self.tableau5.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau6(skip_cards) => {
-				self.tableau6.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Tableau7(skip_cards) => {
-				self.tableau7.take_range_flip_up(skip_cards as usize..)
-			}
-			KlondikePileStack::Foundation1 => Stack::from_iter(self.foundations[1 - 1].pop()),
-			KlondikePileStack::Foundation2 => Stack::from_iter(self.foundations[2 - 1].pop()),
-			KlondikePileStack::Foundation3 => Stack::from_iter(self.foundations[3 - 1].pop()),
-			KlondikePileStack::Foundation4 => Stack::from_iter(self.foundations[4 - 1].pop()),
-			KlondikePileStack::Stock => Stack::from_iter(self.stock.pop()),
-		}
-	}
-	fn dst_card(&self, dst: KlondikePileId) -> Option<&Card> {
-		match dst {
-			KlondikePileId::Tableau1 => self.tableau1.face_up().last(),
-			KlondikePileId::Tableau2 => self.tableau2.face_up().last(),
-			KlondikePileId::Tableau3 => self.tableau3.face_up().last(),
-			KlondikePileId::Tableau4 => self.tableau4.face_up().last(),
-			KlondikePileId::Tableau5 => self.tableau5.face_up().last(),
-			KlondikePileId::Tableau6 => self.tableau6.face_up().last(),
-			KlondikePileId::Tableau7 => self.tableau7.face_up().last(),
-			KlondikePileId::Foundation1 => self.foundations[1 - 1].last(),
-			KlondikePileId::Foundation2 => self.foundations[2 - 1].last(),
-			KlondikePileId::Foundation3 => self.foundations[3 - 1].last(),
-			KlondikePileId::Foundation4 => self.foundations[4 - 1].last(),
-			KlondikePileId::Stock => None,
-		}
-	}
-	fn extend_dst_pile(&mut self, dst: KlondikePileId, cards: Stack<13>) {
-		match dst {
-			KlondikePileId::Tableau1 => self.tableau1.extend(cards),
-			KlondikePileId::Tableau2 => self.tableau2.extend(cards),
-			KlondikePileId::Tableau3 => self.tableau3.extend(cards),
-			KlondikePileId::Tableau4 => self.tableau4.extend(cards),
-			KlondikePileId::Tableau5 => self.tableau5.extend(cards),
-			KlondikePileId::Tableau6 => self.tableau6.extend(cards),
-			KlondikePileId::Tableau7 => self.tableau7.extend(cards),
-			KlondikePileId::Foundation1 => self.foundations[1 - 1].extend(cards),
-			KlondikePileId::Foundation2 => self.foundations[2 - 1].extend(cards),
-			KlondikePileId::Foundation3 => self.foundations[3 - 1].extend(cards),
-			KlondikePileId::Foundation4 => self.foundations[4 - 1].extend(cards),
-			KlondikePileId::Stock => (),
-		}
-	}
-	fn is_instruction_valid(&self, instruction: KlondikeInstruction) -> bool {
-		match instruction {
-			// Stock -> Stock draws a card or resets the stock
-			KlondikeInstruction {
-				src: InstructionSrc::STOCK,
-				dst: KlondikePileId::Stock,
-			} => {
-				// cannot move stock when stock is empty
-				!self.stock.is_empty()
-			}
-
-			// cannot move cards to stock
-			KlondikeInstruction {
-				src: _,
-				dst: KlondikePileId::Stock,
-			} => false,
-
-			// moving to foundation has special rules
-			KlondikeInstruction { src, dst }
-				if matches!(
-					dst,
-					KlondikePileId::Foundation1
-						| KlondikePileId::Foundation2
-						| KlondikePileId::Foundation3
-						| KlondikePileId::Foundation4
-				) =>
-			{
-				// get the top cards
-				if let Some(src_card) = self.src_card(src) {
-					match self.dst_card(dst) {
-						// destination card exists
-						Some(dst_card) => {
-							// suit matches?
-							src_card.suit() == dst_card.suit()
-							// value is +1?
-							&& dst_card.value().checked_add(1) == Some(src_card.value())
-						}
-						// only ace is allowed to go onto empty foundation
-						None => src_card.value() == CardValue::ACE,
-					}
-				} else {
-					false
-				}
-			}
-			// other = move to tableau
-			KlondikeInstruction { src, dst } => {
-				// get the top cards
-				if let Some(src_card) = self.src_card(src) {
-					match self.dst_card(dst) {
-						// destination card exists
-						Some(dst_card) => {
-							// red-ness is opposite?
-							src_card.is_red() != dst_card.is_red()
-							// value is -1?
-							&& dst_card.value().checked_sub(1) == Some(src_card.value())
-						}
-						// only king is allowed to go onto empty tableau
-						None => src_card.value() == CardValue::KING,
-					}
-				} else {
-					false
-				}
-			}
-		}
-	}
-}
-
-pub struct KlondikeIter {
-	instruction: Option<KlondikeInstruction>,
-}
-impl KlondikeIter {
-	const fn new() -> Self {
-		Self {
-			instruction: Some(KlondikeInstruction {
-				src: InstructionSrc::new(KlondikePileStack::Tableau1(SkipCards::Zero)),
-				dst: KlondikePileId::Tableau2,
-			}),
-		}
-	}
-}
-impl Iterator for KlondikeIter {
-	type Item = KlondikeInstruction;
-	fn next(&mut self) -> Option<Self::Item> {
-		let instruction = self.instruction;
-		self.instruction = instruction?.next();
-		instruction
-	}
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct Klondike {
-	config: KlondikeConfig,
-	state: KlondikeState,
-}
-impl Klondike {
-	pub fn new_random_default() -> Self {
-		Self::new(Rng::default(), KlondikeConfig::default())
-	}
-	pub fn new(mut seed: Rng, config: KlondikeConfig) -> Self {
-		// shuffle a new deck
-		let mut deck = Stack::full_deck(0);
-		use rand::seq::SliceRandom;
-		deck.shuffle(&mut seed);
-		let mut deck = deck.into_iter();
-
-		// generate tableaus
-		fn pile<const DN: usize>(deck: &mut arrayvec::IntoIter<Card, 52>) -> Pile<DN, 13> {
-			let stack = arrayvec::ArrayVec::from_iter(deck.take(DN)).into();
-			let mut pile = Pile::new_face_down(stack);
-			pile.push(deck.next().unwrap());
-			pile
-		}
-		let tableau1 = pile(&mut deck);
-		let tableau2 = pile(&mut deck);
-		let tableau3 = pile(&mut deck);
-		let tableau4 = pile(&mut deck);
-		let tableau5 = pile(&mut deck);
-		let tableau6 = pile(&mut deck);
-		let tableau7 = pile(&mut deck);
-
-		// stock is remaining cards
-		let stock = Pile::new_face_down(arrayvec::ArrayVec::from_iter(deck).into());
-
-		let state = KlondikeState {
-			stock,
-			foundations: core::array::from_fn(|_| Stack::new()),
-			tableau1,
-			tableau2,
-			tableau3,
-			tableau4,
-			tableau5,
-			tableau6,
-			tableau7,
-		};
-		Self { config, state }
-	}
-	pub const fn state(&self) -> &KlondikeState {
-		&self.state
-	}
-}
-
-impl Game for Klondike {
-	type Instruction = KlondikeInstruction;
-	fn possible_instructions(&self) -> impl Iterator<Item = Self::Instruction> + use<> {
-		let state = self.state.clone();
-		KlondikeIter::new().filter(move |&instruction| state.is_instruction_valid(instruction))
-	}
-	fn is_instruction_valid(&self, instruction: Self::Instruction) -> bool {
-		self.state.is_instruction_valid(instruction)
-	}
-	fn process_instruction(&mut self, instruction: Self::Instruction) {
-		match instruction {
-			// Reset the stock if it's empty
-			KlondikeInstruction {
-				src: InstructionSrc::STOCK,
-				dst: KlondikePileId::Stock,
-			} => {
-				if self.state.stock.face_down().is_empty() {
-					self.state.stock.flip_it_and_reverse_it();
-				} else {
-					self.state.stock.flip_up();
-				}
-			}
-			KlondikeInstruction { src, dst } => {
-				let cards = self.state.take_src_cards(src);
-				self.state.extend_dst_pile(dst, cards);
-			}
-		}
-	}
-	fn is_win(&self) -> bool {
-		// all face down cards empty means win
-		self.state.stock.face_down().is_empty()
-			&& self.state.tableau1.face_down().is_empty()
-			&& self.state.tableau2.face_down().is_empty()
-			&& self.state.tableau3.face_down().is_empty()
-			&& self.state.tableau4.face_down().is_empty()
-			&& self.state.tableau5.face_down().is_empty()
-			&& self.state.tableau6.face_down().is_empty()
-			&& self.state.tableau7.face_down().is_empty()
-	}
-}

src/lib.rs

@@ -1,12 +0,0 @@
-pub mod card_game;
-pub mod klondike;
-
-#[cfg(test)]
-mod test;
-
-pub type Rng = rand::rngs::ThreadRng;
-
-// // test readme
-// #[doc = include_str!("../README.md")]
-// #[cfg(doctest)]
-// struct ReadmeDoctests;

src/main.rs

@@ -1,209 +0,0 @@
-mod card_game;
-mod klondike;
-
-pub type Rng = rand::rngs::ThreadRng;
-
-use card_game::{Card, Game, Pile, Session, Suit};
-use klondike::{
-	InstructionSrc, Klondike, KlondikeInstruction, KlondikePileId, KlondikePileStack, SkipCards,
-};
-
-use std::fmt::Display;
-
-impl Display for Card {
-	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		match self.value().get() {
-			1 => write!(f, "A"),
-			11 => write!(f, "J"),
-			12 => write!(f, "Q"),
-			13 => write!(f, "K"),
-			other => write!(f, "{other}"),
-		}?;
-		match self.suit() {
-			Suit::Spades => write!(f, "♠"),
-			Suit::Hearts => write!(f, "♡"),
-			Suit::Clubs => write!(f, "♣"),
-			Suit::Diamonds => write!(f, "♢"),
-		}
-	}
-}
-
-struct OptionalCard<'a>(Option<&'a Card>);
-impl Display for OptionalCard<'_> {
-	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		match self {
-			OptionalCard(Some(card)) => write!(f, "{card}"),
-			OptionalCard(None) => write!(f, "None"),
-		}
-	}
-}
-
-impl Display for Klondike {
-	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-		// Stock
-		let stock_count = self.state().stock().face_down().len();
-		writeln!(f, "Stock: {stock_count}")?;
-
-		// Hand
-		let hand = self.state().stock().face_up().last();
-		writeln!(f, "Hand: {}", OptionalCard(hand))?;
-
-		// Foundations
-		write!(
-			f,
-			"Foundations: {} {} {} {}",
-			OptionalCard(self.state().foundation1().last()),
-			OptionalCard(self.state().foundation2().last()),
-			OptionalCard(self.state().foundation3().last()),
-			OptionalCard(self.state().foundation4().last()),
-		)?;
-		writeln!(f)?;
-
-		fn write_pile<const DN: usize, const UP: usize>(
-			f: &mut std::fmt::Formatter<'_>,
-			pile: &Pile<DN, UP>,
-			pile_id: usize,
-		) -> std::fmt::Result {
-			write!(f, "T{} ", pile_id)?;
-			for _ in pile.face_down() {
-				write!(f, "]")?;
-			}
-			for card in pile.face_up() {
-				write!(f, "{card}")?;
-			}
-			writeln!(f)?;
-			Ok(())
-		}
-		write_pile(f, self.state().tableau1(), 1)?;
-		write_pile(f, self.state().tableau2(), 2)?;
-		write_pile(f, self.state().tableau3(), 3)?;
-		write_pile(f, self.state().tableau4(), 4)?;
-		write_pile(f, self.state().tableau5(), 5)?;
-		write_pile(f, self.state().tableau6(), 6)?;
-		write_pile(f, self.state().tableau7(), 7)?;
-
-		Ok(())
-	}
-}
-
-#[derive(Debug)]
-struct Invalid;
-struct Parsed<T>(T);
-impl core::str::FromStr for Parsed<KlondikeInstruction> {
-	type Err = Invalid;
-	fn from_str(s: &str) -> Result<Self, Self::Err> {
-		let Parsed(src) = s.get(0..2).ok_or(Invalid)?.parse()?;
-		let Parsed(dst) = s.get(3..5).ok_or(Invalid)?.parse()?;
-		Ok(Parsed(KlondikeInstruction { src, dst }))
-	}
-}
-impl core::str::FromStr for Parsed<InstructionSrc> {
-	type Err = Invalid;
-	fn from_str(s: &str) -> Result<Self, Self::Err> {
-		Ok(Parsed(match s {
-			"st" => InstructionSrc::new(KlondikePileStack::Stock),
-			"t1" => InstructionSrc::new(KlondikePileStack::Tableau1(SkipCards::Zero)),
-			"t2" => InstructionSrc::new(KlondikePileStack::Tableau2(SkipCards::Zero)),
-			"t3" => InstructionSrc::new(KlondikePileStack::Tableau3(SkipCards::Zero)),
-			"t4" => InstructionSrc::new(KlondikePileStack::Tableau4(SkipCards::Zero)),
-			"t5" => InstructionSrc::new(KlondikePileStack::Tableau5(SkipCards::Zero)),
-			"t6" => InstructionSrc::new(KlondikePileStack::Tableau6(SkipCards::Zero)),
-			"t7" => InstructionSrc::new(KlondikePileStack::Tableau7(SkipCards::Zero)),
-			"f1" => InstructionSrc::new(KlondikePileStack::Foundation1),
-			"f2" => InstructionSrc::new(KlondikePileStack::Foundation2),
-			"f3" => InstructionSrc::new(KlondikePileStack::Foundation3),
-			"f4" => InstructionSrc::new(KlondikePileStack::Foundation4),
-			_ => return Err(Invalid),
-		}))
-	}
-}
-impl core::str::FromStr for Parsed<KlondikePileId> {
-	type Err = Invalid;
-	fn from_str(s: &str) -> Result<Self, Self::Err> {
-		Ok(Parsed(match s {
-			"st" => KlondikePileId::Stock,
-			"t1" => KlondikePileId::Tableau1,
-			"t2" => KlondikePileId::Tableau2,
-			"t3" => KlondikePileId::Tableau3,
-			"t4" => KlondikePileId::Tableau4,
-			"t5" => KlondikePileId::Tableau5,
-			"t6" => KlondikePileId::Tableau6,
-			"t7" => KlondikePileId::Tableau7,
-			"f1" => KlondikePileId::Foundation1,
-			"f2" => KlondikePileId::Foundation2,
-			"f3" => KlondikePileId::Foundation3,
-			"f4" => KlondikePileId::Foundation4,
-			_ => return Err(Invalid),
-		}))
-	}
-}
-
-enum SessionInstruction {
-	New,
-	Undo,
-	Hint,
-	Auto,
-	Stock,
-	Exit,
-	Klondike(KlondikeInstruction),
-}
-impl core::str::FromStr for SessionInstruction {
-	type Err = Invalid;
-	fn from_str(s: &str) -> Result<Self, Self::Err> {
-		Ok(match s {
-			"new" | "n" => Self::New,
-			"undo" | "u" => Self::Undo,
-			"hint" | "h" => Self::Hint,
-			"auto" | "a" => Self::Auto,
-			"exit" => Self::Exit,
-			"s" => Self::Stock,
-			other => {
-				let Parsed(ki) = other.parse()?;
-				Self::Klondike(ki)
-			}
-		})
-	}
-}
-
-fn main() -> Result<(), std::io::Error> {
-	let mut session = Session::new(Klondike::new_random_default());
-	loop {
-		// display game
-		println!("{}", session.state());
-
-		// parse input
-		let mut input = String::new();
-		std::io::stdin().read_line(&mut input)?;
-		let Ok(instruction) = input.trim().parse() else {
-			println!("Invalid instruction.");
-			continue;
-		};
-
-		// run game
-		match instruction {
-			SessionInstruction::New => session = Session::new(Klondike::new_random_default()),
-			SessionInstruction::Undo => session.undo(),
-			SessionInstruction::Exit => break Ok(()),
-			SessionInstruction::Hint => {
-				for instruction in session.possible_instructions() {
-					println!("{instruction:?}");
-				}
-			}
-			SessionInstruction::Auto => {
-				if let Some(instruction) = session.possible_instructions().next() {
-					session.process_instruction(instruction);
-				} else {
-					println!("No valid moves!");
-				}
-			}
-			SessionInstruction::Stock => session.process_instruction(KlondikeInstruction::stock()),
-			SessionInstruction::Klondike(instruction) => {
-				if session.is_instruction_valid(instruction) {
-					session.process_instruction(instruction);
-				} else {
-					println!("Invalid move!");
-				}
-			}
-		}
-	}
-}

src/test.rs

@@ -1,33 +0,0 @@
-use crate::card_game::{Game, Session};
-use crate::klondike::Klondike;
-#[test]
-fn test_is_winnable() {
-	// is winnable
-	let is_winnable = Session::new(Klondike::new_random_default()).is_winnable();
-	println!("is_winnable = {is_winnable:?}");
-}
-#[test]
-fn test_klondike() {
-	// create game session
-	let game = Klondike::new_random_default();
-	let mut session = Session::new(game);
-
-	// is winnable
-	let is_winnable = session.is_winnable();
-	println!("is_winnable = {is_winnable:?}");
-
-	// play game
-	while let Some(instruction) = session.possible_instructions().next() {
-		session.process_instruction(instruction);
-	}
-
-	// did win
-	let is_win = session.is_win();
-
-	// print session history
-	for (i, instruction) in session.history().iter().enumerate() {
-		println!("move {i} = {instruction:?}");
-	}
-
-	println!("is_win = {is_win}");
-}