@seriousgaming/sdk-tools 1.0.0-alpha.2 → 1.0.0-alpha.4

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 (61) hide show
  1. package/README.md +5 -5
  2. package/dist/cli.js +30 -12
  3. package/dist/client/index.d.ts +2 -2
  4. package/dist/client/test-session.d.ts +12 -15
  5. package/dist/client.js +20 -11
  6. package/dist/docs/api/index.md +1 -1
  7. package/dist/docs/api/sdk-tools-client.md +40 -32
  8. package/dist/docs/api/sdk-ui-testing.md +4 -4
  9. package/dist/docs/api/sdk-ui.md +80 -20
  10. package/dist/docs/api/sdk.md +37 -21
  11. package/dist/docs/changelog.md +117 -71
  12. package/dist/docs/cli-and-dev-server.md +16 -15
  13. package/dist/docs/cli-reference.md +10 -0
  14. package/dist/docs/concepts/index.md +1 -1
  15. package/dist/docs/concepts/terminology.md +6 -6
  16. package/dist/docs/getting-started.md +4 -2
  17. package/dist/docs/guides/engine-testing.md +1 -1
  18. package/dist/docs/guides/engine.md +13 -0
  19. package/dist/docs/guides/file-handling.md +4 -4
  20. package/dist/docs/guides/internationalization.md +15 -1
  21. package/dist/docs/guides/llm-integration.md +2 -0
  22. package/dist/docs/guides/patterns.md +33 -5
  23. package/dist/docs/guides/presentation.md +9 -9
  24. package/dist/docs/guides/session.md +22 -19
  25. package/dist/docs/guides/testing.md +3 -3
  26. package/dist/docs/guides/tick-controller.md +5 -3
  27. package/dist/docs/guides/ui.md +5 -1
  28. package/dist/docs/guides/upgrading.md +21 -6
  29. package/dist/docs/recipes/create-endpoint.md +1 -1
  30. package/dist/docs/recipes/start-from-an-empty-package.md +6 -7
  31. package/dist/docs/recipes/use-request-tick.md +1 -1
  32. package/dist/docs/troubleshooting.md +6 -4
  33. package/dist/schema.json +6 -6
  34. package/dist/templates/endpoint/logic.test.ts.liquid +35 -48
  35. package/dist/templates/engine/logic-aggregate.test.ts.liquid +34 -53
  36. package/dist/templates/engine/logic.test.ts.liquid +22 -34
  37. package/dist/templates/hook/logic.test.ts.liquid +28 -32
  38. package/dist/templates/package/CLAUDE.md.template +1 -1
  39. package/dist/templates/package/README.md.liquid +3 -3
  40. package/dist/templates/package/claude/rules/workflow-create-capability.md +1 -1
  41. package/dist/templates/package/claude/rules/workflow-create-endpoint.md +1 -1
  42. package/dist/templates/package/vitest.config.ts.liquid +18 -2
  43. package/dist/templates/presentation/src/App.tsx.liquid +1 -1
  44. package/dist/templates/session/src/main.tsx.liquid +3 -3
  45. package/dist/templates/settings-editor/src/main.tsx.liquid +3 -3
  46. package/dist/templates/starter-game/engine/logic.test.ts +37 -47
  47. package/dist/templates/starter-game/engine/test-helpers.ts +13 -65
  48. package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +24 -30
  49. package/dist/templates/starter-game/session/src/main.tsx +3 -3
  50. package/dist/templates/starter-game/ui/src/main.tsx +3 -3
  51. package/dist/templates/starter-game/validators/capacity/logic/logic.test.ts +12 -35
  52. package/dist/templates/starter-game/vitest.config.ts +18 -2
  53. package/dist/templates/starter-game/waiting_room/src/main.tsx +3 -3
  54. package/dist/templates/ui/src/App.test.tsx.liquid +2 -2
  55. package/dist/templates/ui/src/App.tsx.liquid +22 -11
  56. package/dist/templates/ui/src/i18n.ts.liquid +3 -0
  57. package/dist/templates/ui/src/main.tsx.liquid +3 -3
  58. package/dist/templates/validator/logic.test.ts.liquid +21 -30
  59. package/dist/templates/waiting-room/src/App.test.tsx.liquid +2 -2
  60. package/dist/templates/waiting-room/src/main.tsx.liquid +3 -3
  61. package/package.json +3 -3
