@pretty-chitty/core 1.2.18 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (378) hide show
  1. package/README.md +8 -0
  2. package/dist/components/ActionLogDisplay.d.ts.map +1 -1
  3. package/dist/components/ActionLogDisplay.js +1 -1
  4. package/dist/components/ActionLogDisplay.js.map +1 -1
  5. package/dist/components/BottomBarButton.d.ts +3 -1
  6. package/dist/components/BottomBarButton.d.ts.map +1 -1
  7. package/dist/components/BottomBarButton.js +3 -2
  8. package/dist/components/BottomBarButton.js.map +1 -1
  9. package/dist/components/ClientTrustMatchViewer.d.ts +14 -1
  10. package/dist/components/ClientTrustMatchViewer.d.ts.map +1 -1
  11. package/dist/components/ClientTrustMatchViewer.js +25 -2
  12. package/dist/components/ClientTrustMatchViewer.js.map +1 -1
  13. package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
  14. package/dist/components/ContextGalleryDisplay.js +1 -1
  15. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  16. package/dist/components/DemoWrapper.d.ts +30 -2
  17. package/dist/components/DemoWrapper.d.ts.map +1 -1
  18. package/dist/components/DemoWrapper.js +79 -43
  19. package/dist/components/DemoWrapper.js.map +1 -1
  20. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  21. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  22. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  23. package/dist/components/Gallery/BuiltItem.d.ts +6 -2
  24. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  25. package/dist/components/Gallery/BuiltItem.js +31 -9
  26. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  27. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  28. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryController.js +70 -1
  30. package/dist/components/Gallery/GalleryController.js.map +1 -1
  31. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  32. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  33. package/dist/components/Gallery/GalleryViewer.js +48 -10
  34. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  35. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  36. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  37. package/dist/components/Gallery/LayoutManager.js +23 -3
  38. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  39. package/dist/components/Gallery/constants.d.ts +2 -0
  40. package/dist/components/Gallery/constants.d.ts.map +1 -1
  41. package/dist/components/Gallery/constants.js +2 -0
  42. package/dist/components/Gallery/constants.js.map +1 -1
  43. package/dist/components/Gallery/registry.d.ts +34 -0
  44. package/dist/components/Gallery/registry.d.ts.map +1 -0
  45. package/dist/components/Gallery/registry.js +17 -0
  46. package/dist/components/Gallery/registry.js.map +1 -0
  47. package/dist/components/GameDesigner.d.ts.map +1 -1
  48. package/dist/components/GameDesigner.js +42 -10
  49. package/dist/components/GameDesigner.js.map +1 -1
  50. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  51. package/dist/components/InlineGalleryDisplay.js +2 -2
  52. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  53. package/dist/components/LiveButton.d.ts.map +1 -1
  54. package/dist/components/LiveButton.js +5 -2
  55. package/dist/components/LiveButton.js.map +1 -1
  56. package/dist/components/MatchViewer.d.ts +6 -1
  57. package/dist/components/MatchViewer.d.ts.map +1 -1
  58. package/dist/components/MatchViewer.js +9 -3
  59. package/dist/components/MatchViewer.js.map +1 -1
  60. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  61. package/dist/components/Panel/MultiPanel.js +18 -0
  62. package/dist/components/Panel/MultiPanel.js.map +1 -1
  63. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  64. package/dist/components/Panel/PanelContents.js +92 -23
  65. package/dist/components/Panel/PanelContents.js.map +1 -1
  66. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  67. package/dist/components/Panel/PanelTabStack.js +1 -1
  68. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  69. package/dist/components/PanelSpark.d.ts.map +1 -1
  70. package/dist/components/PanelSpark.js +3 -2
  71. package/dist/components/PanelSpark.js.map +1 -1
  72. package/dist/components/Playground.d.ts.map +1 -1
  73. package/dist/components/Playground.js +46 -14
  74. package/dist/components/Playground.js.map +1 -1
  75. package/dist/components/PromptControls.d.ts.map +1 -1
  76. package/dist/components/PromptControls.js +4 -2
  77. package/dist/components/PromptControls.js.map +1 -1
  78. package/dist/components/SparkLineChart.d.ts.map +1 -1
  79. package/dist/components/SparkLineChart.js +22 -26
  80. package/dist/components/SparkLineChart.js.map +1 -1
  81. package/dist/components/TimeControlBar.d.ts.map +1 -1
  82. package/dist/components/TimeControlBar.js +5 -3
  83. package/dist/components/TimeControlBar.js.map +1 -1
  84. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  85. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  86. package/dist/components/TokenizedMarkdown.js +144 -0
  87. package/dist/components/TokenizedMarkdown.js.map +1 -0
  88. package/dist/components/TokenizedMessage.d.ts +8 -6
  89. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  90. package/dist/components/TokenizedMessage.js +21 -54
  91. package/dist/components/TokenizedMessage.js.map +1 -1
  92. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  93. package/dist/components/TopBarPlayers.js +2 -2
  94. package/dist/components/TopBarPlayers.js.map +1 -1
  95. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  96. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  97. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  98. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  100. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialBox.js +239 -0
  102. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  104. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  106. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  107. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  108. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  109. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  110. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  111. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  112. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  113. package/dist/components/Tutorial/targetRects.js +241 -0
  114. package/dist/components/Tutorial/targetRects.js.map +1 -0
  115. package/dist/game/Chit.d.ts +7 -0
  116. package/dist/game/Chit.d.ts.map +1 -1
  117. package/dist/game/Chit.js +22 -7
  118. package/dist/game/Chit.js.map +1 -1
  119. package/dist/game/ClientTimeState.d.ts +14 -0
  120. package/dist/game/ClientTimeState.d.ts.map +1 -1
  121. package/dist/game/ClientTimeState.js +17 -0
  122. package/dist/game/ClientTimeState.js.map +1 -1
  123. package/dist/game/ConnectionTransport.d.ts +3 -0
  124. package/dist/game/ConnectionTransport.d.ts.map +1 -1
  125. package/dist/game/ConnectionTransport.js +13 -4
  126. package/dist/game/ConnectionTransport.js.map +1 -1
  127. package/dist/game/Game.d.ts +14 -1
  128. package/dist/game/Game.d.ts.map +1 -1
  129. package/dist/game/GameTheme.d.ts +3 -0
  130. package/dist/game/GameTheme.d.ts.map +1 -1
  131. package/dist/game/GameTheme.js +2 -0
  132. package/dist/game/GameTheme.js.map +1 -1
  133. package/dist/game/Match.d.ts +74 -2
  134. package/dist/game/Match.d.ts.map +1 -1
  135. package/dist/game/Match.js +155 -4
  136. package/dist/game/Match.js.map +1 -1
  137. package/dist/game/MatchStorage.d.ts +8 -1
  138. package/dist/game/MatchStorage.d.ts.map +1 -1
  139. package/dist/game/MatchStorage.js +11 -3
  140. package/dist/game/MatchStorage.js.map +1 -1
  141. package/dist/game/Pick.d.ts +16 -0
  142. package/dist/game/Pick.d.ts.map +1 -1
  143. package/dist/game/Pick.js +32 -1
  144. package/dist/game/Pick.js.map +1 -1
  145. package/dist/game/PlayerChit.d.ts +3 -0
  146. package/dist/game/PlayerChit.d.ts.map +1 -1
  147. package/dist/game/PlayerChit.js +3 -0
  148. package/dist/game/PlayerChit.js.map +1 -1
  149. package/dist/game/PlayerInfo.d.ts +8 -0
  150. package/dist/game/PlayerInfo.d.ts.map +1 -1
  151. package/dist/game/PlayerInfo.js +6 -3
  152. package/dist/game/PlayerInfo.js.map +1 -1
  153. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  154. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  155. package/dist/game/PlayerPromptStatusChit.js +8 -2
  156. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  157. package/dist/game/Prompt.d.ts +15 -0
  158. package/dist/game/Prompt.d.ts.map +1 -1
  159. package/dist/game/Prompt.js +16 -0
  160. package/dist/game/Prompt.js.map +1 -1
  161. package/dist/game/Turn.d.ts +20 -4
  162. package/dist/game/Turn.d.ts.map +1 -1
  163. package/dist/game/Turn.js +191 -67
  164. package/dist/game/Turn.js.map +1 -1
  165. package/dist/game/TurnState.d.ts +20 -1
  166. package/dist/game/TurnState.d.ts.map +1 -1
  167. package/dist/game/TurnState.js +22 -3
  168. package/dist/game/TurnState.js.map +1 -1
  169. package/dist/game/ai/AiClientPrompts.d.ts +177 -0
  170. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -0
  171. package/dist/game/ai/AiClientPrompts.js +561 -0
  172. package/dist/game/ai/AiClientPrompts.js.map +1 -0
  173. package/dist/game/ai/AiLiveView.d.ts +2 -0
  174. package/dist/game/ai/AiLiveView.d.ts.map +1 -0
  175. package/dist/game/ai/AiLiveView.js +48 -0
  176. package/dist/game/ai/AiLiveView.js.map +1 -0
  177. package/dist/game/ai/AiPlayerView.d.ts +2 -0
  178. package/dist/game/ai/AiPlayerView.d.ts.map +1 -0
  179. package/dist/game/ai/AiPlayerView.js +91 -0
  180. package/dist/game/ai/AiPlayerView.js.map +1 -0
  181. package/dist/game/ai/connectAiPlayer.d.ts +43 -0
  182. package/dist/game/ai/connectAiPlayer.d.ts.map +1 -0
  183. package/dist/game/ai/connectAiPlayer.js +58 -0
  184. package/dist/game/ai/connectAiPlayer.js.map +1 -0
  185. package/dist/game/ai/defineAi.d.ts +119 -0
  186. package/dist/game/ai/defineAi.d.ts.map +1 -0
  187. package/dist/game/ai/defineAi.js +122 -0
  188. package/dist/game/ai/defineAi.js.map +1 -0
  189. package/dist/game/ai/simulateMatches.d.ts +62 -0
  190. package/dist/game/ai/simulateMatches.d.ts.map +1 -0
  191. package/dist/game/ai/simulateMatches.js +108 -0
  192. package/dist/game/ai/simulateMatches.js.map +1 -0
  193. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts +3 -0
  194. package/dist/game/badAiTransport/BadAIClientPrompts.d.ts.map +1 -1
  195. package/dist/game/badAiTransport/BadAIClientPrompts.js +3 -0
  196. package/dist/game/badAiTransport/BadAIClientPrompts.js.map +1 -1
  197. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  198. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  199. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  200. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  201. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  202. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  203. package/dist/game/clientTransport/ClientTime.js +51 -11
  204. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  205. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  206. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  207. package/dist/game/tutorial/TutorialController.js +1182 -0
  208. package/dist/game/tutorial/TutorialController.js.map +1 -0
  209. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  210. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  211. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  212. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  213. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  214. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  215. package/dist/game/tutorial/TutorialTheme.js +39 -0
  216. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  217. package/dist/game/tutorial/allowed.d.ts +2 -0
  218. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  219. package/dist/game/tutorial/allowed.js +119 -0
  220. package/dist/game/tutorial/allowed.js.map +1 -0
  221. package/dist/game/tutorial/checks.d.ts +58 -0
  222. package/dist/game/tutorial/checks.d.ts.map +1 -0
  223. package/dist/game/tutorial/checks.js +144 -0
  224. package/dist/game/tutorial/checks.js.map +1 -0
  225. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  226. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  227. package/dist/game/tutorial/createDemoMatch.js +67 -0
  228. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  229. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  230. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  231. package/dist/game/tutorial/defineTutorial.js +86 -0
  232. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  233. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  234. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  235. package/dist/game/tutorial/runTutorial.js +273 -0
  236. package/dist/game/tutorial/runTutorial.js.map +1 -0
  237. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  238. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  239. package/dist/hooks/usePanelNavigation.js +36 -0
  240. package/dist/hooks/usePanelNavigation.js.map +1 -0
  241. package/dist/hooks/useTimeController.d.ts +2 -1
  242. package/dist/hooks/useTimeController.d.ts.map +1 -1
  243. package/dist/hooks/useTimeController.js +6 -2
  244. package/dist/hooks/useTimeController.js.map +1 -1
  245. package/dist/hooks/useTokenMap.d.ts +2 -4
  246. package/dist/hooks/useTokenMap.d.ts.map +1 -1
  247. package/dist/hooks/useTokenMap.js +2 -5
  248. package/dist/hooks/useTokenMap.js.map +1 -1
  249. package/dist/hooks/useTutorial.d.ts +48 -0
  250. package/dist/hooks/useTutorial.d.ts.map +1 -0
  251. package/dist/hooks/useTutorial.js +16 -0
  252. package/dist/hooks/useTutorial.js.map +1 -0
  253. package/dist/index.d.ts +57 -1
  254. package/dist/index.d.ts.map +1 -1
  255. package/dist/index.html +12 -0
  256. package/dist/index.js +27 -3
  257. package/dist/index.js.map +1 -1
  258. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  259. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  260. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  261. package/dist/pretty-chitty.js +204513 -0
  262. package/dist/pretty-chitty.js.map +1 -0
  263. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  264. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  265. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  266. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  267. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  268. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  269. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  270. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  271. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  272. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  273. package/dist/rendering/ChitRenderInstance.js +28 -0
  274. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  275. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  276. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  277. package/dist/rendering/RootChitRenderInstance.js +29 -0
  278. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  279. package/dist/utilities/Annotations.d.ts +15 -0
  280. package/dist/utilities/Annotations.d.ts.map +1 -1
  281. package/dist/utilities/Annotations.js +31 -7
  282. package/dist/utilities/Annotations.js.map +1 -1
  283. package/dist/utilities/CanvasStack/CanvasStack.d.ts +13 -0
  284. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  285. package/dist/utilities/CanvasStack/CanvasStack.js +66 -15
  286. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  287. package/dist/utilities/TokenizedText.d.ts +55 -0
  288. package/dist/utilities/TokenizedText.d.ts.map +1 -0
  289. package/dist/utilities/TokenizedText.js +47 -0
  290. package/dist/utilities/TokenizedText.js.map +1 -0
  291. package/dist/utilities/zIndex.d.ts +1 -0
  292. package/dist/utilities/zIndex.d.ts.map +1 -1
  293. package/dist/utilities/zIndex.js +1 -0
  294. package/dist/utilities/zIndex.js.map +1 -1
  295. package/package.json +3 -2
  296. package/src/library/components/ActionLogDisplay.tsx +1 -0
  297. package/src/library/components/BottomBarButton.tsx +5 -0
  298. package/src/library/components/ClientTrustMatchViewer.tsx +32 -2
  299. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  300. package/src/library/components/DemoWrapper.tsx +147 -52
  301. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  302. package/src/library/components/Gallery/BuiltItem.ts +34 -9
  303. package/src/library/components/Gallery/GalleryController.ts +75 -2
  304. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  305. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  306. package/src/library/components/Gallery/constants.ts +2 -0
  307. package/src/library/components/Gallery/registry.ts +44 -0
  308. package/src/library/components/GameDesigner.tsx +121 -12
  309. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  310. package/src/library/components/LiveButton.tsx +8 -5
  311. package/src/library/components/MatchViewer.tsx +14 -3
  312. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  313. package/src/library/components/Panel/PanelContents.tsx +70 -1
  314. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  315. package/src/library/components/PanelSpark.tsx +9 -4
  316. package/src/library/components/Playground.tsx +125 -33
  317. package/src/library/components/PromptControls.tsx +7 -3
  318. package/src/library/components/SparkLineChart.tsx +23 -27
  319. package/src/library/components/TimeControlBar.tsx +5 -3
  320. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  321. package/src/library/components/TokenizedMessage.tsx +30 -95
  322. package/src/library/components/TopBarPlayers.tsx +18 -10
  323. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  324. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  325. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  326. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  327. package/src/library/components/Tutorial/targetRects.ts +273 -0
  328. package/src/library/game/Chit.ts +23 -7
  329. package/src/library/game/ClientTimeState.ts +18 -0
  330. package/src/library/game/ConnectionTransport.ts +12 -3
  331. package/src/library/game/Game.ts +16 -1
  332. package/src/library/game/GameTheme.ts +4 -0
  333. package/src/library/game/Match.ts +174 -5
  334. package/src/library/game/MatchStorage.ts +14 -4
  335. package/src/library/game/Pick.ts +36 -1
  336. package/src/library/game/PlayerChit.ts +4 -1
  337. package/src/library/game/PlayerInfo.ts +13 -3
  338. package/src/library/game/PlayerPromptStatusChit.ts +8 -2
  339. package/src/library/game/Prompt.ts +20 -0
  340. package/src/library/game/Turn.ts +198 -68
  341. package/src/library/game/TurnState.ts +34 -3
  342. package/src/library/game/ai/AI_GUIDE.md +444 -0
  343. package/src/library/game/ai/AiClientPrompts.ts +730 -0
  344. package/src/library/game/ai/AiLiveView.ts +63 -0
  345. package/src/library/game/ai/AiPlayerView.ts +114 -0
  346. package/src/library/game/ai/ai.test.ts +475 -0
  347. package/src/library/game/ai/connectAiPlayer.ts +88 -0
  348. package/src/library/game/ai/defineAi.ts +230 -0
  349. package/src/library/game/ai/simulateMatches.ts +172 -0
  350. package/src/library/game/badAiTransport/BadAIClientPrompts.ts +3 -0
  351. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  352. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  353. package/src/library/game/serialize.test.ts +275 -0
  354. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  355. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  356. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  357. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  358. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  359. package/src/library/game/tutorial/allowed.ts +145 -0
  360. package/src/library/game/tutorial/checks.ts +186 -0
  361. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  362. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  363. package/src/library/game/tutorial/runTutorial.ts +331 -0
  364. package/src/library/game/undo.test.ts +282 -0
  365. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  366. package/src/library/hooks/useTimeController.tsx +6 -2
  367. package/src/library/hooks/useTokenMap.ts +2 -6
  368. package/src/library/hooks/useTutorial.tsx +76 -0
  369. package/src/library/index.ts +91 -4
  370. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  371. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  372. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  373. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  374. package/src/library/utilities/Annotations.ts +35 -7
  375. package/src/library/utilities/CanvasStack/CanvasStack.ts +74 -29
  376. package/src/library/utilities/TokenizedText.test.ts +32 -0
  377. package/src/library/utilities/TokenizedText.ts +103 -0
  378. package/src/library/utilities/zIndex.ts +1 -0
