@pretty-chitty/core 2.0.0 → 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 (318) 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 +30 -2
  13. package/dist/components/DemoWrapper.d.ts.map +1 -1
  14. package/dist/components/DemoWrapper.js +79 -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 +6 -2
  20. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  21. package/dist/components/Gallery/BuiltItem.js +28 -9
  22. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  23. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  24. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  25. package/dist/components/Gallery/GalleryController.js +67 -0
  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 +48 -10
  30. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  31. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  32. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  33. package/dist/components/Gallery/LayoutManager.js +23 -3
  34. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  35. package/dist/components/Gallery/constants.d.ts +2 -0
  36. package/dist/components/Gallery/constants.d.ts.map +1 -1
  37. package/dist/components/Gallery/constants.js +2 -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/GameDesigner.d.ts.map +1 -1
  44. package/dist/components/GameDesigner.js +42 -10
  45. package/dist/components/GameDesigner.js.map +1 -1
  46. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  47. package/dist/components/InlineGalleryDisplay.js +2 -2
  48. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  49. package/dist/components/LiveButton.d.ts.map +1 -1
  50. package/dist/components/LiveButton.js +5 -2
  51. package/dist/components/LiveButton.js.map +1 -1
  52. package/dist/components/MatchViewer.d.ts +6 -1
  53. package/dist/components/MatchViewer.d.ts.map +1 -1
  54. package/dist/components/MatchViewer.js +9 -3
  55. package/dist/components/MatchViewer.js.map +1 -1
  56. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  57. package/dist/components/Panel/MultiPanel.js +18 -0
  58. package/dist/components/Panel/MultiPanel.js.map +1 -1
  59. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  60. package/dist/components/Panel/PanelContents.js +92 -23
  61. package/dist/components/Panel/PanelContents.js.map +1 -1
  62. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  63. package/dist/components/Panel/PanelTabStack.js +1 -1
  64. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  65. package/dist/components/PanelSpark.d.ts.map +1 -1
  66. package/dist/components/PanelSpark.js +3 -2
  67. package/dist/components/PanelSpark.js.map +1 -1
  68. package/dist/components/Playground.d.ts.map +1 -1
  69. package/dist/components/Playground.js +10 -4
  70. package/dist/components/Playground.js.map +1 -1
  71. package/dist/components/PromptControls.d.ts.map +1 -1
  72. package/dist/components/PromptControls.js +4 -2
  73. package/dist/components/PromptControls.js.map +1 -1
  74. package/dist/components/SparkLineChart.d.ts.map +1 -1
  75. package/dist/components/SparkLineChart.js +22 -26
  76. package/dist/components/SparkLineChart.js.map +1 -1
  77. package/dist/components/TimeControlBar.d.ts.map +1 -1
  78. package/dist/components/TimeControlBar.js +5 -3
  79. package/dist/components/TimeControlBar.js.map +1 -1
  80. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  81. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  82. package/dist/components/TokenizedMarkdown.js +144 -0
  83. package/dist/components/TokenizedMarkdown.js.map +1 -0
  84. package/dist/components/TokenizedMessage.d.ts +6 -0
  85. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  86. package/dist/components/TokenizedMessage.js +20 -19
  87. package/dist/components/TokenizedMessage.js.map +1 -1
  88. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  89. package/dist/components/TopBarPlayers.js +1 -1
  90. package/dist/components/TopBarPlayers.js.map +1 -1
  91. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  92. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  93. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  94. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  95. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  96. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  97. package/dist/components/Tutorial/TutorialBox.js +239 -0
  98. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  100. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  102. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  104. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  106. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  107. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  108. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  109. package/dist/components/Tutorial/targetRects.js +241 -0
  110. package/dist/components/Tutorial/targetRects.js.map +1 -0
  111. package/dist/game/Chit.d.ts +7 -0
  112. package/dist/game/Chit.d.ts.map +1 -1
  113. package/dist/game/Chit.js +20 -5
  114. package/dist/game/Chit.js.map +1 -1
  115. package/dist/game/ClientTimeState.d.ts +14 -0
  116. package/dist/game/ClientTimeState.d.ts.map +1 -1
  117. package/dist/game/ClientTimeState.js +17 -0
  118. package/dist/game/ClientTimeState.js.map +1 -1
  119. package/dist/game/Game.d.ts +6 -0
  120. package/dist/game/Game.d.ts.map +1 -1
  121. package/dist/game/GameTheme.d.ts +3 -0
  122. package/dist/game/GameTheme.d.ts.map +1 -1
  123. package/dist/game/GameTheme.js +2 -0
  124. package/dist/game/GameTheme.js.map +1 -1
  125. package/dist/game/Match.d.ts +8 -2
  126. package/dist/game/Match.d.ts.map +1 -1
  127. package/dist/game/Match.js +4 -1
  128. package/dist/game/Match.js.map +1 -1
  129. package/dist/game/Pick.d.ts +2 -0
  130. package/dist/game/Pick.d.ts.map +1 -1
  131. package/dist/game/Pick.js +17 -1
  132. package/dist/game/Pick.js.map +1 -1
  133. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  134. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  135. package/dist/game/PlayerPromptStatusChit.js +5 -1
  136. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  137. package/dist/game/Prompt.d.ts +15 -0
  138. package/dist/game/Prompt.d.ts.map +1 -1
  139. package/dist/game/Prompt.js +16 -0
  140. package/dist/game/Prompt.js.map +1 -1
  141. package/dist/game/Turn.d.ts +15 -4
  142. package/dist/game/Turn.d.ts.map +1 -1
  143. package/dist/game/Turn.js +173 -60
  144. package/dist/game/Turn.js.map +1 -1
  145. package/dist/game/TurnState.d.ts +12 -1
  146. package/dist/game/TurnState.d.ts.map +1 -1
  147. package/dist/game/TurnState.js +15 -3
  148. package/dist/game/TurnState.js.map +1 -1
  149. package/dist/game/ai/AiClientPrompts.d.ts +20 -3
  150. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -1
  151. package/dist/game/ai/AiClientPrompts.js +42 -6
  152. package/dist/game/ai/AiClientPrompts.js.map +1 -1
  153. package/dist/game/ai/AiPlayerView.js +2 -0
  154. package/dist/game/ai/AiPlayerView.js.map +1 -1
  155. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  156. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  157. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  158. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  159. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  160. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  161. package/dist/game/clientTransport/ClientTime.js +51 -11
  162. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  163. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  164. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  165. package/dist/game/tutorial/TutorialController.js +1182 -0
  166. package/dist/game/tutorial/TutorialController.js.map +1 -0
  167. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  168. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  169. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  170. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  171. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  172. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  173. package/dist/game/tutorial/TutorialTheme.js +39 -0
  174. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  175. package/dist/game/tutorial/allowed.d.ts +2 -0
  176. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  177. package/dist/game/tutorial/allowed.js +119 -0
  178. package/dist/game/tutorial/allowed.js.map +1 -0
  179. package/dist/game/tutorial/checks.d.ts +58 -0
  180. package/dist/game/tutorial/checks.d.ts.map +1 -0
  181. package/dist/game/tutorial/checks.js +144 -0
  182. package/dist/game/tutorial/checks.js.map +1 -0
  183. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  184. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  185. package/dist/game/tutorial/createDemoMatch.js +67 -0
  186. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  187. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  188. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  189. package/dist/game/tutorial/defineTutorial.js +86 -0
  190. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  191. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  192. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  193. package/dist/game/tutorial/runTutorial.js +273 -0
  194. package/dist/game/tutorial/runTutorial.js.map +1 -0
  195. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  196. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  197. package/dist/hooks/usePanelNavigation.js +36 -0
  198. package/dist/hooks/usePanelNavigation.js.map +1 -0
  199. package/dist/hooks/useTimeController.d.ts +2 -1
  200. package/dist/hooks/useTimeController.d.ts.map +1 -1
  201. package/dist/hooks/useTimeController.js +6 -2
  202. package/dist/hooks/useTimeController.js.map +1 -1
  203. package/dist/hooks/useTutorial.d.ts +48 -0
  204. package/dist/hooks/useTutorial.d.ts.map +1 -0
  205. package/dist/hooks/useTutorial.js +16 -0
  206. package/dist/hooks/useTutorial.js.map +1 -0
  207. package/dist/index.d.ts +36 -0
  208. package/dist/index.d.ts.map +1 -1
  209. package/dist/index.html +12 -0
  210. package/dist/index.js +19 -2
  211. package/dist/index.js.map +1 -1
  212. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  213. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  214. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  215. package/dist/pretty-chitty.js +204513 -0
  216. package/dist/pretty-chitty.js.map +1 -0
  217. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  218. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  219. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  220. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  221. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  222. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  223. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  224. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  225. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  226. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  227. package/dist/rendering/ChitRenderInstance.js +28 -0
  228. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  229. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  230. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  231. package/dist/rendering/RootChitRenderInstance.js +29 -0
  232. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  233. package/dist/utilities/Annotations.d.ts +15 -0
  234. package/dist/utilities/Annotations.d.ts.map +1 -1
  235. package/dist/utilities/Annotations.js +31 -7
  236. package/dist/utilities/Annotations.js.map +1 -1
  237. package/dist/utilities/CanvasStack/CanvasStack.d.ts +2 -0
  238. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  239. package/dist/utilities/CanvasStack/CanvasStack.js +4 -0
  240. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  241. package/dist/utilities/TokenizedText.d.ts +6 -0
  242. package/dist/utilities/TokenizedText.d.ts.map +1 -1
  243. package/dist/utilities/TokenizedText.js.map +1 -1
  244. package/dist/utilities/zIndex.d.ts +1 -0
  245. package/dist/utilities/zIndex.d.ts.map +1 -1
  246. package/dist/utilities/zIndex.js +1 -0
  247. package/dist/utilities/zIndex.js.map +1 -1
  248. package/package.json +3 -2
  249. package/src/library/components/ActionLogDisplay.tsx +1 -0
  250. package/src/library/components/BottomBarButton.tsx +5 -0
  251. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  252. package/src/library/components/DemoWrapper.tsx +147 -44
  253. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  254. package/src/library/components/Gallery/BuiltItem.ts +30 -9
  255. package/src/library/components/Gallery/GalleryController.ts +72 -1
  256. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  257. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  258. package/src/library/components/Gallery/constants.ts +2 -0
  259. package/src/library/components/Gallery/registry.ts +44 -0
  260. package/src/library/components/GameDesigner.tsx +121 -12
  261. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  262. package/src/library/components/LiveButton.tsx +8 -5
  263. package/src/library/components/MatchViewer.tsx +14 -3
  264. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  265. package/src/library/components/Panel/PanelContents.tsx +70 -1
  266. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  267. package/src/library/components/PanelSpark.tsx +9 -4
  268. package/src/library/components/Playground.tsx +48 -21
  269. package/src/library/components/PromptControls.tsx +7 -3
  270. package/src/library/components/SparkLineChart.tsx +23 -27
  271. package/src/library/components/TimeControlBar.tsx +5 -3
  272. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  273. package/src/library/components/TokenizedMessage.tsx +28 -32
  274. package/src/library/components/TopBarPlayers.tsx +12 -9
  275. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  276. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  277. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  278. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  279. package/src/library/components/Tutorial/targetRects.ts +273 -0
  280. package/src/library/game/Chit.ts +21 -5
  281. package/src/library/game/ClientTimeState.ts +18 -0
  282. package/src/library/game/Game.ts +7 -0
  283. package/src/library/game/GameTheme.ts +4 -0
  284. package/src/library/game/Match.ts +12 -2
  285. package/src/library/game/Pick.ts +16 -1
  286. package/src/library/game/PlayerPromptStatusChit.ts +5 -1
  287. package/src/library/game/Prompt.ts +20 -0
  288. package/src/library/game/Turn.ts +179 -61
  289. package/src/library/game/TurnState.ts +26 -3
  290. package/src/library/game/ai/AI_GUIDE.md +10 -0
  291. package/src/library/game/ai/AiClientPrompts.ts +60 -11
  292. package/src/library/game/ai/AiPlayerView.ts +2 -0
  293. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  294. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  295. package/src/library/game/serialize.test.ts +275 -0
  296. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  297. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  298. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  299. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  300. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  301. package/src/library/game/tutorial/allowed.ts +145 -0
  302. package/src/library/game/tutorial/checks.ts +186 -0
  303. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  304. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  305. package/src/library/game/tutorial/runTutorial.ts +331 -0
  306. package/src/library/game/undo.test.ts +282 -0
  307. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  308. package/src/library/hooks/useTimeController.tsx +6 -2
  309. package/src/library/hooks/useTutorial.tsx +76 -0
  310. package/src/library/index.ts +57 -2
  311. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  312. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  313. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  314. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  315. package/src/library/utilities/Annotations.ts +35 -7
  316. package/src/library/utilities/CanvasStack/CanvasStack.ts +6 -1
  317. package/src/library/utilities/TokenizedText.ts +6 -0
  318. package/src/library/utilities/zIndex.ts +1 -0