@@ -6,14 +6,6 @@ Every export of `@seriousgaming/sdk/ui`, with the declaration it is published wi
6
6
 
7
7
  ## Functions
8
8
 
9
- ### localisedReferences
10
-
11
- The references `useAsset` tries, most specific first: the locale as a directory immediately before the file name, then its language alone, then the reference as given. `asset:documents/intro.md` in `fr-CA` tries `asset:documents/fr-CA/intro.md`, `asset:documents/fr/intro.md` and `asset:documents/intro.md`.
12
-
13
- ```ts
14
- function localisedReferences(reference: string, locale: string | false): string[];
15
- ```
16
-
17
9
  ### PresentationWrapper
18
10
 
19
11
  Wrap a presentation bundle. Read-only: there is nothing here to write with, and the host would refuse it if there were.
@@ -339,7 +331,7 @@ const useUserInterfaceTimer: () => TimerState;
339
331
  Subscribe to validator rejections from the host. Rejections are surfaced when a UI-submitted mutation (via `setData`) violates one or more validators declared in the game. They are delivered as a single batch per submission; the runtime collects every failing validator's verdict and returns them together.
340
332
 
341
333
  ```ts
342
- const useUserInterfaceValidationRejections: () => UserInterfaceValidationContextValue;
334
+ const useUserInterfaceValidationRejections: () => UserInterfaceValidationRejectionsValue;
343
335
  ```
344
336
 
345
337
  ### useUserInterfaceViewerRole
@@ -410,12 +402,6 @@ Provided by every surface wrapper. Exported for the test helpers, which provide
410
402
  const AssetContext: import('react').Context<AssetScope | undefined>;
411
403
  ```
412
404
 
413
- ### CrossTeamDataContext
414
-
415
- ```ts
416
- const CrossTeamDataContext: import('react').Context<CrossTeamData | undefined>;
417
- ```
418
-
419
405
  ### PastStateContext
420
406
 
421
407
  Provided by the wrappers whose surfaces can read past state: the player, session and presentation wrappers. Exported for the test helpers, which provide it without a host; game code reads it through `usePastState`.
@@ -426,6 +412,8 @@ const PastStateContext: import('react').Context<PastStateReader | undefined>;
426
412
 
427
413
  ### PresentationContext
428
414
 
415
+ The React context behind `usePresentation`.
416
+
429
417
  ```ts
430
418
  const PresentationContext: import('react').Context<
431
419
  PresentationValue<unknown, unknown, unknown> | undefined
@@ -434,6 +422,8 @@ const PresentationContext: import('react').Context<
434
422
 
435
423
  ### SessionUserInterfaceCallbacksContext
436
424
 
425
+ The React context behind `useSessionUserInterfaceCallbacks`.
426
+
437
427
  ```ts
438
428
  const SessionUserInterfaceCallbacksContext: import('react').Context<
439
429
  SessionUserInterfaceCallbacks | undefined
@@ -442,6 +432,8 @@ const SessionUserInterfaceCallbacksContext: import('react').Context<
442
432
 
443
433
  ### SessionUserInterfaceDataContext
444
434
 
435
+ The React context behind `useSessionUserInterfaceData`.
436
+
445
437
  ```ts
446
438
  const SessionUserInterfaceDataContext: import('react').Context<
447
439
  | SessionUserInterfaceDataContextValue<
@@ -456,6 +448,8 @@ const SessionUserInterfaceDataContext: import('react').Context<
456
448
 
457
449
  ### SessionUserInterfaceHookFailuresContext
458
450
 
451
+ The React context behind `useSessionUserInterfaceHookFailures`.
452
+
459
453
  ```ts
460
454
  const SessionUserInterfaceHookFailuresContext: import('react').Context<
461
455
  SessionUserInterfaceHookFailuresValue | undefined
@@ -464,12 +458,16 @@ const SessionUserInterfaceHookFailuresContext: import('react').Context<
464
458
 
465
459
  ### SessionUserInterfaceHostOverlaysContext
466
460
 
461
+ The React context behind `useSessionUserInterfaceHostOverlays`.
462
+
467
463
  ```ts
