@seriousgaming/sdk-tools 1.0.0-alpha.2 → 1.0.0-alpha.3
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.
- package/dist/docs/changelog.md +4 -1
- package/dist/docs/cli-reference.md +10 -0
- package/dist/docs/guides/testing.md +2 -2
- package/dist/docs/guides/upgrading.md +4 -1
- package/dist/templates/package/vitest.config.ts.liquid +18 -2
- package/dist/templates/starter-game/vitest.config.ts +18 -2
- package/package.json +3 -3
package/dist/docs/changelog.md
CHANGED
|
@@ -177,11 +177,14 @@ are in the [0.x changelog](changelog-0.x.md).
|
|
|
177
177
|
- **The scaffold's `playwright.config.ts` sets `forbidOnly` on CI**, so a stray `test.only` fails the run rather than skipping every other test. Merge it from `playwright.config.ts.liquid`
|
|
178
178
|
- **The runtime specification settles readings implementers had to choose**: an endpoint's effects take their own `meta.now`; how a cohort tick states the boards it decided on is the runtime's choice; work outside play state may follow an endpoint's effects; a session UI's unchanged capability is compared deeply after the merge; a clamped tick-controller result is reported to operators at every evaluation; and settings the host enforces use the values frozen at play start
|
|
179
179
|
- **The conformance suite reports more of a production host fairly.** Checks that call an endpoint from outside the game require the new `external-callers` driver capability and checks that hold a session at setup require `setup-state`, so a host without either reports them unsupported. REQ-014 and REQ-020 check the outcome rather than a message or the host page's own traffic, each built fixture variant has its own package identifier, a new check holds a participant's `getPastState` to its own surface's rights whatever surface it claims, and the moved-participant check waits for the remount instead of racing it
|
|
180
|
+
- **Two more conformance driver capabilities are test affordances.** `scenario-selection` (moving a running session onto another scenario, which a production host never does since a session's scenario is fixed) and `override-inspection` (reading the stored session-override layer) are documented, like `held-tick` and `ordered-submission`, as capabilities a production host may report unsupported. `RuntimeDriver.selectScenario` is optional, as `sessionOverrides` and `holdTicks` are
|
|
181
|
+
- **The scaffold's unit tests run logic in Node and components in jsdom.** `vitest.config.ts.liquid` declares two Vitest projects: `*.test.ts` in plain Node and `*.test.tsx` in jsdom on the `vmThreads` pool, which can halve unit-test time on a game with many logic tests. A `.ts` test that renders, `renderHook` included, moves to `.tsx`. See [step 12](guides/upgrading.md#step-12-refresh-the-scaffolds-furniture)
|
|
182
|
+
- **The conformance suite's self-navigation checks run under a production content security policy.** The probe frame navigated itself to a `data:` URL, which a host page's `frame-src` refuses, so both checks failed against a host with a real policy. It now navigates to a path on the host page's own origin that the suite answers in the browser. The runtime specification now says a host's `frame-src` on the page embedding a game confines a bundle's self-navigation, and that a host should send one listing every origin it serves bundles from
|
|
180
183
|
- **Three doc pages have new names**: `guides/game-configuration.md` is [`guides/settings.md`](guides/settings.md), `guides/examples.md` is [`guides/patterns.md`](guides/patterns.md), and `recipes/share-logic-between-module-and-ui.md` is [`recipes/share-logic-between-engine-and-ui.md`](recipes/share-logic-between-engine-and-ui.md). The docs no longer point at example packages you cannot see, the publishing and LLM guides say an account needs access Business Simulations grants (as the 403 messages from `package publish` and `generateText` now do, and the scaffold's `workflow-publish-package.md`), and `llms.txt` and `llms-full.txt` on the docs site link by absolute URL
|
|
181
184
|
|
|
182
185
|
- **`complete` counts the tick limit.** On an endpoint's `session`, its team statuses and the state projection `sdk view` prints, a team is `complete` once it can tick no more: its tick controller or engine ended it, or it has played `maxTicks`. The session is `complete` once every team is. A game that ends by its limit used to read `complete: false` after its last round. Undoing that round clears it again; a `getPastState` entry's `complete` still reports only a controller or engine ending the game
|
|
183
186
|
- **The SDK's `react` and `react-dom` peers are optional.** Only `@seriousgaming/sdk/ui` needs them, so a project that imports the SDK without React, such as a runtime running the conformance suite, no longer gets peer warnings
|
|
184
|
-
- **The conformance suite reaches every endpoint check through a surface.**
|
|
187
|
+
- **The conformance suite reaches every endpoint check through a surface.** Ten checks called with no surface, a caller only an authoring host offers; they now call from the participant or session UI, so a host with no outside route runs them. The two that check an endpoint's `readAsset` and `generateText` call internal endpoints from a session UI added to the `logic-callbacks` fixture. A runtime may treat a resource's `rootDirectory` as empty when the archive holds no directory there, which an asset-less scenario packed by npm or a zip tool does not
|
|
185
188
|
|
|
186
189
|
### Removed
|
|
187
190
|
|
|
@@ -2118,6 +2118,16 @@ pnpm dlx @seriousgaming/sdk-tools new package
|
|
|
2118
2118
|
|
|
2119
2119
|
Scaffolds the package structure and `seriousgaming.sdk.json`. It runs interactively by default, and also accepts a JSON definition as an argument, via `--file`, or on stdin. The `pnpm run sdk` script exists only once a package has been scaffolded, so this first command goes through `pnpm dlx`.
|
|
2120
2120
|
|
|
2121
|
+
The definition is three strings, at the top level rather than under `definition` as every other resource's is: the package `identifier`, the `name` the game takes in its first locale, and the `version` that `package.json` carries. All three are required.
|
|
2122
|
+
|
|
2123
|
+
```bash
|
|
2124
|
+
pnpm dlx @seriousgaming/sdk-tools new package '{
|
|
2125
|
+
"identifier": "com.example.bakery",
|
|
2126
|
+
"name": "Bakery",
|
|
2127
|
+
"version": "0.1.0"
|
|
2128
|
+
}'
|
|
2129
|
+
```
|
|
2130
|
+
|
|
2121
2131
|
What it writes is a complete, playable game, not an empty shell: an engine, a game UI, a session UI, a waiting room UI, a validator, a `participantJoin` hook, a facilitator guide, five capabilities, four settings resources, two scenarios, and tests at every level. It is the game the SDK's own test suites play, copied out verbatim apart from the game's name. See [A tour of the starter game](./guides/starter-game.md) for what it is and why.
|
|
2122
2132
|
|
|
2123
2133
|
`--empty` writes the package files and the agent guidance (`CLAUDE.md`, `.claude/`) alone: no game resources or tests.
|
|
@@ -196,8 +196,8 @@ User interfaces are React components. The SDK scaffold sets up [Vitest](https://
|
|
|
196
196
|
|
|
197
197
|
A package is one game, so it has one of each of these at its root:
|
|
198
198
|
|
|
199
|
-
- `vitest.config.ts`: Vitest config with `jsdom`
|
|
200
|
-
- `test-setup.ts`: imports `@testing-library/jest-dom` matchers and sets up cleanup
|
|
199
|
+
- `vitest.config.ts`: Vitest config with two projects. `*.test.tsx` files run in `jsdom`, and `*.test.ts` files (engine, hook and validator logic) run in plain Node, with no DOM to build. A test that renders anything, `renderHook` included, is a `.tsx`
|
|
200
|
+
- `test-setup.ts`: imports `@testing-library/jest-dom` matchers and sets up cleanup, for the `jsdom` project
|
|
201
201
|
|
|
202
202
|
Each UI's tests sit beside its component: the game UI's are at `ui/src/App.test.tsx`.
|
|
203
203
|
|
|
@@ -246,7 +246,9 @@ Rename `configuration-user-interface.sdk.json` to the slot's bundle file, keep `
|
|
|
246
246
|
|
|
247
247
|
`renderSettingsEditor`'s `settings` is keyed by settings identifier, like everything else in step 2, and its `configures` defaults to the keys of `settings`. A UI that was wired into both surfaces has tests that render it for both: split them with the code.
|
|
248
248
|
|
|
249
|
-
The configuration step exists exactly when a game has `setup`. `callbacks.requestPlay` is always present there, and the host refuses it from the scenario editor.
|
|
249
|
+
The configuration step exists exactly when a game has `setup`. `callbacks.requestPlay` is always present there, and the host refuses it from the scenario editor.
|
|
250
|
+
|
|
251
|
+
A host opens the scenario editor only for a game that turns custom scenarios on, so a `scenario-builder` moved into `scenario_editor/` is unreachable until `seriousgaming.sdk.json` sets `"customScenarios": { "supported": true }`. The build warns with `SCENARIO_EDITOR_UNREACHABLE` when it does not. If the game never set it under 0.6, the builder was probably never reachable either: turn custom scenarios on if facilitators should author their own, or delete the slot. A game with custom scenarios should also set `"scenarioFormat": 1` (see [Scenario format: when to bump it](./scenarios.md#scenario-format-when-to-bump-it)).
|
|
250
252
|
|
|
251
253
|
## Step 4: return what logic writes under `capabilities`
|
|
252
254
|
|
|
@@ -590,6 +592,7 @@ Optional, but each item fixes a trap. A package created by `sdk new package` at
|
|
|
590
592
|
- **Playwright no longer hangs on teardown.** Copy `global-setup.ts.template` to `testing/e2e/global-setup.ts` and replace `playwright.config.ts`. The setup starts an isolated dev server with `startDevServer()` and sets `SERIOUSGAMING_DEV_URL`, which the `@seriousgaming/sdk/e2e` helpers read, so drop `{ port }` from their calls
|
|
591
593
|
- **A shared package can use the SDK's UI hooks.** Add `@seriousgaming/sdk` and `@seriousgaming/deck` to `resolve.dedupe` in `vite.config.ts` and `vitest.config.ts`, beside React and Emotion
|
|
592
594
|
- **The agent's pre-approved commands match its guidance.** Replace `.claude/settings.json`: it allows only read and check commands, never `dev`, `publish` or `pnpm add`
|
|
595
|
+
- **Unit tests stop building a DOM they do not use.** Replace `vitest.config.ts`: it runs `*.test.ts` in plain Node and `*.test.tsx` in jsdom on the `vmThreads` pool. Rename any `.ts` test that renders, `renderHook` included, to `.tsx`
|
|
593
596
|
- **Lint fails on a warning.** Set the `lint` script to `oxlint --max-warnings=0`
|
|
594
597
|
- **The wrappers set `lang` and `dir`.** Delete the lines in each `main.tsx` that set them on the document
|
|
595
598
|
- **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
|
|
@@ -17,9 +17,25 @@ export default defineConfig({
|
|
|
17
17
|
jsx: 'automatic',
|
|
18
18
|
},
|
|
19
19
|
test: {
|
|
20
|
-
environment: 'jsdom',
|
|
21
|
-
setupFiles: ['./test-setup.ts'],
|
|
22
20
|
// Exclude engine tests (node env, separate config) and Playwright specs
|
|
23
21
|
exclude: ['testing/**', '**/node_modules/**'],
|
|
22
|
+
// Logic tests need no DOM, and building one per file is most of what
|
|
23
|
+
// they cost. A test that renders, `renderHook` included, is a .tsx.
|
|
24
|
+
projects: [
|
|
25
|
+
{
|
|
26
|
+
extends: true,
|
|
27
|
+
test: { name: 'logic', include: ['**/*.test.ts'], environment: 'node' },
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
extends: true,
|
|
31
|
+
test: {
|
|
32
|
+
name: 'components',
|
|
33
|
+
include: ['**/*.test.tsx'],
|
|
34
|
+
environment: 'jsdom',
|
|
35
|
+
pool: 'vmThreads',
|
|
36
|
+
setupFiles: ['./test-setup.ts'],
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
],
|
|
24
40
|
},
|
|
25
41
|
});
|
|
@@ -7,9 +7,25 @@ export default defineConfig({
|
|
|
7
7
|
dedupe: ['react', 'react-dom'],
|
|
8
8
|
},
|
|
9
9
|
test: {
|
|
10
|
-
environment: 'jsdom',
|
|
11
|
-
setupFiles: ['./test-setup.ts'],
|
|
12
10
|
// Exclude engine tests (node env, separate config) and Playwright specs
|
|
13
11
|
exclude: ['testing/**', '**/node_modules/**'],
|
|
12
|
+
// Logic tests need no DOM, and building one per file is most of what
|
|
13
|
+
// they cost. A test that renders, `renderHook` included, is a .tsx.
|
|
14
|
+
projects: [
|
|
15
|
+
{
|
|
16
|
+
extends: true,
|
|
17
|
+
test: { name: 'logic', include: ['**/*.test.ts'], environment: 'node' },
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
extends: true,
|
|
21
|
+
test: {
|
|
22
|
+
name: 'components',
|
|
23
|
+
include: ['**/*.test.tsx'],
|
|
24
|
+
environment: 'jsdom',
|
|
25
|
+
pool: 'vmThreads',
|
|
26
|
+
setupFiles: ['./test-setup.ts'],
|
|
27
|
+
},
|
|
28
|
+
},
|
|
29
|
+
],
|
|
14
30
|
},
|
|
15
31
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seriousgaming/sdk-tools",
|
|
3
|
-
"version": "1.0.0-alpha.
|
|
3
|
+
"version": "1.0.0-alpha.3",
|
|
4
4
|
"description": "SDK tooling for building Serious Gaming games",
|
|
5
5
|
"homepage": "https://sdk.seriousgaming.com/",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"@mui/icons-material": "^9.4.0",
|
|
69
69
|
"@mui/material": "^9.4.0",
|
|
70
70
|
"@playwright/test": "^1.64.0",
|
|
71
|
-
"@seriousgaming/sdk": "1.0.0-alpha.
|
|
71
|
+
"@seriousgaming/sdk": "1.0.0-alpha.3",
|
|
72
72
|
"@testing-library/jest-dom": "^7.0.1",
|
|
73
73
|
"@testing-library/react": "^16.3.3",
|
|
74
74
|
"@types/adm-zip": "^0.5.8",
|
|
@@ -98,7 +98,7 @@
|
|
|
98
98
|
"vitest": "^5.0.3"
|
|
99
99
|
},
|
|
100
100
|
"peerDependencies": {
|
|
101
|
-
"@seriousgaming/sdk": "^1.0.0-alpha.
|
|
101
|
+
"@seriousgaming/sdk": "^1.0.0-alpha.3"
|
|
102
102
|
},
|
|
103
103
|
"engines": {
|
|
104
104
|
"node": ">=24"
|