Build an original draw-one, Klondike-style teaching variant with explicit rules and small fixtures. The useful starting point is a card ledger and a legal-transfer function. Card artwork and dragging can come after the state survives moves, stock draws, redeals, and resets.
Define the variant before writing handlers
Use one deck with 52 unique identities: suit plus rank, with Ace represented as 1 and King as 13. Hearts and diamonds are red; clubs and spades are black. Keep rank names and suit names visible so a move never depends on color alone.
Deal seven tableau piles containing one through seven cards: 28 cards total. Only the top card of each pile starts face up. Put the remaining 24 cards in the stock, with an empty waste and four empty foundations. Those deck, pile, and foundation concepts are described in Bicycle's Solitaire rules.
This teaching variant draws one card at a time, permits a valid face-up suffix to move as a run, and allows unlimited redeals without reshuffling. Declare those choices on the first screen. Bicycle's Klondike page instead describes draw-three play and moving all face-up cards as a unit. Its wording does not establish the suffix-transfer rule used here.
Do not implement automatic foundation transfers. In this bounded version, foundations receive cards but do not return cards to the tableau. There is no Undo requirement or solvability guarantee.
Represent a location, not another copy
Store each card's permanent identity, suit, and rank once. Pile arrays hold those identities in a documented order. A face-up flag describes visibility; turning a card over does not create a new card.
After every committed action, check two invariants: the combined stock, waste, tableau, and foundations contain exactly 52 entries, and those entries contain exactly the 52 expected distinct identities. A count of 52 alone is insufficient: one duplicate and one missing card still total 52.
For a move, validate the selected source, destination, and whole transferred run first. Then remove the identities from the source and append them to the destination as one transaction. A rejected move leaves every pile, visibility flag, and selection unchanged. A successful move clears the selection and turns up the newly exposed tableau top, if that card was face down.
Make tableau and foundation checks different
A tableau destination needs a card exactly one rank higher than the leading card of the incoming run, in the opposite color. The transferred suffix must itself be face up, descending by one rank, and alternating in color. An empty tableau accepts only a King-leading valid run.
Suppose a pile has face-up King of clubs, Queen of hearts, and Jack of clubs, in that order. Moving the Queen-and-Jack suffix onto a King of spades in another pile is legal under this variant. The leading Queen is one below the destination King and opposite in color; the trailing Jack continues the valid run. The source King remains where it was.
| Proposed move | Result and reason |
|---|---|
| Queen of hearts + Jack of clubs onto King of spades | Accept the valid suffix |
| Queen of diamonds onto Jack of clubs | Reject: destination rank is lower, not one higher |
| Jack of spades onto Queen of clubs | Reject: both are black |
| Queen-leading run into an empty tableau | Reject: the leading card is not King |
A foundation accepts only a single exposed top card. An empty foundation needs an Ace; afterward, the suit must match and rank must increase by exactly one. With Ace of hearts already placed, 2 of hearts is legal. 2 of diamonds has the wrong suit, and 3 of hearts skips a rank. A buried card cannot be selected merely because its identity appears in the array.
Redeal in the right order
Document both stock and waste arrays with their top at the end. Draw pops one identity from stock, turns it face up, and appends it to waste. Only the waste top is available for a move.
Use an isolated order fixture with three cards, not a claim to be a complete deal. Let the first draws be Ace of clubs, 5 of diamonds, and 9 of spades. Before drawing, the stock array is [9 of spades, 5 of diamonds, Ace of clubs]. After three draws, the waste array is [Ace of clubs, 5 of diamonds, 9 of spades].
When the stock is empty, Redeal reverses that waste into the stock and turns those cards face down. The next draw is Ace of clubs again. If a waste card was played elsewhere, redeal includes only the remaining waste cards, in their retained order. It never retrieves played cards or shuffles the waste. Disable Redeal while the stock still contains cards.
Test a complete win without inventing a loss
Use a separate complete 52-card terminal fixture: hearts Ace through Queen are in their foundation, all 13 cards of each other suit are in their foundations, and King of hearts is the waste top. The tableau and stock are empty. That is 12 + 39 + 1 = 52 distinct cards.
Moving King of hearts produces four foundations of 13 cards each and a win. After that, only Reset is enabled. A position with no currently available move is not automatically a declared loss; this example has no solver that proves a deal unwinnable.
Reset creates a fresh deal and clears selection, status, pending callbacks, and terminal state. Keep a deterministic deck order for fixtures separate from the ordinary shuffled-deck path. The shuffle happens for a new deal, never for Redeal.
Copyable implementation prompt
Create an original self-contained HTML/CSS/JavaScript draw-one Klondike-style teaching game with readable source, text/symbol cards, and an acceptance-test report. Do not copy card artwork or source code.
Use 52 unique suit/rank identities, Ace=1 through King=13, no jokers. Deal seven tableau piles of 1..7 cards, 28 total, with only each top face up; stock has 24, waste and four foundations are empty. Document pile order with the top at the end. Keep a deterministic deck fixture separate from the ordinary new-deal shuffle. State this variant's rules visibly: draw one, valid face-up suffix transfers, unlimited unshuffled redeals, no automatic foundation moves or foundation-to-tableau moves.
Validate an action before atomic commit. Tableau runs must be face up, descending by one and alternating in color; their leading card goes onto an opposite-color card exactly one rank higher. Empty tableau requires a King-leading run. Foundations accept a single exposed top card: Ace if empty, then matching suit and next rank. After a successful tableau removal, flip only the newly exposed top if it was hidden. Clear selection after success; illegal moves mutate nothing.
Draw exactly one stock-top card to waste, face up; only the waste top is playable. Redeal only when stock is empty: reverse remaining waste into stock, turn it face down, and never shuffle or retrieve played cards. Isolated fixture: stock [9 of spades,5 of diamonds,Ace of clubs] draws Ace,5,9; waste becomes [Ace,5,9]; Redeal makes the next draw Ace again.
After every action assert exactly 52 entries and exactly the expected 52 distinct card IDs across all piles. Test Queen of hearts + Jack of clubs as a suffix above King of clubs moving onto King of spades. Reject Queen of diamonds onto Jack of clubs, Jack of spades onto Queen of clubs, and a Queen-leading run into an empty tableau. Test Ace of hearts -> 2 of hearts; reject 2 of diamonds and 3 of hearts. Test a move exposing one hidden card.
Complete terminal fixture: hearts Ace..Queen (12), other three suits Ace..King (39), King of hearts on waste, tableau/stock empty. Move that King to win with four 13-card foundations. After win, permit only Reset. Do not infer a loss or claim solvability from no available move. Reset creates a fresh deal and invalidates old selection/callbacks/status.
Provide keyboard-accessible native card-selection and destination controls, Draw, Redeal, and Reset, with visible rank/suit labels and status. Dragging may be optional but never the only route. Check conservation, visibility, rejected moves, order, terminal guards, focus, actual article width, and 360 px. Record unexecuted checks as not_tested; do not promise storage or host compatibility.
Keep the move record with the prepared HTML
The native source and conservation checks give you a way to diagnose a duplicated card even when the layout looks correct. For an optional HTML version in NOS, the supplied product evidence supports HTML saving and rendering; test card selection, destination controls, and redeal behavior in the actual workspace before calling the hosted version playable. Explore NOS with prepared HTML, keeping the 52-card identity check beside the move rules so the next change has a concrete standard to meet.