468
464
  const SessionUserInterfaceHostOverlaysContext: import('react').Context<HostOverlay[]>;
469
465
  ```
470
466
 
471
467
  ### SessionUserInterfaceLocaleContext
472
468
 
469
+ The React context behind `useSessionUserInterfaceLocale`.
470
+
473
471
  ```ts
474
472
  const SessionUserInterfaceLocaleContext: import('react').Context<
475
473
  SessionUserInterfaceLocale | undefined
@@ -478,36 +476,48 @@ const SessionUserInterfaceLocaleContext: import('react').Context<
478
476
 
479
477
  ### SessionUserInterfaceMetaContext
480
478
 
479
+ The React context behind `useSessionUserInterfaceMeta`.
480
+
481
481
  ```ts
482
482
  const SessionUserInterfaceMetaContext: import('react').Context<SessionMeta | undefined>;
483
483
  ```
484
484
 
485
485
  ### SessionUserInterfaceParticipantsContext
486
486
 
487
+ The React context behind `useSessionUserInterfaceParticipants`.
488
+
487
489
  ```ts
488
490
  const SessionUserInterfaceParticipantsContext: import('react').Context<Participant[] | undefined>;
489
491
  ```
490
492
 
491
493
  ### SessionUserInterfaceTeamConfigurationContext
492
494
 
495
+ The React context behind `useSessionUserInterfaceTeamConfiguration`.
496
+
493
497
  ```ts
494
498
  const SessionUserInterfaceTeamConfigurationContext: import('react').Context<TeamConfiguration>;
495
499
  ```
496
500
 
497
501
  ### SessionUserInterfaceTeamLinksContext
498
502
 
503
+ The React context behind `useSessionUserInterfaceTeamLinks`.
504
+
499
505
  ```ts
500
506
  const SessionUserInterfaceTeamLinksContext: import('react').Context<TeamLinks[]>;
501
507
  ```
502
508
 
503
509
  ### SessionUserInterfaceTeamsContext
504
510
 
511
+ The React context behind `useSessionUserInterfaceTeams`.
512
+
505
513
  ```ts
506
514
  const SessionUserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
507
515
  ```
508
516
 
509
517
  ### SessionUserInterfaceThemeContext
510
518
 
519
+ The React context behind `useSessionUserInterfaceTheme`.
520
+
511
521
  ```ts
512
522
  const SessionUserInterfaceThemeContext: import('react').Context<
513
523
  SessionUserInterfaceTheme | undefined
@@ -516,6 +526,8 @@ const SessionUserInterfaceThemeContext: import('react').Context<
516
526
 
517
527
  ### SessionUserInterfaceThemePreferenceContext
518
528
 
529
+ The React context behind `useSessionUserInterfaceThemePreference`.
530
+
519
531
  ```ts
520
532
  const SessionUserInterfaceThemePreferenceContext: import('react').Context<
521
533
  ThemePreference | undefined
@@ -524,48 +536,72 @@ const SessionUserInterfaceThemePreferenceContext: import('react').Context<
524
536
 
525
537
  ### SessionUserInterfaceWalkthroughLinkContext
526
538
 
539
+ The React context behind `useSessionUserInterfaceWalkthroughLink`.
540
+
527
541
  ```ts
528
542
  const SessionUserInterfaceWalkthroughLinkContext: import('react').Context<WalkthroughLink | null>;
529
543
  ```
530
544
 
531
545
  ### SettingsEditorCallbacksContext
532
546
 
547
+ The React context behind `useSettingsEditorCallbacks`.
548
+
533
549
  ```ts
534
550
  const SettingsEditorCallbacksContext: import('react').Context<SettingsEditorCallbacks | undefined>;
535
551
  ```
536
552
 
537
553
  ### SettingsEditorContext
538
554
 
555
+ The React context behind `useSettingsEditor`.
556
+
539
557
  ```ts
540
558
  const SettingsEditorContext: import('react').Context<SettingsEditorValue<unknown> | undefined>;
541
559
  ```
542
560
 
