@pretty-chitty/core 2.0.0 → 2.3.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 (377) 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/ContextGalleryDisplay.d.ts.map +1 -1
  10. package/dist/components/ContextGalleryDisplay.js +1 -1
  11. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  12. package/dist/components/DemoWrapper.d.ts +33 -2
  13. package/dist/components/DemoWrapper.d.ts.map +1 -1
  14. package/dist/components/DemoWrapper.js +77 -36
  15. package/dist/components/DemoWrapper.js.map +1 -1
  16. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  17. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  18. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  19. package/dist/components/Gallery/BuiltItem.d.ts +16 -2
  20. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  21. package/dist/components/Gallery/BuiltItem.js +92 -16
  22. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  23. package/dist/components/Gallery/GalleryController.d.ts +26 -0
  24. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  25. package/dist/components/Gallery/GalleryController.js +106 -6
  26. package/dist/components/Gallery/GalleryController.js.map +1 -1
  27. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  28. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryViewer.js +139 -12
  30. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  31. package/dist/components/Gallery/LayoutManager.d.ts +10 -0
  32. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  33. package/dist/components/Gallery/LayoutManager.js +49 -3
  34. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  35. package/dist/components/Gallery/constants.d.ts +6 -0
  36. package/dist/components/Gallery/constants.d.ts.map +1 -1
  37. package/dist/components/Gallery/constants.js +6 -0
  38. package/dist/components/Gallery/constants.js.map +1 -1
  39. package/dist/components/Gallery/registry.d.ts +34 -0
  40. package/dist/components/Gallery/registry.d.ts.map +1 -0
  41. package/dist/components/Gallery/registry.js +17 -0
  42. package/dist/components/Gallery/registry.js.map +1 -0
  43. package/dist/components/Gallery/types.d.ts +5 -0
  44. package/dist/components/Gallery/types.d.ts.map +1 -1
  45. package/dist/components/GameDesigner.d.ts.map +1 -1
  46. package/dist/components/GameDesigner.js +84 -10
  47. package/dist/components/GameDesigner.js.map +1 -1
  48. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  49. package/dist/components/InlineGalleryDisplay.js +35 -8
  50. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  51. package/dist/components/LiveButton.d.ts.map +1 -1
  52. package/dist/components/LiveButton.js +5 -2
  53. package/dist/components/LiveButton.js.map +1 -1
  54. package/dist/components/MatchViewer.d.ts +6 -1
  55. package/dist/components/MatchViewer.d.ts.map +1 -1
  56. package/dist/components/MatchViewer.js +9 -3
  57. package/dist/components/MatchViewer.js.map +1 -1
  58. package/dist/components/Panel/ExternalDrag.d.ts +30 -0
  59. package/dist/components/Panel/ExternalDrag.d.ts.map +1 -0
  60. package/dist/components/Panel/ExternalDrag.js +87 -0
  61. package/dist/components/Panel/ExternalDrag.js.map +1 -0
  62. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  63. package/dist/components/Panel/MultiPanel.js +18 -0
  64. package/dist/components/Panel/MultiPanel.js.map +1 -1
  65. package/dist/components/Panel/PanelContents.d.ts +3 -0
  66. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  67. package/dist/components/Panel/PanelContents.js +116 -23
  68. package/dist/components/Panel/PanelContents.js.map +1 -1
  69. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  70. package/dist/components/Panel/PanelTabStack.js +1 -1
  71. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  72. package/dist/components/PanelSpark.d.ts.map +1 -1
  73. package/dist/components/PanelSpark.js +6 -3
  74. package/dist/components/PanelSpark.js.map +1 -1
  75. package/dist/components/Playground.d.ts.map +1 -1
  76. package/dist/components/Playground.js +10 -4
  77. package/dist/components/Playground.js.map +1 -1
  78. package/dist/components/PromptControls.d.ts.map +1 -1
  79. package/dist/components/PromptControls.js +4 -2
  80. package/dist/components/PromptControls.js.map +1 -1
  81. package/dist/components/SparkLineChart.d.ts.map +1 -1
  82. package/dist/components/SparkLineChart.js +22 -26
  83. package/dist/components/SparkLineChart.js.map +1 -1
  84. package/dist/components/TimeControlBar.d.ts.map +1 -1
  85. package/dist/components/TimeControlBar.js +5 -3
  86. package/dist/components/TimeControlBar.js.map +1 -1
  87. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  88. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  89. package/dist/components/TokenizedMarkdown.js +144 -0
  90. package/dist/components/TokenizedMarkdown.js.map +1 -0
  91. package/dist/components/TokenizedMessage.d.ts +6 -0
  92. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  93. package/dist/components/TokenizedMessage.js +20 -19
  94. package/dist/components/TokenizedMessage.js.map +1 -1
  95. package/dist/components/TopBar.d.ts.map +1 -1
  96. package/dist/components/TopBar.js +3 -1
  97. package/dist/components/TopBar.js.map +1 -1
  98. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  99. package/dist/components/TopBarPlayers.js +2 -2
  100. package/dist/components/TopBarPlayers.js.map +1 -1
  101. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  102. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  103. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  104. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  105. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  106. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  107. package/dist/components/Tutorial/TutorialBox.js +239 -0
  108. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  109. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  110. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  111. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  112. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  113. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  114. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  115. package/dist/components/Tutorial/TutorialOverlay.js +1147 -0
  116. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  117. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  118. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  119. package/dist/components/Tutorial/targetRects.js +241 -0
  120. package/dist/components/Tutorial/targetRects.js.map +1 -0
  121. package/dist/components/Viewer.d.ts.map +1 -1
  122. package/dist/components/Viewer.js +1 -0
  123. package/dist/components/Viewer.js.map +1 -1
  124. package/dist/game/Chit.d.ts +10 -1
  125. package/dist/game/Chit.d.ts.map +1 -1
  126. package/dist/game/Chit.js +24 -6
  127. package/dist/game/Chit.js.map +1 -1
  128. package/dist/game/ClientTimeState.d.ts +14 -0
  129. package/dist/game/ClientTimeState.d.ts.map +1 -1
  130. package/dist/game/ClientTimeState.js +17 -0
  131. package/dist/game/ClientTimeState.js.map +1 -1
  132. package/dist/game/GalleryItemChitChildrenSource.d.ts +1 -0
  133. package/dist/game/GalleryItemChitChildrenSource.d.ts.map +1 -1
  134. package/dist/game/GalleryItemChitChildrenSource.js +1 -0
  135. package/dist/game/GalleryItemChitChildrenSource.js.map +1 -1
  136. package/dist/game/GalleryItemRawSource.d.ts +1 -0
  137. package/dist/game/GalleryItemRawSource.d.ts.map +1 -1
  138. package/dist/game/GalleryItemRawSource.js +1 -0
  139. package/dist/game/GalleryItemRawSource.js.map +1 -1
  140. package/dist/game/Game.d.ts +6 -0
  141. package/dist/game/Game.d.ts.map +1 -1
  142. package/dist/game/GameButton.d.ts +8 -0
  143. package/dist/game/GameButton.d.ts.map +1 -1
  144. package/dist/game/GameButton.js +13 -1
  145. package/dist/game/GameButton.js.map +1 -1
  146. package/dist/game/GameTheme.d.ts +3 -0
  147. package/dist/game/GameTheme.d.ts.map +1 -1
  148. package/dist/game/GameTheme.js +2 -0
  149. package/dist/game/GameTheme.js.map +1 -1
  150. package/dist/game/Match.d.ts +8 -2
  151. package/dist/game/Match.d.ts.map +1 -1
  152. package/dist/game/Match.js +4 -1
  153. package/dist/game/Match.js.map +1 -1
  154. package/dist/game/ModalState.d.ts +3 -0
  155. package/dist/game/ModalState.d.ts.map +1 -1
  156. package/dist/game/ModalState.js +2 -0
  157. package/dist/game/ModalState.js.map +1 -1
  158. package/dist/game/Pick.d.ts +2 -0
  159. package/dist/game/Pick.d.ts.map +1 -1
  160. package/dist/game/Pick.js +18 -4
  161. package/dist/game/Pick.js.map +1 -1
  162. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  163. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  164. package/dist/game/PlayerPromptStatusChit.js +6 -4
  165. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  166. package/dist/game/Prompt.d.ts +18 -1
  167. package/dist/game/Prompt.d.ts.map +1 -1
  168. package/dist/game/Prompt.js +29 -1
  169. package/dist/game/Prompt.js.map +1 -1
  170. package/dist/game/SparkChit.d.ts +6 -0
  171. package/dist/game/SparkChit.d.ts.map +1 -1
  172. package/dist/game/SparkChit.js +8 -0
  173. package/dist/game/SparkChit.js.map +1 -1
  174. package/dist/game/Turn.d.ts +17 -6
  175. package/dist/game/Turn.d.ts.map +1 -1
  176. package/dist/game/Turn.js +179 -69
  177. package/dist/game/Turn.js.map +1 -1
  178. package/dist/game/TurnState.d.ts +12 -1
  179. package/dist/game/TurnState.d.ts.map +1 -1
  180. package/dist/game/TurnState.js +15 -3
  181. package/dist/game/TurnState.js.map +1 -1
  182. package/dist/game/ai/AiClientPrompts.d.ts +20 -3
  183. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -1
  184. package/dist/game/ai/AiClientPrompts.js +42 -6
  185. package/dist/game/ai/AiClientPrompts.js.map +1 -1
  186. package/dist/game/ai/AiPlayerView.js +2 -0
  187. package/dist/game/ai/AiPlayerView.js.map +1 -1
  188. package/dist/game/clientTransport/ClientPrompts.d.ts +22 -1
  189. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  190. package/dist/game/clientTransport/ClientPrompts.js +72 -5
  191. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  192. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  193. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  194. package/dist/game/clientTransport/ClientTime.js +71 -12
  195. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  196. package/dist/game/tutorial/TutorialController.d.ts +308 -0
  197. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  198. package/dist/game/tutorial/TutorialController.js +1195 -0
  199. package/dist/game/tutorial/TutorialController.js.map +1 -0
  200. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  201. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  202. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  203. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  204. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  205. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  206. package/dist/game/tutorial/TutorialTheme.js +39 -0
  207. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  208. package/dist/game/tutorial/allowed.d.ts +2 -0
  209. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  210. package/dist/game/tutorial/allowed.js +119 -0
  211. package/dist/game/tutorial/allowed.js.map +1 -0
  212. package/dist/game/tutorial/checks.d.ts +58 -0
  213. package/dist/game/tutorial/checks.d.ts.map +1 -0
  214. package/dist/game/tutorial/checks.js +144 -0
  215. package/dist/game/tutorial/checks.js.map +1 -0
  216. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  217. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  218. package/dist/game/tutorial/createDemoMatch.js +67 -0
  219. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  220. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  221. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  222. package/dist/game/tutorial/defineTutorial.js +86 -0
  223. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  224. package/dist/game/tutorial/runTutorial.d.ts +64 -0
  225. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  226. package/dist/game/tutorial/runTutorial.js +293 -0
  227. package/dist/game/tutorial/runTutorial.js.map +1 -0
  228. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  229. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  230. package/dist/hooks/usePanelNavigation.js +36 -0
  231. package/dist/hooks/usePanelNavigation.js.map +1 -0
  232. package/dist/hooks/useTimeController.d.ts +4 -1
  233. package/dist/hooks/useTimeController.d.ts.map +1 -1
  234. package/dist/hooks/useTimeController.js +10 -2
  235. package/dist/hooks/useTimeController.js.map +1 -1
  236. package/dist/hooks/useTutorial.d.ts +51 -0
  237. package/dist/hooks/useTutorial.d.ts.map +1 -0
  238. package/dist/hooks/useTutorial.js +16 -0
  239. package/dist/hooks/useTutorial.js.map +1 -0
  240. package/dist/index.d.ts +37 -0
  241. package/dist/index.d.ts.map +1 -1
  242. package/dist/index.js +19 -2
  243. package/dist/index.js.map +1 -1
  244. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  245. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  246. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  247. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  248. package/dist/rendering/ChitGalleryItemInstance.d.ts +14 -3
  249. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  250. package/dist/rendering/ChitGalleryItemInstance.js +29 -1
  251. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  252. package/dist/rendering/ChitRenderInstance.d.ts +15 -1
  253. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  254. package/dist/rendering/ChitRenderInstance.js +49 -4
  255. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  256. package/dist/rendering/LightWrapper.d.ts.map +1 -1
  257. package/dist/rendering/LightWrapper.js +10 -1
  258. package/dist/rendering/LightWrapper.js.map +1 -1
  259. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  260. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  261. package/dist/rendering/RootChitRenderInstance.js +29 -0
  262. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  263. package/dist/rendering/Splay.d.ts +11 -0
  264. package/dist/rendering/Splay.d.ts.map +1 -1
  265. package/dist/rendering/Splay.js +20 -10
  266. package/dist/rendering/Splay.js.map +1 -1
  267. package/dist/utilities/Annotations.d.ts +15 -0
  268. package/dist/utilities/Annotations.d.ts.map +1 -1
  269. package/dist/utilities/Annotations.js +31 -7
  270. package/dist/utilities/Annotations.js.map +1 -1
  271. package/dist/utilities/CanvasStack/CanvasStack.d.ts +2 -0
  272. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  273. package/dist/utilities/CanvasStack/CanvasStack.js +4 -0
  274. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  275. package/dist/utilities/CanvasStack/RichTextRenderer.d.ts.map +1 -1
  276. package/dist/utilities/CanvasStack/RichTextRenderer.js +12 -0
  277. package/dist/utilities/CanvasStack/RichTextRenderer.js.map +1 -1
  278. package/dist/utilities/Dice.d.ts +2 -0
  279. package/dist/utilities/Dice.d.ts.map +1 -1
  280. package/dist/utilities/Dice.js +5 -1
  281. package/dist/utilities/Dice.js.map +1 -1
  282. package/dist/utilities/GalleryItemConversion.d.ts.map +1 -1
  283. package/dist/utilities/GalleryItemConversion.js +5 -7
  284. package/dist/utilities/GalleryItemConversion.js.map +1 -1
  285. package/dist/utilities/TokenizedText.d.ts +6 -0
  286. package/dist/utilities/TokenizedText.d.ts.map +1 -1
  287. package/dist/utilities/TokenizedText.js.map +1 -1
  288. package/dist/utilities/zIndex.d.ts +1 -0
  289. package/dist/utilities/zIndex.d.ts.map +1 -1
  290. package/dist/utilities/zIndex.js +1 -0
  291. package/dist/utilities/zIndex.js.map +1 -1
  292. package/package.json +3 -2
  293. package/src/library/components/ActionLogDisplay.tsx +1 -0
  294. package/src/library/components/BottomBarButton.tsx +5 -0
  295. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  296. package/src/library/components/DemoWrapper.tsx +150 -44
  297. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  298. package/src/library/components/Gallery/BuiltItem.ts +92 -16
  299. package/src/library/components/Gallery/GalleryController.ts +111 -10
  300. package/src/library/components/Gallery/GalleryViewer.tsx +144 -12
  301. package/src/library/components/Gallery/LayoutManager.ts +55 -6
  302. package/src/library/components/Gallery/constants.ts +6 -0
  303. package/src/library/components/Gallery/registry.ts +44 -0
  304. package/src/library/components/Gallery/types.ts +6 -0
  305. package/src/library/components/GameDesigner.tsx +165 -12
  306. package/src/library/components/InlineGalleryDisplay.tsx +41 -6
  307. package/src/library/components/LiveButton.tsx +8 -5
  308. package/src/library/components/MatchViewer.tsx +14 -3
  309. package/src/library/components/Panel/ExternalDrag.ts +122 -0
  310. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  311. package/src/library/components/Panel/PanelContents.tsx +96 -1
  312. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  313. package/src/library/components/PanelSpark.tsx +12 -5
  314. package/src/library/components/Playground.tsx +48 -21
  315. package/src/library/components/PromptControls.tsx +7 -3
  316. package/src/library/components/SparkLineChart.tsx +23 -27
  317. package/src/library/components/TimeControlBar.tsx +5 -3
  318. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  319. package/src/library/components/TokenizedMessage.tsx +28 -32
  320. package/src/library/components/TopBar.tsx +2 -1
  321. package/src/library/components/TopBarPlayers.tsx +13 -15
  322. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  323. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  324. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  325. package/src/library/components/Tutorial/TutorialOverlay.tsx +1316 -0
  326. package/src/library/components/Tutorial/targetRects.ts +273 -0
  327. package/src/library/components/Viewer.tsx +1 -0
  328. package/src/library/game/Chit.ts +28 -7
  329. package/src/library/game/ClientTimeState.ts +18 -0
  330. package/src/library/game/GalleryItemChitChildrenSource.ts +1 -0
  331. package/src/library/game/GalleryItemRawSource.ts +1 -0
  332. package/src/library/game/Game.ts +7 -0
  333. package/src/library/game/GameButton.ts +13 -1
  334. package/src/library/game/GameTheme.ts +4 -0
  335. package/src/library/game/Match.ts +12 -2
  336. package/src/library/game/ModalState.ts +3 -0
  337. package/src/library/game/Pick.ts +17 -4
  338. package/src/library/game/PlayerPromptStatusChit.ts +6 -4
  339. package/src/library/game/Prompt.ts +33 -2
  340. package/src/library/game/SparkChit.ts +9 -0
  341. package/src/library/game/Turn.ts +185 -70
  342. package/src/library/game/TurnState.ts +26 -3
  343. package/src/library/game/ai/AI_GUIDE.md +10 -0
  344. package/src/library/game/ai/AiClientPrompts.ts +60 -11
  345. package/src/library/game/ai/AiPlayerView.ts +2 -0
  346. package/src/library/game/clientTransport/ClientPrompts.ts +76 -5
  347. package/src/library/game/clientTransport/ClientTime.ts +75 -14
  348. package/src/library/game/serialize.test.ts +275 -0
  349. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +416 -0
  350. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  351. package/src/library/game/tutorial/TutorialController.ts +1299 -0
  352. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  353. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  354. package/src/library/game/tutorial/allowed.ts +145 -0
  355. package/src/library/game/tutorial/checks.ts +186 -0
  356. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  357. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  358. package/src/library/game/tutorial/runTutorial.ts +350 -0
  359. package/src/library/game/undo.test.ts +282 -0
  360. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  361. package/src/library/hooks/useTimeController.tsx +10 -2
  362. package/src/library/hooks/useTutorial.tsx +80 -0
  363. package/src/library/index.ts +58 -2
  364. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  365. package/src/library/rendering/ChitGalleryItemInstance.ts +30 -1
  366. package/src/library/rendering/ChitRenderInstance.ts +57 -4
  367. package/src/library/rendering/LightWrapper.ts +10 -1
  368. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  369. package/src/library/rendering/Splay.test.ts +60 -0
  370. package/src/library/rendering/Splay.ts +30 -9
  371. package/src/library/utilities/Annotations.ts +35 -7
  372. package/src/library/utilities/CanvasStack/CanvasStack.ts +6 -1
  373. package/src/library/utilities/CanvasStack/RichTextRenderer.ts +13 -0
  374. package/src/library/utilities/Dice.tsx +5 -1
  375. package/src/library/utilities/GalleryItemConversion.ts +5 -6
  376. package/src/library/utilities/TokenizedText.ts +6 -0
  377. package/src/library/utilities/zIndex.ts +1 -0
