@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
@@ -0,0 +1,414 @@
1
+ import { Chit } from "../Chit";
2
+ import { OrderedOutlet } from "../OrderedOutlet";
3
+ import { PlayerChit } from "../PlayerChit";
4
+ import { RootChit } from "../RootChit";
5
+ import { PickPrompt } from "../Prompt";
6
+ import type { AiSeatInfo } from "../PlayerInfo";
7
+ import type { SeatAiPlayersOptions } from "../Match";
8
+ import type { Game } from "../Game";
9
+ import type { TutorialTheme } from "./TutorialTheme";
10
+
11
+ /**
12
+ * Names chits in the game: "my hand", "the market cards". Runs against the state the player sees, so
13
+ * it is re-evaluated whenever the board changes and can return nothing while a chit is not there yet.
14
+ */
15
+ export type ChitSelector<P extends PlayerChit, R extends RootChit<P>> = (
16
+ root: R,
17
+ me: P,
18
+ ) => Chit | Chit[] | OrderedOutlet<any> | undefined | null;
19
+
20
+ /** Something in the 2D UI (not a chit) that a step can point at. The names match `data-tutorial-target` attributes. */
21
+ export type UiTarget =
22
+ | `button:${string}` // a prompt button by its label, e.g. "button:Pass" or "button:Confirm"
23
+ | "undo"
24
+ | "log"
25
+ | "time"
26
+ | "players"
27
+ | "prompt" // the whole prompt bar
28
+ | "gallery:inline" // the inline gallery strip, while it shows something
29
+ | "gallery:fullscreen" // the full-screen gallery, while it is open
30
+ | "gallery:toFullscreen" // the inline gallery's "full screen" button
31
+ | "gallery:toInline" // the full-screen gallery's "back to inline" button
32
+ | "gallery:modeButton" // whichever of the two is showing
33
+ | "gallery:context" // the small context gallery in the prompt bar
34
+ | `spark:${string}` // a spark counter by its chit id (`spark:${me.coins.id}`)
35
+ | `panelTab:${string}` // the tab for the panel whose root chit has this id
36
+ | (string & NonNullable<unknown>);
37
+
38
+ /** Where an arrow points or what a ring surrounds. */
39
+ export type Target<P extends PlayerChit, R extends RootChit<P>> =
40
+ | ChitSelector<P, R>
41
+ | {
42
+ chit: ChitSelector<P, R>;
43
+ /** Offset from the chit's centre in units of its bounding box: `{ y: 0.3 }` is 30% of the way to the top edge. */
44
+ offset?: { x?: number; y?: number; z?: number };
45
+ /** Scale the box around the chit: 0.5 rings the middle half of a card. */
46
+ scale?: { x?: number; y?: number };
47
+ }
48
+ | { ui: UiTarget | ((root: R, me: P) => UiTarget) }
49
+ | { screen: { x: number | string; y: number | string } };
50
+
51
+ /**
52
+ * One thing to draw on the overlay. A step's `focus` is a list, so highlight as many regions as you
53
+ * like: `[{ ring: hand }, { ring: tableau, arrow: true }, { arrow: { ui: "button:Pass" } }]`.
54
+ */
55
+ export type Focus<P extends PlayerChit, R extends RootChit<P>> = {
56
+ /** Point an arrow at this. `true` means "at the ring" (each ring, with `separate`). */
57
+ arrow?: Target<P, R> | true;
58
+ /** Draw a ring (rounded box) around this. Several chits get one box around all of them, unless `separate`. */
59
+ ring?: Target<P, R>;
60
+ /** Ring each chit the target names on its own instead of one box around all of them. Default false */
61
+ separate?: boolean;
62
+ /** Ring shape; default "rect" */
63
+ shape?: "rect" | "ellipse";
64
+ /**
65
+ * Spotlight: darken the screen except what the step highlights. Every ring and every arrow target
66
+ * of the step stays lit, not just this entry's. Default false
67
+ */
68
+ dim?: boolean;
69
+ /** Switch to the panel that holds the target and bring it into view. Default true */
70
+ reveal?: boolean;
71
+ /**
72
+ * Frame the ring on a small screen: show its panel full screen, and zoom in on it when it is tiny
73
+ * (see the guide). Default true; false for a ring that is only on screen for a moment, or whose
74
+ * surroundings matter more than its size (it leaves the framing as it is). A number zooms in that
75
+ * much on the ring whatever its size (on a small screen), e.g. 1.6 for a group of things that are each
76
+ * small but together are not.
77
+ */
78
+ zoom?: boolean | number;
79
+ };
80
+
81
+ export type BoxAnchor = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "top" | "bottom" | "center";
82
+
83
+ export type BoxPlacement<P extends PlayerChit, R extends RootChit<P>> =
84
+ | { anchor: BoxAnchor }
85
+ | { anchor: "near"; target: Target<P, R>; side?: "above" | "below" | "left" | "right" }
86
+ | { anchor: "keep" };
87
+
88
+ /**
89
+ * Opens, switches or closes a gallery, as the player could with the gallery buttons.
90
+ * - `{ of: hand }` shows a container's children (what tapping a gallery container does)
91
+ * - `{ items: (root) => root.market.cards }` shows exactly those chits
92
+ * - `{ mode: "fullscreen" }` moves whatever gallery is open to full screen (or back with "inline")
93
+ * - `"close"` closes any open gallery
94
+ * `mode` defaults to the player's own choice (the one the gallery buttons remember).
95
+ */
96
+ export type GalleryCommand<P extends PlayerChit, R extends RootChit<P>> =
97
+ | "close"
98
+ | {
99
+ of?: ChitSelector<P, R>;
100
+ items?: ChitSelector<P, R>;
101
+ mode?: "inline" | "fullscreen" | "preferred";
102
+ };
103
+
104
+ /** An open gallery, for checks: what it shows and how */
105
+ export type TutorialGalleryState = {
106
+ mode: "inline" | "fullscreen";
107
+ /** The container whose children it shows, when it was opened from one */
108
+ of?: string;
109
+ /** Ids of the chits it shows */
110
+ chitIds: string[];
111
+ };
112
+
113
+ /**
114
+ * A change to how chits look, in this player's view only. The properties are set on the client's copy
115
+ * of the chit and the engine renders (and animates) them like any other change: a card flips over, a
116
+ * token turns. The game never sees it, and it is put back when the step ends unless `keep` is set.
117
+ *
118
+ * ```ts
119
+ * pose: [{ chit: (root) => root.table.market.cards[0], set: { faceDown: true } }]
120
+ * ```
121
+ */
122
+ export type Pose<P extends PlayerChit, R extends RootChit<P>> = {
123
+ /** The chit or chits to change */
124
+ chit: ChitSelector<P, R>;
125
+ /**
126
+ * Properties to set (`{ faceDown: true }`), or a function that changes the chit. Leave it out to put
127
+ * the chit back as the game has it. Only properties are put back: do not move chits with a pose.
128
+ */
129
+ set?: { [prop: string]: unknown } | ((chit: Chit) => void);
130
+ /**
131
+ * Keep the change after the step ends, until a later pose of the chit, Back, or the end of the
132
+ * tutorial. A change from the game to the same chit replaces it either way.
133
+ */
134
+ keep?: boolean;
135
+ };
136
+
137
+ /**
138
+ * What the board's timeline does. The board plays the game's moments (clocks) one after another;
139
+ * holding it freezes the board on a moment while the game carries on behind it, so the narration can
140
+ * talk about what just animated. Only this player's view is affected.
141
+ *
142
+ * - `"hold"`: stop at the moment on screen
143
+ * - `{ advance: n }`: play `n` more moments, then stop
144
+ * - `{ until: check }`: play on until the board shows a moment where the check passes, then stop
145
+ * (e.g. `checks.logged(/Robin buys/)`)
146
+ * - `"play"`: play on, catching up with the game and following it again
147
+ *
148
+ * A hold lasts until a later command changes it, Back, or the end of the tutorial.
149
+ */
150
+ export type TimelineCommand<P extends PlayerChit, R extends RootChit<P>> =
151
+ | "hold"
152
+ | "play"
153
+ | { advance: number }
154
+ | { until: Checker<P, R> };
155
+
156
+ export type Cue<P extends PlayerChit, R extends RootChit<P>> = {
157
+ /** Seconds into the narration, or the index (0-based) of the sentence this cue starts with. */
158
+ at: number | { sentence: number };
159
+ /** Replaces the current set of arrows and rings. An empty array clears them. */
160
+ focus?: Focus<P, R>[];
161
+ box?: BoxPlacement<P, R>;
162
+ /** Opens, switches or closes a gallery at this point of the narration */
163
+ gallery?: GalleryCommand<P, R>;
164
+ /** Changes how chits look from this point of the narration (see `Pose`) */
165
+ pose?: Pose<P, R>[];
166
+ /** Holds or plays the board's timeline from this point of the narration (see `TimelineCommand`) */
167
+ timeline?: TimelineCommand<P, R>;
168
+ };
169
+
170
+ /** `true` = done. `false` = not yet. A string = not yet, and the hint to show the player. */
171
+ export type CheckResult = boolean | string;
172
+
173
+ export type TutorialContext<P extends PlayerChit, R extends RootChit<P>> = {
174
+ root: R;
175
+ me: P;
176
+ /** What the player is being asked right now, or undefined when it is not their turn */
177
+ prompt?: PickPrompt;
178
+ clock: number;
179
+ find: <C extends Chit = Chit>(id: string) => C | undefined;
180
+ /** Clock when the current step was entered */
181
+ stepStartClock: number;
182
+ /** Log lines written since the current step was entered, oldest first */
183
+ recentLog: string[];
184
+ /** Galleries open right now, full-screen first */
185
+ galleries: TutorialGalleryState[];
186
+ };
187
+
188
+ export type Checker<P extends PlayerChit, R extends RootChit<P>> = ((ctx: TutorialContext<P, R>) => CheckResult) & {
189
+ /** Called when the step is entered, so a check can remember what the board looked like then. */
190
+ reset?: (ctx: TutorialContext<P, R>) => void;
191
+ };
192
+
193
+ /** A move a bot is told to make (see `TutorialStep.ai`). Every field given must match. */
194
+ export type ForcedDecision<P extends PlayerChit, R extends RootChit<P>> = {
195
+ /** The pick's `.ai("key")` */
196
+ key?: string;
197
+ /** For chit and drag options: the chit (or one of the chits) to play */
198
+ chit?: ChitSelector<P, R>;
199
+ /** For drag options: where to drop it */
200
+ target?: ChitSelector<P, R>;
201
+ /** For button options: the button's label */
202
+ button?: string;
203
+ /** Only use this entry when this holds (checked against the bot's view) */
204
+ when?: (root: R, me: P) => boolean;
205
+ };
206
+
207
+ /**
208
+ * A move the player is allowed to make during a "do it" step. Every field given must match the
209
+ * attempted move; `"any"` allows everything the game offers.
210
+ */
211
+ export type AllowedAction<P extends PlayerChit, R extends RootChit<P>> =
212
+ | "any"
213
+ | {
214
+ /** The pick's `.ai("key")` */
215
+ key?: string;
216
+ /** For taps and drags: the chit (or one of the chits) that may be played */
217
+ chit?: ChitSelector<P, R>;
218
+ /** For drags: where it may be dropped */
219
+ target?: ChitSelector<P, R>;
220
+ /** For buttons (the engine's Confirm included): the label */
221
+ button?: string;
222
+ /**
223
+ * A UI control the player is expected to use (`"button:Market"`, `"gallery:toFullscreen"`).
224
+ * Galleries and other UI are never blocked, so this only says the step waits for the player
225
+ * (not the bots) and matches no game move.
226
+ */
227
+ ui?: UiTarget;
228
+ };
229
+
230
+ export type TutorialStep<P extends PlayerChit, R extends RootChit<P>> = {
231
+ id: string;
232
+ /** Markdown with the game's `:token:` icons inline. See TokenizedMarkdown. */
233
+ text: string;
234
+ /**
235
+ * Narration: a URL (relative to the game bundle) of an audio file, or `"tts"` to have the browser
236
+ * read the text aloud with speech synthesis (handy while authoring, before the recordings exist).
237
+ */
238
+ audio?: string;
239
+ /** Start time of each sentence in the audio file, in seconds. Enables `{ sentence: n }` cues and sentence emphasis for file audio. */
240
+ sentenceTimes?: number[];
241
+ /** Where the box goes when the step starts. Default: where it was. */
242
+ box?: BoxPlacement<P, R>;
243
+ /** Arrows and rings to show from the start of the step (a cue at 0). */
244
+ focus?: Focus<P, R>[];
245
+ /**
246
+ * Opens, switches or closes a gallery when the step starts. A gallery the script opened stays
247
+ * until a later step or cue changes it; Back closes it.
248
+ */
249
+ gallery?: GalleryCommand<P, R>;
250
+ /**
251
+ * Changes how chits look, in this player's view only, from the start of the step (see `Pose`): a
252
+ * card flipping over, a token turning. Put back when the step ends unless a pose sets `keep`.
253
+ */
254
+ pose?: Pose<P, R>[];
255
+ /**
256
+ * Holds or plays the board's timeline when the step starts (see `TimelineCommand`): let the bots'
257
+ * moves animate up to a point and stop there while the narration explains them. The game itself
258
+ * plays on; a "do it" step usually wants `"play"` so the player's prompt is on the board.
259
+ */
260
+ timeline?: TimelineCommand<P, R>;
261
+ /** Changes during the narration */
262
+ cues?: Cue<P, R>[];
263
+ /** Makes this a "do it" step: Next is locked until this passes, then the tutorial moves on by itself. */
264
+ waitFor?: Checker<P, R>;
265
+ /**
266
+ * The only moves the game accepts while this step is waiting. Anything else the player tries is
267
+ * dropped and the hint is shown. A narration step accepts nothing. Required on a "do it" step in
268
+ * practice: without it nothing is allowed and the step cannot be completed (the dev panel and
269
+ * `runTutorial` warn). Use `allow: []` on a step that waits for the bots or the world rather than
270
+ * the player, to say so explicitly.
271
+ */
272
+ allow?: AllowedAction<P, R> | AllowedAction<P, R>[];
273
+ /**
274
+ * Wait for the player to tap Next after the narration instead of moving on by itself. Default false:
275
+ * a narration step auto-advances when its audio (or reading clock) ends; the last step always waits.
276
+ */
277
+ pause?: boolean;
278
+ /** Shown if `waitFor` has not passed after `after` seconds (default 8). A plain string uses the default delay. */
279
+ hint?: string | { after: number; text: string };
280
+ /** Random draws the game makes while this step is active, in order. See `TutorialSpec.match.rng`. */
281
+ rng?: (number | number[])[];
282
+ /** Forced moves per bot (by player id) while this step is active, in order. */
283
+ ai?: { [playerId: string]: ForcedDecision<P, R>[] };
284
+ /** Bots hold their prompts while this step is showing. Default false */
285
+ pauseAi?: boolean;
286
+ onEnter?: (ctx: TutorialContext<P, R>) => void;
287
+ onExit?: (ctx: TutorialContext<P, R>) => void;
288
+ /** Marks the last step: what happens after it. "continue" keeps playing the match; "back" leaves it. */
289
+ end?: "continue" | "back";
290
+ };
291
+
292
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
293
+ export type TutorialMatchSetup<P extends PlayerChit, R extends RootChit<P>> = {
294
+ /** Seats. Default: `Root.setupDemoGame()` seats, "You" first and a bot in every other seat. */
295
+ players?: { name: string; ai?: AiSeatInfo; imageUrl?: string }[];
296
+ /** Index into `players` of the seat the person plays. Default 0 */
297
+ humanSeat?: number;
298
+ /** Match options. Default: what `setupDemoGame()` selects */
299
+ options?: any;
300
+ /**
301
+ * Random draws made during setup, before the first step: the seating shuffle first (an array of
302
+ * 2 × seats values), then whatever `Game.run` draws before it first prompts the player.
303
+ */
304
+ rng?: (number | number[])[];
305
+ /** How the bots play when no step forces a move. Default `{ temperature: 0, thinkMs: [500, 900] }` */
306
+ ai?: SeatAiPlayersOptions;
307
+ };
308
+
309
+ export type TutorialSpec<P extends PlayerChit, R extends RootChit<P>> = {
310
+ id: string;
311
+ /** BCP-47: "en", "es-MX" */
312
+ locale: string;
313
+ title: string;
314
+ /**
315
+ * Shown on the start card, before the player taps Start (markdown, `:token:` icons). Default: the
316
+ * first step's text. Use it for a welcome line rather than adding a title-card step.
317
+ */
318
+ intro?: string;
319
+ /** Feature flags a host must have on to offer this tutorial. Informational. */
320
+ requires?: string[];
321
+ match?: TutorialMatchSetup<P, R>;
322
+ theme?: Partial<TutorialTheme>;
323
+ /** Throw on a stale pinned draw or an unmatched forced move instead of warning. Default false */
324
+ strict?: boolean;
325
+ steps: TutorialStep<P, R>[];
326
+ };
327
+
328
+ /**
329
+ * Declares a scripted tutorial. List it on `Game.tutorials`.
330
+ *
331
+ * ```ts
332
+ * export const intro = defineTutorial<Player, Root>({
333
+ * id: "intro",
334
+ * locale: "en",
335
+ * title: "How to play",
336
+ * steps: [
337
+ * { id: "hand", text: "This is your hand.", focus: [{ ring: (root, me) => me.hand }] },
338
+ * { id: "buy", text: "Buy a card.", waitFor: checks.countChanged((r, me) => me.hand, 1) },
339
+ * ],
340
+ * });
341
+ * ```
342
+ *
343
+ * A tutorial runs the way a demo does: an in-process match, one human seat and bots in the rest.
344
+ * See TUTORIAL_GUIDE.md.
345
+ *
346
+ * @group Tutorials
347
+ */
348
+ export function defineTutorial<P extends PlayerChit, R extends RootChit<P>>(spec: TutorialSpec<P, R>): TutorialSpec<P, R> {
349
+ const ids = new Set<string>();
350
+ spec.steps.forEach((step) => {
351
+ if (ids.has(step.id)) {
352
+ throw new Error(`Tutorial "${spec.id}": duplicate step id "${step.id}"`);
353
+ }
354
+ ids.add(step.id);
355
+ });
356
+ return spec;
357
+ }
358
+
359
+ export type TutorialSummary = { id: string; locale: string; title: string; requires?: string[]; steps: number };
360
+
361
+ /** What a game offers, for a host choosing by language and feature flags. @group Tutorials */
362
+ export function listTutorials(game: Game<any, any>): TutorialSummary[] {
363
+ return (game.tutorials ?? []).map((t) => ({
364
+ id: t.id,
365
+ locale: t.locale,
366
+ title: t.title,
367
+ requires: t.requires,
368
+ steps: t.steps.length,
369
+ }));
370
+ }
371
+
372
+ /** Finds a tutorial by id, and locale when given. @group Tutorials */
373
+ export function findTutorial(game: Game<any, any>, id: string, locale?: string): TutorialSpec<any, any> | undefined {
374
+ const matches = (game.tutorials ?? []).filter((t) => t.id === id);
375
+ if (locale) {
376
+ const exact = matches.find((t) => t.locale === locale);
377
+ if (exact) return exact;
378
+ const language = locale.split("-")[0];
379
+ const sameLanguage = matches.find((t) => t.locale.split("-")[0] === language);
380
+ if (sameLanguage) return sameLanguage;
381
+ }
382
+ return matches[0];
383
+ }
384
+
385
+ /** Normalises a selector's result to a list of chits with ids. @internal */
386
+ export function selectChits<P extends PlayerChit, R extends RootChit<P>>(
387
+ selector: ChitSelector<P, R> | undefined,
388
+ root: R | undefined,
389
+ me: P | undefined,
390
+ ): Chit[] {
391
+ if (!selector || !root || !me) return [];
392
+ let result: Chit | Chit[] | OrderedOutlet<any> | undefined | null;
393
+ try {
394
+ result = selector(root, me);
395
+ } catch {
396
+ return [];
397
+ }
398
+ if (!result) return [];
399
+ if (result instanceof OrderedOutlet) return result.copy();
400
+ if (Array.isArray(result)) return result.filter((c): c is Chit => !!c);
401
+ return [result];
402
+ }
403
+
404
+ /**
405
+ * Splits step text into sentences exactly the way `{ sentence: n }` cues and the narration emphasis
406
+ * count them. Use it in narration tooling (rendering one clip per sentence, measuring `sentenceTimes`)
407
+ * so the counts always agree. Markdown punctuation is left alone.
408
+ *
409
+ * @group Tutorials
410
+ */
411
+ export function splitSentences(text: string): string[] {
412
+ const parts = text.split(/(?<=[.!?][")'\]]*)\s+(?=\S)/);
413
+ return parts.map((p) => p.trim()).filter((p) => p.length > 0);
414
+ }