543
561
  ### SettingsEditorLocaleContext
544
562
 
563
+ The React context behind `useSettingsEditorLocale`.
564
+
545
565
  ```ts
546
566
  const SettingsEditorLocaleContext: import('react').Context<SettingsEditorLocale | undefined>;
547
567
  ```
548
568
 
549
569
  ### SettingsEditorThemeContext
550
570
 
571
+ The React context behind `useSettingsEditorTheme`.
572
+
551
573
  ```ts
552
574
  const SettingsEditorThemeContext: import('react').Context<SettingsEditorTheme | undefined>;
553
575
  ```
554
576
 
555
577
  ### SettingsEditorThemePreferenceContext
556
578
 
579
+ The React context behind `useSettingsEditorThemePreference`.
580
+
557
581
  ```ts
558
582
  const SettingsEditorThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
559
583
  ```
560
584
 
561
585
  ### UserInterfaceCallbacksContext
562
586
 
587
+ The React context behind `useUserInterfaceCallbacks`.
588
+
563
589
  ```ts
564
590
  const UserInterfaceCallbacksContext: import('react').Context<UserInterfaceCallbacks | undefined>;
565
591
  ```
566
592
 
593
+ ### UserInterfaceCrossTeamDataContext
594
+
595
+ The React context behind `useUserInterfaceCrossTeamData`.
596
+
597
+ ```ts
598
+ const UserInterfaceCrossTeamDataContext: import('react').Context<CrossTeamData | undefined>;
599
+ ```
600
+
567
601
  ### UserInterfaceDataContext
568
602
 
603
+ The React context behind `useUserInterfaceData`.
604
+
569
605
  ```ts
570
606
  const UserInterfaceDataContext: import('react').Context<
571
607
  UserInterfaceDataContextValue<unknown, unknown> | undefined
@@ -574,74 +610,98 @@ const UserInterfaceDataContext: import('react').Context<
574
610
 
575
611
  ### UserInterfaceLocaleContext
576
612
 
613
+ The React context behind `useUserInterfaceLocale`.
614
+
577
615
  ```ts
578
616
  const UserInterfaceLocaleContext: import('react').Context<UserInterfaceLocale | undefined>;
579
617
  ```
580
618
 
581
619
  ### UserInterfaceOwnTeamContext
582
620
 
621
+ The React context behind `useUserInterfaceOwnTeam`.
622
+
583
623
  ```ts
584
624
  const UserInterfaceOwnTeamContext: import('react').Context<TeamInfo | null>;
585
625
  ```
586
626
 
587
627
  ### UserInterfaceOwnTeamJoinLinkContext
588
628
 
629
+ The React context behind `useUserInterfaceOwnTeamJoinLink`.
630
+
589
631
  ```ts
590
632
  const UserInterfaceOwnTeamJoinLinkContext: import('react').Context<OwnTeamJoinLink | null>;
591
633
  ```
592
634
 
593
635
  ### UserInterfaceParticipantContext
594
636
 
637
+ The React context behind `useUserInterfaceParticipant`.
638
+
595
639
  ```ts
596
640
  const UserInterfaceParticipantContext: import('react').Context<Participant | null | undefined>;
597
641
  ```
598
642
 
599
643
  ### UserInterfaceParticipantsContext
600
644
 
645
+ The React context behind `useUserInterfaceParticipants`.
646
+
601
647
  ```ts
602
648
  const UserInterfaceParticipantsContext: import('react').Context<Participant[]>;
603
649
  ```
604
650
 
605
651
  ### UserInterfaceRunKindContext
606
652
 
653
+ The React context behind `useRunKind`.
654
+
607
655
  ```ts
608
656
  const UserInterfaceRunKindContext: import('react').Context<RunKind>;
609
657
  ```
610
658
 
611
659
  ### UserInterfaceTeamsContext
612
660
 
661
+ The React context behind `useUserInterfaceTeams`.
662
+
613
663
  ```ts
614
664
  const UserInterfaceTeamsContext: import('react').Context<TeamInfo[]>;
615
665
  ```
616
666
 
617
667
  ### UserInterfaceThemeContext
618
668
 
669
+ The React context behind `useUserInterfaceTheme`.
670
+
619
671
  ```ts
