@seriousgaming/sdk-tools 1.6.0 → 1.7.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 (135) hide show
  1. package/dist/agent/guidance.md +350 -0
  2. package/dist/{cli-I355WTAF.js → cli-2DQJACAH.js} +20 -12
  3. package/dist/{cli-PTT5RGKO.js → cli-3PIJLSRQ.js} +5 -5
  4. package/dist/{cli-O6PWMJTZ.js → cli-4CHKF4DQ.js} +1 -1
  5. package/dist/{cli-UJ4UCL2Z.js → cli-4VZIJYKU.js} +1 -1
  6. package/dist/{cli-O5KP4OVN.js → cli-4XCQUM3E.js} +2 -2
  7. package/dist/{cli-6WXLXJVX.js → cli-57C72YKJ.js} +14 -14
  8. package/dist/{cli-GFBGYFYD.js → cli-57V4ARER.js} +1 -1
  9. package/dist/{cli-IRZ5KB7D.js → cli-5G7TZHD3.js} +14 -14
  10. package/dist/{cli-QEVDDBNO.js → cli-64AA7367.js} +8 -8
  11. package/dist/{cli-LMDJCHHD.js → cli-6HB6HTC6.js} +47 -47
  12. package/dist/{cli-TCY5LJ7E.js → cli-6ZSMW4HR.js} +10 -10
  13. package/dist/{cli-RN6IWTL2.js → cli-7MBLH4M3.js} +14 -14
  14. package/dist/{cli-K2B6WHKA.js → cli-7RYIEKMB.js} +10 -10
  15. package/dist/{cli-ZVSFYDPQ.js → cli-7TOLC62D.js} +16 -14
  16. package/dist/{cli-LXYPE3L5.js → cli-ATI6OLJU.js} +12 -12
  17. package/dist/{cli-ROT3DRKU.js → cli-BOXXMDSX.js} +16 -18
  18. package/dist/{cli-UKQYZYFK.js → cli-C3OERMIR.js} +1 -1
  19. package/dist/{cli-VCKOC2EV.js → cli-C6G65H6S.js} +2 -2
  20. package/dist/{cli-ORIG557O.js → cli-CV4JGVJR.js} +17 -27
  21. package/dist/{cli-HYY64SUD.js → cli-CXCL7VRK.js} +13 -13
  22. package/dist/{cli-FBTRTIZJ.js → cli-DEBCP7UH.js} +10 -10
  23. package/dist/{cli-BPYMTOUL.js → cli-DHOWZCXT.js} +10 -10
  24. package/dist/{cli-E6DJIMYD.js → cli-EDCAH2TC.js} +17 -23
  25. package/dist/{cli-C6TH5S7K.js → cli-EJVAQCMQ.js} +30 -3
  26. package/dist/{cli-DZW3XD5F.js → cli-ESA6YNPF.js} +17 -25
  27. package/dist/{cli-UTJU4IYG.js → cli-FP32D3T6.js} +10 -10
  28. package/dist/{cli-EVFS55WN.js → cli-FXWWYBYU.js} +22 -25
  29. package/dist/{cli-MBNMPVDC.js → cli-FXY3DKPW.js} +8 -5
  30. package/dist/{cli-G6UE5NL4.js → cli-FZ7QAZZP.js} +11 -11
  31. package/dist/{cli-KL3756X6.js → cli-G5DQGZ2E.js} +17 -19
  32. package/dist/{cli-JFU22EJ2.js → cli-GEQUJF4L.js} +11 -11
  33. package/dist/{cli-WAE26SVW.js → cli-GHLILDH7.js} +9 -9
  34. package/dist/{cli-PFFCNGHI.js → cli-GPAN6XK2.js} +3 -3
  35. package/dist/{cli-LFGRFIEO.js → cli-GTWEGYSU.js} +12 -12
  36. package/dist/{cli-4BV45LBH.js → cli-H3J3ICCQ.js} +2 -2
  37. package/dist/{cli-3E3MD5U4.js → cli-HHPMAV4F.js} +1 -1
  38. package/dist/{cli-M6BCQRID.js → cli-HM7CD4VU.js} +18 -29
  39. package/dist/{cli-DMW2OQIJ.js → cli-HYEU3QS6.js} +1 -1
  40. package/dist/{cli-TPU4TUR6.js → cli-IPP5FDCH.js} +12 -12
  41. package/dist/{cli-UELGBQG7.js → cli-JGFJWZFU.js} +1 -1
  42. package/dist/{cli-2GOFEW26.js → cli-JIZTQVL2.js} +8 -8
  43. package/dist/{cli-GXD36NF2.js → cli-JPAXKLVT.js} +8 -8
  44. package/dist/{cli-YVVXUD2G.js → cli-JR5AZLLK.js} +7 -2
  45. package/dist/{cli-PQBXVLEU.js → cli-JRIIAZ33.js} +8 -8
  46. package/dist/{cli-3HE4AVZG.js → cli-JRMHSMYT.js} +17 -21
  47. package/dist/{cli-SIPDUBFL.js → cli-L5IG7MY2.js} +14 -14
  48. package/dist/{cli-FYINNRML.js → cli-LE5ICDAF.js} +27 -70
  49. package/dist/{cli-LFM7GJHI.js → cli-LQ4VSM5R.js} +0 -0
  50. package/dist/{cli-RA673NGF.js → cli-LQERHJFE.js} +4 -4
  51. package/dist/{cli-ZWPYIXNI.js → cli-LRQDF3ZO.js} +7 -7
  52. package/dist/{cli-V4GHRWOV.js → cli-M7WEAIRF.js} +5 -5
  53. package/dist/{cli-GUXKQMJ7.js → cli-MM3A4SPH.js} +1 -1
  54. package/dist/{cli-5JEGTVTG.js → cli-MULKSLA4.js} +12 -12
  55. package/dist/{cli-B4TN6PJP.js → cli-MYJGGLC5.js} +2 -2
  56. package/dist/{cli-7OGYADZ3.js → cli-NEOLMC2P.js} +12 -12
  57. package/dist/{cli-IDKYF5XB.js → cli-NOQBWJQN.js} +1 -1
  58. package/dist/{cli-TLLA6KAP.js → cli-NPPY557S.js} +10 -10
  59. package/dist/{cli-GTSGLN3Z.js → cli-OANH3BTQ.js} +1 -1
  60. package/dist/{cli-UMFFURZ7.js → cli-OQG3Y4RU.js} +10 -10
  61. package/dist/{cli-6RRVEGFB.js → cli-PIO7NWMH.js} +10 -10
  62. package/dist/{cli-GDQ6ILJY.js → cli-PKQNOGBO.js} +7 -7
  63. package/dist/{cli-DL2CVMRF.js → cli-PVA52RC2.js} +11 -11
  64. package/dist/{cli-JZM7XTNV.js → cli-R7RG2VMW.js} +10 -10
  65. package/dist/{cli-ZISJ36MM.js → cli-SOFCTQAL.js} +10 -10
  66. package/dist/{cli-6AMT3BUO.js → cli-SOMIB4B4.js} +12 -12
  67. package/dist/{cli-E33CJRRQ.js → cli-SPGUVL6Z.js} +14 -14
  68. package/dist/{cli-4AKVLEC4.js → cli-SWZY7L7K.js} +3 -3
  69. package/dist/{cli-C3NVCKO6.js → cli-SX3ULO5P.js} +8 -8
  70. package/dist/{cli-S5QDONIQ.js → cli-T4HWGMY4.js} +7 -7
  71. package/dist/{cli-272KBNJH.js → cli-TDYKRXUA.js} +12 -12
  72. package/dist/{cli-UNJ5X6BU.js → cli-TFMNNVJ7.js} +10 -10
  73. package/dist/{cli-PNLYX6R6.js → cli-TFZ53OA2.js} +12 -12
  74. package/dist/{cli-KNOOKGYW.js → cli-TJ3PLRHF.js} +10 -10
  75. package/dist/{cli-JMZLT65J.js → cli-TPNQLYPC.js} +1 -1
  76. package/dist/{cli-QEVE5HUM.js → cli-UBQCSUDH.js} +11 -11
  77. package/dist/{cli-E2NLWIFE.js → cli-UTM4QU67.js} +1 -1
  78. package/dist/{cli-U2UE7I7J.js → cli-UY4VDI7W.js} +8 -8
  79. package/dist/{cli-XCO2VQOH.js → cli-VPON5HGB.js} +19 -17
  80. package/dist/{cli-Q2XJF5AS.js → cli-VYR326C6.js} +18 -21
  81. package/dist/{cli-G522CPRL.js → cli-WAZD75KE.js} +10 -10
  82. package/dist/{cli-R4PCG5YX.js → cli-WG36UJRK.js} +12 -12
  83. package/dist/{cli-GBFM76BF.js → cli-WM6SQJ6Q.js} +5 -5
  84. package/dist/{cli-G6KELFSX.js → cli-X7E3637I.js} +84 -17
  85. package/dist/{cli-AK7OIPWY.js → cli-XR2XSWQN.js} +13 -17
  86. package/dist/{cli-GGPDQNM3.js → cli-XTANOFQR.js} +2 -2
  87. package/dist/{cli-BYJWFFCF.js → cli-YSPZZQCP.js} +2 -2
  88. package/dist/{cli-EEFJKIGL.js → cli-Z5HWENER.js} +17 -25
  89. package/dist/{cli-57RXC3HQ.js → cli-ZBTFLZUL.js} +14 -14
  90. package/dist/{cli-SMFSZF2G.js → cli-ZF7IFB54.js} +21 -4
  91. package/dist/{cli-VCI3CG36.js → cli-ZKG3OPZ6.js} +9 -9
  92. package/dist/{cli-WOGIAU2E.js → cli-ZQ2Y3U7F.js} +7 -7
  93. package/dist/{cli-QUIJCBYB.js → cli-ZRPWZOCW.js} +15 -7
  94. package/dist/{cli-UHSZBKYO.js → cli-ZTZ5H55T.js} +12 -12
  95. package/dist/cli.js +36 -34
  96. package/dist/client.js +178 -69
  97. package/dist/core/game-settings.d.ts +5 -3
  98. package/dist/core/session-roster.d.ts +10 -0
  99. package/dist/dev/console/assets/{index-CuMOOH9m.js → index-CnXlPeLX.js} +47 -47
  100. package/dist/dev/console/index.html +1 -1
  101. package/dist/dev/routes.d.ts +5 -2
  102. package/dist/dev/shell.d.ts +9 -1
  103. package/dist/dev/view/batch.d.ts +11 -1
  104. package/dist/dev/view/route.d.ts +18 -1
  105. package/dist/dev/view/view.d.ts +9 -0
  106. package/dist/docs/ai-agents.md +1 -1
  107. package/dist/docs/api/index.md +1 -1
  108. package/dist/docs/api/sdk-commands.md +4 -0
  109. package/dist/docs/api/sdk-e2e.md +5 -0
  110. package/dist/docs/api/sdk-tools-client.md +4 -0
  111. package/dist/docs/api/sdk-ui-testing.md +1 -0
  112. package/dist/docs/api/sdk-ui.md +28 -0
  113. package/dist/docs/api/sdk.md +2 -0
  114. package/dist/docs/changelog.md +26 -0
  115. package/dist/docs/cli-and-dev-server.md +4 -0
  116. package/dist/docs/cli-reference.md +17 -2
  117. package/dist/docs/getting-started.md +1 -1
  118. package/dist/docs/guides/presentation.md +11 -10
  119. package/dist/docs/guides/session-hooks.md +16 -0
  120. package/dist/docs/guides/settings.md +4 -2
  121. package/dist/docs/guides/starter-game.md +1 -1
  122. package/dist/docs/guides/upgrading.md +31 -2
  123. package/dist/docs/page-index.md +6 -6
  124. package/dist/host/protocol.d.ts +10 -1
  125. package/dist/host.js +1 -0
  126. package/dist/playwright.js +178 -69
  127. package/dist/runtime/manifest-version.d.ts +1 -1
  128. package/dist/runtime.js +1 -1
  129. package/dist/schema.json +10 -1
  130. package/dist/templates/package/CLAUDE.md.template +7 -346
  131. package/dist/templates/package/claude/rules/workflow-create-engine.md +2 -2
  132. package/dist/templates/package/claude/rules/workflow-create-guide.md +2 -2
  133. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  134. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +3 -3
  135. package/package.json +3 -3