@@ -20,8 +20,17 @@ const defaultFindChit: FindChit = () => {
20
20
 
21
21
  type FindChit = (id: string) => Chit;
22
22
 
23
+ /** What a player is trying to do with a prompt; a `PromptGuard` says whether it goes through. */
24
+ export type PromptAction = { type: "pick"; pick: Pick; value: any } | { type: "undo"; fullReset: boolean };
25
+ export type PromptGuard = (action: PromptAction) => boolean;
26
+
23
27
  export abstract class Prompt {
24
28
  public id = "";
29
+ /**
30
+ * Set on the client (see `ClientPrompts.guard`) to vet a player's answers before they are sent: a
31
+ * tutorial lets through only the moves its current step asks for. Not serialized.
32
+ */
33
+ public guard?: PromptGuard;
25
34
  public resolved = false;
26
35
  public clock = 0;
27
36
  public response: any;
@@ -73,6 +82,11 @@ export abstract class Prompt {
73
82
  }
74
83
 
75
84
  stepBack(fullReset: boolean = false) {
85
+ // The guard goes first: a tutorial turns Undo into its own Back, which works even where the
86
+ // engine could not undo (after a draw)
87
+ if (this.guard && !this.guard({ type: "undo", fullReset })) {
88
+ return;
89
+ }
76
90
  if (!this.canReset) {
77
91
  throw new Error("Cannot be stepped back");
78
92
  }
@@ -253,9 +267,18 @@ export class PickPrompt extends Prompt {
253
267
  this._help = details.help;
254
268
  }
255
269
 
256
- resolvePick(pick: Pick, value: any) {
270
+ /** Answers with this pick. Returns false when the answer was not taken (already answered, or refused
271
+ * by the guard), so a drag can put its chit back instead of leaving it on the target. */
272
+ resolvePick(pick: Pick, value: any): boolean {
273
+ if (this.resolved) {
274
+ return false;
275
+ }
276
+ if (this.guard && !this.guard({ type: "pick", pick, value })) {
277
+ return false;
278
+ }
257
279
  const idx = this.picks.indexOf(pick);
258
280
  this.resolve({ idx, value, pickType: pick.type });
281
+ return true;
259
282
  }
260
283
 
261
284
  resolveDetails(resolution: PickResolution) {
@@ -265,7 +288,15 @@ export class PickPrompt extends Prompt {
265
288
 
266
289
  this.resolved = true;
267
290
  const pick = this.picks[resolution.idx];
268
- this.finished = () => pick.resolveDetails(resolution?.value);
291
+ this.finished = () => {
292
+ // A recorded answer replayed against a prompt that has changed (picks added or reordered by
293
+ // a code change) can land on a different pick: the same check a live answer gets
294
+ // (canResolveResponse), so it is a mismatch rather than a crash inside the pick.
295
+ if (!pick || (resolution.pickType && resolution.pickType !== pick.type) || !pick.canResolveResponse(resolution.value)) {
296
+ throw new MismatchError();
297
+ }
298
+ return pick.resolveDetails(resolution.value);
299
+ };
269
300
  }
270
301
 
271
302
  stageIn() {
@@ -39,6 +39,15 @@ export class SparkChit extends Chit {
39
39
  return this.icon;
40
40
  }
41
41
 
42
+ /**
43
+ * Whether a change to this spark, while its panel is out of view, marks the panel as changed (so the layout may
44
+ * slide to it), as `ChitRenderSpec.worthSlidingToPanelToShowChange` does for a chit on the table. Override to
45
+ * return false for a number that changes often during other panels' actions (money earned on every sale).
46
+ */
47
+ public get worthSlidingToPanelToShowChange(): boolean {
48
+ return true;
49
+ }
50
+
42
51
  /** @internal */
43
52
  @NonEditable public element: RefObject<HTMLElement> | undefined;
44
53
 
@@ -93,17 +93,50 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
93
93
  private lockedChitStates: ChitStateLookup = {};
94
94
  private lastChitStates: ChitStateLookup = {};
95
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>();
96
99
  private pendingNewChits = new Set<Chit>();
97
100
  private _statePool?: Map<string, string>;
98
- 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
+ }
99
124
 
100
125
  /**
101
- * Drop any cached serialize() reconstruction on this turn and every ancestor,
102
- * 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.
103
128
  */
104
- private invalidateSerializeCache() {
105
- this._serializeCache = undefined;
106
- 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);
107
140
  }
108
141
 
109
142
  private get statePool(): Map<string, string> {
@@ -200,12 +233,18 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
200
233
  return p.id;
201
234
  });
202
235
 
203
- // 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;
204
239
  Object.values(this.chitLookup).forEach((c) => {
205
240
  if (!c.id) {
206
241
  throw new Error("Cannot serialize a chit without an id");
207
242
  }
208
- 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));
209
248
  });
210
249
  }
