@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
@@ -1,4 +1,5 @@
1
1
  import { Chit } from "./Chit";
2
+ import { buildTokenMap, tokenizedMessageToText } from "../utilities/TokenizedText";
2
3
  import { Match } from "./Match";
3
4
  import { NoValidMovesPrompt, PickPrompt, Prompt } from "./Prompt";
4
5
  import { PromptResponse, RngResponse, TurnState } from "./TurnState";
@@ -92,17 +93,50 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
92
93
  private lockedChitStates: ChitStateLookup = {};
93
94
  private lastChitStates: ChitStateLookup = {};
94
95
  private dirtyChitIds = new Set<string>();
96
+ // Locked roots of absorbed sub-turns. A sub-turn never deletes its own locked roots, so the next
97
+ // flush here checks whether any of them lost their parent.
98
+ private absorbedRootIds = new Set<string>();
95
99
  private pendingNewChits = new Set<Chit>();
96
100
  private _statePool?: Map<string, string>;
97
- private _serializeCache?: SerializeCache;
101
+
102
+ // serialize() replays this turn's diffs from its locked snapshot. Checkpoints are that replay
103
+ // captured part-way, so a request walks only the steps after the nearest one. They cover only
104
+ // steps that can no longer change (flushes, and sub-turn steps every turn of which the parent
105
+ // has absorbed) and merge sub-turns in absorption order, so they hold the same chit states for
106
+ // every player and are shared by every connection to the match.
107
+ private _checkpoints: SerializeCheckpoint[] = [];
108
+ // Set once the parent has absorbed this turn. From then on we are only walked by the parent, which
109
+ // holds the chit map we started from, so we keep neither our locked snapshot nor checkpoints.
110
+ private absorbed = false;
111
+ /** Tests only: false keeps every finished turn's snapshot and checkpoints. @internal */
112
+ static releaseAbsorbedTurns = true;
113
+ /** Steps between checkpoints: the most a request walks before it reaches the live step. @internal */
114
+ static serializeCheckpointInterval = 32;
115
+ /** Tests only: false makes every serialize() replay from the locked snapshot. @internal */
116
+ static serializeCheckpoints = true;
117
+
118
+ /** Drop every checkpoint that includes the step at `index`, which is about to change. */
119
+ private dropCheckpointsFrom(index: number) {
120
+ if (this._checkpoints.length && this._checkpoints[this._checkpoints.length - 1].nextIndex > index) {
121
+ this._checkpoints = this._checkpoints.filter((c) => c.nextIndex <= index);
122
+ }
123
+ }
98
124
 
99
125
  /**
100
- * Drop any cached serialize() reconstruction on this turn and every ancestor,
101
- * since their snapshots include our contribution.
126
+ * Checkpoints stay at least `serializeCheckpointInterval` steps apart, except the last one,
127
+ * which marks wherever the latest walk ended and is replaced as walks reach further.
102
128
  */
103
- private invalidateSerializeCache() {
104
- this._serializeCache = undefined;
105
- this.parent?.invalidateSerializeCache();
129
+ private addCheckpoint(checkpoint: SerializeCheckpoint) {
130
+ const checkpoints = this._checkpoints;
131
+ const last = checkpoints[checkpoints.length - 1];
132
+ if (last && last.nextIndex >= checkpoint.nextIndex) {
133
+ return;
134
+ }
135
+ const previous = checkpoints.length >= 2 ? checkpoints[checkpoints.length - 2].nextIndex : 0;
136
+ if (last && last.nextIndex - previous < Turn.serializeCheckpointInterval) {
137
+ checkpoints.pop();
138
+ }
139
+ checkpoints.push(checkpoint);
106
140
  }
107
141
 
108
142
  private get statePool(): Map<string, string> {
@@ -199,12 +233,18 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
199
233
  return p.id;
200
234
  });
201
235
 