@@ -5,7 +5,7 @@
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
6
  <link rel="icon" type="image/svg+xml" href="/assets/icon-CRaj5uhr.svg" />
7
7
  <title>Serious Gaming</title>
8
- <script type="module" crossorigin src="/assets/index-CuMOOH9m.js"></script>
8
+ <script type="module" crossorigin src="/assets/index-CnXlPeLX.js"></script>
9
9
  <link rel="stylesheet" crossorigin href="/assets/index-q6-lvlN3.css">
10
10
  </head>
11
11
  <body>
@@ -30,8 +30,11 @@ export interface RouteDeps {
30
30
  settleWalkthroughReset: (command: Command) => Promise<MutationResult>;
31
31
  packagePath: string;
32
32
  vitePort: () => number;
33
- /** The origin bundles are served from, as seen by a client that reached `host`. */
34
- assetOrigin: (host: string | undefined) => string;
33
+ /**
34
+ * The origin bundles are served from, as seen by a client that reached
35
+ * `host`; `local` for one that asked for this server's own origins.
36
+ */
37
+ assetOrigin: (host: string | undefined, local: boolean) => string;
35
38
  /** This server, as its lock names it, so a reused port is not taken for it. */
36
39
  instanceId: string;
37
40
  /** What the server could not apply live to a run, for the CLI to say (#640). */
@@ -202,8 +202,11 @@ export declare class DevShell {
202
202
  * public one where given, else the same host on the asset port. A browser
203
203
  * on another machine reached us by an address `localhost` would not
204
204
  * resolve to on its side.
205
+ *
206
+ * `local` skips the public one, for a client that has said it runs here
207
+ * (`?local-origins`): it may not reach the proxy in front of us at all.
205
208
  */
206
- assetOrigin(host: string | undefined): string;
209
+ assetOrigin(host: string | undefined, local?: boolean): string;
207
210
  /** The console's own origin, as a client that reached `host` names it. */
208
211
  private consoleOrigin;
209
212
  /** Where a frame's hot-reload client connects, when a public origin decides it. */
@@ -306,6 +309,11 @@ export declare class DevShell {
306
309
  * somebody else, another surface, or a command its surface may not send.
307
310
  */
308
311
  private receiveView;
312
+ /**
313
+ * Join from the session link's page (§13.4): the session places the
314
+ * newcomer, and the page is sent on to the participant it made.
315
+ */
316
+ private joinThroughSessionLink;
309
317
  private broadcast;
310
318
  /**
311
319
  * Say what went wrong where the author is actually looking.
@@ -13,7 +13,7 @@
13
13
  */
14
14
  import type { HostOverlay, ResolvedPackageManifest } from '@seriousgaming/sdk';
15
15
  import type { StateProjection } from '@seriousgaming/sdk/projection';
16
- import type { CrossTeamData, SessionData, TeamConfiguration, TeamLinks, WalkthroughLink } from '@seriousgaming/sdk/ui';
16
+ import type { CrossTeamData, SessionData, TeamConfiguration, TeamLinks, SessionJoinLink, WalkthroughLink } from '@seriousgaming/sdk/ui';
17
17
  import type { ViewerRole } from '../../core/protocol';
18
18
  import type { HostMessage } from '../../host';
19
19
  import type { MountableSurface } from '../surfaces';
@@ -170,6 +170,16 @@ export declare const PRESENTATION_OVERLAY = "presentation-overlay";
170
170
  * is no `fallbackJoinUrl`: one origin, one form of the link.
171
171
  */
172
172
  export declare function teamLinks(state: StateProjection, origin: string): TeamLinks[];
173
+ /**
174
+ * The session's one join link (§13.4), or `null` where it offers none: a game
175
+ * whose `teams.sessionJoin` is false, and a walkthrough, which holds one
176
+ * participant and so has nobody to place.
177
+ *
178
+ * Like a team's, it is a route that resolves, and with no PIN and no account
179
+ * here, no `fallbackJoinUrl` either. Which team it places somebody in is this
180
+ * host's own rule (see `SessionRoster.joinSession`), not the specification's.
181
+ */
182
+ export declare function sessionJoinLink(state: StateProjection, origin: string): SessionJoinLink | null;
173
183
  /** The mode and the **effective** bounds a surface gates its controls on (§5.4). */
174
184
  export declare function teamConfiguration(state: StateProjection): TeamConfiguration;
175
185
  /**
@@ -16,6 +16,12 @@ import type { RunKind } from '@seriousgaming/sdk';
16
16
  * facilitator hands out, and it asks which participant you are — or, when the
17
17
  * team holds one, simply opens as them.
18
18
  *
19
+ * `/join` is the session's one join link (§13.4): it names no team, and
20
+ * pressing Join places you in one and creates your participant there, then
21
+ * sends you to that participant's own addressable page. Reloading that page
22
+ * keeps you; opening `/join` again is somebody new, which is how an author
23
+ * plays out a room arriving.
24
+ *
19
25
  * `/walkthrough` names the walkthrough run's play surface (§5.7). It takes no
20
26
  * team or participant because a walkthrough holds one of each, so there is
21
27
  * nothing to choose: it is the view you put on the projector while you talk the
@@ -24,7 +30,7 @@ import type { RunKind } from '@seriousgaming/sdk';
24
30
  * `/presentation` is the facilitator's deck (§6.15), and `?preview` shows it as
25
31
  * it looks with no session: in a library, or exported before the day.
26
32
  */
27
- export type RouteKind = 'console' | 'player' | 'observer' | 'join' | 'waiting-room' | 'setup' | 'scenario-editor' | 'guide' | 'print' | 'presentation';
33
+ export type RouteKind = 'console' | 'player' | 'observer' | 'join' | 'session-join' | 'waiting-room' | 'setup' | 'scenario-editor' | 'guide' | 'print' | 'presentation';
28
34
  export interface Route {
29
35
  kind: RouteKind;
30
36
  /**
@@ -50,6 +56,17 @@ export interface Route {
50
56
  /** Show a presentation as if there were no session (§6.15). */
51
57
  preview?: boolean;
52
58
  }
59
+ /**
60
+ * The flag `sdk screenshot` sets on the page it opens. It runs on the
61
+ * server's own machine, which may not reach the public origins a proxy put in
62
+ * front, and the server cannot tell it apart from a proxied browser by its
63
+ * `Host` (a sandbox rewrites every one to `localhost`), so it says so.
64
+ */
65
+ export declare const LOCAL_ORIGINS_FLAG = "local-origins";
66
+ /** Whether a query asks for the server's own origins rather than its public ones. */
67
+ export declare function wantsLocalOrigins(search: string): boolean;
68
+ /** `path` with the flag carried over from a page's query, so its requests ask as it did. */
69
+ export declare function forwardLocalOrigins(path: string, pageSearch: string): string;
53
70
  export declare function parseRoute(pathname: string, search: string): Route;
54
71
  /** The URL for a route, so the console links rather than constructs by hand. */
55
72
  export declare function routeHref(route: Omit<Route, 'bare' | 'run'> & {
@@ -47,6 +47,15 @@ export type ViewPage = {
47
47
  } | {
48
48
  status: 'join';
49
49
  team: JoinTeam | null;
50
+ }
51
+ /**
52
+ * The session link's page (§13.4). `offered` is false where the session
53
+ * has none to follow: a game whose `teams.sessionJoin` is false, or a
54
+ * walkthrough.
55
+ */
56
+ | {
57
+ status: 'session-join';
58
+ offered: boolean;
50
59
  } | {
51
60
  status: 'redirect';
52
61
  href: string;
@@ -34,7 +34,7 @@ mkdir my-game && cd my-game
34
34
  pnpm dlx @seriousgaming/sdk-tools new package '{"identifier":"com.example.mygame","name":"My Game","version":"0.1.0"}'
35
35
  ```
36
36
 
37
- You get the starter game, a complete lemonade stand, with tests at every level, a `CLAUDE.md`, and `.claude/rules/`. Read `CLAUDE.md` before changing anything: it holds the rules that are expensive to get wrong. Pass `--empty` for the package files and the agent guidance alone.
37
+ You get the starter game, a complete lemonade stand, with tests at every level, a `CLAUDE.md`, and `.claude/rules/`. Read `CLAUDE.md` before changing anything. Its first line imports the SDK's guidance, the rules that are expensive to get wrong, from `node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md`, so it describes the installed version; the rest of the file is the package's own, for what this game is. Pass `--empty` for the package files and the agent guidance alone.
38
38
 
39
39
  Without a terminal, the CLI never prompts: a command that would ask fails with `PROMPT_REQUIRED` and exit code 2. Every `new` and `update` takes its definition as an argument, with `--file`, or on stdin, and `delete` takes `--yes`.
40
40
 
@@ -7,7 +7,7 @@ Every type, function, hook and component your game imports, one page per entry p
7
7
  | Entry point | Exports |
8
8
  | ------------------------------------------------------------------ | -------------------------------------------------------------- |
9
9
  | [`@seriousgaming/sdk`](./sdk.md) | 12 functions, 3 classes, 1 constant, 100 interfaces, 48 types |
10
- | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 49 functions, 3 classes, 39 constants, 26 interfaces, 37 types |
10
+ | [`@seriousgaming/sdk/ui`](./sdk-ui.md) | 50 functions, 3 classes, 40 constants, 26 interfaces, 38 types |
11
11
  | [`@seriousgaming/sdk/ui/testing`](./sdk-ui-testing.md) | 14 functions, 6 types |
12
12
  | [`@seriousgaming/sdk/testing`](./sdk-testing.md) | 8 functions, 4 constants, 8 types |
13
13
  | [`@seriousgaming/sdk/projection`](./sdk-projection.md) | 1 constant, 8 interfaces, 3 types |
@@ -152,6 +152,10 @@ type MutationCommand =
152
152
  teamId: string;
153
153
  name?: string;
154
154
  }
155
+ | {
156
+ type: 'joinSession';
157
+ name?: string;
158
+ }
155
159
  | {
156
160
  type: 'renameParticipant';
157
161
  participantId: string;
@@ -115,6 +115,7 @@ const DEV_SERVER: {
115
115
  readonly observeUrl: (team: number) => string;
116
116
  readonly waitingRoomUrl: (team: number) => string;
117
117
  readonly joinUrl: (team: number) => string;
118
+ readonly sessionJoinUrl: () => string;
118
119
  readonly setupUrl: () => string;
119
120
  readonly scenarioEditorUrl: (scenario: string) => string;
120
121
  readonly guideUrl: () => string;
@@ -292,6 +293,10 @@ type MutationCommand =
292
293
  teamId: string;
293
294
  name?: string;
294
295
  }
296
+ | {
297
+ type: 'joinSession';
298
+ name?: string;
299
+ }
295
300
  | {
296
301
  type: 'renameParticipant';
297
302
  participantId: string;
@@ -419,6 +419,10 @@ type MutationCommand =
419
419
  teamId: string;
420
420
  name?: string;
421
421
  }
422
+ | {
423
+ type: 'joinSession';
424
+ name?: string;
425
+ }
422
426
  | {
423
427
  type: 'renameParticipant';
424
428
  participantId: string;
@@ -168,6 +168,7 @@ type RenderSessionUserInterfaceOptions<
168
168
  teamLinks?: TeamLinks[];
169
169
  runKind?: RunKind;
170
170
  walkthroughLink?: WalkthroughLink | null;
171
+ sessionJoinLink?: SessionJoinLink | null;
171
172
  hostOverlays?: HostOverlay[];
172
173
  hookFailures?: SessionHookFailure[];
173
174
  clearHookFailures?: () => void;
@@ -203,6 +203,14 @@ Hook to access all participants across all teams in the session.
203
203
  const useSessionUserInterfaceParticipants: () => Participant[];
204
204
  ```
205
205
 
206
+ ### useSessionUserInterfaceSessionJoinLink
207
+
208
+ Hook returning the session's one join link, or `null` when there is none to show.
209
+
210
+ ```ts
211
+ const useSessionUserInterfaceSessionJoinLink: () => SessionJoinLink | null;
212
+ ```
213
+
206
214
  ### useSessionUserInterfaceTeamConfiguration
207
215
 
208
216
  Hook to access the session's interaction mode and team bounds.
@@ -541,6 +549,14 @@ The React context behind `useSessionUserInterfaceParticipants`.
541
549
  const SessionUserInterfaceParticipantsContext: import('react').Context<Participant[] | undefined>;
542
550
  ```
543
551
 
552
+ ### SessionUserInterfaceSessionJoinLinkContext
553
+
554
+ The React context behind `useSessionUserInterfaceSessionJoinLink`.
555
+
556
+ ```ts
557
+ const SessionUserInterfaceSessionJoinLinkContext: import('react').Context<SessionJoinLink | null>;
558
+ ```
559
+
544
560
  ### SessionUserInterfaceTeamConfigurationContext
545
561
 
546
562
  The React context behind `useSessionUserInterfaceTeamConfiguration`.
@@ -976,6 +992,7 @@ interface PresentationSession<
976
992
  participants?: Participant[];
977
993
  joinLinks?: PresentationJoinLink[];
978
994
  joinPin?: string | null;
995
+ sessionJoinLink?: SessionJoinLink | null;
979
996
  }
980
997
  ```
981
998
 
@@ -1327,6 +1344,17 @@ type SessionData<
1327
1344
  };
1328
1345
  ```
1329
1346
 
1347
+ ### SessionJoinLink
1348
+
1349
+ One join link for the whole session: somebody who follows it is placed in a team by the host, rather than choosing one.
1350
+
1351
+ ```ts
1352
+ type SessionJoinLink = {
1353
+ joinUrl: string;
1354
+ fallbackJoinUrl?: string;
1355
+ };
1356
+ ```
1357
+
1330
1358
  ### SessionMeta
1331
1359
 
1332
1360
  The session's identity and lifecycle state, pushed on connect and again whenever any of it changes.
@@ -508,6 +508,7 @@ interface GameSettings {
508
508
  name: string;
509
509
  };
510
510
  }[];
511
+ sessionJoin?: boolean;
511
512
  };
512
513
  waitingRoom?: {
513
514
  openOnStart?: boolean;
@@ -530,6 +531,7 @@ interface GameSettingsConstraints {
530
531
  maxParticipants?: GameSettingConstraint;
531
532
  };
532
533
  defaultNames?: GameSettingConstraint;
534
+ sessionJoin?: GameSettingConstraint;
533
535
  };
534
536
  waitingRoom?: {
535
537
  openOnStart?: GameSettingConstraint;
@@ -31,6 +31,32 @@ are in the [0.x changelog](changelog-0.x.md).
31
31
 
32
32
  ## [Unreleased]
33
33
 
34
+ ## [1.7.0] — 2026-11-05
35
+
36
+ ### Added
37
+
38
+ - **One join link for the whole session.** A session UI reads it with `useSessionUserInterfaceSessionJoinLink()`, and a presentation as `session.sessionJoinLink`, so a facilitator can put a single QR code in front of a room and let the host put each person in a team. It is `null` where the host has none. Someone joining through it is an ordinary participant with an ordinary `participantJoin`, but no host promises which team they land in, so never depend on it. The dev server offers it at `/join`, placing each arrival in the team with the fewest participants, and lists it in the dev drawer as 'Session join link'. `pnpm run sdk participant join` does the same from the command line, and `renderSessionUserInterface` takes a `sessionJoinLink` option for tests. See [useSessionUserInterfaceSessionJoinLink](guides/session-hooks.md#usesessionuserinterfacesessionjoinlink)
39
+ - **`teams.sessionJoin` turns the session link off.** A new game setting, `true` by default, which a game sets in `seriousgaming.sdk.json` or a scenario sets under `settings.game`; setup cannot. A game whose teams are not interchangeable, such as one that gives each team a role, should set it to `false` and rebuild. A test that builds the `game` settings by hand, rather than from the generated `defaultSettings`, adds `sessionJoin` to `teams`. See [The game settings](guides/settings.md#the-game-settings)
40
+
41
+ ### Fixed
42
+
43
+ - **`sdk screenshot` works against a dev server given public origins this machine cannot reach.** With `--public-url`, `--public-asset-url` or `--public-hmr-url` set, it used to load the game's frames from those public origins, so a sandbox that cannot reach its own proxy (a hosted builder's, say) failed with `SURFACE_NOT_RENDERED`. It now asks the server for its local ports (`?local-origins` on the page it opens) and loads everything from them, and leaves the frame's hot-reload socket unconnected, as a capture never needs it. Everyone else is still handed the public origins, and the flagged responses are sent `Cache-Control: no-store`, so a proxy or CDN in front never keeps one
44
+
45
+ ## [1.6.1] — 2026-11-02
46
+
47
+ ### Changed
48
+
49
+ - **A new package's agent guidance no longer describes the starter game as the package.** The SDK's guidance (`guidance.md`, below; until now `CLAUDE.md.template`) replaces its 'This package' section with four patterns worth keeping in any game (keyed state, a validator on shared state, awaited writes, and a deliberate team mode), citing the starter as one worked example, and its command examples use placeholders such as `/<capability>/<variable>` in place of the starter's paths. The `workflow-create-engine.md`, `workflow-create-user-interface.md` and `workflow-create-guide.md` rules read the same way for a package that has since been reskinned. Merge the rules into an existing package's `.claude/rules/`, and import the guidance as below, so an agent stops being told a reskinned game is a lemonade stand
50
+ - **A package's `CLAUDE.md` imports the SDK's agent guidance instead of copying it.** The guidance ships in `@seriousgaming/sdk-tools` at `dist/agent/guidance.md`, so it always matches the installed version and updates when you upgrade. A new package's `CLAUDE.md` (`CLAUDE.md.template`) starts with `@node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md`, then a sentence naming that path for a tool that does not follow imports, then a section of its own for describing the game. `workflow-update-sdk-version.md` says the same. An existing package can replace its copied SDK text with the import, keeping what it wrote about the game; see [Import the SDK's agent guidance](guides/upgrading.md#optional-import-the-sdks-agent-guidance-in-claudemd)
51
+
52
+ ### Fixed
53
+
54
+ - **`new <type>` keeps every field you write.** It used to drop some fields from the written bundle without an error: an endpoint's `actions` and `roster`, a capability's `lifetime`, `endpoints` and `crossTeamParticipants` on the participant interface, `endpoints` on the session interface, `crossTeamParticipants` on the waiting room, and `settings` on the guide. A generated field the build derives from the code, a validator's `gates` or an endpoint's `responds`, is now refused rather than dropped. Interactive `update engine` also keeps the engine's `uses`. On an earlier version, add a dropped field after creating the resource with `pnpm run sdk update <type> <id> --patch '[...]'`
55
+
56
+ ### Security
57
+
58
+ - **The `body-parser` advisory is cleared.** The SDK's lockfile now takes `body-parser` 2.4.0 through `express` in the dev server, as 1.5.0 said the next release would. A game's own install already resolves it
59
+
34
60
  ## [1.6.0] — 2026-11-02
35
61
 
36
62
  ### Added
@@ -112,6 +112,10 @@ changes.
112
112
  The server still listens on the ports it prints, so point the gateway at those:
113
113
  the console's port, the asset port, and the Vite port for hot reload.
114
114
 
115
+ `sdk screenshot` runs on the server's own machine, which may not reach the
116
+ public origins at all, so it asks for the local ports instead and loads
117
+ everything from them. No other page is affected.
118
+
115
119
  ### Colour scheme and brand
116
120
 
117
121
  The console keeps its colour scheme and brand in its own browser storage,
@@ -1598,6 +1598,17 @@ Add a participant to a team.
1598
1598
  | `--team [NUMBER]` | | Team to add them to (1-based, defaults to 1). |
1599
1599
  | `--no-server` | | Run in this process instead of starting a dev server. |
1600
1600
 
1601
+ ```text
1602
+ pnpm run sdk participant join [name] [options]
1603
+ ```
1604
+
1605
+ Join through the session link, letting the session choose the team.
1606
+
1607
+ | Option | Default | Description |
1608
+ | -------------------------- | --------------------- | ----------------------------------------------------- |
1609
+ | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1610
+ | `--no-server` | | Run in this process instead of starting a dev server. |
1611
+
1601
1612
  ```text
1602
1613
  pnpm run sdk participant rename <participantId> <name> [options]
1603
1614
  ```
@@ -1620,7 +1631,11 @@ Move a participant to another team (1-based).
1620
1631
  | `-w, --working-dir [PATH]` | the current directory | The working directory to execute in. |
1621
1632
  | `--no-server` | | Run in this process instead of starting a dev server. |
1622
1633
 
1623
- `participant add` defaults to team 1 when `--team` is omitted.
1634
+ `participant add` defaults to team 1 when `--team` is omitted. `participant join` is what following the session's one join link does: the dev server places the newcomer in the team with the fewest participants, the lowest numbered on a tie, and refuses when the game sets `teams.sessionJoin` to `false`. Another host may place people differently, so a game must not depend on where they land.
1635
+
1636
+ ```bash
1637
+ pnpm run sdk participant join Ada
1638
+ ```
1624
1639
 
1625
1640
  ### Waiting room, scenario, and locale
1626
1641
 
@@ -2127,7 +2142,7 @@ Capture a surface as a PNG, as a participant sees it.
2127
2142
  pnpm run sdk screenshot /team/1/player/1 --width 390 --height 844 --scheme dark --out plan.png --json
2128
2143
  ```
2129
2144
 
2130
- The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
2145
+ The path is any surface's URL path, such as `/team/1/player/1` or `/` for the session surface; `?bare` is added for you, and so is `?local-origins`, which loads everything from the server's local ports even when it was given public origins this machine cannot reach. The capture waits for the surface to report its first paint, so it shows the screen as drawn rather than its loading state. With `--json` the data names the image (`path`), the `url` it opened, and the page's `consoleErrors`, `failedRequests` and `uncaughtExceptions`, those inside the surface's frame included.
2131
2146
 
2132
2147
  It drives the game's own Playwright (`@playwright/test`, which every scaffolded game has), and fails with `BROWSER_MISSING` (exit 5) without it or its Chromium. A surface that does not connect, or does not report its first paint within `--timeout`, fails with `SURFACE_NOT_RENDERED` (exit 4), carrying the same three lists in `error.details`.
2133
2148
 
@@ -146,7 +146,7 @@ pnpm test:engine
146
146
 
147
147
  ## Working with an AI coding agent
148
148
 
149
- A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for coding agents. They cover the workflows an agent needs (creating resources, testing, publishing) and tell the agent to leave `sdk dev` for you to start. The points worth knowing:
149
+ A scaffolded package includes a `CLAUDE.md` and `.claude/rules/` written for coding agents. `CLAUDE.md` imports the SDK's guidance from the installed `@seriousgaming/sdk-tools`, so it stays current as you upgrade, and leaves the rest of the file for you to describe your game. They cover the workflows an agent needs (creating resources, testing, publishing) and tell the agent to leave `sdk dev` for you to start. The points worth knowing:
150
150
 
151
151
  - Session commands print JSON, so an agent can read state with `view` and make decisions with `tick --patch`
152
152
  - Use `pnpm run --silent` when parsing output, so pnpm's banner stays out of the JSON
@@ -53,15 +53,15 @@ const { game, session, settings, theme, locale, getPastState, getAssetUrl } = us
53
53
  >();
54
54
  ```
55
55
 
56
- | Field | What it holds |
57
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
58
- | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
- | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
60
- | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
- | `theme` | The host's theme, to map onto the deck's colours |
62
- | `locale` | The locale to render in |
63
- | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
- | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
56
+ | Field | What it holds |
57
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `game` | `name` in the current locale, `maxTicks` (or `null` when the engine or tick controller decides), `mode`, and `scenarioName` (or `null`). Present with or without a session |
59
+ | `session` | `null` with no session. Otherwise its `id`, `name`, `completedTicks` (the most rounds any team has completed, 0 before the first), `data` (the shared store and every team, narrowed to `reads`), `teams`, and how the room joins: `participants`, `joinLinks`, `sessionJoinLink` and `joinPin` (see [Showing the room how to join](#showing-the-room-how-to-join)) |
60
+ | `settings` | The settings resources the presentation declares, resolved for the scenario, and for the session when there is one |
61
+ | `theme` | The host's theme, to map onto the deck's colours |
62
+ | `locale` | The locale to render in |
63
+ | `getPastState` | Reads past rounds, as the session UI does, with `teams` defaulting to every team. Rejects when there is no session |
64
+ | `getAssetUrl` | Turns an `asset:`, `shared:` or `blob:` reference into a URL |
65
65
 
66
66
  A presentation sees every team: it is the facilitator's view of the room.
67
67
 
@@ -90,10 +90,11 @@ export function useResults(): Results {
90
90
  The first slides are often on the projector while the room arrives, so a session carries what a join slide needs:
91
91
 
92
92
  - **`joinLinks`**: one entry per team, in index order, each `{ teamId, joinUrl, fallbackJoinUrl? }`. Encode `joinUrl` in a QR code; offer `fallbackJoinUrl` only on request. There is no observe URL: watching a team is the facilitator's tool, not the room's
93
+ - **`sessionJoinLink`**: one link for the whole room, `{ joinUrl, fallbackJoinUrl? }`, or `null` when the host has none or the game turns it off. The host puts whoever follows it in a team, and no host promises which, so show it as one code for everyone and keep the team links for anyone who needs a particular team
93
94
  - **`joinPin`**: the code to enter alongside the link, or `null` when joining needs none. Show it beside the link, never inside it
94
95
  - **`participants`**: every team's participants, `connected` or not, for a count of who has arrived
95
96
 
96
- All three are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
97
+ All four are optional in the type. A host that predates them leaves them out, so render a placeholder there, as you would with no session.
97
98
 
98
99
  ### Varying by scenario
99
100
 
@@ -76,6 +76,21 @@ const teamLinks = useSessionUserInterfaceTeamLinks();
76
76
 
77
77
  Encode `joinUrl` in a QR code: the host chose that form because a denser code is harder to scan across a room. Show `fallbackJoinUrl` on request rather than beside it, for the networks that block URL shorteners. `observeUrl` opens the team's game UI as an observer, with no participant identity and no presence.
78
78
 
79
+ ## useSessionUserInterfaceSessionJoinLink
80
+
81
+ Get the session's one join link, for a single QR code the whole room scans:
82
+
83
+ ```typescript
84
+ import { useSessionUserInterfaceSessionJoinLink } from '@seriousgaming/sdk/ui';
85
+
86
+ const sessionLink = useSessionUserInterfaceSessionJoinLink();
87
+ // SessionJoinLink | null: { joinUrl, fallbackJoinUrl? }
88
+ ```
89
+
90
+ Somebody who follows it is placed in a team by the host, rather than choosing one, and joins as an ordinary participant. That is what a room of many small teams needs: one code on the projector instead of one per team. Encode `joinUrl` and offer `fallbackJoinUrl` on request, as with the team links.
91
+
92
+ It is `null` until the host sends it, on a host with no session link, and for a game that turns it off, so fall back to the team links whenever it is. Never depend on which team somebody lands in: hosts choose differently, and none promises an order or a balance. If it matters, move people afterwards with `moveParticipant`, or turn the link off with `teams.sessionJoin` (see [The game settings](./settings.md#the-game-settings)).
93
+
79
94
  ## useSessionUserInterfaceHostOverlays
80
95
 
81
96
  Find out which host overlays this host offers, before rendering a control for one:
@@ -201,5 +216,6 @@ Additional messages sent after initialisation:
201
216
  | -------------------- | -------------------------------------------------------------------------------------------------------- |
202
217
  | `setTeamList` | Updates the list of teams in the session (`TeamInfo[]`, each `{ teamId, index, name }`, sorted by index) |
203
218
  | `setTeamLinks` | Updates each team's facilitator-only join and observe URLs |
219
+ | `setSessionJoinLink` | Updates the session's one join link, or `null` when there is none |
204
220
  | `setParticipantList` | Updates the participant roster across all teams |
205
221
  | `hookFailed` | Reports a hook chain that threw |
@@ -293,7 +293,7 @@ Keep a value in a capability only when it changes during play, or when it is com
293
293
 
294
294
  ## The game settings
295
295
 
296
- Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
296
+ Every game has one built-in settings resource, `game`, holding the game-level settings: how many ticks (rounds) it plays, how many teams a session may hold, how many participants a team is meant for, what the teams are called to begin with, whether one link may join the whole session, and whether the waiting room opens with the session. It is a settings resource like any other, with two differences: the SDK owns its schema, and the game sets its values in `seriousgaming.sdk.json` rather than in `settings/game/`.
297
297
 
298
298
  | Setting | The game's value, in `seriousgaming.sdk.json` | What it does |
299
299
  | --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
@@ -301,6 +301,7 @@ Every game has one built-in settings resource, `game`, holding the game-level se
301
301
  | `teams.min`, `teams.max` | `teams.min` and `teams.max`, or `null` for no bound | The fewest teams play can start with, and the most a session can hold |
302
302
  | `teams.perTeam.minParticipants`, `.maxParticipants` | `teams.perTeam`, or `null` | Guidance on team size shown to the facilitator, never a limit on joining |
303
303
  | `teams.defaultNames` | `teams.defaultNames`, or `[]` | The names teams start with, by team index. A facilitator or the team can rename |
304
+ | `teams.sessionJoin` | `teams.sessionJoin`, or `true` | Whether the host may offer one join link for the whole session |
304
305
  | `waitingRoom.openOnStart` | `waitingRoom.openOnStart`, or `false` | Whether a new session starts with participants held in the waiting room |
305
306
 
306
307
  `teams.mode` stays in the manifest and is not a setting: a game is independent or shared-state, and nothing can change that.
@@ -312,9 +313,10 @@ Override the game settings as you would any other, under `game`:
312
313
  - **`sdk configure`** sets them on the dev server: `pnpm run sdk configure '{"game":{"maxTicks":6}}'`
313
314
  - **Any resource can read them** by listing `game` in its `settings`, and its generated `types.ts` types them
314
315
 
315
- Two rules are particular to these settings:
316
+ Three rules are particular to these settings:
316
317
 
317
318
  - **`waitingRoom.openOnStart` is set by the game or a scenario, never by setup.** It takes effect as the session is created, before setup runs, so a setup value would do nothing, and is refused
319
+ - **`teams.sessionJoin` is set by the game or a scenario, never by setup.** It is read as the session is created, because people can follow the session link before play starts, so a setup value is refused. Set it to `false` when your teams are not interchangeable, such as one role per team or teams set up by index: the host places whoever follows the session link in a team of its own choosing, so a game like that hands out team links instead (see [useSessionUserInterfaceSessionJoinLink](./session-hooks.md#usesessionuserinterfacesessionjoinlink))
318
320
  - **Play cannot start outside the team bounds.** Setup can change `teams.min` and `teams.max` after the teams were created, so play is refused while the team count is outside them. Add or remove teams, or change the setting, and start again
319
321
 
320
322
  A settings resource of your own may not be called `game`, and is refused with a message saying what to change.
@@ -199,7 +199,7 @@ These are written by `new package` for every package, starter game or not:
199
199
  | `pnpm-workspace.yaml` | Dependency overrides and install-script decisions the SDK tooling needs |
200
200
  | `.oxlintrc.json`, `.oxfmtrc.json` | Lint and format settings |
201
201
  | `README.md`, `DESIGN.md` | A readme, and prompts for writing down your game's design as you build it |
202
- | `CLAUDE.md`, `.claude/` | Guidance and permissions for an AI coding agent working in the package |
202
+ | `CLAUDE.md`, `.claude/` | Guidance and permissions for an AI coding agent. `CLAUDE.md` imports the SDK's guidance, then leaves a section to describe your game |
203
203
  | `.gitignore` | Keeps `dist/`, `node_modules/`, `.seriousgaming-sdk/`, and Playwright's `test-results/` and `playwright-report/` out of version control |
204
204
 
205
205
  Two directories appear once you use the package. `dist/` is what `sdk build` writes. `.seriousgaming-sdk/` holds the dev server's lock file (`session.json`) and the session overrides `sdk configure` writes (`configuration.json`); the session itself lives only in the dev server's memory.
@@ -634,7 +634,7 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
634
634
  - **Playwright's output stays out of git.** Merge `gitignore.template` into `.gitignore`: it ignores `test-results/` and `playwright-report/`
635
635
  - **A stray `test.only` fails CI.** `playwright.config.ts.liquid` sets `forbidOnly` when `CI` is set, so one focused test no longer skips every other test. Merge it into `playwright.config.ts` if you did not replace that file above
636
636
  - **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
637
- - **A shorter `CLAUDE.md` and refreshed rules.** Merge in the new `CLAUDE.md.template` and `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
637
+ - **A current `CLAUDE.md` and refreshed rules.** Replace the SDK's text in `CLAUDE.md` with the import described in [Optional: import the SDK's agent guidance](#optional-import-the-sdks-agent-guidance-in-claudemd), and merge in the new `claude/rules/` if you have not customised them heavily, as `workflow-update-sdk-version.md` describes
638
638
  - **Refreshed dependencies.** Merge the versions in `package.json.liquid`, and after the Playwright bump run `pnpm exec playwright install chromium --only-shell` (drop `--only-shell` if you run tests with `--headed` or `--ui`)
639
639
 
640
640
  Nothing breaks if you skip the new features 1.0 adds, but several replace workarounds games carry: the engine's private `state` and `complete: true` (see [Engine](./engine.md#keeping-memory-between-ticks) and [Game completion](./tick-controller.md#game-completion)), capabilities with `"lifetime": "session"` that undo and reset leave alone ([Lifetime](./capabilities.md#lifetime)), a facilitator's slide deck in the `presentation/` slot ([Building presentations](./presentation.md)), endpoints that act on the session or take files ([Endpoints](./endpoints.md)), and the `useAsset`, `usePastState` and `useViewerStorage` hooks ([User interfaces](./ui.md)).
@@ -667,7 +667,7 @@ pnpm run test:e2e
667
667
 
668
668
  ## After 1.0
669
669
 
670
- A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md).
670
+ A minor release that changes a public type a test may build by hand lists it here as well as in the [changelog](../changelog.md), and so does an optional step that keeps an older package's scaffold current.
671
671
 
672
672
  ### 1.2: give `Brand.icon` a variant for each background
673
673
 
@@ -684,6 +684,35 @@ renderUserInterface(<App />, { callbacks: { requestTick } });
684
684
 
685
685
  These types are outside semantic versioning from 1.3, so the helpers are the way to keep up with later additions too. See [What a minor release may change](./testing.md#what-a-minor-release-may-change).
686
686
 
687
+ ### 1.7: turn off the session join link where teams are not interchangeable
688
+
689
+ A host may now offer one join link for the whole session and put each person who follows it in a team of its choosing. A game that gives each team a role, or sets teams up by index, should not offer it. Set it off in `seriousgaming.sdk.json` and rebuild:
690
+
691
+ ```json
692
+ {
693
+ "teams": { "mode": "independent", "sessionJoin": false }
694
+ }
695
+ ```
696
+
697
+ A game whose teams are interchangeable needs nothing. A test that builds the `game` settings by hand, rather than spreading the generated `defaultSettings`, adds `sessionJoin` to `teams`.
698
+
699
+ ### Optional: import the SDK's agent guidance in `CLAUDE.md`
700
+
701
+ A new package's `CLAUDE.md` no longer holds a copy of the SDK's guidance. Its first line imports the copy that ships with `@seriousgaming/sdk-tools`, so the guidance always matches the installed version, and the rest of the file is the package's own. An older package keeps the copy it was scaffolded with, which goes stale with every upgrade and, in a package that began as the starter game, describes the lemonade stand after a reskin.
702
+
703
+ Nothing breaks if you skip this. To adopt it:
704
+
705
+ 1. Replace the SDK's text in `CLAUDE.md` (everything copied from the old template) with the first three lines of `node_modules/@seriousgaming/sdk-tools/dist/templates/package/CLAUDE.md.template`. The first is the import:
706
+
707
+ ```
708
+ @node_modules/@seriousgaming/sdk-tools/dist/agent/guidance.md
709
+ ```
710
+
711
+ 2. Keep anything you wrote about the game itself below them, under a heading of its own
712
+ 3. Leave `.claude/rules/` as it is: the rules are still copied into the package and merged by hand, as `workflow-update-sdk-version.md` describes
713
+
714
+ There is no command that refreshes the file: from here on, upgrading the SDK updates the guidance.
715
+
687
716
  ## Before you publish
688
717
 
689
718
  A 1.0 build is a manifest version 3 package, and the platform must accept version 3 before you publish one. Until it does, the platform refuses the upload, and a version 2 package you published from 0.6 keeps running as it is. Check with Business Simulations that the platform you publish to accepts version 3 packages, and keep publishing from 0.6 until it does.
@@ -21,12 +21,12 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
21
21
  ## Start here and reference
22
22
 
23
23
  - [`index.md`](index.md), about 6k characters: The Serious Gaming SDK is for building serious games: facilitated learning experiences, such as business simulations and experiential learning, in which teams make decisions and see the consequences.
24
- - [`ai-agents.md`](ai-agents.md), about 5k characters: An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer.
24
+ - [`ai-agents.md`](ai-agents.md), about 6k characters: An AI coding agent can build, check, and play a serious game with this SDK from the terminal alone, with no browser and no prompt to answer.
25
25
  - [`changelog-0.x.md`](changelog-0.x.md): Every release before 1.0, from 0.0.1 to 0.6.0, kept as history.
26
26
  - [`changelog.md`](changelog.md): All notable changes to the Serious Gaming SDK are recorded here.
27
27
  - [`cli-and-dev-server.md`](cli-and-dev-server.md), about 15k characters: The dev server runs your game on your own machine, with every screen in the browser, and the CLI plays and inspects the same session from the terminal.
28
28
  - [`cli-error-codes.md`](cli-error-codes.md), about 31k characters: Every code a failed `seriousgaming-sdk` command can report.
29
- - [`cli-reference.md`](cli-reference.md), about 161k characters: Every `seriousgaming-sdk` command and flag, in one place.
29
+ - [`cli-reference.md`](cli-reference.md), about 162k characters: Every `seriousgaming-sdk` command and flag, in one place.
30
30
  - [`cli-simulation-testing.md`](cli-simulation-testing.md), about 11k characters: Play a game from the terminal: configure it, start a session, make decisions, advance ticks, and read the state back as JSON.
31
31
  - [`environment-variables.md`](environment-variables.md), about 10k characters: A single reference for every environment variable the dev server and CLI read.
32
32
  - [`getting-started.md`](getting-started.md), about 11k characters: Scaffold the starter game, play it in the dev server, change one thing, and see the change.
@@ -56,12 +56,12 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
56
56
  - [`guides/llm-integration.md`](guides/llm-integration.md), about 26k characters: Use generated text to give teams feedback, play characters, or write round reports that react to what they did.
57
57
  - [`guides/multi-team-games.md`](guides/multi-team-games.md), about 35k characters: Let teams compete for one market, cooperate on a shared goal, or each play their own copy of the game.
58
58
  - [`guides/patterns.md`](guides/patterns.md), about 12k characters: Three patterns for an engine's state and logic, each built up from the CLI commands that create its resources: a stock level that never goes negative, revenue computed in a second step, and a production loop split into one step per concern.
59
- - [`guides/presentation.md`](guides/presentation.md), about 16k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
59
+ - [`guides/presentation.md`](guides/presentation.md), about 17k characters: Ship the facilitator's slide deck as part of the game, live with the session's results and exportable for anyone who wants to edit it.
60
60
  - [`guides/production-constraints.md`](guides/production-constraints.md), about 10k characters: In production your UI bundle runs cross-origin, behind a strict content security policy and a short-lived auth cookie, and talks to the host only through a typed message channel.
61
61
  - [`guides/scenario-editor.md`](guides/scenario-editor.md), about 10k characters: The `scenario_editor` slot holds the screen people use to build new scenarios for a released game, without rebuilding it.
62
62
  - [`guides/scenarios.md`](guides/scenarios.md), about 31k characters: A scenario is a named set of settings overrides and static assets that makes a distinct flavour of a game: a different storyline, difficulty preset, or themed variant.
63
63
  - [`guides/session-game-flow.md`](guides/session-game-flow.md), about 20k characters: How a session UI drives the session: ticks, the timer, host overlays, undo and reset, the waiting room, the language, the roster, and the participant list.
64
- - [`guides/session-hooks.md`](guides/session-hooks.md), about 14k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
64
+ - [`guides/session-hooks.md`](guides/session-hooks.md), about 15k characters: Every hook a session UI reads its data and callbacks from, and the messages the host sends it.
65
65
  - [`guides/session.md`](guides/session.md), about 23k characters: The session UI is the facilitator's view of the whole room: every team's position side by side, with the controls to run the session.
66
66
  - [`guides/settings.md`](guides/settings.md), about 34k characters: Settings are a game's read-only parameters: a price, a difficulty, a round length, a menu, an answer key.
67
67
  - [`guides/setup.md`](guides/setup.md), about 9k characters: The `setup` slot holds the small form a facilitator fills in when they create a session.
@@ -76,7 +76,7 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
76
76
  - [`guides/ui-styling.md`](guides/ui-styling.md), about 11k characters: How a game UI handles language, theme, and screen size, and how to customise the Vite build that serves and bundles it.
77
77
  - [`guides/ui-ticks.md`](guides/ui-ticks.md), about 15k characters: How a game UI ends a round and shows the time left: requesting a tick, awaiting a write or tick and handling a `MutationError`, and driving a countdown from the tick timer.
78
78
  - [`guides/ui.md`](guides/ui.md), about 17k characters: The game UI is what each participant sees and plays: where they read the situation, make decisions, and see what those decisions caused.
79
- - [`guides/upgrading.md`](guides/upgrading.md), about 66k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
79
+ - [`guides/upgrading.md`](guides/upgrading.md), about 68k characters: This guide takes a game package on 0.6 to 1.0, in 13 steps.
80
80
  - [`guides/validators.md`](guides/validators.md), about 23k characters: A validator is a read-only gate on what a participant does: a context write before it is applied, and a request for the next tick before it runs.
81
81
  - [`guides/waiting-room.md`](guides/waiting-room.md), about 14k characters: The waiting room is the holding screen participants see while a session is parked, and you can replace the host's stock panel with your own.
82
82
 
@@ -142,5 +142,5 @@ This index lists pages; `--outline` lists a page's sections, each with its slug
142
142
  - [`api/sdk-tools-client.md`](api/sdk-tools-client.md), about 14k characters: Programmatic API for testing a game in-process.
143
143
  - [`api/sdk-tools-playwright.md`](api/sdk-tools-playwright.md), about 3k characters: Playwright for a game's browser tests: a dev server for each worker.
144
144
  - [`api/sdk-ui-testing.md`](api/sdk-ui-testing.md), about 8k characters: Every export of `@seriousgaming/sdk/ui/testing`, with the declaration it is published with.
145
- - [`api/sdk-ui.md`](api/sdk-ui.md), about 35k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
145
+ - [`api/sdk-ui.md`](api/sdk-ui.md), about 36k characters: Every export of `@seriousgaming/sdk/ui`, with the declaration it is published with.
146
146
  - [`api/sdk.md`](api/sdk.md), about 58k characters: Every export of `@seriousgaming/sdk`, with the declaration it is published with.