@tastic/cardtastic-engine 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/LICENSE +19 -0
  2. package/README.md +68 -2
  3. package/dist/acesup.d.mts +17 -0
  4. package/dist/acesup.d.ts +17 -0
  5. package/dist/acesup.js +8 -0
  6. package/dist/acesup.mjs +8 -0
  7. package/dist/autoFoundation-CfnFNysj.d.ts +63 -0
  8. package/dist/autoFoundation-Ctp9LKa-.d.mts +63 -0
  9. package/dist/canfield.d.mts +64 -0
  10. package/dist/canfield.d.ts +64 -0
  11. package/dist/canfield.js +20 -0
  12. package/dist/canfield.mjs +20 -0
  13. package/dist/chunk-22DC2YH6.js +95 -0
  14. package/dist/chunk-3BMUGHKQ.mjs +95 -0
  15. package/dist/chunk-4HJ7QMYV.mjs +339 -0
  16. package/dist/chunk-4WAWIFQF.js +131 -0
  17. package/dist/chunk-5266UC2Q.mjs +271 -0
  18. package/dist/chunk-6JWUTZVU.mjs +214 -0
  19. package/dist/chunk-AY3CR5EH.mjs +212 -0
  20. package/dist/chunk-B56TRALO.js +23 -0
  21. package/dist/chunk-CV3VJX34.mjs +341 -0
  22. package/dist/chunk-FDHHAPZA.mjs +177 -0
  23. package/dist/chunk-FTR733R7.mjs +297 -0
  24. package/dist/chunk-GFP5NUYK.mjs +23 -0
  25. package/dist/chunk-IKLYXDG7.mjs +131 -0
  26. package/dist/chunk-LH3UZP7D.js +165 -0
  27. package/dist/chunk-LSS44UKH.js +22 -0
  28. package/dist/chunk-M37CNJHF.mjs +165 -0
  29. package/dist/chunk-PLSNST56.mjs +163 -0
  30. package/dist/chunk-PTRHGPCN.js +163 -0
  31. package/dist/chunk-S3WNVF2K.js +339 -0
  32. package/dist/chunk-SDZPP3HI.mjs +22 -0
  33. package/dist/chunk-SLQ7RGMZ.js +212 -0
  34. package/dist/chunk-TNMFNWEM.mjs +249 -0
  35. package/dist/chunk-VGJPT3CX.js +214 -0
  36. package/dist/chunk-W5CPH6TD.js +115 -0
  37. package/dist/chunk-WJGEX74V.js +341 -0
  38. package/dist/chunk-WKES4P36.js +297 -0
  39. package/dist/chunk-XPTQNUF3.js +348 -0
  40. package/dist/chunk-XSS5M6C7.mjs +115 -0
  41. package/dist/chunk-XTHDUWJF.js +271 -0
  42. package/dist/chunk-XV5OUPIW.js +177 -0
  43. package/dist/chunk-YKY4K67K.mjs +348 -0
  44. package/dist/chunk-ZMNGTXU5.js +249 -0
  45. package/dist/fortythieves.d.mts +50 -0
  46. package/dist/fortythieves.d.ts +50 -0
  47. package/dist/fortythieves.js +22 -0
  48. package/dist/fortythieves.mjs +22 -0
  49. package/dist/freecell.d.mts +30 -0
  50. package/dist/freecell.d.ts +30 -0
  51. package/dist/freecell.js +18 -0
  52. package/dist/freecell.mjs +18 -0
  53. package/dist/gameTypes-BnfLkwzA.d.mts +201 -0
  54. package/dist/gameTypes-BnfLkwzA.d.ts +201 -0
  55. package/dist/golf.d.mts +17 -0
  56. package/dist/golf.d.ts +17 -0
  57. package/dist/golf.js +7 -0
  58. package/dist/golf.mjs +7 -0
  59. package/dist/index.d.mts +176 -0
  60. package/dist/index.d.ts +176 -0
  61. package/dist/index.js +446 -0
  62. package/dist/index.mjs +446 -0
  63. package/dist/klondike.d.mts +25 -0
  64. package/dist/klondike.d.ts +25 -0
  65. package/dist/klondike.js +15 -0
  66. package/dist/klondike.mjs +15 -0
  67. package/dist/pyramid.d.mts +36 -0
  68. package/dist/pyramid.d.ts +36 -0
  69. package/dist/pyramid.js +16 -0
  70. package/dist/pyramid.mjs +16 -0
  71. package/dist/scorpion.d.mts +14 -0
  72. package/dist/scorpion.d.ts +14 -0
  73. package/dist/scorpion.js +9 -0
  74. package/dist/scorpion.mjs +9 -0
  75. package/dist/spider.d.mts +22 -0
  76. package/dist/spider.d.ts +22 -0
  77. package/dist/spider.js +11 -0
  78. package/dist/spider.mjs +11 -0
  79. package/dist/tripeaks.d.mts +43 -0
  80. package/dist/tripeaks.d.ts +43 -0
  81. package/dist/tripeaks.js +19 -0
  82. package/dist/tripeaks.mjs +19 -0
  83. package/dist/yukon.d.mts +24 -0
  84. package/dist/yukon.d.ts +24 -0
  85. package/dist/yukon.js +15 -0
  86. package/dist/yukon.mjs +15 -0
  87. package/package.json +187 -4