202
- // now serialize all chits in their "locked" state
236
+ // now serialize all chits in their "locked" state. createTurn flushes the parent right before
237
+ // building us, so a clean chit's state there is already current and interned.
238
+ const parentStates = this.parent?.lastChitStates;
203
239
  Object.values(this.chitLookup).forEach((c) => {
204
240
  if (!c.id) {
205
241
  throw new Error("Cannot serialize a chit without an id");
206
242
  }
207
- this.lastChitStates[c.id] = this.lockedChitStates[c.id] = this.internState(c.serialize(this._playerIds));
243
+ const parentState = parentStates?.[c.id];
244
+ this.lastChitStates[c.id] = this.lockedChitStates[c.id] =
245
+ parentState !== undefined && parentState !== Chit.deletedIfSerialized() && !c._dirty
246
+ ? parentState
247
+ : this.internState(c.serialize(this._playerIds));
208
248
  });
209
249
  }
210
250
 
@@ -243,6 +283,20 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
243
283
  };
244
284
  }
245
285
 
286
+ /**
287
+ * Records what a player is being asked for: the tokenized message for the in-game UI, and a plain-text version
288
+ * (player tokens become names, etc.) for anything that can only show text.
289
+ */
290
+ private setPromptMessage(player: P, message: string | undefined) {
291
+ player.promptStatus.latestPromptMessage = message;
292
+ if (message === undefined) {
293
+ player.promptStatus.latestPromptMessageText = undefined;
294
+ return;
295
+ }
296
+ const tokenMap = buildTokenMap(this.match.game.tokenMap, this.rootChit.players.map((p) => p));
297
+ player.promptStatus.latestPromptMessageText = tokenizedMessageToText(message, tokenMap);
298
+ }
299
+
246
300
  /**
247
301
  * Add a game log message to the last flush step
248
302
  * @param message
@@ -261,6 +315,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
261
315
 
262
316
  const flushStep = step as FlushClockStep;
263
317
  flushStep.log = message;
318
+ this.dropCheckpointsFrom(this.clockSteps.length - 1);
264
319
  }
265
320
 
266
321
  /**
@@ -287,6 +342,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
287
342
  message = message(step.log!);
288
343
  }
289
344
  step.log = message;
345
+ this.dropCheckpointsFrom(lastIndex);
290
346
  }
291
347
 
292
348
  _zipStartPoint = 0;
@@ -315,8 +371,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
315
371
  }
316
372
 
317
373
  if (hasChange) {
318
- // Pops and in-place merges can leave any cached walk pointing into invalid territory.
319
- this.invalidateSerializeCache();
374
+ // The merged step changed in place: checkpoints that include it are stale.
375
+ this.dropCheckpointsFrom(this.clockSteps.length - 1);
320
376
  this.pass++;
321
377
  // No trailing force-flush: it would only push an empty FlushClockStep (no chit
322
378
  // diff, no log) that the client has to walk through for no visual change. The
@@ -386,17 +442,22 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
386
442
  sawChange = true;
387
443
  }
388
444
  }
389
- this.dirtyChitIds.clear();
390
445
 
391
- // 3. Detect deleted chits — orphans in lastChitStates that weren't serialized above
392
- const deletedRoots: Chit[] = [];
393
- for (const id of Object.keys(this.lastChitStates)) {
394
- if (this.lastChitStates[id] === Chit.deletedIfSerialized()) continue;
446
+ // 3. Detect deleted chits — orphans in lastChitStates. Losing a parent marks a chit dirty, so
447
+ // only this flush's dirty chits and the roots of absorbed sub-turns can have become orphans.
448
+ const deletedRoots = new Set<Chit>();
449
+ const checkOrphan = (id: string) => {
450
+ const lastState = this.lastChitStates[id];
451
+ if (lastState === undefined || lastState === Chit.deletedIfSerialized()) return;
395
452
  const chit = this.chitLookup[id];
396
453
  if (chit && !chit.parent && !this.chitsToLock.includes(chit)) {
397
- deletedRoots.push(chit);
454
+ deletedRoots.add(chit);
398
455
  }
399
- }
456
+ };
457
+ this.dirtyChitIds.forEach(checkOrphan);
458
+ this.absorbedRootIds.forEach(checkOrphan);
459
+ this.dirtyChitIds.clear();
460
+ this.absorbedRootIds.clear();
400
461
 
401
462
  for (const chit of deletedRoots) {
402
463
  if (chit.id) {
@@ -421,9 +482,9 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
421
482
  throw new Error("Cannot flush while subturns are active");
422
483
  }
423
484
 
485
+ // Appending leaves every checkpoint valid, ours and our ancestors': theirs stop before the
486
+ // step that holds us until we have been absorbed.
424
487
  this.clockSteps.push(new FlushClockStep(this.clock, newStates));
425
- // Ancestors' caches included our prior contribution; the new step makes them stale.
426
- this.parent?.invalidateSerializeCache();
427
488
  }
428
489
  }
429
490
 
@@ -478,17 +539,19 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
478
539
 
479
540
  this.decisionIndex++;
480
541
 
542
+ let step: SubTurnsClockStep<P, R>;
481
543
  if (this.activeSubTurns.length === 0) {
482
- this.clockSteps.push(new SubTurnsClockStep(this.clock, [turn]));
544
+ step = new SubTurnsClockStep(this.clock, [turn]);
545
+ this.clockSteps.push(step);
483
546
  } else {
484
547
  const lastStep = this.clockSteps[this.clockSteps.length - 1];
485
548
  if (!(lastStep instanceof SubTurnsClockStep)) {
486
549
  throw new Error("Unexpected clocksteps stage");
487
550
  }
488
551
  lastStep.turns.push(turn);
552
+ step = lastStep;
489
553
  }
490
- // Either case mutates a step our own cache (or an ancestor's) may have already walked past.
491
- this.invalidateSerializeCache();
554
+ // Neither case touches a checkpoint: none reaches a step with a turn still to absorb.
492
555
 
493
556
  this.activeSubTurns.push(turn);
494
557
 
@@ -511,6 +574,10 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
511
574
  });
512
575
 
513
576
  this.lastChitStates = { ...this.lastChitStates, ...turn.lastChitStates };
577
+ turn.chitsToLock.forEach((chit) => chit.id && this.absorbedRootIds.add(chit.id));
578
+ // serialize() merges the step's turns in this order, so a chit written by several parallel
579
+ // turns serializes as the engine now holds it.
580
+ step.absorbed.push(turn);
514
581
  turn.releasePostAbsorptionRefs();
515
582
 
516
583
  return result;
@@ -519,8 +586,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
519
586
  /**
520
587
  * Called by the parent right after it has absorbed our `chitLookup` and `lastChitStates`.
521
588
  * After this we will only ever be walked via `serialize` / `chitsHistory` / `gameLog`,
522
- * which only need `clockSteps` and `lockedChitStates` — so drop the heavy per-chit
523
- * bookkeeping to keep finished sub-turns from pinning hundreds of chit references.
589
+ * and only by the parent, which needs nothing of ours but `clockSteps` — so drop the heavy
590
+ * per-chit bookkeeping to keep finished sub-turns from pinning hundreds of chit references.
524
591
  * @internal
525
592
  */