620
672
  const UserInterfaceThemeContext: import('react').Context<UserInterfaceTheme | undefined>;
621
673
  ```
622
674
 
623
675
  ### UserInterfaceThemePreferenceContext
624
676
 
677
+ The React context behind `useUserInterfaceThemePreference`.
678
+
625
679
  ```ts
626
680
  const UserInterfaceThemePreferenceContext: import('react').Context<ThemePreference | undefined>;
627
681
  ```
628
682
 
629
683
  ### UserInterfaceTimerContext
630
684
 
685
+ The React context behind `useUserInterfaceTimer`.
686
+
631
687
  ```ts
632
688
  const UserInterfaceTimerContext: import('react').Context<TimerState>;
633
689
  ```
634
690
 
635
- ### UserInterfaceValidationContext
691
+ ### UserInterfaceValidationRejectionsContext
692
+
693
+ The React context behind `useUserInterfaceValidationRejections`.
636
694
 
637
695
  ```ts
638
- const UserInterfaceValidationContext: import('react').Context<
639
- UserInterfaceValidationContextValue | undefined
696
+ const UserInterfaceValidationRejectionsContext: import('react').Context<
697
+ UserInterfaceValidationRejectionsValue | undefined
640
698
  >;
641
699
  ```
642
700
 
643
701
  ### UserInterfaceViewerRoleContext
644
702
 
703
+ The React context behind `useUserInterfaceViewerRole`.
704
+
645
705
  ```ts
646
706
  const UserInterfaceViewerRoleContext: import('react').Context<ViewerRole>;
647
707
  ```
@@ -854,12 +914,12 @@ interface UseAssetOptions<F extends AssetFormat = AssetFormat> {
854
914
  }
855
915
  ```
856
916
 
857
- ### UserInterfaceValidationContextValue
917
+ ### UserInterfaceValidationRejectionsValue
858
918
 
859
919
  Value exposed to consumers of `useUserInterfaceValidationRejections`.
860
920
 
861
921
  ```ts
862
- interface UserInterfaceValidationContextValue {
922
+ interface UserInterfaceValidationRejectionsValue {
863
923
  rejections: ValidationRejection[];
864
924
  clearRejections: () => void;
865
925
  }
@@ -364,8 +364,8 @@ The arguments of the engine's own functions: everything logic receives, plus the
364
364
 
365
365
  ```ts
366
366
  interface EngineFunctionArgs<
367
- TContext,
368
- TSettings,
367
+ TContext = Record<string, Record<string, unknown>>,
368
+ TSettings = unknown,
369
369
  TCallbacks = SignatureCallbacks,
370
370
  TState = never,
371
371
  > extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