@@ -3,7 +3,7 @@ import { ClockDetails, samePasses } from "../ClockDetails";
3
3
  import { Connection } from "../Connection";
4
4
  import { ConnectionObject } from "../ConnectionObject";
5
5
  import { PlayerChit } from "../PlayerChit";
6
- import { Prompt, PromptSerialization } from "../Prompt";
6
+ import { PickPrompt, Prompt, PromptAction, PromptSerialization } from "../Prompt";
7
7
  import { RootChit } from "../RootChit";
8
8
  import { ServerPrompts } from "../serverTransport/ServerPrompts";
9
9
  import { ClientTime } from "./ClientTime";
@@ -13,6 +13,20 @@ export class ClientPrompts<P extends PlayerChit, R extends RootChit<P>> extends
13
13
  private serverPrompts: ServerPrompts<P, R>;
14
14
  public currentPrompt = new EventChannel<Prompt | undefined>(undefined);
15
15
 
16
+ /**
17
+ * Vets the player's answers before they are sent. Undefined (the default) lets everything through.
18
+ * A tutorial sets this so only the moves its current step asks for go through; everything else
19
+ * is dropped and `blocked` fires so the UI can say so.
20
+ */
21
+ public guard?: (prompt: PickPrompt, action: PromptAction) => boolean | "handled";
22
+ /**
23
+ * Replaces what Undo does while set (a tutorial maps it to its Back). Whether Undo is offered does
24
+ * not change: it still shows only when the current prompt can be undone.
25
+ */
26
+ public undoOverride = new EventChannel<{ undo: () => void } | undefined>(undefined);
27
+ /** Fires with the attempted action each time the guard drops one */
28
+ public blocked = new EventChannel<{ prompt: PickPrompt; action: PromptAction; at: number } | undefined>(undefined);
29
+
16
30
  private _currentPromptSpec?: PromptSerialization;
