@pretty-chitty/core 1.2.18 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (378) hide show
  1. package/README.md +8 -0
  2. package/dist/components/ActionLogDisplay.d.ts.map +1 -1
  3. package/dist/components/ActionLogDisplay.js +1 -1
  4. package/dist/components/ActionLogDisplay.js.map +1 -1
  5. package/dist/components/BottomBarButton.d.ts +3 -1
  6. package/dist/components/BottomBarButton.d.ts.map +1 -1
  7. package/dist/components/BottomBarButton.js +3 -2
  8. package/dist/components/BottomBarButton.js.map +1 -1
  9. package/dist/components/ClientTrustMatchViewer.d.ts +14 -1
  10. package/dist/components/ClientTrustMatchViewer.d.ts.map +1 -1
  11. package/dist/components/ClientTrustMatchViewer.js +25 -2
  12. package/dist/components/ClientTrustMatchViewer.js.map +1 -1
  13. package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
  14. package/dist/components/ContextGalleryDisplay.js +1 -1
  15. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  16. package/dist/components/DemoWrapper.d.ts +30 -2
  17. package/dist/components/DemoWrapper.d.ts.map +1 -1
  18. package/dist/components/DemoWrapper.js +79 -43
  19. package/dist/components/DemoWrapper.js.map +1 -1
  20. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  21. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  22. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  23. package/dist/components/Gallery/BuiltItem.d.ts +6 -2
  24. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  25. package/dist/components/Gallery/BuiltItem.js +31 -9
  26. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  27. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  28. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryController.js +70 -1
  30. package/dist/components/Gallery/GalleryController.js.map +1 -1
  31. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  32. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  33. package/dist/components/Gallery/GalleryViewer.js +48 -10
  34. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  35. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  36. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  37. package/dist/components/Gallery/LayoutManager.js +23 -3
  38. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  39. package/dist/components/Gallery/constants.d.ts +2 -0
  40. package/dist/components/Gallery/constants.d.ts.map +1 -1
  41. package/dist/components/Gallery/constants.js +2 -0
  42. package/dist/components/Gallery/constants.js.map +1 -1
  43. package/dist/components/Gallery/registry.d.ts +34 -0
  44. package/dist/components/Gallery/registry.d.ts.map +1 -0
  45. package/dist/components/Gallery/registry.js +17 -0
  46. package/dist/components/Gallery/registry.js.map +1 -0
  47. package/dist/components/GameDesigner.d.ts.map +1 -1
  48. package/dist/components/GameDesigner.js +42 -10
  49. package/dist/components/GameDesigner.js.map +1 -1
  50. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  51. package/dist/components/InlineGalleryDisplay.js +2 -2
  52. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  53. package/dist/components/LiveButton.d.ts.map +1 -1
  54. package/dist/components/LiveButton.js +5 -2
  55. package/dist/components/LiveButton.js.map +1 -1
  56. package/dist/components/MatchViewer.d.ts +6 -1
  57. package/dist/components/MatchViewer.d.ts.map +1 -1
  58. package/dist/components/MatchViewer.js +9 -3
  59. package/dist/components/MatchViewer.js.map +1 -1
  60. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  61. package/dist/components/Panel/MultiPanel.js +18 -0
  62. package/dist/components/Panel/MultiPanel.js.map +1 -1
  63. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  64. package/dist/components/Panel/PanelContents.js +92 -23
  65. package/dist/components/Panel/PanelContents.js.map +1 -1
  66. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  67. package/dist/components/Panel/PanelTabStack.js +1 -1
  68. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  69. package/dist/components/PanelSpark.d.ts.map +1 -1
  70. package/dist/components/PanelSpark.js +3 -2
  71. package/dist/components/PanelSpark.js.map +1 -1
  72. package/dist/components/Playground.d.ts.map +1 -1
  73. package/dist/components/Playground.js +46 -14
  74. package/dist/components/Playground.js.map +1 -1
  75. package/dist/components/PromptControls.d.ts.map +1 -1
  76. package/dist/components/PromptControls.js +4 -2
  77. package/dist/components/PromptControls.js.map +1 -1
  78. package/dist/components/SparkLineChart.d.ts.map +1 -1
  79. package/dist/components/SparkLineChart.js +22 -26
  80. package/dist/components/SparkLineChart.js.map +1 -1
  81. package/dist/components/TimeControlBar.d.ts.map +1 -1
  82. package/dist/components/TimeControlBar.js +5 -3
  83. package/dist/components/TimeControlBar.js.map +1 -1
  84. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  85. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  86. package/dist/components/TokenizedMarkdown.js +144 -0
  87. package/dist/components/TokenizedMarkdown.js.map +1 -0
  88. package/dist/components/TokenizedMessage.d.ts +8 -6
  89. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  90. package/dist/components/TokenizedMessage.js +21 -54
  91. package/dist/components/TokenizedMessage.js.map +1 -1
  92. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  93. package/dist/components/TopBarPlayers.js +2 -2
  94. package/dist/components/TopBarPlayers.js.map +1 -1
  95. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  96. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  97. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  98. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  100. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialBox.js +239 -0
  102. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  104. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  106. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  107. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  108. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  109. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  110. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  111. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  112. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  113. package/dist/components/Tutorial/targetRects.js +241 -0
  114. package/dist/components/Tutorial/targetRects.js.map +1 -0
  115. package/dist/game/Chit.d.ts +7 -0
  116. package/dist/game/Chit.d.ts.map +1 -1
  117. package/dist/game/Chit.js +22 -7
  118. package/dist/game/Chit.js.map +1 -1
  119. package/dist/game/ClientTimeState.d.ts +14 -0
  120. package/dist/game/ClientTimeState.d.ts.map +1 -1
  121. package/dist/game/ClientTimeState.js +17 -0
  122. package/dist/game/ClientTimeState.js.map +1 -1
  123. package/dist/game/ConnectionTransport.d.ts +3 -0
  124. package/dist/game/ConnectionTransport.d.ts.map +1 -1
  125. package/dist/game/ConnectionTransport.js +13 -4
  126. package/dist/game/ConnectionTransport.js.map +1 -1
  127. package/dist/game/Game.d.ts +14 -1
  128. package/dist/game/Game.d.ts.map +1 -1
  129. package/dist/game/GameTheme.d.ts +3 -0
  130. package/dist/game/GameTheme.d.ts.map +1 -1
  131. package/dist/game/GameTheme.js +2 -0
  132. package/dist/game/GameTheme.js.map +1 -1
  133. package/dist/game/Match.d.ts +74 -2
  134. package/dist/game/Match.d.ts.map +1 -1
  135. package/dist/game/Match.js +155 -4
  136. package/dist/game/Match.js.map +1 -1
  137. package/dist/game/MatchStorage.d.ts +8 -1
  138. package/dist/game/MatchStorage.d.ts.map +1 -1
  139. package/dist/game/MatchStorage.js +11 -3
  140. package/dist/game/MatchStorage.js.map +1 -1
  141. package/dist/game/Pick.d.ts +16 -0
  142. package/dist/game/Pick.d.ts.map +1 -1
  143. package/dist/game/Pick.js +32 -1
  144. package/dist/game/Pick.js.map +1 -1
  145. package/dist/game/PlayerChit.d.ts +3 -0
  146. package/dist/game/PlayerChit.d.ts.map +1 -1
  147. package/dist/game/PlayerChit.js +3 -0
  148. package/dist/game/PlayerChit.js.map +1 -1
  149. package/dist/game/PlayerInfo.d.ts +8 -0
  150. package/dist/game/PlayerInfo.d.ts.map +1 -1
  151. package/dist/game/PlayerInfo.js +6 -3
  152. package/dist/game/PlayerInfo.js.map +1 -1
  153. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  154. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  155. package/dist/game/PlayerPromptStatusChit.js +8 -2
  156. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  157. package/dist/game/Prompt.d.ts +15 -0
  158. package/dist/game/Prompt.d.ts.map +1 -1
  159. package/dist/game/Prompt.js +16 -0
  160. package/dist/game/Prompt.js.map +1 -1
  161. package/dist/game/Turn.d.ts +20 -4
  162. package/dist/game/Turn.d.ts.map +1 -1
  163. package/dist/game/Turn.js +191 -67
  164. package/dist/game/Turn.js.map +1 -1
  165. package/dist/game/TurnState.d.ts +20 -1
  166. package/dist/game/TurnState.d.ts.map +1 -1
  167. package/dist/game/TurnState.js +22 -3
  168. package/dist/game/TurnState.js.map +1 -1
  169. package/dist/game/ai/AiClientPrompts.d.ts +177 -0
  170. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -0
  171. package/dist/game/ai/AiClientPrompts.js +561 -0
  172. package/dist/game/ai/AiClientPrompts.js.map +1 -0
  173. package/dist/game/ai/AiLiveView.d.ts +2 -0
  174. package/dist/game/ai/AiLiveView.d.ts.map +1 -0
  175. package/dist/game/ai/AiLiveView.js +48 -0
  176. package/dist/game/ai/AiLiveView.js.map +1 -0
  177. package/dist/game/ai/AiPlayerView.d.ts +2 -0
  178. package/dist/game/ai/AiPlayerView.d.ts.map +1 -0
  179. package/dist/game/ai/AiPlayerView.js +91 -0
  180. package/dist/game/ai/AiPlayerView.js.map +1 -0
  181. package/dist/game/ai/connectAiPlayer.d.ts +43 -0
  182. package/dist/game/ai/connectAiPlayer.d.ts.map +1 -0
  183. package/dist/game/ai/connectAiPlayer.js +58 -0
  184. package/dist/game/ai/connectAiPlayer.js.map +1 -0
  185. package/dist/game/ai/defineAi.d.ts +119 -0
  186. package/dist/game/ai/defineAi.d.ts.map +1 -0
  187. package/dist/game/ai/defineAi.js +122 -0
  188. package/dist/game/ai/defineAi.js.map +1 -0
  189. package/dist/game/ai/simulateMatches.d.ts +62 -0
  190. package/dist/game/ai/simulateMatches.d.ts.map +1 -0
  191. package/dist/game/ai/simulateMatches.js +108 -0
  192. package/dist/game/ai/simulateMatches.js.map +1 -0
  193. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts +3 -0
  194. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts.map +1 -1
  195. package/dist/game/badAiTransport/BadAIClientPrompts.js +3 -0
  196. package/dist/game/badAiTransport/BadAIClientPrompts.js.map +1 -1
  197. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  198. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  199. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  200. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  201. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  202. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  203. package/dist/game/clientTransport/ClientTime.js +51 -11
  204. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  205. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  206. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  207. package/dist/game/tutorial/TutorialController.js +1182 -0
  208. package/dist/game/tutorial/TutorialController.js.map +1 -0
  209. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  210. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  211. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  212. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  213. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  214. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  215. package/dist/game/tutorial/TutorialTheme.js +39 -0
  216. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  217. package/dist/game/tutorial/allowed.d.ts +2 -0
  218. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  219. package/dist/game/tutorial/allowed.js +119 -0
  220. package/dist/game/tutorial/allowed.js.map +1 -0
  221. package/dist/game/tutorial/checks.d.ts +58 -0
  222. package/dist/game/tutorial/checks.d.ts.map +1 -0
  223. package/dist/game/tutorial/checks.js +144 -0
  224. package/dist/game/tutorial/checks.js.map +1 -0
  225. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  226. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  227. package/dist/game/tutorial/createDemoMatch.js +67 -0
  228. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  229. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  230. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  231. package/dist/game/tutorial/defineTutorial.js +86 -0
  232. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  233. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  234. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  235. package/dist/game/tutorial/runTutorial.js +273 -0
  236. package/dist/game/tutorial/runTutorial.js.map +1 -0
  237. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  238. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  239. package/dist/hooks/usePanelNavigation.js +36 -0
  240. package/dist/hooks/usePanelNavigation.js.map +1 -0
  241. package/dist/hooks/useTimeController.d.ts +2 -1
  242. package/dist/hooks/useTimeController.d.ts.map +1 -1
  243. package/dist/hooks/useTimeController.js +6 -2
  244. package/dist/hooks/useTimeController.js.map +1 -1
  245. package/dist/hooks/useTokenMap.d.ts +2 -4
  246. package/dist/hooks/useTokenMap.d.ts.map +1 -1
  247. package/dist/hooks/useTokenMap.js +2 -5
  248. package/dist/hooks/useTokenMap.js.map +1 -1
  249. package/dist/hooks/useTutorial.d.ts +48 -0
  250. package/dist/hooks/useTutorial.d.ts.map +1 -0
  251. package/dist/hooks/useTutorial.js +16 -0
  252. package/dist/hooks/useTutorial.js.map +1 -0
  253. package/dist/index.d.ts +57 -1
  254. package/dist/index.d.ts.map +1 -1
  255. package/dist/index.html +12 -0
  256. package/dist/index.js +27 -3
  257. package/dist/index.js.map +1 -1
  258. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  259. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  260. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  261. package/dist/pretty-chitty.js +204513 -0
  262. package/dist/pretty-chitty.js.map +1 -0
  263. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  264. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  265. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  266. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  267. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  268. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  269. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  270. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  271. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  272. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  273. package/dist/rendering/ChitRenderInstance.js +28 -0
  274. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  275. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  276. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  277. package/dist/rendering/RootChitRenderInstance.js +29 -0
  278. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  279. package/dist/utilities/Annotations.d.ts +15 -0
  280. package/dist/utilities/Annotations.d.ts.map +1 -1
  281. package/dist/utilities/Annotations.js +31 -7
  282. package/dist/utilities/Annotations.js.map +1 -1
  283. package/dist/utilities/CanvasStack/CanvasStack.d.ts +13 -0
  284. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  285. package/dist/utilities/CanvasStack/CanvasStack.js +66 -15
  286. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  287. package/dist/utilities/TokenizedText.d.ts +55 -0
  288. package/dist/utilities/TokenizedText.d.ts.map +1 -0
  289. package/dist/utilities/TokenizedText.js +47 -0
  290. package/dist/utilities/TokenizedText.js.map +1 -0
  291. package/dist/utilities/zIndex.d.ts +1 -0
  292. package/dist/utilities/zIndex.d.ts.map +1 -1
  293. package/dist/utilities/zIndex.js +1 -0
  294. package/dist/utilities/zIndex.js.map +1 -1
  295. package/package.json +3 -2
  296. package/src/library/components/ActionLogDisplay.tsx +1 -0
  297. package/src/library/components/BottomBarButton.tsx +5 -0
  298. package/src/library/components/ClientTrustMatchViewer.tsx +32 -2
  299. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  300. package/src/library/components/DemoWrapper.tsx +147 -52
  301. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  302. package/src/library/components/Gallery/BuiltItem.ts +34 -9
  303. package/src/library/components/Gallery/GalleryController.ts +75 -2
  304. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  305. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  306. package/src/library/components/Gallery/constants.ts +2 -0
  307. package/src/library/components/Gallery/registry.ts +44 -0
  308. package/src/library/components/GameDesigner.tsx +121 -12
  309. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  310. package/src/library/components/LiveButton.tsx +8 -5
  311. package/src/library/components/MatchViewer.tsx +14 -3
  312. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  313. package/src/library/components/Panel/PanelContents.tsx +70 -1
  314. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  315. package/src/library/components/PanelSpark.tsx +9 -4
  316. package/src/library/components/Playground.tsx +125 -33
  317. package/src/library/components/PromptControls.tsx +7 -3
  318. package/src/library/components/SparkLineChart.tsx +23 -27
  319. package/src/library/components/TimeControlBar.tsx +5 -3
  320. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  321. package/src/library/components/TokenizedMessage.tsx +30 -95
  322. package/src/library/components/TopBarPlayers.tsx +18 -10
  323. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  324. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  325. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  326. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  327. package/src/library/components/Tutorial/targetRects.ts +273 -0
  328. package/src/library/game/Chit.ts +23 -7
  329. package/src/library/game/ClientTimeState.ts +18 -0
  330. package/src/library/game/ConnectionTransport.ts +12 -3
  331. package/src/library/game/Game.ts +16 -1
  332. package/src/library/game/GameTheme.ts +4 -0
  333. package/src/library/game/Match.ts +174 -5
  334. package/src/library/game/MatchStorage.ts +14 -4
  335. package/src/library/game/Pick.ts +36 -1
  336. package/src/library/game/PlayerChit.ts +4 -1
  337. package/src/library/game/PlayerInfo.ts +13 -3
  338. package/src/library/game/PlayerPromptStatusChit.ts +8 -2
  339. package/src/library/game/Prompt.ts +20 -0
  340. package/src/library/game/Turn.ts +198 -68
  341. package/src/library/game/TurnState.ts +34 -3
  342. package/src/library/game/ai/AI_GUIDE.md +444 -0
  343. package/src/library/game/ai/AiClientPrompts.ts +730 -0
  344. package/src/library/game/ai/AiLiveView.ts +63 -0
  345. package/src/library/game/ai/AiPlayerView.ts +114 -0
  346. package/src/library/game/ai/ai.test.ts +475 -0
  347. package/src/library/game/ai/connectAiPlayer.ts +88 -0
  348. package/src/library/game/ai/defineAi.ts +230 -0
  349. package/src/library/game/ai/simulateMatches.ts +172 -0
  350. package/src/library/game/badAiTransport/BadAIClientPrompts.ts +3 -0
  351. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  352. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  353. package/src/library/game/serialize.test.ts +275 -0
  354. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  355. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  356. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  357. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  358. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  359. package/src/library/game/tutorial/allowed.ts +145 -0
  360. package/src/library/game/tutorial/checks.ts +186 -0
  361. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  362. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  363. package/src/library/game/tutorial/runTutorial.ts +331 -0
  364. package/src/library/game/undo.test.ts +282 -0
  365. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  366. package/src/library/hooks/useTimeController.tsx +6 -2
  367. package/src/library/hooks/useTokenMap.ts +2 -6
  368. package/src/library/hooks/useTutorial.tsx +76 -0
  369. package/src/library/index.ts +91 -4
  370. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  371. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  372. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  373. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  374. package/src/library/utilities/Annotations.ts +35 -7
  375. package/src/library/utilities/CanvasStack/CanvasStack.ts +74 -29
  376. package/src/library/utilities/TokenizedText.test.ts +32 -0
  377. package/src/library/utilities/TokenizedText.ts +103 -0
  378. package/src/library/utilities/zIndex.ts +1 -0
