@pretty-chitty/core 1.2.18 → 2.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 (378) hide show
  1. package/README.md +8 -0
  2. package/dist/components/ActionLogDisplay.d.ts.map +1 -1
  3. package/dist/components/ActionLogDisplay.js +1 -1
  4. package/dist/components/ActionLogDisplay.js.map +1 -1
  5. package/dist/components/BottomBarButton.d.ts +3 -1
  6. package/dist/components/BottomBarButton.d.ts.map +1 -1
  7. package/dist/components/BottomBarButton.js +3 -2
  8. package/dist/components/BottomBarButton.js.map +1 -1
  9. package/dist/components/ClientTrustMatchViewer.d.ts +14 -1
  10. package/dist/components/ClientTrustMatchViewer.d.ts.map +1 -1
  11. package/dist/components/ClientTrustMatchViewer.js +25 -2
  12. package/dist/components/ClientTrustMatchViewer.js.map +1 -1
  13. package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
  14. package/dist/components/ContextGalleryDisplay.js +1 -1
  15. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  16. package/dist/components/DemoWrapper.d.ts +30 -2
  17. package/dist/components/DemoWrapper.d.ts.map +1 -1
  18. package/dist/components/DemoWrapper.js +79 -43
  19. package/dist/components/DemoWrapper.js.map +1 -1
  20. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  21. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  22. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  23. package/dist/components/Gallery/BuiltItem.d.ts +6 -2
  24. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  25. package/dist/components/Gallery/BuiltItem.js +31 -9
  26. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  27. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  28. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryController.js +70 -1
  30. package/dist/components/Gallery/GalleryController.js.map +1 -1
  31. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  32. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  33. package/dist/components/Gallery/GalleryViewer.js +48 -10
  34. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  35. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  36. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  37. package/dist/components/Gallery/LayoutManager.js +23 -3
  38. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  39. package/dist/components/Gallery/constants.d.ts +2 -0
  40. package/dist/components/Gallery/constants.d.ts.map +1 -1
  41. package/dist/components/Gallery/constants.js +2 -0
  42. package/dist/components/Gallery/constants.js.map +1 -1
  43. package/dist/components/Gallery/registry.d.ts +34 -0
  44. package/dist/components/Gallery/registry.d.ts.map +1 -0
  45. package/dist/components/Gallery/registry.js +17 -0
  46. package/dist/components/Gallery/registry.js.map +1 -0
  47. package/dist/components/GameDesigner.d.ts.map +1 -1
  48. package/dist/components/GameDesigner.js +42 -10
  49. package/dist/components/GameDesigner.js.map +1 -1
  50. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  51. package/dist/components/InlineGalleryDisplay.js +2 -2
  52. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  53. package/dist/components/LiveButton.d.ts.map +1 -1
  54. package/dist/components/LiveButton.js +5 -2
  55. package/dist/components/LiveButton.js.map +1 -1
  56. package/dist/components/MatchViewer.d.ts +6 -1
  57. package/dist/components/MatchViewer.d.ts.map +1 -1
  58. package/dist/components/MatchViewer.js +9 -3
  59. package/dist/components/MatchViewer.js.map +1 -1
  60. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  61. package/dist/components/Panel/MultiPanel.js +18 -0
  62. package/dist/components/Panel/MultiPanel.js.map +1 -1
  63. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  64. package/dist/components/Panel/PanelContents.js +92 -23
  65. package/dist/components/Panel/PanelContents.js.map +1 -1
  66. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  67. package/dist/components/Panel/PanelTabStack.js +1 -1
  68. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  69. package/dist/components/PanelSpark.d.ts.map +1 -1
  70. package/dist/components/PanelSpark.js +3 -2
  71. package/dist/components/PanelSpark.js.map +1 -1
  72. package/dist/components/Playground.d.ts.map +1 -1
  73. package/dist/components/Playground.js +46 -14
  74. package/dist/components/Playground.js.map +1 -1
  75. package/dist/components/PromptControls.d.ts.map +1 -1
  76. package/dist/components/PromptControls.js +4 -2
  77. package/dist/components/PromptControls.js.map +1 -1
  78. package/dist/components/SparkLineChart.d.ts.map +1 -1
  79. package/dist/components/SparkLineChart.js +22 -26
  80. package/dist/components/SparkLineChart.js.map +1 -1
  81. package/dist/components/TimeControlBar.d.ts.map +1 -1
  82. package/dist/components/TimeControlBar.js +5 -3
  83. package/dist/components/TimeControlBar.js.map +1 -1
  84. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  85. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  86. package/dist/components/TokenizedMarkdown.js +144 -0
  87. package/dist/components/TokenizedMarkdown.js.map +1 -0
  88. package/dist/components/TokenizedMessage.d.ts +8 -6
  89. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  90. package/dist/components/TokenizedMessage.js +21 -54
  91. package/dist/components/TokenizedMessage.js.map +1 -1
  92. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  93. package/dist/components/TopBarPlayers.js +2 -2
  94. package/dist/components/TopBarPlayers.js.map +1 -1
  95. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  96. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  97. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  98. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  100. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialBox.js +239 -0
  102. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  104. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  106. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  107. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  108. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  109. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  110. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  111. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  112. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  113. package/dist/components/Tutorial/targetRects.js +241 -0
  114. package/dist/components/Tutorial/targetRects.js.map +1 -0
  115. package/dist/game/Chit.d.ts +7 -0
  116. package/dist/game/Chit.d.ts.map +1 -1
  117. package/dist/game/Chit.js +22 -7
  118. package/dist/game/Chit.js.map +1 -1
  119. package/dist/game/ClientTimeState.d.ts +14 -0
  120. package/dist/game/ClientTimeState.d.ts.map +1 -1
  121. package/dist/game/ClientTimeState.js +17 -0
  122. package/dist/game/ClientTimeState.js.map +1 -1
  123. package/dist/game/ConnectionTransport.d.ts +3 -0
  124. package/dist/game/ConnectionTransport.d.ts.map +1 -1
  125. package/dist/game/ConnectionTransport.js +13 -4
  126. package/dist/game/ConnectionTransport.js.map +1 -1
  127. package/dist/game/Game.d.ts +14 -1
  128. package/dist/game/Game.d.ts.map +1 -1
  129. package/dist/game/GameTheme.d.ts +3 -0
  130. package/dist/game/GameTheme.d.ts.map +1 -1
  131. package/dist/game/GameTheme.js +2 -0
  132. package/dist/game/GameTheme.js.map +1 -1
  133. package/dist/game/Match.d.ts +74 -2
  134. package/dist/game/Match.d.ts.map +1 -1
  135. package/dist/game/Match.js +155 -4
  136. package/dist/game/Match.js.map +1 -1
  137. package/dist/game/MatchStorage.d.ts +8 -1
  138. package/dist/game/MatchStorage.d.ts.map +1 -1
  139. package/dist/game/MatchStorage.js +11 -3
  140. package/dist/game/MatchStorage.js.map +1 -1
  141. package/dist/game/Pick.d.ts +16 -0
  142. package/dist/game/Pick.d.ts.map +1 -1
  143. package/dist/game/Pick.js +32 -1
  144. package/dist/game/Pick.js.map +1 -1
  145. package/dist/game/PlayerChit.d.ts +3 -0
  146. package/dist/game/PlayerChit.d.ts.map +1 -1
  147. package/dist/game/PlayerChit.js +3 -0
  148. package/dist/game/PlayerChit.js.map +1 -1
  149. package/dist/game/PlayerInfo.d.ts +8 -0
  150. package/dist/game/PlayerInfo.d.ts.map +1 -1
  151. package/dist/game/PlayerInfo.js +6 -3
  152. package/dist/game/PlayerInfo.js.map +1 -1
  153. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  154. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  155. package/dist/game/PlayerPromptStatusChit.js +8 -2
  156. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  157. package/dist/game/Prompt.d.ts +15 -0
  158. package/dist/game/Prompt.d.ts.map +1 -1
  159. package/dist/game/Prompt.js +16 -0
  160. package/dist/game/Prompt.js.map +1 -1
  161. package/dist/game/Turn.d.ts +20 -4
  162. package/dist/game/Turn.d.ts.map +1 -1
  163. package/dist/game/Turn.js +191 -67
  164. package/dist/game/Turn.js.map +1 -1
  165. package/dist/game/TurnState.d.ts +20 -1
  166. package/dist/game/TurnState.d.ts.map +1 -1
  167. package/dist/game/TurnState.js +22 -3
  168. package/dist/game/TurnState.js.map +1 -1
  169. package/dist/game/ai/AiClientPrompts.d.ts +177 -0
  170. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -0
  171. package/dist/game/ai/AiClientPrompts.js +561 -0
  172. package/dist/game/ai/AiClientPrompts.js.map +1 -0
  173. package/dist/game/ai/AiLiveView.d.ts +2 -0
  174. package/dist/game/ai/AiLiveView.d.ts.map +1 -0
  175. package/dist/game/ai/AiLiveView.js +48 -0
  176. package/dist/game/ai/AiLiveView.js.map +1 -0
  177. package/dist/game/ai/AiPlayerView.d.ts +2 -0
  178. package/dist/game/ai/AiPlayerView.d.ts.map +1 -0
  179. package/dist/game/ai/AiPlayerView.js +91 -0
  180. package/dist/game/ai/AiPlayerView.js.map +1 -0
  181. package/dist/game/ai/connectAiPlayer.d.ts +43 -0
  182. package/dist/game/ai/connectAiPlayer.d.ts.map +1 -0
  183. package/dist/game/ai/connectAiPlayer.js +58 -0
  184. package/dist/game/ai/connectAiPlayer.js.map +1 -0
  185. package/dist/game/ai/defineAi.d.ts +119 -0
  186. package/dist/game/ai/defineAi.d.ts.map +1 -0
  187. package/dist/game/ai/defineAi.js +122 -0
  188. package/dist/game/ai/defineAi.js.map +1 -0
  189. package/dist/game/ai/simulateMatches.d.ts +62 -0
  190. package/dist/game/ai/simulateMatches.d.ts.map +1 -0
  191. package/dist/game/ai/simulateMatches.js +108 -0
  192. package/dist/game/ai/simulateMatches.js.map +1 -0
  193. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts +3 -0
  194. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts.map +1 -1
  195. package/dist/game/badAiTransport/BadAIClientPrompts.js +3 -0
  196. package/dist/game/badAiTransport/BadAIClientPrompts.js.map +1 -1
  197. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  198. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  199. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  200. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  201. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  202. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  203. package/dist/game/clientTransport/ClientTime.js +51 -11
  204. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  205. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  206. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  207. package/dist/game/tutorial/TutorialController.js +1182 -0
  208. package/dist/game/tutorial/TutorialController.js.map +1 -0
  209. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  210. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  211. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  212. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  213. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  214. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  215. package/dist/game/tutorial/TutorialTheme.js +39 -0
  216. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  217. package/dist/game/tutorial/allowed.d.ts +2 -0
  218. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  219. package/dist/game/tutorial/allowed.js +119 -0
  220. package/dist/game/tutorial/allowed.js.map +1 -0
  221. package/dist/game/tutorial/checks.d.ts +58 -0
  222. package/dist/game/tutorial/checks.d.ts.map +1 -0
  223. package/dist/game/tutorial/checks.js +144 -0
  224. package/dist/game/tutorial/checks.js.map +1 -0
  225. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  226. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  227. package/dist/game/tutorial/createDemoMatch.js +67 -0
  228. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  229. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  230. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  231. package/dist/game/tutorial/defineTutorial.js +86 -0
  232. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  233. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  234. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  235. package/dist/game/tutorial/runTutorial.js +273 -0
  236. package/dist/game/tutorial/runTutorial.js.map +1 -0
  237. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  238. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  239. package/dist/hooks/usePanelNavigation.js +36 -0
  240. package/dist/hooks/usePanelNavigation.js.map +1 -0
  241. package/dist/hooks/useTimeController.d.ts +2 -1
  242. package/dist/hooks/useTimeController.d.ts.map +1 -1
  243. package/dist/hooks/useTimeController.js +6 -2
  244. package/dist/hooks/useTimeController.js.map +1 -1
  245. package/dist/hooks/useTokenMap.d.ts +2 -4
  246. package/dist/hooks/useTokenMap.d.ts.map +1 -1
  247. package/dist/hooks/useTokenMap.js +2 -5
  248. package/dist/hooks/useTokenMap.js.map +1 -1
  249. package/dist/hooks/useTutorial.d.ts +48 -0
  250. package/dist/hooks/useTutorial.d.ts.map +1 -0
  251. package/dist/hooks/useTutorial.js +16 -0
  252. package/dist/hooks/useTutorial.js.map +1 -0
  253. package/dist/index.d.ts +57 -1
  254. package/dist/index.d.ts.map +1 -1
  255. package/dist/index.html +12 -0
  256. package/dist/index.js +27 -3
  257. package/dist/index.js.map +1 -1
  258. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  259. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  260. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  261. package/dist/pretty-chitty.js +204513 -0
  262. package/dist/pretty-chitty.js.map +1 -0
  263. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  264. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  265. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  266. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  267. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  268. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  269. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  270. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  271. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  272. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  273. package/dist/rendering/ChitRenderInstance.js +28 -0
  274. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  275. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  276. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  277. package/dist/rendering/RootChitRenderInstance.js +29 -0
  278. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  279. package/dist/utilities/Annotations.d.ts +15 -0
  280. package/dist/utilities/Annotations.d.ts.map +1 -1
  281. package/dist/utilities/Annotations.js +31 -7
  282. package/dist/utilities/Annotations.js.map +1 -1
  283. package/dist/utilities/CanvasStack/CanvasStack.d.ts +13 -0
  284. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  285. package/dist/utilities/CanvasStack/CanvasStack.js +66 -15
  286. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  287. package/dist/utilities/TokenizedText.d.ts +55 -0
  288. package/dist/utilities/TokenizedText.d.ts.map +1 -0
  289. package/dist/utilities/TokenizedText.js +47 -0
  290. package/dist/utilities/TokenizedText.js.map +1 -0
  291. package/dist/utilities/zIndex.d.ts +1 -0
  292. package/dist/utilities/zIndex.d.ts.map +1 -1
  293. package/dist/utilities/zIndex.js +1 -0
  294. package/dist/utilities/zIndex.js.map +1 -1
  295. package/package.json +3 -2
  296. package/src/library/components/ActionLogDisplay.tsx +1 -0
  297. package/src/library/components/BottomBarButton.tsx +5 -0
  298. package/src/library/components/ClientTrustMatchViewer.tsx +32 -2
  299. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  300. package/src/library/components/DemoWrapper.tsx +147 -52
  301. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  302. package/src/library/components/Gallery/BuiltItem.ts +34 -9
  303. package/src/library/components/Gallery/GalleryController.ts +75 -2
  304. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  305. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  306. package/src/library/components/Gallery/constants.ts +2 -0
  307. package/src/library/components/Gallery/registry.ts +44 -0
  308. package/src/library/components/GameDesigner.tsx +121 -12
  309. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  310. package/src/library/components/LiveButton.tsx +8 -5
  311. package/src/library/components/MatchViewer.tsx +14 -3
  312. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  313. package/src/library/components/Panel/PanelContents.tsx +70 -1
  314. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  315. package/src/library/components/PanelSpark.tsx +9 -4
  316. package/src/library/components/Playground.tsx +125 -33
  317. package/src/library/components/PromptControls.tsx +7 -3
  318. package/src/library/components/SparkLineChart.tsx +23 -27
  319. package/src/library/components/TimeControlBar.tsx +5 -3
  320. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  321. package/src/library/components/TokenizedMessage.tsx +30 -95
  322. package/src/library/components/TopBarPlayers.tsx +18 -10
  323. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  324. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  325. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  326. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  327. package/src/library/components/Tutorial/targetRects.ts +273 -0
  328. package/src/library/game/Chit.ts +23 -7
  329. package/src/library/game/ClientTimeState.ts +18 -0
  330. package/src/library/game/ConnectionTransport.ts +12 -3
  331. package/src/library/game/Game.ts +16 -1
  332. package/src/library/game/GameTheme.ts +4 -0
  333. package/src/library/game/Match.ts +174 -5
  334. package/src/library/game/MatchStorage.ts +14 -4
  335. package/src/library/game/Pick.ts +36 -1
  336. package/src/library/game/PlayerChit.ts +4 -1
  337. package/src/library/game/PlayerInfo.ts +13 -3
  338. package/src/library/game/PlayerPromptStatusChit.ts +8 -2
  339. package/src/library/game/Prompt.ts +20 -0
  340. package/src/library/game/Turn.ts +198 -68
  341. package/src/library/game/TurnState.ts +34 -3
  342. package/src/library/game/ai/AI_GUIDE.md +444 -0
  343. package/src/library/game/ai/AiClientPrompts.ts +730 -0
  344. package/src/library/game/ai/AiLiveView.ts +63 -0
  345. package/src/library/game/ai/AiPlayerView.ts +114 -0
  346. package/src/library/game/ai/ai.test.ts +475 -0
  347. package/src/library/game/ai/connectAiPlayer.ts +88 -0
  348. package/src/library/game/ai/defineAi.ts +230 -0
  349. package/src/library/game/ai/simulateMatches.ts +172 -0
  350. package/src/library/game/badAiTransport/BadAIClientPrompts.ts +3 -0
  351. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  352. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  353. package/src/library/game/serialize.test.ts +275 -0
  354. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  355. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  356. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  357. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  358. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  359. package/src/library/game/tutorial/allowed.ts +145 -0
  360. package/src/library/game/tutorial/checks.ts +186 -0
  361. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  362. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  363. package/src/library/game/tutorial/runTutorial.ts +331 -0
  364. package/src/library/game/undo.test.ts +282 -0
  365. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  366. package/src/library/hooks/useTimeController.tsx +6 -2
  367. package/src/library/hooks/useTokenMap.ts +2 -6
  368. package/src/library/hooks/useTutorial.tsx +76 -0
  369. package/src/library/index.ts +91 -4
  370. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  371. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  372. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  373. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  374. package/src/library/utilities/Annotations.ts +35 -7
  375. package/src/library/utilities/CanvasStack/CanvasStack.ts +74 -29
  376. package/src/library/utilities/TokenizedText.test.ts +32 -0
  377. package/src/library/utilities/TokenizedText.ts +103 -0
  378. package/src/library/utilities/zIndex.ts +1 -0
