@pretty-chitty/core 2.1.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 (192) hide show
  1. package/dist/components/DemoWrapper.d.ts +4 -1
  2. package/dist/components/DemoWrapper.d.ts.map +1 -1
  3. package/dist/components/DemoWrapper.js +2 -4
  4. package/dist/components/DemoWrapper.js.map +1 -1
  5. package/dist/components/Gallery/BuiltItem.d.ts +10 -0
  6. package/dist/components/Gallery/BuiltItem.d.ts.map +1 -1
  7. package/dist/components/Gallery/BuiltItem.js +65 -8
  8. package/dist/components/Gallery/BuiltItem.js.map +1 -1
  9. package/dist/components/Gallery/GalleryController.d.ts +8 -0
  10. package/dist/components/Gallery/GalleryController.d.ts.map +1 -1
  11. package/dist/components/Gallery/GalleryController.js +39 -6
  12. package/dist/components/Gallery/GalleryController.js.map +1 -1
  13. package/dist/components/Gallery/GalleryViewer.d.ts.map +1 -1
  14. package/dist/components/Gallery/GalleryViewer.js +91 -2
  15. package/dist/components/Gallery/GalleryViewer.js.map +1 -1
  16. package/dist/components/Gallery/LayoutManager.d.ts +4 -0
  17. package/dist/components/Gallery/LayoutManager.d.ts.map +1 -1
  18. package/dist/components/Gallery/LayoutManager.js +36 -10
  19. package/dist/components/Gallery/LayoutManager.js.map +1 -1
  20. package/dist/components/Gallery/constants.d.ts +5 -1
  21. package/dist/components/Gallery/constants.d.ts.map +1 -1
  22. package/dist/components/Gallery/constants.js +5 -1
  23. package/dist/components/Gallery/constants.js.map +1 -1
  24. package/dist/components/Gallery/types.d.ts +5 -0
  25. package/dist/components/Gallery/types.d.ts.map +1 -1
  26. package/dist/components/GameDesigner.d.ts.map +1 -1
  27. package/dist/components/GameDesigner.js +45 -3
  28. package/dist/components/GameDesigner.js.map +1 -1
  29. package/dist/components/InlineGalleryDisplay.d.ts.map +1 -1
  30. package/dist/components/InlineGalleryDisplay.js +33 -6
  31. package/dist/components/InlineGalleryDisplay.js.map +1 -1
  32. package/dist/components/Panel/ExternalDrag.d.ts +30 -0
  33. package/dist/components/Panel/ExternalDrag.d.ts.map +1 -0
  34. package/dist/components/Panel/ExternalDrag.js +87 -0
  35. package/dist/components/Panel/ExternalDrag.js.map +1 -0
  36. package/dist/components/Panel/PanelContents.d.ts +3 -0
  37. package/dist/components/Panel/PanelContents.d.ts.map +1 -1
  38. package/dist/components/Panel/PanelContents.js +24 -0
  39. package/dist/components/Panel/PanelContents.js.map +1 -1
  40. package/dist/components/PanelSpark.d.ts.map +1 -1
  41. package/dist/components/PanelSpark.js +3 -1
  42. package/dist/components/PanelSpark.js.map +1 -1
  43. package/dist/components/TopBar.d.ts.map +1 -1
  44. package/dist/components/TopBar.js +3 -1
  45. package/dist/components/TopBar.js.map +1 -1
  46. package/dist/components/TopBarPlayers.d.ts.map +1 -1
  47. package/dist/components/TopBarPlayers.js +1 -1
  48. package/dist/components/TopBarPlayers.js.map +1 -1
  49. package/dist/components/Tutorial/TutorialOverlay.js +17 -2
  50. package/dist/components/Tutorial/TutorialOverlay.js.map +1 -1
  51. package/dist/components/Viewer.d.ts.map +1 -1
  52. package/dist/components/Viewer.js +1 -0
  53. package/dist/components/Viewer.js.map +1 -1
  54. package/dist/game/Chit.d.ts +3 -1
  55. package/dist/game/Chit.d.ts.map +1 -1
  56. package/dist/game/Chit.js +4 -1
  57. package/dist/game/Chit.js.map +1 -1
  58. package/dist/game/GalleryItemChitChildrenSource.d.ts +1 -0
  59. package/dist/game/GalleryItemChitChildrenSource.d.ts.map +1 -1
  60. package/dist/game/GalleryItemChitChildrenSource.js +1 -0
  61. package/dist/game/GalleryItemChitChildrenSource.js.map +1 -1
  62. package/dist/game/GalleryItemRawSource.d.ts +1 -0
  63. package/dist/game/GalleryItemRawSource.d.ts.map +1 -1
  64. package/dist/game/GalleryItemRawSource.js +1 -0
  65. package/dist/game/GalleryItemRawSource.js.map +1 -1
  66. package/dist/game/GameButton.d.ts +8 -0
  67. package/dist/game/GameButton.d.ts.map +1 -1
  68. package/dist/game/GameButton.js +13 -1
  69. package/dist/game/GameButton.js.map +1 -1
  70. package/dist/game/ModalState.d.ts +3 -0
  71. package/dist/game/ModalState.d.ts.map +1 -1
  72. package/dist/game/ModalState.js +2 -0
  73. package/dist/game/ModalState.js.map +1 -1
  74. package/dist/game/Pick.d.ts.map +1 -1
  75. package/dist/game/Pick.js +1 -3
  76. package/dist/game/Pick.js.map +1 -1
  77. package/dist/game/PlayerPromptStatusChit.d.ts.map +1 -1
  78. package/dist/game/PlayerPromptStatusChit.js +1 -3
  79. package/dist/game/PlayerPromptStatusChit.js.map +1 -1
  80. package/dist/game/Prompt.d.ts +3 -1
  81. package/dist/game/Prompt.d.ts.map +1 -1
  82. package/dist/game/Prompt.js +15 -3
  83. package/dist/game/Prompt.js.map +1 -1
  84. package/dist/game/SparkChit.d.ts +6 -0
  85. package/dist/game/SparkChit.d.ts.map +1 -1
  86. package/dist/game/SparkChit.js +8 -0
  87. package/dist/game/SparkChit.js.map +1 -1
  88. package/dist/game/Turn.d.ts +2 -2
  89. package/dist/game/Turn.d.ts.map +1 -1
  90. package/dist/game/Turn.js +6 -9
  91. package/dist/game/Turn.js.map +1 -1
  92. package/dist/game/clientTransport/ClientPrompts.d.ts +2 -0
  93. package/dist/game/clientTransport/ClientPrompts.d.ts.map +1 -1
  94. package/dist/game/clientTransport/ClientPrompts.js +42 -4
  95. package/dist/game/clientTransport/ClientPrompts.js.map +1 -1
  96. package/dist/game/clientTransport/ClientTime.d.ts.map +1 -1
  97. package/dist/game/clientTransport/ClientTime.js +20 -1
  98. package/dist/game/clientTransport/ClientTime.js.map +1 -1
  99. package/dist/game/tutorial/TutorialController.d.ts +9 -1
  100. package/dist/game/tutorial/TutorialController.d.ts.map +1 -1
  101. package/dist/game/tutorial/TutorialController.js +21 -8
  102. package/dist/game/tutorial/TutorialController.js.map +1 -1
  103. package/dist/game/tutorial/runTutorial.d.ts +3 -2
  104. package/dist/game/tutorial/runTutorial.d.ts.map +1 -1
  105. package/dist/game/tutorial/runTutorial.js +28 -8
  106. package/dist/game/tutorial/runTutorial.js.map +1 -1
  107. package/dist/hooks/useTimeController.d.ts +2 -0
  108. package/dist/hooks/useTimeController.d.ts.map +1 -1
  109. package/dist/hooks/useTimeController.js +4 -0
  110. package/dist/hooks/useTimeController.js.map +1 -1
  111. package/dist/hooks/useTutorial.d.ts +4 -1
  112. package/dist/hooks/useTutorial.d.ts.map +1 -1
  113. package/dist/hooks/useTutorial.js +2 -2
  114. package/dist/hooks/useTutorial.js.map +1 -1
  115. package/dist/index.d.ts +1 -0
  116. package/dist/index.d.ts.map +1 -1
  117. package/dist/index.js.map +1 -1
  118. package/dist/rendering/ChitGalleryItemInstance.d.ts +13 -3
  119. package/dist/rendering/ChitGalleryItemInstance.d.ts.map +1 -1
  120. package/dist/rendering/ChitGalleryItemInstance.js +17 -1
  121. package/dist/rendering/ChitGalleryItemInstance.js.map +1 -1
  122. package/dist/rendering/ChitRenderInstance.d.ts +6 -0
  123. package/dist/rendering/ChitRenderInstance.d.ts.map +1 -1
  124. package/dist/rendering/ChitRenderInstance.js +21 -4
  125. package/dist/rendering/ChitRenderInstance.js.map +1 -1
  126. package/dist/rendering/LightWrapper.d.ts.map +1 -1
  127. package/dist/rendering/LightWrapper.js +10 -1
  128. package/dist/rendering/LightWrapper.js.map +1 -1
  129. package/dist/rendering/Splay.d.ts +11 -0
  130. package/dist/rendering/Splay.d.ts.map +1 -1
  131. package/dist/rendering/Splay.js +20 -10
  132. package/dist/rendering/Splay.js.map +1 -1
  133. package/dist/utilities/CanvasStack/RichTextRenderer.d.ts.map +1 -1
  134. package/dist/utilities/CanvasStack/RichTextRenderer.js +12 -0
  135. package/dist/utilities/CanvasStack/RichTextRenderer.js.map +1 -1
  136. package/dist/utilities/Dice.d.ts +2 -0
  137. package/dist/utilities/Dice.d.ts.map +1 -1
  138. package/dist/utilities/Dice.js +5 -1
  139. package/dist/utilities/Dice.js.map +1 -1
  140. package/dist/utilities/GalleryItemConversion.d.ts.map +1 -1
  141. package/dist/utilities/GalleryItemConversion.js +5 -7
  142. package/dist/utilities/GalleryItemConversion.js.map +1 -1
  143. package/package.json +1 -1
  144. package/src/library/components/DemoWrapper.tsx +5 -2
  145. package/src/library/components/Gallery/BuiltItem.ts +63 -8
  146. package/src/library/components/Gallery/GalleryController.ts +39 -9
  147. package/src/library/components/Gallery/GalleryViewer.tsx +90 -2
  148. package/src/library/components/Gallery/LayoutManager.ts +40 -15
  149. package/src/library/components/Gallery/constants.ts +5 -1
  150. package/src/library/components/Gallery/types.ts +6 -0
  151. package/src/library/components/GameDesigner.tsx +46 -2
  152. package/src/library/components/InlineGalleryDisplay.tsx +36 -6
  153. package/src/library/components/Panel/ExternalDrag.ts +122 -0
  154. package/src/library/components/Panel/PanelContents.tsx +26 -0
  155. package/src/library/components/PanelSpark.tsx +3 -1
  156. package/src/library/components/TopBar.tsx +2 -1
  157. package/src/library/components/TopBarPlayers.tsx +1 -6
  158. package/src/library/components/Tutorial/TutorialOverlay.tsx +16 -1
  159. package/src/library/components/Viewer.tsx +1 -0
  160. package/src/library/game/Chit.ts +7 -2
  161. package/src/library/game/GalleryItemChitChildrenSource.ts +1 -0
  162. package/src/library/game/GalleryItemRawSource.ts +1 -0
  163. package/src/library/game/GameButton.ts +13 -1
  164. package/src/library/game/ModalState.ts +3 -0
  165. package/src/library/game/Pick.ts +1 -3
  166. package/src/library/game/PlayerPromptStatusChit.ts +1 -3
  167. package/src/library/game/Prompt.ts +15 -4
  168. package/src/library/game/SparkChit.ts +9 -0
  169. package/src/library/game/Turn.ts +6 -9
  170. package/src/library/game/clientTransport/ClientPrompts.ts +45 -4
  171. package/src/library/game/clientTransport/ClientTime.ts +21 -1
  172. package/src/library/game/tutorial/TUTORIAL_GUIDE.md +11 -6
  173. package/src/library/game/tutorial/TutorialController.test.ts +4 -4
  174. package/src/library/game/tutorial/TutorialController.ts +20 -7
  175. package/src/library/game/tutorial/runTutorial.ts +29 -10
  176. package/src/library/hooks/useTimeController.tsx +4 -0
  177. package/src/library/hooks/useTutorial.tsx +6 -2
  178. package/src/library/index.ts +1 -0
  179. package/src/library/rendering/ChitGalleryItemInstance.ts +18 -1
  180. package/src/library/rendering/ChitRenderInstance.ts +23 -4
  181. package/src/library/rendering/LightWrapper.ts +10 -1
  182. package/src/library/rendering/Splay.test.ts +60 -0
  183. package/src/library/rendering/Splay.ts +30 -9
  184. package/src/library/utilities/CanvasStack/RichTextRenderer.ts +13 -0
  185. package/src/library/utilities/Dice.tsx +5 -1
  186. package/src/library/utilities/GalleryItemConversion.ts +5 -6
  187. package/dist/index.html +0 -12
  188. package/dist/main.0792d734cde2c688d5f7.hot-update.js +0 -16991
  189. package/dist/main.0792d734cde2c688d5f7.hot-update.js.map +0 -1
  190. package/dist/main.0792d734cde2c688d5f7.hot-update.json +0 -1
  191. package/dist/pretty-chitty.js +0 -204513
  192. package/dist/pretty-chitty.js.map +0 -1