@@ -645,7 +645,11 @@ interface LLMUsage {
645
645
  ### LogicFunctionArgs
646
646
 
647
647
  ```ts
648
- interface LogicFunctionArgs<TContext, TSettings, TCallbacks = SignatureCallbacks> {
648
+ interface LogicFunctionArgs<
649
+ TContext = Record<string, Record<string, unknown>>,
650
+ TSettings = unknown,
651
+ TCallbacks = SignatureCallbacks,
652
+ > {
649
653
  context: TContext;
650
654
  settings: TSettings;
651
655
  meta: TeamRunMeta;
@@ -834,9 +838,9 @@ interface ResolvedPackageManifest {
834
838
 
835
839
  ```ts
836
840
  interface RunAggregateFunctionArgs<
837
- TTeamContext,
838
- TSharedContext,
839
- TSettings,
841
+ TTeamContext = Record<string, Record<string, unknown>>,
842
+ TSharedContext = Record<string, Record<string, unknown>>,
843
+ TSettings = unknown,
840
844
  TCallbacks = SignatureCallbacks,
841
845
  TTeamState = never,
842
846
  TSharedState = never,
@@ -1392,8 +1396,8 @@ interface TickControllerDefinition {
1392
1396
 
1393
1397
  ```ts
1394
1398
  interface TickControllerFunctionArgs<
1395
- TContext,
1396
- TSettings,
1399
+ TContext = Record<string, Record<string, unknown>>,
1400
+ TSettings = unknown,
1397
1401
  TCallbacks = SignatureCallbacks,
1398
1402
  > extends LogicFunctionArgs<TContext, TSettings, TCallbacks> {
1399
1403
  teams: AggregateFunctionTeam<TContext>[];
@@ -1860,7 +1864,11 @@ type GenerateSpeechVoice = 'neutral' | 'narrator' | 'announcer' | 'executive' |
1860
1864
  ### GetTickControllerFunction
1861
1865
 
1862
1866
  ```ts
1863
- type GetTickControllerFunction<TContext, TSettings, TCallbacks = SignatureCallbacks> = (
1867
+ type GetTickControllerFunction<
1868
+ TContext = Record<string, Record<string, unknown>>,
1869
+ TSettings = unknown,
1870
+ TCallbacks = SignatureCallbacks,
1871
+ > = (
1864
1872
  args: TickControllerFunctionArgs<TContext, TSettings, TCallbacks>
1865
1873
  ) => Promise<TickControllerResult>;
1866
1874
  ```
@@ -1925,9 +1933,9 @@ type HostOverlay = 'facilitator-guide' | 'print-sheets';
1925
1933
 
1926
1934
  ```ts
1927
1935
  type InitAggregateFunction<
1928
- TTeamContext,
1929
- TSharedContext,
1930
- TSettings,
1936
+ TTeamContext = Record<string, Record<string, unknown>>,
1937
+ TSharedContext = Record<string, Record<string, unknown>>,
1938
+ TSettings = unknown,
1931
1939
  TCallbacks = SignatureCallbacks,
1932
1940
  TTeamState = never,
1933
1941
  TSharedState = never,
@@ -1947,8 +1955,8 @@ type InitAggregateFunction<
1947
1955
 
1948
1956
  ```ts
1949
1957
  type InitializationFunction<
1950
- TContext,
1951
- TSettings,
1958
+ TContext = Record<string, Record<string, unknown>>,
1959
+ TSettings = unknown,
1952
1960
  TCallbacks = SignatureCallbacks,
1953
1961
  TState = never,
1954
1962
  > = (
@@ -2003,9 +2011,9 @@ type RequestTickFunction<TContext = unknown, TSettings = unknown> = (
2003
2011
 
2004
2012
  ```ts
2005
2013
  type RunAggregateFunction<
2006
- TTeamContext,
2007
- TSharedContext,
2008
- TSettings,
2014
+ TTeamContext = Record<string, Record<string, unknown>>,
2015
+ TSharedContext = Record<string, Record<string, unknown>>,
2016
+ TSettings = unknown,
2009
2017
  TCallbacks = SignatureCallbacks,
2010
2018
  TTeamState = never,
2011
2019
  TSharedState = never,
@@ -2024,7 +2032,12 @@ type RunAggregateFunction<
2024
2032
  ### RunFunction
2025
2033
 
2026
2034
  ```ts
2027
- type RunFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = never> = (
2035
+ type RunFunction<
2036
+ TContext = Record<string, Record<string, unknown>>,
2037
+ TSettings = unknown,
2038
+ TCallbacks = SignatureCallbacks,
2039
+ TState = never,
2040
+ > = (
2028
2041
  args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
2029
2042
  ) => Promise<RunResult<TContext, TState>>;
2030
2043
  ```
@@ -2042,9 +2055,12 @@ type RunKind = 'session' | 'walkthrough';
2042
2055
  One step of an engine that splits its `Init` or `Run` into several functions.
2043
2056
 
2044
2057
  ```ts
2045
- type StepFunction<TContext, TSettings, TCallbacks = SignatureCallbacks, TState = unknown> = (
2046
- args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>
2047
- ) => Promise<TContext>;
2058
+ type StepFunction<
2059
+ TContext = Record<string, Record<string, unknown>>,
2060
+ TSettings = unknown,
2061
+ TCallbacks = SignatureCallbacks,
2062
+ TState = unknown,
2063
+ > = (args: EngineFunctionArgs<TContext, TSettings, TCallbacks, TState>) => Promise<TContext>;
2048
2064
  ```
2049
2065
 
2050
2066
  ### ThemePreference