magmacrunch-solitaire 0.1.0__tar.gz

magmacrunch_solitaire-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# The link tools/link-shared.mjs makes to the website's arcade/shared/.
+/shared
+__pycache__/
+*.pyc
+.pytest_cache/
+node_modules/
+.DS_Store
+.ruff_cache/
+*.egg-info/
+build/
+sdcard/
+*.dol
+*.elf
+*.map

magmacrunch_solitaire-0.1.0/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright 2026 magmacrunch media (https://magmacrunch.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

magmacrunch_solitaire-0.1.0/NOTICE

@@ -0,0 +1,30 @@
+solitaire
+Copyright 2026 magmacrunch media
+
+
+THE LICENCE
+
+Everything in this repository -- the game in web/, its terminal version in tui/, the
+tools and the documentation -- is licensed under the PolyForm Noncommercial License 1.0.0, in the
+LICENSE file beside this one.
+
+Read it, learn from it, build on it, play with it. Any noncommercial purpose is
+permitted, and that includes personal projects, teaching and research. What is not
+permitted is commercial use: selling the game or a derivative of it, shipping it inside
+a product, or running it as part of a business.
+
+Solitaire is a traditional game and nobody's property; this licence does not pretend
+otherwise. What is licensed is this implementation: the rules engine, the board
+renderer and the arcade's presentation of them.
+
+What is reserved: the magmacrunch name and marks and the visual design of the arcade.
+If you want to use any of it, ask.
+
+
+THIRD-PARTY COMPONENTS
+
+Fonts are loaded from Google Fonts under the SIL Open Font License 1.1 rather than
+shipped here as files.
+
+The page loads adenosine-cards.js, adenosine-score-client.js, arcade-base.css, cards/cards.css, cards/deck-choice.js, score-server.js from the website's arcade/shared/.
+Those are part of the magmacrunch.com repository and adenosine, and are not copied here.

magmacrunch_solitaire-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: magmacrunch-solitaire
+Version: 0.1.0
+Summary: Klondike solitaire, draw three, as the magmacrunch arcade plays it. Terminal version.
+Project-URL: Homepage, https://magmacrunch.com/arcade/solitaire/
+Author: magmacrunch media
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: arcade,cards,games,klondike,solitaire,terminal,tui
+Requires-Python: >=3.10
+Requires-Dist: magmacrunch>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Solitaire (terminal)
+
+The magmacrunch arcade's Solitaire, Klondike draw three, in a terminal. It is
+the second version of the game, beside `web/`. It runs on the
+[magmacrunch](https://github.com/magmacrunch-media/magmacrunch) engine's
+terminal backend, either as a cabinet in the magmacrunch arcade or as its own
+command, and plays the same either way.
+
+```
+pipx install magmacrunch-solitaire
+solitaire                    # the title
+solitaire --play --seed 7    # straight to a deal, the same deals every time
+```
+
+For working on it, from this folder, once the website's `shared/` is linked
+in beside `web/` (`node tools/link-shared.mjs` from the repository's root),
+which the oracle test needs:
+
+```
+pip install -e ".[dev]"
+python -m klondike
+```
+
+## Keys
+
+A cursor stands for the mouse, and ENTER is a click wherever it stands.
+
+| key | |
+|---|---|
+| `←` `→` | along the top row (stock, waste, foundations) or across the columns |
+| `↑` `↓` | up and down a column's face-up cards, and between the top row and the columns |
+| `1` to `7` | a column |
+| `ENTER` `SPACE` | click: draw from the stock, pick a card up, or put the held card there |
+| `F` | double-click: a card to its foundation, if it can go |
+| `D` | draw, wherever the cursor is |
+| `X` | click the felt: put the held card down |
+| `N` | deal again |
+| `H` `S` | help, the scores; the clock stops while they are open |
+| `Esc` `Esc` | leave the deal, for the title (and from there, the arcade) |
+| `Q` | quit |
+
+The stock shows its back and how many cards are left. The waste shows its
+top three, fanned. A column shows its face-down cards as one back and a
+count, then its face-up cards one to a row. The held card is lit cyan and
+the cursor pink. A win shows the page's win screen: time, moves, score, and
+the time bonus, with a NEW HIGH SCORE badge when the score makes the board.
+It goes on the board with its time beside it, as the page saves it.
+
+Needs a 41x24 terminal.
+
+## It is the browser's game, on the browser's clock
+
+`klondike/rules.py` is `web/js/game.js`, method for method, with the deck and
+its shuffle from the website's `shared/adenosine-cards.js`. The page keeps
+its time with a one-second `setInterval`, and that is part of the rules: the
+time on the table, and the bonus a win is paid, are whatever that timer last
+set. So the port keeps the page's clock too. Its time only moves when the
+screen moves it, by the real time gone, and the interval fires at each of
+its seconds on the way. A double click is two clicks on one card inside 300
+ms of that time. Two tests hold the port to the page:
+
+- **`tests/test_oracle.py`.** `tools/js_oracle.mjs` loads those files
+  unmodified on a page that does nothing, with a seeded `Math.random` and a
+  clock of its own. It plays 40 games through the `Solitaire` class the way
+  the page's clicks reach it: the stock, a card, an empty foundation or
+  column, the felt, the menu's pauses and New. Half are a random clicker
+  that now and then clicks the same card again quickly. Half are a greedy
+  player, which won 16 of its 285 deals. That is 134,958 clicks and clock
+  steps. The test makes the same ones through the port and requires the same
+  state after every one: every pile, face up or down, the card held and
+  where from, moves, score, the seconds on the clock, whether it runs, and
+  the win screens set going. Widening the double click to 310 ms fails it at
+  seed 1, event 266; a bonus of x36 fails it at seed 2, event 3,194.
+- **`tests/test_rules.py`.** It sets up by hand the cases worth pinning,
+  including the fixes below, so that undoing one shows as a change.
+
+## Fixed in both
+
+- **Only a column's top card goes to a foundation.** The page checked the card
+  picked and moved the column's top card: with the 5♥ and 4♠ face up and the
+  hearts at 4, picking the 5♥ put the 4♠ on the hearts. Now nothing moves.
+- **A card on a foundation stays there.** Moving one to another foundation
+  counted a move and moved nothing; now it counts nothing.
+- **A won table is finished.** It still played: a king taken off its
+  foundation and put back won again, with a second bonus and a second score.
+  A win now stops the clock for good, and Help and the scores no longer start
+  it again.
+- **The bonus is paid on the time to the win,** read at the winning move, not
+  on the timer's last tick up to a second before it. A win under 30 seconds is
+  paid as 30, so the bonus never falls as a win gets faster: it was 24,500,000
+  at one second and nothing under one.
+- **The clock holds for every reason at once.** A modal and the page being
+  hidden each hold it, and it runs again only once neither does. A new deal
+  starts it clean, and drops a win screen still waiting from the last deal.
+- **A draw puts down a waste card held.** The page kept it held by its old
+  place on the waste, so the next move took whatever card the draw had put
+  there. Worse, holding the waste's king, turning the waste back into the
+  stock and clicking an empty column pushed `undefined` into the column, and
+  every render after threw: in Chromium, "Cannot read properties of
+  undefined (reading 'getHTML')", and the table stopped answering clicks.
+  `drawFromStock` and `draw_from_stock` now put a held waste card down first;
+  a tableau card held stays held. In Chromium the same clicks on the fixed
+  page leave the column empty, and the king, drawn again, goes there. Taking
+  the fix out of the port alone fails the oracle at seed 1, event 252; the
+  trace has 57 draws with a waste card held, three of them turn-overs.
+
+## Licence
+
+PolyForm Noncommercial 1.0.0, as for the rest of this repository. See
+`LICENSE` and `NOTICE`.

magmacrunch_solitaire-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Solitaire (terminal)
+
+The magmacrunch arcade's Solitaire, Klondike draw three, in a terminal. It is
+the second version of the game, beside `web/`. It runs on the
+[magmacrunch](https://github.com/magmacrunch-media/magmacrunch) engine's
+terminal backend, either as a cabinet in the magmacrunch arcade or as its own
+command, and plays the same either way.
+
+```
+pipx install magmacrunch-solitaire
+solitaire                    # the title
+solitaire --play --seed 7    # straight to a deal, the same deals every time
+```
+
+For working on it, from this folder, once the website's `shared/` is linked
+in beside `web/` (`node tools/link-shared.mjs` from the repository's root),
+which the oracle test needs:
+
+```
+pip install -e ".[dev]"
+python -m klondike
+```
+
+## Keys
+
+A cursor stands for the mouse, and ENTER is a click wherever it stands.
+
+| key | |
+|---|---|
+| `←` `→` | along the top row (stock, waste, foundations) or across the columns |
+| `↑` `↓` | up and down a column's face-up cards, and between the top row and the columns |
+| `1` to `7` | a column |
+| `ENTER` `SPACE` | click: draw from the stock, pick a card up, or put the held card there |
+| `F` | double-click: a card to its foundation, if it can go |
+| `D` | draw, wherever the cursor is |
+| `X` | click the felt: put the held card down |
+| `N` | deal again |
+| `H` `S` | help, the scores; the clock stops while they are open |
+| `Esc` `Esc` | leave the deal, for the title (and from there, the arcade) |
+| `Q` | quit |
+
+The stock shows its back and how many cards are left. The waste shows its
+top three, fanned. A column shows its face-down cards as one back and a
+count, then its face-up cards one to a row. The held card is lit cyan and
+the cursor pink. A win shows the page's win screen: time, moves, score, and
+the time bonus, with a NEW HIGH SCORE badge when the score makes the board.
+It goes on the board with its time beside it, as the page saves it.
+
+Needs a 41x24 terminal.
+
+## It is the browser's game, on the browser's clock
+
+`klondike/rules.py` is `web/js/game.js`, method for method, with the deck and
+its shuffle from the website's `shared/adenosine-cards.js`. The page keeps
+its time with a one-second `setInterval`, and that is part of the rules: the
+time on the table, and the bonus a win is paid, are whatever that timer last
+set. So the port keeps the page's clock too. Its time only moves when the
+screen moves it, by the real time gone, and the interval fires at each of
+its seconds on the way. A double click is two clicks on one card inside 300
+ms of that time. Two tests hold the port to the page:
+
+- **`tests/test_oracle.py`.** `tools/js_oracle.mjs` loads those files
+  unmodified on a page that does nothing, with a seeded `Math.random` and a
+  clock of its own. It plays 40 games through the `Solitaire` class the way
+  the page's clicks reach it: the stock, a card, an empty foundation or
+  column, the felt, the menu's pauses and New. Half are a random clicker
+  that now and then clicks the same card again quickly. Half are a greedy
+  player, which won 16 of its 285 deals. That is 134,958 clicks and clock
+  steps. The test makes the same ones through the port and requires the same
+  state after every one: every pile, face up or down, the card held and
+  where from, moves, score, the seconds on the clock, whether it runs, and
+  the win screens set going. Widening the double click to 310 ms fails it at
+  seed 1, event 266; a bonus of x36 fails it at seed 2, event 3,194.
+- **`tests/test_rules.py`.** It sets up by hand the cases worth pinning,
+  including the fixes below, so that undoing one shows as a change.
+
+## Fixed in both
+
+- **Only a column's top card goes to a foundation.** The page checked the card
+  picked and moved the column's top card: with the 5♥ and 4♠ face up and the
+  hearts at 4, picking the 5♥ put the 4♠ on the hearts. Now nothing moves.
+- **A card on a foundation stays there.** Moving one to another foundation
+  counted a move and moved nothing; now it counts nothing.
+- **A won table is finished.** It still played: a king taken off its
+  foundation and put back won again, with a second bonus and a second score.
+  A win now stops the clock for good, and Help and the scores no longer start
+  it again.
+- **The bonus is paid on the time to the win,** read at the winning move, not
+  on the timer's last tick up to a second before it. A win under 30 seconds is
+  paid as 30, so the bonus never falls as a win gets faster: it was 24,500,000
+  at one second and nothing under one.
+- **The clock holds for every reason at once.** A modal and the page being
+  hidden each hold it, and it runs again only once neither does. A new deal
+  starts it clean, and drops a win screen still waiting from the last deal.
+- **A draw puts down a waste card held.** The page kept it held by its old
+  place on the waste, so the next move took whatever card the draw had put
+  there. Worse, holding the waste's king, turning the waste back into the
+  stock and clicking an empty column pushed `undefined` into the column, and
+  every render after threw: in Chromium, "Cannot read properties of
+  undefined (reading 'getHTML')", and the table stopped answering clicks.
+  `drawFromStock` and `draw_from_stock` now put a held waste card down first;
+  a tableau card held stays held. In Chromium the same clicks on the fixed
+  page leave the column empty, and the king, drawn again, goes there. Taking
+  the fix out of the port alone fails the oracle at seed 1, event 252; the
+  trace has 57 draws with a waste card held, three of them turn-overs.
+
+## Licence
+
+PolyForm Noncommercial 1.0.0, as for the rest of this repository. See
+`LICENSE` and `NOTICE`.

magmacrunch_solitaire-0.1.0/klondike/__main__.py

@@ -0,0 +1,27 @@
+"""``python -m klondike`` -- play the arcade's Solitaire: Klondike, draw three."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="solitaire",
+                                     description="Klondike solitaire, draw three.")
+    parser.add_argument("--play", action="store_true", help="skip the title screen")
+    parser.add_argument("--seed", type=int, default=None, help="the same deals every time")
+    parser.add_argument(
+        "--ascii", action="store_true", dest="ascii_only",
+        help="draw with plain ASCII instead of block and box glyphs. Detected "
+             "automatically from the terminal's encoding; this forces it. "
+             "MAGMACRUNCH_ASCII=1 says the same for every cabinet.",
+    )
+    args = parser.parse_args()
+
+    from klondike.app import run
+
+    run(args.seed, args.play, args.ascii_only)
+
+
+if __name__ == "__main__":
+    main()

magmacrunch_solitaire-0.1.0/klondike/app.py

@@ -0,0 +1,98 @@
+"""Wiring -- what outlives one deal, and how the screens reach it.
+
+Everything that draws lives in :mod:`klondike.scenes`; everything that decides
+lives in :mod:`klondike.rules`. **The terminal is not owned here**: it belongs
+to a ``TuiHost``, which is what lets this run as its own command or be seated
+by the arcade.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+from typing import Any
+
+from magmacrunch.engine.scores import ScoreBook
+
+from klondike.arcade import INFO
+from klondike.scenes import GameScene, TitleScene
+
+
+class SolitaireApp:
+    def __init__(self, host: Any, seed: int | None = None,
+                 scores: ScoreBook | None = None,
+                 clock: Callable[[], float] | None = None):
+        self.host = host
+        #: Where each deal's shuffle comes from. Seeded, so ``--seed``
+        #: replays a whole session.
+        self.rng = random.Random(seed)
+        #: The board the browser posts to: the score of a won game, with its
+        #: time beside it.
+        self.scores = scores or ScoreBook(INFO.scoreboard)
+        #: Seconds, for the page's clock. A test hands in its own.
+        self.clock = clock or time.monotonic
+        self.initials = "AAA"
+        self.last_rank: int | None = None
+        self.root_scene = TitleScene(self)
+
+    @property
+    def renderer(self):
+        return self.host.renderer
+
+    def new_rand(self):
+        return random.Random(self.rng.randrange(1 << 32)).random
+
+    def start_game(self) -> None:
+        self.host.push_scene(GameScene(self))
+
+    def show_scores(self) -> None:
+        from klondike.scenes import ScoresScene
+
+        self.host.push_scene(ScoresScene(self))
+
+    def show_rules(self) -> None:
+        from klondike.scenes import RulesScene
+
+        self.host.push_scene(RulesScene(self))
+
+    def enter_initials(self, score: int, extra: dict) -> None:
+        from klondike.scenes import InitialsScene
+
+        self.host.push_scene(InitialsScene(self, score, extra))
+
+    def to_title(self) -> None:
+        self.host.pop_scene()
+
+    def leave(self) -> None:
+        self.host.pop_scene()
+
+    def qualifies(self, score: int) -> bool:
+        """``isHighScore``: above nothing, and in the top ten."""
+        return score > 0 and self.scores.qualifies(score)
+
+    def record(self, score: int, initials: str | None = None,
+               extra: dict | None = None):
+        self.initials = initials or self.initials
+        result = self.scores.save(self.initials, score, **(extra or {}))
+        self.last_rank = result.rank
+        return result
+
+    @property
+    def scene(self):
+        return self.host.scene
+
+
+def run(seed: int | None = None, skip_title: bool = False,
+        ascii_only: bool = False) -> None:
+    """Play Solitaire as its own command."""
+    from magmacrunch.engine.core.tui_host import TuiHost
+    from magmacrunch.engine.ui.glyphs import Glyphs
+
+    host = TuiHost(title=INFO.title, fps=INFO.fps, hold_ms=INFO.hold_ms,
+                   glyphs=Glyphs.detect(ascii_only=ascii_only))
+    app = SolitaireApp(host, seed)
+    host.push_scene(app.root_scene)
+    if skip_title:
+        host.push_scene(GameScene(app))
+    host.run()

magmacrunch_solitaire-0.1.0/klondike/arcade.py

@@ -0,0 +1,39 @@
+"""What the arcade needs to know to launch this game. Kept tiny: a menu loads
+one of these per installed game just to draw a card."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from magmacrunch.engine.arcade import GameInfo
+
+from klondike import theme
+
+INFO = GameInfo(
+    key="solitaire",
+    title="Solitaire",
+    blurb="Klondike, draw three, against the clock.",
+    # The frame rate moves the page's clock and the cursor, nothing else.
+    # Edge input, so one arrow is one step.
+    fps=20,
+    hold_ms=0,
+    min_cols=theme.MIN_COLS,
+    min_rows=theme.MIN_ROWS,
+    accent=theme.PINK,
+)
+
+
+class SolitaireGame:
+    """Satisfies :class:`magmacrunch.engine.arcade.ArcadeGame`."""
+
+    info = INFO
+
+    def start(self, host: Any) -> Any:
+        from klondike.app import SolitaireApp
+
+        return SolitaireApp(host).root_scene
+
+
+GAME = SolitaireGame()
+
+__all__ = ["GAME", "INFO", "SolitaireGame"]