@@ -0,0 +1,411 @@
1
+ # Writing a scripted tutorial for a Pretty Chitty game
2
+
3
+ This guide is for whoever adds a tutorial to a game, whether a person or a coding agent. Follow it
4
+ top to bottom. When you're done:
5
+
6
+ - `src/tutorial.ts` exports one `defineTutorial(...)` per locale, listed on `Game.tutorials`,
7
+ - every step either narrates or asks the player to do one thing and checks it against game state,
8
+ - every random draw and every bot move the script relies on is pinned to the step it happens in,
9
+ - a `runTutorial` test proves the script can be completed.
10
+
11
+ The reference implementation is the engine's own demo: `src/demo/market/tutorial.ts` (the script),
12
+ `src/demo/market/MarketGame.ts` (the game it runs on) and `src/demo/market/tutorial.test.ts`.
13
+
14
+ ---
15
+
16
+ ## How it works (read this first)
17
+
18
+ - A tutorial runs **the way a demo game runs**: an in-process match on ephemeral storage, the person
19
+ in one seat and an engine bot in every other seat. A demo *is* a tutorial with no steps. Hosts start
20
+ one with `DemoWrapper` (`createDemoMatchViewer` in a bundle); the Playground's **Demo** tab lists
21
+ every tutorial the game declares.
22
+ - The script is a list of **steps**. A step shows text in a floating box (markdown with the game's
23
+ `:token:` icons), optionally reads it aloud, and draws **rings** and **arrows** on a 2D layer over
24
+ the player. Targets are selectors over game state (`(root, me) => me.hand`), re-resolved every
25
+ frame, so highlights follow chits as they move and the overlay switches to whatever panel holds
26
+ them.
27
+ - A step with `waitFor` is a **"do it" step**: the box says "Your move" and shows no Next until
28
+ the check passes, then the tutorial moves on by itself. Checks are predicates on the state the player sees, so order and
29
+ alternatives are tolerated by construction.
30
+ - **The game only accepts what the script allows.** While a tutorial runs, every tap, drag, button
31
+ and undo goes through a guard: a narration step lets nothing through, and a "do it" step lets
32
+ through only the moves in its `allow` list. Anything else is dropped and the box shows the hint.
33
+ The game's **Undo button is the tutorial's Back** while a tutorial runs: it shows exactly when it
34
+ normally would, and pressing it (or long-pressing it) puts the board back the same way the box's
35
+ Back does. When the tutorial ends, everything is allowed again.
36
+ - **Acting ahead is stepping forward.** If, while a narration step is talking, the player makes a
37
+ move the *next* "do it" step allows (or taps a control it lists as `{ ui }`), the tutorial jumps
38
+ to that step and the move goes through. The steps skipped over still count as seen: their
39
+ snapshots are taken for Back and their `onEnter`/`onExit` and step events run, but their
40
+ narration, focus and gallery commands do not. The "do it" step itself is not narrated, since it
41
+ would only ask for what was just done; it moves on after the usual short beat once its check
42
+ passes, and narrates as usual if the check does not pass. Only the first "do it" step ahead counts,
43
+ so nothing jumps past a step that waits.
44
+ - A step without `waitFor` **narrates and moves on by itself** when its audio ends (or its reading
45
+ clock, when there is no audio). Set `pause: true` to wait for Next instead. The last step always
46
+ waits for Finish.
47
+ - **Back puts the game back** where it was when that step started. The runner snapshots the match as
48
+ each step goes live; Back hands that snapshot to the running match, which reruns from it in place
49
+ (decisions replay deterministically, the pinned draws and forced moves rewind with it) while the
50
+ viewer animates the board back. Rapid presses queue up. **Back also pauses the tutorial**: the
51
+ bots hold their moves, further Back and Next presses move silently between steps, and nothing plays
52
+ or advances until the player presses **Resume** (or completes a "do it" step, which counts as
53
+ resuming). Headless runs have no match to rewind, so there Back only reviews the earlier step's text.
54
+ - **The box never sits on what the step points at.** It takes the step's `box` placement unless that
55
+ hides a ring or arrow target, in which case it moves to the corner that hides the least, and it
56
+ moves again when a cue changes the targets. A dragged box stays put unless a target appears under it.
57
+ - Randomness and the bots are **scripted per step**: `step.rng` pins the values `turn.rng()` returns
58
+ while that step is active; `step.ai` forces the bots' moves. **A bot whose next scripted move
59
+ belongs to a later step waits for that step** to be on screen, so the move happens while the step
60
+ narrates it. It still answers the engine's own Confirm meanwhile (ending a turn the script never
61
+ mentions), unless that Confirm is the scripted move. Once the script runs out, the match carries on normally with the same bots.
62
+ - A **"do it" step that passes while it is still narrating finishes the narration** before moving
63
+ on (Next skips the wait).
64
+
65
+ What the engine does for you. **Do not reimplement these:**
66
+
67
+ | Situation | What the engine does |
68
+ |---|---|
69
+ | Target chit is in another panel (phone tab stack) or a zoomed panel | Switches to it, then draws (nothing is ringed while its panel is behind another) |
70
+ | Everything a step rings on the table sits in one panel, is under 24 px, and zooming that panel's camera cannot bring it to 40 px (the panel is too small), while full screen would grow the panel at least 1.5× — on any screen size. A board overview or anything readable in place stays in the normal layout, beside the rest of the table | Shows that panel full screen, as zooming in does (every panel becomes a tab at the bottom). Rings in another panel go back to the normal layout first, and full screen returns only if that panel needs it too (tab after tab with no context is what this avoids); a new step ringing nothing on the table leaves full screen on a bigger screen. Already full screen because the player zoomed in, it switches tabs instead of leaving |
71
+ | A ringed thing is still tiny (under ~28 px with the whole table shown) | Zooms its panel's camera in until it is readable (about 30% of the panel, at most 140 px, so its surroundings stay in view), and keeps that zoom while the step's later rings still show in it, and back out when the step moves on (not if the player zoomed meanwhile). Rings in a gallery do not zoom, nor a ring with `zoom: false` (which leaves the framing as it is: for rings that only flash by); `zoom: 1.6` zooms that much on a small screen whatever the size (a group of small things); the framing waits half a second, so rings that follow each other quickly (one per word) do not move it |
72
+ | A prompt's own strip (a toggle button's gallery that opens by itself) is up while the player only watches | Puts it away so the board gets the room; it comes back when it is the player's move or a step points into it (a gallery target, a `gallery:`/`button:` UI target, or one of its chits). A strip the player opens stays open |
73
+ | Narration on a phone | The next step's recording loads while a step talks; the box shows about four lines and scrolls to keep the spoken sentence in view, and stays on screen when dragged |
74
+ | Audio on a phone | Plays after the Start tap (the gesture browsers require) |
75
+ | No audio file yet | `audio: "tts"` reads the text with the browser's speech synthesis (authoring only; voices vary per device) |
76
+ | No audio at all | Cues run on a reading clock (3 words/second) |
77
+ | A pinned draw has the wrong length, or lands in a different step than declared | Warns in the console and the dev panel (throws with `strict: true`) |
78
+ | A forced bot move matches no legal option | Warns; the bot plays normally |
79
+ | Engine Confirm prompts ("confirm draw or roll", "confirm turn end") | Nothing special: point at `{ ui: "button:Confirm" }` and check the state after |
80
+
81
+ ---
82
+
83
+ ## Before you start — make the game focus its picks
84
+
85
+ The engine brings a panel to the front on the player's turn only for picks that call `.focus()`
86
+ (`Chit.pick(cards, …).focus()`, `Chit.dragPick(hand, …).focus()`). A game that skips it leaves the
87
+ tab stack wherever the last animation put it, which on phones means the player's own panel can be
88
+ hidden on their turn. The tutorial's reveal is a backstop for what a step points at, not a substitute.
89
+ Check every pick the script will ask for:
90
+
91
+ ```sh
92
+ grep -rn "Chit.pick\|Chit.dragPick" src/ | grep -v "\.focus("
93
+ ```
94
+
95
+ ## Step 1 — Decide the deal
96
+
97
+ A tutorial is written against one fixed board. Work out, in order, every random draw the game makes
98
+ before and during the script, and what you want each to produce:
99
+
100
+ 1. The engine shuffles the seats first: one `takeRng(2 × seats)` draw. Zeros keep the order.
101
+ 2. Then whatever `Game.run` draws before its first prompt (the deal).
102
+ 3. Then each draw that happens while a step is active (a refill after a buy, a bot's draw…).
103
+
104
+ Find your game's draws with:
105
+
106
+ ```sh
107
+ grep -rn "rng(\|takeRng(\|\.draw(\|\.shuffle(" src/
108
+ ```
109
+
110
+ Write a helper that turns "I want *this* card" into the numbers, so the script stays readable. The
111
+ demo's `pinDraws` does it for its deck. Pinned values are honest about their cost: if the rules or the
112
+ setup order change, re-tune them in the Playground (the RNG log has "copy rng" per step).
113
+
114
+ ## Step 2 — Write the match block
115
+
116
+ ```ts
117
+ match: {
118
+ players: [{ name: "You" }, { name: "Robin", ai: {} }, { name: "Sam", ai: {} }], // seat 0 is the person
119
+ options: { rounds: "3" }, // match options, like the Playground's dialog
120
+ rng: [[0, 0, 0, 0, 0, 0], ...SETUP_DRAWS], // seating shuffle, then the deal
121
+ ai: { thinkMs: [600, 1000] }, // bots: temperature 0 by default, so "normal" play is predictable
122
+ },
123
+ ```
124
+
125
+ Omit `match` entirely and you get the demo's defaults (`setupDemoGame()` seats, bots everywhere but seat 0).
126
+
127
+ The start card (before the player taps Start) shows the spec's `intro` (markdown), or the first
128
+ step's text when there is none. Use `intro` for a welcome line instead of a title-card step.
129
+ The card sits in the middle of a darkened table, and nothing on the board can be played until the
130
+ player taps Start (or presses → or Enter).
131
+
132
+ ## Step 3 — Write the steps
133
+
134
+ ```ts
135
+ {
136
+ id: "buy", // stable, unique; shows in logs and the dev panel
137
+ text: "**Your move.** Buy a card: tap any highlighted card you can afford.",
138
+ audio: narration.en.buy.url, // an imported MP3 (see "Narration files"); "tts" while authoring
139
+ sentenceTimes: narration.en.buy.sentenceTimes,
140
+ box: { anchor: "top-right" }, // or { anchor: "near", target, side }, or "keep"
141
+ focus: [{ ring: affordable, arrow: true, dim: true }],
142
+ cues: [{ at: { sentence: 1 }, focus: [...] }], // change highlights mid-narration
143
+ allow: { key: "market.buy" }, // the only moves accepted while waiting; "any" opens everything
144
+ waitFor: checks.countChanged((root, me) => me.hand, 1, "Tap one of the highlighted cards."),
145
+ hint: { after: 6, text: "…" }, // shown if the check hasn't passed after 6 s
146
+ pause: true, // wait for Next after the narration (default: move on by itself)
147
+ pauseAi: true, // bots hold their prompts during this step
148
+ rng: [[0.5, 0.5]], // draws made while this step is active
149
+ ai: { p1: [{ key: "market.buy", chit: affordable }] }, // forced bot moves while active
150
+ },
151
+ ```
152
+
153
+ Rules of thumb:
154
+
155
+ - **One action per "do it" step.** If the engine will ask for a Confirm afterwards, make that its own
156
+ step with an arrow at `{ ui: "button:Confirm" }` and `allow: { button: "Confirm" }`.
157
+ - **Every "do it" step needs `allow`.** It is matched like a forced bot move: `key`, `chit`,
158
+ `target`, `button`, or `"any"`; `allow: []` says the step waits for the bots, not the player. The
159
+ dev panel flags a waiting step without one, and `runTutorial` warns and then gets stuck on it.
160
+ - **Check state, not events.** `checks.state((root) => root.market.cards.length === 4)` passes
161
+ whether the player confirmed just now or a second before the step started.
162
+ `checks.logged(...)` only sees log lines written *during* the step.
163
+ - **Narrate what the bots do only when you force it.** A step that says "Robin buys a card" has
164
+ `ai: { p1: [{ key: "market.buy", … }] }` on it and `waitFor: checks.promptFor("me")` so the
165
+ tutorial waits for the bots to finish.
166
+ - **Pause the bots while you talk** (`pauseAi: true`) when the next thing the bots do would change
167
+ what the step is pointing at.
168
+ - **Highlight as many regions as the step needs.** `focus` is a list; each entry has its own ring
169
+ and arrow (`[{ ring: hand }, { ring: tableau, arrow: true }]`). A ring around several chits is one
170
+ box around all of them; add `separate: true` to ring each one on its own. `dim` keeps every ring
171
+ and arrow target of the step lit; the dim fades in and out, and stays 0.4 s through a gap with nothing ringed
172
+ (a tab sliding, a sentence with no ring) so it does not blink.
173
+ - **Point at parts of a chit** with `{ chit, offset: { y: 0.3 } }` (bbox units, half-extent 0.5, +y
174
+ toward the top of the chit) and `scale: { y: 0.3 }` to ring a band of it.
175
+ - **UI targets:** `button:<Label>`, `undo`, `log`, `time`, `players`, `prompt`,
176
+ `spark:<chitId>` (a counter, use `(root, me) => \`spark:${me.coins.id}\``), `panelTab:<chitId>`,
177
+ and the gallery ones below. Any component can expose more with a `data-tutorial-target` attribute.
178
+ - **Last step** has `end: "continue"` (keep playing) or `"back"`.
179
+
180
+ ### Galleries
181
+
182
+ Some actions only happen in a gallery (a hand shown as a strip, a toggle button's cards), so a
183
+ tutorial can point into galleries, open and close them, and wait for the player to open one. The
184
+ demo's `market-button`, `gallery-tour` and `buy` steps use all of it.
185
+
186
+ - **Rings and arrows reach gallery items.** A chit selector finds the chit in an open gallery first
187
+ (full-screen, then inline), then on the table, so `ring: (root, me) => me.hand.tryGet(0)` circles
188
+ the card where the player can tap it. An item scrolled out of the gallery's view is scrolled in.
189
+ `offset`, `scale`, `separate` and `dim` work the same. Identical chits merged into one "2x" item
190
+ resolve to that item.
191
+ - **The gallery controls are UI targets:**
192
+
193
+ | Target | What it is |
194
+ |---|---|
195
+ | `button:<Label>` | the show/hide toggle in the bottom bar (a `ToggleGalleryButton`, e.g. `button:Hand`) |
196
+ | `gallery:toFullscreen` | the inline gallery's "full screen" button |
197
+ | `gallery:toInline` | the full-screen gallery's "back to inline" button |
198
+ | `gallery:modeButton` | whichever of those two is showing |
199
+ | `gallery:inline` / `gallery:fullscreen` | the gallery itself, to ring the whole strip or screen |
200
+ | `gallery:context` | the small context gallery in the prompt bar |
201
+
202
+ - **The script can open, switch and close galleries** with `gallery` on a step or a cue:
203
+ `{ of: (root, me) => me.hand }` shows a container's children (like tapping it),
204
+ `{ items: (root) => root.market.cards }` shows exactly those chits, `{ mode: "fullscreen" }` moves
205
+ the open gallery to full screen (or `"inline"`), and `"close"` closes it. `mode` defaults to the
206
+ player's own inline/full-screen choice. A gallery the script opened stays until a step or cue
207
+ changes it; Back closes it.
208
+ - **Waiting for the player to open one:** `waitFor: checks.galleryOpen({ of: hand })` (or
209
+ `{ mode: "fullscreen" }`; `checks.galleryClosed()` for the reverse), with
210
+ `allow: { ui: "button:Hand" }` to say the step waits for the player to use a control rather than
211
+ make a game move. Gallery buttons are never blocked by the guard; taps on gallery items that make
212
+ a move go through `allow` like any other move. Tapping that control during an earlier narration
213
+ step acts ahead, as above.
214
+ - **Headless:** `runTutorial` has no buttons, so a step that waits for the player to open a gallery
215
+ needs `ui: (step, ui) => step.id === "open-hand" && ui.gallery({ of: (root, me) => me.hand })`.
216
+
217
+ ### Poses: changing how chits look
218
+
219
+ A pose sets properties on the **player's own copy** of a chit, and the engine renders and animates
220
+ the change as it would any other: a card flips over, a token turns. The match never hears of it, so
221
+ rules, checks, bots and the history are untouched. Put `pose` on a step (from its start) or on a cue
222
+ (from that point of the narration):
223
+
224
+ ```ts
225
+ {
226
+ id: "welcome",
227
+ // the market starts face down...
228
+ pose: [{ chit: (root) => root.table.market.cards, set: { faceDown: true } }],
229
+ cues: [
230
+ // ...and turns over as the narration reaches it: no `set` puts the chit back as the game has it
231
+ { at: { sentence: 3 }, pose: [{ chit: (root) => root.table.market.cards }] },
232
+ ],
233
+ }
234
+ ```
235
+
236
+ - **`set`** is an object of properties or a function `(chit) => { ... }`. Its effect is whatever the
237
+ chit's `render` does with those properties, so the game needs a property that drives the look you
238
+ want (Petty Market's `Card.faceDown` turns the card with `spec.rotateY = Math.PI`).
239
+ - **How long it lasts:** until the step ends, unless the pose sets `keep: true`; then until a later
240
+ pose of that chit or the end of the tutorial. Back puts every pose back, and the step it lands on
241
+ poses its own again. A step that poses the same chit as the step before keeps it posed without a
242
+ flicker.
243
+ - **The game wins.** If the match changes a posed chit, the client loads the new state over the pose.
244
+ - **Only properties come back.** Don't move chits between parents with a pose.
245
+ - **It can only show what the client knows.** A property the server hides from this player (a
246
+ face-down card's face) is not on the client, so a pose cannot reveal it.
247
+ - `runTutorial` ignores poses: they are looks, not state.
248
+
249
+ ### Holding the board's timeline
250
+
251
+ The board plays the game's moments (clocks) one after another, animating each. `timeline` on a step
252
+ or cue holds it on a moment so the narration can talk about what just moved, while the game itself
253
+ carries on behind it. It changes only this player's view.
254
+
255
+ ```ts
256
+ {
257
+ id: "robin",
258
+ // play Robin's buy and the market refill, then hold there...
259
+ timeline: { until: checks.logged(/A new card joins the market/) },
260
+ // ...and play on (Sam's pass, then the player's prompt) at the next sentence
261
+ cues: [{ at: { sentence: 1 }, timeline: "play" }],
262
+ }
263
+ ```
264
+
265
+ - `"hold"` stops at the moment on screen. `{ advance: n }` plays `n` more moments, then stops.
266
+ `{ until: check }` plays on until a moment where the check passes (its `recentLog` counts from the
267
+ command). `"play"` catches up with the game and follows it again.
268
+ - A hold lasts until a later command, Back, or the end of the tutorial. The Skip/Live and Forward
269
+ buttons stop at it too.
270
+ - Release the board before a step that needs it: the player's prompt and most `waitFor` checks only
271
+ show up once the board reaches them. A "do it" step entered while the board is held warns in the
272
+ console unless it sets `timeline` itself.
273
+ - A play-through from the workbench ignores holds until it lands.
274
+
275
+ ### Narration files
276
+
277
+ Ship recordings, not browser speech: an MP3 per step plus `sentenceTimes` (start of each sentence,
278
+ in seconds) so sentence cues and the emphasis are exact. Split text with the exported
279
+ `splitSentences` in your narration tooling, so its sentence count always matches the cues'. The demo generates its files with the
280
+ machine's text-to-speech so the pipeline is real end to end: `yarn demo:audio` renders every sentence
281
+ of every step with macOS `say`, measures each clip, concatenates them, and writes
282
+ `src/demo/market/audio/<locale>/<step>.mp3` and a generated `index.ts` with the imports and timings
283
+ (see `src/demo/market/audio/generate.mjs`). Swap any MP3 for a studio recording and re-run with
284
+ `--timings-only`, or use the workbench's sentence-timing recorder for a file whose sentences you cannot
285
+ measure. Audio files are bundled as assets (`*.mp3` imports resolve to URLs), so `audio` can be an
286
+ imported file or any URL the host serves.
287
+
288
+ Players can speed narration up (1×, 1.25×, 1.5×, 2×; remembered per device). `sentenceTimes` and
289
+ `at` cues are always in the recording's own seconds, so nothing in the script changes with speed.
290
+
291
+ ### Text in the box
292
+
293
+ Markdown: paragraphs, **bold**, lists, headings, links, block quotes, images. `:token:` references
294
+ render with the same icons and player avatars as the action log. `![alt](token:gem)` shows a token's
295
+ art at image size; a URL shows a file from the bundle. Sentence cues (`{ sentence: n }`) and the
296
+ narration emphasis count sentences across the whole text in document order.
297
+
298
+ ### Localisation
299
+
300
+ Keep one script skeleton and one strings file per locale. The demo keeps each locale's step texts,
301
+ hints, title and voice in `src/demo/market/audio/strings.<locale>.json`; `intro(strings)` in
302
+ `tutorial.ts` builds the same steps from any of them, and `yarn demo:audio` renders each locale's
303
+ narration with that file's voice. Sentence cue indices survive translation as long as translators
304
+ keep sentence counts; `at` seconds need per-locale values when the audio differs. A host picks a
305
+ locale with `findTutorial(game, id, locale)` (exact match, then same language, then the first one).
306
+
307
+ ### Colours and type
308
+
309
+ The overlay derives its colours from the game's `GameTheme` (highlight colour, bar colours, font).
310
+ Override any of them, from broadest to narrowest; later layers win:
311
+
312
+ ```ts
313
+ theme.tutorial = { accent: "#ffcc66", arrowColor: "#ffffff" }; // the game's default (GameTheme)
314
+ defineTutorial({ ..., theme: { highlightColor: "#9cf" } }); // one tutorial
315
+ <DemoWrapper game={game} tutorial="intro" tutorialTheme={{ boxBackground: "#102030ee" }} /> // one host
316
+ ```
317
+
318
+ Fields (`TutorialTheme`): `boxBackground`, `boxTextColor`, `accent` (buttons, progress, the sentence
319
+ being read), `boxShadow`, `borderRadius`, `arrowColor`, `highlightColor`, `highlightGlow`,
320
+ `dimColor`, `dimOpacity` (the spotlight), `fontFamily`, `fontScalar`, `boxWidth`.
321
+
322
+ ## Step 4 — Wire it into the game
323
+
324
+ ```ts
325
+ import { marketTutorials } from "./tutorial";
326
+ export class MyGame implements Game<Player, Root> {
327
+ // ...
328
+ tutorials = marketTutorials;
329
+ }
330
+ ```
331
+
332
+ ## Step 5 — Test it
333
+
334
+ ```ts
335
+ test("intro can be completed", async () => {
336
+ const result = await runTutorial(new MyGame(), intro, {
337
+ // Optional: by default the player takes the first move the step's `allow` accepts
338
+ answer: (step, options) => {
339
+ if (step?.id === "buy") return options.findIndex((o) => o.option.key === "market.buy");
340
+ return undefined;
341
+ },
342
+ });
343
+ expect(result.outcome).toBe("completed");
344
+ expect(result.warnings).toEqual([]); // every pinned draw/move landed in the step that declared it
345
+ });
346
+ ```
347
+
348
+ `runTutorial` plays the person's seat with a stand-in that answers only while a "do it" step is
349
+ waiting, and only with a move that step's `allow` accepts. That includes the engine's own Confirm
350
+ prompts, so a step that forgets `allow: { button: "Confirm" }` gets stuck in the test just as it
351
+ would for a player. Every other prompt it holds. The stand-in is not one of the bots, so `pauseAi`
352
+ never pauses it and resuming the bots never lets it act during narration. The run fails with the
353
+ step id when a step can never be completed, which is what a rules change that breaks the script
354
+ looks like.
355
+
356
+ ## Step 6 — Watch it in the Playground
357
+
358
+ Demo tab → pick the tutorial → the workbench on the right shows the steps (click to jump), the live
359
+ check result and hint, the RNG log with step attribution and "copy rng", the bot decisions, warnings,
360
+ a sentence-timing recorder (space while the narration plays, then copy `sentenceTimes`), and toggles
361
+ for muting and showing target rects. "Open full screen" gives a phone-sized check at
362
+ `/demo?tutorial=<id>&locale=<locale>`.
363
+
364
+ Keyboard, anywhere a tutorial runs: **→** next step, **←** previous step, **Space** play/pause. On a
365
+ step waiting for the player's move, → makes the move for them: the first entry of the step's `allow`
366
+ (in the order written) that the prompt can take, or the UI control an entry names. It goes through the
367
+ same guard as a tap, so the game sees an ordinary move. Pressing → over and over plays the whole
368
+ tutorial. While the sentence recorder is on, Space marks a sentence instead.
369
+
370
+ In the workbench, clicking a later step **plays through to it**: narration skipped, animations
371
+ rushed, the player's moves made the same way, the bots playing as scripted. It waits for the board
372
+ to settle before each step, and the step it lands on plays as usual. Alt-click jumps without
373
+ playing. Back, Pause or another jump stops a play-through, and one stuck on a step for 20 s gives up
374
+ there. The status line shows the board's clock (for counting `{ advance: n }`) and any hold.
375
+
376
+ ## Starting a tutorial from a host
377
+
378
+ A tutorial is a demo with a script, so a host starts it the way it starts a demo:
379
+
380
+ ```tsx
381
+ import { DemoWrapper, listTutorials } from "@pretty-chitty/core";
382
+
383
+ listTutorials(game); // [{ id: "intro", locale: "en", title: "How to play", requires: [], steps: 11 }, …]
384
+
385
+ <DemoWrapper
386
+ game={game}
387
+ tutorial="intro" // an id (or a spec); omit it for a plain demo
388
+ locale="es" // picks the matching translation
389
+ tutorialTheme={{ … }} // optional colour overrides
390
+ onTutorialEvent={(e) => …} // "started" | "step" | "satisfied" | "completed" | "skipped"
391
+ onBack={() => …} // the back button, and where `end: "back"` goes
392
+ />
393
+ ```
394
+
395
+ The match is in-process and ephemeral: a reload starts the tutorial again. When the last step's
396
+ Finish is pressed (or the player skips), the box goes away and the same match carries on as a normal
397
+ game against the same bots.
398
+
399
+ ---
400
+
401
+ ## Checklist before you're done
402
+
403
+ - [ ] Every pick the script asks for calls `.focus()`.
404
+ - [ ] Every step has a unique `id` and a `text`.
405
+ - [ ] Every "do it" step's `waitFor` is state-based, has a `hint`, and lists what it `allow`s.
406
+ - [ ] Every move that only happens in a gallery has a step that opens it (or asks the player to) first.
407
+ - [ ] Every draw the script depends on is pinned on the step it happens in; `runTutorial` reports no warnings.
408
+ - [ ] Bot moves the narration mentions are forced on that step.
409
+ - [ ] The last step has `end`.
410
+ - [ ] A locale table exists per language the game ships, and `Game.tutorials` lists them all.
411
+ - [ ] The test passes and the script was watched once on a phone-sized screen.