17
31
 
18
32
  constructor(
@@ -40,6 +54,22 @@ export class ClientPrompts<P extends PlayerChit, R extends RootChit<P>> extends
40
54
  private stageInPrompt(promptSpec: PromptSerialization) {
41
55
  this._currentPromptSpec = promptSpec;
42
56
  const prompt = Prompt.deserialize(promptSpec, this.clientTime.findChit, this.clientTime.game.buttonLibrary);
57
+ if (prompt instanceof PickPrompt) {
58
+ prompt.guard = (action) => {
59
+ if (!this.guard) {
60
+ return true;
61
+ }
62
+ const verdict = this.guard(prompt, action);
63
+ if (verdict === true) {
64
+ return true;
65
+ }
66
+ if (verdict === false) {
67
+ this.blocked.value = { prompt, action, at: Date.now() };
68
+ }
69
+ // "handled": the guard did something else with it (a tutorial's Undo is its Back)
70
+ return false;
71
+ };
72
+ }
43
73
  prompt.onResolve(async (success) => {
44
74
  try {
45
75
  this.fixActiveLog();
@@ -27,15 +27,11 @@ export class ClientTime extends ConnectionObject {
27
27
  this.register(this.clientTimeState.targetClock.on(() => this.processNewTargetClock()));
28
28
  this.register(
29
29
  this.clientTimeState.isWaitingOnAnimations.on((isWaiting) => {
30
- if (
31
- !isWaiting &&
32
- this.clientTimeState.live.value &&
33
- this.clientTimeState.targetClock.value < this.maxClock.value.clock
34
- ) {
35
- this.clientTimeState.targetClock.value++;
36
- }
30
+ if (!isWaiting) this.playOn();
37
31
  }),
38
32
  );
33
+ // A hold that is raised or lifted lets the board carry on from where it stopped
34
+ this.register(this.clientTimeState.timelineHold.on(() => this.playOn(), false));
39
35
 
40
36
  this.clientTimeState.animationSpeedMultiplier.value =
41
37
  parseFloat(localStorage["animationSpeedMultiplier"] ?? "1") || 1;
@@ -89,7 +85,9 @@ export class ClientTime extends ConnectionObject {
89
85
  if (this.clientTimeState.targetClock.value <= newTime || newTime === 0) {
90
86
  this.clientTimeState.isLoading.value = true;
91
87
 
92
- if (!this.clientTimeState.skipReplay.value) {
88
+ const skip = this.clientTimeState.skipReplay.value || this.clientTimeState.skipInitialReplay;
89
+ this.clientTimeState.skipInitialReplay = false;
90
+ if (!skip) {
93
91
  this.startTime = newTime;
94
92
  this.clientTimeState.targetClock.value = newTime;
95
93
  } else {
@@ -98,6 +96,22 @@ export class ClientTime extends ConnectionObject {
98
96
  }
99
97
  }
100
98
 
99
+ /** The furthest clock the board may play to right now (the game's latest, or a tutorial's hold) */
100
+ private get playableClock() {
101
+ return this.clientTimeState.playableClock(this.maxClock.value.clock);
102
+ }
103
+
104
+ /** Moves the board one clock on, if it is live, idle and allowed further */
105
+ private playOn() {
106
+ if (
107
+ !this.clientTimeState.isWaitingOnAnimations.value &&
108
+ this.clientTimeState.live.value &&
109
+ this.clientTimeState.targetClock.value < this.playableClock
110
+ ) {
111
+ this.clientTimeState.targetClock.value++;
112
+ }
113
+ }
114
+
101
115
  public async newMaxClock(newMaxClock: ClockDetails) {
102
116
  const oldClock = this.maxClock.value;
103
117
  const isSamePass = samePasses(oldClock, newMaxClock);
@@ -110,15 +124,15 @@ export class ClientTime extends ConnectionObject {
110
124
  if (this.clientTimeState.live.value || !isSamePass) {
111
125
  if (
112
126
  !this.clientTimeState.isWaitingOnAnimations.value &&
113
- this.clientTimeState.targetClock.value < this.maxClock.value.clock
127
+ this.clientTimeState.targetClock.value < this.playableClock
114
128
  ) {
115
129
  this.clientTimeState.targetClock.value++;
116
130
  } else if (!isSamePass && !this.clientTimeState.isWaitingOnAnimations.value) {
117
- this.clientTimeState.targetClock.value = this.maxClock.value.clock;
131
+ this.clientTimeState.targetClock.value = this.playableClock;
118
132
  this.processNewTargetClock();
119
133
  } else if (!this.clientTimeState.isWaitingOnAnimations.value) {
120
134
  // some other use has reset...
121
- this.clientTimeState.targetClock.value = this.maxClock.value.clock;
135
+ this.clientTimeState.targetClock.value = this.playableClock;
122
136
  } else {
123
137
  this.processNewTargetClock();
124
138
  }
@@ -135,8 +149,9 @@ export class ClientTime extends ConnectionObject {
135
149
  const newTargetClock = this.clientTimeState.targetClock.value;
136
150
  const currentClock = this.currentClock.value;
137
151
 
138
- if (newTargetClock > this.maxClock.value.clock) {
139
- this.clientTimeState.targetClock.value = this.maxClock.value.clock;
152
+ if (newTargetClock > this.playableClock) {
153
+ // past the game's latest clock, or past a tutorial's hold (the Live and Forward buttons too)
154
+ this.clientTimeState.targetClock.value = this.playableClock;
140
155
  return;
141
156
  }
142
157
  if (newTargetClock < 1) {
@@ -175,6 +190,8 @@ export class ClientTime extends ConnectionObject {
175
190
 
176
191
  Object.values(this.chitLookup).forEach((chit) => {
177
192
  if (chit.id && !serializedChits[chit.id]) {
193
+ // Back into its bag if it came from one; otherwise gone, as a visible fallback would keep it drawn
194
+ chit.forgetFallbackUnlessHidden();
178
195
  if (chit.parentFallback) {
179
196
  chit.beginDeserializing();
180
197
  chit.setParent(chit.parentFallback, chit.parentOutlet ?? "graveyard");
@@ -225,6 +242,30 @@ export class ClientTime extends ConnectionObject {
225
242
  }
226
243
  }
227
244
 
245
+ /**
246
+ * Changes a chit in this client's view only: `change` sets properties on the local copy and the
247
+ * renderer picks it up (and animates it) like any change from the server. The server never hears
248
+ * of it. A later server change to the same chit overwrites it; `restoreChit` puts it back sooner.
249
+ * For tutorials and demos (a card flipping over while the narration talks about it).
250
+ */
251
+ public poseChit(chit: Chit, change: (chit: Chit) => void) {
252
+ chit.beginDeserializing();
253
+ try {
254
+ change(chit);
255
+ } finally {
256
+ chit.doneDeserializing();
257
+ }
258
+ }
259
+
260
+ /** Puts a chit's properties back to the server's state for the moment on screen, undoing `poseChit`. */
261
+ public restoreChit(chit: Chit) {
262
+ const value = chit.id ? this.lastSerializedState[chit.id] : undefined;
263
+ if (!value) return;
264
+ chit.beginDeserializing();
265
+ chit.deserialize(value, this.findChit, true);
266
+ chit.doneDeserializing();
267
+ }
268
+
228
269
  public async chitHistory(chits: Chit[]) {
229
270
  const sparkHistory = await this.serverTime.chitHistory(chits.map((s) => s.id!));
230
271
  const result: { [id: string]: { clock: number; chit: Chit }[] } = {};
@@ -0,0 +1,275 @@
1
+ import { describe, expect, test } from "vitest";
2
+
3
+ import { Chit } from "./Chit";
4
+ import { Game } from "./Game";
5
+ import { GameButton } from "./GameButton";
6
+ import { Match } from "./Match";
7
+ import { EphemeralMatchStorage } from "./MatchStorage";
8
+ import { OrderedOutlet } from "./OrderedOutlet";
9
+ import { PlayerChit } from "./PlayerChit";
10
+ import { PlayerInfo } from "./PlayerInfo";
11
+ import { RootChit } from "./RootChit";
12
+ import { Turn } from "./Turn";
13
+ import { connectAiPlayer } from "./ai/connectAiPlayer";
14
+
15
+ //
16
+ // A small game that exercises every kind of clock step: sequential sub-turns, parallel sub-turns,
17
+ // flushes with and without logs, amended logs and zips. Bots play it at random.
18
+ //
19
+
20
+ class Card extends Chit {
21
+ value = 0;
22
+ }
23
+
24
+ class Seat extends PlayerChit {
25
+ score = 0;
26
+ ready = 0;
27
+ hand = new OrderedOutlet<Card>("hand", this);
28
+ }
29
+
30
+ class Table extends RootChit<Seat> {
31
+ minPlayers = 2;
32
+ lastMover = "";
33
+ market = new OrderedOutlet<Card>("market", this);
34
+ }
35
+
36
+ class ChoiceButton extends GameButton {
37
+ label = "Choice";
38
+ }
39
+
40
+ function tableGame(rounds: number): Game<Seat, Table> {
41
+ return {
42
+ chitLibrary: { Root: Table, Player: Seat, Table, Seat, Card },
43
+ buttonLibrary: { ChoiceButton },
44
+ canvasLibrary: {},
45
+ async run(setup: Turn<any, Seat, Table>, root: Table) {
46
+ const players = root.players.copy();
47
+ for (let i = 0; i < 30; i++) {
48
+ root.market.add(new Card().set((c) => (c.value = i)));
49
+ }
50
+ setup.flush();
51
+ setup.log("setup");
52
+
53
+ for (let round = 0; round < rounds; round++) {
54
+ for (const player of players) {
55
+ await setup.createTurn([root], player, async (turn) => {
56
+ const take = Chit.pick(root.market, async (c: Card) => {
57
+ player.hand.add(c);
58
+ player.score += c.value;
59
+ root.lastMover = player.id ?? "";
60
+ }).message("take a card");
61
+ const pass = new ChoiceButton(() => {
62
+ root.lastMover = player.id ?? "";
63
+ })
64
+ .pick()
65
+ .message("pass");
66
+ await turn.pick([take, pass]);
67
+ turn.log(`${player.id} moved`);
68
+ turn.zip();
69
+ });
70
+ }
71
+ setup.amendLog((previous) => `${previous} (round ${round})`);
72
+
73
+ await setup.runParallelTurns(
74
+ players,
75
+ (p) => [p],
76
+ async (player, turn) => {
77
+ const ready = new ChoiceButton(() => {
78
+ player.ready += 1;
79
+ })
80
+ .pick()
81
+ .message("ready");
82
+ const wait = new ChoiceButton(() => {
83
+ player.ready += 2;
84
+ })
85
+ .pick()
86
+ .message("wait");
87
+ await turn.pick([ready, wait]);
88
+ turn.log(`${player.id} ready`);
89
+ },
90
+ );
91
+ setup.log(`round ${round} done`);
92
+ }
93
+ return { winners: [players[0]] };
94
+ },
95
+ } as unknown as Game<Seat, Table>;
96
+ }
97
+
98
+ // Private engine structure the test reaches into
99
+ type AnyTurn = {
100
+ clockSteps: { turns?: AnyTurn[]; absorbed?: AnyTurn[] }[];
101
+ _checkpoints: { nextIndex: number }[];
102
+ lockedChitStates: Record<string, string>;
103
+ absorbed: boolean;
104
+ serialize: (playerId: string, clock: number) => { chits: Record<string, string> };
105
+ chitsHistory: (playerId: string, ids: string[]) => unknown;
106
+ playerVisibleClockTime: (playerId: string) => number;
107
+ };
108
+
109
+ function allTurns(turn: AnyTurn): AnyTurn[] {
110
+ const result = [turn];
111
+ for (const step of turn.clockSteps) {
112
+ for (const sub of step.turns ?? []) {
113
+ result.push(...allTurns(sub));
114
+ }
115
+ }
116
+ return result;
117
+ }
118
+
119
+ /** Every turn in the tree its parent has absorbed */
120
+ function finishedTurns(root: AnyTurn): AnyTurn[] {
121
+ return allTurns(root).flatMap((t) => t.clockSteps.flatMap((s) => s.absorbed ?? []));
122
+ }
123
+
124
+ /** Runs `fn` as if every finished turn had released its snapshot and checkpoints at absorption. */
125
+ function withReleasedTurns<T>(root: AnyTurn, fn: () => T): T {
126
+ const turns = finishedTurns(root);
127
+ const saved = turns.map((t) => ({ locked: t.lockedChitStates, checkpoints: t._checkpoints, absorbed: t.absorbed }));
128
+ turns.forEach((t) => {
129
+ t.lockedChitStates = {};
130
+ t._checkpoints = [];
131
+ t.absorbed = true;
132
+ });
133
+ try {
134
+ return fn();
135
+ } finally {
136
+ turns.forEach((t, i) => {
137
+ t.lockedChitStates = saved[i].locked;
138
+ t._checkpoints = saved[i].checkpoints;
139
+ t.absorbed = saved[i].absorbed;
140
+ });
141
+ }
142
+ }
143
+
144
+ /** Runs `fn` with every checkpoint in the tree hidden and none created: a replay from the snapshots. */
145
+ function withoutCheckpoints<T>(root: AnyTurn, fn: () => T): T {
146
+ const turns = allTurns(root);
147
+ const saved = turns.map((t) => t._checkpoints);
148
+ turns.forEach((t) => (t._checkpoints = []));
149
+ Turn.serializeCheckpoints = false;
150
+ try {
151
+ return fn();
152
+ } finally {
153
+ Turn.serializeCheckpoints = true;
154
+ turns.forEach((t, i) => (t._checkpoints = saved[i]));
155
+ }
156
+ }
157
+
158
+ // `pass` is wall-clock based; everything else must match exactly
159
+ function comparable(response: unknown): string {
160
+ return JSON.stringify(response, (key, value) => (key === "pass" ? undefined : value));
161
+ }
162
+
163
+ const PLAYERS = [0, 1, 2].map((i) => new PlayerInfo(`p${i}`, `Bot ${i}`));
164
+
165
+ /** Plays the game with seeded bots, calling `onChange(root)` at every match change, and returns the root turn. */
166
+ async function play(onChange: (root: AnyTurn) => void): Promise<AnyTurn> {
167
+ const match = new Match(tableGame(6), PLAYERS, new EphemeralMatchStorage("serialize"), {});
168
+ await match.load();
169
+ const bots = PLAYERS.map((p) => connectAiPlayer(match, p.id, { log: false, seed: 1 }));
170
+ match.onChange(() => {
171
+ const root = match.turn.value as unknown as AnyTurn | undefined;
172
+ if (root) onChange(root);
173
+ }, false);
174
+ await match.start();
175
+ bots.forEach((b) => b.dispose());
176
+ const root = match.turn.value as unknown as AnyTurn;
177
+ match.dispose();
178
+ return root;
179
+ }
180
+
181
+ /**
182
+ * Compares two ways of reading the match for every player at every clock, forwards like a client
183
+ * playing the timeline, then backwards like one scrubbing it, and the history of every chit.
184
+ * Returns the readings that differed.
185
+ */
186
+ function compareEveryReading(
187
+ root: AnyTurn,
188
+ read: (fn: () => string) => [expected: string, actual: string],
189
+ counter: { checks: number },
190
+ ): string[] {
191
+ const mismatches: string[] = [];
192
+ const check = (label: string, fn: () => string) => {
193
+ const [expected, actual] = read(fn);
194
+ counter.checks++;
195
+ if (expected !== actual) mismatches.push(label);
196
+ };
197
+ for (const p of PLAYERS) {
198
+ const max = root.playerVisibleClockTime(p.id);
199
+ const clocks = [...Array(max).keys()].map((c) => c + 1);
200
+ for (const clock of [...clocks, ...clocks.reverse()]) {
201
+ check(`${p.id}@${clock}`, () => comparable(root.serialize(p.id, clock)));
202
+ }
203
+ const ids = Object.keys(root.serialize(p.id, max).chits);
204
+ check(`${p.id} history`, () => JSON.stringify(root.chitsHistory(p.id, ids)));
205
+ }
206
+ return mismatches;
207
+ }
208
+
209
+ describe("Turn.serialize", () => {
210
+ test("checkpoints match a full replay for every player at every clock, as the game runs", async () => {
211
+ // A short interval so a small game spans several checkpoints
212
+ const defaultInterval = Turn.serializeCheckpointInterval;
213
+ Turn.serializeCheckpointInterval = 8;
214
+ try {
215
+ const counter = { checks: 0 };
216
+ const mismatches: string[] = [];
217
+ const resets: string[] = [];
218
+ const root = await play((root) => {
219
+ mismatches.push(...compareEveryReading(root, (fn) => [withoutCheckpoints(root, fn), fn()], counter));
220
+ // A move must not throw the walk away: after reading the latest clock, the last
221
+ // checkpoint reaches every step but the one still in motion.
222
+ const last = root._checkpoints[root._checkpoints.length - 1];
223
+ if (root.clockSteps.length > 1 && (!last || last.nextIndex < root.clockSteps.length - 1)) {
224
+ resets.push(`${last?.nextIndex ?? "none"} of ${root.clockSteps.length}`);
225
+ }
226
+ });
227
+
228
+ expect(mismatches).toEqual([]);
229
+ expect(resets).toEqual([]);
230
+ expect(counter.checks).toBeGreaterThan(1000);
231
+
232
+ root.serialize("p0", root.playerVisibleClockTime("p0"));
233
+ expect(root.clockSteps.length).toBeGreaterThan(Turn.serializeCheckpointInterval);
234
+ expect(root._checkpoints.length).toBeGreaterThanOrEqual(3);
235
+ expect(root._checkpoints[root._checkpoints.length - 1].nextIndex).toBe(root.clockSteps.length);
236
+ } finally {
237
+ Turn.serializeCheckpointInterval = defaultInterval;
238
+ }
239
+ });
240
+
241
+ test("finished turns read the same without their snapshots and checkpoints", async () => {
242
+ // Reference game: every finished turn keeps its locked snapshot and checkpoints. At every
243
+ // change, each reading is taken that way and again as a plain replay with them released.
244
+ Turn.releaseAbsorbedTurns = false;
245
+ try {
246
+ const counter = { checks: 0 };
247
+ const mismatches: string[] = [];
248
+ const root = await play((root) => {
249
+ mismatches.push(
250
+ ...compareEveryReading(
251
+ root,
252
+ (fn) => [fn(), withReleasedTurns(root, () => withoutCheckpoints(root, fn))],
253
+ counter,
254
+ ),
255
+ );
256
+ });
257
+ expect(mismatches).toEqual([]);
258
+ expect(counter.checks).toBeGreaterThan(1000);
259
+ expect(finishedTurns(root).length).toBeGreaterThan(10);
260
+ expect(finishedTurns(root).filter((t) => Object.keys(t.lockedChitStates).length === 0)).toEqual([]);
261
+ } finally {
262
+ Turn.releaseAbsorbedTurns = true;
263
+ }
264
+
265
+ // As shipped, a finished turn holds nothing; the live root keeps its own snapshot
266
+ const root = await play(() => {});
267
+ root.serialize("p0", root.playerVisibleClockTime("p0"));
268
+ const finished = finishedTurns(root);
269
+ expect(finished.length).toBeGreaterThan(10);
270
+ expect(finished.filter((t) => !t.absorbed)).toEqual([]);
271
+ expect(finished.filter((t) => Object.keys(t.lockedChitStates).length > 0)).toEqual([]);
272
+ expect(finished.filter((t) => t._checkpoints.length > 0)).toEqual([]);
273
+ expect(Object.keys(root.lockedChitStates).length).toBeGreaterThan(0);
274
+ });
275
+ });