@@ -1,4 +1,4 @@
1
- import React, { useEffect, useState } from "react";
1
+ import React, { useEffect, useRef, useState } from "react";
2
2
  import { Game } from "../game/Game";
3
3
  import { IMatchStorage } from "../game/MatchStorage";
4
4
  import { IPlayerInfo, PlayerInfo } from "../game/PlayerInfo";
@@ -6,11 +6,19 @@ import { ConnectionProvider } from "../hooks/useConnection";
6
6
  import { GameProvider } from "../hooks/useGame";
7
7
  import { PlayerProvider } from "../hooks/usePlayer";
8
8
  import { MatchViewer } from "./MatchViewer";
9
- import { Match } from "../game/Match";
9
+ import { Match, SeatAiPlayersOptions } from "../game/Match";
10
10
  import { Connection } from "../game/Connection";
11
11
  import { LocalConnectionTransport } from "../game/ConnectionTransport";
12
12
  import { LoadingStateProvider, LoadingStates, LoadingStatesCallback } from "../hooks/useLoadingStates";
13
13
 
14
+ /**
15
+ * Runs the match in this browser tab (client-trust mode) and shows it to `playerId`.
16
+ *
17
+ * AI seats: pass `seatAi` to have the match play every seat whose `IPlayerInfo.ai` is set (see
18
+ * `Match.seatAiPlayers`). In client-trust mode every participant's tab runs its own copy of the
19
+ * match, so the host must make sure only one tab drives the bots: pass `aiEnabled={false}` on
20
+ * every other tab (it can change at runtime, e.g. when the driving player leaves).
21
+ */
14
22
  export function ClientTrustMatchViewer({
15
23
  playerId,
16
24
  players,
@@ -19,6 +27,8 @@ export function ClientTrustMatchViewer({
19
27
  onBack,
20
28
  onLoadProgress,
21
29
  options = {},
30
+ seatAi = false,
31
+ aiEnabled = true,
22
32
  }: {
23
33
  playerId: string;
24
34
  players: IPlayerInfo[];
@@ -27,10 +37,19 @@ export function ClientTrustMatchViewer({
27
37
  onBack?: () => void;
28
38
  onLoadProgress?: LoadingStatesCallback;
29
39
  options?: any;
40
+ /** Seat engine AIs in the flagged seats; an object sets their options (think time, logging…) */
41
+ seatAi?: boolean | SeatAiPlayersOptions;
42
+ /** Whether this tab's bots answer prompts. Default true */
43
+ aiEnabled?: boolean;
30
44
  }) {
31
45
  const [loadingStates] = useState<LoadingStates>(new LoadingStates());
32
46
  const [match, setMatch] = useState<Match<any, any> | undefined>();
33
47
  const [localConnection, setLocalConnection] = useState<Connection | undefined>();
48
+ // Read at match creation only: changing how bots are seated should not rebuild the match
49
+ const seatAiRef = useRef(seatAi);
50
+ seatAiRef.current = seatAi;
51
+ const aiEnabledRef = useRef(aiEnabled);
52
+ aiEnabledRef.current = aiEnabled;
34
53
 
35
54
  useEffect(() => {
36
55
  if (onLoadProgress) {
@@ -51,6 +70,11 @@ export function ClientTrustMatchViewer({
51
70
  if (cancelled) {
52
71
  return;
53
72
  }
73
+ const seat = seatAiRef.current;
74
+ if (seat) {
75
+ match.ai.enabled = aiEnabledRef.current;
76
+ match.seatAiPlayers(typeof seat === "object" ? seat : {});
77
+ }
54
78
  match.start();
55
79
  setMatch(match);
56
80
  });
@@ -63,6 +87,12 @@ export function ClientTrustMatchViewer({
63
87
  }
64
88
  }, [game, matchStorage, players, options]);
65
89
 
90
+ useEffect(() => {
91
+ if (match) {
92
+ match.ai.enabled = aiEnabled;
93
+ }
94
+ }, [match, aiEnabled]);
95
+
66
96
  useEffect(() => {
67
97
  if (!match) {
68
98
  setLocalConnection(undefined);
@@ -54,6 +54,8 @@ export function ContextGalleryDisplay({ size }: { size: number }) {
54
54
  }}
55
55
  >
56
56
  <GalleryViewer
57
+ kind="context"
58
+ tutorialTarget="gallery:context"
57
59
  fov={2}
58
60
  angle={0}
59
61
  showSummary={"none"}
@@ -1,4 +1,4 @@
1
- import React, { useEffect, useState } from "react";
1
+ import React, { useCallback, useEffect, useRef, useState } from "react";
2
2
 
3
3
  import { Chit } from "../game/Chit";
4
4
  import { MatchViewer } from "./MatchViewer";
@@ -8,20 +8,31 @@ import { ConnectionProvider } from "../hooks/useConnection";
8
8
  import { Connection } from "../game/Connection";
9
9
  import { LocalConnectionTransport } from "../game/ConnectionTransport";
10
10
  import { Match } from "../game/Match";
11
- import { PlayerInfo } from "../game/PlayerInfo";
12
- import { EphemeralMatchStorage } from "../game/MatchStorage";
13
11
  import { PlayerProvider } from "../hooks/usePlayer";
14
- import { LoadingStateProvider, LoadingStates } from "../hooks/useLoadingStates";
15
- import { BadAIClientPrompts } from "../game/badAiTransport/BadAIClientPrompts";
16
- import { RootChit } from "../game/RootChit";
12
+ import { LoadingStateProvider, LoadingStates, LoadingStatesCallback } from "../hooks/useLoadingStates";
13
+ import { TutorialSpec, findTutorial } from "../game/tutorial/defineTutorial";
14
+ import { createDemoMatch, DemoMatch } from "../game/tutorial/createDemoMatch";
15
+ import { runTutorial } from "../game/tutorial/runTutorial";
16
+ import { TutorialProvider } from "../hooks/useTutorial";
17
+ import { TutorialTheme } from "../game/tutorial/TutorialTheme";
18
+ import { TutorialEvent } from "../game/tutorial/TutorialController";
17
19
 
18
20
  export interface IChitLibrary {
19
21
  [key: string]: new () => Chit;
20
22
  }
21
23
 
22
- function PlayerEditor({ playerId, match, showBack }: { showBack?: boolean; playerId: string; match: Match<any, any> }) {
24
+ function PlayerEditor({
25
+ playerId,
26
+ match,
27
+ onBack,
28
+ skipReplay,
29
+ }: {
30
+ onBack?: () => void;
31
+ playerId: string;
32
+ match: Match<any, any>;
33
+ skipReplay?: boolean;
34
+ }) {
23
35
  const [localConnection, setLocalConnection] = useState<Connection | undefined>();
24
- const [, setRemoteConnection] = useState<LocalConnectionTransport>(new LocalConnectionTransport());
25
36
 
26
37
  useEffect(() => {
27
38
  const newRemoteConnection = new LocalConnectionTransport();
@@ -29,18 +40,7 @@ function PlayerEditor({ playerId, match, showBack }: { showBack?: boolean; playe
29
40
  (newConnection.transport as LocalConnectionTransport).connect(newRemoteConnection);
30
41
  match.connect(newRemoteConnection, playerId);
31
42
 
32
- match.players.forEach((p) => {
33
- if (p.id !== playerId) {
34
- const opponentRemoteConnection = new LocalConnectionTransport();
35
- const opponentConnection = new Connection(new LocalConnectionTransport());
36
- opponentConnection.register(new BadAIClientPrompts<any, any>(p.id, opponentConnection, match), "ClientPrompts");
37
- (opponentConnection.transport as LocalConnectionTransport).connect(opponentRemoteConnection);
38
- match.connect(opponentRemoteConnection, p.id);
39
- }
40
- });
41
-
42
43
  setLocalConnection(newConnection);
43
- setRemoteConnection(newRemoteConnection);
44
44
  return () => {
45
45
  newConnection.dispose();
46
46
  };
@@ -53,65 +53,160 @@ function PlayerEditor({ playerId, match, showBack }: { showBack?: boolean; playe
53
53
  return (
54
54
  <ConnectionProvider connection={localConnection}>
55
55
  <PlayerProvider playerId={playerId}>
56
- <MatchViewer
57
- onBack={
58
- showBack
59
- ? () => {
60
- window.history.back();
61
- }
62
- : undefined
63
- }
64
- />
56
+ <MatchViewer onBack={onBack} skipReplay={skipReplay} />
65
57
  </PlayerProvider>
66
58
  </ConnectionProvider>
67
59
  );
68
60
  }
69
61
 
70
- function Editor({ game }: { game: Game<any, any> }) {
71
- const [match, setMatch] = useState<Match<any, any> | null>(null);
62
+ export type DemoWrapperProps = {
63
+ game: Game<any, any>;
64
+ /**
65
+ * Run a tutorial: its id (looked up on `game.tutorials`, with `locale` when given) or the spec
66
+ * itself. Without one this is a plain demo game: the same match, no overlay.
67
+ */
68
+ tutorial?: string | TutorialSpec<any, any>;
69
+ locale?: string;
70
+ /** Colour overrides for the overlay, on top of the game's and the spec's */
71
+ tutorialTheme?: Partial<TutorialTheme>;
72
+ onTutorialEvent?: (e: TutorialEvent) => void;
73
+ /** Shown as the back button; with a tutorial whose last step ends with "back", called when it finishes */
74
+ onBack?: () => void;
75
+ /** Panel load progress, as on `ClientTrustMatchViewer`: a host hides its loading screen when loaded equals created */
76
+ onLoadProgress?: LoadingStatesCallback;
77
+ /** Start the tutorial at this step (the Playground's "restart at step") */
78
+ startAt?: number;
79
+ /** Rendered alongside the match once it exists (the Playground's dev panel) */
80
+ children?: React.ReactNode;
81
+ };
72
82
 
83
+ /**
84
+ * Runs a demo game in this tab: an ephemeral match with one human seat and a bot in every other
85
+ * seat. With `tutorial`, the same match runs the given script on top. A demo is a tutorial with no
86
+ * steps, so both go through `createDemoMatch`.
87
+ */
88
+ export function DemoWrapper({
89
+ game,
90
+ tutorial,
91
+ locale,
92
+ tutorialTheme,
93
+ onTutorialEvent,
94
+ onBack,
95
+ onLoadProgress,
96
+ startAt = 0,
97
+ children,
98
+ }: DemoWrapperProps) {
99
+ const [loadingStates] = useState<LoadingStates>(new LoadingStates());
73
100
  useEffect(() => {
74
- const storage = new EphemeralMatchStorage("demogame");
101
+ if (onLoadProgress) {
102
+ return loadingStates.onChange(onLoadProgress);
103
+ }
104
+ }, [loadingStates, onLoadProgress]);
105
+ const [demo, setDemo] = useState<DemoMatch<any, any> | null>(null);
106
+ const demoRef = useRef<DemoMatch<any, any> | null>(null);
107
+ // Where the script (re)starts and whether it needs the Start tap: a rewind restarts at the step it
108
+ // went back to, without the tap
109
+ const [start] = useState<{ at: number; auto: boolean; paused: boolean }>({
110
+ at: startAt,
111
+ auto: false,
112
+ paused: false,
113
+ });
75
114
 
76
- const tempRoot = new game.chitLibrary.Root() as RootChit<any>;
77
- const playerCount = tempRoot.setupDemoGame();
78
- const configOptions = tempRoot.getCurrentlySelectedMatchOptions();
115
+ const spec = typeof tutorial === "string" ? findTutorial(game, tutorial, locale) : tutorial;
116
+ if (typeof tutorial === "string" && !spec) {
117
+ console.warn(`Tutorial "${tutorial}" not found on ${game.metadata.name}; running a plain demo`);
118
+ }
79
119
 
80
- const players = [];
81
- for (let i = 0; i < playerCount; i++) {
82
- players.push(new PlayerInfo(`p${i}`, i === 0 ? "Human" : `Robot ${i}`));
83
- }
84
- const match = new Match(game, players, storage, configOptions);
120
+ useEffect(() => {
85
121
  let cancelled = false;
86
- match.load().then(() => {
122
+ createDemoMatch(game, spec).then((d) => {
87
123
  if (cancelled) {
124
+ d.match.dispose();
88
125
  return;
89
126
  }
90
- match.start();
91
- setMatch(match);
127
+ demoRef.current?.match.dispose();
128
+ demoRef.current = d;
129
+ d.match.start();
130
+ setDemo(d);
92
131
  });
93
132
  return () => {
94
- match.dispose();
95
133
  cancelled = true;
134
+ demoRef.current?.match.dispose();
135
+ demoRef.current = null;
96
136
  };
137
+ }, [game, spec]);
138
+
139
+ // Back in a tutorial: put the match back to the snapshot taken when that step went live. The
140
+ // match reruns from it in place (saved decisions replay deterministically; the pinned draws and
141
+ // forced moves rewind with it) and the viewer animates to the old board without remounting.
142
+ const snapshot = useCallback(() => JSON.parse(JSON.stringify(demoRef.current?.match.state ?? {})), []);
143
+ // Skipping ahead (the dev panel) goes the same way: a step not played yet is played headlessly
144
+ // first, and this match takes that run's snapshots, so Back works from wherever it lands.
145
+ const specRef = useRef(spec);
146
+ specRef.current = spec;
147
+ const rewind = useCallback(async (stepId: string) => {
148
+ const current = demoRef.current;
149
+ if (!current) return false;
150
+ if (!current.runtime.hasSnapshot(stepId) && specRef.current) {
151
+ const T0 = performance.now();
152
+ const run = await runTutorial(game, specRef.current, { until: stepId, stepTimeoutMs: 5000 });
153
+ console.info("ZZTIME headless", Math.round(performance.now() - T0));
154
+ if (demoRef.current !== current) return false;
155
+ if (!run.runtime.hasSnapshot(stepId)) {
156
+ console.warn(
157
+ `[tutorial ${specRef.current.id}] could not play ahead to "${stepId}": ${run.error ?? `stuck on "${run.stuckOn}"`}`,
158
+ );
159
+ return false;
160
+ }
161
+ current.runtime.adoptSnapshots(run.runtime);
162
+ }
163
+ const state = current.runtime.restoreSnapshot(stepId);
164
+ if (state === undefined) return false;
165
+ await current.replaceState(state);
166
+ return true;
97
167
  }, [game]);
98
168
 
99
- if (!match) {
169
+ if (!demo) {
100
170
  return null;
101
171
  }
102
172
 
103
- return (
104
- <GameProvider game={game}>
105
- <PlayerEditor playerId={"p0"} match={match} showBack />
106
- </GameProvider>
173
+ const onFinished = (e: TutorialEvent) => {
174
+ onTutorialEvent?.(e);
175
+ if (e.type === "completed" && e.end === "back") {
176
+ onBack?.();
177
+ }
178
+ };
179
+
180
+ const viewer = (
181
+ <PlayerEditor key={demo.key} playerId={demo.playerId} match={demo.match} onBack={onBack} skipReplay={start.auto} />
107
182
  );
108
- }
109
183
 
110
- export function DemoWrapper({ game }: { game: Game<any, any> }) {
111
- const [loadingStates] = useState<LoadingStates>(new LoadingStates());
112
184
  return (
113
185
  <LoadingStateProvider loadingStates={loadingStates}>
114
- <Editor game={game} />
186
+ <GameProvider game={game}>
187
+ {spec && spec.steps.length > 0 ? (
188
+ <TutorialProvider
189
+ spec={spec}
190
+ runtime={demo.runtime}
191
+ themeOverrides={tutorialTheme}
192
+ ai={demo.match.ai}
193
+ onEvent={onFinished}
194
+ startAt={start.at}
195
+ autoStart={start.auto}
196
+ startPaused={start.paused}
197
+ snapshot={snapshot}
198
+ rewind={rewind}
199
+ >
200
+ {viewer}
201
+ {children}
202
+ </TutorialProvider>
203
+ ) : (
204
+ <>
205
+ {viewer}
206
+ {children}
207
+ </>
208
+ )}
209
+ </GameProvider>
115
210
  </LoadingStateProvider>
116
211
  );
117
212
  }
@@ -46,6 +46,7 @@ export function FullScreenGalleryDisplay() {
46
46
  <GameModalBackdrop visible={!!hasItems}>
47
47
  {source?.inlineGallerySize && (
48
48
  <IconButton
49
+ data-tutorial-target="gallery:toInline"
49
50
  sx={{
50
51
  backgroundColor: theme.inlineGalleryButtonBackgroundColor,
51
52
  position: "absolute",
@@ -64,6 +65,8 @@ export function FullScreenGalleryDisplay() {
64
65
  </IconButton>
65
66
  )}
66
67
  <GalleryViewer
68
+ kind="fullscreen"
69
+ tutorialTarget="gallery:fullscreen"
67
70
  onClose={() => {
68
71
  setSource(undefined);
69
72
  }}
@@ -76,6 +76,17 @@ export class BuiltItem {
76
76
  return this.summaryHeight;
77
77
  }
78
78
 
79
+ /** The item's mesh in world space (its summary text excluded), for pointing at it */
80
+ worldBox(): Box3 {
81
+ this.group.updateWorldMatrix(true, true);
82
+ return new Box3().setFromObject(this.mesh);
83
+ }
84
+
85
+ /** False while the item is sliding in or out */
86
+ get settled() {
87
+ return !this.removing && this.enteredAmount >= 1;
88
+ }
89
+
79
90
  public raycastHitsItem(camera: Camera, x: number, y: number): boolean {
80
91
  const { w, h } = this.layoutManager.getDimensions();
81
92
  const ndc = new Vector3((x / w) * 2 - 1, -(y / h) * 2 + 1, 0.5);
@@ -128,6 +139,10 @@ export class BuiltItem {
128
139
 
129
140
  this.checkRecreateSummaryMesh();
130
141
 
142
+ // The clone changed; make sure the next render() repositions and repaints
143
+ // it, otherwise the canvas keeps the previous frame until a pan happens.
144
+ this.dirty = true;
145
+
131
146
  TextureReferenceCounter.update();
132
147
  this.sceneWrapper.markDirty();
133
148
  }
@@ -323,12 +338,13 @@ export class BuiltItem {
323
338
  };
324
339
  }
325
340
 
326
- private _lastSummaryMeshWidth = 0;
341
+ private _lastSummaryMeshKey = "";
327
342
  private checkRecreateSummaryMesh() {
328
- const { w: itemWidth } = this.layoutManager.getItemDimensions();
329
- if (this._lastSummaryMeshWidth !== itemWidth) {
343
+ const { w, maxHeight } = this.layoutManager.getSummaryDimensions();
344
+ const key = `${w}x${maxHeight}`;
345
+ if (this._lastSummaryMeshKey !== key) {
330
346
  this.createHelpText();
331
- this._lastSummaryMeshWidth = itemWidth;
347
+ this._lastSummaryMeshKey = key;
332
348
  }
333
349
  }
334
350
 
@@ -360,7 +376,8 @@ export class BuiltItem {
360
376
  }
361
377
 
362
378
  private createSummaryMesh(summary: string, specs: RichTextRenderOptionsParameters): Mesh {
363
- const { w: itemWidth, h: itemHeight } = this.layoutManager.getItemDimensions();
379
+ const { h: itemHeight } = this.layoutManager.getItemDimensions();
380
+ const { w: summaryWidth, maxHeight: summaryMaxHeight } = this.layoutManager.getSummaryDimensions();
364
381
  const pad =
365
382
  this.layoutManager.getSummaryMode() === "full"
366
383
  ? this.theme.spacing * window.devicePixelRatio
@@ -376,12 +393,12 @@ export class BuiltItem {
376
393
  const height = itemHeight * 2; // arbitrary large height to allow text to flow
377
394
 
378
395
  // First pass: render with full height to let text flow and calculate actual size
379
- const stack1 = new CanvasStack(itemWidth * window.devicePixelRatio, height * window.devicePixelRatio, ops);
396
+ const stack1 = new CanvasStack(summaryWidth * window.devicePixelRatio, height * window.devicePixelRatio, ops);
380
397
  stack1.render();
381
398
  stack1.dispose();
382
399
 
383
400
  // Second pass: render with actual measured height for final material
384
- const stack2 = new CanvasStack(itemWidth * window.devicePixelRatio, markdown.height + pad * 2, ops);
401
+ const stack2 = new CanvasStack(summaryWidth * window.devicePixelRatio, markdown.height + pad * 2, ops);
385
402
  stack2.render();
386
403
 
387
404
  const material = stack2.material;
@@ -389,10 +406,18 @@ export class BuiltItem {
389
406
  material.depthWrite = true;
390
407
 
391
408
  const finalHeight = stack2.height / window.devicePixelRatio;
392
- this.summaryHeight = finalHeight;
393
409
 
394
- const geometry = new PlaneGeometry(itemWidth, finalHeight);
410
+ const geometry = new PlaneGeometry(summaryWidth, finalHeight);
395
411
  const mesh = new Mesh(geometry, material);
412
+
413
+ // Too long to fit even at full width: shrink it rather than crowd out the item
414
+ if (summaryMaxHeight > 0 && finalHeight > summaryMaxHeight) {
415
+ const scale = summaryMaxHeight / finalHeight;
416
+ mesh.scale.set(scale, scale, 1);
417
+ this.summaryHeight = summaryMaxHeight;
418
+ } else {
419
+ this.summaryHeight = finalHeight;
420
+ }
396
421
  return mesh;
397
422
  }
398
423
  }
@@ -1,4 +1,4 @@
1
- import { Object3D } from "three";
1
+ import { Object3D, Vector3 } from "three";
2
2
  import { GameTheme } from "../../game/GameTheme";
3
3
  import { SceneWrapper } from "../../rendering/outline";
4
4
  import { TextureReferenceCounterRootGroup } from "../../rendering/TextureReferenceCounter";
@@ -97,8 +97,81 @@ export class GalleryController implements TextureReferenceCounterRootGroup {
97
97
  return item.getGalleryItem();
98
98
  }
99
99
 
100
+ /** The built item showing `matches` (by its gallery item) */
101
+ private findItem(matches: (item: GalleryItem) => boolean): BuiltItem | undefined {
102
+ return this.items.find((b) => matches(b.getGalleryItem()));
103
+ }
104
+
105
+ /** Ids of the gallery items currently shown (chit ids for items built from chits) */
106
+ itemIds(): string[] {
107
+ return this.items.map((b) => b.id);
108
+ }
109
+
110
+ /** The gallery items currently shown */
111
+ galleryItems(): GalleryItem[] {
112
+ return this.items.map((b) => b.getGalleryItem());
113
+ }
114
+
115
+ /**
116
+ * Where an item is drawn, in the canvas's CSS pixels: a rect when it is on screen, "offscreen"
117
+ * when it is scrolled out of view, undefined when no item matches.
118
+ */
119
+ locateItem(
120
+ matches: (item: GalleryItem) => boolean,
121
+ ): { left: number; top: number; right: number; bottom: number } | "offscreen" | undefined {
122
+ const built = this.findItem(matches);
123
+ if (!built || !built.settled) return undefined;
124
+ const box = built.worldBox();
125
+ if (box.isEmpty()) return undefined;
126
+ const { w, h } = this.layoutManager.getDimensions();
127
+ const camera = this.cameraManager.camera;
128
+ camera.updateMatrixWorld();
129
+ let left = Infinity,
130
+ top = Infinity,
131
+ right = -Infinity,
132
+ bottom = -Infinity;
133
+ for (const x of [box.min.x, box.max.x]) {
134
+ for (const y of [box.min.y, box.max.y]) {
135
+ for (const z of [box.min.z, box.max.z]) {
136
+ const p = new Vector3(x, y, z).project(camera);
137
+ const px = ((p.x + 1) / 2) * w;
138
+ const py = ((1 - p.y) / 2) * h;
139
+ left = Math.min(left, px);
140
+ right = Math.max(right, px);
141
+ top = Math.min(top, py);
142
+ bottom = Math.max(bottom, py);
143
+ }
144
+ }
145
+ }
146
+ // Mostly out of the visible strip: it needs scrolling into view first
147
+ const visible = Math.max(0, Math.min(right, w) - Math.max(left, 0));
148
+ if (visible < (right - left) * 0.6) return "offscreen";
149
+ return {
150
+ left: Math.max(0, left),
151
+ top: Math.max(0, top),
152
+ right: Math.min(w, right),
153
+ bottom: Math.min(h, bottom),
154
+ };
155
+ }
156
+
157
+ /** Pans (animated) so the matching item is on screen, roughly centred */
158
+ scrollToItem(matches: (item: GalleryItem) => boolean) {
159
+ const built = this.findItem(matches);
160
+ if (!built) return;
161
+ const { itemsPerPage, itemSpacing } = this.layoutManager.getStageDimensions();
162
+ const { w: itemWidth } = this.layoutManager.getItemDimensions();
163
+ const step = itemWidth + itemSpacing;
164
+ const firstVisible = -this.animationController.getOffsetX() / step;
165
+ const index = Math.round(built.getIndex());
166
+ if (index >= firstVisible && index <= firstVisible + itemsPerPage - 1) return;
167
+ const target = -(index - Math.floor((itemsPerPage - 1) / 2)) * step;
168
+ this.pan(target - this.animationController.getOffsetX(), true);
169
+ }
170
+
100
171
  render(): boolean {
101
- let changed = this.dirty;
172
+ // Item rebuilds (and other paths) only mark the scene wrapper dirty; honor
173
+ // that here the same way RootChitRenderInstance does so the canvas repaints.
174
+ let changed = this.dirty || this.sceneWrapper.isDirty();
102
175
 
103
176
  while (this.layoutManager.dirty) {
104
177
  changed = true;
@@ -10,6 +10,9 @@ import { requestSharedAnimationFrame } from "../../utilities/RequestSharedAnimat
10
10
  import { TextureReferenceCounter } from "../../rendering/TextureReferenceCounter";
11
11
  import { GalleryController } from "./GalleryController";
12
12
  import { GalleryItem, SummaryMode } from "./types";
13
+ import { GalleryKind, galleryRegistry } from "./registry";
14
+ import { Chit } from "../../game/Chit";
15
+ import { ChitGalleryItemInstance } from "../../rendering/ChitGalleryItemInstance";
13
16
  import {
14
17
  DEFAULT_TWEEN_DURATION,
15
18
  DEFAULT_FOV,
@@ -39,6 +42,20 @@ export interface GalleryViewerProps {
39
42
  onLongPress?: () => void;
40
43
  showSummary?: SummaryMode;
41
44
  zFactor?: number;
45
+ /** Lets tutorials find and point at this gallery's items (see `galleryRegistry`) */
46
+ kind?: GalleryKind;
47
+ /** `data-tutorial-target` for the gallery area */
48
+ tutorialTarget?: string;
49
+ }
50
+
51
+ /**
52
+ * Whether a gallery item shows `chit`: the item is that chit, or (galleries merge identical chits into
53
+ * one "2x" item) an identical one.
54
+ */
55
+ function itemShows(item: GalleryItem, chit: Chit) {
56
+ if (item.id === chit.id) return true;
57
+ const shown = (item as ChitGalleryItemInstance).chit;
58
+ return shown instanceof Chit && shown !== chit && shown.functionallyIdentical(chit);
42
59
  }
43
60
 
44
61
  export function GalleryViewer({
@@ -56,6 +73,8 @@ export function GalleryViewer({
56
73
  galleryItemHeight = h * 0.7,
57
74
  showSummary = "full",
58
75
  zFactor = DEFAULT_Z_FACTOR,
76
+ kind,
77
+ tutorialTarget,
59
78
  }: GalleryViewerProps) {
60
79
  const calcedItemWidth =
61
80
  items.length > 0 ? Math.min(...items.map((item) => item.preferredWidth ?? galleryItemWidth)) : galleryItemWidth;
@@ -71,6 +90,17 @@ export function GalleryViewer({
71
90
  galleryController.setTweenDuration(tweenDuration);
72
91
  galleryController.showSummary = showSummary;
73
92
 
93
+ // Must run before the effects below build items: each build sweeps unused textures, and the gallery's clones
94
+ // only count as used once it's registered.
95
+ useEffect(() => {
96
+ TextureReferenceCounter.registerInstance(galleryController);
97
+ return () => {
98
+ galleryController.destroy();
99
+ TextureReferenceCounter.unregisterInstance(galleryController);
100
+ galleryController.sceneWrapper.dispose();
101
+ };
102
+ }, [galleryController]);
103
+
74
104
  // Single effect to handle both size and items changes
75
105
  useEffect(() => {
76
106
  if (!w || !h || !Number.isFinite(calcedItemHeight) || !Number.isFinite(calcedItemWidth)) {
@@ -89,6 +119,29 @@ export function GalleryViewer({
89
119
  });
90
120
  }, [calcedItemWidth, itemSpacing, calcedItemHeight, w, h, galleryController, zFactor]);
91
121
 
122
+ // Tell tutorials where this gallery's items are
123
+ useEffect(() => {
124
+ const canvas = refContainer.current;
125
+ if (!kind || !canvas) return;
126
+ return galleryRegistry.register({
127
+ kind,
128
+ element: canvas,
129
+ chitIds: () => galleryController.itemIds(),
130
+ locate: (chit) => {
131
+ const exact = galleryController.locateItem((item) => item.id === chit.id);
132
+ const found = exact ?? galleryController.locateItem((item) => itemShows(item, chit));
133
+ if (!found || found === "offscreen") return found;
134
+ const r = canvas.getBoundingClientRect();
135
+ return { left: r.left + found.left, top: r.top + found.top, right: r.left + found.right, bottom: r.top + found.bottom };
136
+ },
137
+ scrollTo: (chit) => {
138
+ const hasExact = galleryController.itemIds().includes(chit.id ?? "");
139
+ galleryController.scrollToItem((item) => (hasExact ? item.id === chit.id : itemShows(item, chit)));
140
+ },
141
+ });
142
+ // the canvas exists only once w and h are known
143
+ }, [kind, galleryController, w, h]);
144
+
92
145
  useEffect(() => {
93
146
  galleryController.setItems(items);
94
147
  // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -204,21 +257,12 @@ export function GalleryViewer({
204
257
  };
205
258
  }, [galleryController, onClose, onLongPress]);
206
259
 
207
- useEffect(() => {
208
- TextureReferenceCounter.registerInstance(galleryController);
209
- return () => {
210
- galleryController.destroy();
211
- TextureReferenceCounter.unregisterInstance(galleryController);
212
- galleryController.sceneWrapper.dispose();
213
- };
214
- }, [galleryController]);
215
-
216
260
  if (!w || !h) {
217
261
  return null;
218
262
  }
219
263
 
220
264
  return (
221
- <Box sx={{ position: "absolute", top: 0, right: 0, left: 0, bottom: 0 }}>
265
+ <Box data-tutorial-target={tutorialTarget} sx={{ position: "absolute", top: 0, right: 0, left: 0, bottom: 0 }}>
222
266
  <canvas
223
267
  width={w * rendererWrapper.pixelRatio}
224
268
  height={h * rendererWrapper.pixelRatio}