@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
@@ -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,19 +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 { 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";
16
19
 
17
20
  export interface IChitLibrary {
18
21
  [key: string]: new () => Chit;
19
22
  }
20
23
 
21
- 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
+ }) {
22
35
  const [localConnection, setLocalConnection] = useState<Connection | undefined>();
23
- const [, setRemoteConnection] = useState<LocalConnectionTransport>(new LocalConnectionTransport());
24
36
 
25
37
  useEffect(() => {
26
38
  const newRemoteConnection = new LocalConnectionTransport();
@@ -29,7 +41,6 @@ function PlayerEditor({ playerId, match, showBack }: { showBack?: boolean; playe
29
41
  match.connect(newRemoteConnection, playerId);
30
42
 
31
43
  setLocalConnection(newConnection);
32
- setRemoteConnection(newRemoteConnection);
33
44
  return () => {
34
45
  newConnection.dispose();
35
46
  };
@@ -42,68 +53,163 @@ function PlayerEditor({ playerId, match, showBack }: { showBack?: boolean; playe
42
53
  return (
43
54
  <ConnectionProvider connection={localConnection}>
44
55
  <PlayerProvider playerId={playerId}>
45
- <MatchViewer
46
- onBack={
47
- showBack
48
- ? () => {
49
- window.history.back();
50
- }
51
- : undefined
52
- }
53
- />
56
+ <MatchViewer onBack={onBack} skipReplay={skipReplay} />
54
57
  </PlayerProvider>
55
58
  </ConnectionProvider>
56
59
  );
57
60
  }
58
61
 
59
- function Editor({ game }: { game: Game<any, any> }) {
60
- 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
+ /** Go straight to this step (by id) once the board loads, playing the script up to it headlessly: a reload
80
+ * that comes back to where the player was */
81
+ resumeAt?: string;
82
+ /** Rendered alongside the match once it exists (the Playground's dev panel) */
83
+ children?: React.ReactNode;
84
+ };
61
85
 
86
+ /**
87
+ * Runs a demo game in this tab: an ephemeral match with one human seat and a bot in every other
88
+ * seat. With `tutorial`, the same match runs the given script on top. A demo is a tutorial with no
89
+ * steps, so both go through `createDemoMatch`.
90
+ */
91
+ export function DemoWrapper({
92
+ game,
93
+ tutorial,
94
+ locale,
95
+ tutorialTheme,
96
+ onTutorialEvent,
97
+ onBack,
98
+ onLoadProgress,
99
+ startAt = 0,
100
+ resumeAt,
101
+ children,
102
+ }: DemoWrapperProps) {
103
+ const [loadingStates] = useState<LoadingStates>(new LoadingStates());
62
104
  useEffect(() => {
63
- const storage = new EphemeralMatchStorage("demogame");
105
+ if (onLoadProgress) {
106
+ return loadingStates.onChange(onLoadProgress);
107
+ }
108
+ }, [loadingStates, onLoadProgress]);
109
+ const [demo, setDemo] = useState<DemoMatch<any, any> | null>(null);
110
+ const demoRef = useRef<DemoMatch<any, any> | null>(null);
111
+ // Where the script (re)starts and whether it needs the Start tap: a rewind restarts at the step it
112
+ // went back to, without the tap
113
+ const [start] = useState<{ at: number; auto: boolean; paused: boolean }>({
114
+ at: startAt,
115
+ auto: false,
116
+ paused: false,
117
+ });
64
118
 
65
- const tempRoot = new game.chitLibrary.Root() as RootChit<any>;
66
- const playerCount = tempRoot.setupDemoGame();
67
- const configOptions = tempRoot.getCurrentlySelectedMatchOptions();
119
+ const spec = typeof tutorial === "string" ? findTutorial(game, tutorial, locale) : tutorial;
120
+ if (typeof tutorial === "string" && !spec) {
121
+ console.warn(`Tutorial "${tutorial}" not found on ${game.metadata.name}; running a plain demo`);
122
+ }
68
123
 
69
- const players = [];
70
- for (let i = 0; i < playerCount; i++) {
71
- const player = new PlayerInfo(`p${i}`, i === 0 ? "Human" : `Robot ${i}`);
72
- player.ai = i === 0 ? undefined : {};
73
- players.push(player);
74
- }
75
- const match = new Match(game, players, storage, configOptions);
124
+ useEffect(() => {
76
125
  let cancelled = false;
77
- match.load().then(() => {
126
+ createDemoMatch(game, spec).then((d) => {
78
127
  if (cancelled) {
128
+ d.match.dispose();
79
129
  return;
80
130
  }
81
- match.seatAiPlayers({ thinkMs: [400, 900] });
82
- match.start();
83
- setMatch(match);
131
+ demoRef.current?.match.dispose();
132
+ demoRef.current = d;
133
+ d.match.start();
134
+ setDemo(d);
84
135
  });
85
136
  return () => {
86
- match.dispose();
87
137
  cancelled = true;
138
+ demoRef.current?.match.dispose();
139
+ demoRef.current = null;
88
140
  };
141
+ }, [game, spec]);
142
+
143
+ // Back in a tutorial: put the match back to the snapshot taken when that step went live. The
144
+ // match reruns from it in place (saved decisions replay deterministically; the pinned draws and
145
+ // forced moves rewind with it) and the viewer animates to the old board without remounting.
146
+ const snapshot = useCallback(() => JSON.parse(JSON.stringify(demoRef.current?.match.state ?? {})), []);
147
+ // Skipping ahead (the dev panel) goes the same way: a step not played yet is played headlessly
148
+ // first, and this match takes that run's snapshots, so Back works from wherever it lands.
149
+ const specRef = useRef(spec);
150
+ specRef.current = spec;
151
+ const rewind = useCallback(async (stepId: string) => {
152
+ const current = demoRef.current;
153
+ if (!current) return false;
154
+ if (!current.runtime.hasSnapshot(stepId) && specRef.current) {
155
+ const run = await runTutorial(game, specRef.current, { until: stepId, stepTimeoutMs: 5000 });
156
+ if (demoRef.current !== current) return false;
157
+ if (!run.runtime.hasSnapshot(stepId)) {
158
+ console.warn(
159
+ `[tutorial ${specRef.current.id}] could not play ahead to "${stepId}": ${run.error ?? `stuck on "${run.stuckOn}"`}`,
160
+ );
161
+ return false;
162
+ }
163
+ current.runtime.adoptSnapshots(run.runtime);
164
+ }
165
+ const state = current.runtime.restoreSnapshot(stepId);
166
+ if (state === undefined) return false;
167
+ await current.replaceState(state);
168
+ return true;
89
169
  }, [game]);
90
170
 
91
- if (!match) {
171
+ if (!demo) {
92
172
  return null;
93
173
  }
94
174
 
95
- return (
96
- <GameProvider game={game}>
97
- <PlayerEditor playerId={"p0"} match={match} showBack />
98
- </GameProvider>
175
+ const onFinished = (e: TutorialEvent) => {
176
+ onTutorialEvent?.(e);
177
+ if (e.type === "completed" && e.end === "back") {
178
+ onBack?.();
179
+ }
180
+ };
181
+
182
+ const viewer = (
183
+ <PlayerEditor key={demo.key} playerId={demo.playerId} match={demo.match} onBack={onBack} skipReplay={start.auto} />
99
184
  );
100
- }
101
185
 
102
- export function DemoWrapper({ game }: { game: Game<any, any> }) {
103
- const [loadingStates] = useState<LoadingStates>(new LoadingStates());
104
186
  return (
105
187
  <LoadingStateProvider loadingStates={loadingStates}>
106
- <Editor game={game} />
188
+ <GameProvider game={game}>
189
+ {spec && spec.steps.length > 0 ? (
190
+ <TutorialProvider
191
+ spec={spec}
192
+ runtime={demo.runtime}
193
+ themeOverrides={tutorialTheme}
194
+ ai={demo.match.ai}
195
+ onEvent={onFinished}
196
+ startAt={start.at}
197
+ autoStart={start.auto}
198
+ startPaused={start.paused}
199
+ resumeAt={resumeAt}
200
+ snapshot={snapshot}
201
+ rewind={rewind}
202
+ >
203
+ {viewer}
204
+ {children}
205
+ </TutorialProvider>
206
+ ) : (
207
+ <>
208
+ {viewer}
209
+ {children}
210
+ </>
211
+ )}
212
+ </GameProvider>
107
213
  </LoadingStateProvider>
108
214
  );
109
215
  }
@@ -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
  }}
@@ -28,7 +28,13 @@ export class BuiltItem {
28
28
 
29
29
  // to be implemented soon
30
30
  private summaryMesh?: Object3D;
31
+ /** the summary's natural height (all of its text, never shrunk in the full gallery) */
31
32
  private summaryHeight: number;
33
+ /** the height it takes on screen: in the full gallery the window it scrolls in */
34
+ private summaryVisibleHeight = 0;
35
+ /** full gallery: how far this item's own summary is scrolled (each summary scrolls on its own) */
36
+ private summaryScrollOffset = 0;
37
+ private summaryScrollDirty = true;
32
38
 
33
39
  private center: Vector3;
34
40
  private _baseOffsetX: number;
@@ -76,6 +82,17 @@ export class BuiltItem {
76
82
  return this.summaryHeight;
77
83
  }
78
84
 
85
+ /** The item's mesh in world space (its summary text excluded), for pointing at it */
86
+ worldBox(): Box3 {
87
+ this.group.updateWorldMatrix(true, true);
88
+ return new Box3().setFromObject(this.mesh);
89
+ }
90
+
91
+ /** False while the item is sliding in or out */
92
+ get settled() {
93
+ return !this.removing && this.enteredAmount >= 1;
94
+ }
95
+
79
96
  public raycastHitsItem(camera: Camera, x: number, y: number): boolean {
80
97
  const { w, h } = this.layoutManager.getDimensions();
81
98
  const ndc = new Vector3((x / w) * 2 - 1, -(y / h) * 2 + 1, 0.5);
@@ -214,11 +231,13 @@ export class BuiltItem {
214
231
  if (this.enterLeaveTween) {
215
232
  this.enterLeaveTween.update();
216
233
  }
234
+ const rewindowed = this.applySummaryScroll();
217
235
  if (this.dirty) {
218
236
  this.positionGroup();
219
237
  this.dirty = false;
220
238
  return true;
221
239
  }
240
+ if (rewindowed) return true;
222
241
  return false;
223
242
  }
224
243
 
@@ -234,13 +253,14 @@ export class BuiltItem {
234
253
 
235
254
  private positionGroup() {
236
255
  const { frontStageWidth, itemsPerPage, itemSpacing } = this.layoutManager.getStageDimensions();
237
- const { w: itemWidth, summaryMaxHeight } = this.layoutManager.getItemDimensions();
256
+ const { w: itemWidth } = this.layoutManager.getItemDimensions();
238
257
  const { h } = this.layoutManager.getDimensions();
239
258
  const initialOffset = -(frontStageWidth / 2 - itemWidth / 2);
240
259
  const targetX = initialOffset + this.index * (itemWidth + itemSpacing) + this._baseOffsetX;
260
+ const summaryViewport = this.layoutManager.getSummaryViewportHeight();
241
261
 
242
262
  this.group.position.y =
243
- (1 - this.enteredAmount) * -h + summaryMaxHeight / 2 + (this.summaryHeight > 0 ? this.theme.spacing / 2 : 0);
263
+ (1 - this.enteredAmount) * -h + summaryViewport / 2 + (summaryViewport > 0 ? this.theme.spacing / 2 : 0);
244
264
 
245
265
  this.group.position.x = targetX;
246
266
 
@@ -252,7 +272,9 @@ export class BuiltItem {
252
272
  this.applyOvershootEffect(-(initialOffset - targetX), largestX, initialOffset);
253
273
  this.repositionSummary(-(initialOffset - targetX));
254
274
  } else {
275
+ // back on the front stage: undo any overshoot tilt (an item built at a stale pan offset starts overshot)
255
276
  this.group.position.z = 0;
277
+ this.group.rotation.y = 0;
256
278
  this.repositionSummary(0);
257
279
  }
258
280
  }
@@ -297,13 +319,41 @@ export class BuiltItem {
297
319
 
298
320
  repositionSummary(overshootX: number) {
299
321
  if (this.summaryMesh) {
300
- const summaryHeight = this.summaryHeight;
301
- const { h } = this.layoutManager.getItemDimensions();
302
- this.summaryMesh.position.y = -summaryHeight / 2 - h / 2 - this.theme.spacing;
322
+ // directly under the item as it draws (an item narrower or shorter than its slot keeps its text close)
323
+ const drawnHalf = (this._meshSize.y * this.mesh.scale.y) / 2;
324
+ this.summaryMesh.position.y = -this.summaryVisibleHeight / 2 - drawnHalf - this.theme.spacing;
303
325
  this.summaryMesh.position.x = (overshootX * this.zFactor) / 3;
304
326
  }
305
327
  }
306
328
 
329
+ /** Full gallery: scroll this item's summary by `delta` (positive reads further down). Returns true when it moved. */
330
+ scrollSummary(delta: number): boolean {
331
+ const max = Math.max(0, this.summaryHeight - this.summaryVisibleHeight);
332
+ const next = Math.max(0, Math.min(max, this.summaryScrollOffset + delta));
333
+ if (next === this.summaryScrollOffset) return false;
334
+ this.summaryScrollOffset = next;
335
+ this.summaryScrollDirty = true;
336
+ return true;
337
+ }
338
+
339
+ /** Full gallery: show the scrolled window of the summary's texture. Returns true when it moved. */
340
+ private applySummaryScroll(): boolean {
341
+ const mesh = this.summaryMesh as Mesh | undefined;
342
+ if (!mesh || this.summaryVisibleHeight >= this.summaryHeight - 0.5) return false;
343
+ if (!this.summaryScrollDirty) return false;
344
+ this.summaryScrollDirty = false;
345
+ const total = this.summaryHeight, visible = this.summaryVisibleHeight;
346
+ const offset = Math.max(0, Math.min(total - visible, this.summaryScrollOffset));
347
+ const top = 1 - offset / total, bottom = 1 - (offset + visible) / total;
348
+ const uv = mesh.geometry.attributes.uv;
349
+ // the plane's top row of vertices shows `top`, its bottom row `bottom`
350
+ const pos = mesh.geometry.attributes.position;
351
+ for (let i = 0; i < uv.count; i++) uv.setY(i, pos.getY(i) > 0 ? top : bottom);
352
+ uv.needsUpdate = true;
353
+ this.sceneWrapper.markDirty();
354
+ return true;
355
+ }
356
+
307
357
  private getSummaryText() {
308
358
  if (this.layoutManager.getSummaryMode() === "full") {
309
359
  return this.item.summary ?? this.item.shortSummary;
@@ -327,12 +377,15 @@ export class BuiltItem {
327
377
  };
328
378
  }
329
379
 
330
- private _lastSummaryMeshWidth = 0;
380
+ private _lastSummaryMeshKey = "";
331
381
  private checkRecreateSummaryMesh() {
332
- const { w: itemWidth } = this.layoutManager.getItemDimensions();
333
- if (this._lastSummaryMeshWidth !== itemWidth) {
382
+ const { w, maxHeight } = this.layoutManager.getSummaryDimensions();
383
+ // The text is part of the key: an item kept across updates (a gallery swapped in place)
384
+ // must redraw its caption when its chit's summary changes, not only when it resizes.
385
+ const key = `${w}x${maxHeight}:${this.getSummaryText() ?? ""}`;
386
+ if (this._lastSummaryMeshKey !== key) {
334
387
  this.createHelpText();
335
- this._lastSummaryMeshWidth = itemWidth;
388
+ this._lastSummaryMeshKey = key;
336
389
  }
337
390
  }
338
391
 
@@ -353,6 +406,7 @@ export class BuiltItem {
353
406
  const summary = this.getSummaryText();
354
407
  if (!summary) {
355
408
  this.summaryHeight = 0;
409
+ this.summaryVisibleHeight = 0;
356
410
  return;
357
411
  }
358
412
 
@@ -364,7 +418,8 @@ export class BuiltItem {
364
418
  }
365
419
 
366
420
  private createSummaryMesh(summary: string, specs: RichTextRenderOptionsParameters): Mesh {
367
- const { w: itemWidth, h: itemHeight } = this.layoutManager.getItemDimensions();
421
+ const { h: itemHeight } = this.layoutManager.getItemDimensions();
422
+ const { w: summaryWidth, maxHeight: summaryMaxHeight } = this.layoutManager.getSummaryDimensions();
368
423
  const pad =
369
424
  this.layoutManager.getSummaryMode() === "full"
370
425
  ? this.theme.spacing * window.devicePixelRatio
@@ -376,16 +431,17 @@ export class BuiltItem {
376
431
  new PadCanvasOperation({ top: pad, bottom: pad, left: pad, right: pad }, markdown),
377
432
  ]);
378
433
 
379
- // Calculate the maximum available height for the summary
380
- const height = itemHeight * 2; // arbitrary large height to allow text to flow
434
+ const full = this.layoutManager.getSummaryMode() === "full";
435
+ // A tall area to let all of the text flow (the full gallery shows all of it, scrolling)
436
+ const height = full ? Math.max(itemHeight * 2, 3000) : itemHeight * 2;
381
437
 
382
438
  // First pass: render with full height to let text flow and calculate actual size
383
- const stack1 = new CanvasStack(itemWidth * window.devicePixelRatio, height * window.devicePixelRatio, ops);
439
+ const stack1 = new CanvasStack(summaryWidth * window.devicePixelRatio, height * window.devicePixelRatio, ops);
384
440
  stack1.render();
385
441
  stack1.dispose();
386
442
 
387
443
  // Second pass: render with actual measured height for final material
388
- const stack2 = new CanvasStack(itemWidth * window.devicePixelRatio, markdown.height + pad * 2, ops);
444
+ const stack2 = new CanvasStack(summaryWidth * window.devicePixelRatio, markdown.height + pad * 2, ops);
389
445
  stack2.render();
390
446
 
391
447
  const material = stack2.material;
@@ -393,10 +449,30 @@ export class BuiltItem {
393
449
  material.depthWrite = true;
394
450
 
395
451
  const finalHeight = stack2.height / window.devicePixelRatio;
396
- this.summaryHeight = finalHeight;
397
452
 
398
- const geometry = new PlaneGeometry(itemWidth, finalHeight);
453
+ if (full) {
454
+ // Never shrunk: shown through a window as tall as the space under the item, scrolled by a vertical swipe
455
+ const visible = summaryMaxHeight > 0 ? Math.min(finalHeight, summaryMaxHeight) : finalHeight;
456
+ const mesh = new Mesh(new PlaneGeometry(summaryWidth, visible), material);
457
+ this.summaryHeight = finalHeight;
458
+ this.summaryVisibleHeight = visible;
459
+ this.summaryScrollOffset = Math.min(this.summaryScrollOffset, Math.max(0, finalHeight - visible));
460
+ this.summaryScrollDirty = true;
461
+ return mesh;
462
+ }
463
+
464
+ const geometry = new PlaneGeometry(summaryWidth, finalHeight);
399
465
  const mesh = new Mesh(geometry, material);
466
+
467
+ // Too long to fit even at full width: shrink it rather than crowd out the item
468
+ if (summaryMaxHeight > 0 && finalHeight > summaryMaxHeight) {
469
+ const scale = summaryMaxHeight / finalHeight;
470
+ mesh.scale.set(scale, scale, 1);
471
+ this.summaryHeight = summaryMaxHeight;
472
+ } else {
473
+ this.summaryHeight = finalHeight;
474
+ }
475
+ this.summaryVisibleHeight = this.summaryHeight;
400
476
  return mesh;
401
477
  }
402
478
  }
@@ -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,22 +97,96 @@ 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
172
  // Item rebuilds (and other paths) only mark the scene wrapper dirty; honor
102
173
  // that here the same way RootChitRenderInstance does so the canvas repaints.
103
174
  let changed = this.dirty || this.sceneWrapper.isDirty();
104
175
 
176
+ // The summaries' height is part of the layout. Items built since the last layout pass (a gallery swapped in place)
177
+ // bring summaries the layout has not measured yet, so re-measure every frame: setSummaryMaxHeight only marks the
178
+ // layout dirty when the height actually changed.
179
+ const syncSummaryHeight = () => {
180
+ if (this.items.length > 0) {
181
+ this.layoutManager.setSummaryMaxHeight(Math.max(...this.items.map((item) => item.getSummaryHeight())));
182
+ }
183
+ };
184
+ syncSummaryHeight();
105
185
  while (this.layoutManager.dirty) {
106
186
  changed = true;
107
187
  this.items.forEach((item) => item.layoutDirty());
108
188
  this.layoutManager.dirty = false;
109
-
110
- const newMaxHeight =
111
- this.items.length === 0
112
- ? this.layoutManager.getSummaryMaxHeight()
113
- : Math.max(...this.items.map((item) => item.getSummaryHeight()));
114
-
115
- this.layoutManager.setSummaryMaxHeight(newMaxHeight);
189
+ syncSummaryHeight();
116
190
  }
117
191
 
118
192
  changed = this.animationController.update() || changed;
@@ -137,6 +211,31 @@ export class GalleryController implements TextureReferenceCounterRootGroup {
137
211
  this.animationController.pan(deltaX, animate, this.items, itemsPerPage, itemWidth, itemSpacing, w);
138
212
  }
139
213
 
214
+ /** Full gallery: whether some summary is longer than the space under its item */
215
+ canScrollSummaries() {
216
+ return this.layoutManager.canScrollSummaries();
217
+ }
218
+ /** Full gallery: scroll the summary in the column at `x` (only that one) by `delta` (positive reads further down) */
219
+ scrollSummaries(delta: number, x: number) {
220
+ if (this.builtItemInColumn(x)?.scrollSummary(delta)) this.dirty = true;
221
+ }
222
+ /** The item whose column (item and summary) contains `x`, whatever the height */
223
+ private builtItemInColumn(x: number): BuiltItem | undefined {
224
+ const { w } = this.layoutManager.getDimensions();
225
+ const { w: itemWidth } = this.layoutManager.getItemDimensions();
226
+ const { frontStageWidth, itemSpacing } = this.layoutManager.getStageDimensions();
227
+ const index = (-this.animationController.getOffsetX() + x - (w - frontStageWidth) / 2) / (itemWidth + itemSpacing);
228
+ return this.items.find((item) => index >= item.getIndex() - itemSpacing / 2 / (itemWidth + itemSpacing) && index < item.getIndex() + 1);
229
+ }
230
+ /** The y (from the top of the gallery) where the summaries start: below it a wheel scrolls them */
231
+ summariesTop() {
232
+ const { h } = this.layoutManager.getDimensions();
233
+ const { h: itemH } = this.layoutManager.getItemDimensions();
234
+ const viewport = this.layoutManager.getSummaryViewportHeight();
235
+ const groupY = viewport / 2 + (viewport > 0 ? this.theme.spacing / 2 : 0);
236
+ return h / 2 - (groupY - itemH / 2);
237
+ }
238
+
140
239
  setItems(items: GalleryItem[]) {
141
240
  const prevItemCount = this.items.length;
142
241
  if (items.length > 0) {
@@ -192,8 +291,10 @@ export class GalleryController implements TextureReferenceCounterRootGroup {
192
291
  // TODO: this is wrong-ish
193
292
  this.cameraManager.updateCameraPosition(0);
194
293
 
195
- const currentItemCount = this.items.length;
196
- if (currentItemCount !== prevItemCount && !this.animationController.isAnimating()) {
294
+ // A changed set of items re-settles the pan (pan stops any running tween), even mid-animation: otherwise a
295
+ // gallery swapped in while the last one was still easing keeps that one's scroll offset, and its items sit off
296
+ // the front stage.
297
+ if (newItems.length > 0 || itemsToDelete.length > 0 || this.items.length !== prevItemCount) {
197
298
  this.pan(0, true);
198
299
  }
199
300
  }