@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/cli.js CHANGED
@@ -430,6 +430,10 @@ var ERROR_CODES = {
430
430
  category: "usage",
431
431
  description: "A file named on the command line does not exist or cannot be read."
432
432
  },
433
+ DOCS_SECTION_NOT_FOUND: {
434
+ category: "usage",
435
+ description: "The page `docs view --section` reads has no heading by that name; the details list the ones it has."
436
+ },
433
437
  RESOURCE_TYPE_UNKNOWN: {
434
438
  category: "usage",
435
439
  description: "The resource type does not exist, or does not support this operation."
@@ -620,6 +624,10 @@ var ERROR_CODES = {
620
624
  category: "refused",
621
625
  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."
622
626
  },
627
+ SURFACE_NOT_RENDERED: {
628
+ category: "refused",
629
+ 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."
630
+ },
623
631
  SETTINGS_STALE: {
624
632
  category: "refused",
625
633
  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`."
@@ -661,6 +669,10 @@ var ERROR_CODES = {
661
669
  category: "environment",
662
670
  description: "The dev server could not be stopped."
663
671
  },
672
+ BROWSER_MISSING: {
673
+ category: "environment",
674
+ 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`."
675
+ },
664
676
  LLM_NOT_CONFIGURED: {
665
677
  category: "environment",
666
678
  description: "Logic called generateText, and the dev server or in-process session running it has no platform API key configured."
@@ -3543,7 +3555,7 @@ function gameOverrideRefusal(overrides) {
3543
3555
 
3544
3556
  // cli/runtime/manifest-version.ts
3545
3557
  var MANIFEST_VERSION = 3;
3546
- var SPEC_REVISION = "1.4";
3558
+ var SPEC_REVISION = "1.5";
3547
3559
  var SUPPORTED_FEATURES = [
3548
3560
  // A validator's `Scenario` gate (§15.8).
3549
3561
  "scenario-validation",
@@ -5920,12 +5932,23 @@ var ConfigResolver = class {
5920
5932
  /**
5921
5933
  * Resolve the active scenario from a provided ID or the game's default.
5922
5934
  * Returns null if the game declares no scenarios, or when null is passed
5923
- * to explicitly opt out of the default scenario (the settings defaults).
5935
+ * for a game with no default scenario (the settings defaults).
5936
+ *
5937
+ * A game that declares a default never runs on none (§6.7), so null is
5938
+ * refused for it, naming the default.
5924
5939
  */
5925
5940
  resolveScenario(scenarioId) {
5926
- if (scenarioId === null) return null;
5927
5941
  const game = this.ctx.getGame();
5928
5942
  const config = this.ctx.getConfig();
5943
+ if (scenarioId === null) {
5944
+ const fallback = config?.scenarios?.find((s) => s.definition.default);
5945
+ if (fallback) {
5946
+ throw new DeniedError(
5947
+ `This game runs on a scenario: its default is "${fallback.definition.identifier}", so it cannot run on none`
5948
+ );
5949
+ }
5950
+ return null;
5951
+ }
5929
5952
  if (!game || !config) return null;
5930
5953
  const allScenarios = config.scenarios || [];
5931
5954
  if (allScenarios.length === 0) return null;
@@ -14948,10 +14971,10 @@ function resolveAll(constructs2, events, context) {
14948
14971
  const called = [];
14949
14972
  let index3 = -1;
14950
14973
  while (++index3 < constructs2.length) {
14951
- const resolve35 = constructs2[index3].resolveAll;
14952
- if (resolve35 && !called.includes(resolve35)) {
14953
- events = resolve35(events, context);
14954
- called.push(resolve35);
14974
+ const resolve36 = constructs2[index3].resolveAll;
14975
+ if (resolve36 && !called.includes(resolve36)) {
14976
+ events = resolve36(events, context);
14977
+ called.push(resolve36);
14955
14978
  }
14956
14979
  }
14957
14980
  return events;
@@ -19932,20 +19955,20 @@ function compiler(options) {
19932
19955
  data
19933
19956
  };
19934
19957
  const listStack = [];
19935
- const prepared = [];
19958
+ const prepared2 = [];
19936
19959
  let index3 = -1;
19937
19960
  while (++index3 < events.length) {
19938
- prepared.push(events[index3]);
19961
+ prepared2.push(events[index3]);
19939
19962
  if (events[index3][1].type === "listOrdered" || events[index3][1].type === "listUnordered") {
19940
19963
  if (events[index3][0] === "enter") {
19941
- listStack.push(prepared.length - 1);
19964
+ listStack.push(prepared2.length - 1);
19942
19965
  } else {
19943
19966
  const tail = listStack.pop();
19944
- prepareList(prepared, tail);
19967
+ prepareList(prepared2, tail);
19945
19968
  }
19946
19969
  }
19947
19970
  }
19948
- events = prepared;
19971
+ events = prepared2;
19949
19972
  index3 = -1;
19950
19973
  while (++index3 < events.length) {
19951
19974
  const handler = config[events[index3][0]];
@@ -20958,9 +20981,9 @@ var VFile = class {
20958
20981
  * @returns {undefined}
20959
20982
  * Nothing.
20960
20983
  */
20961
- set dirname(dirname22) {
20984
+ set dirname(dirname23) {
20962
20985
  assertPath(this.basename, "dirname");
20963
- this.path = default2.join(dirname22 || "", this.basename);
20986
+ this.path = default2.join(dirname23 || "", this.basename);
20964
20987
  }
20965
20988
  /**
20966
20989
  * Get the extname (including dot) (example: `'.js'`).
@@ -21559,7 +21582,7 @@ var Processor = class _Processor extends CallableInstance {
21559
21582
  assertParser("process", this.parser || this.Parser);
21560
21583
  assertCompiler("process", this.compiler || this.Compiler);
21561
21584
  return done ? executor(void 0, done) : new Promise(executor);
21562
- function executor(resolve35, reject) {
21585
+ function executor(resolve36, reject) {
21563
21586
  const realFile = vfile(file);
21564
21587
  const parseTree = (
21565
21588
  /** @type {HeadTree extends undefined ? Node : HeadTree} */
@@ -21590,8 +21613,8 @@ var Processor = class _Processor extends CallableInstance {
21590
21613
  function realDone(error, file2) {
21591
21614
  if (error || !file2) {
21592
21615
  reject(error);
21593
- } else if (resolve35) {
21594
- resolve35(file2);
21616
+ } else if (resolve36) {
21617
+ resolve36(file2);
21595
21618
  } else {
21596
21619
  ok(done, "`done` is defined if `resolve` is not");
21597
21620
  done(void 0, file2);
@@ -21693,7 +21716,7 @@ var Processor = class _Processor extends CallableInstance {
21693
21716
  file = void 0;
21694
21717
  }
21695
21718
  return done ? executor(void 0, done) : new Promise(executor);
21696
- function executor(resolve35, reject) {
21719
+ function executor(resolve36, reject) {
21697
21720
  ok(
21698
21721
  typeof file !== "function",
21699
21722
  "`file` can\u2019t be a `done` anymore, we checked"
@@ -21707,8 +21730,8 @@ var Processor = class _Processor extends CallableInstance {
21707
21730
  );
21708
21731
  if (error) {
21709
21732
  reject(error);
21710
- } else if (resolve35) {
21711
- resolve35(resultingTree);
21733
+ } else if (resolve36) {
21734
+ resolve36(resultingTree);
21712
21735
  } else {
21713
21736
  ok(done, "`done` is defined if `resolve` is not");
21714
21737
  done(void 0, resultingTree, file2);
@@ -22611,7 +22634,7 @@ function fileSettingDeclarationErrors(identifier, settingsSchema) {
22611
22634
  }
22612
22635
  return errors;
22613
22636
  }
22614
- async function packageFileSettingErrors(owner, settings, schemas, resolve35, skip = () => false) {
22637
+ async function packageFileSettingErrors(owner, settings, schemas, resolve36, skip = () => false) {
22615
22638
  const errors = [];
22616
22639
  for (const [identifier, value] of Object.entries(settings)) {
22617
22640
  for (const file of fileSettingValues(schemas[identifier], value)) {
@@ -22623,7 +22646,7 @@ async function packageFileSettingErrors(owner, settings, schemas, resolve35, ski
22623
22646
  );
22624
22647
  continue;
22625
22648
  }
22626
- const found = await resolve35(file.value);
22649
+ const found = await resolve36(file.value);
22627
22650
  if (!found) {
22628
22651
  errors.push(`${setting}, but the package ships no such file`);
22629
22652
  continue;
@@ -31381,7 +31404,7 @@ async function released(packagePath, lock, timeoutMs) {
31381
31404
  return true;
31382
31405
  }
31383
31406
  if (Date.now() >= deadline) return false;
31384
- await new Promise((resolve35) => setTimeout(resolve35, 100));
31407
+ await new Promise((resolve36) => setTimeout(resolve36, 100));
31385
31408
  }
31386
31409
  }
31387
31410
 
@@ -31590,6 +31613,9 @@ ${PENDING_CHANGES_HINT}` : `Warning: ${notice.message}`
31590
31613
  );
31591
31614
  }
31592
31615
  }
31616
+ function connectSession(url, run = "session") {
31617
+ return connect(url, run);
31618
+ }
31593
31619
  function connect(url, run) {
31594
31620
  const query = run === "walkthrough" ? "?run=walkthrough" : "";
31595
31621
  return {
@@ -31792,13 +31818,13 @@ function readStdin() {
31792
31818
  if (stdin.isTTY) return Promise.resolve(null);
31793
31819
  const previous4 = reads.get(stdin);
31794
31820
  if (previous4) return previous4;
31795
- const read = new Promise((resolve35, reject) => {
31821
+ const read = new Promise((resolve36, reject) => {
31796
31822
  let data = "";
31797
31823
  stdin.setEncoding("utf-8");
31798
31824
  stdin.on("data", (chunk) => {
31799
31825
  data += chunk;
31800
31826
  });
31801
- stdin.on("end", () => resolve35(data.trim() || null));
31827
+ stdin.on("end", () => resolve36(data.trim() || null));
31802
31828
  stdin.on("error", reject);
31803
31829
  });
31804
31830
  reads.set(stdin, read);
@@ -32647,18 +32673,18 @@ async function createPackageFiles(options) {
32647
32673
  }
32648
32674
  }
32649
32675
  async function runNpmInstall(packagePath) {
32650
- return new Promise((resolve35) => {
32676
+ return new Promise((resolve36) => {
32651
32677
  const npm = spawn2("pnpm", ["install"], {
32652
32678
  cwd: packagePath,
32653
32679
  shell: true,
32654
32680
  stdio: isJsonOutput() ? ["ignore", 2, "inherit"] : "inherit"
32655
32681
  });
32656
32682
  npm.on("close", (code3) => {
32657
- resolve35(code3 === 0);
32683
+ resolve36(code3 === 0);
32658
32684
  });
32659
32685
  npm.on("error", (error) => {
32660
32686
  console.error("Failed to run pnpm install:", error.message);
32661
- resolve35(false);
32687
+ resolve36(false);
32662
32688
  });
32663
32689
  });
32664
32690
  }
@@ -37921,6 +37947,73 @@ function networkAddresses(interfaces = networkInterfaces()) {
37921
37947
  return Object.values(interfaces).flatMap((entries) => entries ?? []).filter((entry) => entry.family === "IPv4" && !entry.internal).map((entry) => entry.address);
37922
37948
  }
37923
37949
 
37950
+ // cli/dev/public-origins.ts
37951
+ var PUBLIC_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_URL";
37952
+ var PUBLIC_ASSET_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_ASSET_URL";
37953
+ var PUBLIC_HMR_URL_ENV_VAR = "SERIOUSGAMING_DEV_PUBLIC_HMR_URL";
37954
+ function parsePublicOrigin(value, flag, kind2) {
37955
+ const allowed = kind2 === "http" ? ["http:", "https:"] : ["http:", "https:", "ws:", "wss:"];
37956
+ let url;
37957
+ try {
37958
+ url = new URL(value.trim());
37959
+ } catch {
37960
+ throw badOrigin(value, flag, kind2);
37961
+ }
37962
+ if (!allowed.includes(url.protocol) || url.pathname !== "/" && url.pathname !== "") {
37963
+ throw badOrigin(value, flag, kind2);
37964
+ }
37965
+ if (url.search || url.hash || url.username || url.password) throw badOrigin(value, flag, kind2);
37966
+ if (kind2 === "ws") {
37967
+ const secure = url.protocol === "https:" || url.protocol === "wss:";
37968
+ return `${secure ? "wss" : "ws"}://${url.host}`;
37969
+ }
37970
+ return url.origin;
37971
+ }
37972
+ function badOrigin(value, flag, kind2) {
37973
+ const example = kind2 === "http" ? "https://game.example.com" : "wss://hmr.example.com";
37974
+ return new CliError(
37975
+ "USAGE_BAD_FLAG",
37976
+ `"${value}" is not an origin ${flag} can take. Pass a scheme, a host and, where it is not the default, a port, with no path: ${example}.`
37977
+ );
37978
+ }
37979
+ function resolvePublicOrigins(flags, env = process.env) {
37980
+ const pick = (flag, name) => flag || env[name] || void 0;
37981
+ const publicUrl = pick(flags.publicUrl, PUBLIC_URL_ENV_VAR);
37982
+ const publicAssetUrl = pick(flags.publicAssetUrl, PUBLIC_ASSET_URL_ENV_VAR);
37983
+ const publicHmrUrl = pick(flags.publicHmrUrl, PUBLIC_HMR_URL_ENV_VAR);
37984
+ return {
37985
+ ...publicUrl ? { publicUrl: parsePublicOrigin(publicUrl, "--public-url", "http") } : {},
37986
+ ...publicAssetUrl ? {
37987
+ publicAssetUrl: parsePublicOrigin(publicAssetUrl, "--public-asset-url", "http")
37988
+ } : {},
37989
+ ...publicHmrUrl ? { publicHmrUrl: parsePublicOrigin(publicHmrUrl, "--public-hmr-url", "ws") } : {}
37990
+ };
37991
+ }
37992
+ function publicAssetOrigin(origins, assetPort) {
37993
+ if (origins.publicAssetUrl) return origins.publicAssetUrl;
37994
+ if (!origins.publicUrl) return null;
37995
+ const url = new URL(origins.publicUrl);
37996
+ return `${url.protocol}//${url.hostname}:${assetPort}`;
37997
+ }
37998
+ function publicHmrOrigin(origins, assetPort, vitePort) {
37999
+ if (origins.publicHmrUrl) return origins.publicHmrUrl;
38000
+ const asset = publicAssetOrigin(origins, assetPort);
38001
+ if (!asset) return null;
38002
+ const url = new URL(asset);
38003
+ return `${url.protocol === "https:" ? "wss" : "ws"}://${url.hostname}:${vitePort}`;
38004
+ }
38005
+ function hmrClientTarget(origin) {
38006
+ const url = new URL(origin);
38007
+ const protocol = url.protocol === "wss:" ? "wss" : "ws";
38008
+ const clientPort = url.port ? Number(url.port) : protocol === "wss" ? 443 : 80;
38009
+ return { protocol, host: url.hostname, clientPort };
38010
+ }
38011
+ function publicHostnames(origins) {
38012
+ return [
38013
+ ...new Set(origins.filter((o) => Boolean(o)).map((o) => new URL(o).hostname))
38014
+ ];
38015
+ }
38016
+
37924
38017
  // cli/dev/shell.ts
37925
38018
  import { mkdtemp as mkdtemp2, rm as rm7 } from "fs/promises";
37926
38019
  import { createServer } from "http";
@@ -37951,7 +38044,7 @@ async function listenWithPortFallback(server, startPort, options = {}) {
37951
38044
  );
37952
38045
  }
37953
38046
  function tryListen(server, port, host) {
37954
- return new Promise((resolve35, reject) => {
38047
+ return new Promise((resolve36, reject) => {
37955
38048
  const cleanup = () => {
37956
38049
  server.removeListener("error", onError);
37957
38050
  server.removeListener("listening", onListening);
@@ -37959,14 +38052,14 @@ function tryListen(server, port, host) {
37959
38052
  const onError = (err) => {
37960
38053
  cleanup();
37961
38054
  if (err.code === "EADDRINUSE") {
37962
- resolve35(false);
38055
+ resolve36(false);
37963
38056
  } else {
37964
38057
  reject(err);
37965
38058
  }
37966
38059
  };
37967
38060
  const onListening = () => {
37968
38061
  cleanup();
37969
- resolve35(true);
38062
+ resolve36(true);
37970
38063
  };
37971
38064
  server.once("error", onError);
37972
38065
  server.once("listening", onListening);
@@ -37996,13 +38089,13 @@ async function isFree(port) {
37996
38089
  return true;
37997
38090
  }
37998
38091
  function isFreeOn(port, host) {
37999
- return new Promise((resolve35) => {
38092
+ return new Promise((resolve36) => {
38000
38093
  const probe = createSocket();
38001
38094
  probe.once(
38002
38095
  "error",
38003
- (error) => resolve35(error.code === "EADDRNOTAVAIL" || error.code === "EAFNOSUPPORT")
38096
+ (error) => resolve36(error.code === "EADDRNOTAVAIL" || error.code === "EAFNOSUPPORT")
38004
38097
  );
38005
- probe.once("listening", () => probe.close(() => resolve35(true)));
38098
+ probe.once("listening", () => probe.close(() => resolve36(true)));
38006
38099
  probe.listen(port, host);
38007
38100
  });
38008
38101
  }
@@ -38474,9 +38567,9 @@ function summarise(brand, assetOrigin) {
38474
38567
  // cli/dev/console-path.ts
38475
38568
  import { existsSync as existsSync32 } from "fs";
38476
38569
  import { join as join48, sep as sep13 } from "path";
38477
- function resolveConsolePath(dirname22, filename, fileExists = existsSync32) {
38570
+ function resolveConsolePath(dirname23, filename, fileExists = existsSync32) {
38478
38571
  const fromSource = filename.includes(`${sep13}cli${sep13}dev${sep13}`) || filename.includes("/cli/dev/");
38479
- const path3 = fromSource ? join48(dirname22, "..", "..", "dist", "dev", "console") : join48(dirname22, "dev", "console");
38572
+ const path3 = fromSource ? join48(dirname23, "..", "..", "dist", "dev", "console") : join48(dirname23, "dev", "console");
38480
38573
  return { path: path3, built: fileExists(join48(path3, "index.html")) };
38481
38574
  }
38482
38575
  var MISSING_CONSOLE_MESSAGE = "The dev console has not been built yet. Run `pnpm build` in sdk-tools, or `pnpm exec vite build cli/dev/console` to build just the console.";
@@ -38534,7 +38627,7 @@ async function untilWatchesDeliver(timeoutMs = 2e3) {
38534
38627
  const deadline = Date.now() + timeoutMs;
38535
38628
  for (let attempt = 0; !delivered && Date.now() < deadline; attempt++) {
38536
38629
  await writeFile15(join49(directory, "probe"), String(attempt));
38537
- await new Promise((resolve35) => setTimeout(resolve35, 25));
38630
+ await new Promise((resolve36) => setTimeout(resolve36, 25));
38538
38631
  }
38539
38632
  return async () => {
38540
38633
  probe.close();
@@ -38566,7 +38659,7 @@ async function watchPackage(packagePath, onChange, debounceMs = 150) {
38566
38659
  const change = classifyChange(packagePath, path3);
38567
38660
  if (change) schedule(change);
38568
38661
  });
38569
- await new Promise((resolve35) => watcher.once("ready", () => resolve35()));
38662
+ await new Promise((resolve36) => watcher.once("ready", () => resolve36()));
38570
38663
  const closeProbe = await untilWatchesDeliver();
38571
38664
  return {
38572
38665
  async close() {
@@ -39820,6 +39913,8 @@ var DevShell = class {
39820
39913
  viteFailure = null;
39821
39914
  /** Serialises the first requests for a surface so they share one Vite. */
39822
39915
  viteStarting = null;
39916
+ /** The hot-reload socket's own listener, when a public origin moves its client. */
39917
+ hmrServer = null;
39823
39918
  port;
39824
39919
  vitePort;
39825
39920
  assetPort;
@@ -39918,10 +40013,10 @@ var DevShell = class {
39918
40013
  await this.viteStarting;
39919
40014
  await this.vite?.close();
39920
40015
  await Promise.all(
39921
- [this.server, this.assetServer].map(
39922
- (server) => new Promise((resolve35) => {
39923
- if (!server) return resolve35();
39924
- server.close(() => resolve35());
40016
+ [this.server, this.assetServer, this.hmrServer].map(
40017
+ (server) => new Promise((resolve36) => {
40018
+ if (!server) return resolve36();
40019
+ server.close(() => resolve36());
39925
40020
  })
39926
40021
  )
39927
40022
  );
@@ -40039,18 +40134,37 @@ var DevShell = class {
40039
40134
  get assetUrl() {
40040
40135
  return `http://localhost:${this.assetPort}`;
40041
40136
  }
40137
+ /** Where people reach the console, when a proxy stands in front of it. */
40138
+ get publicUrl() {
40139
+ return this.options.publicUrl ?? null;
40140
+ }
40141
+ /** Where people's browsers load bundles from, when a proxy stands in front. */
40142
+ get publicAssetUrl() {
40143
+ return publicAssetOrigin(this.options, this.assetPort);
40144
+ }
40042
40145
  /**
40043
- * The asset origin as a client that reached `host` must name it: the same
40044
- * host, the asset port. A browser on another machine reached us by an
40045
- * address `localhost` would not resolve to on its side.
40146
+ * The asset origin as a client that reached `host` must name it: the
40147
+ * public one where given, else the same host on the asset port. A browser
40148
+ * on another machine reached us by an address `localhost` would not
40149
+ * resolve to on its side.
40046
40150
  */
40047
40151
  assetOrigin(host) {
40152
+ const configured = this.publicAssetUrl;
40153
+ if (configured) return configured;
40048
40154
  const name = (host ?? "localhost").replace(/:\d+$/, "") || "localhost";
40049
40155
  return `http://${name}:${this.assetPort}`;
40050
40156
  }
40051
40157
  /** The console's own origin, as a client that reached `host` names it. */
40052
40158
  consoleOrigin(host) {
40053
- return host ? `http://${host}` : this.url;
40159
+ return this.options.publicUrl ?? (host ? `http://${host}` : this.url);
40160
+ }
40161
+ /** Where a frame's hot-reload client connects, when a public origin decides it. */
40162
+ get publicHmrUrl() {
40163
+ return publicHmrOrigin(this.options, this.assetPort, this.vitePort);
40164
+ }
40165
+ /** What the bundle policy's `connect-src` admits for hot reload. */
40166
+ hmrSources(host) {
40167
+ return this.publicHmrUrl ?? hmrConnectSources(host, this.vitePort);
40054
40168
  }
40055
40169
  /** The session this shell wraps, for tests and for the CLI in-process path. */
40056
40170
  get runtime() {
@@ -40181,7 +40295,7 @@ ${MISSING_CONSOLE_MESSAGE}
40181
40295
  */
40182
40296
  configureAssets() {
40183
40297
  this.assetApp.use((req, res, next) => {
40184
- applyBundlePolicy(res, req.headers.host, this.vitePort);
40298
+ applyBundlePolicy(res, this.hmrSources(req.headers.host));
40185
40299
  next();
40186
40300
  });
40187
40301
  registerAssetRoutes(
@@ -40240,6 +40354,7 @@ Install the package's dependencies to serve its surfaces.
40240
40354
  return this.viteStarting;
40241
40355
  }
40242
40356
  async createVite() {
40357
+ const server = await this.viteServerOptions();
40243
40358
  return createViteServer({
40244
40359
  root: this.options.packagePath,
40245
40360
  appType: "custom",
@@ -40262,10 +40377,43 @@ Install the package's dependencies to serve its surfaces.
40262
40377
  workingDir: this.options.packagePath
40263
40378
  })
40264
40379
  ],
40265
- server: { middlewareMode: true, hmr: { port: this.vitePort, ...this.bindHost } },
40380
+ server,
40266
40381
  logLevel: "error"
40267
40382
  });
40268
40383
  }
40384
+ /**
40385
+ * Vite's server options: its own hot-reload socket on the Vite port, as
40386
+ * before, unless a public origin says where the client connects.
40387
+ *
40388
+ * Vite takes one `host` for both where its socket listens and where its
40389
+ * client connects, and a public hostname is no address to listen on. So
40390
+ * behind a proxy the socket's listener is opened here, on the Vite port
40391
+ * as usual, and Vite only attaches to it.
40392
+ */
40393
+ async viteServerOptions() {
40394
+ const hmr = this.publicHmrUrl;
40395
+ if (!hmr) {
40396
+ return { middlewareMode: true, hmr: { port: this.vitePort, ...this.bindHost } };
40397
+ }
40398
+ const listener = createServer((_req, res) => {
40399
+ res.writeHead(426, { "Content-Type": "text/plain" }).end("Upgrade Required");
40400
+ });
40401
+ await new Promise((resolve36, reject) => {
40402
+ listener.once("error", reject);
40403
+ listener.listen(this.vitePort, this.bindHost.host, () => {
40404
+ listener.off("error", reject);
40405
+ resolve36();
40406
+ });
40407
+ });
40408
+ this.hmrServer = listener;
40409
+ return {
40410
+ middlewareMode: true,
40411
+ ws: { server: listener, ...hmrClientTarget(hmr) },
40412
+ // Vite refuses a request whose `Host` it does not recognise, and a
40413
+ // proxy that passes its own on would otherwise be refused it.
40414
+ allowedHosts: publicHostnames([this.options.publicUrl, this.publicAssetUrl, hmr])
40415
+ };
40416
+ }
40269
40417
  // -----------------------------------------------------------------------
40270
40418
  // WebSocket
40271
40419
  // -----------------------------------------------------------------------
@@ -40585,8 +40733,7 @@ function send(socket, message) {
40585
40733
  if (socket.readyState !== 1) return;
40586
40734
  socket.send(JSON.stringify(message));
40587
40735
  }
40588
- function applyBundlePolicy(res, host, vitePort) {
40589
- const hmr = hmrConnectSources(host, vitePort);
40736
+ function applyBundlePolicy(res, hmr) {
40590
40737
  res.setHeader(
40591
40738
  "Content-Security-Policy",
40592
40739
  [
@@ -40619,6 +40766,7 @@ async function devCommand(options) {
40619
40766
  const assetPort = options.assetPort === void 0 ? void 0 : parseDevPort(options.assetPort);
40620
40767
  const teams = options.teams === void 0 ? void 0 : teamCountFromFlag(options.teams);
40621
40768
  const scenarioId = options.scenario === void 0 ? void 0 : requireScenario(packagePath, options.scenario);
40769
+ const publicOrigins = resolvePublicOrigins(options);
40622
40770
  const envConfig = loadEnvironmentConfig(packagePath, {
40623
40771
  seriousGamingApiKey: options.apiKey,
40624
40772
  seriousGamingApiHost: options.host
@@ -40648,6 +40796,7 @@ A package holds one session, so this is it, whichever port you asked for.
40648
40796
  port,
40649
40797
  ...vitePort === void 0 ? {} : { vitePort },
40650
40798
  ...assetPort === void 0 ? {} : { assetPort },
40799
+ ...publicOrigins,
40651
40800
  ...scenarioId === void 0 ? {} : { scenarioId },
40652
40801
  ...envConfig.seriousGamingApiKey === void 0 ? {} : { seriousGamingApiKey: envConfig.seriousGamingApiKey },
40653
40802
  ...envConfig.seriousGamingApiHost === void 0 ? {} : { seriousGamingApiHost: envConfig.seriousGamingApiHost },
@@ -40666,8 +40815,8 @@ A package holds one session, so this is it, whichever port you asked for.
40666
40815
  let isShuttingDown = false;
40667
40816
  let stopped = () => {
40668
40817
  };
40669
- const untilStopped = new Promise((resolve35) => {
40670
- stopped = resolve35;
40818
+ const untilStopped = new Promise((resolve36) => {
40819
+ stopped = resolve36;
40671
40820
  });
40672
40821
  const shutdown = async () => {
40673
40822
  if (isShuttingDown) return;
@@ -40687,6 +40836,10 @@ A package holds one session, so this is it, whichever port you asked for.
40687
40836
  console.log(`
40688
40837
  \u2713 Dev server running at ${server.url}`);
40689
40838
  console.log(` Game surfaces are served from ${server.assetUrl}`);
40839
+ if (server.publicUrl) console.log(` People reach it at ${server.publicUrl}`);
40840
+ if (server.publicAssetUrl) {
40841
+ console.log(` Their browsers load game surfaces from ${server.publicAssetUrl}`);
40842
+ }
40690
40843
  if (options.isolated) {
40691
40844
  console.log(
40692
40845
  ` Isolated: no lock file, so CLI commands reach it only through SERIOUSGAMING_DEV_URL=${server.url}. Configuration comes from the package alone, and uploads go to a temporary directory removed on stop.`
@@ -40700,7 +40853,7 @@ A package holds one session, so this is it, whichever port you asked for.
40700
40853
  console.log(reachability(server.url, server.reachableFromNetwork));
40701
40854
  console.log("\nPress Ctrl+C to stop the server\n");
40702
40855
  if (options.open !== false) {
40703
- await open(server.url);
40856
+ await open(server.publicUrl ?? server.url);
40704
40857
  }
40705
40858
  process.on("SIGINT", shutdown);
40706
40859
  process.on("SIGTERM", shutdown);
@@ -40718,6 +40871,8 @@ A package holds one session, so this is it, whichever port you asked for.
40718
40871
  assetUrl: server.assetUrl,
40719
40872
  port: Number(new URL(server.url).port),
40720
40873
  assetPort: Number(new URL(server.assetUrl).port),
40874
+ ...server.publicUrl ? { publicUrl: server.publicUrl } : {},
40875
+ ...server.publicAssetUrl ? { publicAssetUrl: server.publicAssetUrl } : {},
40721
40876
  isolated: options.isolated === true,
40722
40877
  stopped: true
40723
40878
  });
@@ -40768,32 +40923,105 @@ async function devStopCommand(options) {
40768
40923
  }
40769
40924
 
40770
40925
  // cli/commands/docs.ts
40771
- import { readFileSync as readFileSync24, readdirSync as readdirSync6, statSync as statSync3 } from "fs";
40926
+ import { readFileSync as readFileSync25, readdirSync as readdirSync7, statSync as statSync4 } from "fs";
40772
40927
  import { existsSync as existsSync34 } from "fs";
40773
- import { join as join52, resolve as resolve26 } from "path";
40928
+ import { join as join53, resolve as resolve26 } from "path";
40929
+
40930
+ // cli/docs-reference/anchors.ts
40931
+ var ATX_HEADING = /^ {0,3}#{1,6}\s+(.*?)\s*#*\s*$/;
40932
+ function slug2(text5) {
40933
+ return text5.replace(/<[^>]+>/g, "").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[*_`~]/g, (character) => character === "_" ? "_" : "").trim().toLowerCase().replace(/[^\p{L}\p{M}\p{N}\p{Pc}\- ]/gu, "").replace(/ /g, "-");
40934
+ }
40935
+ function atxHeadingText(line) {
40936
+ return ATX_HEADING.exec(line)?.[1];
40937
+ }
40938
+ function createAnchorSlugger() {
40939
+ const seen = /* @__PURE__ */ new Map();
40940
+ return (headingText2) => {
40941
+ const base = slug2(headingText2);
40942
+ const count = seen.get(base) ?? 0;
40943
+ seen.set(base, count + 1);
40944
+ return count === 0 ? base : `${base}-${count}`;
40945
+ };
40946
+ }
40947
+
40948
+ // cli/docs-reference/outline.ts
40949
+ var FENCE = /^\s*(`{3,}|~{3,})/;
40950
+ function headingText(raw) {
40951
+ return raw.replace(/<[^>]+>/g, "").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").trim();
40952
+ }
40953
+ function readOutline(markdown) {
40954
+ const slugFor = createAnchorSlugger();
40955
+ const headings = [];
40956
+ let fence2;
40957
+ let offset = 0;
40958
+ const lines = markdown.split("\n");
40959
+ lines.forEach((line, index3) => {
40960
+ const start = offset;
40961
+ offset += line.length + 1;
40962
+ const opener = FENCE.exec(line);
40963
+ if (fence2) {
40964
+ const closes = opener && opener[1][0] === fence2.marker && opener[1].length >= fence2.size && line.trim() === opener[1];
40965
+ if (closes) fence2 = void 0;
40966
+ return;
40967
+ }
40968
+ if (opener) {
40969
+ fence2 = { marker: opener[1][0], size: opener[1].length };
40970
+ return;
40971
+ }
40972
+ const raw = atxHeadingText(line);
40973
+ if (raw === void 0) return;
40974
+ headings.push({
40975
+ level: /^ {0,3}(#+)/.exec(line)?.[1].length ?? 1,
40976
+ text: headingText(raw),
40977
+ slug: slugFor(raw),
40978
+ line: index3 + 1,
40979
+ start
40980
+ });
40981
+ });
40982
+ return headings.map((heading2, index3) => {
40983
+ const next = headings.slice(index3 + 1).find((candidate) => candidate.level <= heading2.level);
40984
+ const end = next ? next.start : markdown.length;
40985
+ return { ...heading2, end, length: end - heading2.start };
40986
+ });
40987
+ }
40988
+ function normalise(text5) {
40989
+ return text5.replace(/[`*_]/g, "").replace(/\s+/g, " ").trim().toLowerCase();
40990
+ }
40991
+ function findSections(outline, query) {
40992
+ const wanted = query.trim().replace(/^#/, "");
40993
+ const bySlug = outline.filter((heading2) => heading2.slug === wanted.toLowerCase());
40994
+ if (bySlug.length > 0) return bySlug;
40995
+ return outline.filter((heading2) => normalise(heading2.text) === normalise(wanted));
40996
+ }
40997
+
40998
+ // cli/docs-reference/page-index.ts
40999
+ import { readdirSync as readdirSync6, readFileSync as readFileSync24, statSync as statSync3 } from "node:fs";
41000
+ import { join as join51, posix as posix3, relative as relative10, sep as sep16 } from "node:path";
41001
+ var PAGE_INDEX = "page-index.md";
40774
41002
 
40775
41003
  // cli/utils/docs-path.ts
40776
- import { dirname as dirname20, join as join51 } from "path";
41004
+ import { dirname as dirname20, join as join52 } from "path";
40777
41005
  import { fileURLToPath as fileURLToPath9 } from "url";
40778
41006
  function resolveDocsPath() {
40779
41007
  const currentFilePath = fileURLToPath9(import.meta.url);
40780
41008
  const currentDir = dirname20(currentFilePath);
40781
41009
  const fromSource = currentFilePath.includes("/cli/utils/") || currentFilePath.includes("\\cli\\utils\\");
40782
- return fromSource ? join51(currentDir, "../../docs") : join51(currentDir, "./docs");
41010
+ return fromSource ? join52(currentDir, "../../docs") : join52(currentDir, "./docs");
40783
41011
  }
40784
41012
 
40785
41013
  // cli/commands/docs.ts
40786
41014
  function buildFileTree(dir, basePath = "") {
40787
41015
  try {
40788
- const entries = readdirSync6(dir);
41016
+ const entries = readdirSync7(dir);
40789
41017
  const nodes = [];
40790
41018
  for (const entry of entries) {
40791
41019
  if (entry.startsWith(".") || entry === "node_modules") {
40792
41020
  continue;
40793
41021
  }
40794
- const fullPath = join52(dir, entry);
40795
- const relativePath = basePath ? join52(basePath, entry) : entry;
40796
- const stat3 = statSync3(fullPath);
41022
+ const fullPath = join53(dir, entry);
41023
+ const relativePath = basePath ? join53(basePath, entry) : entry;
41024
+ const stat3 = statSync4(fullPath);
40797
41025
  if (stat3.isDirectory()) {
40798
41026
  nodes.push({
40799
41027
  name: entry,
@@ -40840,7 +41068,7 @@ function filePaths(nodes) {
40840
41068
  }
40841
41069
  function printTree(docsPath) {
40842
41070
  const fileTree = buildFileTree(docsPath);
40843
- reportResult({ files: filePaths(fileTree) }, () => {
41071
+ reportResult({ files: filePaths(fileTree), index: PAGE_INDEX }, () => {
40844
41072
  if (fileTree.length === 0) {
40845
41073
  console.log("No documentation files found. Create .md files in the docs/ directory.");
40846
41074
  return;
@@ -40849,21 +41077,20 @@ function printTree(docsPath) {
40849
41077
  console.log("docs/");
40850
41078
  formatTree(fileTree).forEach((line) => console.log(line));
40851
41079
  console.log(
40852
- "\nUsage: pnpm run sdk docs view <file-path>\nExample: pnpm run sdk docs view concepts/terminology.md\n"
41080
+ "\nStart at page-index.md: every page with a one-sentence summary and its length.\n\nUsage: pnpm run sdk docs view <file-path> [--outline | --section <heading>]\nExample: pnpm run sdk docs view page-index.md\nExample: pnpm run sdk docs view guides/engine.md --outline\n"
40853
41081
  );
40854
41082
  });
40855
41083
  }
40856
- function printDocFile(docsPath, filePath) {
40857
- const resolved = resolve26(join52(docsPath, filePath));
41084
+ function readDocFile(docsPath, filePath) {
41085
+ const resolved = resolve26(join53(docsPath, filePath));
40858
41086
  if (!resolved.startsWith(resolve26(docsPath))) {
40859
41087
  throw new CliError("USAGE_BAD_ARGUMENT", "Invalid file path: it is outside the docs");
40860
41088
  }
40861
41089
  if (!resolved.endsWith(".md")) {
40862
41090
  throw new CliError("USAGE_BAD_ARGUMENT", "Only .md files are supported");
40863
41091
  }
40864
- let content3;
40865
41092
  try {
40866
- content3 = readFileSync24(resolved, "utf-8");
41093
+ return readFileSync25(resolved, "utf-8");
40867
41094
  } catch (error) {
40868
41095
  if (error.code === "ENOENT") {
40869
41096
  throw new CliError("FILE_NOT_FOUND", `File not found: ${filePath}`, {
@@ -40872,9 +41099,56 @@ function printDocFile(docsPath, filePath) {
40872
41099
  }
40873
41100
  throw new CliError("FILE_NOT_FOUND", `Error reading file: ${error.message}`);
40874
41101
  }
40875
- reportResult({ file: filePath, content: content3 }, () => console.log(content3));
40876
41102
  }
40877
- async function docsCommand(filePath) {
41103
+ function describeHeading({ level, text: text5, slug: slug4, length }) {
41104
+ return { level, text: text5, slug: slug4, length };
41105
+ }
41106
+ function printOutline(filePath, content3) {
41107
+ const headings = readOutline(content3).map(describeHeading);
41108
+ reportResult({ file: filePath, length: content3.length, headings }, () => {
41109
+ console.log(`${filePath} (${content3.length.toLocaleString("en-GB")} characters)
41110
+ `);
41111
+ for (const heading2 of headings) {
41112
+ const indent3 = " ".repeat(heading2.level - 1);
41113
+ console.log(
41114
+ `${indent3}${"#".repeat(heading2.level)} ${heading2.text} [${heading2.slug}, ${heading2.length.toLocaleString("en-GB")} characters]`
41115
+ );
41116
+ }
41117
+ console.log(
41118
+ `
41119
+ Read one section with: pnpm run sdk docs view ${filePath} --section <slug or heading>`
41120
+ );
41121
+ });
41122
+ }
41123
+ function printSection(filePath, content3, query) {
41124
+ const outline = readOutline(content3);
41125
+ const matches4 = findSections(outline, query);
41126
+ const available = outline.map((heading3) => heading3.slug);
41127
+ if (matches4.length === 0) {
41128
+ throw new CliError("DOCS_SECTION_NOT_FOUND", `${filePath} has no section '${query}'`, {
41129
+ hint: `Run "pnpm run sdk docs view ${filePath} --outline" to see its sections.`,
41130
+ details: { file: filePath, section: query, available }
41131
+ });
41132
+ }
41133
+ if (matches4.length > 1) {
41134
+ throw new CliError(
41135
+ "USAGE_BAD_FLAG",
41136
+ `More than one section of ${filePath} is headed '${query}': ` + matches4.map((heading3) => heading3.slug).join(", "),
41137
+ {
41138
+ hint: "Name the section by its slug instead.",
41139
+ details: { file: filePath, section: query, matches: matches4.map((h) => h.slug) }
41140
+ }
41141
+ );
41142
+ }
41143
+ const [heading2] = matches4;
41144
+ const section = `${content3.slice(heading2.start, heading2.end).trimEnd()}
41145
+ `;
41146
+ reportResult(
41147
+ { file: filePath, heading: describeHeading(heading2), content: section },
41148
+ () => console.log(section)
41149
+ );
41150
+ }
41151
+ async function docsCommand(filePath, options = {}) {
40878
41152
  const docsPath = resolveDocsPath();
40879
41153
  if (!existsSync34(docsPath)) {
40880
41154
  throw new CliError(
@@ -40882,11 +41156,26 @@ async function docsCommand(filePath) {
40882
41156
  "Documentation files not found. Make sure the SDK is properly installed."
40883
41157
  );
40884
41158
  }
41159
+ if (options.outline && options.section !== void 0) {
41160
+ throw new CliError("USAGE_BAD_FLAG", "--outline and --section cannot be combined", {
41161
+ hint: "Read the outline first, then ask for one of its sections."
41162
+ });
41163
+ }
40885
41164
  if (!filePath) {
41165
+ if (options.outline || options.section !== void 0) {
41166
+ throw new CliError(
41167
+ "USAGE_MISSING_ARGUMENT",
41168
+ `${options.outline ? "--outline" : "--section"} needs a page to read`,
41169
+ { hint: `Name one, such as ${PAGE_INDEX} or guides/engine.md.` }
41170
+ );
41171
+ }
40886
41172
  printTree(docsPath);
40887
- } else {
40888
- printDocFile(docsPath, filePath);
41173
+ return;
40889
41174
  }
41175
+ const content3 = readDocFile(docsPath, filePath);
41176
+ if (options.outline) printOutline(filePath, content3);
41177
+ else if (options.section !== void 0) printSection(filePath, content3, options.section);
41178
+ else reportResult({ file: filePath, content: content3 }, () => console.log(content3));
40890
41179
  }
40891
41180
 
40892
41181
  // cli/commands/docs-export.ts
@@ -40970,7 +41259,7 @@ async function endpointAuditCommand(options) {
40970
41259
  // cli/commands/endpoint-call.ts
40971
41260
  import { existsSync as existsSync36 } from "fs";
40972
41261
  import { mkdir as mkdir14, readFile as readFile13, writeFile as writeFile16 } from "fs/promises";
40973
- import { basename as basename7, join as join53, resolve as resolve28 } from "path";
41262
+ import { basename as basename7, join as join54, resolve as resolve28 } from "path";
40974
41263
  function describeStep(step) {
40975
41264
  switch (step.kind) {
40976
41265
  case "capabilities":
@@ -41052,8 +41341,8 @@ async function saveBlobs(response, dir, workingDir) {
41052
41341
  let name = basename7(blob.name) || "blob";
41053
41342
  for (let n = 2; taken.has(name); n += 1) name = `${n}-${basename7(blob.name)}`;
41054
41343
  taken.add(name);
41055
- await writeFile16(join53(target, name), blob.data);
41056
- console.error(`Saved ${reference} to ${join53(target, name)}`);
41344
+ await writeFile16(join54(target, name), blob.data);
41345
+ console.error(`Saved ${reference} to ${join54(target, name)}`);
41057
41346
  }
41058
41347
  }
41059
41348
  async function endpointCallCommand(identifier, options) {
@@ -41238,16 +41527,16 @@ Supported types: ${supportedTypes("new")}`
41238
41527
  }
41239
41528
 
41240
41529
  // cli/commands/package-bundle.ts
41241
- import { existsSync as existsSync37, readdirSync as readdirSync7, readFileSync as readFileSync25, statSync as statSync4 } from "fs";
41530
+ import { existsSync as existsSync37, readdirSync as readdirSync8, readFileSync as readFileSync26, statSync as statSync5 } from "fs";
41242
41531
  import { mkdir as mkdir15, rm as rm8 } from "fs/promises";
41243
- import { dirname as dirname21, join as join54, relative as relative10, resolve as resolve30, sep as sep16 } from "path";
41532
+ import { dirname as dirname21, join as join55, relative as relative11, resolve as resolve30, sep as sep17 } from "path";
41244
41533
  import AdmZip from "adm-zip";
41245
41534
  function emptyDirectoryEntries(root2, excluded) {
41246
41535
  const empty2 = /* @__PURE__ */ new Set();
41247
41536
  const walk3 = (absolute, prefix) => {
41248
41537
  let holdsFile = false;
41249
- for (const child of readdirSync7(absolute, { withFileTypes: true })) {
41250
- const childPath = join54(absolute, child.name);
41538
+ for (const child of readdirSync8(absolute, { withFileTypes: true })) {
41539
+ const childPath = join55(absolute, child.name);
41251
41540
  if (child.isDirectory()) {
41252
41541
  if (walk3(childPath, `${prefix}${child.name}/`)) holdsFile = true;
41253
41542
  } else if (childPath !== excluded) {
@@ -41260,14 +41549,14 @@ function emptyDirectoryEntries(root2, excluded) {
41260
41549
  walk3(root2, "");
41261
41550
  return empty2;
41262
41551
  }
41263
- function includeBundleEntry(entryPath, emptyDirectories, outputRelToBuildDir, separator = sep16) {
41552
+ function includeBundleEntry(entryPath, emptyDirectories, outputRelToBuildDir, separator = sep17) {
41264
41553
  const entryName = separator === "/" ? entryPath : entryPath.split(separator).join("/");
41265
41554
  if (emptyDirectories.has(entryName)) return false;
41266
41555
  if (outputRelToBuildDir === null) return true;
41267
41556
  return entryPath !== outputRelToBuildDir;
41268
41557
  }
41269
41558
  function readManifest(buildDirAbs) {
41270
- const manifestPath = join54(buildDirAbs, "seriousgaming.json");
41559
+ const manifestPath = join55(buildDirAbs, "seriousgaming.json");
41271
41560
  if (!existsSync37(manifestPath)) {
41272
41561
  throw new CliError(
41273
41562
  "BUILD_NOT_FOUND",
@@ -41276,7 +41565,7 @@ function readManifest(buildDirAbs) {
41276
41565
  }
41277
41566
  let raw;
41278
41567
  try {
41279
- raw = readFileSync25(manifestPath, "utf-8");
41568
+ raw = readFileSync26(manifestPath, "utf-8");
41280
41569
  } catch (error) {
41281
41570
  const message = error instanceof Error ? error.message : String(error);
41282
41571
  throw new CliError("BUILD_NOT_FOUND", `Failed to read ${manifestPath}: ${message}`);
@@ -41309,15 +41598,15 @@ async function bundlePackage(options) {
41309
41598
  );
41310
41599
  }
41311
41600
  const manifest = readManifest(buildDirAbs);
41312
- const defaultOutputFile = join54(
41601
+ const defaultOutputFile = join55(
41313
41602
  options.buildDir,
41314
41603
  `${manifest.identifier}-${manifest.version}.zip`
41315
41604
  );
41316
41605
  const outputFileAbs = resolve30(options.workingDir, options.outputFile ?? defaultOutputFile);
41317
41606
  await mkdir15(dirname21(outputFileAbs), { recursive: true });
41318
41607
  await rm8(outputFileAbs, { force: true });
41319
- const outputRelToBuildDir = relative10(buildDirAbs, outputFileAbs);
41320
- const outputIsInsideBuildDir = !outputRelToBuildDir.startsWith("..") && !outputRelToBuildDir.startsWith(sep16);
41608
+ const outputRelToBuildDir = relative11(buildDirAbs, outputFileAbs);
41609
+ const outputIsInsideBuildDir = !outputRelToBuildDir.startsWith("..") && !outputRelToBuildDir.startsWith(sep17);
41321
41610
  const emptyDirectories = emptyDirectoryEntries(
41322
41611
  buildDirAbs,
41323
41612
  outputIsInsideBuildDir ? outputFileAbs : ""
@@ -41340,7 +41629,7 @@ async function bundlePackage(options) {
41340
41629
  );
41341
41630
  }
41342
41631
  zip.writeZip(outputFileAbs);
41343
- const size = statSync4(outputFileAbs).size;
41632
+ const size = statSync5(outputFileAbs).size;
41344
41633
  const result = {
41345
41634
  outputFile: outputFileAbs,
41346
41635
  size,
@@ -41362,9 +41651,9 @@ async function packageBundleCommand(options) {
41362
41651
  }
41363
41652
 
41364
41653
  // cli/commands/package-publish.ts
41365
- import { existsSync as existsSync38, readFileSync as readFileSync26, statSync as statSync5 } from "fs";
41654
+ import { existsSync as existsSync38, readFileSync as readFileSync27, statSync as statSync6 } from "fs";
41366
41655
  import { readFile as readFile14 } from "fs/promises";
41367
- import { join as join55, resolve as resolve31 } from "path";
41656
+ import { join as join56, resolve as resolve31 } from "path";
41368
41657
  function buildApiPath(publisherSlug) {
41369
41658
  return `/api/v0/admin/publishers/${encodeURIComponent(publisherSlug)}/packages`;
41370
41659
  }
@@ -41378,7 +41667,7 @@ function readSdkConfig(workingDir) {
41378
41667
  }
41379
41668
  let raw;
41380
41669
  try {
41381
- raw = readFileSync26(sdkPath, "utf-8");
41670
+ raw = readFileSync27(sdkPath, "utf-8");
41382
41671
  } catch (error) {
41383
41672
  const message = error instanceof Error ? error.message : String(error);
41384
41673
  throw new CliError("MANIFEST_INVALID", `Failed to read ${sdkPath}: ${message}`);
@@ -41406,7 +41695,7 @@ function readSdkConfig(workingDir) {
41406
41695
  }
41407
41696
  let version;
41408
41697
  try {
41409
- version = JSON.parse(readFileSync26(packageJsonPath, "utf-8")).version;
41698
+ version = JSON.parse(readFileSync27(packageJsonPath, "utf-8")).version;
41410
41699
  } catch (error) {
41411
41700
  const message = error instanceof Error ? error.message : String(error);
41412
41701
  throw new CliError("MANIFEST_INVALID", `Failed to parse ${packageJsonPath}: ${message}`);
@@ -41456,7 +41745,7 @@ async function packagePublishCommand(zip, options) {
41456
41745
  };
41457
41746
  const sdkConfig = readSdkConfig(options.workingDir);
41458
41747
  const buildDirAbs = resolve31(options.workingDir, options.buildDir);
41459
- const defaultZipPath = join55(buildDirAbs, `${sdkConfig.identifier}-${sdkConfig.version}.zip`);
41748
+ const defaultZipPath = join56(buildDirAbs, `${sdkConfig.identifier}-${sdkConfig.version}.zip`);
41460
41749
  let zipPath;
41461
41750
  if (zip) {
41462
41751
  zipPath = resolve31(options.workingDir, zip);
@@ -41528,7 +41817,7 @@ async function packagePublishCommand(zip, options) {
41528
41817
  );
41529
41818
  return;
41530
41819
  }
41531
- const zipSize = statSync5(zipPath).size;
41820
+ const zipSize = statSync6(zipPath).size;
41532
41821
  const form = new FormData();
41533
41822
  const blob = new Blob([new Uint8Array(zipBuffer)], { type: "application/zip" });
41534
41823
  form.append("body", blob, `${sdkConfig.identifier}-${sdkConfig.version}.zip`);
@@ -41587,8 +41876,8 @@ async function packagePublishCommand(zip, options) {
41587
41876
  }
41588
41877
 
41589
41878
  // cli/commands/package-version.ts
41590
- import { existsSync as existsSync39, readFileSync as readFileSync27, writeFileSync as writeFileSync6 } from "fs";
41591
- import { join as join56, resolve as resolve32 } from "path";
41879
+ import { existsSync as existsSync39, readFileSync as readFileSync28, writeFileSync as writeFileSync6 } from "fs";
41880
+ import { join as join57, resolve as resolve32 } from "path";
41592
41881
  var BUMP_KEYWORDS = ["patch", "minor", "major", "prerelease"];
41593
41882
  function isBumpKeyword(value) {
41594
41883
  return BUMP_KEYWORDS.includes(value);
@@ -41661,7 +41950,7 @@ function bumpVersion(current, keyword) {
41661
41950
  function readJsonFile(path3, label4) {
41662
41951
  let raw;
41663
41952
  try {
41664
- raw = readFileSync27(path3, "utf-8");
41953
+ raw = readFileSync28(path3, "utf-8");
41665
41954
  } catch (error) {
41666
41955
  const message = error instanceof Error ? error.message : String(error);
41667
41956
  throw new CliError("MANIFEST_INVALID", `Failed to read ${label4} at ${path3}: ${message}`);
@@ -41704,7 +41993,7 @@ async function packageVersionCommand(value, options) {
41704
41993
  );
41705
41994
  return;
41706
41995
  }
41707
- const packageJsonPath = join56(options.workingDir, "package.json");
41996
+ const packageJsonPath = join57(options.workingDir, "package.json");
41708
41997
  if (!existsSync39(packageJsonPath)) {
41709
41998
  fail(
41710
41999
  "MANIFEST_NOT_FOUND",
@@ -41995,8 +42284,427 @@ function newFileHelp(spec) {
41995
42284
  return spec.fileHelp ?? `path to a JSON file containing the ${spec.typeLabel} definition`;
41996
42285
  }
41997
42286
 
42287
+ // cli/commands/screenshot.ts
42288
+ import { existsSync as existsSync40 } from "fs";
42289
+ import { mkdir as mkdir16 } from "fs/promises";
42290
+ import { createRequire } from "module";
42291
+ import { dirname as dirname22, join as join58, resolve as resolve34 } from "path";
42292
+ import { pathToFileURL } from "url";
42293
+
42294
+ // cli/client/dev-server.ts
42295
+ async function startDevServer(options) {
42296
+ const environment = loadEnvironmentConfig(options.packagePath);
42297
+ const shell = new DevShell({
42298
+ packagePath: options.packagePath,
42299
+ port: options.port ?? 0,
42300
+ isolated: true,
42301
+ ...options.teams === void 0 ? {} : { teams: options.teams },
42302
+ ...options.participants === void 0 ? {} : { participants: options.participants },
42303
+ ...options.scenarioId === void 0 ? {} : { scenarioId: options.scenarioId },
42304
+ ...options.locale === void 0 ? {} : { locale: options.locale },
42305
+ ...options.clock === void 0 ? {} : { clock: options.clock },
42306
+ ...options.callbacks === void 0 ? {} : { callbacks: options.callbacks },
42307
+ ...options.reinitOnChange ? { reinitOnChange: true } : {},
42308
+ ...environment.seriousGamingApiKey === void 0 ? {} : { seriousGamingApiKey: environment.seriousGamingApiKey },
42309
+ ...environment.seriousGamingApiHost === void 0 ? {} : { seriousGamingApiHost: environment.seriousGamingApiHost },
42310
+ ...environment.elevenLabsApiKey === void 0 ? {} : { elevenLabsApiKey: environment.elevenLabsApiKey }
42311
+ });
42312
+ try {
42313
+ await shell.start();
42314
+ } catch (error) {
42315
+ await shell.stop().catch(() => {
42316
+ });
42317
+ throw error;
42318
+ }
42319
+ let stopping = null;
42320
+ return {
42321
+ url: shell.url,
42322
+ assetUrl: shell.assetUrl,
42323
+ stop() {
42324
+ stopping ??= shell.stop();
42325
+ return stopping;
42326
+ }
42327
+ };
42328
+ }
42329
+
42330
+ // cli/commands/screenshot.ts
42331
+ var DEFAULT_WIDTH = 1280;
42332
+ var DEFAULT_HEIGHT = 800;
42333
+ var DEFAULT_TIMEOUT_SECONDS = 30;
42334
+ var MAX_DIMENSION = 16384;
42335
+ var MISSING_HINT = "Add it to the package with `pnpm add -D @playwright/test`, then run `pnpm exec playwright install chromium`.";
42336
+ async function screenshotCommand(path3, options, dependencies = {}) {
42337
+ const packagePath = resolve34(options.workingDir);
42338
+ const plan = planScreenshot(path3, options, packagePath);
42339
+ const chromium = await (dependencies.loadPlaywright ?? loadPlaywright)(packagePath);
42340
+ if (!chromium) {
42341
+ throw new CliError(
42342
+ "BROWSER_MISSING",
42343
+ "sdk screenshot drives Playwright, and this package does not depend on it.",
42344
+ { hint: MISSING_HINT }
42345
+ );
42346
+ }
42347
+ const result = await withServer(packagePath, plan, async (url, server) => {
42348
+ const problems = await capture(chromium, `${url}${plan.target}`, plan);
42349
+ return {
42350
+ path: plan.out,
42351
+ url: `${url}${plan.target}`,
42352
+ width: plan.width,
42353
+ height: plan.height,
42354
+ fullPage: plan.fullPage,
42355
+ server,
42356
+ ...problems
42357
+ };
42358
+ });
42359
+ reportResult(result, () => {
42360
+ console.log(`Saved ${result.path} (${result.width}x${result.height}) from ${result.url}`);
42361
+ printProblems(result);
42362
+ });
42363
+ }
42364
+ function planScreenshot(path3, options, packagePath) {
42365
+ if (!path3.startsWith("/")) {
42366
+ throw new CliError(
42367
+ "USAGE_BAD_ARGUMENT",
42368
+ `"${path3}" is not a console path: it starts with /, such as /team/1/player/1`
42369
+ );
42370
+ }
42371
+ const url = new URL(path3, "http://localhost");
42372
+ const route = parseRoute(url.pathname, url.search);
42373
+ if (route.kind === "console" && url.pathname !== "/") {
42374
+ throw new CliError(
42375
+ "USAGE_BAD_ARGUMENT",
42376
+ `"${url.pathname}" names no surface. Use / for the session surface, /team/<n>/player/<n>, /team/<n>/observe, /team/<n>/waiting-room, /walkthrough, /setup, /scenario-editor?scenario=<id>, /presentation, /guide or /print`
42377
+ );
42378
+ }
42379
+ const scheme = options.scheme;
42380
+ if (scheme !== void 0 && scheme !== "light" && scheme !== "dark" && scheme !== "system") {
42381
+ throw new CliError(
42382
+ "USAGE_BAD_FLAG",
42383
+ `--scheme takes light, dark or system, and got "${scheme}"`
42384
+ );
42385
+ }
42386
+ url.searchParams.set("bare", "");
42387
+ if (scheme !== void 0) url.searchParams.set("scheme", scheme);
42388
+ if (options.brand !== void 0) url.searchParams.set("brand", options.brand);
42389
+ const width = dimension(options.width, "--width", DEFAULT_WIDTH);
42390
+ const height = dimension(options.height, "--height", DEFAULT_HEIGHT);
42391
+ const timeout = positive(options.timeout, "--timeout", DEFAULT_TIMEOUT_SECONDS);
42392
+ const out = options.out === void 0 ? join58(
42393
+ packagePath,
42394
+ ".seriousgaming-sdk",
42395
+ "screenshots",
42396
+ `${slug3(url.pathname)}-${width}x${height}.png`
42397
+ ) : resolve34(packagePath, options.out);
42398
+ if (!out.toLowerCase().endsWith(".png")) {
42399
+ throw new CliError("USAGE_BAD_FLAG", `--out names a PNG file, and got "${options.out}"`);
42400
+ }
42401
+ return {
42402
+ // `bare` is a flag, not a value: `?bare=` reads as one, as the console's own links avoid.
42403
+ target: `${url.pathname}${url.search.replace(/([?&]bare)=(?=&|$)/, "$1")}`,
42404
+ route,
42405
+ width,
42406
+ height,
42407
+ ...scheme === void 0 ? {} : { scheme },
42408
+ ...options.brand === void 0 ? {} : { brand: options.brand },
42409
+ ...options.locale === void 0 ? {} : { locale: options.locale },
42410
+ fullPage: options.fullPage === true,
42411
+ out,
42412
+ timeoutMs: timeout * 1e3
42413
+ };
42414
+ }
42415
+ function dimension(value, flag, fallback) {
42416
+ const parsed = positive(value, flag, fallback);
42417
+ if (!Number.isInteger(parsed) || parsed > MAX_DIMENSION) {
42418
+ throw new CliError(
42419
+ "USAGE_BAD_FLAG",
42420
+ `${flag} takes a whole number of pixels up to ${MAX_DIMENSION}, and got "${value}"`
42421
+ );
42422
+ }
42423
+ return parsed;
42424
+ }
42425
+ function positive(value, flag, fallback) {
42426
+ if (value === void 0) return fallback;
42427
+ const parsed = Number(value);
42428
+ if (!/^\d+(\.\d+)?$/.test(value) || parsed <= 0) {
42429
+ throw new CliError("USAGE_BAD_FLAG", `${flag} takes a positive number, and got "${value}"`);
42430
+ }
42431
+ return parsed;
42432
+ }
42433
+ function slug3(pathname) {
42434
+ const parts = pathname.split("/").filter(Boolean);
42435
+ return parts.length === 0 ? "session" : parts.join("-");
42436
+ }
42437
+ async function loadPlaywright(packagePath, resolution = {}) {
42438
+ const exists = resolution.exists ?? existsSync40;
42439
+ const requireFrom = resolution.requireFrom ?? createRequire;
42440
+ for (const name of ["@playwright/test", "playwright"]) {
42441
+ const modules = nodeModulesHolding(packagePath, name, exists);
42442
+ if (modules === null) continue;
42443
+ let entry;
42444
+ try {
42445
+ entry = requireFrom(join58(modules, "package.json")).resolve(name);
42446
+ } catch {
42447
+ continue;
42448
+ }
42449
+ const module = await import(pathToFileURL(entry).href);
42450
+ const chromium = module.chromium ?? module.default?.chromium;
42451
+ if (chromium) return chromium;
42452
+ }
42453
+ return null;
42454
+ }
42455
+ function nodeModulesHolding(from, name, exists) {
42456
+ let directory = resolve34(from);
42457
+ for (; ; ) {
42458
+ const modules = join58(directory, "node_modules");
42459
+ if (exists(join58(modules, name, "package.json"))) return modules;
42460
+ const parent = dirname22(directory);
42461
+ if (parent === directory) return null;
42462
+ directory = parent;
42463
+ }
42464
+ }
42465
+ async function launchBrowser(chromium) {
42466
+ try {
42467
+ return await chromium.launch({ headless: true });
42468
+ } catch (error) {
42469
+ const message = error instanceof Error ? error.message : String(error);
42470
+ if (/Executable doesn't exist|playwright install/i.test(message)) {
42471
+ throw new CliError(
42472
+ "BROWSER_MISSING",
42473
+ "Playwright is installed, but the Chromium it drives is not.",
42474
+ {
42475
+ hint: "Run `pnpm exec playwright install chromium` in the package.",
42476
+ cause: error
42477
+ }
42478
+ );
42479
+ }
42480
+ throw new CliError("BROWSER_MISSING", `Chromium did not start: ${message.split("\n")[0]}`, {
42481
+ hint: "Run `pnpm exec playwright install chromium` in the package.",
42482
+ cause: error
42483
+ });
42484
+ }
42485
+ }
42486
+ async function withServer(packagePath, plan, work) {
42487
+ let found = null;
42488
+ try {
42489
+ found = await resolveSession({ packagePath, autoStart: false, runKind: plan.route.run });
42490
+ } catch (error) {
42491
+ if (!(error instanceof CliError && error.code === "NO_SESSION")) throw error;
42492
+ }
42493
+ if (found?.url) {
42494
+ const url = found.url;
42495
+ return prepared(url, found, plan, false, () => work(url, "running"));
42496
+ }
42497
+ console.error("No dev server is running, so one is starting for this capture.");
42498
+ const server = await startDevServer({ packagePath });
42499
+ try {
42500
+ const session = connectSession(server.url, plan.route.run);
42501
+ if (plan.route.kind !== "setup" && (await session.state()).session.inSetup) {
42502
+ await session.send({ type: "play" });
42503
+ }
42504
+ return await prepared(server.url, session, plan, true, () => work(server.url, "started"));
42505
+ } finally {
42506
+ await server.stop();
42507
+ }
42508
+ }
42509
+ async function prepared(url, session, plan, own5, work) {
42510
+ if (plan.brand !== void 0) {
42511
+ const { brands } = await fetchJson(`${url}/api/brands`);
42512
+ const ids = brands.map((brand) => brand.id);
42513
+ if (!ids.includes(plan.brand)) {
42514
+ throw new CliError(
42515
+ "USAGE_BAD_FLAG",
42516
+ `--brand "${plan.brand}" is not one the dev server offers (${ids.join(", ") || "none"})`
42517
+ );
42518
+ }
42519
+ }
42520
+ if (plan.locale === void 0) return work();
42521
+ const locales = await fetchJson(`${url}/api/locales`);
42522
+ if (!locales.supported.includes(plan.locale)) {
42523
+ throw new CliError(
42524
+ "USAGE_BAD_FLAG",
42525
+ `--locale "${plan.locale}" is not one of this game's locales (${locales.supported.join(", ")})`
42526
+ );
42527
+ }
42528
+ if (locales.active === plan.locale) return work();
42529
+ await setLocale(session, plan.locale);
42530
+ try {
42531
+ return await work();
42532
+ } finally {
42533
+ if (!own5) await setLocale(session, locales.active).catch(() => {
42534
+ });
42535
+ }
42536
+ }
42537
+ async function setLocale(session, locale) {
42538
+ const result = await session.send({ type: "setLocale", locale });
42539
+ if ("ok" in result && !result.ok) {
42540
+ throw new CliError(
42541
+ "REFUSED_DENIED",
42542
+ result.outcome.message ?? `The session refused the locale "${locale}"`
42543
+ );
42544
+ }
42545
+ }
42546
+ async function fetchJson(url) {
42547
+ let response;
42548
+ try {
42549
+ response = await fetch(url);
42550
+ } catch (error) {
42551
+ throw new CliError(
42552
+ "DEV_SERVER_UNREACHABLE",
42553
+ `The dev server at ${new URL(url).origin} did not answer: ${error instanceof Error ? error.message : String(error)}`
42554
+ );
42555
+ }
42556
+ if (!response.ok) {
42557
+ throw new CliError(
42558
+ "DEV_SERVER_OUTDATED",
42559
+ `The dev server did not answer ${new URL(url).pathname} (HTTP ${response.status})`,
42560
+ { hint: "Restart the dev server: `sdk dev stop`, then run the command again." }
42561
+ );
42562
+ }
42563
+ return await response.json();
42564
+ }
42565
+ function readinessScript(route) {
42566
+ const content3 = route.kind === "guide" ? '[data-testid="guide-content"]' : route.kind === "print" ? '[data-testid="print-sheets"]' : null;
42567
+ return `(() => {
42568
+ const frames = [...document.querySelectorAll('[data-surface-state]')];
42569
+ if (frames.some((frame) => frame.dataset.surfaceState === 'lost')) return 'lost';
42570
+ if (frames.length > 0) {
42571
+ return frames.every((frame) => frame.dataset.surfaceState === 'rendered') ? 'rendered' : false;
42572
+ }
42573
+ const root = document.getElementById('root');
42574
+ if (!root || root.childElementCount === 0) return false;
42575
+ if (document.querySelector('[data-testid="console-loading"]')) return false;
42576
+ return ${content3 === null ? "'rendered'" : `document.querySelector(${JSON.stringify(content3)}) ? 'rendered' : false`};
42577
+ })()`;
42578
+ }
42579
+ var SURFACE_STATE_SCRIPT = `[...document.querySelectorAll('[data-surface-state]')].map((frame) => frame.dataset.surfaceState)`;
42580
+ async function capture(chromium, url, plan) {
42581
+ const browser = await launchBrowser(chromium);
42582
+ const problems = {
42583
+ consoleErrors: [],
42584
+ failedRequests: [],
42585
+ uncaughtExceptions: []
42586
+ };
42587
+ try {
42588
+ const context = await browser.newContext({
42589
+ viewport: { width: plan.width, height: plan.height },
42590
+ ...plan.scheme === "light" || plan.scheme === "dark" ? { colorScheme: plan.scheme } : {}
42591
+ });
42592
+ const page = await context.newPage();
42593
+ watch2(page, problems);
42594
+ const deadline = Date.now() + plan.timeoutMs;
42595
+ try {
42596
+ await page.goto(url, { waitUntil: "load", timeout: plan.timeoutMs });
42597
+ const state2 = await page.waitForFunction(readinessScript(plan.route), void 0, {
42598
+ timeout: Math.max(1, deadline - Date.now()),
42599
+ polling: 100
42600
+ });
42601
+ if (await settled(state2) === "lost") {
42602
+ throw notRendered(
42603
+ `The surface at ${plan.target} did not connect to the console. Check its console for an error.`,
42604
+ problems
42605
+ );
42606
+ }
42607
+ } catch (error) {
42608
+ if (error instanceof CliError) throw error;
42609
+ const states = await page.evaluate(SURFACE_STATE_SCRIPT).catch(() => []);
42610
+ throw notRendered(timeoutMessage(plan, states, error), problems);
42611
+ }
42612
+ if (plan.fullPage) await growToContent(page, plan);
42613
+ await mkdir16(dirname22(plan.out), { recursive: true });
42614
+ await page.screenshot({ path: plan.out, fullPage: plan.fullPage, animations: "disabled" });
42615
+ return problems;
42616
+ } finally {
42617
+ await browser.close().catch(() => {
42618
+ });
42619
+ }
42620
+ }
42621
+ async function settled(handle2) {
42622
+ const value = handle2;
42623
+ return typeof value?.jsonValue === "function" ? value.jsonValue() : handle2;
42624
+ }
42625
+ function timeoutMessage(plan, states, error) {
42626
+ const seconds = plan.timeoutMs / 1e3;
42627
+ if (states.includes("unconfirmed")) {
42628
+ return `The surface at ${plan.target} connected but did not report its first paint within ${seconds}s. It most likely threw while rendering: see uncaughtExceptions and consoleErrors.`;
42629
+ }
42630
+ if (states.length > 0) {
42631
+ return `The surface at ${plan.target} did not connect within ${seconds}s.`;
42632
+ }
42633
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
42634
+ return `The page at ${plan.target} did not finish loading within ${seconds}s: ${reason}`;
42635
+ }
42636
+ function notRendered(message, problems) {
42637
+ return new CliError("SURFACE_NOT_RENDERED", message, {
42638
+ hint: "Open the same path in a browser to see it, or pass --timeout for a slower surface.",
42639
+ details: { ...problems }
42640
+ });
42641
+ }
42642
+ function watch2(page, problems) {
42643
+ page.on("console", (message) => {
42644
+ if (message.type() !== "error") return;
42645
+ const url = message.location().url;
42646
+ problems.consoleErrors.push({ text: message.text(), ...url ? { url } : {} });
42647
+ });
42648
+ page.on("pageerror", (error) => {
42649
+ problems.uncaughtExceptions.push({
42650
+ message: error.message,
42651
+ ...error.stack ? { stack: error.stack } : {}
42652
+ });
42653
+ });
42654
+ page.on("requestfailed", (request) => {
42655
+ problems.failedRequests.push({
42656
+ url: request.url(),
42657
+ method: request.method(),
42658
+ failure: request.failure()?.errorText ?? "failed"
42659
+ });
42660
+ });
42661
+ page.on("response", (response) => {
42662
+ if (response.status() < 400) return;
42663
+ problems.failedRequests.push({
42664
+ url: response.url(),
42665
+ method: response.request().method(),
42666
+ status: response.status()
42667
+ });
42668
+ });
42669
+ }
42670
+ var OVERFLOW_SCRIPT = `(() => {
42671
+ let overflow = Math.max(document.documentElement.scrollHeight, document.body ? document.body.scrollHeight : 0) - window.innerHeight;
42672
+ for (const element of document.querySelectorAll('*')) {
42673
+ const scrolls = /^(auto|scroll)$/.test(getComputedStyle(element).overflowY);
42674
+ if (scrolls) overflow = Math.max(overflow, element.scrollHeight - element.clientHeight);
42675
+ }
42676
+ return overflow;
42677
+ })()`;
42678
+ async function growToContent(page, plan) {
42679
+ const frame = page.mainFrame().childFrames()[0];
42680
+ if (!frame) return;
42681
+ const overflow = await frame.evaluate(OVERFLOW_SCRIPT).catch(() => 0);
42682
+ if (overflow <= 0) return;
42683
+ await page.setViewportSize({
42684
+ width: plan.width,
42685
+ height: Math.min(plan.height + overflow, MAX_DIMENSION)
42686
+ });
42687
+ await frame.evaluate(
42688
+ "new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(() => done(true))))"
42689
+ ).catch(() => {
42690
+ });
42691
+ }
42692
+ function printProblems(problems) {
42693
+ const lines = [
42694
+ ...problems.uncaughtExceptions.map((error) => ` Uncaught: ${error.message}`),
42695
+ ...problems.consoleErrors.map((error) => ` Console error: ${error.text}`),
42696
+ ...problems.failedRequests.map(
42697
+ (request) => ` Failed request: ${request.method} ${request.url} (${request.status ?? request.failure})`
42698
+ )
42699
+ ];
42700
+ if (lines.length === 0) return;
42701
+ console.log(`
42702
+ The page reported ${lines.length} problem${lines.length === 1 ? "" : "s"}:`);
42703
+ for (const line of lines) console.log(line);
42704
+ }
42705
+
41998
42706
  // cli/commands/session.ts
41999
- import { resolve as resolve34 } from "path";
42707
+ import { resolve as resolve35 } from "path";
42000
42708
  async function withSession(options, use) {
42001
42709
  const session = await resolveSession({
42002
42710
  packagePath: options.workingDir,
@@ -42193,7 +42901,7 @@ async function timerCommand(action, seconds, options) {
42193
42901
  throw new CliError("USAGE_BAD_ARGUMENT", `sdk timer ${chosen} takes no value`);
42194
42902
  }
42195
42903
  const byMs = chosen === "extend" ? parseSeconds(seconds, "sdk timer extend <seconds>") * 1e3 : 0;
42196
- const config = await loadConfig(loadPackageContext(resolve34(options.workingDir)).configPath);
42904
+ const config = await loadConfig(loadPackageContext(resolve35(options.workingDir)).configPath);
42197
42905
  if (!config.tick_controller) {
42198
42906
  throw new CliError(
42199
42907
  "USAGE_NOT_APPLICABLE",
@@ -42563,6 +43271,15 @@ Examples:
42563
43271
  "--brand <FILE>",
42564
43272
  "a brand file to preview the game in, added to the brand picker and selected; repeat for more than one",
42565
43273
  (value, previous4 = []) => [...previous4, value]
43274
+ ).option(
43275
+ "--public-url <ORIGIN>",
43276
+ `the origin people reach the console at, when a proxy or gateway stands in front of the server; used for every link the server prints or hands out (can also be set via ${PUBLIC_URL_ENV_VAR})`
43277
+ ).option(
43278
+ "--public-asset-url <ORIGIN>",
43279
+ `the origin browsers load game surfaces from behind that proxy, which must differ from the console's (defaults to the --public-url host on the asset port; can also be set via ${PUBLIC_ASSET_URL_ENV_VAR})`
43280
+ ).option(
43281
+ "--public-hmr-url <ORIGIN>",
43282
+ `the origin a surface's hot-reload client connects to behind that proxy, as wss:// or ws:// (defaults to the public asset host on the Vite port; can also be set via ${PUBLIC_HMR_URL_ENV_VAR})`
42566
43283
  ).addOption(new Option("--background").hideHelp()).action(devCommand);
42567
43284
  devCmd.command("status").description("Report whether a dev server is running for this package, and where").option("-w, --working-dir [PATH]", "the working directory to execute in", cwd()).action(
42568
43285
  (options, command) => devStatusCommand(devControlOptions(options, command))
@@ -42580,7 +43297,10 @@ Examples:
42580
43297
  configCmd.command("path").description("Print the resolved path to the global settings file").action(configPathCommand);
42581
43298
  const docsCmd = program.command("docs").description("Manage and view documentation");
42582
43299
  docsCmd.command("view [file]").description(
42583
- "View Serious Gaming SDK documentation\n\nShows a tree of available documentation files, or displays a specific file.\nThe docs ship inside the package, match its version and need no network.\n\nExamples:\n # Show documentation tree\n $ seriousgaming-sdk docs view\n\n # View a specific documentation file\n $ seriousgaming-sdk docs view getting-started.md\n $ seriousgaming-sdk docs view concepts/terminology.md\n $ seriousgaming-sdk docs view guides/engine.md"
43300
+ "View Serious Gaming SDK documentation\n\nShows a tree of available documentation files, or displays a specific file.\nThe docs ship inside the package, match its version and need no network.\npage-index.md lists every page with a summary and its length.\n\nExamples:\n # Show documentation tree\n $ seriousgaming-sdk docs view\n\n # Find the page for a subject\n $ seriousgaming-sdk docs view page-index.md\n\n # View a specific documentation file\n $ seriousgaming-sdk docs view getting-started.md\n $ seriousgaming-sdk docs view guides/engine.md\n\n # Read a long page a section at a time\n $ seriousgaming-sdk docs view guides/session.md --outline\n $ seriousgaming-sdk docs view guides/session.md --section 'Building the session UI'"
43301
+ ).option("--outline", "list the page's headings, with each section's length in characters").option(
43302
+ "--section <heading>",
43303
+ "print only the section under this heading, named by its slug or its text"
42584
43304
  ).action(docsCommand);
42585
43305
  docsCmd.command("export [dir]").description(
42586
43306
  "Export SDK documentation to your project\n\nCopies all documentation files to a local directory for use with Claude Code and other tools.\n\nExamples:\n # Export to default location (.seriousgaming-sdk/docs)\n $ seriousgaming-sdk docs export\n\n # Export to custom location\n $ seriousgaming-sdk docs export ./my-docs\n\nThe exported docs can be searched by Claude Code using its native file search.\nA scaffolded package already ignores .seriousgaming-sdk/ in its .gitignore."
@@ -42678,8 +43398,19 @@ Examples:
42678
43398
  participantCmd.command("rename <participantId> <name>").description("Rename a participant").option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(participantRenameCommand);
42679
43399
  participantCmd.command("move <participantId> <team>").description("Move a participant to another team (1-based)").option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(participantMoveCommand);
42680
43400
  program.command("waiting-room <action>").description("Open or close the session waiting room").option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(waitingRoomCommand);
42681
- program.command("scenario [identifier]").description("Activate a scenario, or `none` to run on the settings defaults").option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(scenarioCommand);
43401
+ program.command("scenario [identifier]").description(
43402
+ "Activate a scenario, or `none` to run on the settings defaults when no scenario is the default"
43403
+ ).option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(scenarioCommand);
42682
43404
  program.command("locale <code>").description("Change the session locale").option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--no-server", "run in this process instead of starting a dev server").action(localeCommand);
43405
+ program.command("screenshot <path>").description(
43406
+ "Capture a surface as a PNG, as a participant sees it\n\nOpens the console path with ?bare in headless Chromium and captures it once the\nsurface reports its first paint. Uses the running dev server, or starts one for\nthe capture and stops it after. Needs Playwright in the package's own\ndependencies and its Chromium installed.\n\nExamples:\n $ seriousgaming-sdk screenshot /team/1/player/1 --width 390 --height 844 --out plan.png\n $ seriousgaming-sdk screenshot / --scheme dark --full-page --json"
43407
+ ).option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option("--width <PIXELS>", "viewport width", "1280").option("--height <PIXELS>", "viewport height", "800").option("--scheme <SCHEME>", "colour scheme: light, dark or system").option("--brand <ID>", "brand to show, from those the dev server offers").option(
43408
+ "--locale <CODE>",
43409
+ "session locale for the capture; a running server's is switched back after"
43410
+ ).option("--full-page", "capture the surface's whole height, not just the viewport").option(
43411
+ "--out <FILE>",
43412
+ "PNG to write (default: .seriousgaming-sdk/screenshots/<path>-<width>x<height>.png)"
43413
+ ).option("--timeout <SECONDS>", "how long to wait for the surface to render", "30").action((path3, options) => screenshotCommand(path3, options));
42683
43414
  program.command("timer [action] [seconds]").description(
42684
43415
  "Pause, resume or extend the automatic tick timer, or report it when no\naction is given. `extend <seconds>` moves the scheduled tick only, and a\nnegative value brings it forward"
42685
43416
  ).option(WORKING_DIR[0], WORKING_DIR[1], cwd()).option(