@seriousgaming/sdk-tools 1.4.0 → 1.5.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 (157) hide show
  1. package/dist/cli.js +830 -99
  2. package/dist/client.js +114 -11
  3. package/dist/dev/console/assets/{index-BvB-LFQZ.js → index-BVF8exas.js} +21 -21
  4. package/dist/dev/console/index.html +1 -1
  5. package/dist/dev/public-origins.d.ts +61 -0
  6. package/dist/dev/shell.d.ts +32 -4
  7. package/dist/docs/ai-agents.md +5 -0
  8. package/dist/docs/changelog-0.x.md +2 -2
  9. package/dist/docs/changelog.md +37 -4
  10. package/dist/docs/cli-and-dev-server.md +58 -0
  11. package/dist/docs/cli-error-codes.md +39 -36
  12. package/dist/docs/cli-reference.md +68 -21
  13. package/dist/docs/environment-variables.md +10 -5
  14. package/dist/docs/guides/ai-facilitation.md +2 -0
  15. package/dist/docs/guides/capabilities.md +2 -0
  16. package/dist/docs/guides/designing-a-game.md +2 -0
  17. package/dist/docs/guides/designing-screens.md +133 -0
  18. package/dist/docs/guides/endpoints.md +2 -0
  19. package/dist/docs/guides/engine-testing.md +5 -1
  20. package/dist/docs/guides/engine.md +2 -0
  21. package/dist/docs/guides/file-handling.md +3 -1
  22. package/dist/docs/guides/games.md +3 -1
  23. package/dist/docs/guides/global-settings.md +2 -0
  24. package/dist/docs/guides/guide.md +2 -0
  25. package/dist/docs/guides/hooks.md +2 -0
  26. package/dist/docs/guides/index.md +9 -0
  27. package/dist/docs/guides/internationalization.md +2 -0
  28. package/dist/docs/guides/llm-integration.md +4 -2
  29. package/dist/docs/guides/multi-team-games.md +3 -1
  30. package/dist/docs/guides/patterns.md +2 -0
  31. package/dist/docs/guides/presentation.md +1 -1
  32. package/dist/docs/guides/production-constraints.md +2 -0
  33. package/dist/docs/guides/scenario-editor.md +2 -0
  34. package/dist/docs/guides/scenarios.md +6 -2
  35. package/dist/docs/guides/session-game-flow.md +365 -0
  36. package/dist/docs/guides/session-hooks.md +205 -0
  37. package/dist/docs/guides/session.md +27 -565
  38. package/dist/docs/guides/settings.md +2 -0
  39. package/dist/docs/guides/setup.md +3 -1
  40. package/dist/docs/guides/speech-generation.md +2 -0
  41. package/dist/docs/guides/starter-game.md +61 -21
  42. package/dist/docs/guides/testing.md +2 -0
  43. package/dist/docs/guides/tick-controller.md +3 -1
  44. package/dist/docs/guides/type-safety.md +2 -0
  45. package/dist/docs/guides/ui-files-and-llms.md +328 -0
  46. package/dist/docs/guides/ui-participants.md +281 -0
  47. package/dist/docs/guides/ui-styling.md +263 -0
  48. package/dist/docs/guides/ui-ticks.md +247 -0
  49. package/dist/docs/guides/ui.md +11 -1092
  50. package/dist/docs/guides/upgrading.md +2 -0
  51. package/dist/docs/guides/validators.md +2 -0
  52. package/dist/docs/guides/waiting-room.md +1 -1
  53. package/dist/docs/index.md +2 -1
  54. package/dist/docs/page-index.md +145 -0
  55. package/dist/docs/recipes/adapt-a-game-for-walkthroughs.md +1 -1
  56. package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
  57. package/dist/docs/recipes/create-presentation.md +11 -0
  58. package/dist/docs/recipes/create-scenario-editor.md +1 -0
  59. package/dist/docs/recipes/create-session-ui.md +2 -1
  60. package/dist/docs/recipes/create-setup.md +1 -0
  61. package/dist/docs/recipes/create-user-interface.md +1 -0
  62. package/dist/docs/recipes/create-waiting-room-ui.md +1 -0
  63. package/dist/docs/recipes/design-state-for-concurrent-writes.md +1 -1
  64. package/dist/docs/recipes/fix-duplicate-packages.md +2 -2
  65. package/dist/docs/recipes/index.md +3 -0
  66. package/dist/docs/recipes/screenshot-a-surface.md +80 -0
  67. package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
  68. package/dist/docs/recipes/use-request-tick.md +2 -2
  69. package/dist/execution/config-resolver.d.ts +4 -1
  70. package/dist/runtime/manifest-version.d.ts +1 -1
  71. package/dist/runtime.js +1 -1
  72. package/dist/templates/package/CLAUDE.md.template +14 -5
  73. package/dist/templates/package/DESIGN.md.liquid +39 -7
  74. package/dist/templates/package/README.md.liquid +1 -1
  75. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  76. package/dist/templates/package/pnpm-workspace.yaml.template +13 -0
  77. package/dist/templates/starter-game/capabilities/pacing/capability.sdk.json +18 -0
  78. package/dist/templates/starter-game/package.json +2 -0
  79. package/dist/templates/starter-game/presentation/defaults.ts +52 -0
  80. package/dist/templates/starter-game/presentation/index.html +20 -0
  81. package/dist/templates/starter-game/presentation/presentation.sdk.json +10 -0
  82. package/dist/templates/starter-game/presentation/src/App.tsx +55 -0
  83. package/dist/templates/starter-game/presentation/src/Band.tsx +40 -0
  84. package/dist/templates/starter-game/presentation/src/Slides.tsx +415 -0
  85. package/dist/templates/starter-game/presentation/src/WeatherIcon.tsx +21 -0
  86. package/dist/templates/starter-game/presentation/src/i18n.ts +88 -0
  87. package/dist/templates/starter-game/presentation/src/main.tsx +15 -0
  88. package/dist/templates/starter-game/presentation/src/stalls.test.ts +196 -0
  89. package/dist/templates/starter-game/presentation/src/stalls.ts +199 -0
  90. package/dist/templates/starter-game/presentation/types.ts +94 -0
  91. package/dist/templates/starter-game/seriousgaming.sdk.json +2 -1
  92. package/dist/templates/starter-game/session/defaults.ts +6 -0
  93. package/dist/templates/starter-game/session/index.html +1 -1
  94. package/dist/templates/starter-game/session/session.sdk.json +2 -2
  95. package/dist/templates/starter-game/session/src/App.test.tsx +436 -115
  96. package/dist/templates/starter-game/session/src/App.tsx +372 -222
  97. package/dist/templates/starter-game/session/src/JoinCodes.tsx +184 -0
  98. package/dist/templates/starter-game/session/src/ManagePanel.tsx +188 -0
  99. package/dist/templates/starter-game/session/src/Results.tsx +340 -0
  100. package/dist/templates/starter-game/session/src/SessionBar.tsx +179 -0
  101. package/dist/templates/starter-game/session/src/SessionPanels.tsx +105 -0
  102. package/dist/templates/starter-game/session/src/SidePanel.tsx +89 -0
  103. package/dist/templates/starter-game/session/src/StallCard.tsx +253 -0
  104. package/dist/templates/starter-game/session/src/TopBar.tsx +36 -0
  105. package/dist/templates/starter-game/session/src/i18n.ts +91 -24
  106. package/dist/templates/starter-game/session/src/status.ts +28 -0
  107. package/dist/templates/starter-game/session/types.ts +8 -2
  108. package/dist/templates/starter-game/shared/Awning.tsx +31 -0
  109. package/dist/templates/starter-game/shared/HostLogo.test.tsx +38 -0
  110. package/dist/templates/starter-game/shared/HostLogo.tsx +48 -0
  111. package/dist/templates/starter-game/shared/StallIcons.tsx +83 -0
  112. package/dist/templates/starter-game/shared/days.ts +11 -0
  113. package/dist/templates/starter-game/shared/format.test.ts +13 -0
  114. package/dist/templates/starter-game/{ui/src → shared}/format.ts +1 -1
  115. package/dist/templates/starter-game/testing/e2e/game.spec.ts +42 -8
  116. package/dist/templates/starter-game/ui/defaults.ts +3 -0
  117. package/dist/templates/starter-game/ui/src/App.test.tsx +197 -29
  118. package/dist/templates/starter-game/ui/src/App.tsx +176 -99
  119. package/dist/templates/starter-game/ui/src/DayBar.test.tsx +50 -7
  120. package/dist/templates/starter-game/ui/src/DayBar.tsx +96 -38
  121. package/dist/templates/starter-game/ui/src/DaysTable.tsx +69 -0
  122. package/dist/templates/starter-game/ui/src/FirstDay.tsx +37 -0
  123. package/dist/templates/starter-game/ui/src/Header.tsx +257 -0
  124. package/dist/templates/starter-game/ui/src/Lesson.tsx +63 -0
  125. package/dist/templates/starter-game/ui/src/MakeRow.tsx +98 -71
  126. package/dist/templates/starter-game/ui/src/Notices.tsx +59 -0
  127. package/dist/templates/starter-game/ui/src/PastDay.tsx +88 -0
  128. package/dist/templates/starter-game/ui/src/Section.tsx +26 -26
  129. package/dist/templates/starter-game/ui/src/ThemeToggle.tsx +25 -11
  130. package/dist/templates/starter-game/ui/src/TodayPanel.test.tsx +37 -33
  131. package/dist/templates/starter-game/ui/src/TodayPanel.tsx +66 -52
  132. package/dist/templates/starter-game/ui/src/WeatherCard.tsx +47 -0
  133. package/dist/templates/starter-game/ui/src/WeekOver.tsx +145 -0
  134. package/dist/templates/starter-game/ui/src/YesterdayPanel.tsx +65 -114
  135. package/dist/templates/starter-game/ui/src/days.ts +58 -0
  136. package/dist/templates/starter-game/ui/src/i18n.ts +86 -32
  137. package/dist/templates/starter-game/ui/src/test-helpers.ts +1 -0
  138. package/dist/templates/starter-game/ui/src/theme.ts +8 -8
  139. package/dist/templates/starter-game/ui/types.ts +6 -0
  140. package/dist/templates/starter-game/ui/ui.sdk.json +1 -1
  141. package/dist/templates/starter-game/validators/daylimit/defaults.ts +13 -0
  142. package/dist/templates/starter-game/validators/daylimit/logic/logic.test.ts +20 -0
  143. package/dist/templates/starter-game/validators/daylimit/logic/logic.ts +23 -0
  144. package/dist/templates/starter-game/validators/daylimit/types.ts +23 -0
  145. package/dist/templates/starter-game/validators/daylimit/validator.sdk.json +10 -0
  146. package/dist/templates/starter-game/waiting_room/src/App.test.tsx +83 -5
  147. package/dist/templates/starter-game/waiting_room/src/App.tsx +262 -119
  148. package/dist/templates/starter-game/waiting_room/src/i18n.ts +8 -4
  149. package/dist/utils/error-codes.d.ts +12 -0
  150. package/package.json +11 -4
  151. package/dist/templates/starter-game/session/src/Section.tsx +0 -37
  152. package/dist/templates/starter-game/session/src/TeamDoor.tsx +0 -96
  153. package/dist/templates/starter-game/session/src/format.ts +0 -8
  154. package/dist/templates/starter-game/ui/src/HistoryPanel.test.tsx +0 -74
  155. package/dist/templates/starter-game/ui/src/HistoryPanel.tsx +0 -120
  156. package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +0 -25
  157. package/dist/templates/starter-game/ui/src/HostLogo.tsx +0 -38