@@ -0,0 +1,444 @@
1
+ # Writing AI players for a Pretty Chitty game
2
+
3
+ This guide is for whoever is adding computer opponents to a Pretty Chitty game, whether a
4
+ person or a coding agent. Follow it from top to bottom. When you're done:
5
+
6
+ - every pick in the game is tagged with `.ai("key")`,
7
+ - `src/ai.ts` has a scoring rule for every key,
8
+ - a `simulateMatches` test shows that bots finish games without getting stuck.
9
+
10
+ **The goal is bots that never look broken, not bots that win.** A bot that makes reasonable,
11
+ legal, purposeful moves is a success. Don't build search trees, simulations or "perfect play".
12
+
13
+ ---
14
+
15
+ ## How it works (read this first)
16
+
17
+ - A game prompts a player with `turn.pick([...picks])`. Each pick offers options: chits to
18
+ click (`Chit.pick`), chits to drag onto targets (`Chit.dragPick`), or buttons.
19
+ - You tag each pick with a key: `.ai("market.buy")`.
20
+ - In `src/ai.ts` you write one **rule** per key. A rule receives **one option** and returns a
21
+ **score**. The bot scores every option in the prompt, across all of its picks, and plays the
22
+ highest one.
23
+ - By default the bot reads the match's **live game objects** in place, so rules see everything,
24
+ hidden information included. That is fast. If your rules would use information the seat should
25
+ not have, set `serializedView: true` (see Step 4) and the bot sees only what a human in that seat
26
+ would.
27
+ - A rule may also return a **plan**, which is saved to the bot's memory if that option wins.
28
+ Later rules can read it, which lets a bot carry intentions across prompts.
29
+
30
+ The engine already handles these. **Do not reimplement them:**
31
+
32
+ | Situation | What the engine does |
33
+ |---|---|
34
+ | Engine-inserted Confirm prompts | Pressed automatically |
35
+ | "No valid moves" dead end | Undoes the last answer, marks it dead for that exact situation, tries the next best; backs up further if every option is dead |
36
+ | Server rejects an answer | Tries the next best option |
37
+ | Untagged pick | Scores 0 (or uses `default`), logs `[AI p1] no rule for "..."` once |
38
+ | Game has no `ai` at all | Falls back to random play weighted by `Game.demoPickWeight` |
39
+ | Pacing in demo mode and Playground | Pauses 400–900 ms before each answer |
40
+
41
+ ---
42
+
43
+ ## Step 1 — Inventory every pick
44
+
45
+ Find every prompt in the game:
46
+
47
+ ```sh
48
+ grep -rn "turn.pick\|\.pick(\|Chit.pick\|Chit.dragPick\|noValidMoves" src/
49
+ ```
50
+
51
+ Make a table before writing any code. Write it in your notes, not in the repo:
52
+
53
+ | File:line | What the player is deciding | Pick type | Proposed key |
54
+ |---|---|---|---|
55
+ | phases/build.ts:88 | which factory to place, and where | DragPick | `build.place` |
56
+ | phases/build.ts:95 | stop building | ButtonPick (Done) | `build.done` |
57
+ | phases/market.ts:40 | which car to buy | ChitPick | `market.buy` |
58
+ | phases/market.ts:46 | skip buying | ButtonPick (Pass) | `market.pass` |
59
+
60
+ **Key naming:** `phase.action`, lowercase, stable, describing the *decision* rather than the
61
+ UI. Give each kind of action its own key. Two picks in different places that mean the same
62
+ decision may share a key.
63
+
64
+ ## Step 2 — Tag the picks
65
+
66
+ Add `.ai(key)` to each pick, next to `.message()`:
67
+
68
+ ```ts
69
+ await turn.pick([
70
+ Chit.pick(cars, (c) => buy(c)).message("buy a car").ai("market.buy"),
71
+ new PassButton(() => (passed = true)).pick().message("pass").ai("market.pass"),
72
+ Chit.dragPick(factories, DragTarget.from(hexes, place)).message("build").ai("build.place"),
73
+ ]);
74
+ ```
75
+
76
+ Rules for tagging:
77
+
78
+ - **Tag picks, not prompts.** Each pick in the array gets its own `.ai()`.
79
+ - **Don't change game behaviour.** Only add `.ai(...)`. Don't add, remove or reorder picks,
80
+ change callbacks, or add buttons to make the bot's life easier. If the bot can't cope with the
81
+ game as written, fix the rules in `ai.ts`.
82
+ - **Bare buttons:** if the code passes `new PassButton(...)` directly into the array, change
83
+ it to `new PassButton(...).pick().ai("x.pass")`. That's the same pick with a tag.
84
+ - **Optional data:** `.ai("market.buy", { cost })` passes a JSON hint to the rule. **Every
85
+ client receives it**, so never put hidden information in it. Prefer reading values from the
86
+ option's chit instead.
87
+ - Don't tag Confirm prompts the engine inserts automatically, or `turn.noValidMoves()`.
88
+
89
+ ## Step 3 — Write `src/ai.ts`
90
+
91
+ ```ts
92
+ import { defineAi } from "@pretty-chitty/core";
93
+ import { Player, Root, Car, Factory, Hex } from "./chits";
94
+
95
+ type Memory = {
96
+ /** id of the car we intend to buy, then build a factory for */
97
+ targetCar?: string;
98
+ };
99
+
100
+ export const ai = defineAi<Player, Root, Memory>({
101
+ initialMemory: () => ({}),
102
+
103
+ rules: {
104
+ "market.buy": (opt, { me }) => {
105
+ if (opt.kind !== "chit") return 0;
106
+ const car = opt.chit as Car;
107
+ if (car.cost > me.money) return -Infinity;
108
+ return {
109
+ score: car.value - car.cost * 0.5,
110
+ plan: (prev) => ({ ...prev, targetCar: car.id }),
111
+ };
112
+ },
113
+
114
+ "market.pass": (_opt, { options }) => {
115
+ // pass only when nothing else is worth doing
116
+ return options.some((o) => o.key === "market.buy") ? -1 : 0;
117
+ },
118
+
119
+ "build.place": (opt, { memory, find, view }) => {
120
+ if (opt.kind !== "drag") return 0;
121
+ const hex = opt.target as Hex;
122
+ if (hex.occupied) return -Infinity;
123
+ let score = adjacencyBonus(hex, view);
124
+ if (memory.targetCar && find(memory.targetCar) && hex.region === (find(memory.targetCar) as Car).region) {
125
+ score += 10;
126
+ }
127
+ return score;
128
+ },
129
+
130
+ "build.done": (_opt, { options }) => (options.some((o) => o.key === "build.place") ? -2 : 1),
131
+ },
132
+ });
133
+ ```
134
+
135
+ Then wire it into the Game class:
136
+
137
+ ```ts
138
+ import { ai } from "./ai";
139
+
140
+ export class MyGame implements Game<Player, Root> {
141
+ // ...
142
+ ai = ai;
143
+ }
144
+ ```
145
+
146
+ ### The rule signature
147
+
148
+ ```ts
149
+ (option: AiOption, ctx: AiContext) => number | { score: number; plan?: Memory | ((prev: Memory) => Memory) }
150
+ ```
151
+
152
+ **`option`**
153
+
154
+ | Field | Meaning |
155
+ |---|---|
156
+ | `kind` | `"chit"` (click a chit), `"drag"` (drag `chit` onto `target`), or `"button"` |
157
+ | `chit` | The chit clicked or dragged. Present for `"chit"` and `"drag"` |
158
+ | `target` | The drop target. Present for `"drag"` |
159
+ | `button` | The button instance. Present for `"button"` |
160
+ | `key`, `data` | From `.ai(key, data)` |
161
+ | `pick.message`, `pick.help`, `pick.context`, `pick.buttonType` | Where the option came from |
162
+
163
+ Narrow on `opt.kind` before using `chit`, `target` or `button`, then cast to your chit class:
164
+ `opt.chit as Car`.
165
+
166
+ **`ctx`**
167
+
168
+ | Field | Meaning |
169
+ |---|---|
170
+ | `view` | Root chit as this seat sees it. Query it like game code |
171
+ | `me` | This bot's PlayerChit inside `view` |
172
+ | `options` | Every legal option in this prompt. Use it to compare ("is there anything better?") |
173
+ | `memory` | The current plan. Frozen, so don't mutate it |
174
+ | `find(id)` | Look up a chit in `view` by id. `undefined` if it's gone |
175
+ | `random()` | Per-bot rng in [0, 1). Use it for variety, never `Math.random` |
176
+ | `params` | Whatever the host passed as `connectAiPlayer(…, { params })` for this seat (per-seat weights, a version, a personality); `undefined` if none |
177
+ | `prompt.message` | The prompt's text |
178
+
179
+ ### Scores
180
+
181
+ - **Higher is better.** Only the relative order within one prompt matters.
182
+ - **All keys in one prompt share a scale.** A prompt offering `market.buy` and `market.pass`
183
+ compares their numbers directly, so pick units for the game (points or money are good) and
184
+ use them everywhere.
185
+ - **`-Infinity`** means "never, unless nothing else is legal". Use it for illegal-in-spirit or
186
+ self-destructive moves.
187
+ - **Ties are broken at random**, and a small amount of noise is added, so bots aren't robotic.
188
+ By default the noise is `(max − min) × (1 − difficulty)` of the prompt's scores, so one outlier
189
+ (a −50 "never") makes the bot nearly random among the rest, and close scores make it fully
190
+ predictable. Use `-Infinity` for "never" (it is left out of the spread). For noise in your own
191
+ units, set a **temperature**: `defineAi({ temperature: 1, … })` for every bot of the game, or
192
+ `connectAiPlayer(…, { temperature })` per seat. The bot then picks by softmax: an option one
193
+ score unit worse is chosen e≈2.7× less often at temperature 1, and temperature 0 always plays
194
+ the best.
195
+ - **Untagged options in the same prompt score 0.** Keep that in mind when choosing your scale.
196
+
197
+ ### Harness hooks
198
+
199
+ Harnesses (playouts, tutorials) can steer a bot without touching the game's rules:
200
+ `connectAiPlayer(match, id, { choose, hold })`. `choose(scored, ctx)` is consulted for every prompt,
201
+ the engine's Confirm included: return an index to force that option, `undefined` for the normal
202
+ choice, or `null` to leave the prompt unanswered for now. `hold(prompt)` keeps the bot from
203
+ answering while it returns true for the current prompt (look at the prompt to let some through, such
204
+ as the engine's Confirm). After either, call `handle.prompts.recheck()` when whatever held
205
+ the bot may have changed.
206
+
207
+ ## Step 4 — Hidden information
208
+
209
+ The default view is the live board: the bot *could* read other hands, deck order, and other
210
+ players' unfinished simultaneous moves. That is your call as the developer: if your rules only
211
+ read the bot's own pieces and public information, leave it — it is many times faster (a 3-player
212
+ Excursions game spent ~60% of its time rebuilding serialized views). If fairness depends on it,
213
+ opt in:
214
+
215
+ ```ts
216
+ export const ai = defineAi<Player, Root, Memory>({ serializedView: true, rules: { … } });
217
+ // or per seat: connectAiPlayer(match, playerId, { view: "serialized" })
218
+ ```
219
+
220
+ With `serializedView`, the bot's view is redacted exactly like a human's:
221
+
222
+ - **Every field another player might hide can be `undefined`.** Always default it:
223
+ `const v = card.value ?? AVERAGE_CARD_VALUE;`
224
+ - **A face-down deck still has its chits**, with their contents stripped. Count them, but
225
+ don't read them.
226
+ - **Never mutate what you read.** With the live view, `view` *is* the game; a rule that sets a field
227
+ changes the real match.
228
+ - **Never** read state from anywhere except `ctx` and the option: no module-level game
229
+ singletons, no root captured from `run()`, no imports of live state. Helper functions and
230
+ constant tables (card data, scoring tables) are fine to import.
231
+ - A rule that throws scores 0 and is counted in `ruleErrors`. A missing `?? default` is the
232
+ usual cause.
233
+
234
+ ## Step 5 — Plans (memory across prompts)
235
+
236
+ Use plans when one intention spans several prompts. For example: "buy car X, then build in
237
+ X's region", "save money for the 7-cost upgrade", "go for the blue majority".
238
+
239
+ - Return `{ score, plan }`. The plan is saved **only if this option wins**, so rules can
240
+ propose plans freely while scoring.
241
+ - A plain object **replaces** memory. Use the function form to keep other fields:
242
+ `plan: (prev) => ({ ...prev, targetCar: car.id })`.
243
+ - Memory must be JSON. Store **chit ids**, not chits, and resolve them with `find(id)`.
244
+ - **Plans are hints, not commitments.** Other players can make them stale. Always guard:
245
+
246
+ ```ts
247
+ const target = memory.targetCar ? find(memory.targetCar) : undefined;
248
+ if (target && target.parent === view.market) { /* still buyable */ }
249
+ ```
250
+
251
+ - When the bot backs out of a dead end, memory rolls back automatically.
252
+ - Clear a plan once it's done: `plan: (prev) => ({ ...prev, targetCar: undefined })`.
253
+ - Memory is saved inside the match state (`state.ai[playerId]`), so it survives a reload or a bot
254
+ re-seated in another process. That is also why it must be JSON.
255
+
256
+ Keep plans small. Most games need one or two fields, or none.
257
+
258
+ ## Step 6 — Prove it with a soak test
259
+
260
+ Create `src/ai.test.ts`:
261
+
262
+ ```ts
263
+ import { expect, test } from "vitest";
264
+ import { simulateMatches } from "@pretty-chitty/core";
265
+ import { MyGame } from "./MyGame";
266
+
267
+ test("AI players finish games without getting stuck", async () => {
268
+ const report = await simulateMatches(new MyGame(), { players: 3, games: 5 });
269
+ expect(report.finished).toBe(5);
270
+ expect(report.stuck).toBe(0);
271
+ expect(report.stalls).toBe(0);
272
+ expect(report.ruleErrors).toBe(0);
273
+ expect(report.untagged).toEqual({});
274
+ }, 120_000);
275
+ ```
276
+
277
+ Run it at each player count the game supports. How to read a failed report:
278
+
279
+ | Symptom | Likely cause |
280
+ |---|---|
281
+ | `untagged` not empty | A pick has no `.ai()` tag, or its key has no rule. The keys of `untagged` are the pick messages |
282
+ | `ruleErrors > 0` | A rule threw. Usually it read a hidden field without `?? default` |
283
+ | `outcome: "maxPrompts"` | The bot loops: a free-arrange or "keep going" pick always outscores Done/Pass. Make the stop option win once progress is made (see the cookbook) |
284
+ | `stepBacks` very high | Rules keep choosing moves that lead to "no valid moves". Score those moves `-Infinity` up front |
285
+ | `stalls > 0` | A pick callback can leave state unchanged, so the server never responds. That's a game bug; report it rather than working around it |
286
+ | `stuck > 0` | Every option leads to a dead end and the bot can't undo further. Usually a game bug |
287
+
288
+ To print details, use `const report = await simulateMatches(game, { log: true });` and
289
+ `console.log(report.matches)`.
290
+
291
+ Then watch one game in the browser: open the game's demo page (`/demo`), or use Playground
292
+ with AI players checked. Moves should look purposeful.
293
+
294
+ ---
295
+
296
+ ## Step 7 — Measure and tune (optional)
297
+
298
+ Hand-written rules encode assumptions, and some will be wrong. Three hooks let a harness test them
299
+ by playing:
300
+
301
+ - **`params`**: give each seat its own weights (`connectAiPlayer(…, { params: { weights } })`,
302
+ read as `ctx.params` in rules). Put every constant your rules use in one weights object, and a
303
+ tournament can play variants against each other: seat them at random, rank by the share of
304
+ opponents each finished ahead of, keep the best, mutate, repeat. Rotate seats every game —
305
+ turn order alone can be worth ±20 points of win rate.
306
+ - **`onDecision(d)`**: called after every choice with each option's score, the chosen index and
307
+ the `ctx`. Log it to compare what the bot expected with what happened.
308
+ - **`choose(scored, ctx)`**: return an index to force the answer. With it a harness can fork a
309
+ match at a decision — copy `match.state` (the decision history), load it into a new `Match`,
310
+ and the engine replays it to the pending prompt — then force each option in turn and play the
311
+ game out. Comparing options by playout finds wrong assumptions that no weight change can fix:
312
+ a value that should depend on the board, two things that only pay together, a goal no rule
313
+ pursues.
314
+
315
+ Headless runs: set `match.immediateNotify = true` and use `new EphemeralMatchStorage(id, true)`
316
+ (lazy saves). Both are off by default because they change behaviour a server relies on; see
317
+ their doc comments.
318
+
319
+ ## Seating bots in a host
320
+
321
+ A seat is an AI seat when its `IPlayerInfo.ai` is set (`{}` or `{ difficulty }`). The flag on its own
322
+ does nothing; a host opts in by calling `match.seatAiPlayers()` once, after `load()`:
323
+
324
+ ```ts
325
+ const match = new Match(game, players, storage, options);
326
+ await match.load();
327
+ match.seatAiPlayers({ thinkMs: [400, 900] }); // one bot per flagged seat, skipping seats a connectAiPlayer bot already holds
328
+ match.start();
329
+ ```
330
+
331
+ `ClientTrustMatchViewer` does this for you when given `seatAi` (`true` or the options object).
332
+ Harnesses keep calling `connectAiPlayer` directly for the seat under test and can still call
333
+ `seatAiPlayers` to fill the rest.
334
+
335
+ Then three things the host owns:
336
+
337
+ - **One driver per match.** Several copies of one match can run at once: every browser tab in
338
+ client-trust mode, or two bundle versions of a match on a server. Each copy would answer the
339
+ same prompt, so set `match.ai.enabled = false` on all but one (`aiEnabled` on
340
+ `ClientTrustMatchViewer`). Paused bots keep their memory and answer the pending prompt when
341
+ re-enabled, re-reading memory from the state first in case the previous driver moved it on.
342
+ - **Wait for `match.ai.idle`** before tearing a match down, so an answer in flight is not lost.
343
+ - **`match.dispose()`** disposes the bots and every connection with the match.
344
+
345
+ The flag is copied onto the `PlayerChit` as `player.ai` and serialized publicly, so a UI can mark
346
+ the seat.
347
+
348
+ ## Heuristic cookbook
349
+
350
+ Start every key with **1**, **2** and **6**. That alone usually stops a bot looking broken.
351
+
352
+ 1. **Take immediate value.** Score = what the action is worth right now, in the game's units.
353
+ 2. **Prefer progress to passing.** Pass/Done should lose while useful options exist:
354
+
355
+ ```ts
356
+ "x.pass": (_o, { options }) => (options.some((o) => o.key !== "x.pass") ? -1 : 0),
357
+ ```
358
+
359
+ 3. **Pay attention to cost.** Score = gain − cost, in the same units.
360
+ 4. **Finish what you start.** Commit a plan on step one and add a bonus on the next step for
361
+ options that fulfil it.
362
+ 5. **Deny the leader cheaply.** Add a small bonus for taking something the leading opponent
363
+ clearly needs, using only public information.
364
+ 6. **Never do the obviously broken thing:** dropping a piece onto itself or into its own
365
+ stack, moving something back where it came from, discarding instead of building, buying
366
+ what you can't use. Return `-Infinity` or a large negative.
367
+ 7. **Converge in loops.** For "keep acting until Done" picks, track progress in memory and
368
+ make Done win after enough actions, or when nothing scores above 0:
369
+
370
+ ```ts
371
+ "arrange.move": (o) => ({ score: moveValue(o), plan: (m) => ({ ...m, moves: m.moves + 1 }) }),
372
+ "arrange.done": (_o, { memory }) => (memory.moves >= 3 ? 10 : -10),
373
+ ```
374
+
375
+ Reset the counter when the loop starts again (for example, when the round number in
376
+ `view` changes).
377
+
378
+ 8. **Add a little personality.** `ctx.random() * 0.5` on near-equal choices makes bots feel
379
+ less mechanical. The engine already adds some noise (or set a `temperature`). For bots that
380
+ differ from each other, give each seat its own weights through `params`.
381
+
382
+ ## Anti-patterns
383
+
384
+ - ❌ Changing game code, picks or callbacks to make the AI easier.
385
+ - ❌ Reading hidden state from anywhere other than `ctx`.
386
+ - ❌ Calling `Math.random()` or `Date.now()` in rules. Use `ctx.random()`.
387
+ - ❌ Mutating `memory` or any chit in `view`. Rules must be side-effect free.
388
+ - ❌ Expensive work in rules, such as cloning the board or simulating turns. Rules run once per
389
+ option, and drags can have hundreds of options. Keep each rule cheap, and precompute shared
390
+ values outside the per-option logic where possible.
391
+ - ❌ Scoring everything the same. That gives a random bot with extra steps.
392
+ - ❌ Leaving `untagged` non-empty "for later".
393
+
394
+ ## Reference
395
+
396
+ ```ts
397
+ // Tag a pick
398
+ pick.ai(key: string, data?: unknown): this
399
+
400
+ // Define the AI (set as `ai` on your Game)
401
+ defineAi<P, R, M>({
402
+ serializedView?: boolean, // rules see only what the seat is sent (slower)
403
+ temperature?: number, // default softmax temperature for every bot of the game
404
+ initialMemory?: () => M,
405
+ rules?: { [key: string]: (option, ctx) => number | { score, plan? } },
406
+ default?: (option, ctx) => number | { score, plan? }, // for untagged picks
407
+ })
408
+
409
+ // Seat every flagged seat (hosts; demo mode, Playground and ClientTrustMatchViewer do this)
410
+ match.seatAiPlayers({ thinkMs?, temperature?, seed?, log?, view?, onDecision? }): AiPlayerHandle[]
411
+ match.ai.enabled // pause/resume every bot of this match (one driver per match!)
412
+ match.ai.idle // true when no bot is mid-answer
413
+ match.ai.handles // every bot attached, however it was seated
414
+
415
+ // Seat one bot with exactly these options (harnesses)
416
+ connectAiPlayer(match, playerId, {
417
+ difficulty?: 0..1, temperature?: number, thinkMs?: number | [min, max], seed?, log?,
418
+ view?: "live" | "serialized", params?: unknown,
419
+ choose?: (scored, ctx) => number | undefined, // harnesses: force an answer
420
+ onDecision?: (decision) => void, // harnesses: every choice, with all scores
421
+ memoryStore?: AiMemoryStore | false, // default: the match state; false: in-process only
422
+ disabled?: boolean, // start paused
423
+ })
424
+
425
+ // Headless soak test
426
+ simulateMatches(game, { players?, games?, maxPrompts?, stallMs?, timeoutMs?, matchOptions?, difficulty?, log? })
427
+ ```
428
+
429
+ - **Worked example:** `src/demo/ai.ts` with the tags in `src/demo/DemoGame.ts`, in the
430
+ pretty-chitty repo. It includes drag rules that avoid self-drops and cycles, a stop-after-a-
431
+ few-moves loop, and a plan read back by a later prompt.
432
+ - **Engine source:** `src/library/game/ai/` (`defineAi.ts` has the types,
433
+ `AiClientPrompts.ts` the bot).
434
+
435
+ ## Done checklist
436
+
437
+ - [ ] Every `turn.pick` option in the game has an `.ai(key)` tag, and no game behaviour changed
438
+ - [ ] `src/ai.ts` has a rule for every key, and `ai` is set on the Game class
439
+ - [ ] Every read of a field that could be hidden has a `?? default`
440
+ - [ ] Pass/Done/Stop options lose while useful work remains, and win once it doesn't
441
+ - [ ] Obviously broken moves score `-Infinity`
442
+ - [ ] `simulateMatches` test: all matches finish; `stuck`, `stalls` and `ruleErrors` are 0;
443
+ `untagged` is empty, at every supported player count
444
+ - [ ] Watched one game in demo mode or Playground and the moves look purposeful