211
250
 
@@ -245,17 +284,14 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
245
284
  }
246
285
 
247
286
  /**
248
- * Records what a player is being asked for: the tokenized message for the in-game UI, and a plain-text version
249
- * (player tokens become names, etc.) for anything that can only show text.
287
+ * Records what a player is being asked for, as plain text (player tokens become names, etc.) for match storage,
288
+ * match lists and notifications. The in-game prompt renders its own tokenized message.
250
289
  */
251
290
  private setPromptMessage(player: P, message: string | undefined) {
252
- player.promptStatus.latestPromptMessage = message;
253
- if (message === undefined) {
254
- player.promptStatus.latestPromptMessageText = undefined;
255
- return;
256
- }
257
- const tokenMap = buildTokenMap(this.match.game.tokenMap, this.rootChit.players.map((p) => p));
258
- player.promptStatus.latestPromptMessageText = tokenizedMessageToText(message, tokenMap);
291
+ player.promptStatus.latestPromptMessage =
292
+ message === undefined
293
+ ? undefined
294
+ : tokenizedMessageToText(message, buildTokenMap(this.match.game.tokenMap, this.rootChit.players.map((p) => p)));
259
295
  }
260
296
 
261
297
  /**
@@ -276,6 +312,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
276
312
 
277
313
  const flushStep = step as FlushClockStep;
278
314
  flushStep.log = message;
315
+ this.dropCheckpointsFrom(this.clockSteps.length - 1);
279
316
  }
280
317
 
281
318
  /**
@@ -302,6 +339,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
302
339
  message = message(step.log!);
303
340
  }
304
341
  step.log = message;
342
+ this.dropCheckpointsFrom(lastIndex);
305
343
  }
306
344
 
307
345
  _zipStartPoint = 0;
@@ -330,8 +368,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
330
368
  }
331
369
 
332
370
  if (hasChange) {
333
- // Pops and in-place merges can leave any cached walk pointing into invalid territory.
334
- this.invalidateSerializeCache();
371
+ // The merged step changed in place: checkpoints that include it are stale.
372
+ this.dropCheckpointsFrom(this.clockSteps.length - 1);
335
373
  this.pass++;
336
374
  // No trailing force-flush: it would only push an empty FlushClockStep (no chit
337
375
  // diff, no log) that the client has to walk through for no visual change. The
@@ -401,17 +439,22 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
401
439
  sawChange = true;
402
440
  }
403
441
  }
404
- this.dirtyChitIds.clear();
405
442
 
406
- // 3. Detect deleted chits — orphans in lastChitStates that weren't serialized above
407
- const deletedRoots: Chit[] = [];
408
- for (const id of Object.keys(this.lastChitStates)) {
409
- if (this.lastChitStates[id] === Chit.deletedIfSerialized()) continue;
443
+ // 3. Detect deleted chits — orphans in lastChitStates. Losing a parent marks a chit dirty, so
444
+ // only this flush's dirty chits and the roots of absorbed sub-turns can have become orphans.
445
+ const deletedRoots = new Set<Chit>();
446
+ const checkOrphan = (id: string) => {
447
+ const lastState = this.lastChitStates[id];
448
+ if (lastState === undefined || lastState === Chit.deletedIfSerialized()) return;
410
449
  const chit = this.chitLookup[id];
411
450
  if (chit && !chit.parent && !this.chitsToLock.includes(chit)) {
412
- deletedRoots.push(chit);
451
+ deletedRoots.add(chit);
413
452
  }
414
- }
453
+ };
454
+ this.dirtyChitIds.forEach(checkOrphan);
455
+ this.absorbedRootIds.forEach(checkOrphan);
456
+ this.dirtyChitIds.clear();
457
+ this.absorbedRootIds.clear();
415
458
 
416
459
  for (const chit of deletedRoots) {
417
460
  if (chit.id) {
@@ -436,9 +479,9 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
436
479
  throw new Error("Cannot flush while subturns are active");
437
480
  }
438
481
 
482
+ // Appending leaves every checkpoint valid, ours and our ancestors': theirs stop before the
483
+ // step that holds us until we have been absorbed.
439
484
  this.clockSteps.push(new FlushClockStep(this.clock, newStates));
440
- // Ancestors' caches included our prior contribution; the new step makes them stale.
441
- this.parent?.invalidateSerializeCache();
442
485
  }
443
486
  }
444
487
 
@@ -493,17 +536,19 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
493
536
 
494
537
  this.decisionIndex++;
495
538
 
539
+ let step: SubTurnsClockStep<P, R>;
496
540
  if (this.activeSubTurns.length === 0) {
497
- this.clockSteps.push(new SubTurnsClockStep(this.clock, [turn]));
541
+ step = new SubTurnsClockStep(this.clock, [turn]);
542
+ this.clockSteps.push(step);
498
543
  } else {
499
544
  const lastStep = this.clockSteps[this.clockSteps.length - 1];
500
545
  if (!(lastStep instanceof SubTurnsClockStep)) {
501
546
  throw new Error("Unexpected clocksteps stage");
502
547
  }
503
548
  lastStep.turns.push(turn);
549
+ step = lastStep;
504
550
  }
505
- // Either case mutates a step our own cache (or an ancestor's) may have already walked past.
506
- this.invalidateSerializeCache();
551
+ // Neither case touches a checkpoint: none reaches a step with a turn still to absorb.
507
552
 
508
553
  this.activeSubTurns.push(turn);
509
554
 
@@ -526,6 +571,10 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
526
571
  });
527
572
 
528
573
  this.lastChitStates = { ...this.lastChitStates, ...turn.lastChitStates };
574
+ turn.chitsToLock.forEach((chit) => chit.id && this.absorbedRootIds.add(chit.id));
575
+ // serialize() merges the step's turns in this order, so a chit written by several parallel
576
+ // turns serializes as the engine now holds it.
577
+ step.absorbed.push(turn);
529
578
  turn.releasePostAbsorptionRefs();
530
579
 
531
580
  return result;
@@ -534,8 +583,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
534
583
  /**
535
584
  * Called by the parent right after it has absorbed our `chitLookup` and `lastChitStates`.
536
585
  * After this we will only ever be walked via `serialize` / `chitsHistory` / `gameLog`,
537
- * which only need `clockSteps` and `lockedChitStates` — so drop the heavy per-chit
538
- * bookkeeping to keep finished sub-turns from pinning hundreds of chit references.
586
+ * and only by the parent, which needs nothing of ours but `clockSteps` — so drop the heavy
587
+ * per-chit bookkeeping to keep finished sub-turns from pinning hundreds of chit references.
539
588
  * @internal
540
589
  */