526
593
  private releasePostAbsorptionRefs() {
@@ -529,7 +596,14 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
529
596
  this.lastChitStates = {};
530
597
  this.pendingNewChits.clear();
531
598
  this.dirtyChitIds.clear();
532
- this._serializeCache = undefined;
599
+ this.absorbedRootIds.clear();
600
+ if (!Turn.releaseAbsorbedTurns) return;
601
+ // The locked snapshot and every checkpoint are full copies of the chit map, and a long game
602
+ // has hundreds of finished turns. The parent walks into us with its own map, which at our
603
+ // step holds exactly what the snapshot held, so a finished turn keeps neither.
604
+ this.absorbed = true;
605
+ this.lockedChitStates = {};
606
+ this._checkpoints = [];
533
607
  }
534
608
 
535
609
  public async runParallelTurns<A>(
@@ -538,7 +612,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
538
612
  action: (p: P, turn: Turn<A, P, R>) => Promise<A>,
539
613
  ): Promise<A[]> {
540
614
  // the whole point of this function is so we can mark all players as having a prompt waiting for them
541
- players.forEach((player) => (player.promptStatus.latestPromptMessage = "Waiting for turn to complete"));
615
+ players.forEach((player) => this.setPromptMessage(player, "Waiting for turn to complete"));
542
616
 
543
617
  const turns = players.map((player) =>
544
618
  this.createTurn(chits(player), player, (turn: Turn<A, P, R>) => action(player, turn)),
@@ -806,7 +880,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
806
880
  };
807
881
 
808
882
  // Seed with the initial locked state so chits that never diff in this turn still
809
- // surface their starting form (flush steps now hold diffs only).
883
+ // surface their starting form (flush steps now hold diffs only). A finished turn has no
884
+ // snapshot; the parent already logged that state before walking into it.
810
885
  ids.forEach((id) => {
811
886
  const initial = this.lockedChitStates[id];
812
887
  if (initial !== undefined) {
@@ -831,8 +906,12 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
831
906
  return result;
832
907
  }
833
908
 
834
- /** @internal */
835
- serialize(playerId: string, clock: number): ChitSerializationResponse {
909
+ /**
910
+ * `into` is the parent's working chit map while it walks this turn. A finished turn has no
911
+ * snapshot of its own and writes its diffs straight into it; the parent then needs no merge.
912
+ * @internal
913
+ */
914
+ serialize(playerId: string, clock: number, into?: ChitStateLookup): ChitSerializationResponse {
836
915
  clock = Math.max(0, Math.min(clock, this.playerVisibleClockTime(playerId)));
837
916
 
838
917
  let chits: ChitStateLookup;
@@ -841,24 +920,41 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
841
920
  let resultingClock: number;
842
921
  let index: number;
843
922
 
844
- const cache = this._serializeCache;
845
- if (cache && cache.playerId === playerId && clock >= cache.resultingClock) {
846
- chits = { ...cache.chits };
847
- subTurns = cache.subTurns ? { ...cache.subTurns } : undefined;
848
- log = cache.log ? { ...cache.log } : undefined;
849
- resultingClock = cache.resultingClock;
850
- index = cache.nextIndex;
923
+ // Resume from the furthest checkpoint that ends at or before the target clock
924
+ let checkpoint: SerializeCheckpoint | undefined;
925
+ for (let i = this._checkpoints.length - 1; i >= 0; i--) {
926
+ if (this._checkpoints[i].resultingClock <= clock) {
927
+ checkpoint = this._checkpoints[i];
928
+ break;
929
+ }
930
+ }
931
+ if (checkpoint) {
932
+ chits = { ...checkpoint.chits };
933
+ subTurns = checkpoint.subTurns ? { ...checkpoint.subTurns } : undefined;
934
+ log = checkpoint.log ? { ...checkpoint.log } : undefined;
935
+ resultingClock = checkpoint.resultingClock;
936
+ index = checkpoint.nextIndex;
851
937
  } else {
852
938
  // Diff-replay: seed with the initial locked snapshot and merge every flush diff
853
- // up to (but not including) the target clock.
854
- chits = { ...this.lockedChitStates };
939
+ // up to (but not including) the target clock. A finished turn's snapshot was the parent's
940
+ // map at this step, which is what the parent hands us.
941
+ chits = this.absorbed ? (into ?? {}) : { ...this.lockedChitStates };
855
942
  subTurns = undefined;
856
943
  log = undefined;
857
944
  resultingClock = -1;
858
945
  index = 0;
859
946
  }
860
947
 
861
- let cacheable = true;
948
+ const snapshot = (): SerializeCheckpoint => ({
949
+ nextIndex: index,
950
+ chits: { ...chits },
951
+ subTurns: subTurns ? { ...subTurns } : undefined,
952
+ log: log ? { ...log } : undefined,
953
+ resultingClock: resultingClock === -1 ? clock : resultingClock,
954
+ });
955
+ // True while every step walked is final and was consumed whole, so the walk may be checkpointed
956
+ let checkpointable = Turn.serializeCheckpoints && !this.absorbed;
957
+ let lastCheckpointIndex = index;
862
958
  while (index < this.clockSteps.length) {
863
959
  const clockStep = this.clockSteps[index];
864
960
  if (clockStep.startClock >= clock) break;
@@ -875,13 +971,21 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
875
971
  subTurns = {};
876
972
  resultingClock = clockStep.startClock;
877
973
  let remainingClocksToSpend = clock - clockStep.startClock;
878
- for (const turn of clockStep.visibleTurns(playerId)) {
974
+ // A step every turn of which has been absorbed is final, and asked for in full it reads the
975
+ // same for every player: its turns merge in absorption order, the order their changes
976
+ // landed in `lastChitStates`, so a chit written by two parallel turns serializes as the
977
+ // engine holds it. A step still in motion, or asked for part-way, is walked as this player
978
+ // may see it, and the walk stops there: a later request has to re-walk it.
979
+ const final = clockStep.fullyAbsorbed && clock >= clockStep.endClock();
980
+ for (const turn of final ? clockStep.absorbed : clockStep.visibleTurns(playerId)) {
879
981
  const time = Math.max(remainingClocksToSpend, 0);
880
982
  if (time <= 0) break;
881
983
 
882
984
  // we are going forward so we never want to have a turn go backwards. ever.
883
- const serialized = turn.serialize(playerId, time);
884
- Object.assign(chits, serialized.chits);
985
+ const serialized = turn.serialize(playerId, time, chits);
986
+ if (serialized.chits !== chits) {
987
+ Object.assign(chits, serialized.chits);
988
+ }
885
989
 
886
990
  resultingClock += serialized.clockDetails.clock;
887
991
  remainingClocksToSpend -= serialized.clockDetails.clock;
@@ -890,30 +994,24 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
890
994
  log = { message: serialized.log.message, clock: serialized.log.clock + clockStep.startClock };
891
995
  }
892
996
  }
893
- // We can only advance `index` past this step (and cache from here) if the
894
- // requested `clock` consumed this step's *entire* extent — i.e. every visible
895
- // sub-turn was asked for at least its full clock time. Otherwise a future
896
- // request at a higher `clock` needs to re-ask the sub-turn for more time,
897
- // which means re-processing this same step.
898
- if (clock < clockStep.endClock(playerId)) {
899
- cacheable = false;
997
+ if (!final) {
998
+ checkpointable = false;
900
999
  break;
901
1000
  }
902
1001
  index++;
903
1002
  } else {
904
1003
  index++;
905
1004
  }
1005
+
1006
+ if (checkpointable && index - lastCheckpointIndex >= Turn.serializeCheckpointInterval) {
1007
+ this.addCheckpoint(snapshot());
1008
+ lastCheckpointIndex = index;
1009
+ }
906
1010
  }
907
1011
 
908
- if (cacheable) {
909
- this._serializeCache = {
910
- playerId,
911
- nextIndex: index,
912
- chits: { ...chits },
913
- subTurns: subTurns ? { ...subTurns } : undefined,
914
- log: log ? { ...log } : undefined,
915
- resultingClock: resultingClock === -1 ? clock : resultingClock,
916
- };
1012
+ // Remember where this walk ended, so a request for a later clock continues from here
1013
+ if (checkpointable && index > lastCheckpointIndex) {
1014
+ this.addCheckpoint(snapshot());
917
1015
  }
918
1016
 
919
1017
  return {
@@ -971,10 +1069,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
971
1069
  prompt.id = `${this.id} prompt ${this.decisionIndex}`;
972
1070
  prompt.clock = this.clock;
973
1071
  prompt.canReset = this.state.hasUserMadeChoiceSinceUserContextChangedOrRng(this.decisionIndex - 1);
974
- this.player.promptStatus.latestPromptMessage = prompt.message;
975
- if (!this.player.promptStatus.latestPromptMessage.length) {
976
- this.player.promptStatus.latestPromptMessage = "No prompt set";
977
- }
1072
+ this.setPromptMessage(this.player, prompt.message.length ? prompt.message : "No prompt set");
978
1073
 
979
1074
  this.flush();
980
1075
 
@@ -1039,7 +1134,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1039
1134
  this.state.setOrCreatePromptResponse(this.decisionIndex, resolution);
1040
1135
 
1041
1136
  this.player.promptStatus.latestPromptResponseTime = this.absoluteClock(this.player.id);
1042
- this.player.promptStatus.latestPromptMessage = undefined;
1137
+ this.setPromptMessage(this.player, undefined);
1043
1138
  this.decisionIndex++;
1044
1139
  }
1045
1140
 
@@ -1145,7 +1240,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1145
1240
 
1146
1241
  private cleanUp() {
1147
1242
  if (this.player) {
1148
- this.player.promptStatus.latestPromptMessage = undefined;
1243
+ this.setPromptMessage(this.player, undefined);
1149
1244
  }
1150
1245
  this.completed = true;
1151
1246
  this.flush();
@@ -1190,8 +1285,34 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1190
1285
  return result;
1191
1286
  }
1192
1287
 
1288
+ /**
1289
+ * Takes every chit this turn made (and those a sub-turn still running under it made) off the board,
1290
+ * ahead of a parent's restart. The parent never absorbed us, so its own reset knows nothing of them:
1291
+ * left alone they would stay on the board, and the next sub-turn would lock them as if they had
1292
+ * always been there. Chits we only changed are the parent's to restore.
1293
+ */
1294
+ private discardCreatedChits() {
1295
+ this.activeSubTurns.forEach((t) => t.discardCreatedChits());
1296
+ for (const chit of Object.values(this.chitLookup)) {
1297
+ if (chit.id && this.lockedChitStates[chit.id] === undefined) {
1298
+ chit.forgetFallbackUnlessHidden();
1299
+ chit.removeFromParent();
1300
+ }
1301
+ }
1302
+ for (const chit of this.pendingNewChits) {
1303
+ if (!chit.id) {
1304
+ chit.forgetFallbackUnlessHidden();
1305
+ chit.removeFromParent();
1306
+ }
1307
+ }
1308
+ this.pendingNewChits.clear();
1309
+ }
1310
+
1193
1311
  private restartExecution() {
1194
- this.activeSubTurns.forEach((t) => t.destroy());
1312
+ this.activeSubTurns.forEach((t) => {
1313
+ t.discardCreatedChits();
1314
+ t.destroy();
1315
+ });
1195
1316
 
1196
1317
  const chits = Object.values(this.chitLookup).filter((chit) => chit.id);
1197
1318
 
@@ -1204,6 +1325,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1204
1325
  if (lockedState) {
1205
1326
  chit.deserialize(lockedState, this.findChit);
1206
1327
  } else {
1328
+ chit.forgetFallbackUnlessHidden(); // a chit made to come from another piece must not linger beside it
1207
1329
  chit.removeFromParent(); // effectively "deletes" it. In practice, the `fn` will recreate a new chit which will have the new ID, which replaces this one.
1208
1330
  }
1209
1331
  });
@@ -1223,6 +1345,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1223
1345
 
1224
1346
  this.lastChitStates = { ...this.lockedChitStates }; // reset our known chit states
1225
1347
  this.dirtyChitIds.clear();
1348
+ this.absorbedRootIds.clear();
1226
1349
  this.pendingNewChits.clear();
1227
1350
  // chits were deserialized back to locked state — mark them clean so future
1228
1351
  // modifications correctly trigger markDirty() → notifyChitDirty()
@@ -1235,7 +1358,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1235
1358
  this.unresolvedPrompt = undefined;
1236
1359
  this.activeSubTurns = [];
1237
1360
  this.pass++;
1238
- this.invalidateSerializeCache();
1361
+ this._checkpoints = [];
1239
1362
  }
1240
1363
  }
1241
1364
 
@@ -1246,8 +1369,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1246
1369
  type ChitLookup = { [id: string]: Chit };
1247
1370
  type ChitStateLookup = { [id: string]: string };
1248
1371
 
1249
- type SerializeCache = {
1250
- playerId: string;
1372
+ /** serialize()'s replay captured after `nextIndex` steps; see Turn._checkpoints */
1373
+ type SerializeCheckpoint = {
1251
1374
  nextIndex: number;
1252
1375
  chits: ChitStateLookup;
1253
1376
  subTurns?: { [turnId: string]: ClockDetails };
@@ -1261,6 +1384,13 @@ abstract class ClockStep {
1261
1384
  }
1262
1385
 
1263
1386
  class SubTurnsClockStep<P extends PlayerChit, R extends RootChit<P>> extends ClockStep {
1387
+ /** The turns the parent has absorbed, in that order: the order their changes landed in its state */
1388
+ public absorbed: Turn<any, P, R>[] = [];
1389
+
1390
+ get fullyAbsorbed() {
1391
+ return this.absorbed.length === this.turns.length;
1392
+ }
1393
+
1264
1394
  visibleTurns(playerId?: string) {
1265
1395
  if (this.turns.length === 1 || playerId === undefined) {
1266
1396
  return this.turns;
@@ -12,6 +12,14 @@ export type RngResponse = { readonly type: "rng"; value: number[] };
12
12
 
13
13
  export type Decision = PromptResponse | RngResponse | TurnState;
14
14
 
15
+ /**
16
+ * Where a match's random numbers come from. Called once per `rng()` / `takeRng(count)` draw with the
17
+ * number of values wanted; return that many numbers in [0, 1), or `undefined` to fall back to
18
+ * `Math.random`. Draws are persisted in the turn state as always, so a source only matters for a
19
+ * draw that has not been made yet (never on replay, reload or undo).
20
+ */
21
+ export type RngSource = (count: number) => number[] | undefined;
22
+
15
23
  export class TurnState {
16
24
  readonly type = "turn";
17
25
  id = "root";
@@ -20,12 +28,34 @@ export class TurnState {
20
28
 
21
29
  decisions: Decision[] = [];
22
30
 
31
+ /**
32
+ * AI players' plan memory, keyed by player id. Only the root turn state carries it. It rides
33
+ * along with the decisions so a bot that is re-seated after a reload (or in another process)
34
+ * picks up where it left off. Absent when no bot has committed a plan.
35
+ */
36
+ ai?: { [playerId: string]: unknown };
37
+
23
38
  private parentTurnState: TurnState | undefined;
24
39
  private parentTurnIndex = 0;
25
40
 
41
+ /** Set on the root turn state (see `Match`); sub-turns inherit it. Not serialized. */
42
+ public rngSource?: RngSource;
43
+
44
+ private get rng(): RngSource | undefined {
45
+ return this.rngSource ?? this.parentTurnState?.rng;
46
+ }
47
+
48
+ private draw(count: number): number[] {
49
+ const scripted = this.rng?.(count);
50
+ if (scripted && scripted.length === count) {
51
+ return scripted;
52
+ }
53
+ return Array.from({ length: count }, () => Math.random());
54
+ }
55
+
26
56
  toJSON() {
27
57
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
28
- const { parentTurnIndex, parentTurnState, ...rest } = this;
58
+ const { parentTurnIndex, parentTurnState, rngSource, ...rest } = this;
29
59
  return rest;
30
60
  }
31
61
 
@@ -68,7 +98,7 @@ export class TurnState {
68
98
  }
69
99
  return (result as RngResponse).value[0];
70
100
  } else if (index === this.decisions.length) {
71
- const rng = Math.random();
101
+ const rng = this.draw(1)[0];
72
102
  this.decisions.push({
73
103
  type: "rng",
74
104
  value: [rng],
@@ -87,7 +117,7 @@ export class TurnState {
87
117
  }
88
118
  return (result as RngResponse).value;
89
119
  } else if (index === this.decisions.length) {
90
- const rngs = Array.from({ length: count }, () => Math.random());
120
+ const rngs = this.draw(count);
91
121
  this.decisions.push({
92
122
  type: "rng",
93
123
  value: rngs,
@@ -120,6 +150,7 @@ export class TurnState {
120
150
  this.playerId = serialized.playerId;
121
151
  this.id = serialized.id;
122
152
  this.createdDate = serialized.createdDate ?? Date.now();
153
+ this.ai = serialized.ai;
123
154
  this.decisions = (serialized.decisions ?? []).map((d: Decision, i: number) => {
124
155
  if (d.type === "turn") {
125
156
  const existing = this.decisions[i];