@pretty-chitty/core 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (318) hide show
  1. package/README.md +8 -0
  2. package/dist/components/ActionLogDisplay.d.ts.map +1 -1
  3. package/dist/components/ActionLogDisplay.js +1 -1
  4. package/dist/components/ActionLogDisplay.js.map +1 -1
  5. package/dist/components/BottomBarButton.d.ts +3 -1
  6. package/dist/components/BottomBarButton.d.ts.map +1 -1
  7. package/dist/components/BottomBarButton.js +3 -2
  8. package/dist/components/BottomBarButton.js.map +1 -1
  9. package/dist/components/ContextGalleryDisplay.d.ts.map +1 -1
  10. package/dist/components/ContextGalleryDisplay.js +1 -1
  11. package/dist/components/ContextGalleryDisplay.js.map +1 -1
  12. package/dist/components/DemoWrapper.d.ts +30 -2
  13. package/dist/components/DemoWrapper.d.ts.map +1 -1
  14. package/dist/components/DemoWrapper.js +79 -36
  15. package/dist/components/DemoWrapper.js.map +1 -1
  16. package/dist/components/FullScreenGalleryDisplay.d.ts.map +1 -1
  17. package/dist/components/FullScreenGalleryDisplay.js +2 -2
  18. package/dist/components/FullScreenGalleryDisplay.js.map +1 -1
  19. package/dist/components/Gallery/BuiltItem.d.ts +6 -2
  20. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  21. package/dist/components/Gallery/BuiltItem.js +28 -9
  22. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  23. package/dist/components/Gallery/GalleryController.d.ts +18 -0
  24. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  25. package/dist/components/Gallery/GalleryController.js +67 -0
  26. package/dist/components/Gallery/GalleryController.js.map +1 -1
  27. package/dist/components/Gallery/GalleryViewer.d.ts +6 -1
  28. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  29. package/dist/components/Gallery/GalleryViewer.js +48 -10
  30. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  31. package/dist/components/Gallery/LayoutManager.d.ts +6 -0
  32. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  33. package/dist/components/Gallery/LayoutManager.js +23 -3
  34. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  35. package/dist/components/Gallery/constants.d.ts +2 -0
  36. package/dist/components/Gallery/constants.d.ts.map +1 -1
  37. package/dist/components/Gallery/constants.js +2 -0
  38. package/dist/components/Gallery/constants.js.map +1 -1
  39. package/dist/components/Gallery/registry.d.ts +34 -0
  40. package/dist/components/Gallery/registry.d.ts.map +1 -0
  41. package/dist/components/Gallery/registry.js +17 -0
  42. package/dist/components/Gallery/registry.js.map +1 -0
  43. package/dist/components/GameDesigner.d.ts.map +1 -1
  44. package/dist/components/GameDesigner.js +42 -10
  45. package/dist/components/GameDesigner.js.map +1 -1
  46. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  47. package/dist/components/InlineGalleryDisplay.js +2 -2
  48. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  49. package/dist/components/LiveButton.d.ts.map +1 -1
  50. package/dist/components/LiveButton.js +5 -2
  51. package/dist/components/LiveButton.js.map +1 -1
  52. package/dist/components/MatchViewer.d.ts +6 -1
  53. package/dist/components/MatchViewer.d.ts.map +1 -1
  54. package/dist/components/MatchViewer.js +9 -3
  55. package/dist/components/MatchViewer.js.map +1 -1
  56. package/dist/components/Panel/MultiPanel.d.ts.map +1 -1
  57. package/dist/components/Panel/MultiPanel.js +18 -0
  58. package/dist/components/Panel/MultiPanel.js.map +1 -1
  59. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  60. package/dist/components/Panel/PanelContents.js +92 -23
  61. package/dist/components/Panel/PanelContents.js.map +1 -1
  62. package/dist/components/Panel/PanelTabStack.d.ts.map +1 -1
  63. package/dist/components/Panel/PanelTabStack.js +1 -1
  64. package/dist/components/Panel/PanelTabStack.js.map +1 -1
  65. package/dist/components/PanelSpark.d.ts.map +1 -1
  66. package/dist/components/PanelSpark.js +3 -2
  67. package/dist/components/PanelSpark.js.map +1 -1
  68. package/dist/components/Playground.d.ts.map +1 -1
  69. package/dist/components/Playground.js +10 -4
  70. package/dist/components/Playground.js.map +1 -1
  71. package/dist/components/PromptControls.d.ts.map +1 -1
  72. package/dist/components/PromptControls.js +4 -2
  73. package/dist/components/PromptControls.js.map +1 -1
  74. package/dist/components/SparkLineChart.d.ts.map +1 -1
  75. package/dist/components/SparkLineChart.js +22 -26
  76. package/dist/components/SparkLineChart.js.map +1 -1
  77. package/dist/components/TimeControlBar.d.ts.map +1 -1
  78. package/dist/components/TimeControlBar.js +5 -3
  79. package/dist/components/TimeControlBar.js.map +1 -1
  80. package/dist/components/TokenizedMarkdown.d.ts +23 -0
  81. package/dist/components/TokenizedMarkdown.d.ts.map +1 -0
  82. package/dist/components/TokenizedMarkdown.js +144 -0
  83. package/dist/components/TokenizedMarkdown.js.map +1 -0
  84. package/dist/components/TokenizedMessage.d.ts +6 -0
  85. package/dist/components/TokenizedMessage.d.ts.map +1 -1
  86. package/dist/components/TokenizedMessage.js +20 -19
  87. package/dist/components/TokenizedMessage.js.map +1 -1
  88. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  89. package/dist/components/TopBarPlayers.js +1 -1
  90. package/dist/components/TopBarPlayers.js.map +1 -1
  91. package/dist/components/Tutorial/BrowserNarration.d.ts +55 -0
  92. package/dist/components/Tutorial/BrowserNarration.d.ts.map +1 -0
  93. package/dist/components/Tutorial/BrowserNarration.js +240 -0
  94. package/dist/components/Tutorial/BrowserNarration.js.map +1 -0
  95. package/dist/components/Tutorial/TutorialBox.d.ts +26 -0
  96. package/dist/components/Tutorial/TutorialBox.d.ts.map +1 -0
  97. package/dist/components/Tutorial/TutorialBox.js +239 -0
  98. package/dist/components/Tutorial/TutorialBox.js.map +1 -0
  99. package/dist/components/Tutorial/TutorialDevPanel.d.ts +9 -0
  100. package/dist/components/Tutorial/TutorialDevPanel.d.ts.map +1 -0
  101. package/dist/components/Tutorial/TutorialDevPanel.js +92 -0
  102. package/dist/components/Tutorial/TutorialDevPanel.js.map +1 -0
  103. package/dist/components/Tutorial/TutorialOverlay.d.ts +7 -0
  104. package/dist/components/Tutorial/TutorialOverlay.d.ts.map +1 -0
  105. package/dist/components/Tutorial/TutorialOverlay.js +1132 -0
  106. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -0
  107. package/dist/components/Tutorial/targetRects.d.ts +67 -0
  108. package/dist/components/Tutorial/targetRects.d.ts.map +1 -0
  109. package/dist/components/Tutorial/targetRects.js +241 -0
  110. package/dist/components/Tutorial/targetRects.js.map +1 -0
  111. package/dist/game/Chit.d.ts +7 -0
  112. package/dist/game/Chit.d.ts.map +1 -1
  113. package/dist/game/Chit.js +20 -5
  114. package/dist/game/Chit.js.map +1 -1
  115. package/dist/game/ClientTimeState.d.ts +14 -0
  116. package/dist/game/ClientTimeState.d.ts.map +1 -1
  117. package/dist/game/ClientTimeState.js +17 -0
  118. package/dist/game/ClientTimeState.js.map +1 -1
  119. package/dist/game/Game.d.ts +6 -0
  120. package/dist/game/Game.d.ts.map +1 -1
  121. package/dist/game/GameTheme.d.ts +3 -0
  122. package/dist/game/GameTheme.d.ts.map +1 -1
  123. package/dist/game/GameTheme.js +2 -0
  124. package/dist/game/GameTheme.js.map +1 -1
  125. package/dist/game/Match.d.ts +8 -2
  126. package/dist/game/Match.d.ts.map +1 -1
  127. package/dist/game/Match.js +4 -1
  128. package/dist/game/Match.js.map +1 -1
  129. package/dist/game/Pick.d.ts +2 -0
  130. package/dist/game/Pick.d.ts.map +1 -1
  131. package/dist/game/Pick.js +17 -1
  132. package/dist/game/Pick.js.map +1 -1
  133. package/dist/game/PlayerPromptStatusChit.d.ts +8 -0
  134. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  135. package/dist/game/PlayerPromptStatusChit.js +5 -1
  136. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  137. package/dist/game/Prompt.d.ts +15 -0
  138. package/dist/game/Prompt.d.ts.map +1 -1
  139. package/dist/game/Prompt.js +16 -0
  140. package/dist/game/Prompt.js.map +1 -1
  141. package/dist/game/Turn.d.ts +15 -4
  142. package/dist/game/Turn.d.ts.map +1 -1
  143. package/dist/game/Turn.js +173 -60
  144. package/dist/game/Turn.js.map +1 -1
  145. package/dist/game/TurnState.d.ts +12 -1
  146. package/dist/game/TurnState.d.ts.map +1 -1
  147. package/dist/game/TurnState.js +15 -3
  148. package/dist/game/TurnState.js.map +1 -1
  149. package/dist/game/ai/AiClientPrompts.d.ts +20 -3
  150. package/dist/game/ai/AiClientPrompts.d.ts.map +1 -1
  151. package/dist/game/ai/AiClientPrompts.js +42 -6
  152. package/dist/game/ai/AiClientPrompts.js.map +1 -1
  153. package/dist/game/ai/AiPlayerView.js +2 -0
  154. package/dist/game/ai/AiPlayerView.js.map +1 -1
  155. package/dist/game/clientTransport/ClientPrompts.d.ts +20 -1
  156. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  157. package/dist/game/clientTransport/ClientPrompts.js +30 -1
  158. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  159. package/dist/game/clientTransport/ClientTime.d.ts +13 -0
  160. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  161. package/dist/game/clientTransport/ClientTime.js +51 -11
  162. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  163. package/dist/game/tutorial/TutorialController.d.ts +300 -0
  164. package/dist/game/tutorial/TutorialController.d.ts.map +1 -0
  165. package/dist/game/tutorial/TutorialController.js +1182 -0
  166. package/dist/game/tutorial/TutorialController.js.map +1 -0
  167. package/dist/game/tutorial/TutorialRuntime.d.ts +89 -0
  168. package/dist/game/tutorial/TutorialRuntime.d.ts.map +1 -0
  169. package/dist/game/tutorial/TutorialRuntime.js +261 -0
  170. package/dist/game/tutorial/TutorialRuntime.js.map +1 -0
  171. package/dist/game/tutorial/TutorialTheme.d.ts +28 -0
  172. package/dist/game/tutorial/TutorialTheme.d.ts.map +1 -0
  173. package/dist/game/tutorial/TutorialTheme.js +39 -0
  174. package/dist/game/tutorial/TutorialTheme.js.map +1 -0
  175. package/dist/game/tutorial/allowed.d.ts +2 -0
  176. package/dist/game/tutorial/allowed.d.ts.map +1 -0
  177. package/dist/game/tutorial/allowed.js +119 -0
  178. package/dist/game/tutorial/allowed.js.map +1 -0
  179. package/dist/game/tutorial/checks.d.ts +58 -0
  180. package/dist/game/tutorial/checks.d.ts.map +1 -0
  181. package/dist/game/tutorial/checks.js +144 -0
  182. package/dist/game/tutorial/checks.js.map +1 -0
  183. package/dist/game/tutorial/createDemoMatch.d.ts +47 -0
  184. package/dist/game/tutorial/createDemoMatch.d.ts.map +1 -0
  185. package/dist/game/tutorial/createDemoMatch.js +67 -0
  186. package/dist/game/tutorial/createDemoMatch.js.map +1 -0
  187. package/dist/game/tutorial/defineTutorial.d.ts +353 -0
  188. package/dist/game/tutorial/defineTutorial.d.ts.map +1 -0
  189. package/dist/game/tutorial/defineTutorial.js +86 -0
  190. package/dist/game/tutorial/defineTutorial.js.map +1 -0
  191. package/dist/game/tutorial/runTutorial.d.ts +63 -0
  192. package/dist/game/tutorial/runTutorial.d.ts.map +1 -0
  193. package/dist/game/tutorial/runTutorial.js +273 -0
  194. package/dist/game/tutorial/runTutorial.js.map +1 -0
  195. package/dist/hooks/usePanelNavigation.d.ts +28 -0
  196. package/dist/hooks/usePanelNavigation.d.ts.map +1 -0
  197. package/dist/hooks/usePanelNavigation.js +36 -0
  198. package/dist/hooks/usePanelNavigation.js.map +1 -0
  199. package/dist/hooks/useTimeController.d.ts +2 -1
  200. package/dist/hooks/useTimeController.d.ts.map +1 -1
  201. package/dist/hooks/useTimeController.js +6 -2
  202. package/dist/hooks/useTimeController.js.map +1 -1
  203. package/dist/hooks/useTutorial.d.ts +48 -0
  204. package/dist/hooks/useTutorial.d.ts.map +1 -0
  205. package/dist/hooks/useTutorial.js +16 -0
  206. package/dist/hooks/useTutorial.js.map +1 -0
  207. package/dist/index.d.ts +36 -0
  208. package/dist/index.d.ts.map +1 -1
  209. package/dist/index.html +12 -0
  210. package/dist/index.js +19 -2
  211. package/dist/index.js.map +1 -1
  212. package/dist/main.0792d734cde2c688d5f7.hot-update.js +16991 -0
  213. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +1 -0
  214. package/dist/main.0792d734cde2c688d5f7.hot-update.json +1 -0
  215. package/dist/pretty-chitty.js +204513 -0
  216. package/dist/pretty-chitty.js.map +1 -0
  217. package/dist/rendering/CameraWrapperPerspective.d.ts +5 -0
  218. package/dist/rendering/CameraWrapperPerspective.d.ts.map +1 -1
  219. package/dist/rendering/CameraWrapperPerspective.js +16 -0
  220. package/dist/rendering/CameraWrapperPerspective.js.map +1 -1
  221. package/dist/rendering/ChitGalleryItemInstance.d.ts +1 -0
  222. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  223. package/dist/rendering/ChitGalleryItemInstance.js +12 -0
  224. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  225. package/dist/rendering/ChitRenderInstance.d.ts +9 -1
  226. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  227. package/dist/rendering/ChitRenderInstance.js +28 -0
  228. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  229. package/dist/rendering/RootChitRenderInstance.d.ts +2 -0
  230. package/dist/rendering/RootChitRenderInstance.d.ts.map +1 -1
  231. package/dist/rendering/RootChitRenderInstance.js +29 -0
  232. package/dist/rendering/RootChitRenderInstance.js.map +1 -1
  233. package/dist/utilities/Annotations.d.ts +15 -0
  234. package/dist/utilities/Annotations.d.ts.map +1 -1
  235. package/dist/utilities/Annotations.js +31 -7
  236. package/dist/utilities/Annotations.js.map +1 -1
  237. package/dist/utilities/CanvasStack/CanvasStack.d.ts +2 -0
  238. package/dist/utilities/CanvasStack/CanvasStack.d.ts.map +1 -1
  239. package/dist/utilities/CanvasStack/CanvasStack.js +4 -0
  240. package/dist/utilities/CanvasStack/CanvasStack.js.map +1 -1
  241. package/dist/utilities/TokenizedText.d.ts +6 -0
  242. package/dist/utilities/TokenizedText.d.ts.map +1 -1
  243. package/dist/utilities/TokenizedText.js.map +1 -1
  244. package/dist/utilities/zIndex.d.ts +1 -0
  245. package/dist/utilities/zIndex.d.ts.map +1 -1
  246. package/dist/utilities/zIndex.js +1 -0
  247. package/dist/utilities/zIndex.js.map +1 -1
  248. package/package.json +3 -2
  249. package/src/library/components/ActionLogDisplay.tsx +1 -0
  250. package/src/library/components/BottomBarButton.tsx +5 -0
  251. package/src/library/components/ContextGalleryDisplay.tsx +2 -0
  252. package/src/library/components/DemoWrapper.tsx +147 -44
  253. package/src/library/components/FullScreenGalleryDisplay.tsx +3 -0
  254. package/src/library/components/Gallery/BuiltItem.ts +30 -9
  255. package/src/library/components/Gallery/GalleryController.ts +72 -1
  256. package/src/library/components/Gallery/GalleryViewer.tsx +54 -10
  257. package/src/library/components/Gallery/LayoutManager.ts +30 -6
  258. package/src/library/components/Gallery/constants.ts +2 -0
  259. package/src/library/components/Gallery/registry.ts +44 -0
  260. package/src/library/components/GameDesigner.tsx +121 -12
  261. package/src/library/components/InlineGalleryDisplay.tsx +5 -0
  262. package/src/library/components/LiveButton.tsx +8 -5
  263. package/src/library/components/MatchViewer.tsx +14 -3
  264. package/src/library/components/Panel/MultiPanel.tsx +21 -0
  265. package/src/library/components/Panel/PanelContents.tsx +70 -1
  266. package/src/library/components/Panel/PanelTabStack.tsx +1 -0
  267. package/src/library/components/PanelSpark.tsx +9 -4
  268. package/src/library/components/Playground.tsx +48 -21
  269. package/src/library/components/PromptControls.tsx +7 -3
  270. package/src/library/components/SparkLineChart.tsx +23 -27
  271. package/src/library/components/TimeControlBar.tsx +5 -3
  272. package/src/library/components/TokenizedMarkdown.tsx +224 -0
  273. package/src/library/components/TokenizedMessage.tsx +28 -32
  274. package/src/library/components/TopBarPlayers.tsx +12 -9
  275. package/src/library/components/Tutorial/BrowserNarration.ts +233 -0
  276. package/src/library/components/Tutorial/TutorialBox.tsx +506 -0
  277. package/src/library/components/Tutorial/TutorialDevPanel.tsx +297 -0
  278. package/src/library/components/Tutorial/TutorialOverlay.tsx +1301 -0
  279. package/src/library/components/Tutorial/targetRects.ts +273 -0
  280. package/src/library/game/Chit.ts +21 -5
  281. package/src/library/game/ClientTimeState.ts +18 -0
  282. package/src/library/game/Game.ts +7 -0
  283. package/src/library/game/GameTheme.ts +4 -0
  284. package/src/library/game/Match.ts +12 -2
  285. package/src/library/game/Pick.ts +16 -1
  286. package/src/library/game/PlayerPromptStatusChit.ts +5 -1
  287. package/src/library/game/Prompt.ts +20 -0
  288. package/src/library/game/Turn.ts +179 -61
  289. package/src/library/game/TurnState.ts +26 -3
  290. package/src/library/game/ai/AI_GUIDE.md +10 -0
  291. package/src/library/game/ai/AiClientPrompts.ts +60 -11
  292. package/src/library/game/ai/AiPlayerView.ts +2 -0
  293. package/src/library/game/clientTransport/ClientPrompts.ts +31 -1
  294. package/src/library/game/clientTransport/ClientTime.ts +54 -13
  295. package/src/library/game/serialize.test.ts +275 -0
  296. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +411 -0
  297. package/src/library/game/tutorial/TutorialController.test.ts +731 -0
  298. package/src/library/game/tutorial/TutorialController.ts +1286 -0
  299. package/src/library/game/tutorial/TutorialRuntime.ts +311 -0
  300. package/src/library/game/tutorial/TutorialTheme.ts +67 -0
  301. package/src/library/game/tutorial/allowed.ts +145 -0
  302. package/src/library/game/tutorial/checks.ts +186 -0
  303. package/src/library/game/tutorial/createDemoMatch.ts +115 -0
  304. package/src/library/game/tutorial/defineTutorial.ts +414 -0
  305. package/src/library/game/tutorial/runTutorial.ts +331 -0
  306. package/src/library/game/undo.test.ts +282 -0
  307. package/src/library/hooks/usePanelNavigation.tsx +65 -0
  308. package/src/library/hooks/useTimeController.tsx +6 -2
  309. package/src/library/hooks/useTutorial.tsx +76 -0
  310. package/src/library/index.ts +57 -2
  311. package/src/library/rendering/CameraWrapperPerspective.ts +17 -0
  312. package/src/library/rendering/ChitGalleryItemInstance.ts +12 -0
  313. package/src/library/rendering/ChitRenderInstance.ts +34 -0
  314. package/src/library/rendering/RootChitRenderInstance.ts +30 -1
  315. package/src/library/utilities/Annotations.ts +35 -7
  316. package/src/library/utilities/CanvasStack/CanvasStack.ts +6 -1
  317. package/src/library/utilities/TokenizedText.ts +6 -0
  318. package/src/library/utilities/zIndex.ts +1 -0