package/dist/client.js CHANGED
@@ -487,6 +487,10 @@ var ERROR_CODES = {
487
487
  category: "usage",
488
488
  description: "A file named on the command line does not exist or cannot be read."
489
489
  },
490
+ DOCS_SECTION_NOT_FOUND: {
491
+ category: "usage",
492
+ description: "The page `docs view --section` reads has no heading by that name; the details list the ones it has."
493
+ },
490
494
  RESOURCE_TYPE_UNKNOWN: {
491
495
  category: "usage",
492
496
  description: "The resource type does not exist, or does not support this operation."
@@ -677,6 +681,10 @@ var ERROR_CODES = {
677
681
  category: "refused",
678
682
  description: "Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at."
679
683
  },
684
+ SURFACE_NOT_RENDERED: {
685
+ category: "refused",
686
+ description: "`sdk screenshot` gave up on the page: its surface did not connect, or did not report its first paint before the timeout. error.details carries the page's console errors, failed requests and uncaught exceptions."
687
+ },
680
688
  SETTINGS_STALE: {
681
689
  category: "refused",
682
690
  description: "The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`."
@@ -718,6 +726,10 @@ var ERROR_CODES = {
718
726
  category: "environment",
719
727
  description: "The dev server could not be stopped."
720
728
  },
729
+ BROWSER_MISSING: {
730
+ category: "environment",
731
+ description: "`sdk screenshot` found no Playwright in the package's dependencies, or no Chromium installed for it. Add `@playwright/test` and run `pnpm exec playwright install chromium`."
732
+ },
721
733
  LLM_NOT_CONFIGURED: {
722
734
  category: "environment",
723
735
  description: "Logic called generateText, and the dev server or in-process session running it has no platform API key configured."
@@ -5898,12 +5910,23 @@ var ConfigResolver = class {
5898
5910
  /**
5899
5911
  * Resolve the active scenario from a provided ID or the game's default.
5900
5912
  * Returns null if the game declares no scenarios, or when null is passed
5901
- * to explicitly opt out of the default scenario (the settings defaults).
5913
+ * for a game with no default scenario (the settings defaults).
5914
+ *
5915
+ * A game that declares a default never runs on none (§6.7), so null is
5916
+ * refused for it, naming the default.
5902
5917
  */
5903
5918
  resolveScenario(scenarioId) {
5904
- if (scenarioId === null) return null;
5905
5919
  const game = this.ctx.getGame();
5906
5920
  const config = this.ctx.getConfig();
5921
+ if (scenarioId === null) {
5922
+ const fallback = config?.scenarios?.find((s) => s.definition.default);
5923
+ if (fallback) {
5924
+ throw new DeniedError(
5925
+ `This game runs on a scenario: its default is "${fallback.definition.identifier}", so it cannot run on none`
5926
+ );
5927
+ }
5928
+ return null;
5929
+ }
5907
5930
  if (!game || !config) return null;
5908
5931
  const allScenarios = config.scenarios || [];
5909
5932
  if (allScenarios.length === 0) return null;
@@ -29786,6 +29809,32 @@ async function watchPackage(packagePath, onChange, debounceMs = 150) {
29786
29809
  };
29787
29810
  }
29788
29811
 
29812
+ // cli/dev/public-origins.ts
29813
+ function publicAssetOrigin(origins, assetPort) {
29814
+ if (origins.publicAssetUrl) return origins.publicAssetUrl;
29815
+ if (!origins.publicUrl) return null;
29816
+ const url = new URL(origins.publicUrl);
29817
+ return `${url.protocol}//${url.hostname}:${assetPort}`;
29818
+ }
29819
+ function publicHmrOrigin(origins, assetPort, vitePort) {
29820
+ if (origins.publicHmrUrl) return origins.publicHmrUrl;
29821
+ const asset = publicAssetOrigin(origins, assetPort);
29822
+ if (!asset) return null;
29823
+ const url = new URL(asset);
29824
+ return `${url.protocol === "https:" ? "wss" : "ws"}://${url.hostname}:${vitePort}`;
29825
+ }
29826
+ function hmrClientTarget(origin) {
29827
+ const url = new URL(origin);
29828
+ const protocol = url.protocol === "wss:" ? "wss" : "ws";
29829
+ const clientPort = url.port ? Number(url.port) : protocol === "wss" ? 443 : 80;
29830
+ return { protocol, host: url.hostname, clientPort };
29831
+ }
29832
+ function publicHostnames(origins) {
29833
+ return [
29834
+ ...new Set(origins.filter((o) => Boolean(o)).map((o) => new URL(o).hostname))
29835
+ ];
29836
+ }
29837
+
29789
29838
  // cli/dev/routes.ts
29790
29839
  import { existsSync as existsSync19 } from "fs";
29791
29840
  import { readFile as readFile10 } from "fs/promises";
@@ -31283,6 +31332,8 @@ var DevShell = class {
31283
31332
  viteFailure = null;
31284
31333
  /** Serialises the first requests for a surface so they share one Vite. */
31285
31334
  viteStarting = null;
31335
+ /** The hot-reload socket's own listener, when a public origin moves its client. */
31336
+ hmrServer = null;
31286
31337
  port;
31287
31338
  vitePort;
31288
31339
  assetPort;
@@ -31381,7 +31432,7 @@ var DevShell = class {
31381
31432
  await this.viteStarting;
31382
31433
  await this.vite?.close();
31383
31434
  await Promise.all(
31384
- [this.server, this.assetServer].map(
31435
+ [this.server, this.assetServer, this.hmrServer].map(
31385
31436
  (server) => new Promise((resolve12) => {
31386
31437
  if (!server) return resolve12();
31387
31438
  server.close(() => resolve12());
@@ -31502,18 +31553,37 @@ var DevShell = class {
31502
31553
  get assetUrl() {
31503
31554
  return `http://localhost:${this.assetPort}`;
31504
31555
  }
31556
+ /** Where people reach the console, when a proxy stands in front of it. */
31557
+ get publicUrl() {
31558
+ return this.options.publicUrl ?? null;
31559
+ }
31560
+ /** Where people's browsers load bundles from, when a proxy stands in front. */
31561
+ get publicAssetUrl() {
31562
+ return publicAssetOrigin(this.options, this.assetPort);
31563
+ }
31505
31564
  /**
31506
- * The asset origin as a client that reached `host` must name it: the same
31507
- * host, the asset port. A browser on another machine reached us by an
31508
- * address `localhost` would not resolve to on its side.
31565
+ * The asset origin as a client that reached `host` must name it: the
31566
+ * public one where given, else the same host on the asset port. A browser
31567
+ * on another machine reached us by an address `localhost` would not
31568
+ * resolve to on its side.
31509
31569
  */
31510
31570
  assetOrigin(host) {
31571
+ const configured = this.publicAssetUrl;
31572
+ if (configured) return configured;
31511
31573
  const name = (host ?? "localhost").replace(/:\d+$/, "") || "localhost";
31512
31574
  return `http://${name}:${this.assetPort}`;
31513
31575
  }
31514
31576
  /** The console's own origin, as a client that reached `host` names it. */
31515
31577
  consoleOrigin(host) {
31516
- return host ? `http://${host}` : this.url;
31578
+ return this.options.publicUrl ?? (host ? `http://${host}` : this.url);
31579
+ }
31580
+ /** Where a frame's hot-reload client connects, when a public origin decides it. */
31581
+ get publicHmrUrl() {
31582
+ return publicHmrOrigin(this.options, this.assetPort, this.vitePort);
31583
+ }
31584
+ /** What the bundle policy's `connect-src` admits for hot reload. */
31585
+ hmrSources(host) {
31586
+ return this.publicHmrUrl ?? hmrConnectSources(host, this.vitePort);
31517
31587
  }
31518
31588
  /** The session this shell wraps, for tests and for the CLI in-process path. */
31519
31589
  get runtime() {
@@ -31644,7 +31714,7 @@ ${MISSING_CONSOLE_MESSAGE}
31644
31714
  */
31645
31715
  configureAssets() {
31646
31716
  this.assetApp.use((req, res, next) => {
31647
- applyBundlePolicy(res, req.headers.host, this.vitePort);
31717
+ applyBundlePolicy(res, this.hmrSources(req.headers.host));
31648
31718
  next();
31649
31719
  });
31650
31720
  registerAssetRoutes(
@@ -31703,6 +31773,7 @@ Install the package's dependencies to serve its surfaces.
31703
31773
  return this.viteStarting;
31704
31774
  }
31705
31775
  async createVite() {
31776
+ const server = await this.viteServerOptions();
31706
31777
  return createViteServer({
31707
31778
  root: this.options.packagePath,
31708
31779
  appType: "custom",
@@ -31725,10 +31796,43 @@ Install the package's dependencies to serve its surfaces.
31725
31796
  workingDir: this.options.packagePath
31726
31797
  })
31727
31798
  ],
31728
- server: { middlewareMode: true, hmr: { port: this.vitePort, ...this.bindHost } },
31799
+ server,
31729
31800
  logLevel: "error"
31730
31801
  });
31731
31802
  }
31803
+ /**
31804
+ * Vite's server options: its own hot-reload socket on the Vite port, as
31805
+ * before, unless a public origin says where the client connects.
31806
+ *
31807
+ * Vite takes one `host` for both where its socket listens and where its
31808
+ * client connects, and a public hostname is no address to listen on. So
31809
+ * behind a proxy the socket's listener is opened here, on the Vite port
31810
+ * as usual, and Vite only attaches to it.
31811
+ */
31812
+ async viteServerOptions() {
31813
+ const hmr = this.publicHmrUrl;
31814
+ if (!hmr) {
31815
+ return { middlewareMode: true, hmr: { port: this.vitePort, ...this.bindHost } };
31816
+ }
31817
+ const listener = createServer((_req, res) => {
31818
+ res.writeHead(426, { "Content-Type": "text/plain" }).end("Upgrade Required");
31819
+ });
31820
+ await new Promise((resolve12, reject) => {
31821
+ listener.once("error", reject);
31822
+ listener.listen(this.vitePort, this.bindHost.host, () => {
31823
+ listener.off("error", reject);
31824
+ resolve12();
31825
+ });
31826
+ });
31827
+ this.hmrServer = listener;
31828
+ return {
31829
+ middlewareMode: true,
31830
+ ws: { server: listener, ...hmrClientTarget(hmr) },
31831
+ // Vite refuses a request whose `Host` it does not recognise, and a
31832
+ // proxy that passes its own on would otherwise be refused it.
31833
+ allowedHosts: publicHostnames([this.options.publicUrl, this.publicAssetUrl, hmr])
31834
+ };
31835
+ }
31732
31836
  // -----------------------------------------------------------------------
31733
31837
  // WebSocket
31734
31838
  // -----------------------------------------------------------------------
@@ -32048,8 +32152,7 @@ function send(socket, message) {
32048
32152
  if (socket.readyState !== 1) return;
32049
32153
  socket.send(JSON.stringify(message));
32050
32154
  }
32051
- function applyBundlePolicy(res, host, vitePort) {
32052
- const hmr = hmrConnectSources(host, vitePort);
32155
+ function applyBundlePolicy(res, hmr) {
32053
32156
  res.setHeader(
32054
32157
  "Content-Security-Policy",
32055
32158
  [