541
590
  private releasePostAbsorptionRefs() {
@@ -544,7 +593,14 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
544
593
  this.lastChitStates = {};
545
594
  this.pendingNewChits.clear();
546
595
  this.dirtyChitIds.clear();
547
- this._serializeCache = undefined;
596
+ this.absorbedRootIds.clear();
597
+ if (!Turn.releaseAbsorbedTurns) return;
598
+ // The locked snapshot and every checkpoint are full copies of the chit map, and a long game
599
+ // has hundreds of finished turns. The parent walks into us with its own map, which at our
600
+ // step holds exactly what the snapshot held, so a finished turn keeps neither.
601
+ this.absorbed = true;
602
+ this.lockedChitStates = {};
603
+ this._checkpoints = [];
548
604
  }
549
605
 
550
606
  public async runParallelTurns<A>(
@@ -821,7 +877,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
821
877
  };
822
878
 
823
879
  // Seed with the initial locked state so chits that never diff in this turn still
824
- // surface their starting form (flush steps now hold diffs only).
880
+ // surface their starting form (flush steps now hold diffs only). A finished turn has no
881
+ // snapshot; the parent already logged that state before walking into it.
825
882
  ids.forEach((id) => {
826
883
  const initial = this.lockedChitStates[id];
827
884
  if (initial !== undefined) {
@@ -846,8 +903,12 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
846
903
  return result;
847
904
  }
848
905
 
849
- /** @internal */
850
- serialize(playerId: string, clock: number): ChitSerializationResponse {
906
+ /**
907
+ * `into` is the parent's working chit map while it walks this turn. A finished turn has no
908
+ * snapshot of its own and writes its diffs straight into it; the parent then needs no merge.
909
+ * @internal
910
+ */
911
+ serialize(playerId: string, clock: number, into?: ChitStateLookup): ChitSerializationResponse {
851
912
  clock = Math.max(0, Math.min(clock, this.playerVisibleClockTime(playerId)));
852
913
 
853
914
  let chits: ChitStateLookup;
@@ -856,24 +917,41 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
856
917
  let resultingClock: number;
857
918
  let index: number;
858
919
 
859
- const cache = this._serializeCache;
860
- if (cache && cache.playerId === playerId && clock >= cache.resultingClock) {
861
- chits = { ...cache.chits };
862
- subTurns = cache.subTurns ? { ...cache.subTurns } : undefined;
863
- log = cache.log ? { ...cache.log } : undefined;
864
- resultingClock = cache.resultingClock;
865
- index = cache.nextIndex;
920
+ // Resume from the furthest checkpoint that ends at or before the target clock
921
+ let checkpoint: SerializeCheckpoint | undefined;
922
+ for (let i = this._checkpoints.length - 1; i >= 0; i--) {
923
+ if (this._checkpoints[i].resultingClock <= clock) {
924
+ checkpoint = this._checkpoints[i];
925
+ break;
926
+ }
927
+ }
928
+ if (checkpoint) {
929
+ chits = { ...checkpoint.chits };
930
+ subTurns = checkpoint.subTurns ? { ...checkpoint.subTurns } : undefined;
931
+ log = checkpoint.log ? { ...checkpoint.log } : undefined;
932
+ resultingClock = checkpoint.resultingClock;
933
+ index = checkpoint.nextIndex;
866
934
  } else {
867
935
  // Diff-replay: seed with the initial locked snapshot and merge every flush diff
868
- // up to (but not including) the target clock.
869
- chits = { ...this.lockedChitStates };
936
+ // up to (but not including) the target clock. A finished turn's snapshot was the parent's
937
+ // map at this step, which is what the parent hands us.
938
+ chits = this.absorbed ? (into ?? {}) : { ...this.lockedChitStates };
870
939
  subTurns = undefined;
871
940
  log = undefined;
872
941
  resultingClock = -1;
873
942
  index = 0;
874
943
  }
875
944
 
876
- let cacheable = true;
945
+ const snapshot = (): SerializeCheckpoint => ({
946
+ nextIndex: index,
947
+ chits: { ...chits },
948
+ subTurns: subTurns ? { ...subTurns } : undefined,
949
+ log: log ? { ...log } : undefined,
950
+ resultingClock: resultingClock === -1 ? clock : resultingClock,
951
+ });
952
+ // True while every step walked is final and was consumed whole, so the walk may be checkpointed
953
+ let checkpointable = Turn.serializeCheckpoints && !this.absorbed;
954
+ let lastCheckpointIndex = index;
877
955
  while (index < this.clockSteps.length) {
878
956
  const clockStep = this.clockSteps[index];
879
957
  if (clockStep.startClock >= clock) break;
@@ -890,13 +968,21 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
890
968
  subTurns = {};
891
969
  resultingClock = clockStep.startClock;
892
970
  let remainingClocksToSpend = clock - clockStep.startClock;
893
- for (const turn of clockStep.visibleTurns(playerId)) {
971
+ // A step every turn of which has been absorbed is final, and asked for in full it reads the
972
+ // same for every player: its turns merge in absorption order, the order their changes
973
+ // landed in `lastChitStates`, so a chit written by two parallel turns serializes as the
974
+ // engine holds it. A step still in motion, or asked for part-way, is walked as this player
975
+ // may see it, and the walk stops there: a later request has to re-walk it.
976
+ const final = clockStep.fullyAbsorbed && clock >= clockStep.endClock();
977
+ for (const turn of final ? clockStep.absorbed : clockStep.visibleTurns(playerId)) {
894
978
  const time = Math.max(remainingClocksToSpend, 0);
895
979
  if (time <= 0) break;
896
980
 
897
981
  // we are going forward so we never want to have a turn go backwards. ever.
898
- const serialized = turn.serialize(playerId, time);
899
- Object.assign(chits, serialized.chits);
982
+ const serialized = turn.serialize(playerId, time, chits);
983
+ if (serialized.chits !== chits) {
984
+ Object.assign(chits, serialized.chits);
985
+ }
900
986
 
901
987
  resultingClock += serialized.clockDetails.clock;
902
988
  remainingClocksToSpend -= serialized.clockDetails.clock;
@@ -905,30 +991,24 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
905
991
  log = { message: serialized.log.message, clock: serialized.log.clock + clockStep.startClock };
906
992
  }
907
993
  }
908
- // We can only advance `index` past this step (and cache from here) if the
909
- // requested `clock` consumed this step's *entire* extent — i.e. every visible
910
- // sub-turn was asked for at least its full clock time. Otherwise a future
911
- // request at a higher `clock` needs to re-ask the sub-turn for more time,
912
- // which means re-processing this same step.
913
- if (clock < clockStep.endClock(playerId)) {
914
- cacheable = false;
994
+ if (!final) {
995
+ checkpointable = false;
915
996
  break;
916
997
  }
917
998
  index++;
918
999
  } else {
919
1000
  index++;
920
1001
  }
1002
+
1003
+ if (checkpointable && index - lastCheckpointIndex >= Turn.serializeCheckpointInterval) {
1004
+ this.addCheckpoint(snapshot());
1005
+ lastCheckpointIndex = index;
1006
+ }
921
1007
  }
922
1008
 
923
- if (cacheable) {
924
- this._serializeCache = {
925
- playerId,
926
- nextIndex: index,
927
- chits: { ...chits },
928
- subTurns: subTurns ? { ...subTurns } : undefined,
929
- log: log ? { ...log } : undefined,
930
- resultingClock: resultingClock === -1 ? clock : resultingClock,
931
- };
1009
+ // Remember where this walk ended, so a request for a later clock continues from here
1010
+ if (checkpointable && index > lastCheckpointIndex) {
1011
+ this.addCheckpoint(snapshot());
932
1012
  }
933
1013
 
934
1014
  return {
@@ -1202,8 +1282,34 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1202
1282
  return result;
1203
1283
  }
1204
1284
 
1285
+ /**
1286
+ * Takes every chit this turn made (and those a sub-turn still running under it made) off the board,
1287
+ * ahead of a parent's restart. The parent never absorbed us, so its own reset knows nothing of them:
1288
+ * left alone they would stay on the board, and the next sub-turn would lock them as if they had
1289
+ * always been there. Chits we only changed are the parent's to restore.
1290
+ */
1291
+ private discardCreatedChits() {
1292
+ this.activeSubTurns.forEach((t) => t.discardCreatedChits());
1293
+ for (const chit of Object.values(this.chitLookup)) {
1294
+ if (chit.id && this.lockedChitStates[chit.id] === undefined) {
1295
+ chit.forgetFallbackUnlessHidden();
1296
+ chit.removeFromParent();
1297
+ }
1298
+ }
1299
+ for (const chit of this.pendingNewChits) {
1300
+ if (!chit.id) {
1301
+ chit.forgetFallbackUnlessHidden();
1302
+ chit.removeFromParent();
1303
+ }
1304
+ }
1305
+ this.pendingNewChits.clear();
1306
+ }
1307
+
1205
1308
  private restartExecution() {
1206
- this.activeSubTurns.forEach((t) => t.destroy());
1309
+ this.activeSubTurns.forEach((t) => {
1310
+ t.discardCreatedChits();
1311
+ t.destroy();
1312
+ });
1207
1313
 
1208
1314
  const chits = Object.values(this.chitLookup).filter((chit) => chit.id);
1209
1315
 
@@ -1216,6 +1322,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1216
1322
  if (lockedState) {
1217
1323
  chit.deserialize(lockedState, this.findChit);
1218
1324
  } else {
1325
+ chit.forgetFallbackUnlessHidden(); // a chit made to come from another piece must not linger beside it
1219
1326
  chit.removeFromParent(); // effectively "deletes" it. In practice, the `fn` will recreate a new chit which will have the new ID, which replaces this one.
1220
1327
  }
1221
1328
  });
@@ -1235,6 +1342,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1235
1342
 
1236
1343
  this.lastChitStates = { ...this.lockedChitStates }; // reset our known chit states
1237
1344
  this.dirtyChitIds.clear();
1345
+ this.absorbedRootIds.clear();
1238
1346
  this.pendingNewChits.clear();
1239
1347
  // chits were deserialized back to locked state — mark them clean so future
1240
1348
  // modifications correctly trigger markDirty() → notifyChitDirty()
@@ -1247,7 +1355,7 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1247
1355
  this.unresolvedPrompt = undefined;
1248
1356
  this.activeSubTurns = [];
1249
1357
  this.pass++;
1250
- this.invalidateSerializeCache();
1358
+ this._checkpoints = [];
1251
1359
  }
1252
1360
  }
1253
1361
 
@@ -1258,8 +1366,8 @@ export class Turn<T, P extends PlayerChit, R extends RootChit<P>> {
1258
1366
  type ChitLookup = { [id: string]: Chit };
1259
1367
  type ChitStateLookup = { [id: string]: string };
1260
1368
 
1261
- type SerializeCache = {
1262
- playerId: string;
1369
+ /** serialize()'s replay captured after `nextIndex` steps; see Turn._checkpoints */
1370
+ type SerializeCheckpoint = {
1263
1371
  nextIndex: number;
1264
1372
  chits: ChitStateLookup;
1265
1373
  subTurns?: { [turnId: string]: ClockDetails };
@@ -1273,6 +1381,13 @@ abstract class ClockStep {
1273
1381
  }
1274
1382
 
1275
1383
  class SubTurnsClockStep<P extends PlayerChit, R extends RootChit<P>> extends ClockStep {
1384
+ /** The turns the parent has absorbed, in that order: the order their changes landed in its state */
1385
+ public absorbed: Turn<any, P, R>[] = [];
1386
+
1387
+ get fullyAbsorbed() {
1388
+ return this.absorbed.length === this.turns.length;
1389
+ }
1390
+
1276
1391
  visibleTurns(playerId?: string) {
1277
1392
  if (this.turns.length === 1 || playerId === undefined) {
1278
1393
  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";
@@ -30,9 +38,24 @@ export class TurnState {
30
38
  private parentTurnState: TurnState | undefined;
31
39
  private parentTurnIndex = 0;
32
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
+
33
56
  toJSON() {
34
57
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
35
- const { parentTurnIndex, parentTurnState, ...rest } = this;
58
+ const { parentTurnIndex, parentTurnState, rngSource, ...rest } = this;
36
59
  return rest;
37
60
  }
38
61
 
@@ -75,7 +98,7 @@ export class TurnState {
75
98
  }
76
99
  return (result as RngResponse).value[0];
77
100
  } else if (index === this.decisions.length) {
78
- const rng = Math.random();
101
+ const rng = this.draw(1)[0];
79
102
  this.decisions.push({
80
103
  type: "rng",
81
104
  value: [rng],
@@ -94,7 +117,7 @@ export class TurnState {
94
117
  }
95
118
  return (result as RngResponse).value;
96
119
  } else if (index === this.decisions.length) {
97
- const rngs = Array.from({ length: count }, () => Math.random());
120
+ const rngs = this.draw(count);
98
121
  this.decisions.push({
99
122
  type: "rng",
100
123
  value: rngs,
@@ -194,6 +194,16 @@ Narrow on `opt.kind` before using `chit`, `target` or `button`, then cast to you
194
194
  the best.
195
195
  - **Untagged options in the same prompt score 0.** Keep that in mind when choosing your scale.
196
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
+
197
207
  ## Step 4 — Hidden information
198
208
 
199
209
  The default view is the live board: the bot *could* read other hands, deck order, and other