@@ -0,0 +1,50 @@
1
+ import { AutoCompleteStep, FinishMove } from './index.js';
2
+ import { Card, GameController, AccessibleCard } from './index.js';
3
+
4
+ interface FortyThievesState {
5
+ /** 10 tableau columns, 4 cards each at deal, all face up. */
6
+ tableau: Card[][];
7
+ /** 8 independent foundation piles - see this file's header comment on why they aren't
8
+ * fixed one-per-suit. */
9
+ foundation: Card[][];
10
+ /** 64-card face-down draw pile at deal. No recycling once empty. */
11
+ stock: Card[];
12
+ waste: Card[];
13
+ }
14
+ /** Which foundation pile `card` belongs on: a non-empty pile of its own suit already waiting for
15
+ * exactly this rank, or - failing that - an unclaimed (empty) pile, but only for an Ace (nothing
16
+ * else may start a fresh pile). Returns null if neither exists (e.g. a non-Ace whose suit hasn't
17
+ * been started at all yet, or whose two piles are both already ahead of or behind this rank). */
18
+ declare function findFoundationSlot(foundation: Card[][], card: Card): number | null;
19
+ /** Closes over `runMoves` (settings.fortyThievesRunMoves) - the only rule this game's tableau move
20
+ * logic varies by. */
21
+ declare function createFortyThievesController(runMoves: boolean): GameController<FortyThievesState>;
22
+ /** True if the entire remaining game can be cleared via foundation moves alone, in some order -
23
+ * see engine/autoFoundation.ts's own isFullyAutoCompletable for the full "why a plain greedy
24
+ * simulation is correct here" reasoning, which applies unchanged to this game's own foundation
25
+ * shape. */
26
+ declare function isFullyAutoCompletable(controller: Pick<GameController<FortyThievesState>, 'isWon' | 'accessibleCards' | 'tryMove'>, state: FortyThievesState): boolean;
27
+ /** The next single move in a full auto-complete cascade - only meaningful once
28
+ * isFullyAutoCompletable has confirmed true; each successive call (after applying the previous
29
+ * move for real) advances the cascade by exactly one card. */
30
+ declare function nextAutoCompleteMove(controller: Pick<GameController<FortyThievesState>, 'accessibleCards' | 'tryMove'>, state: FortyThievesState): AccessibleCard | null;
31
+ /** True while the board is SOLVED: nothing hidden and no choice left - the stock and the waste are
32
+ * empty (the stock is the only place a face-down card can be here, see newGame/drawStock), the game
33
+ * isn't won yet, and every remaining tableau card can go up by foundation moves alone. The explicit
34
+ * isWon matters: isFullyAutoCompletable is true on a won board, and the finish would never end. Takes
35
+ * the controller because the screen's is per deal (controllerRef), though no foundation move depends
36
+ * on its runMoves. */
37
+ declare function canAutoFinish(controller: Pick<GameController<FortyThievesState>, 'isWon' | 'accessibleCards' | 'tryMove'>, state: FortyThievesState): boolean;
38
+ /** The next card the finish sends up and the foundation pile it goes to (findFoundationSlot's - one
39
+ * of two piles per suit, not a fixed one), or null unless the board is solved. */
40
+ declare function nextFinishMove(controller: Pick<GameController<FortyThievesState>, 'isWon' | 'accessibleCards' | 'tryMove'>, state: FortyThievesState): FinishMove | null;
41
+ /** Draws-aware counterpart of isFullyAutoCompletable above - see engine/autoFoundation.ts's shared
42
+ * isFullyAutoCompletableWithDraws for the full termination argument, which applies unchanged here. */
43
+ declare function isFullyAutoCompletableWithDraws(controller: Pick<GameController<FortyThievesState>, 'isWon' | 'accessibleCards' | 'tryMove' | 'drawStock'>, state: FortyThievesState): boolean;
44
+ /** The next single step in a draws-aware full auto-complete cascade - only meaningful once
45
+ * isFullyAutoCompletableWithDraws has confirmed true; each successive call (after applying the
46
+ * previous step for real) advances the cascade by exactly one step. */
47
+ declare function nextAutoCompleteMoveWithDraws(controller: Pick<GameController<FortyThievesState>, 'accessibleCards' | 'tryMove' | 'drawStock'>, state: FortyThievesState): AutoCompleteStep | null;
48
+
49
+ export { canAutoFinish, createFortyThievesController, findFoundationSlot, isFullyAutoCompletable, isFullyAutoCompletableWithDraws, nextAutoCompleteMove, nextAutoCompleteMoveWithDraws, nextFinishMove };
50
+ export type { FortyThievesState };
@@ -0,0 +1,22 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true});
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+ var _chunkWJGEX74Vjs = require('./chunk-WJGEX74V.js');
11
+ require('./chunk-XV5OUPIW.js');
12
+ require('./chunk-W5CPH6TD.js');
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+ exports.canAutoFinish = _chunkWJGEX74Vjs.canAutoFinish; exports.createFortyThievesController = _chunkWJGEX74Vjs.createFortyThievesController; exports.findFoundationSlot = _chunkWJGEX74Vjs.findFoundationSlot; exports.isFullyAutoCompletable = _chunkWJGEX74Vjs.isFullyAutoCompletable; exports.isFullyAutoCompletableWithDraws = _chunkWJGEX74Vjs.isFullyAutoCompletableWithDraws; exports.nextAutoCompleteMove = _chunkWJGEX74Vjs.nextAutoCompleteMove; exports.nextAutoCompleteMoveWithDraws = _chunkWJGEX74Vjs.nextAutoCompleteMoveWithDraws; exports.nextFinishMove = _chunkWJGEX74Vjs.nextFinishMove;
@@ -0,0 +1,22 @@
1
+ import {
2
+ canAutoFinish,
3
+ createFortyThievesController,
4
+ findFoundationSlot,
5
+ isFullyAutoCompletable,
6
+ isFullyAutoCompletableWithDraws,
7
+ nextAutoCompleteMove,
8
+ nextAutoCompleteMoveWithDraws,
9
+ nextFinishMove
10
+ } from "./chunk-CV3VJX34.mjs";
11
+ import "./chunk-FDHHAPZA.mjs";
12
+ import "./chunk-XSS5M6C7.mjs";
13
+ export {
14
+ canAutoFinish,
15
+ createFortyThievesController,
16
+ findFoundationSlot,
17
+ isFullyAutoCompletable,
18
+ isFullyAutoCompletableWithDraws,
19
+ nextAutoCompleteMove,
20
+ nextAutoCompleteMoveWithDraws,
21
+ nextFinishMove
22
+ };
@@ -0,0 +1,30 @@
1
+ import { GameController, Card, PileRef } from './index.mjs';
2
+
3
+ interface FreeCellState {
4
+ /** 8 tableau columns, all cards always face-up. */
5
+ tableau: Card[][];
6
+ /** 4 freecells, each holds 0 or 1 card. */
7
+ freecells: (Card | null)[];
8
+ /** 4 foundation piles, indexed to match engine/foundation's FOUNDATION_SUITS order (spades, diamonds, clubs, hearts). */
9
+ foundation: Card[][];
10
+ }
11
+ declare function countEmptyFreecells(state: FreeCellState): number;
12
+ /** Count empty tableau columns, excluding `excludeIndex` (the move's own destination doesn't help).
13
+ * Exported alongside countEmptyFreecells/maxSupermoveCount so a UI can explain a failed move in
14
+ * terms of the exact numbers that produced its cap (see FreeCellScreen.tsx's completeMove). */
15
+ declare function countEmptyTableauColumns(state: FreeCellState, excludeIndex: number): number;
16
+ /** Max cards movable together in one tableau->tableau move (the "supermove" convention). Pass a
17
+ * `destIndex` that matches no real column (e.g. -1) to get the best-case cap - the size achievable
18
+ * when the destination isn't itself one of the empty columns - for previews that don't yet know
19
+ * the destination (see FreeCellScreen.tsx's tableauRunCount, which dims a card whose own coherent
20
+ * run exceeds even this generous cap). */
21
+ declare function maxSupermoveCount(state: FreeCellState, destIndex: number): number;
22
+ /** The card at the head of a `count`-card move from `from` - the first of the run, the one a
23
+ * player grabs and a flight is drawn for - or undefined if `from` holds fewer than `count` cards.
24
+ * tryMove itself only knows positions, so callers use this to check a move is still about the card
25
+ * they meant. */
26
+ declare function moveHeadCard(state: FreeCellState, from: PileRef, count: number): Card | undefined;
27
+ declare const FreeCellController: GameController<FreeCellState>;
28
+
29
+ export { FreeCellController, countEmptyFreecells, countEmptyTableauColumns, maxSupermoveCount, moveHeadCard };
30
+ export type { FreeCellState };
@@ -0,0 +1,30 @@
1
+ import { GameController, Card, PileRef } from './index.js';
2
+
3
+ interface FreeCellState {
4
+ /** 8 tableau columns, all cards always face-up. */
5
+ tableau: Card[][];
6
+ /** 4 freecells, each holds 0 or 1 card. */
7
+ freecells: (Card | null)[];
8
+ /** 4 foundation piles, indexed to match engine/foundation's FOUNDATION_SUITS order (spades, diamonds, clubs, hearts). */
9
+ foundation: Card[][];
10
+ }
11
+ declare function countEmptyFreecells(state: FreeCellState): number;
12
+ /** Count empty tableau columns, excluding `excludeIndex` (the move's own destination doesn't help).
13
+ * Exported alongside countEmptyFreecells/maxSupermoveCount so a UI can explain a failed move in
14
+ * terms of the exact numbers that produced its cap (see FreeCellScreen.tsx's completeMove). */
15
+ declare function countEmptyTableauColumns(state: FreeCellState, excludeIndex: number): number;
16
+ /** Max cards movable together in one tableau->tableau move (the "supermove" convention). Pass a
17
+ * `destIndex` that matches no real column (e.g. -1) to get the best-case cap - the size achievable
18
+ * when the destination isn't itself one of the empty columns - for previews that don't yet know
19
+ * the destination (see FreeCellScreen.tsx's tableauRunCount, which dims a card whose own coherent
20
+ * run exceeds even this generous cap). */
21
+ declare function maxSupermoveCount(state: FreeCellState, destIndex: number): number;
22
+ /** The card at the head of a `count`-card move from `from` - the first of the run, the one a
23
+ * player grabs and a flight is drawn for - or undefined if `from` holds fewer than `count` cards.
24
+ * tryMove itself only knows positions, so callers use this to check a move is still about the card
25
+ * they meant. */
26
+ declare function moveHeadCard(state: FreeCellState, from: PileRef, count: number): Card | undefined;
27
+ declare const FreeCellController: GameController<FreeCellState>;
28
+
29
+ export { FreeCellController, countEmptyFreecells, countEmptyTableauColumns, maxSupermoveCount, moveHeadCard };
30
+ export type { FreeCellState };
@@ -0,0 +1,18 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true});
2
+
3
+
4
+
5
+
6
+
7
+ var _chunkWKES4P36js = require('./chunk-WKES4P36.js');
8
+ require('./chunk-LSS44UKH.js');
9
+ require('./chunk-B56TRALO.js');
10
+ require('./chunk-XV5OUPIW.js');
11
+ require('./chunk-W5CPH6TD.js');
12
+
13
+
14
+
15
+
16
+
17
+
18
+ exports.FreeCellController = _chunkWKES4P36js.FreeCellController; exports.countEmptyFreecells = _chunkWKES4P36js.countEmptyFreecells; exports.countEmptyTableauColumns = _chunkWKES4P36js.countEmptyTableauColumns; exports.maxSupermoveCount = _chunkWKES4P36js.maxSupermoveCount; exports.moveHeadCard = _chunkWKES4P36js.moveHeadCard;
@@ -0,0 +1,18 @@
1
+ import {
2
+ FreeCellController,
3
+ countEmptyFreecells,
4
+ countEmptyTableauColumns,
5
+ maxSupermoveCount,
6
+ moveHeadCard
7
+ } from "./chunk-FTR733R7.mjs";
8
+ import "./chunk-SDZPP3HI.mjs";
9
+ import "./chunk-GFP5NUYK.mjs";
10
+ import "./chunk-FDHHAPZA.mjs";
11
+ import "./chunk-XSS5M6C7.mjs";
12
+ export {
13
+ FreeCellController,
14
+ countEmptyFreecells,
15
+ countEmptyTableauColumns,
16
+ maxSupermoveCount,
17
+ moveHeadCard
18
+ };
@@ -0,0 +1,201 @@
1
+ /** One step of a search: a move, or a draw from the stock. */
2
+ type SearchStep = {
3
+ kind: 'move';
4
+ move: Move;
5
+ } | {
6
+ kind: 'draw';
7
+ };
8
+ /**
9
+ * A game's idea of progress, for the look-ahead behind Hint (engine/hint.ts) and the dead-board check
10
+ * (games/shared/useStuckLossCheck.ts). Optional on GameController: a game without one keeps the plain scored Hint.
11
+ */
12
+ interface ProgressSpec<S> {
13
+ /** The rules this describes, e.g. 'klondike-draw3': a board's look-ahead is kept by it (engine/hint.ts), and two specs
14
+ * with the same id search alike, so a screen's rules made twice share one. */
15
+ id: string;
16
+ /** Every move worth looking at from here. Unlike legalMoves, which narrows each run to the one column tap-to-move would
17
+ * pick, every destination: the dead-board check is only exact when nothing reachable is left out (see allDestinations). */
18
+ moves(state: S): Move[];
19
+ /** Moves the dead-board check also tries but Hint never suggests: a card back down off a foundation. Hint leaving them
20
+ * out isn't only taste: the board after one is a foundation card short, so from there the card going straight back up
21
+ * is "progress", and Hint would offer the two moves turn about. */
22
+ rescueMoves?(state: S): Move[];
23
+ /** Whether a draw is a step of the search. True for a stock that turns over and comes round again (Klondike, Canfield,
24
+ * Pyramid): drawing is only a way to reach its cards. False for a stock dealt out for good (Spider, Scorpion, Aces Up,
25
+ * Forty Thieves): the search stays on the board in front of the player, and a draw is what's left when it finds nothing. */
26
+ drawIsStep: boolean;
27
+ /** Two states with the same key are the same position (columns may be listed in any order). */
28
+ key(state: S): string;
29
+ /** Counts that only ever go up as a deal is won: cards turned over, cards on the foundations, runs completed, cards
30
+ * cleared. A position is progress when any of them is higher than where the search started. Winning always raises one,
31
+ * so a board from which no position is progress can't be won. */
32
+ progress(state: S): number[];
33
+ }
34
+ interface SearchOutcome {
35
+ /** Whether the search reached progress. */
36
+ found: 'progress' | null;
37
+ /** The first step of every shortest way there, in the order Hint should offer them. */
38
+ firstSteps: SearchStep[];
39
+ /** Every position reachable from the start was looked at, so `found: null` means the board can't make progress. */
40
+ exhausted: boolean;
41
+ /** Positions expanded. */
42
+ nodes: number;
43
+ }
44
+ /** 'hint' finds the shortest ways to progress (all of their first steps); 'alive' stops at the first progress it finds,
45
+ * and is only interested in whether there is any (and tries the rescue moves too). */
46
+ type SearchMode = 'hint' | 'alive';
47
+ type SearchController<S> = Pick<GameController<S>, 'tryMove'> & Partial<Pick<GameController<S>, 'drawStock' | 'scoreHintMove'>>;
48
+ /**
49
+ * A breadth-first look-ahead from one position, run in slices (`step`) so a long one can be spread over several frames.
50
+ * Every position is expanded once (by `spec.key`). A position that is progress over the start is a goal and is not looked
51
+ * past: Hint only needs the first step toward it, and a card turned over is all the search may know about it (it can see
52
+ * face-down cards, but a hint must not lean on them).
53
+ */
54
+ declare class ProgressSearch<S> {
55
+ private readonly controller;
56
+ private readonly spec;
57
+ private readonly mode;
58
+ private readonly queue;
59
+ private head;
60
+ private readonly seen;
61
+ private readonly startProgress;
62
+ private progressDepth;
63
+ private readonly progressFirst;
64
+ private readonly progressKeys;
65
+ private nodes;
66
+ private done;
67
+ private exhausted;
68
+ constructor(controller: SearchController<S>, spec: ProgressSpec<S>, start: S, mode: SearchMode);
69
+ /** Expands up to `maxNodes` more positions; true once the search has its answer. */
70
+ step(maxNodes: number): boolean;
71
+ /** Positions expanded so far. */
72
+ get expanded(): number;
73
+ /** Runs to the end, or until `budget` positions have been expanded, or (given) `maxMs` have passed. */
74
+ run(budget: number, maxMs?: number): SearchOutcome;
75
+ outcome(): SearchOutcome;
76
+ /** True when the search can stop (alive mode found progress). */
77
+ private expand;
78
+ /** At the start, the order Hint should offer moves in when several get somewhere equally soon: foundation moves first,
79
+ * then the game's own scorer. Deeper down the order doesn't matter, so it is left as it comes. */
80
+ private orderedMoves;
81
+ }
82
+ /** Positions, and milliseconds, a Hint press looks at itself when the look-ahead run after the last move hasn't finished
83
+ * yet. A position costs ~5-15us in Node (Klondike to Spider with empty columns: ~70us), several times that in Hermes, so the
84
+ * time cap is what holds on a phone; the few boards that need more get the background's answer once it has one. */
85
+ declare const HINT_SEARCH_BUDGET = 1500;
86
+ declare const HINT_SEARCH_MAX_MS = 80;
87
+ /** Positions the look-ahead after each move expands (games/shared/useBoardLookahead.ts), a few at a time: enough to find
88
+ * progress on nearly every board, and to see that a dead board is dead (5,000-11,000 positions on Klondike's hardest).
89
+ * LOOKAHEAD_MAX_MS caps the time it spends, in slices, on any one board, whatever the phone: a board it runs out on is
90
+ * simply not known to be dead. */
91
+ declare const LOOKAHEAD_BUDGET = 40000;
92
+ declare const LOOKAHEAD_MAX_MS = 1000;
93
+ /** Whether an outcome is the whole answer: progress found, or every reachable position looked at. Anything else is
94
+ * worth looking at further. */
95
+ declare function isConclusive(outcome: SearchOutcome): boolean;
96
+ /**
97
+ * legalMoves narrowed to one destination per run (the column tap-to-move picks); this adds every other pile of the
98
+ * `zones` named (e.g. { tableau: 7 }) that takes the same run, and any `extra` moves the game allows but legalMoves never
99
+ * offers (a card back down off a foundation). Duplicates are dropped.
100
+ */
101
+ declare function allDestinations<S>(controller: Pick<GameController<S>, 'legalMoves' | 'tryMove'>, state: S, zones: Record<string, number>, extra?: Move[]): Move[];
102
+ /** A foundation's top card back down onto each column that takes it (`takes(column, [card])`), for a game whose tryMove
103
+ * allows it but whose legalMoves never offers it (see allDestinations' `extra`). */
104
+ declare function foundationDownMoves<C>(foundations: readonly (readonly C[])[], columns: readonly C[][], takes: (column: C[], moving: C[]) => boolean): Move[];
105
+ /** A pile in a position key. */
106
+ declare function pileKey(cards: readonly {
107
+ suit: string;
108
+ rank: number;
109
+ faceUp: boolean;
110
+ }[]): string;
111
+ /** Columns in a position key, in any order: the same cards in other columns are the same position. */
112
+ declare function columnsKey(columns: readonly (readonly {
113
+ suit: string;
114
+ rank: number;
115
+ faceUp: boolean;
116
+ }[])[]): string;
117
+ /** Cards face-down in the columns. */
118
+ declare function faceDownCount(columns: readonly (readonly {
119
+ faceUp: boolean;
120
+ }[])[]): number;
121
+
122
+ type Suit = 'clubs' | 'diamonds' | 'hearts' | 'spades';
123
+ type Rank = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
124
+ type Color = 'red' | 'black';
125
+ interface Card {
126
+ /** Stable unique id, e.g. "hearts-7-0" (the deck index suffix keeps two decks' cards apart). */
127
+ id: string;
128
+ suit: Suit;
129
+ rank: Rank;
130
+ faceUp: boolean;
131
+ }
132
+ declare const SUITS: Suit[];
133
+ declare function cardColor(suit: Suit): Color;
134
+
135
+ interface PileRef {
136
+ /** Logical zone name within the game's own state, e.g. 'tableau' | 'foundation' | 'stock' | 'waste' | 'freecell'. */
137
+ zone: string;
138
+ /** Which pile within that zone (0-indexed). Zones with a single pile (e.g. stock) always use 0. */
139
+ index: number;
140
+ }
141
+ interface Move {
142
+ from: PileRef;
143
+ to: PileRef;
144
+ /** How many cards from the top of `from` to move together (1 for a single card). */
145
+ count: number;
146
+ }
147
+ /** A card currently sitting at a legally-reachable position - a tableau top, a freecell, a waste
148
+ * top - the unit engine/autoFoundation.ts scans over for the auto-play-to-foundation feature.
149
+ * Lives here rather than in autoFoundation.ts itself so that file can import PileRef/GameController
150
+ * from this one without a cycle. */
151
+ interface AccessibleCard {
152
+ ref: PileRef;
153
+ card: Card;
154
+ }
155
+ interface GameController<TState> {
156
+ id: string;
157
+ title: string;
158
+ /** Deal a brand new game from a seed (same seed -> same deal, for testability / shareable game numbers). */
159
+ newGame(seed: number): TState;
160
+ /** All currently legal moves - used for hints and "no moves left" detection. */
161
+ legalMoves(state: TState): Move[];
162
+ /** Attempt a move. Returns a new state if legal, or null if illegal (state is never mutated in place). */
163
+ tryMove(state: TState, move: Move): TState | null;
164
+ /** Draw from stock / recycle waste, etc. Returns a new state, or null if not applicable right now. */
165
+ drawStock?(state: TState): TState | null;
166
+ isWon(state: TState): boolean;
167
+ /** True if no legal moves and no stock draw remain (used for "stuck" banners). */
168
+ isStuck?(state: TState): boolean;
169
+ /**
170
+ * Optional: given a single tapped card, find its best automatic destination - a foundation move
171
+ * if one exists, otherwise the best tableau destination (fewest buried cards, then largest pile,
172
+ * then leftmost, breaking ties in that order), or null if the card has nowhere legal to go.
173
+ * Powers tap-to-auto-move; calling it again with the card now sitting at that destination finds
174
+ * the next-best destination from there, since the one it just left is no longer a valid target.
175
+ */
176
+ autoMoveHint?(state: TState, from: PileRef, cardId: string): Move | null;
177
+ /**
178
+ * Optional: scores a legal move for Hint-ordering purposes - higher means more worth
179
+ * suggesting. A non-positive score on every legal move (see engine/hint.ts's findHint) means
180
+ * "nothing productive available," which prefers a stock-draw suggestion over the best of a bad
181
+ * lot, where one's legal. Games without this keep legalMoves()'s own raw order (foundation-bound
182
+ * moves first, otherwise whatever order legalMoves() returned them).
183
+ */
184
+ scoreHintMove?(state: TState, move: Move): number;
185
+ /**
186
+ * Optional: every card currently sitting at a legally-reachable position - tableau tops,
187
+ * freecell contents, a waste top - for the auto-play-to-foundation feature (see
188
+ * engine/autoFoundation.ts) to scan. Never includes stock or anything else that would need an
189
+ * extra action (like a draw) to become reachable.
190
+ */
191
+ accessibleCards?(state: TState): AccessibleCard[];
192
+ /**
193
+ * Optional: what counts as progress in this game (cards turned over, cards on the foundations, runs completed), for
194
+ * the look-ahead behind Hint and the dead-board check (see engine/progressSearch.ts). A game without one keeps the
195
+ * scored Hint and only its own isStuck.
196
+ */
197
+ progress?: ProgressSpec<TState>;
198
+ }
199
+
200
+ export { HINT_SEARCH_BUDGET as H, LOOKAHEAD_BUDGET as L, HINT_SEARCH_MAX_MS as d, LOOKAHEAD_MAX_MS as e, ProgressSearch as f, SUITS as g, allDestinations as j, cardColor as k, columnsKey as l, faceDownCount as m, foundationDownMoves as n, isConclusive as o, pileKey as p };
201
+ export type { AccessibleCard as A, Card as C, GameController as G, Move as M, PileRef as P, Rank as R, Suit as S, ProgressSpec as a, SearchOutcome as b, Color as c, SearchMode as h, SearchStep as i };
@@ -0,0 +1,201 @@
1
+ /** One step of a search: a move, or a draw from the stock. */
2
+ type SearchStep = {
3
+ kind: 'move';
4
+ move: Move;
5
+ } | {
6
+ kind: 'draw';
7
+ };
8
+ /**
9
+ * A game's idea of progress, for the look-ahead behind Hint (engine/hint.ts) and the dead-board check
10
+ * (games/shared/useStuckLossCheck.ts). Optional on GameController: a game without one keeps the plain scored Hint.
11
+ */
12
+ interface ProgressSpec<S> {
13
+ /** The rules this describes, e.g. 'klondike-draw3': a board's look-ahead is kept by it (engine/hint.ts), and two specs
14
+ * with the same id search alike, so a screen's rules made twice share one. */
15
+ id: string;
16
+ /** Every move worth looking at from here. Unlike legalMoves, which narrows each run to the one column tap-to-move would
17
+ * pick, every destination: the dead-board check is only exact when nothing reachable is left out (see allDestinations). */
18
+ moves(state: S): Move[];
19
+ /** Moves the dead-board check also tries but Hint never suggests: a card back down off a foundation. Hint leaving them
20
+ * out isn't only taste: the board after one is a foundation card short, so from there the card going straight back up
21
+ * is "progress", and Hint would offer the two moves turn about. */
22
+ rescueMoves?(state: S): Move[];
23
+ /** Whether a draw is a step of the search. True for a stock that turns over and comes round again (Klondike, Canfield,
24
+ * Pyramid): drawing is only a way to reach its cards. False for a stock dealt out for good (Spider, Scorpion, Aces Up,
25
+ * Forty Thieves): the search stays on the board in front of the player, and a draw is what's left when it finds nothing. */
26
+ drawIsStep: boolean;
27
+ /** Two states with the same key are the same position (columns may be listed in any order). */
28
+ key(state: S): string;
29
+ /** Counts that only ever go up as a deal is won: cards turned over, cards on the foundations, runs completed, cards
30
+ * cleared. A position is progress when any of them is higher than where the search started. Winning always raises one,
31
+ * so a board from which no position is progress can't be won. */
32
+ progress(state: S): number[];
33
+ }
34
+ interface SearchOutcome {
35
+ /** Whether the search reached progress. */
36
+ found: 'progress' | null;
37
+ /** The first step of every shortest way there, in the order Hint should offer them. */
38
+ firstSteps: SearchStep[];
39
+ /** Every position reachable from the start was looked at, so `found: null` means the board can't make progress. */
40
+ exhausted: boolean;
41
+ /** Positions expanded. */
42
+ nodes: number;
43
+ }
44
+ /** 'hint' finds the shortest ways to progress (all of their first steps); 'alive' stops at the first progress it finds,
45
+ * and is only interested in whether there is any (and tries the rescue moves too). */
46
+ type SearchMode = 'hint' | 'alive';
47
+ type SearchController<S> = Pick<GameController<S>, 'tryMove'> & Partial<Pick<GameController<S>, 'drawStock' | 'scoreHintMove'>>;
48
+ /**
49
+ * A breadth-first look-ahead from one position, run in slices (`step`) so a long one can be spread over several frames.
50
+ * Every position is expanded once (by `spec.key`). A position that is progress over the start is a goal and is not looked
51
+ * past: Hint only needs the first step toward it, and a card turned over is all the search may know about it (it can see
52
+ * face-down cards, but a hint must not lean on them).
53
+ */
54
+ declare class ProgressSearch<S> {
55
+ private readonly controller;
56
+ private readonly spec;
57
+ private readonly mode;
58
+ private readonly queue;
59
+ private head;
60
+ private readonly seen;
61
+ private readonly startProgress;
62
+ private progressDepth;
63
+ private readonly progressFirst;
64
+ private readonly progressKeys;
65
+ private nodes;
66
+ private done;
67
+ private exhausted;
68
+ constructor(controller: SearchController<S>, spec: ProgressSpec<S>, start: S, mode: SearchMode);
69
+ /** Expands up to `maxNodes` more positions; true once the search has its answer. */
70
+ step(maxNodes: number): boolean;
71
+ /** Positions expanded so far. */
72
+ get expanded(): number;
73
+ /** Runs to the end, or until `budget` positions have been expanded, or (given) `maxMs` have passed. */
74
+ run(budget: number, maxMs?: number): SearchOutcome;
75
+ outcome(): SearchOutcome;
76
+ /** True when the search can stop (alive mode found progress). */
77
+ private expand;
78
+ /** At the start, the order Hint should offer moves in when several get somewhere equally soon: foundation moves first,
79
+ * then the game's own scorer. Deeper down the order doesn't matter, so it is left as it comes. */
80
+ private orderedMoves;
81
+ }
82
+ /** Positions, and milliseconds, a Hint press looks at itself when the look-ahead run after the last move hasn't finished
83
+ * yet. A position costs ~5-15us in Node (Klondike to Spider with empty columns: ~70us), several times that in Hermes, so the
84
+ * time cap is what holds on a phone; the few boards that need more get the background's answer once it has one. */
85
+ declare const HINT_SEARCH_BUDGET = 1500;
86
+ declare const HINT_SEARCH_MAX_MS = 80;
87
+ /** Positions the look-ahead after each move expands (games/shared/useBoardLookahead.ts), a few at a time: enough to find
88
+ * progress on nearly every board, and to see that a dead board is dead (5,000-11,000 positions on Klondike's hardest).
89
+ * LOOKAHEAD_MAX_MS caps the time it spends, in slices, on any one board, whatever the phone: a board it runs out on is
90
+ * simply not known to be dead. */
91
+ declare const LOOKAHEAD_BUDGET = 40000;
92
+ declare const LOOKAHEAD_MAX_MS = 1000;
93
+ /** Whether an outcome is the whole answer: progress found, or every reachable position looked at. Anything else is
94
+ * worth looking at further. */
95
+ declare function isConclusive(outcome: SearchOutcome): boolean;
96
+ /**
97
+ * legalMoves narrowed to one destination per run (the column tap-to-move picks); this adds every other pile of the
98
+ * `zones` named (e.g. { tableau: 7 }) that takes the same run, and any `extra` moves the game allows but legalMoves never
99
+ * offers (a card back down off a foundation). Duplicates are dropped.
100
+ */
101
+ declare function allDestinations<S>(controller: Pick<GameController<S>, 'legalMoves' | 'tryMove'>, state: S, zones: Record<string, number>, extra?: Move[]): Move[];
102
+ /** A foundation's top card back down onto each column that takes it (`takes(column, [card])`), for a game whose tryMove
103
+ * allows it but whose legalMoves never offers it (see allDestinations' `extra`). */
104
+ declare function foundationDownMoves<C>(foundations: readonly (readonly C[])[], columns: readonly C[][], takes: (column: C[], moving: C[]) => boolean): Move[];
105
+ /** A pile in a position key. */
106
+ declare function pileKey(cards: readonly {
107
+ suit: string;
108
+ rank: number;
109
+ faceUp: boolean;
110
+ }[]): string;
111
+ /** Columns in a position key, in any order: the same cards in other columns are the same position. */
112
+ declare function columnsKey(columns: readonly (readonly {
113
+ suit: string;
114
+ rank: number;
115
+ faceUp: boolean;
116
+ }[])[]): string;
117
+ /** Cards face-down in the columns. */
118
+ declare function faceDownCount(columns: readonly (readonly {
119
+ faceUp: boolean;
120
+ }[])[]): number;
121
+
122
+ type Suit = 'clubs' | 'diamonds' | 'hearts' | 'spades';
123
+ type Rank = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
124
+ type Color = 'red' | 'black';
125
+ interface Card {
126
+ /** Stable unique id, e.g. "hearts-7-0" (the deck index suffix keeps two decks' cards apart). */
127
+ id: string;
128
+ suit: Suit;
129
+ rank: Rank;
130
+ faceUp: boolean;
131
+ }
132
+ declare const SUITS: Suit[];
133
+ declare function cardColor(suit: Suit): Color;
134
+
135
+ interface PileRef {
136
+ /** Logical zone name within the game's own state, e.g. 'tableau' | 'foundation' | 'stock' | 'waste' | 'freecell'. */
137
+ zone: string;
138
+ /** Which pile within that zone (0-indexed). Zones with a single pile (e.g. stock) always use 0. */
139
+ index: number;
140
+ }
141
+ interface Move {
142
+ from: PileRef;
143
+ to: PileRef;
144
+ /** How many cards from the top of `from` to move together (1 for a single card). */
145
+ count: number;
146
+ }
147
+ /** A card currently sitting at a legally-reachable position - a tableau top, a freecell, a waste
148
+ * top - the unit engine/autoFoundation.ts scans over for the auto-play-to-foundation feature.
149
+ * Lives here rather than in autoFoundation.ts itself so that file can import PileRef/GameController
150
+ * from this one without a cycle. */
151
+ interface AccessibleCard {
152
+ ref: PileRef;
153
+ card: Card;
154
+ }
155
+ interface GameController<TState> {
156
+ id: string;
157
+ title: string;
158
+ /** Deal a brand new game from a seed (same seed -> same deal, for testability / shareable game numbers). */
159
+ newGame(seed: number): TState;
160
+ /** All currently legal moves - used for hints and "no moves left" detection. */
161
+ legalMoves(state: TState): Move[];
162
+ /** Attempt a move. Returns a new state if legal, or null if illegal (state is never mutated in place). */
163
+ tryMove(state: TState, move: Move): TState | null;
164
+ /** Draw from stock / recycle waste, etc. Returns a new state, or null if not applicable right now. */
165
+ drawStock?(state: TState): TState | null;
166
+ isWon(state: TState): boolean;
167
+ /** True if no legal moves and no stock draw remain (used for "stuck" banners). */
168
+ isStuck?(state: TState): boolean;
169
+ /**
170
+ * Optional: given a single tapped card, find its best automatic destination - a foundation move
171
+ * if one exists, otherwise the best tableau destination (fewest buried cards, then largest pile,
172
+ * then leftmost, breaking ties in that order), or null if the card has nowhere legal to go.
173
+ * Powers tap-to-auto-move; calling it again with the card now sitting at that destination finds
174
+ * the next-best destination from there, since the one it just left is no longer a valid target.
175
+ */
176
+ autoMoveHint?(state: TState, from: PileRef, cardId: string): Move | null;
177
+ /**
178
+ * Optional: scores a legal move for Hint-ordering purposes - higher means more worth
179
+ * suggesting. A non-positive score on every legal move (see engine/hint.ts's findHint) means
180
+ * "nothing productive available," which prefers a stock-draw suggestion over the best of a bad
181
+ * lot, where one's legal. Games without this keep legalMoves()'s own raw order (foundation-bound
182
+ * moves first, otherwise whatever order legalMoves() returned them).
183
+ */
184
+ scoreHintMove?(state: TState, move: Move): number;
185
+ /**
186
+ * Optional: every card currently sitting at a legally-reachable position - tableau tops,
187
+ * freecell contents, a waste top - for the auto-play-to-foundation feature (see
188
+ * engine/autoFoundation.ts) to scan. Never includes stock or anything else that would need an
189
+ * extra action (like a draw) to become reachable.
190
+ */
191
+ accessibleCards?(state: TState): AccessibleCard[];
192
+ /**
193
+ * Optional: what counts as progress in this game (cards turned over, cards on the foundations, runs completed), for
194
+ * the look-ahead behind Hint and the dead-board check (see engine/progressSearch.ts). A game without one keeps the
195
+ * scored Hint and only its own isStuck.
196
+ */
197
+ progress?: ProgressSpec<TState>;
198
+ }
199
+
200
+ export { HINT_SEARCH_BUDGET as H, LOOKAHEAD_BUDGET as L, HINT_SEARCH_MAX_MS as d, LOOKAHEAD_MAX_MS as e, ProgressSearch as f, SUITS as g, allDestinations as j, cardColor as k, columnsKey as l, faceDownCount as m, foundationDownMoves as n, isConclusive as o, pileKey as p };
201
+ export type { AccessibleCard as A, Card as C, GameController as G, Move as M, PileRef as P, Rank as R, Suit as S, ProgressSpec as a, SearchOutcome as b, Color as c, SearchMode as h, SearchStep as i };
@@ -0,0 +1,17 @@
1
+ import { Card, GameController } from './index.mjs';
2
+
3
+ interface GolfState {
4
+ /** 7 tableau columns, 5 cards each at deal, all face up. */
5
+ tableau: Card[][];
6
+ /** The single build pile - top card is the current target rank. Starts with 1 card. */
7
+ waste: Card[];
8
+ /** Face-down draw pile, 16 cards at deal. No recycling once empty. */
9
+ stock: Card[];
10
+ }
11
+ /** Closes over `wrapAceKing` (settings.golfRankWrap) - the only rule this game's move logic varies
12
+ * by, so only the functions that actually consult isAdjacentRank move inside this factory;
13
+ * newGame/drawStock/isWon are wrap-independent and stay as plain module-level functions above. */
14
+ declare function createGolfController(wrapAceKing: boolean): GameController<GolfState>;
15
+
16
+ export { createGolfController };
17
+ export type { GolfState };
package/dist/golf.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ import { Card, GameController } from './index.js';
2
+
3
+ interface GolfState {
4
+ /** 7 tableau columns, 5 cards each at deal, all face up. */
5
+ tableau: Card[][];
6
+ /** The single build pile - top card is the current target rank. Starts with 1 card. */
7
+ waste: Card[];
8
+ /** Face-down draw pile, 16 cards at deal. No recycling once empty. */
9
+ stock: Card[];
10
+ }
11
+ /** Closes over `wrapAceKing` (settings.golfRankWrap) - the only rule this game's move logic varies
12
+ * by, so only the functions that actually consult isAdjacentRank move inside this factory;
13
+ * newGame/drawStock/isWon are wrap-independent and stay as plain module-level functions above. */
14
+ declare function createGolfController(wrapAceKing: boolean): GameController<GolfState>;
15
+
16
+ export { createGolfController };
17
+ export type { GolfState };
package/dist/golf.js ADDED
@@ -0,0 +1,7 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true});
2
+
3
+ var _chunk4WAWIFQFjs = require('./chunk-4WAWIFQF.js');
4
+ require('./chunk-W5CPH6TD.js');
5
+
6
+
7
+ exports.createGolfController = _chunk4WAWIFQFjs.createGolfController;