@@ -4,6 +4,8 @@ import { Connection } from "../Connection";
4
4
  import { ConnectionObject } from "../ConnectionObject";
5
5
  import { PlayerChit } from "../PlayerChit";
6
6
  import { PickPrompt, Prompt, PromptAction, PromptSerialization } from "../Prompt";
7
+ import type { Chit } from "../Chit";
8
+ import type { FindChit } from "../Pick";
7
9
  import { RootChit } from "../RootChit";
8
10
  import { ServerPrompts } from "../serverTransport/ServerPrompts";
9
11
  import { ClientTime } from "./ClientTime";
@@ -51,9 +53,43 @@ export class ClientPrompts<P extends PlayerChit, R extends RootChit<P>> extends
51
53
  }
52
54
  }
53
55
 
54
- private stageInPrompt(promptSpec: PromptSerialization) {
55
- this._currentPromptSpec = promptSpec;
56
- const prompt = Prompt.deserialize(promptSpec, this.clientTime.findChit, this.clientTime.game.buttonLibrary);
56
+ /** The staged prompt was inflated without some of its chits (staged in early): it is staged in again on time */
57
+ private _provisional = false;
58
+
59
+ private stageInPrompt(promptSpec: PromptSerialization, early = false) {
60
+ // A chit the prompt names that the client has not got. Staged in early (a pick asked for it, so the piece is
61
+ // still animating in), the board is a clock behind the prompt and a chit made in the prompt's own flush (a
62
+ // fresh drop target) is not here yet: it is left out, and the prompt is staged in again, whole, once the
63
+ // board catches up. On time, a missing chit is a bug to report, never an exception: this runs inside the
64
+ // client's state update (a clock listener), and an exception here left the board half-updated with the
65
+ // previous prompt still up, which swallowed every later move ("it gets stuck on me dragging my dealer").
66
+ const missing: string[] = [];
67
+ const find: FindChit = (id) => {
68
+ const chit = this.clientTime.findChitUnsafe(id);
69
+ if (!chit) missing.push(id);
70
+ return chit as Chit; // every pick drops a falsy chit (`.filter((d) => d)`)
71
+ };
72
+ let prompt: Prompt;
73
+ try {
74
+ prompt = Prompt.deserialize(promptSpec, find, this.clientTime.game.buttonLibrary);
75
+ } catch (e) {
76
+ console.error(`[prompt] could not inflate "${promptSpec.id}" at clock ${JSON.stringify(this.clientTime.currentClock.value)}:`, e);
77
+ // the caller already staged the previous prompt out: it must not stay up as the current one
78
+ this._currentPromptSpec = undefined;
79
+ this._provisional = false;
80
+ this.currentPrompt.value = undefined;
81
+ this.fixActiveLog();
82
+ return;
83
+ }
84
+ if (missing.length && !early) {
85
+ console.error(
86
+ `[prompt] "${promptSpec.id}" names chits the client has not got at clock ${JSON.stringify(this.clientTime.currentClock.value)} (latest ${JSON.stringify(this.clientTime.maxClock.value)}): ${missing.join(", ")}`,
87
+ );
88
+ }
89
+ // Only an early stage-in is provisional: on time the board will not catch up any further, so restaging it on every
90
+ // later clock event would only tear it down and log the same error again
91
+ this._provisional = early && missing.length > 0;
92
+ this._currentPromptSpec = this._provisional ? undefined : promptSpec;
57
93
  if (prompt instanceof PickPrompt) {
58
94
  prompt.guard = (action) => {
59
95
  if (!this.guard) {
@@ -109,6 +145,11 @@ export class ClientPrompts<P extends PlayerChit, R extends RootChit<P>> extends
109
145
  !isWaitingOnAnimations &&
110
146
  samePasses(this.clientTime.currentClock.value, this.clientTime.maxClock.value)
111
147
  ) {
148
+ // Staged in early and whole: it is the prompt
149
+ if (this.currentPrompt.value && !this._provisional && this.currentPrompt.value.isSameSerialization(promptSpec)) {
150
+ this._currentPromptSpec = promptSpec;
151
+ return;
152
+ }
112
153
  if (this.currentPrompt.value) {
113
154
  this.currentPrompt.value.stageOut();
114
155
  }
@@ -129,7 +170,7 @@ export class ClientPrompts<P extends PlayerChit, R extends RootChit<P>> extends
129
170
  if (this.currentPrompt.value) {
130
171
  this.currentPrompt.value.stageOut();
131
172
  }
132
- this.stageInPrompt(promptSpec);
173
+ this.stageInPrompt(promptSpec, true);
133
174
  } else {
134
175
  this._currentPromptSpec = undefined;
135
176
  if (this.currentPrompt.value) {
@@ -6,6 +6,7 @@ import { ClockDetails, samePasses } from "../ClockDetails";
6
6
  import { Connection } from "../Connection";
7
7
  import { ConnectionObject } from "../ConnectionObject";
8
8
  import { Game } from "../Game";
9
+ import { OrderedOutlet } from "../OrderedOutlet";
9
10
  import { RootChit } from "../RootChit";
10
11
  import { ServerTime } from "../serverTransport/ServerTime";
11
12
  import { ClientPrompts } from "./ClientPrompts";
@@ -70,7 +71,7 @@ export class ClientTime extends ConnectionObject {
70
71
  public readonly findChit: (id: string) => Chit = (id: string) => {
71
72
  const result = this.chitLookup[id];
72
73
  if (!result) {
73
- throw new Error("Cannot find chit");
74
+ throw new Error(`Cannot find chit ${id}`);
74
75
  }
75
76
  return result;
76
77
  };
@@ -228,6 +229,25 @@ export class ClientTime extends ConnectionObject {
228
229
 
229
230
  chits.forEach((chit) => chit.doneDeserializing());
230
231
 
232
+ // A dragged chit is moved onto its drop target here as the drag ends, before the server answers. Its state
233
+ // then puts it back under its real parent, but into an ordered outlet only the parent's own state fills: when
234
+ // the parent did not change (a piece moved within a factory), the chit was its child yet missing from the
235
+ // list, so anything reading the list lost it ("it gets stuck on me dragging my dealer"). Load such a parent
236
+ // again from its current state.
237
+ const owners = new Set<Chit>();
238
+ chits.forEach((chit) => {
239
+ const parent = chit.parent;
240
+ const outlet = parent && chit.parentOutlet ? (parent as any)[chit.parentOutlet] : undefined;
241
+ if (outlet instanceof OrderedOutlet && !outlet.some((c) => c === chit) && parent!.id && this.lastSerializedState[parent!.id]) {
242
+ owners.add(parent!);
243
+ }
244
+ });
245
+ owners.forEach((owner) => {
246
+ owner.beginDeserializing();
247
+ owner.deserialize(this.lastSerializedState[owner.id!], this.findChit, true);
248
+ owner.doneDeserializing();
249
+ });
250
+
231
251
  this.rootChit.value = this.findChit("root") as RootChit<any>;
232
252
 
233
253
  // sometimes deserializing chits does not result in animations (maybe a pure texture change?)
@@ -172,7 +172,8 @@ Rules of thumb:
172
172
  (a tab sliding, a sentence with no ring) so it does not blink.
173
173
  - **Point at parts of a chit** with `{ chit, offset: { y: 0.3 } }` (bbox units, half-extent 0.5, +y
174
174
  toward the top of the chit) and `scale: { y: 0.3 }` to ring a band of it.
175
- - **UI targets:** `button:<Label>`, `undo`, `log`, `time`, `players`, `prompt`,
175
+ - **UI targets:** `button:<Label>`, `undo`, `log`, `time`, `players`, `dropdown:<chitId>` (a top-bar dropdown such as
176
+ a player aid: `(root) => \`dropdown:${root.playerAid.id}\``), `prompt`,
176
177
  `spark:<chitId>` (a counter, use `(root, me) => \`spark:${me.coins.id}\``), `panelTab:<chitId>`,
177
178
  and the gallery ones below. Any component can expose more with a `data-tutorial-target` attribute.
178
179
  - **Last step** has `end: "continue"` (keep playing) or `"back"`.
@@ -367,11 +368,15 @@ step waiting for the player's move, → makes the move for them: the first entry
367
368
  same guard as a tap, so the game sees an ordinary move. Pressing → over and over plays the whole
368
369
  tutorial. While the sentence recorder is on, Space marks a sentence instead.
369
370
 
370
- In the workbench, clicking a later step **plays through to it**: narration skipped, animations
371
- rushed, the player's moves made the same way, the bots playing as scripted. It waits for the board
372
- to settle before each step, and the step it lands on plays as usual. Alt-click jumps without
373
- playing. Back, Pause or another jump stops a play-through, and one stuck on a step for 20 s gives up
374
- there. The status line shows the board's clock (for counting `{ advance: n }`) and any hold.
371
+ In the workbench, clicking any step **goes straight to it**, before Start too: the script is played
372
+ headlessly up to that step (the player's moves made from `allow`, the bots playing as scripted,
373
+ steps that wait on a screen control passed over), and the board jumps to the result without
374
+ replaying it. Back works from there as usual. It is `runTutorial(game, spec, { until: stepId })`
375
+ underneath, so a step a headless run cannot reach (stuck, an error) logs why and leaves the board
376
+ as it is. Shift-click instead **plays through** on screen: narration skipped, animations rushed,
377
+ the same moves made one by one (Back, Pause or another jump stops it; stuck for 20 s, it gives
378
+ up). Alt-click jumps without touching the game. The status line shows the board's clock (for
379
+ counting `{ advance: n }`) and any hold.
375
380
 
376
381
  ## Starting a tutorial from a host
377
382
 
@@ -475,13 +475,13 @@ describe("TutorialController flow", () => {
475
475
  vi.advanceTimersByTime(1100); // the second sentence: hold where the board is now
476
476
  expect(holds).toEqual([12, 11]);
477
477
 
478
- vi.advanceTimersByTime(1100); // step b plays on until the log says so
478
+ vi.advanceTimersByTime(1100); // step b plays on until the log says so, one moment at a time
479
479
  expect(c.index.value).toBe(1);
480
- expect(holds).toEqual([12, 11, undefined]);
480
+ expect(holds).toEqual([12, 11, 12]);
481
481
  show(12, "Sam passes");
482
- expect(holds.length).toBe(3);
482
+ expect(holds).toEqual([12, 11, 12, 13]);
483
483
  show(13, "Robin buys a card");
484
- expect(holds).toEqual([12, 11, undefined, 13]);
484
+ expect(holds).toEqual([12, 11, 12, 13]); // already held at the moment it was waiting for
485
485
  expect(c.timelineHold.value).toBe(13);
486
486
 
487
487
  vi.advanceTimersByTime(2200); // step c lets it play
@@ -711,7 +711,7 @@ export class TutorialController<P extends PlayerChit = PlayerChit, R extends Roo
711
711
  this.runtime && (this.runtime.activeStep.value = step.id);
712
712
  const firstTime = this.markSeen(step);
713
713
  if (step.timeline) this.applyTimeline(step.timeline);
714
- if (step.waitFor && this.timelineHold.value !== undefined && !step.timeline) {
714
+ if (step.waitFor && this.timelineHold.value !== undefined && !step.timeline && !this.timelineUntil) {
715
715
  console.warn(
716
716
  `[tutorial ${this.spec.id}] step "${step.id}" waits with the board's timeline held at clock ` +
717
717
  `${this.timelineHold.value}; if it needs the board to catch up, give it timeline: "play"`,
@@ -1189,27 +1189,35 @@ export class TutorialController<P extends PlayerChit = PlayerChit, R extends Roo
1189
1189
  const ctx = this.context();
1190
1190
  if (ctx) command.until.reset?.(ctx);
1191
1191
  this.timelineUntil = { check: command.until, logFrom: this.recentLog.length };
1192
- this.holdTimeline(undefined);
1193
1192
  this.checkTimelineUntil();
1194
1193
  }
1195
1194
  }
1196
1195
 
1197
- /** Stops the board at the first moment that passes a pending `{ until }` command */
1196
+ /**
1197
+ * Stops the board at the first moment that passes a pending `{ until }` command. Until then the
1198
+ * board is held one moment ahead of the one on screen, and the hold moves on as each moment loads,
1199
+ * so every moment is shown and checked. Lifting the hold instead would let the board jump: when a
1200
+ * confirmed turn is folded into a new pass, an idle board skips straight to the furthest clock it may
1201
+ * show, past the moment being waited for.
1202
+ */
1198
1203
  private checkTimelineUntil() {
1199
1204
  const until = this.timelineUntil;
1200
1205
  if (!until || !this.view.timeline) return;
1201
1206
  const ctx = this.context();
1202
- if (!ctx) return;
1203
1207
  let passed = false;
1204
1208
  try {
1205
- passed = until.check({ ...ctx, recentLog: this.recentLog.slice(until.logFrom) }) === true;
1209
+ passed = !!ctx && until.check({ ...ctx, recentLog: this.recentLog.slice(until.logFrom) }) === true;
1206
1210
  } catch (e) {
1207
1211
  console.error(`[tutorial ${this.spec.id}] a timeline "until" check in step "${this.step?.id}" threw`, e);
1208
1212
  }
1209
- if (!passed) return;
1213
+ if (!passed) {
1214
+ const next = this.view.clock() + 1;
1215
+ if (this.timelineHold.value !== next) this.holdTimeline(next);
1216
+ return;
1217
+ }
1210
1218
  this.timelineUntil = undefined;
1211
1219
  // Change events arrive once the moment has loaded and before the board moves on from it
1212
- this.holdTimeline(this.view.clock());
1220
+ if (this.timelineHold.value !== this.view.clock()) this.holdTimeline(this.view.clock());
1213
1221
  }
1214
1222
 
1215
1223
  private holdTimeline(clock: number | undefined) {
@@ -1238,6 +1246,11 @@ export class TutorialController<P extends PlayerChit = PlayerChit, R extends Roo
1238
1246
  if (this.fastForwardTarget.value !== undefined && this.status.value === "waiting") this.doItForMe();
1239
1247
  }
1240
1248
 
1249
+ /** Re-runs the current step's check against the board (a host that cannot see every change polls this) */
1250
+ public recheck() {
1251
+ if (this.began && !this.disposed) this.evaluate();
1252
+ }
1253
+
1241
1254
  private evaluate() {
1242
1255
  const step = this.step;
1243
1256
  if (!step || this.status.value === "done" || this.reviewing.value) return;
@@ -14,8 +14,9 @@ import type { TutorialRuntime } from "./TutorialRuntime";
14
14
  export type RunTutorialOptions<P extends PlayerChit, R extends RootChit<P>> = {
15
15
  /**
16
16
  * Plays the human seat: given the step the tutorial is on and the legal options, return the index
17
- * to play, or undefined to take the first option the step's `allow` list accepts (a player
18
- * following instructions). A step that allows nothing is never answered.
17
+ * to play, or undefined to take what the step's `allow` list asks for first: its entries in the order
18
+ * written, each the first option it matches (a player following instructions, as "do it for me" plays).
19
+ * A step that allows nothing is never answered.
19
20
  */
20
21
  answer?: (
21
22
  step: TutorialStep<P, R> | undefined,
@@ -199,8 +200,14 @@ export async function runTutorial<P extends PlayerChit, R extends RootChit<P>>(
199
200
  if (chosen !== undefined) return chosen;
200
201
  const root = ctx.view as R;
201
202
  const me = ctx.me as P;
202
- const index = scored.findIndex((s) => isAllowed(step.allow, shapeOfAiOption(s.option), root, me));
203
- return index >= 0 ? index : null;
203
+ // The first entry of `allow` (in the order written) that an option matches, as "do it for me" (the → key) does:
204
+ // in prompt order a Done step that also allows moving the piece would drag it forever and never press Done
205
+ const list = step.allow === undefined ? [] : Array.isArray(step.allow) ? step.allow : [step.allow];
206
+ for (const entry of list) {
207
+ const index = scored.findIndex((s) => isAllowed(entry, shapeOfAiOption(s.option), root, me));
208
+ if (index >= 0) return index;
209
+ }
210
+ return null;
204
211
  },
205
212
  });
206
213
  // It plays the person, not a bot: keep it out of the bots' switch, so `pauseAi` and resuming the
@@ -272,12 +279,24 @@ export async function runTutorial<P extends PlayerChit, R extends RootChit<P>>(
272
279
 
273
280
  const outcome: RunTutorialResult<P, R>["outcome"] = error || match.errorState.value ? "error" : stuckOn ? "stuck" : "completed";
274
281
  controller.dispose();
275
- // The match first: a run stopped mid-game (`until`) still has bots moving, and the player's
276
- // connection must not be gone while the match still reports to it
277
- match.dispose();
278
- // and its replies already on their way get a moment to land
279
- await new Promise((resolve) => setTimeout(resolve, 0));
280
- human?.dispose();
282
+ // A run stopped mid-game (`until`) still has everyone playing: stop them, and let the messages
283
+ // already on their way land before the connections go. A skip-ahead does not wait for this.
284
+ match.ai.enabled = false;
285
+ human?.prompts.setEnabled(false);
286
+ const teardown = new Promise<void>((resolve) =>
287
+ setTimeout(() => {
288
+ // a throw here must not leave a full run waiting forever on this promise
289
+ try {
290
+ match.dispose();
291
+ human?.dispose();
292
+ } catch (e) {
293
+ console.error("[runTutorial] teardown failed:", e);
294
+ } finally {
295
+ resolve();
296
+ }
297
+ }, 50),
298
+ );
299
+ if (untilIndex < 0) await teardown;
281
300
  void run;
282
301
  void finishedEnd;
283
302
 
@@ -43,6 +43,10 @@ export function useClientPrompts() {
43
43
  }
44
44
  return result.clientPrompts;
45
45
  }
46
+ /** The client prompts, or undefined where there is no connection (a viewer with no seat). */
47
+ export function useOptionalClientPrompts() {
48
+ return useContext(TimeControllerContext).clientPrompts;
49
+ }
46
50
  export function useClientStatus() {
47
51
  const result = useContext(TimeControllerContext);
48
52
  if (!result.clientStatus) {
@@ -27,6 +27,8 @@ export type TutorialContextValue = {
27
27
  autoStart: boolean;
28
28
  /** Start held (after Back): silent until the player presses Play */
29
29
  startPaused: boolean;
30
+ /** A step id to go straight to once the board loads, played up to headlessly (a reload of /demo?step=) */
31
+ resumeAt?: string;
30
32
  /** Serializes the match for a step snapshot; undefined when the host cannot rebuild the match */
31
33
  snapshot?: () => unknown;
32
34
  /** Puts the match back to the snapshot taken when `stepId` went live; false when there is none */
@@ -49,6 +51,7 @@ export function TutorialProvider({
49
51
  startAt = 0,
50
52
  autoStart = false,
51
53
  startPaused = false,
54
+ resumeAt,
52
55
  snapshot,
53
56
  rewind,
54
57
  children,
@@ -61,6 +64,7 @@ export function TutorialProvider({
61
64
  startAt?: number;
62
65
  autoStart?: boolean;
63
66
  startPaused?: boolean;
67
+ resumeAt?: string;
64
68
  snapshot?: () => unknown;
65
69
  rewind?: (stepId: string) => Promise<boolean>;
66
70
  children: ReactNode;
@@ -69,8 +73,8 @@ export function TutorialProvider({
69
73
  const [dev] = useState(() => new EventChannel<TutorialDevSettings>({ showTargetRects: false }));
70
74
  const [muted] = useState(() => new EventChannel<boolean>(false));
71
75
  const value = useMemo<TutorialContextValue>(
72
- () => ({ spec, runtime, themeOverrides, ai, onEvent, controller, dev, muted, startAt, autoStart, startPaused, snapshot, rewind }),
73
- [spec, runtime, themeOverrides, ai, onEvent, controller, dev, muted, startAt, autoStart, startPaused, snapshot, rewind],
76
+ () => ({ spec, runtime, themeOverrides, ai, onEvent, controller, dev, muted, startAt, autoStart, startPaused, resumeAt, snapshot, rewind }),
77
+ [spec, runtime, themeOverrides, ai, onEvent, controller, dev, muted, startAt, autoStart, startPaused, resumeAt, snapshot, rewind],
74
78
  );
75
79
  return <TutorialContext.Provider value={value}>{children}</TutorialContext.Provider>;
76
80
  }
@@ -141,6 +141,7 @@ export { HighlightSpec } from "./rendering/HighlightSpec";
141
141
  export { LightSpec, Light } from "./rendering/LightSpec";
142
142
  /** @group 3D Rendering */
143
143
  export { Splay } from "./rendering/Splay";
144
+ export type { SplayFill, SplayOrientation } from "./rendering/Splay";
144
145
 
145
146
  /** @group Utilities */
146
147
  export { extrudeSVGToGeometry } from "./utilities/SvgExtruder";
@@ -19,7 +19,19 @@ export class ChitGalleryItemInstance implements GalleryItem {
19
19
  preferredHeight?: number;
20
20
 
21
21
  originalSummary?: string;
22
- summary?: string;
22
+ /**
23
+ * How many functionally identical chits this item stands for in its gallery (see
24
+ * `chitsToGalleryItems`); above 1 the summary leads with "Nx". Kept apart from the summary
25
+ * text, so a refresh that copies the render spec's summary back onto the item keeps the count.
26
+ */
27
+ count?: number;
28
+ private _summary?: string;
29
+ get summary(): string | undefined {
30
+ return this.count && this.count > 1 ? `${this.count}x\n${this._summary ?? ""}` : this._summary;
31
+ }
32
+ set summary(value: string | undefined) {
33
+ this._summary = value;
34
+ }
23
35
  shortSummary?: string;
24
36
  summaryIconMap?: IconMap;
25
37
  summaryRenderingOptions?: RichTextRenderOptionsParameters;
@@ -80,6 +92,11 @@ export class ChitGalleryItemInstance implements GalleryItem {
80
92
 
81
93
  createMesh(sceneWrapper: SceneWrapper) {
82
94
  this.sceneWrapper = sceneWrapper;
95
+ return this.cloneMesh();
96
+ }
97
+
98
+ /** A copy of the chit as drawn, without binding this item to a scene (a drag's ghost on the board). */
99
+ cloneMesh(): Object3D {
83
100
  const renderInstance = this.chit.renderInstance;
84
101
  const g = new Group();
85
102
  if (renderInstance) {
@@ -443,7 +443,7 @@ export class ChitRenderInstance {
443
443
  item.preferredWidth = this.renderSpec?.galleryPreferredWidth;
444
444
  item.summary = this.renderSpec?.summary;
445
445
  item.shortSummary = this.renderSpec?.shortSummary;
446
- item.originalSummary = item.summary;
446
+ item.originalSummary = this.renderSpec?.summary; // not item.summary: that leads with the item's "Nx" count
447
447
  item.summaryIconMap = this.renderSpec?.summaryIconMap;
448
448
  item.summaryRenderingOptions = this.renderSpec?.summaryRenderingOptions;
449
449
  item.shortSummaryRenderingOptions = this.renderSpec?.shortSummaryRenderingOptions;
@@ -584,7 +584,10 @@ export class ChitRenderInstance {
584
584
  this.renderSpec.ornaments.forEach((ornament) => this.group.add(ornament));
585
585
 
586
586
  this.fixObjectPosition();
587
- this._galleryItem?.update();
587
+ if (this._galleryItem) {
588
+ this.createGalleryItem(this._galleryItem); // copy the new spec's summary and sizes onto it
589
+ this._galleryItem.update();
590
+ }
588
591
 
589
592
  this.rootRenderInstance.markHasChange();
590
593
  }
@@ -597,6 +600,22 @@ export class ChitRenderInstance {
597
600
  );
598
601
  }
599
602
 
603
+ /** Where this chit sits in world space: what a dragged chit's position is compared with. */
604
+ public worldCenter(): Vector3 {
605
+ return this.bboxGroup.getWorldPosition(new Vector3());
606
+ }
607
+
608
+ /** Outline (or clear) this chit as the target a drag would drop on. */
609
+ public markAsDropTarget(on: boolean) {
610
+ this.chit.isDropTarget = on;
611
+ this.refresh();
612
+ }
613
+
614
+ /** How far a drag lifts this chit (`ChitRenderSpec.dragZLiftAmount`). */
615
+ public get dragLift(): number {
616
+ return this.renderSpec?.dragZLiftAmount ?? 0;
617
+ }
618
+
600
619
  public executeDrag(x: number, y: number) {
601
620
  const root = this.rootRenderInstance;
602
621
  const dragPoint = root.attemptToFindPlaneZ0OfCanvasPoints(x, y) ?? new Vector3(0, 0, 0);
@@ -656,8 +675,8 @@ export class ChitRenderInstance {
656
675
  dropTarget.isDropTarget = false;
657
676
  dropTarget.renderInstance?.refresh();
658
677
 
659
- this.chit.onDrag!(dropTarget);
660
- dropTarget.add(this.chit);
678
+ // A refused drop (a tutorial's guard) leaves the chit where it was: refresh() puts it back
679
+ if (this.chit.onDrag!(dropTarget) !== false) dropTarget.add(this.chit);
661
680
  }
662
681
  this.refresh();
663
682
  },
@@ -74,6 +74,9 @@ export class LightWrapper {
74
74
  l.shadow.camera.right = 0.1;
75
75
  l.shadow.camera.top = 0.1;
76
76
  l.shadow.camera.bottom = -0.1;
77
+ // the camera is fitted to the whole panel, so a board-sized panel needs more than the default 512 texels for
78
+ // a piece's shadow to read
79
+ l.shadow.mapSize.set(1024, 1024);
77
80
  this.group.add(l);
78
81
  }
79
82
 
@@ -126,12 +129,16 @@ export class LightWrapper {
126
129
  camera.bottom = -1;
127
130
  camera.top = 1;
128
131
  camera.updateProjectionMatrix();
132
+ // point the shadow camera along the light now (the renderer would only do it at the next shadow pass), so the
133
+ // projection below is in the light's view
134
+ light.updateMatrixWorld(true);
135
+ light.shadow.updateMatrices(light);
129
136
 
130
137
  const b = new Box2();
131
138
  const adjust = (x: number, y: number, z: number) => {
132
139
  const v = new Vector3(x, y, z);
133
140
  const cameraPoint = v.project(camera);
134
- b.expandByPoint(new Vector2(cameraPoint.x * 2, cameraPoint.y * 2));
141
+ b.expandByPoint(new Vector2(cameraPoint.x, cameraPoint.y));
135
142
  };
136
143
 
137
144
  [this.bbox.min.x, this.bbox.max.x].forEach((x) =>
@@ -142,6 +149,8 @@ export class LightWrapper {
142
149
  ),
143
150
  );
144
151
 
152
+ // with -1..1 bounds the projection is the light's own view coordinates: fit them, with a small margin
153
+ b.expandByScalar(0.5);
145
154
  camera.left = Math.min(left, b.min.x);
146
155
  camera.right = Math.max(right, b.max.x);
147
156
  camera.bottom = Math.min(bottom, b.min.y);
@@ -0,0 +1,60 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import { Splay } from "./Splay";
3
+
4
+ /** the grid slot (column, row) each child index lands on, in unit item sizes */
5
+ function slots(s: Splay): string[] {
6
+ const out: string[] = [];
7
+ for (let i = 0; i < s.rows * s.columns; i++) {
8
+ const r = s.processSplay(i, 1, 1, 1);
9
+ out.push(`${r.x},${r.y}`);
10
+ }
11
+ return out;
12
+ }
13
+
14
+ function grid(rows: number, columns: number, set: Partial<Splay> = {}): Splay {
15
+ const s = new Splay();
16
+ s.enabled = true;
17
+ s.rows = rows;
18
+ s.columns = columns;
19
+ Object.assign(s, set);
20
+ return s;
21
+ }
22
+
23
+ describe("Splay fill", () => {
24
+ it("fills a 4×2 window in reading order from the top left with fill 'rows'", () => {
25
+ const s = grid(2, 4, { fill: "rows", columnOrientation: "increasing", rowOrientation: "decreasing" });
26
+ // y up the table: the top row is y 0, the next y -1
27
+ expect(slots(s)).toEqual(["0,0", "1,0", "2,0", "3,0", "0,-1", "1,-1", "2,-1", "3,-1"]);
28
+ });
29
+
30
+ it("fills column by column with fill 'columns'", () => {
31
+ const s = grid(2, 4, { fill: "columns", columnOrientation: "increasing", rowOrientation: "decreasing" });
32
+ expect(slots(s)).toEqual(["0,0", "0,-1", "1,0", "1,-1", "2,0", "2,-1", "3,0", "3,-1"]);
33
+ });
34
+
35
+ it("keeps 'nearest' as the default: closest to the anchor first", () => {
36
+ const s = grid(2, 4, { columnOrientation: "increasing", rowOrientation: "decreasing" });
37
+ expect(s.fill).toBe("nearest");
38
+ const order = slots(s);
39
+ expect(order[0]).toBe("0,0");
40
+ // distances never decrease
41
+ const d = order.map((o) => o.split(",").reduce((a, v) => a + Math.abs(Number(v)), 0));
42
+ expect([...d].sort((a, b) => a - b)).toEqual(d);
43
+ });
44
+
45
+ it("breaks distance ties in row-major order on a non-square grid", () => {
46
+ // centred 2×4: the four inner slots, then the four outer ones row by row (the old tie-break, row * rows + column,
47
+ // took the outer ones column by column on a grid that is not square)
48
+ const s = grid(2, 4);
49
+ expect(slots(s)).toEqual([
50
+ "-0.5,-0.5", "0.5,-0.5", "-0.5,0.5", "0.5,0.5",
51
+ "-1.5,-0.5", "1.5,-0.5", "-1.5,0.5", "1.5,0.5",
52
+ ]);
53
+ });
54
+
55
+ it("piles past the grid: the next child goes back to the first slot, one layer up", () => {
56
+ const s = grid(2, 2, { fill: "rows", columnOrientation: "increasing", rowOrientation: "decreasing" });
57
+ const r = s.processSplay(4, 1, 1, 1);
58
+ expect([r.x, r.y, r.z]).toEqual([0, 0, 1]);
59
+ });
60
+ });
@@ -1,5 +1,14 @@
1
1
  type SplayResults = { x: number; y: number; z: number };
2
2
  export type SplayOrientation = "center" | "decreasing" | "increasing";
3
+ /**
4
+ * The order a splay hands out its slots, measured from the anchor (the slot the orientations put at 0,0).
5
+ * - `"nearest"`: closest to the anchor first (Manhattan distance), so a grid fills in rings: a 4×2 fills diagonally.
6
+ * - `"rows"`: the anchor's row first, working away from the anchor column, then the next row away from the anchor.
7
+ * With `columnOrientation = "increasing"` and `rowOrientation = "decreasing"` that is reading order from the top
8
+ * left: a window of identical markers filled the way a person fills it.
9
+ * - `"columns"`: the same, column by column.
10
+ */
11
+ export type SplayFill = "nearest" | "rows" | "columns";
3
12
 
4
13
  function midFromOrientation(max: number, orientation: SplayOrientation) {
5
14
  switch (orientation) {
@@ -20,6 +29,7 @@ function getSplayOrder(
20
29
  columns: number,
21
30
  rowOrientation: SplayOrientation,
22
31
  columnOrientation: SplayOrientation,
32
+ fill: SplayFill,
23
33
  ): SplayResults[] {
24
34
  if (splayOrder[key]) {
25
35
  return splayOrder[key];
@@ -30,17 +40,25 @@ function getSplayOrder(
30
40
  const order: SplayResults[] = [];
31
41
  for (let row = 0; row < rows; row++) {
32
42
  for (let column = 0; column < columns; column++) {
33
- order.push({ x: column - midX, y: row - midY, z: row * rows + column });
43
+ order.push({ x: column - midX, y: row - midY, z: row * columns + column });
34
44
  }
35
45
  }
36
46
 
37
- order.sort((a, b) => {
38
- const d1 = Math.abs(a.x) + Math.abs(a.y);
39
- const d2 = Math.abs(b.x) + Math.abs(b.y);
40
- if (d1 == d2) {
41
- return a.z - b.z;
47
+ // the primary and secondary distance from the anchor for each fill; ties keep row-major order
48
+ const keys = (o: SplayResults): [number, number] => {
49
+ switch (fill) {
50
+ case "rows":
51
+ return [Math.abs(o.y), Math.abs(o.x)];
52
+ case "columns":
53
+ return [Math.abs(o.x), Math.abs(o.y)];
54
+ default:
55
+ return [Math.abs(o.x) + Math.abs(o.y), 0];
42
56
  }
43
- return d1 - d2;
57
+ };
58
+ order.sort((a, b) => {
59
+ const [a1, a2] = keys(a);
60
+ const [b1, b2] = keys(b);
61
+ return a1 - b1 || a2 - b2 || a.z - b.z;
44
62
  });
45
63
  splayOrder[key] = order;
46
64
  return order;
@@ -51,6 +69,8 @@ export class Splay {
51
69
  public columns: number = 1;
52
70
  public rowOrientation: SplayOrientation = "center";
53
71
  public columnOrientation: SplayOrientation = "center";
72
+ /** the order slots fill in (see {@link SplayFill}); `"nearest"` by default */
73
+ public fill: SplayFill = "nearest";
54
74
 
55
75
  public enabled: boolean = false;
56
76
  public zSpacingMultiplier: number = 1;
@@ -60,16 +80,17 @@ export class Splay {
60
80
  public itemHeight?: number = undefined;
61
81
 
62
82
  toString() {
63
- return `${this.rows} ${this.columns} ${this.rowOrientation} ${this.columnOrientation} ${this.enabled} ${this.zSpacingMultiplier} ${this.spacingMultiplier} ${this.itemWidth} ${this.itemHeight}`;
83
+ return `${this.rows} ${this.columns} ${this.rowOrientation} ${this.columnOrientation} ${this.fill} ${this.enabled} ${this.zSpacingMultiplier} ${this.spacingMultiplier} ${this.itemWidth} ${this.itemHeight}`;
64
84
  }
65
85
 
66
86
  private get splayOrder() {
67
87
  return getSplayOrder(
68
- `${this.rows}_${this.columns}_${this.rowOrientation}_${this.columnOrientation}`,
88
+ `${this.rows}_${this.columns}_${this.rowOrientation}_${this.columnOrientation}_${this.fill}`,
69
89
  this.rows,
70
90
  this.columns,
71
91
  this.rowOrientation,
72
92
  this.columnOrientation,
93
+ this.fill,
73
94
  );
74
95
  }
75
96
 
@@ -416,6 +416,19 @@ export class RichTextRenderer {
416
416
  const avail = maxWidth - cursorW;
417
417
  const threshold = maxWidth * HYPH_RATIO;
418
418
 
419
+ // Punctuation never starts a line: a closing mark that does not fit hangs on the end of this one (it is a few
420
+ // pixels; wrapping it alone strands a full stop or comma at the start of the next line).
421
+ if (cursorW > 0 && wordWidth > avail && /^[.,;:!?)\]}»”’…]+$/.test(r.text)) {
422
+ line.segments.push({
423
+ kind: "text",
424
+ text: r.text,
425
+ width: wordWidth,
426
+ style: { bold: r.bold, italic: r.italic },
427
+ });
428
+ cursorW += wordWidth;
429
+ continue;
430
+ }
431
+
419
432
  // Fits in remaining space: place and continue.
420
433
  if (wordWidth <= avail) {
421
434
  line.segments.push({