@@ -0,0 +1,311 @@
1
+ import { EventChannel } from "../../utilities/EventChannel";
2
+ import type { RngSource } from "../TurnState";
3
+ import type { AiDecision, AiPlayerOptions } from "../ai/AiClientPrompts";
4
+ import type { AiPlayerHandle } from "../ai/connectAiPlayer";
5
+ import type { PromptSerialization } from "../Prompt";
6
+ import type { AiContext, AiOption } from "../ai/defineAi";
7
+ import { PlayerChit } from "../PlayerChit";
8
+ import { RootChit } from "../RootChit";
9
+ import { ForcedDecision, TutorialSpec, selectChits } from "./defineTutorial";
10
+
11
+ export type RngLogEntry = {
12
+ index: number;
13
+ count: number;
14
+ values: number[];
15
+ /** Step that declared the values, or undefined when they came from Math.random */
16
+ declaredBy?: string;
17
+ /** Step that was active when the draw happened ("setup" before the first step) */
18
+ activeStep: string;
19
+ source: "script" | "random";
20
+ mismatch: boolean;
21
+ at: number;
22
+ };
23
+
24
+ export type DecisionLogEntry = {
25
+ playerId: string;
26
+ activeStep: string;
27
+ prompt?: string;
28
+ /** Description of the forced entry that applied, or why none did */
29
+ forced?: string;
30
+ declaredBy?: string;
31
+ chosen: string;
32
+ mismatch: boolean;
33
+ at: number;
34
+ };
35
+
36
+ type RngQueueEntry = { stepId: string; value: number | number[] };
37
+ type AiQueueEntry<P extends PlayerChit, R extends RootChit<P>> = { stepId: string; decision: ForcedDecision<P, R> };
38
+
39
+ const SETUP = "setup";
40
+
41
+ function describeOption(o: AiOption): string {
42
+ switch (o.kind) {
43
+ case "chit":
44
+ return `${o.key ?? "?"} ${o.chit}`;
45
+ case "drag":
46
+ return `${o.key ?? "?"} ${o.chit} → ${o.target}`;
47
+ case "button":
48
+ return `${o.key ?? "?"} [${o.button.label}]`;
49
+ }
50
+ }
51
+
52
+ function describeForced(d: ForcedDecision<any, any>): string {
53
+ const parts: string[] = [];
54
+ if (d.key) parts.push(d.key);
55
+ if (d.chit) parts.push("chit");
56
+ if (d.target) parts.push("→target");
57
+ if (d.button) parts.push(`[${d.button}]`);
58
+ return parts.join(" ") || "(any)";
59
+ }
60
+
61
+ /**
62
+ * What a running tutorial shares between the match (random draws, bot moves) and the overlay (which
63
+ * step is active). One per tutorial match. The Playground's dev panel reads the logs.
64
+ *
65
+ * @group Tutorials
66
+ */
67
+ export class TutorialRuntime<P extends PlayerChit = PlayerChit, R extends RootChit<P> = RootChit<P>> {
68
+ /** Id of the step the overlay is showing; "setup" before the tutorial starts. */
69
+ public activeStep = new EventChannel<string>(SETUP);
70
+ public rngLog = new EventChannel<RngLogEntry[]>([]);
71
+ public decisionLog = new EventChannel<DecisionLogEntry[]>([]);
72
+ public warnings = new EventChannel<string[]>([]);
73
+
74
+ private rngQueue: RngQueueEntry[] = [];
75
+ private rngIndex = 0;
76
+ private aiQueues: { [playerId: string]: AiQueueEntry<P, R>[] } = {};
77
+ private aiIndex: { [playerId: string]: number } = {};
78
+ private snapshots = new Map<string, { state: unknown; rngIndex: number; aiIndex: { [playerId: string]: number } }>();
79
+
80
+ /**
81
+ * Remembers the match as it was when `stepId` went live (its serialized `TurnState`) together with
82
+ * where the pinned draws and forced moves had got to, so Back can rebuild the match from there.
83
+ */
84
+ public saveSnapshot(stepId: string, state: unknown) {
85
+ // The first snapshot of a step wins: re-entering it after a rewind must not overwrite it with
86
+ // the board as it was before the rewind landed
87
+ if (this.snapshots.has(stepId)) return;
88
+ this.snapshots.set(stepId, { state, rngIndex: this.rngIndex, aiIndex: { ...this.aiIndex } });
89
+ }
90
+
91
+ public hasSnapshot(stepId: string) {
92
+ return this.snapshots.has(stepId);
93
+ }
94
+
95
+ /**
96
+ * Takes another run's snapshots in place of this one's (a headless play-through of the same script),
97
+ * so Back and `restoreSnapshot` reach every step that run got to.
98
+ */
99
+ public adoptSnapshots(from: TutorialRuntime<P, R>) {
100
+ this.snapshots = new Map(from.snapshots);
101
+ }
102
+
103
+ /** Rewinds the queues to where they were at `stepId` and returns the match state to rebuild from. */
104
+ public restoreSnapshot(stepId: string): unknown | undefined {
105
+ const snap = this.snapshots.get(stepId);
106
+ if (!snap) return undefined;
107
+ // Steps after this one will be played again, possibly differently: forget their snapshots
108
+ const order = (this.spec?.steps ?? []).map((s) => s.id);
109
+ const at = order.indexOf(stepId);
110
+ order.slice(at + 1).forEach((id) => this.snapshots.delete(id));
111
+ this.rngIndex = snap.rngIndex;
112
+ this.aiIndex = { ...snap.aiIndex };
113
+ this.pendingForced = {};
114
+ this.activeStep.value = stepId;
115
+ return snap.state;
116
+ }
117
+
118
+ constructor(public readonly spec: TutorialSpec<P, R> | undefined) {
119
+ (spec?.match?.rng ?? []).forEach((value) => this.rngQueue.push({ stepId: SETUP, value }));
120
+ (spec?.steps ?? []).forEach((step) => {
121
+ (step.rng ?? []).forEach((value) => this.rngQueue.push({ stepId: step.id, value }));
122
+ Object.entries(step.ai ?? {}).forEach(([playerId, decisions]) => {
123
+ const q = (this.aiQueues[playerId] ??= []);
124
+ decisions.forEach((decision) => q.push({ stepId: step.id, decision }));
125
+ });
126
+ });
127
+ }
128
+
129
+ /** Pinned draws left to hand out */
130
+ get rngRemaining() {
131
+ return this.rngQueue.length - this.rngIndex;
132
+ }
133
+
134
+ /** Forced moves left per bot */
135
+ aiRemaining(playerId: string) {
136
+ return (this.aiQueues[playerId]?.length ?? 0) - (this.aiIndex[playerId] ?? 0);
137
+ }
138
+
139
+ private warn(message: string) {
140
+ if (this.spec?.strict) {
141
+ throw new Error(`[tutorial ${this.spec.id}] ${message}`);
142
+ }
143
+ console.warn(`[tutorial ${this.spec?.id ?? ""}] ${message}`);
144
+ this.warnings.value = [...this.warnings.value, message];
145
+ }
146
+
147
+ private pendingForced: { [playerId: string]: { description: string; declaredBy?: string; mismatch: boolean } } = {};
148
+
149
+ /** The `RngSource` to give the match. */
150
+ public readonly rngSource: RngSource = (count: number) => {
151
+ const index = this.rngIndex;
152
+ const entry = this.rngQueue[index];
153
+ const active = this.activeStep.value;
154
+ let values: number[] | undefined;
155
+ let mismatch = false;
156
+ if (entry) {
157
+ this.rngIndex++;
158
+ values = Array.isArray(entry.value) ? entry.value : [entry.value];
159
+ if (values.length !== count) {
160
+ this.warn(
161
+ `rng draw #${index} (declared by step "${entry.stepId}") has ${values.length} value(s) but the game asked for ${count}`,
162
+ );
163
+ values = undefined;
164
+ } else if (entry.stepId !== active) {
165
+ mismatch = true;
166
+ this.warn(`rng draw #${index} was declared by step "${entry.stepId}" but consumed during "${active}"`);
167
+ }
168
+ }
169
+ const log = this.rngLog.value;
170
+ this.rngLog.value = [
171
+ ...log,
172
+ {
173
+ index,
174
+ count,
175
+ values: values ?? [],
176
+ declaredBy: entry?.stepId,
177
+ activeStep: active,
178
+ source: values ? "script" : "random",
179
+ mismatch,
180
+ at: Date.now(),
181
+ },
182
+ ];
183
+ if (!values) {
184
+ // Let TurnState draw from Math.random and record what it drew
185
+ const drawn = Array.from({ length: count }, () => Math.random());
186
+ const entries = this.rngLog.value;
187
+ entries[entries.length - 1] = { ...entries[entries.length - 1], values: drawn };
188
+ this.rngLog.value = [...entries];
189
+ return drawn;
190
+ }
191
+ return values;
192
+ };
193
+
194
+ /** AI options (the `choose`, `hold` and `onDecision` hooks) for the bot in `playerId`'s seat. */
195
+ public aiOptionsFor(playerId: string): Pick<AiPlayerOptions, "choose" | "hold" | "onDecision"> {
196
+ return {
197
+ choose: (scored, ctx) => this.choose(playerId, scored, ctx),
198
+ hold: (prompt) => this.waitingForStep(playerId, prompt),
199
+ onDecision: (decision) => this.recordDecision(playerId, decision),
200
+ };
201
+ }
202
+
203
+ private bots: AiPlayerHandle[] = [];
204
+ private unsubActiveStep?: () => void;
205
+
206
+ /** The bots to wake when the active step changes (a held bot's move may now be due) */
207
+ public attachBots(bots: AiPlayerHandle[]) {
208
+ this.bots = bots;
209
+ this.unsubActiveStep?.();
210
+ this.unsubActiveStep = this.activeStep.on(() => this.bots.forEach((b) => b.prompts.recheck()), false);
211
+ }
212
+
213
+ /** Position of a step in the script: -1 for setup, past the end once the tutorial is over */
214
+ private stepOrder(stepId: string) {
215
+ if (stepId === SETUP) return -1;
216
+ const index = (this.spec?.steps ?? []).findIndex((s) => s.id === stepId);
217
+ return index < 0 ? Number.POSITIVE_INFINITY : index;
218
+ }
219
+
220
+ /**
221
+ * A bot whose next scripted move belongs to a step that is not on screen yet waits for it, so the
222
+ * move happens while that step is narrating it. The engine's own Confirm (ending a turn or
223
+ * confirming a draw) goes through unless that Confirm is the scripted move: holding it would
224
+ * deadlock a bot that has to finish a turn before its next scripted step can come.
225
+ */
226
+ private waitingForStep(playerId: string, prompt?: PromptSerialization) {
227
+ const entry = this.aiQueues[playerId]?.[this.aiIndex[playerId] ?? 0];
228
+ if (!entry) return false;
229
+ if (prompt && isConfirmOnly(prompt) && entry.decision.button?.toLowerCase() !== "confirm") return false;
230
+ return this.stepOrder(entry.stepId) > this.stepOrder(this.activeStep.value);
231
+ }
232
+
233
+ private choose(
234
+ playerId: string,
235
+ scored: { option: AiOption; score: number }[],
236
+ ctx: AiContext<any, any, any>,
237
+ ): number | undefined {
238
+ const queue = this.aiQueues[playerId];
239
+ const index = this.aiIndex[playerId] ?? 0;
240
+ const entry = queue?.[index];
241
+ delete this.pendingForced[playerId];
242
+ if (!entry) {
243
+ return undefined;
244
+ }
245
+ const root = ctx.view as R;
246
+ const me = ctx.me as P;
247
+ const d = entry.decision;
248
+ // The engine's own Confirm: answered as usual unless the scripted move is that Confirm
249
+ const onlyConfirms = scored.every((s) => s.option.kind === "button" && s.option.pick.buttonType === "Confirm");
250
+ if (onlyConfirms && d.button?.toLowerCase() !== "confirm") {
251
+ return undefined;
252
+ }
253
+ if (d.when && !d.when(root, me)) {
254
+ return undefined;
255
+ }
256
+ const chits = d.chit ? new Set(selectChits(d.chit, root, me).map((c) => c.id)) : undefined;
257
+ const targets = d.target ? new Set(selectChits(d.target, root, me).map((c) => c.id)) : undefined;
258
+ const matching = scored
259
+ .map((s, i) => ({ s, i }))
260
+ .filter(({ s }) => {
261
+ const o = s.option;
262
+ if (d.key !== undefined && o.key !== d.key) return false;
263
+ if (chits && !(o.kind !== "button" && chits.has(o.chit.id))) return false;
264
+ if (targets && !(o.kind === "drag" && targets.has(o.target.id))) return false;
265
+ if (d.button !== undefined && !(o.kind === "button" && o.button.label.toLowerCase() === d.button.toLowerCase()))
266
+ return false;
267
+ return true;
268
+ });
269
+ const description = describeForced(d);
270
+ if (matching.length === 0) {
271
+ this.warn(
272
+ `bot ${playerId}: forced move ${description} (declared by step "${entry.stepId}") matches none of ${scored.length} option(s) in "${ctx.prompt.message ?? ""}"; playing normally`,
273
+ );
274
+ this.pendingForced[playerId] = { description: `${description} (no match)`, declaredBy: entry.stepId, mismatch: true };
275
+ return undefined;
276
+ }
277
+ this.aiIndex[playerId] = index + 1;
278
+ const active = this.activeStep.value;
279
+ const mismatch = entry.stepId !== active;
280
+ if (mismatch) {
281
+ this.warn(`bot ${playerId}: forced move ${description} was declared by step "${entry.stepId}" but used during "${active}"`);
282
+ }
283
+ this.pendingForced[playerId] = { description, declaredBy: entry.stepId, mismatch };
284
+ return matching[0].i;
285
+ }
286
+
287
+ private recordDecision(playerId: string, decision: AiDecision) {
288
+ const forced = this.pendingForced[playerId];
289
+ delete this.pendingForced[playerId];
290
+ const chosen = decision.scored[decision.chosen]?.option;
291
+ this.decisionLog.value = [
292
+ ...this.decisionLog.value,
293
+ {
294
+ playerId,
295
+ activeStep: this.activeStep.value,
296
+ prompt: decision.prompt.message,
297
+ forced: forced?.description,
298
+ declaredBy: forced?.declaredBy,
299
+ chosen: chosen ? describeOption(chosen) : "?",
300
+ mismatch: forced?.mismatch ?? false,
301
+ at: Date.now(),
302
+ },
303
+ ];
304
+ }
305
+ }
306
+
307
+ /** A prompt whose only options are the engine's Confirm button */
308
+ function isConfirmOnly(prompt: PromptSerialization): boolean {
309
+ const picks: { type?: string; details?: { __buttonType?: string } }[] = prompt.details?.picks ?? [];
310
+ return picks.length > 0 && picks.every((p) => p.type === "ButtonPick" && p.details?.__buttonType === "Confirm");
311
+ }
@@ -0,0 +1,67 @@
1
+ import Color from "color";
2
+ import { GameTheme } from "../GameTheme";
3
+
4
+ /**
5
+ * Colours and type for the tutorial overlay. Defaults are derived from the game's theme; a game can
6
+ * set `GameTheme.tutorial`, a spec can set `theme`, and a host can pass `tutorialTheme`, in that order
7
+ * of precedence (last wins).
8
+ *
9
+ * @group Tutorials
10
+ */
11
+ export type TutorialTheme = {
12
+ boxBackground: string;
13
+ boxTextColor: string;
14
+ /** Buttons, progress, the emphasised sentence */
15
+ accent: string;
16
+ boxShadow: string;
17
+ borderRadius: number;
18
+ arrowColor: string;
19
+ highlightColor: string;
20
+ highlightGlow: string;
21
+ dimColor: string;
22
+ dimOpacity: number;
23
+ fontFamily: string;
24
+ fontScalar: number;
25
+ /** Width of the box on large screens, in px */
26
+ boxWidth: number;
27
+ };
28
+
29
+ export function defaultTutorialTheme(theme: GameTheme): TutorialTheme {
30
+ const text = theme.barActiveTextColor;
31
+ const accent = theme.chitHighlightColor;
32
+ let background: string;
33
+ try {
34
+ background = Color(theme.barColor).alpha(0.96).hexa();
35
+ } catch {
36
+ background = "rgba(20,20,30,0.96)";
37
+ }
38
+ return {
39
+ boxBackground: background,
40
+ boxTextColor: text,
41
+ accent,
42
+ boxShadow: "0 10px 30px rgba(0,0,0,0.45)",
43
+ borderRadius: 14,
44
+ arrowColor: accent,
45
+ highlightColor: accent,
46
+ highlightGlow: (() => {
47
+ try {
48
+ return Color(accent).alpha(0.55).hexa();
49
+ } catch {
50
+ return accent;
51
+ }
52
+ })(),
53
+ dimColor: "#000000",
54
+ dimOpacity: 0.55,
55
+ fontFamily: theme.fontFamily,
56
+ fontScalar: theme.fontScalar,
57
+ boxWidth: 360,
58
+ ...(theme.tutorial ?? {}),
59
+ };
60
+ }
61
+
62
+ export function resolveTutorialTheme(
63
+ gameTheme: GameTheme,
64
+ ...overrides: (Partial<TutorialTheme> | undefined)[]
65
+ ): TutorialTheme {
66
+ return overrides.reduce<TutorialTheme>((acc, o) => ({ ...acc, ...(o ?? {}) }), defaultTutorialTheme(gameTheme));
67
+ }
@@ -0,0 +1,145 @@
1
+ import { Chit } from "../Chit";
2
+ import { ButtonPick, ChitPick, DragPick, Pick } from "../Pick";
3
+ import { PlayerChit } from "../PlayerChit";
4
+ import { RootChit } from "../RootChit";
5
+ import type { PickPrompt, PromptAction } from "../Prompt";
6
+ import type { AiOption } from "../ai/defineAi";
7
+ import { AllowedAction, ChitSelector, TutorialStep, selectChits } from "./defineTutorial";
8
+
9
+ /** A move in a form both the client prompt and the AI option list can be reduced to. @internal */
10
+ export type MoveShape = {
11
+ kind: "chit" | "drag" | "button";
12
+ key?: string;
13
+ chitId?: string;
14
+ targetId?: string;
15
+ buttonLabel?: string;
16
+ };
17
+
18
+ /** @internal */
19
+ export function shapeOfPromptAction(action: PromptAction): MoveShape | undefined {
20
+ if (action.type !== "pick") return undefined;
21
+ const pick: Pick = action.pick;
22
+ const key = pick.aiTag?.k;
23
+ if (pick instanceof ChitPick) {
24
+ return { kind: "chit", key, chitId: action.value as string };
25
+ }
26
+ if (pick instanceof DragPick) {
27
+ const v = action.value as { chitId: string; targetChitId: string };
28
+ return { kind: "drag", key, chitId: v?.chitId, targetId: v?.targetChitId };
29
+ }
30
+ if (pick instanceof ButtonPick) {
31
+ return { kind: "button", key, buttonLabel: pick.button?.label };
32
+ }
33
+ return undefined;
34
+ }
35
+
36
+ /** @internal */
37
+ export function shapeOfAiOption(o: AiOption): MoveShape {
38
+ switch (o.kind) {
39
+ case "chit":
40
+ return { kind: "chit", key: o.key, chitId: o.chit.id };
41
+ case "drag":
42
+ return { kind: "drag", key: o.key, chitId: o.chit.id, targetId: o.target.id };
43
+ case "button":
44
+ return { kind: "button", key: o.key, buttonLabel: o.button.label };
45
+ }
46
+ }
47
+
48
+ /** Whether a move matches one of the step's allowed actions (none allowed when the step lists none). @internal */
49
+ export function isAllowed<P extends PlayerChit, R extends RootChit<P>>(
50
+ allow: AllowedAction<P, R> | AllowedAction<P, R>[] | undefined,
51
+ move: MoveShape,
52
+ root: R | undefined,
53
+ me: P | undefined,
54
+ ): boolean {
55
+ if (!allow) return false;
56
+ const list = Array.isArray(allow) ? allow : [allow];
57
+ const ids = (sel: ChitSelector<P, R>) => new Set(selectChits<P, R>(sel, root, me).map((c: Chit) => c.id));
58
+ return list.some((a) => {
59
+ if (a === "any") return true;
60
+ if (a.ui !== undefined) return false; // a UI control, never a game move
61
+ if (a.key !== undefined && move.key !== a.key) return false;
62
+ if (a.chit && (move.kind === "button" || !ids(a.chit).has(move.chitId))) return false;
63
+ if (a.target && (move.kind !== "drag" || !ids(a.target).has(move.targetId))) return false;
64
+ if (
65
+ a.button !== undefined &&
66
+ (move.kind !== "button" || (move.buttonLabel ?? "").toLowerCase() !== a.button.toLowerCase())
67
+ )
68
+ return false;
69
+ return true;
70
+ });
71
+ }
72
+
73
+ /** Steps that wait for the player but allow nothing: a script bug worth flagging. @internal */
74
+ export function stepsWithoutAllow(steps: TutorialStep<any, any>[]): string[] {
75
+ return steps.filter((s) => s.waitFor && !s.allow).map((s) => s.id);
76
+ }
77
+
78
+ /** UI names that stand for "whichever of these is showing". @internal */
79
+ export const UI_ALIASES: { [name: string]: string[] } = {
80
+ "gallery:modeButton": ["gallery:toFullscreen", "gallery:toInline"],
81
+ };
82
+
83
+ /** Whether a step's `allow` lists the UI control the player just used (by its `data-tutorial-target`). @internal */
84
+ export function allowsUi<P extends PlayerChit, R extends RootChit<P>>(
85
+ allow: AllowedAction<P, R> | AllowedAction<P, R>[] | undefined,
86
+ used: string,
87
+ ): boolean {
88
+ if (!allow) return false;
89
+ const list = Array.isArray(allow) ? allow : [allow];
90
+ return list.some(
91
+ (a) => a !== "any" && a.ui !== undefined && (a.ui === used || (UI_ALIASES[a.ui] ?? []).includes(used)),
92
+ );
93
+ }
94
+
95
+ /** One answer to a client prompt, as a tap or drag would give it. @internal */
96
+ export type PromptMove = { pick: Pick; value: unknown; shape: MoveShape };
97
+
98
+ /** Every answer the player's prompt accepts, in prompt order (chit taps, drags, buttons). @internal */
99
+ export function promptMoves(prompt: PickPrompt): PromptMove[] {
100
+ const moves: PromptMove[] = [];
101
+ for (const pick of prompt.picks) {
102
+ const key = pick.aiTag?.k;
103
+ if (pick instanceof ChitPick) {
104
+ for (const chit of pick.chits as Chit[]) {
105
+ if (chit.id) moves.push({ pick, value: chit.id, shape: { kind: "chit", key, chitId: chit.id } });
106
+ }
107
+ } else if (pick instanceof DragPick) {
108
+ const targets = pick.dropTargets.flatMap((t) => t.chits as Chit[]);
109
+ for (const chit of pick.chits as Chit[]) {
110
+ for (const target of targets) {
111
+ if (!chit.id || !target.id) continue;
112
+ moves.push({
113
+ pick,
114
+ value: { chitId: chit.id, targetChitId: target.id },
115
+ shape: { kind: "drag", key, chitId: chit.id, targetId: target.id },
116
+ });
117
+ }
118
+ }
119
+ } else if (pick instanceof ButtonPick) {
120
+ moves.push({ pick, value: null, shape: { kind: "button", key, buttonLabel: pick.button?.label } });
121
+ }
122
+ }
123
+ return moves;
124
+ }
125
+
126
+ /**
127
+ * What "do it for me" does on a step: the first entry of `allow` (in the order written) that the
128
+ * player can act on right now, as a game move from the prompt or a UI control to press. @internal
129
+ */
130
+ export function scriptedAnswer<P extends PlayerChit, R extends RootChit<P>>(
131
+ allow: AllowedAction<P, R> | AllowedAction<P, R>[] | undefined,
132
+ prompt: PickPrompt | undefined,
133
+ root: R | undefined,
134
+ me: P | undefined,
135
+ ): { move: PromptMove } | { ui: string } | undefined {
136
+ if (!allow) return undefined;
137
+ const list = Array.isArray(allow) ? allow : [allow];
138
+ const moves = prompt ? promptMoves(prompt) : [];
139
+ for (const entry of list) {
140
+ if (entry !== "any" && entry.ui !== undefined) return { ui: entry.ui };
141
+ const move = moves.find((m) => isAllowed(entry, m.shape, root, me));
142
+ if (move) return { move };
143
+ }
144
+ return undefined;
145
+ }